Specify automatic PromptKit source discovery
This commit is contained in:
@@ -1,8 +1,9 @@
|
||||
# PromptKit Adoption Outline
|
||||
|
||||
**Updated:** 2026-11-07
|
||||
**Updated:** 2026-11-09
|
||||
|
||||
**Status:** Initial outline. Follow the [master roadmap](library-adoption.md)
|
||||
**Status:** Adoption direction and automatic operator-source selection resolved;
|
||||
implementation remains pending. Follow the [master roadmap](library-adoption.md)
|
||||
for shared adoption principles, dependency identities, and sequencing.
|
||||
|
||||
## Baseline and Target
|
||||
@@ -81,8 +82,9 @@ checks whose purpose was enforcing the removed application backend registry.
|
||||
|
||||
Remove superseded fields, code, and tests in the major-release cutover and update
|
||||
the affected policies and current contracts with implementation. The ConfigKit
|
||||
outline owns file discovery and import policy; those choices govern how native
|
||||
resources are supplied, not who owns their semantics.
|
||||
outline owns Audita main-file discovery and general import policy; this outline
|
||||
owns the automatic PromptKit source selection below. PromptKit retains resource
|
||||
semantics under both policies.
|
||||
|
||||
### Bundled Prompts and Operator Replacements — Resolved
|
||||
|
||||
@@ -111,9 +113,69 @@ mechanism supports production customization. Standard inspection, provenance,
|
||||
and request preview must make effective prompts and their origins understandable.
|
||||
Audita's response schemas and domain validation continue to apply.
|
||||
|
||||
External source selection follows the [ConfigKit discovery/import plan](configkit.md).
|
||||
This workflow is required PromptKit adoption scope and should use
|
||||
native composition rather than a separate prompt loader or override system.
|
||||
External source selection follows the [automatic source contract below](#automatic-prompt-sources--resolved),
|
||||
using the [ConfigKit import policy](configkit.md#discovery-locations-and-import-selection--resolved).
|
||||
This workflow is required PromptKit adoption scope and uses native composition.
|
||||
|
||||
### Automatic Prompt Sources — Resolved
|
||||
|
||||
Automatically compose optional `./prompts.yml` and YAML files recursively under
|
||||
`./prompts/`. Both locations are relative to the invocation's working directory,
|
||||
independent of the selected Audita configuration file's location. The same
|
||||
loading applies when no main application configuration file is found.
|
||||
|
||||
Supply one operator-source underlay with these native ConfigKit imports:
|
||||
|
||||
```yaml
|
||||
config:
|
||||
imports:
|
||||
- path: prompts.yml
|
||||
required: false
|
||||
- dir: prompts
|
||||
required: false
|
||||
recursive: true
|
||||
pattern: ["*.yml", "*.yaml"]
|
||||
```
|
||||
|
||||
Enable imports and provide the declaration's host filesystem context through
|
||||
ConfigKit's public input APIs, rooted at the invocation's working directory.
|
||||
Keep this host context separate from the embedded prompt filesystem. ConfigKit
|
||||
owns traversal, composition, inheritance, and provenance; do not add an Audita
|
||||
directory walker, YAML parser, or replacement mechanism.
|
||||
|
||||
Compose the engine's layers from lowest to highest priority:
|
||||
|
||||
1. PromptKit's default-on bundled OpenRouter catalog.
|
||||
2. Audita's embedded `audita` prompt underlay.
|
||||
3. The operator-source underlay containing both automatic imports.
|
||||
|
||||
Load both automatic locations when present. Missing optional sources contribute
|
||||
nothing; present but unreadable, invalid, or conflicting sources retain native
|
||||
errors. The file and directory compose as strict peers within one tier. Neither
|
||||
gains priority from declaration, filename, or discovery order; duplicate resource
|
||||
identities in that tier are errors. At the boundary above embedded defaults,
|
||||
native same-ID replacement replaces the complete matching record while retaining
|
||||
unmatched defaults. Follow the upstream
|
||||
[source and profile precedence](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/formats.md#source-and-profile-precedence).
|
||||
|
||||
Use native PromptKit documents at the document root, with namespaces and IDs
|
||||
declared in their content. Each file may define one or several resources,
|
||||
including supported profiles and backends. Filenames and subdirectories do not
|
||||
assign identities or namespaces. Replacing an Audita prompt uses the same
|
||||
`collections.audita` namespace and local prompt ID as its embedded definition,
|
||||
as specified above; no source-selector setting is required.
|
||||
|
||||
Operators can use `prompts.yml` for definitions or as a manifest importing shared
|
||||
libraries elsewhere, and organize local definitions beneath `prompts/`. Nested
|
||||
imports and prompt `content_file` references retain native source-relative
|
||||
handling. Avoid importing the automatically discovered directory again from the
|
||||
manifest; repeated inclusion within the tier retains ConfigKit's native error.
|
||||
|
||||
Use one shared engine-loading path for processing, configuration/resource
|
||||
inspection, request preview, validation, and smoke commands. All must observe
|
||||
the same layers and captured definitions for the same invocation inputs.
|
||||
`--config` continues to select Audita's application configuration; it does not
|
||||
change the working-directory base of these automatic resource imports.
|
||||
|
||||
### Profile Inspection and Summary — Resolved
|
||||
|
||||
@@ -143,6 +205,8 @@ surface and request-preview integration work.
|
||||
are selected; mounting does not rewrite stored references.
|
||||
3. Convert the seven embedded prompts into the `audita` collection and update
|
||||
maintained operator examples/fixtures for the resolved replacement workflow.
|
||||
Implement automatic operator imports above the embedded underlay through the
|
||||
shared engine loader, including explicit host and embedded filesystem contexts.
|
||||
Remove prompt version selectors and descriptive `PromptVersion` metadata from
|
||||
requests, registries, inspection, and diagnostics. Response-schema versions
|
||||
are separate and need not change. Keep domain instructions and per-call schemas;
|
||||
@@ -168,8 +232,9 @@ surface and request-preview integration work.
|
||||
zero conversion and document intentional request changes.
|
||||
7. Update captured-source accounting for list indexes and collection prefixes,
|
||||
including inherited/moved content-file origins. Preserve output-collision
|
||||
protection for consumed host documents and effective message files. Array
|
||||
positions are addresses, not durable resource identities.
|
||||
protection for consumed host documents, including automatic imports, and
|
||||
effective message files. Array positions are addresses, not durable resource
|
||||
identities.
|
||||
8. Keep self-contained embedded response schemas. The new schema rule does not
|
||||
require a bundler for Audita's current schemas. Check custom artifact-reader
|
||||
ownership only where such a reader is actually used. Preserve native retries,
|
||||
@@ -207,13 +272,23 @@ that no application override layer or direct-key injection defeats native
|
||||
precedence, and that synthetic keys stay out of Audita diagnostics and artifacts.
|
||||
|
||||
Verify the embedded `audita` prompts work without external prompt definitions.
|
||||
Cover both automatic locations absent, each present alone, and both present with
|
||||
distinct resources, including nested YAML files. Exercise missing optional
|
||||
sources, unreadable/invalid sources, and same-tier identity conflicts through
|
||||
native loading. Confirm that an explicit application config elsewhere and absent
|
||||
main-file discovery both retain the invocation working directory as the automatic
|
||||
source base. Check manifest imports of shared libraries and source-relative
|
||||
message files, with provenance and consumed-source collision protection intact.
|
||||
Exercise both individual-prompt and complete-set replacements using native
|
||||
collection IDs, checking that unreplaced defaults remain available. Demonstrate
|
||||
that editing external prompt/message files changes a newly constructed runtime's
|
||||
prepared request without rebuilding the binary, while the existing runtime keeps
|
||||
its captured inputs. Check qualified-ID selection, effective prompt inspection,
|
||||
source provenance, and continued response-schema and domain validation with
|
||||
controlled responses. Include a maintained edit-and-rerun example for developers.
|
||||
controlled responses. Verify that processing and standard inspection/preview use
|
||||
the same effective replacements and that the bundled catalog remains available.
|
||||
Include a maintained edit-and-rerun example using the automatic sources, without
|
||||
requiring a source-selector setting or binary rebuild.
|
||||
|
||||
Verify that role selections are visible in application configuration inspection,
|
||||
resources through standard inspection, and completed request settings through
|
||||
|
||||
Reference in New Issue
Block a user