From 363920deb2a8eaf04105abc191011d20297f5b16 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 6 Nov 2026 12:15:00 +0000 Subject: [PATCH] Plan symmetric typed prompt source helpers --- docs/roadmap/inspect-backend.md | 93 +++++++++++++++++++++++++-------- 1 file changed, 72 insertions(+), 21 deletions(-) diff --git a/docs/roadmap/inspect-backend.md b/docs/roadmap/inspect-backend.md index b78ff52..6416e95 100644 --- a/docs/roadmap/inspect-backend.md +++ b/docs/roadmap/inspect-backend.md @@ -8,9 +8,9 @@ presentation; Promptkit exposes the selected resource's resolved configuration. The direction is accepted for planning; implementation has not begun. Selected work includes fuller prompt inspection, profile inspection of the resolved -profile itself, a new `InspectBackend`, and `BackendConfig.Extends`. Execution- -policy reporting and prepared-request enhancements have been removed from this -roadmap. Decisions below record the accepted boundary and remaining choices. +profile itself, a new `InspectBackend`, `BackendConfig.Extends`, and typed prompt +construction through `PromptConfig`/`PromptSource`. Execution-policy reporting +and prepared-request enhancements have been removed from this roadmap. Decisions below record the accepted boundary and remaining choices. ## Resource-Inspection Boundary @@ -195,18 +195,54 @@ mappings remain available for generic controls outside the convenience helper. See [resource inheritance](../formats.md#resource-inheritance) and the existing [profile helper](../../profiles.go). +## Typed Prompt Sources + +Add `PromptConfig` and `PromptSource` to complete the typed source-helper set +alongside `BackendConfig`/`BackendSource` and `ProfileConfig`/`ProfileSource`. +The proposed helper follows their calling convention: + +```go +func PromptSource(label string, prompts []PromptConfig) configkit.Source +``` + +Cover prompt identity, sibling inheritance through `Extends`, default profile, +description, session template, inputs, messages with inline or file content and +cache controls, and output settings. Choose nested input types for configuration +semantics; reuse existing types where suitable without forcing execution or +inspection values into the source-input role. + +Keep the helper a straightforward mapping constructor. Encode supplied fields +under a `prompts` list, then delegate to `configkit.Mapping`. Optional nil fields +mean omission; explicit values, including zero, false, and empty strings where +supported, must remain representable. Preserve nil-versus-empty collections +where that distinction matters to composition. Raw ConfigKit mappings remain +the escape hatch for explicit-null configuration operations and other advanced +composition controls outside the typed convenience surface. + +The helper does not resolve inheritance, apply execution defaults, render +messages, read content files, or independently validate a prompt. Existing +ConfigKit composition and engine loading retain those responsibilities. Relative +content references use the ordinary input/source resource-context mechanism; +creating a typed source does not select a new filesystem root or file-loading +workflow. Reuse ConfigKit's source snapshot behavior rather than adding another +copier or recursive compatibility converter. + +Keep all three source-helper families consistent in their scope and omission +conventions. They need not reproduce every generic configuration operation or +share a reflection-based encoding framework. Maintain the field mappings and +focused behavioral tests as the configuration model evolves. + ## Related Work -Typed prompt construction remains open decision 3. Listing return-type -consistency is a possible later cleanup, not required here. Collections, -schemas, and engine options do not need identical APIs merely for symmetry. +Listing return-type consistency is a possible later cleanup, not required here. +Collections, schemas, and engine options do not need identical APIs merely for symmetry. The [deferred fingerprint proposal](deferred.md#semantic-execution-target-fingerprints) remains separate. Live capacity monitoring, provider health guarantees, and source round-tripping are not selected deliverables. ## Decisions -Decisions 1, 2, and 5 are accepted. Decisions 3 and 4 remain open. Numbering is +Decisions 1, 2, 3, and 5 are accepted. Only decision 4 remains open. Numbering is retained for continuity with the discussion; implementation is pending. ### 1. How Should An Unknown Backend Be Classified? @@ -252,14 +288,23 @@ where to place those additions remains necessary for resource inspection. ### 3. Should Typed Prompt Construction Be Added In This Round? -**Recommendation:** Keep `PromptConfig`/`PromptSource` separate until a -programmatic authoring need justifies the public input model. Files and ConfigKit -mappings already support prompts; this does not block operator inspection. +**Status:** Accepted; implementation pending. -**Alternative:** Add the typed helper for discoverability and compiler assistance. -It would need useful message/input/output and omission semantics, inheritance, -and source context for relative content files. Its maintenance cost is larger -than adding backend `Extends`; composition can still delegate to ConfigKit. +**Decision:** Add `PromptConfig` and `PromptSource`, including inheritance, +following the thin mapping-constructor pattern described above. Retain the +backend/profile helpers and raw ConfigKit mapping support. + +**Rationale:** API symmetry and convenient programmatic construction have value +as Promptkit approaches 1.0. The existing helpers are small explicit encoders; +a prompt helper adds nested input values and mappings, not a new authoring, +composition, or validation subsystem. That bounded maintenance cost is justified +by consistent discoverability and compiler assistance across all three resources. + +**Alternatives considered:** Deferring prompt helpers would leave asymmetric Go +conveniences. Removing the existing typed helpers would simplify Promptkit's +surface but move string-keyed mapping construction to consumers and require +migration. Neither is selected. Full typed coverage of all ConfigKit operations +is unnecessary; raw mappings continue to serve those cases. ### 4. How Should Resolved Resource Results And Presence Be Represented? @@ -300,14 +345,16 @@ in resource inspection. ## Implementation And Verification -1. Resolve result representation/migration in decision 4. Decide typed prompt - construction separately; it is not a prerequisite for the selected work. +1. Resolve result representation/migration in decision 4. Source-input helper + types and inspection results have distinct purposes; select their shapes + accordingly. 2. Expose expanded prompt content and resolved profile fields through existing capture/lookup paths, before execution completion. Preserve configured presence/null distinctions without another composition pass. 3. Add backend inspection and the accepted public missing-backend error, returning configured diagnostic metadata without endpoint derivation. -4. Add typed backend inheritance through the existing ConfigKit source helper. +4. Add typed backend inheritance and the prompt source/helper types, delegating + both to the ordinary ConfigKit mapping and loading path. 5. Update GoDoc, consumer/internal guidance, and release notes for the selected behavior and profile compatibility change. Coordinate CommandKit reporting. @@ -325,8 +372,11 @@ Use focused offline tests for actual boundary risks: leaving omitted overrides absent. It does not require diagnostic readiness. - Resource selection, error classification, and mutable-result ownership follow the selected contract; reuse existing namespace and ownership coverage. -- Typed backend inheritance works through real ConfigKit composition without - retesting ConfigKit's entire generic inheritance feature set. +- Typed backend and prompt inheritance work through real ConfigKit composition. + Prompt sources preserve nested message/input/output settings, omission and + explicit values, ordering, and source snapshot behavior. Include a representative + relative content-file case using ordinary source context. Reuse generic loading, + validation, and inheritance coverage rather than duplicating it for each helper. CommandKit owns presentation tests for the migrated resource view. Follow the [testing policy](../policy/testing.md), combine cases where useful, and reuse @@ -334,6 +384,7 @@ existing coverage. No new benchmark threshold or release gate is selected. Completion means operators can inspect the resolved selected prompt, profile, or backend accurately without assembling execution settings or navigating raw -configuration paths. Backend inheritance is available through the typed source -helper, and consumers have migration guidance for changed profile inspection. +configuration paths. All three resource kinds have typed source helpers, +including inheritance support, and consumers have migration guidance for changed +profile inspection. No engine-policy or prepared-request additions are part of completion.