Plan symmetric typed prompt source helpers
This commit is contained in:
@@ -8,9 +8,9 @@ presentation; Promptkit exposes the selected resource's resolved configuration.
|
|||||||
|
|
||||||
The direction is accepted for planning; implementation has not begun. Selected
|
The direction is accepted for planning; implementation has not begun. Selected
|
||||||
work includes fuller prompt inspection, profile inspection of the resolved
|
work includes fuller prompt inspection, profile inspection of the resolved
|
||||||
profile itself, a new `InspectBackend`, and `BackendConfig.Extends`. Execution-
|
profile itself, a new `InspectBackend`, `BackendConfig.Extends`, and typed prompt
|
||||||
policy reporting and prepared-request enhancements have been removed from this
|
construction through `PromptConfig`/`PromptSource`. Execution-policy reporting
|
||||||
roadmap. Decisions below record the accepted boundary and remaining choices.
|
and prepared-request enhancements have been removed from this roadmap. Decisions below record the accepted boundary and remaining choices.
|
||||||
|
|
||||||
## Resource-Inspection Boundary
|
## 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
|
See [resource inheritance](../formats.md#resource-inheritance) and the existing
|
||||||
[profile helper](../../profiles.go).
|
[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
|
## Related Work
|
||||||
|
|
||||||
Typed prompt construction remains open decision 3. Listing return-type
|
Listing return-type consistency is a possible later cleanup, not required here.
|
||||||
consistency is a possible later cleanup, not required here. Collections,
|
Collections, schemas, and engine options do not need identical APIs merely for symmetry.
|
||||||
schemas, and engine options do not need identical APIs merely for symmetry.
|
|
||||||
The [deferred fingerprint proposal](deferred.md#semantic-execution-target-fingerprints)
|
The [deferred fingerprint proposal](deferred.md#semantic-execution-target-fingerprints)
|
||||||
remains separate. Live capacity monitoring, provider health guarantees, and
|
remains separate. Live capacity monitoring, provider health guarantees, and
|
||||||
source round-tripping are not selected deliverables.
|
source round-tripping are not selected deliverables.
|
||||||
|
|
||||||
## Decisions
|
## 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.
|
retained for continuity with the discussion; implementation is pending.
|
||||||
|
|
||||||
### 1. How Should An Unknown Backend Be Classified?
|
### 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?
|
### 3. Should Typed Prompt Construction Be Added In This Round?
|
||||||
|
|
||||||
**Recommendation:** Keep `PromptConfig`/`PromptSource` separate until a
|
**Status:** Accepted; implementation pending.
|
||||||
programmatic authoring need justifies the public input model. Files and ConfigKit
|
|
||||||
mappings already support prompts; this does not block operator inspection.
|
|
||||||
|
|
||||||
**Alternative:** Add the typed helper for discoverability and compiler assistance.
|
**Decision:** Add `PromptConfig` and `PromptSource`, including inheritance,
|
||||||
It would need useful message/input/output and omission semantics, inheritance,
|
following the thin mapping-constructor pattern described above. Retain the
|
||||||
and source context for relative content files. Its maintenance cost is larger
|
backend/profile helpers and raw ConfigKit mapping support.
|
||||||
than adding backend `Extends`; composition can still delegate to ConfigKit.
|
|
||||||
|
**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?
|
### 4. How Should Resolved Resource Results And Presence Be Represented?
|
||||||
|
|
||||||
@@ -300,14 +345,16 @@ in resource inspection.
|
|||||||
|
|
||||||
## Implementation And Verification
|
## Implementation And Verification
|
||||||
|
|
||||||
1. Resolve result representation/migration in decision 4. Decide typed prompt
|
1. Resolve result representation/migration in decision 4. Source-input helper
|
||||||
construction separately; it is not a prerequisite for the selected work.
|
types and inspection results have distinct purposes; select their shapes
|
||||||
|
accordingly.
|
||||||
2. Expose expanded prompt content and resolved profile fields through existing
|
2. Expose expanded prompt content and resolved profile fields through existing
|
||||||
capture/lookup paths, before execution completion. Preserve configured
|
capture/lookup paths, before execution completion. Preserve configured
|
||||||
presence/null distinctions without another composition pass.
|
presence/null distinctions without another composition pass.
|
||||||
3. Add backend inspection and the accepted public missing-backend error,
|
3. Add backend inspection and the accepted public missing-backend error,
|
||||||
returning configured diagnostic metadata without endpoint derivation.
|
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
|
5. Update GoDoc, consumer/internal guidance, and release notes for the selected
|
||||||
behavior and profile compatibility change. Coordinate CommandKit reporting.
|
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.
|
leaving omitted overrides absent. It does not require diagnostic readiness.
|
||||||
- Resource selection, error classification, and mutable-result ownership follow
|
- Resource selection, error classification, and mutable-result ownership follow
|
||||||
the selected contract; reuse existing namespace and ownership coverage.
|
the selected contract; reuse existing namespace and ownership coverage.
|
||||||
- Typed backend inheritance works through real ConfigKit composition without
|
- Typed backend and prompt inheritance work through real ConfigKit composition.
|
||||||
retesting ConfigKit's entire generic inheritance feature set.
|
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
|
CommandKit owns presentation tests for the migrated resource view. Follow the
|
||||||
[testing policy](../policy/testing.md), combine cases where useful, and reuse
|
[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,
|
Completion means operators can inspect the resolved selected prompt, profile,
|
||||||
or backend accurately without assembling execution settings or navigating raw
|
or backend accurately without assembling execution settings or navigating raw
|
||||||
configuration paths. Backend inheritance is available through the typed source
|
configuration paths. All three resource kinds have typed source helpers,
|
||||||
helper, and consumers have migration guidance for changed profile inspection.
|
including inheritance support, and consumers have migration guidance for changed
|
||||||
|
profile inspection.
|
||||||
No engine-policy or prepared-request additions are part of completion.
|
No engine-policy or prepared-request additions are part of completion.
|
||||||
|
|||||||
Reference in New Issue
Block a user