Document collection discovery in the PromptKit adoption roadmap
This commit is contained in:
@@ -15,7 +15,8 @@ The [definition boundary](../adr/0004-definition-boundary.md) and
|
|||||||
The existing CLI and HTTP surfaces should be able to use valid definitions for
|
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
|
the selected PromptKit release without copying its schema or maintaining a
|
||||||
narrower application-specific subset. This roadmap covers the changes to
|
narrower application-specific subset. This roadmap covers the changes to
|
||||||
existing surfaces needed for the migration. New CLI capabilities, including
|
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
|
[Narratio's requirements inspection](narratio-feature-request.md), concrete
|
||||||
request validation, inventory, backend inspection, configuration diffs, and
|
request validation, inventory, backend inspection, configuration diffs, and
|
||||||
smoke diagnostics, are deferred to a separate roadmap. It does not add HTTP
|
smoke diagnostics, are deferred to a separate roadmap. It does not add HTTP
|
||||||
@@ -74,6 +75,34 @@ composition. Scriptorium does not recreate the former catalogs, maintained
|
|||||||
profile aliases, or a local implicit profile selection. Bundle availability
|
profile aliases, or a local implicit profile selection. Bundle availability
|
||||||
is not a readiness check or a promise of a fixed provider model.
|
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. 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
|
### Existing Commands And Execution
|
||||||
|
|
||||||
Execution, rendering, and prompt inspection select a prompt by exact ID,
|
Execution, rendering, and prompt inspection select a prompt by exact ID,
|
||||||
@@ -141,6 +170,16 @@ serve the application independently of wire compatibility.
|
|||||||
existing application discovery, overlays, and path semantics where still
|
existing application discovery, overlays, and path semantics where still
|
||||||
appropriate; they do not need to change solely to make an old file fail.
|
appropriate; they do not need to change solely to make an old file fail.
|
||||||
Review maintained examples and real-engine test fixtures together.
|
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,
|
- **Adapt the existing interfaces.** Update CLI argument mapping,
|
||||||
formatters, captured framework source records and list-index explanation
|
formatters, captured framework source records and list-index explanation
|
||||||
paths, HTTP DTOs, and terminal report projections. Keep explicit zero
|
paths, HTTP DTOs, and terminal report projections. Keep explicit zero
|
||||||
@@ -154,6 +193,13 @@ serve the application independently of wire compatibility.
|
|||||||
[consumer migration guide](../consumers/upgrading-promptkit.md) with
|
[consumer migration guide](../consumers/upgrading-promptkit.md) with
|
||||||
before-and-after application and framework examples, directions for old
|
before-and-after application and framework examples, directions for old
|
||||||
prompt versions and catalog references, and the changed CLI contract.
|
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,
|
Explain semantic changes that can survive a syntactic conversion,
|
||||||
particularly replacement, null fallback, and schema
|
particularly replacement, null fallback, and schema
|
||||||
resolution. Document the new HTTP contract directly in the
|
resolution. Document the new HTTP contract directly in the
|
||||||
@@ -170,7 +216,12 @@ serve the application independently of wire compatibility.
|
|||||||
and real-engine adapter tests. Exercise native source composition,
|
and real-engine adapter tests. Exercise native source composition,
|
||||||
qualified selection, source-local resources, captured inspection,
|
qualified selection, source-local resources, captured inspection,
|
||||||
render and execution, and representative failures for obsolete formats
|
render and execution, and representative failures for obsolete formats
|
||||||
and selectors. Protect behavior likely to regress in this cutover:
|
and selectors. Verify both collection entry-file spellings, multiple loaded
|
||||||
|
collections, 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.
|
||||||
|
Protect behavior likely to regress in this cutover:
|
||||||
explicit zero overrides, shared backend admission, timeout attribution,
|
explicit zero overrides, shared backend admission, timeout attribution,
|
||||||
safe output, and unchanged HTTP artifact policy. No live inference is
|
safe output, and unchanged HTTP artifact policy. No live inference is
|
||||||
needed to validate the migration.
|
needed to validate the migration.
|
||||||
|
|||||||
Reference in New Issue
Block a user