140 lines
8.7 KiB
Markdown
140 lines
8.7 KiB
Markdown
# 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.
|