Document native library adoption plans
This commit is contained in:
139
docs/roadmap/promptkit.md
Normal file
139
docs/roadmap/promptkit.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# PromptKit Adoption Outline
|
||||
|
||||
**Updated:** 2026-11-07
|
||||
|
||||
**Status:** Initial outline. Follow the [master roadmap](library-adoption.md)
|
||||
for shared adoption principles, dependency identities, and sequencing.
|
||||
|
||||
## Baseline and Target
|
||||
|
||||
Audita currently uses PromptKit v0.14.0. Its
|
||||
[LLM runtime](../internal/llm-runtime.md) uses a shared engine, application-owned
|
||||
backend overrides, curated profile inspection, and prepared execution.
|
||||
|
||||
Adopt PromptKit v0.20.0 through its native configuration and execution APIs.
|
||||
Retain the built-in OpenRouter backend and bundled profiles. They must be usable
|
||||
through the normal selection and credential mechanisms, not merely visible in
|
||||
an inventory while Audita rejects them for lacking a duplicate registration.
|
||||
Expose native resource and configuration inspection through the full standard
|
||||
ckprompt surface described in the [CommandKit outline](commandkit.md).
|
||||
|
||||
PromptKit owns resources, composition, provider settings and credentials,
|
||||
preparation, transport, structural repair, and backend admission. Audita owns
|
||||
proposal/validation role selection, transcript processing, domain decisions,
|
||||
response contracts, and truthful partial-success reporting. Review existing
|
||||
application-only endpoint and credential restrictions against those boundaries.
|
||||
|
||||
Use the pinned [migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/configuration-migration.md),
|
||||
[format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/formats.md),
|
||||
and [v0.20 release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/releases/v0.20.0.md).
|
||||
The bundle is default-on; older migration prose about catalog removal does not
|
||||
mean the current release has no bundled resources. It does not select an implicit
|
||||
execution profile or make provider calls during construction.
|
||||
|
||||
## Agreed Direction and Migration Work
|
||||
|
||||
1. Move to `go.maximumdirect.net/promptkit` together with ConfigKit's new types.
|
||||
Remove the old external catalog dependencies when no longer incorporated;
|
||||
retain PromptKit's built-in catalog rather than disabling it.
|
||||
2. Convert root and collection backends, profiles, and prompts to identified lists
|
||||
with explicit `id` fields. Use sibling `extends: {id: parent}` and complete
|
||||
same-ID replacement records. Typed source builders use ordered slices.
|
||||
Preserve provider settings deliberately: partial same-ID replacements no
|
||||
longer merge fields. Use exact native collection references where collections
|
||||
are selected; mounting does not rewrite stored references.
|
||||
3. Convert the seven embedded prompts and maintained operator examples/fixtures.
|
||||
Remove prompt version selectors and descriptive `PromptVersion` metadata from
|
||||
requests, registries, inspection, and diagnostics. Response-schema versions
|
||||
are separate and need not change. Keep domain instructions and per-call schemas;
|
||||
this adoption is not a prompt-quality rewrite. Shared instruction variables
|
||||
remain available to templates, while native operator overrides control their
|
||||
inclusion. Domain validation remains enforced after model responses.
|
||||
4. Adapt resource inspection to optional profile fields and separate backend
|
||||
inspection. These describe resources, not completed requests. Use real
|
||||
`PrepareExecution` details and `RunPrepared` for execution of the same captured
|
||||
request. Do not duplicate PromptKit's full resolver or construct synthetic
|
||||
requests merely to reproduce the old profile summary. Inspect bundled and
|
||||
unselected partial resources without requiring them to be runnable.
|
||||
5. Adopt native credential precedence, including bundled OpenRouter environment
|
||||
lookup. Migrate any retained application secret references deliberately;
|
||||
do not blanket-clear library credential sources or reject a valid native
|
||||
selection merely because it differs from today's Audita backend map.
|
||||
Preserve secret-safe diagnostics using the library's public boundaries and
|
||||
Audita's domain artifact redaction; evaluate actual gaps with synthetic keys.
|
||||
6. Review presence semantics field by field. Null endpoint, credential-source,
|
||||
and whole provider map now allow backend defaults; explicit empty strings
|
||||
clear endpoint/credential sources. Null does not suppress the entire backend
|
||||
provider map. Sampling fields have distinct semantics. Avoid blanket null or
|
||||
zero conversion and document intentional request changes.
|
||||
7. Update captured-source accounting for list indexes and collection prefixes,
|
||||
including inherited/moved content-file origins. Preserve output-collision
|
||||
protection for consumed host documents and effective message files. Array
|
||||
positions are addresses, not durable resource identities.
|
||||
8. Keep self-contained embedded response schemas. The new schema rule does not
|
||||
require a bundler for Audita's current schemas. Check custom artifact-reader
|
||||
ownership only where such a reader is actually used. Preserve native retries,
|
||||
structural repair, cancellation, deadlines, and shared engine admission while
|
||||
retaining Audita's domain reconciliation and partial-success outcomes.
|
||||
|
||||
Update [configuration](../config.md), [LLM integration](../integrations/openai-compatible-llm.md),
|
||||
[runtime internals](../internal/llm-runtime.md), [prompt guidance](../internal/prompts.md),
|
||||
operator examples, diagnostics metadata documentation, and attribution with the
|
||||
implementation. Standard inspection replaces curated-only disclosure; prompts
|
||||
and provider settings may appear where the library's normal inspection exposes
|
||||
them, with native redaction. Do not accidentally promise old prompt hashes.
|
||||
|
||||
## Acceptance and Upstream Requests
|
||||
|
||||
Verify native bundle inventory and selection, configuration/resource/prepared
|
||||
view distinctions, inheritance and replacement, credential precedence, optional
|
||||
fields, source-relative messages and collisions, and captured configuration.
|
||||
Use controlled providers to verify actual targets, domain schemas, shared
|
||||
admission, retry/repair budgets, cancellation, and partial success. Standard
|
||||
inspection must work without model calls; library presence alone does not prove
|
||||
successful Audita integration.
|
||||
|
||||
No upstream request is yet selected. PromptKit is mature but pre-v1: significant
|
||||
blockers or awkward public boundaries can justify focused requests. Submit the
|
||||
minimal reproducer, desired outcome, and domain justification before building
|
||||
substantial local machinery. A review probe demonstrated distinct base/derived
|
||||
backend records preserving provider fields; that is an available native technique,
|
||||
not a decision to retain Audita's old backend ownership model.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
### Backend, Credential, and Admission Ownership
|
||||
|
||||
**Recommendation:** make native PromptKit resources the authoritative backend
|
||||
configuration and remove duplicate application registration/endpoint enforcement
|
||||
unless a concrete processing requirement needs it. Keep Audita role selections
|
||||
and operation budgets, and use native backend capacity settings for workloads.
|
||||
This makes bundled profiles usable and avoids losing operator fields through a
|
||||
highest-priority application replacement. Plan the existing backend/secret file
|
||||
migration with the ConfigKit outline.
|
||||
|
||||
The current architecture policy requires finite shared admission. Determine
|
||||
whether that remains a domain requirement and how native configuration satisfies
|
||||
it for bundled and custom selections. Do not silently reject the bundle, impose
|
||||
an arbitrary cap, or weaken the policy during implementation. Any selected
|
||||
exception needs a documented reason and an explicit policy update.
|
||||
|
||||
**Alternative:** retain a narrow application capacity or credential policy and
|
||||
express it through native derived backends/profiles. The probe shows this can
|
||||
preserve provider fields while supplying application-owned fields. It is viable
|
||||
if operational requirements demand it, but introduces naming/reference conventions
|
||||
and can recreate duplicate ownership. Prefer an upstream facility if a justified
|
||||
policy cannot be applied cleanly without replacing whole resources or resolver
|
||||
logic. Blanket preservation of today's restrictions is not the selected default.
|
||||
|
||||
### Existing Curated Profile Summary
|
||||
|
||||
**Recommendation:** use standard resource inspection and prepared-request preview
|
||||
for their distinct meanings; retire the old completed-profile summary unless a
|
||||
specific Audita role summary remains useful. This avoids a parallel target resolver
|
||||
and aligns operator expectations.
|
||||
|
||||
**Alternative:** retain a small role-to-resource summary alongside the full native
|
||||
commands. It helps transcript operators identify proposal and validation choices,
|
||||
but must clearly describe resource values rather than implying completed request
|
||||
settings. It adds maintenance and must not constrain native inspection.
|
||||
Reference in New Issue
Block a user