177 lines
11 KiB
Markdown
177 lines
11 KiB
Markdown
# PromptKit v0.23.2 Adoption
|
|
|
|
## Status And Scope
|
|
|
|
Accepted direction; not yet implemented. Upgrade the existing Scriptorium
|
|
product in one native cutover. Use the released PromptKit and ConfigKit APIs
|
|
for framework and configuration mechanisms that they already own. Provide
|
|
migration guidance for configuration, definitions, and CLI usage, not a
|
|
second application schema, a legacy definition reader, or compatibility
|
|
aliases. Refactor the early-beta HTTP API directly, without an HTTP migration
|
|
or backward-compatibility requirement.
|
|
|
|
The [definition boundary](../adr/0004-definition-boundary.md) and
|
|
[configuration boundary](../adr/0005-configkit-boundary.md) remain in effect.
|
|
The existing CLI and HTTP surfaces should be able to use valid definitions for
|
|
the selected PromptKit release without copying its schema or maintaining a
|
|
narrower application-specific subset. This roadmap covers the changes to
|
|
existing surfaces needed for the migration. New CLI capabilities, including
|
|
[Narratio's requirements inspection](narratio-feature-request.md), concrete
|
|
request validation, inventory, backend inspection, configuration diffs, and
|
|
smoke diagnostics, are deferred to a separate roadmap. It does not add HTTP
|
|
operations for those capabilities or introduce continuation, coordination,
|
|
prepared-handle workflows, or prepared-content capture.
|
|
|
|
## Baseline And Target
|
|
|
|
The reviewed Scriptorium baseline is
|
|
`1b1d967fc78e9c514a478b27debf1fadbc772283`. It uses
|
|
`gitea.maximumdirect.net/eric/promptkit` v0.12.0. Application configuration
|
|
already uses native ConfigKit v1.2.0, but framework inputs, inspection
|
|
records, and diagnostics still use old-path ConfigKit v0.5.0. The old
|
|
PromptKit module also selects two external catalog modules and go-yaml
|
|
v4.0.0-rc.6. Prompt versions are selectors in both executable interfaces and
|
|
appear in prepared, inspection, and execution output. The completed
|
|
[v0.12.0 roadmap](promptkit.md) records the prior migration.
|
|
|
|
The target is `go.maximumdirect.net/promptkit` v0.23.2, commit
|
|
`382ccfb14b9630fd8f48c8364dbe2b6159637d71`, and
|
|
`go.maximumdirect.net/configkit` v1.2.1, commit
|
|
`51ef3144158db1a09fabdbd1c7ae59908c84923b`, with stable go-yaml v4.0.0.
|
|
The existing Go 1.27.0 consumer minimum and Go 1.27.4 release toolchain
|
|
already satisfy this selection.
|
|
|
|
- [PromptKit release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/releases/v0.23.2.md)
|
|
- [PromptKit migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/configuration-migration.md)
|
|
- [PromptKit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
|
|
- [PromptKit consumer API guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
|
|
- [ConfigKit v1.2.1 release notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/releases/v1.2.1.md)
|
|
|
|
## Targeted End State
|
|
|
|
### One Configuration Mechanism, Separate Schemas
|
|
|
|
ConfigKit resolves the application document; Scriptorium owns its schema,
|
|
defaults, domain rules, source selection, and override mapping. The app uses
|
|
one native schema and decoder. Existing fields can remain where they still
|
|
express the right application setting, without a separate legacy mode.
|
|
PromptKit loads its framework sources separately using the same released
|
|
ConfigKit types. Application-only configuration inspection still does not
|
|
construct a PromptKit engine or require framework resources.
|
|
|
|
Scriptorium selects ordered framework files and directories and supplies
|
|
them through PromptKit's supported public APIs. The application config file
|
|
is not itself a framework source. Preserve the application selectors,
|
|
explicit override behavior, and source grouping where they already map
|
|
directly to upstream inputs. PromptKit and ConfigKit determine how those
|
|
inputs compose and how relative framework resources resolve. Scriptorium
|
|
does not infer namespaces, rewrite IDs, flatten source origins, or supply a
|
|
second merge policy.
|
|
|
|
Adopt PromptKit's default OpenRouter bundle as its lowest-priority underlay.
|
|
Caller definitions remain able to replace bundled records by ordinary
|
|
composition. Scriptorium does not recreate the former catalogs, maintained
|
|
profile aliases, or a local implicit profile selection. Bundle availability
|
|
is not a readiness check or a promise of a fixed provider model.
|
|
|
|
### Existing Commands And Execution
|
|
|
|
Execution, rendering, and prompt inspection select a prompt by exact ID,
|
|
including a qualified collection ID where appropriate. Remove the CLI
|
|
version selector and the corresponding version members from the CLI and HTTP
|
|
request, response, inspection, and report contracts where they exist. Do not
|
|
accept a legacy version selector and then ignore it.
|
|
|
|
Continue to distinguish framework configuration, resolved resources, and
|
|
request preparation. Framework configuration inspection reports the
|
|
upstream captured result, with native provenance, normalization, and
|
|
redaction where currently used. Profile inspection reports the resolved
|
|
profile, preserving unset versus explicitly supplied values, rather than
|
|
reconstructing backend-completed settings. Render shows request-completed
|
|
settings. Use native reports or writers when their content matches the
|
|
existing interface's purpose; retain focused projections where Scriptorium
|
|
owns the format or disclosure boundary. In particular, captured prompt
|
|
messages becoming available upstream is not reason to add them automatically
|
|
to existing prompt inspection output.
|
|
|
|
PromptKit owns preparation, provider calls, retries, capacity, validation,
|
|
and repair. Preserve the configured shared server engine and established
|
|
backend admission behavior. Use PromptKit's native operation timeout for the
|
|
existing whole-run budget where it can preserve the execution boundary and
|
|
support the intended CLI and HTTP outcomes. A provider-attempt timeout is
|
|
still distinct from the whole-run deadline; caller cancellation still
|
|
applies. Keep the existing context wrapper if delegation would change those
|
|
semantics rather than introducing two independent timers. CLI process
|
|
behavior, HTTP decoding, limits, restricted artifact loading, safe
|
|
diagnostics, and application-owned execution reports remain adapter
|
|
responsibilities.
|
|
|
|
### HTTP Contract
|
|
|
|
Serve one ID-only HTTP execution contract. Choose the route, request and
|
|
response shapes, and status mapping that best fit the single-run model.
|
|
There is no need to preserve `POST /v1/runs` or to introduce a successor
|
|
route solely to signal incompatibility. No HTTP compatibility routes,
|
|
legacy payload adapters, or client migration procedures are needed.
|
|
Retain operational boundaries such as configured size limits, restricted
|
|
artifact access, credential handling, and shared backend admission; these
|
|
serve the application independently of wire compatibility.
|
|
|
|
## Work Needed From The Baseline
|
|
|
|
- **Converge the module graph and engine wiring.** Move runtime and test
|
|
imports to the vanity paths. Replace old ConfigKit input, path, provenance,
|
|
and diagnostic types at the CLI construction and inspection boundaries.
|
|
Remove the obsolete diagnostic branches and the legacy module and catalog
|
|
dependencies. Keep distinctions between application and framework error
|
|
presentation where they remain useful. Use public typed causes and sentinel
|
|
categories, including for construction, deadlines, and artifact failures.
|
|
Reconcile commit-pinned attribution and license notices against the
|
|
resulting runtime graph under the [OSS policy](../policy/oss.md),
|
|
distinguishing linked dependencies from upstream maintainer tooling.
|
|
- **Migrate maintained configuration and definitions in place.** Convert
|
|
version-keyed prompts and other keyed resource maps to explicit-ID lists;
|
|
choose one definition per ID or give separately selectable former versions
|
|
distinct IDs. Convert framework source controls to `config:`, write
|
|
`required: true` where a missing import is an error, and use version 2 only
|
|
where an optional framework source header is supplied. Use sibling
|
|
`extends: {id: ...}` and update exact references when using collections.
|
|
Review same-ID whole-record replacement, backend fallback from null
|
|
profile fields, self-contained schemas, and source-local message files. Retain
|
|
existing application discovery, overlays, and path semantics where still
|
|
appropriate; they do not need to change solely to make an old file fail.
|
|
Review maintained examples and real-engine test fixtures together.
|
|
- **Adapt the existing interfaces.** Update CLI argument mapping,
|
|
formatters, captured framework source records and list-index explanation
|
|
paths, HTTP DTOs, and terminal report projections. Keep explicit zero
|
|
overrides and optional-value presence. Check that the restricted HTTP
|
|
artifact reader transfers ownership of returned artifacts and bytes under
|
|
the new public contract without changing Scriptorium's containment policy.
|
|
Preserve established CLI outcomes outside the intentional cutover changes.
|
|
Validate the HTTP adapter against its new contract and the application
|
|
boundaries above, not against old wire shapes.
|
|
- **Give operators a migration path in documentation.** Update the
|
|
[consumer migration guide](../consumers/upgrading-promptkit.md) with
|
|
before-and-after application and framework examples, directions for old
|
|
prompt versions and catalog references, and the changed CLI contract.
|
|
Explain semantic changes that can survive a syntactic conversion,
|
|
particularly replacement, null fallback, and schema
|
|
resolution. Document the new HTTP contract directly in the
|
|
[API reference](../api.md) and update its maintained examples. Update the
|
|
canonical configuration, CLI, subprocess, and internal references where
|
|
their implementation changes. Refresh current contributor and
|
|
architecture references to the selected upstream release,
|
|
leaving historical release records intact. Record release impact as
|
|
an intentional incompatible change under the
|
|
[release policy](../policy/release.md#versioning-and-compatibility); this
|
|
roadmap does not select or publish a release.
|
|
- **Verify the migrated boundary, not a second upstream test suite.** Use
|
|
the repository's baseline Go checks and representative offline examples
|
|
and real-engine adapter tests. Exercise native source composition,
|
|
qualified selection, source-local resources, captured inspection,
|
|
render and execution, and representative failures for obsolete formats
|
|
and selectors. Protect behavior likely to regress in this cutover:
|
|
explicit zero overrides, shared backend admission, timeout attribution,
|
|
safe output, and unchanged HTTP artifact policy. No live inference is
|
|
needed to validate the migration.
|