238 lines
14 KiB
Markdown
238 lines
14 KiB
Markdown
# PromptKit v0.12.0 Adoption Roadmap
|
|
|
|
**Last updated:** 2026-10-03
|
|
|
|
**Status:** Accepted target scope; ready for implementation planning. The
|
|
operator-directory scope decision has been resolved. Implementation has not
|
|
begun.
|
|
|
|
## Purpose and Baseline
|
|
|
|
Adopt PromptKit v0.12.0 now that the independent
|
|
[ConfigKit v0.5.0 upgrade](configkit.md) is complete. Align Audita with the
|
|
libraries' native configuration model while retaining Audita's domain rules,
|
|
application-owned backend settings, and resilient processing workflow.
|
|
|
|
At reviewed Audita revision `8cba751835ba9faad340e933a3cfbb59c03924fd`,
|
|
[go.mod](../../go.mod) selects ConfigKit v0.5.0 and PromptKit v0.11.2, with
|
|
OpenRouter and Rakestrawhome `/v2` catalogs at `v2.20260926.0`. Go 1.25.5
|
|
remains the application minimum. The implemented contracts belong to
|
|
[configuration](../config.md), the
|
|
[LLM integration](../integrations/openai-compatible-llm.md), and the
|
|
[LLM runtime](../internal/llm-runtime.md).
|
|
|
|
`internal/framework/llm.NewRuntime` currently assembles one engine using the
|
|
old prompt/profile filesystem options and programmatic backend registration.
|
|
Audita embeds seven prompt definitions and separate response schemas. Operators
|
|
select proposal and validation profiles from `profiles_dir`; the effective
|
|
backend must be registered in application configuration, its endpoint must
|
|
match, and its credential comes from Audita's ConfigKit-resolved settings.
|
|
Successful profile reads are recorded to protect those sources from output
|
|
collisions. Both roles share the same engine's backend admission controls.
|
|
|
|
The reviewed upstream release is
|
|
[PromptKit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/releases/v0.12.0.md),
|
|
commit `4b8169da286917fde7875425bb32b799b12c6af3`. It depends on ConfigKit
|
|
v0.5.0 and both maintained `/v3` catalog modules at `v3.20260930.0`. This is an
|
|
intentional incompatible pre-1.0 minor release: it replaces construction and
|
|
configuration APIs, rather than simply updating provider data. PromptKit's
|
|
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
|
|
and [consumer migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md#migrate-from-the-previous-configuration-api)
|
|
own the upstream details.
|
|
|
|
## Target End State
|
|
|
|
- Audita imports released PromptKit v0.12.0 and its `/v3` catalogs, retaining
|
|
ConfigKit v0.5.0 and using no local dependency replacement.
|
|
- The runtime uses `Config.Sources` and native ConfigKit source groups.
|
|
PromptKit owns composition, inheritance, presence, final-definition
|
|
validation, prompt capture, and execution. Audita does not translate old
|
|
profiles or implement a second YAML loader or inheritance resolver.
|
|
- Embedded prompts and maintained operator profiles use keyed `prompts` and
|
|
`profiles` mappings. Existing prompt IDs, versions, role selections,
|
|
instructions, and response-schema associations remain the adoption baseline.
|
|
The application configuration schema, overlay selection, CLI interface, and
|
|
main-file-relative `profiles_dir` resolution remain in place.
|
|
- Native profile `extends`, field-presence semantics, and source-relative
|
|
resource rules apply. Documents can contain multiple definitions, and IDs
|
|
come from mapping keys rather than filenames. The existing `profiles_dir`
|
|
accepts native unified PromptKit documents containing profiles, backends,
|
|
and prompts, including intentional operator prompt overrides.
|
|
- Application backend endpoints, configured concurrency and queue capacity,
|
|
and credential ownership remain authoritative for selected roles. Preserve
|
|
the existing profile-selection and prepared-target checks; do not introduce
|
|
a second admission controller or implicit provider credential lookup.
|
|
- A runtime uses one captured configuration snapshot for both roles. Each CLI
|
|
invocation constructs a new engine; hot reload is not part of this feature.
|
|
Existing inspection remains offline and safe, and consumed host sources
|
|
remain protected from output collisions.
|
|
- PromptKit retains responsibility for transport retries, schema repair,
|
|
observation, and prepared execution. Preserve Audita's configured retry and
|
|
repair budgets, operation deadlines, cancellation, partial-success behavior,
|
|
error/recovery reporting, and debug selection.
|
|
|
|
## Configuration Assembly and Ownership
|
|
|
|
Replace removed `WithPromptFS`, `WithProfileFS`, and `WithBackend` usage with
|
|
the released source API. Discover embedded YAML through `FilesystemInputs` and
|
|
operator YAML through `DirectoryInputs`, with explicit caller tiers. Keep the
|
|
retained schema filesystem integration and HTTP client configuration.
|
|
Use the helpers' default-disabled imports; this adoption does not require new
|
|
application source-selection flags or operator underlay tiers.
|
|
|
|
PromptKit supplies catalog definitions first and its own defaults next. Caller
|
|
tiers then overlay in their supplied order, followed by an optional highest
|
|
priority main input. Files within one directory group compose strictly;
|
|
alphabetical filenames do not establish override precedence. Use separate
|
|
tiers for genuine priority differences rather than manufacturing file-order
|
|
semantics.
|
|
|
|
Represent application backend settings as a final programmatic source, using
|
|
`BackendSource` or ConfigKit mappings where explicit null is needed. Preserve
|
|
configured zero queue capacity as an explicit value. Suppress backend-derived
|
|
credential environment lookup explicitly where catalog layering would otherwise
|
|
introduce it; omission alone can retain a lower-tier value. Continue detecting
|
|
competing effective profile credential lookups rather than silently clearing
|
|
operator profile fields. A missing backend credential remains valid for an
|
|
unauthenticated local service unless the selected profile requires a key.
|
|
|
|
Catalog backend IDs are no longer reserved upstream. Audita should not invent a
|
|
new reservation rule. Catalog selection alone must not bypass application
|
|
registration, endpoint, capacity, or credential requirements. Catalog profile
|
|
contents may evolve; this upgrade does not promise fixed model choices or live
|
|
provider availability.
|
|
|
|
The accepted caller order is embedded Audita prompts, operator definitions,
|
|
then application backend settings. The existing `profiles_dir` accepts native
|
|
unified PromptKit documents containing profiles, backends, and prompts. Keep
|
|
the name and path setting for continuity, and document its broader accepted
|
|
content. This follows the upstream source API without a parallel parser or
|
|
top-level filtering. Profiles, provider defaults, and intentional prompt
|
|
overrides use the same native composition model.
|
|
|
|
Audita continues to ship its domain prompts, enforce its selected-backend
|
|
requirements, and supply its per-call schemas. Operator prompt overrides are
|
|
an accepted capability of this adoption; documentation, source accounting,
|
|
and focused behavioral coverage should reflect them.
|
|
|
|
## Work Required
|
|
|
|
### Runtime Construction and Source Accounting
|
|
|
|
Migrate `internal/framework/llm/runtime.go` to layered construction and retain
|
|
the role-bound adapter boundary. Review startup inspection and failure
|
|
classification because upstream now validates all final definitions, including
|
|
unused ones, during engine construction. Distinguish invalid operator inputs
|
|
from broken embedded assets under the existing
|
|
[CLI exit contract](../cli.md); do not treat every construction failure as an
|
|
operator error merely because validation moved earlier.
|
|
|
|
Upstream permits partial profiles and defers endpoint/model completeness until
|
|
request overrides are applied. Preserve Audita's established checks for its
|
|
selected roles without adding a requirement that every unselected profile be
|
|
runnable. Native rejection of invalid unused definitions is different from
|
|
requiring all profiles to be complete.
|
|
|
|
Adapt source accounting to the new discovery/capture boundary. The existing
|
|
recording filesystem wrapper may be replaceable with discovered inputs or
|
|
upstream source metadata. Protect the host sources actually consumed by the
|
|
runtime, including inherited and differently named definitions, without
|
|
guessing filenames from selected profile IDs. Account for consumed operator
|
|
message files as well. Keep this proportionate to the existing collision
|
|
contract; do not add filesystem concurrency or power-loss guarantees.
|
|
|
|
Keep the existing safe effective-profile summaries and application explanations.
|
|
Use upstream metadata where useful, but do not expose the full
|
|
`InspectConfiguration` snapshot as ordinary CLI or report output: prompt text
|
|
and arbitrary provider fields are outside those summaries' current scope.
|
|
|
|
### Prompt Assets, Profiles, and Presence Semantics
|
|
|
|
Move each of the seven files in `internal/prompts/assets/prompts` to the keyed
|
|
prompt/version format. Keep the shared instruction fragments and the complete
|
|
per-call output contracts owned by Audita. This migration does not authorize
|
|
another prompt-quality rewrite or changes to domain validators.
|
|
|
|
Convert the six maintained profiles in `examples/profiles` and test-generated
|
|
profile/prompt fixtures to the new format. Convert any old `base_profile`
|
|
usage to `extends`, and remove embedded identities. Migrate tests that construct
|
|
engines using removed options or old `Profile`/`Backend` values.
|
|
|
|
Review presence deliberately rather than mechanically preserving old serialized
|
|
values. In particular, explicit zero temperature, top-p, or max-tokens now means
|
|
an outbound zero; zero timeout disables PromptKit's generation deadline while
|
|
Audita's outer operation deadline still applies. Omission, blank values, and
|
|
null have field-specific meanings. Empty provider maps do not erase inherited
|
|
entries, and changing model/backend does not erase unrelated explicit settings.
|
|
|
|
Use the native meanings without a compatibility shim. Retaining the examples'
|
|
literal `temperature: 0` as an explicit provider setting is recommended; explain
|
|
that omitting the field requests an unspecified value, and null suppresses an
|
|
inherited control. Do not automatically turn every existing zero into omission
|
|
or every omission into a zero. Demonstrate representative profile inheritance
|
|
without requiring every maintained example to use it.
|
|
|
|
### Documentation, Migration, and Attribution
|
|
|
|
Update the profile section of `docs/config.md` and maintained examples when the
|
|
implementation lands. Explain the broader accepted content of `profiles_dir`,
|
|
operator prompt overrides and their precedence, keyed identities, composition
|
|
versus precedence, profile inheritance, presence, eager final-definition
|
|
validation, selected-root errors, and captured configuration. Link to the pinned
|
|
upstream reference for generic field semantics rather than reproducing its
|
|
entire contract.
|
|
|
|
Include operator migration guidance for old profile documents and behaviorally
|
|
significant zeros/nulls. This is a deliberate format migration, not an automatic
|
|
upgrade of existing installation files. Preserve supported application overlays,
|
|
including the cheaper/faster testing-profile workflow.
|
|
|
|
Update the pinned consumer link in `docs/integrations/openai-compatible-llm.md`,
|
|
construction/source-accounting descriptions in `docs/internal/llm-runtime.md`,
|
|
and asset-format guidance in `docs/internal/prompts.md`. Update other affected
|
|
references only where implemented behavior changes.
|
|
|
|
Update `go.mod`, `go.sum`, and `docs/oss/attribution.md` for PromptKit and the two
|
|
catalog modules. Verify exact selected source revisions and upstream notices
|
|
under the [OSS policy](../policy/oss.md); retain the applicable LGPL/GPL and MIT
|
|
texts rather than duplicating unchanged license documents. Dependency adoption
|
|
does not change Audita's application license.
|
|
|
|
The profile format is publicly documented and incompatible with the old one.
|
|
Assess Audita's release classification under the
|
|
[release policy](../policy/release.md#versioning-and-compatibility); PromptKit's
|
|
own pre-1.0 minor version does not establish that this is an Audita minor update.
|
|
Version selection and publication belong to later release preparation.
|
|
|
|
## Verification and Completion
|
|
|
|
Use existing offline tests as the starting point. Update fixtures intentionally,
|
|
and add focused behavioral coverage where the source migration creates a
|
|
distinct risk. Completion means:
|
|
|
|
- The released dependency set builds and the complete Audita test suite passes.
|
|
- All registered prompts load and render from keyed assets, with the established
|
|
per-call schemas and adapter-supplied shared instructions.
|
|
- Selected roles use final application backend settings and direct resolved
|
|
credentials; both roles still share configured capacity, including explicit
|
|
zero queue capacity. Catalog layering does not introduce a competing lookup.
|
|
- Representative keyed profiles, native inheritance, and explicit presence work
|
|
through the real runtime. Directory conflicts and invalid final definitions
|
|
produce useful startup errors without filename-derived identity assumptions.
|
|
- Operator prompt and backend contributions follow the accepted source order;
|
|
prompt overrides render while Audita retains its per-call schemas and
|
|
authoritative application backend settings.
|
|
- Source collision protection, safe inspection, and operator-versus-asset error
|
|
classification remain effective at the changed construction boundary.
|
|
- Representative prepared execution, schema repair, transient retry, and
|
|
partial-success tests retain their existing behavior. Reuse adequate coverage
|
|
rather than duplicating PromptKit's complete upstream test matrix.
|
|
- Maintained examples and canonical documentation describe the migrated format;
|
|
attribution identifies the selected PromptKit and catalog sources accurately.
|
|
|
|
No live provider calls, new release gates, or CI-success dependency are needed
|
|
to establish adoption. Guided domain recovery and the other work recorded in
|
|
[future.md](future.md) remain separate features. Do not expand this upgrade into
|
|
new report formats, pipeline scheduling, or general configuration-inspection
|
|
commands. A staged implementation plan can now be prepared.
|