261 lines
16 KiB
Markdown
261 lines
16 KiB
Markdown
# PromptKit v0.23.2 Adoption
|
|
|
|
## Status And Scope
|
|
|
|
Implemented. The original v0.23.2 target below was superseded for final
|
|
verification by PromptKit v0.23.3 at commit
|
|
`804a4d32b23aa2e7973400bb0a322a7016574c9f`, with the maintainer's approval,
|
|
to correct in-flight HTTP operation-timeout attribution. ConfigKit remains
|
|
v1.2.1. This roadmap upgrades 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 and the collection-discovery model
|
|
below. 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.
|
|
|
|
CommandKit adoption (`go.maximumdirect.net/commandkit`), including the
|
|
`ckconfig` and `ckprompt` integrations, is planned after this migration and
|
|
belongs to a separate roadmap. Its standardized operator interfaces are
|
|
expected to replace Scriptorium's current inspection interfaces. This roadmap
|
|
keeps those existing commands in maintenance-only scope and adds no
|
|
CommandKit dependencies or advance integration scaffolding.
|
|
|
|
## 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.
|
|
|
|
### Independently Maintained Collections
|
|
|
|
Scriptorium provides a neutral application interface over PromptKit, including
|
|
CLI subprocess execution for consumers with limited prompting needs. One
|
|
installation may load dozens of collections, each maintained in a separate
|
|
Git repository with its own maintainer and update cadence. Operators can place
|
|
those checkouts beneath a selected directory and make their prompts available
|
|
through the same Scriptorium invocation model.
|
|
|
|
Use ConfigKit imports in a selected framework source to discover collection
|
|
entry files. Establish `collection.yml` and `collection.yaml` as equivalent
|
|
Scriptorium conventions for the collection-root entry file, and select both
|
|
spellings through the installation's import declarations. When using a
|
|
separate glob for each spelling, leave each glob optional (omit
|
|
`required: true`) so either spelling can have zero matches. An installation
|
|
using only one spelling still discovers its collections. Each entry file
|
|
declares its own namespace under PromptKit's native `collections` mapping and
|
|
uses relative imports to assemble its profiles, prompts, and other definition
|
|
files. The checkout directory name does not determine the namespace; callers
|
|
select resources by their exact qualified IDs.
|
|
|
|
The application selects the discovery source through its existing framework
|
|
source selection. ConfigKit owns entry-file discovery, relative imports, and
|
|
composition; PromptKit owns the resulting collection and resource semantics.
|
|
Load the repository entry files rather than treating every YAML file in each
|
|
checkout as an independent framework input. PromptKit's `DirectoryInputs`
|
|
remains useful for curated configuration trees where all YAML files are
|
|
intended contributions. Adding another checkout with a matching entry file
|
|
must make that collection available on the next CLI invocation without adding
|
|
a per-collection source registration or changing the discovery configuration.
|
|
|
|
### 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.
|
|
|
|
Keep the existing `config` and `inspect` commands functional and accurate
|
|
against the selected upstream APIs. Limit inspection work to required import,
|
|
API, type, selector, and semantic adaptations. Do not expand capabilities,
|
|
redesign command syntax or report presentation, or build reusable inspection
|
|
abstractions for the later CommandKit adoption. Necessary output changes should
|
|
be the smallest accurate adaptation, with proportionate test and documentation
|
|
updates.
|
|
|
|
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. Reuse existing native writers and make only required adjustments to
|
|
local inspection projections. Preserve existing disclosure boundaries;
|
|
captured prompt messages becoming available upstream is not reason to add them
|
|
automatically to existing prompt inspection output. Adoption of CommandKit's
|
|
report formats and disclosure behavior belongs to the later roadmap.
|
|
|
|
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.
|
|
- **Demonstrate collection discovery and composition.** Add complete,
|
|
copyable assets under `examples/` showing application selection of a
|
|
framework discovery file, ConfigKit imports matching both collection-root
|
|
filename spellings, and multiple independently namespaced collection
|
|
directories. Include a representative collection with multiple profile and
|
|
prompt definitions in separate files, relative entry-file imports,
|
|
sibling profile inheritance, and qualified prompt-to-profile references.
|
|
Supply synthetic input fixtures and offline CLI rendering examples that
|
|
exercise the discovery-to-selection flow. Keep the example collections in
|
|
the repository so validation does not require cloning external repositories.
|
|
- **Adapt the existing interfaces.** Update CLI argument mapping,
|
|
formatters, captured framework source records and list-index explanation
|
|
paths, HTTP DTOs, and terminal report projections. Inspection changes are
|
|
limited to the maintenance-only adaptations above; inspection formatter
|
|
cleanup, presentation improvements, and CommandKit command standardization
|
|
are outside this migration. 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.
|
|
Document the collection entry-file convention and discovery configuration
|
|
in the [configuration reference](../config.md), with links to the maintained
|
|
examples. Explain the checkout layout and independently managed updates in
|
|
[operations](../operations.md), and demonstrate qualified prompt/profile
|
|
selection and offline rendering in the [CLI reference](../cli.md).
|
|
Distinguish collection-owned namespaces from checkout directory names and
|
|
explain how entry-file imports select the collection's internal resources.
|
|
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. For existing inspection commands, correct
|
|
documentation affected by required API and semantic changes without expanding
|
|
their operator workflows or documenting future CommandKit behavior as current.
|
|
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. Verify collection discovery with either entry-file spelling
|
|
alone and with both spellings across multiple checkouts. Verify relative
|
|
imports and discovery of an added collection without editing the
|
|
installation's source configuration. Include unrelated YAML outside the
|
|
authored import selections to verify that entry-file discovery does not
|
|
treat an entire repository as framework configuration.
|
|
Update affected inspection tests to cover required adaptations, accurate
|
|
optional-value handling, and preserved disclosure boundaries. Reuse existing
|
|
coverage and keep new inspection checks focused on migration regressions;
|
|
do not build a broader report or command suite ahead of CommandKit adoption.
|
|
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.
|