Document the PromptKit upgrade roadmap
This commit is contained in:
180
docs/roadmap/promptkit-v0.23.2-adoption.md
Normal file
180
docs/roadmap/promptkit-v0.23.2-adoption.md
Normal file
@@ -0,0 +1,180 @@
|
|||||||
|
# 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, not a second application schema, a legacy definition
|
||||||
|
reader, or compatibility aliases.
|
||||||
|
|
||||||
|
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. The HTTP route decision
|
||||||
|
below determines where the single new HTTP contract is served.
|
||||||
|
|
||||||
|
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 current execution
|
||||||
|
boundary and error mapping. 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.
|
||||||
|
|
||||||
|
## 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 the established execution outcome, size-limit, cancellation, and
|
||||||
|
credential-disclosure behavior outside the intentional cutover changes.
|
||||||
|
- **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 and HTTP
|
||||||
|
contracts. Explain semantic changes that can survive a syntactic
|
||||||
|
conversion, particularly replacement, null fallback, and schema
|
||||||
|
resolution. Update the canonical configuration, CLI, HTTP, 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.
|
||||||
|
|
||||||
|
## Open Decisions
|
||||||
|
|
||||||
|
### HTTP Route For The ID-Only Contract
|
||||||
|
|
||||||
|
**Recommendation:** Replace `POST /v1/runs` with a successor route such as
|
||||||
|
`POST /v2/runs` and support only the successor in the new release. Removing
|
||||||
|
`prompt_version` changes a documented request and output contract. A new route
|
||||||
|
makes that break explicit and lets a stale client fail even if it happened
|
||||||
|
not to send the removed field. Operators must update the URL as well as
|
||||||
|
their request and response handling, but there is no route forwarding or
|
||||||
|
legacy model to maintain.
|
||||||
|
|
||||||
|
**Alternative:** Cut over `POST /v1/runs` in place as part of the incompatible
|
||||||
|
application release. This is viable if all deployed HTTP callers can migrate
|
||||||
|
in lockstep and changing the URL would add unnecessary deployment work.
|
||||||
|
The downside is that callers omitting the old field could reach a changed
|
||||||
|
contract at the same URL, while callers sending it fail strict decoding.
|
||||||
|
Either choice has one live contract; compatibility routing is not part of
|
||||||
|
this work.
|
||||||
Reference in New Issue
Block a user