236 lines
13 KiB
Markdown
236 lines
13 KiB
Markdown
# Feature Considerations Before The Next Release
|
|
|
|
Status: items 1 and 2 record accepted design decisions. Review these items before
|
|
the next release; this document does not authorize implementation or commit either
|
|
item to that release. Implemented schema support is documented in the
|
|
[format reference](../formats.md#schemas).
|
|
|
|
## 1. Enable One Structured-Output Repair Attempt By Default
|
|
|
|
**Accepted:** default to one repair attempt for every validation mode that
|
|
supports repair. This gives structurally invalid or empty output one automatic
|
|
correction opportunity without requiring each consumer to opt in.
|
|
|
|
| Validation mode | Default repair attempts |
|
|
| --- | ---: |
|
|
| `none` | 0 |
|
|
| `basic` | 1 |
|
|
| `json` | 1 |
|
|
| `json_schema` | 1 |
|
|
|
|
Use a presence-aware public input `RepairAttempts` field: omission or final null
|
|
selects the mode's default; explicit zero disables repairs. Accepting null is a
|
|
deliberate change from the current configuration contract. Authors can clear an
|
|
inherited budget with null through ordinary ConfigKit composition; PromptKit
|
|
interprets the final value without replaying that composition.
|
|
|
|
Retain explicit budgets of two or three
|
|
for eligible modes. Keep the existing rejection of positive budgets for `none`.
|
|
Choose one rather than two as the default; consumers can opt into another
|
|
correction opportunity when appropriate for their workloads.
|
|
|
|
Apply defaults after ConfigKit composition, preserving explicit values. Execution
|
|
and inspection use the resolved concrete budget. Apply the same mode defaults to
|
|
omitted runtime output-contract budgets; runtime contracts still replace the
|
|
configured contract completely. Prepared execution retains its resolved budget.
|
|
|
|
Confine presence awareness to inputs. A `*int` is the recommended Go input shape:
|
|
nil selects the default and a pointer to zero disables repair. Resolved inspection
|
|
and prepared details expose the concrete budget; execution uses a concrete integer.
|
|
Counters reporting repairs actually performed remain ordinary integers. Do not
|
|
propagate optional-value handling into execution or counters solely to accommodate
|
|
input defaulting.
|
|
|
|
Implementation planning must specify the presence-aware Go shape and migration
|
|
from the current integer field, and cover omission, null, and explicit zero across
|
|
configuration, typed helpers, and runtime contracts. Document that repair runs
|
|
only after failed validation and can add generation latency and usage. Existing
|
|
repair accounting, exhaustion, cancellation, and transient-retry semantics remain
|
|
unchanged; the change does not promise successful correction.
|
|
|
|
## 2. Consume Application-Resolved Configuration Under `promptkit`
|
|
|
|
**Accepted:** the application composes configuration once through ConfigKit and
|
|
passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit
|
|
locates the fixed root-level `promptkit` section and consumes only that section,
|
|
ignoring sibling application settings. The application does not extract, reshape,
|
|
serialize, or reload a PromptKit-specific view. Do not add a configurable mounting
|
|
key.
|
|
|
|
The root-key migration supports this handoff; changing YAML paths alone does not
|
|
fulfill the feature. The architectural benefit is a single composition lifecycle
|
|
with native source context and provenance, rather than an application bridge
|
|
between separately loaded configurations.
|
|
|
|
### Current Boundary And Intended Consumer Workflow
|
|
|
|
Today, PromptKit accepts configuration sources and runs its own ConfigKit load.
|
|
Its typed root document rejects unrelated application fields. Audita, for example,
|
|
loads application settings separately, then uses their recorded main-source
|
|
context to assemble embedded and companion PromptKit sources for another load.
|
|
It does not currently hand PromptKit its resolved application configuration.
|
|
|
|
The target workflow is:
|
|
|
|
1. The application includes PromptKit's configuration definition/registration and
|
|
desired bundled or application sources in its ordinary ConfigKit setup.
|
|
2. ConfigKit composes and resolves the complete application configuration once,
|
|
applying each component's registered rules.
|
|
3. The application passes the whole resolved result to PromptKit, together with
|
|
runtime collaborators such as its HTTP client. PromptKit captures its effective
|
|
resources and constructs the engine without another configuration load.
|
|
|
|
File discovery, source selection, imports, layering, and application overrides
|
|
remain application policy. Embedded prompt selection and companion-file imports
|
|
join the original load; they do not disappear. The change removes context-transfer
|
|
and duplicate-loading machinery, not application-specific execution requests,
|
|
profile selection, required-resource checks, or diagnostics policy.
|
|
|
|
### Configuration Rules And Handoff
|
|
|
|
Expose a small public integration surface for PromptKit's configuration rules to
|
|
participate in the application's ConfigKit load. Defaults, normalization, field
|
|
validation, collection identity constraints, and sensitivity declarations remain
|
|
PromptKit-owned rules applied through ConfigKit's native lifecycle. Applications
|
|
must not reproduce these rules or depend on PromptKit's internal types.
|
|
|
|
The exact public registration and result-accepting API shapes require planning.
|
|
The handoff must work with an application-owned result type, not require replacing
|
|
its configuration model with PromptKit's root document type. Preserve effective
|
|
values, source contexts for relative message/schema files, provenance, and native
|
|
redaction. A decoded map alone or a serialized section loaded again is not an
|
|
equivalent handoff.
|
|
|
|
Register desired bundled defaults as ordinary underlays before composition;
|
|
engine construction must not inject another configuration layer into an already
|
|
resolved result. Apply configured repair defaults from item 1 during resolution,
|
|
so inspection and execution agree. Runtime request defaulting remains separate.
|
|
|
|
Retain source-loading construction as a convenience for consumers that want
|
|
PromptKit to select its own loading path. It should use the same configuration
|
|
rules and engine-capture path: load once, then hand off the result. Do not maintain
|
|
two independent implementations of configuration semantics. Existing source
|
|
selection choices remain available subject to the accepted layout migration.
|
|
|
|
### Fixed Section And Clean Migration
|
|
|
|
Move all PromptKit-owned document settings beneath `promptkit`, including
|
|
`promptkit.backends`, `promptkit.profiles`, `promptkit.prompts`,
|
|
`promptkit.collections`, and `promptkit.schema_root`. Collection-local fields
|
|
remain inside their collection. Runtime collaborators are Go API inputs, not new
|
|
YAML fields.
|
|
|
|
Make a clean breaking migration with one canonical resolved location. Do not
|
|
support legacy root-level resource locations through aliases, automatic detection,
|
|
or a second merge/precedence pass. Runtime resource IDs and namespace selection
|
|
remain unchanged; the configuration wrapper is not part of a resource ID.
|
|
|
|
Preserve convenient standalone files. Individual resource files can still begin
|
|
with `id`, and collection files can still contain local `prompts`, `profiles`,
|
|
`backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit
|
|
import destinations and PromptKit source helpers mount those fragments at the
|
|
appropriate nested location. Source-relative context follows the effective
|
|
contributing field, not the location of the application document or mount point.
|
|
|
|
ConfigKit-owned headers and directives retain their native semantics. The
|
|
application owns its main configuration specification; PromptKit must not impose
|
|
its standalone document version on the whole application. Planning must account
|
|
for application headers and optional PromptKit fragment headers in the same load,
|
|
including the standalone convenience path, without inventing a second header
|
|
parser or version-composition pass.
|
|
|
|
An absent `promptkit` section contributes no application-supplied PromptKit
|
|
settings; selected bundled underlays can still contribute defaults during the
|
|
original load. Old root-level keys such as `prompts` and `profiles` are neither
|
|
consumed nor specially rejected by PromptKit: they may be application settings.
|
|
Unknown fields inside `promptkit` remain configuration errors. The application's
|
|
own validation and ConfigKit's document/composition rules still apply to the
|
|
whole document. Migration guidance must explain that unmigrated resources are
|
|
not loaded and can therefore produce missing-resource errors when selected.
|
|
|
|
### Inspection Boundary
|
|
|
|
Scope `InspectConfiguration` value reports and comparisons to PromptKit's section,
|
|
retaining actual `promptkit.…` paths and relevant source provenance. Unrelated
|
|
application values must not become part of PromptKit's reports or comparisons
|
|
merely because they share an input document. Preserve native ConfigKit redaction
|
|
and explanation semantics. Resource inspection remains resource-scoped.
|
|
|
|
Prefer native ConfigKit scoped inspection over PromptKit-maintained reporting
|
|
adapters. The requirement concerns the public scope and ownership of inspection;
|
|
it does not independently promise that ConfigKit never visits sibling data
|
|
internally. Do not silently substitute whole-application reporting, reconstruct
|
|
source history, or reload a copied section to manufacture a scoped result.
|
|
|
|
## Guidance For Implementation Planning
|
|
|
|
### Start With The Public Integration Contract
|
|
|
|
Prepare a concrete consumer sketch covering registration, one application-owned
|
|
load, whole-result engine construction, and PromptKit-scoped inspection. Also show
|
|
the standalone source-loading convenience path using the same machinery. Verify
|
|
against ConfigKit's selected public API before committing to an implementation
|
|
structure. This sketch should demonstrate reduced integration work, not merely
|
|
move source-context reconstruction or PromptKit validation into application code.
|
|
|
|
The earlier ConfigKit v1.3.0 feasibility assessment verified loading a typed
|
|
`promptkit` envelope with arbitrary siblings and explaining a section with native
|
|
paths, provenance, and redaction. It reported that effective-output writing,
|
|
opaque metadata, and comparison APIs were whole-result operations. That assessment
|
|
**does not establish support for the expanded application-owned load and
|
|
whole-result handoff**. Recheck current capabilities rather than assume that the
|
|
envelope alone solves the new integration contract.
|
|
|
|
Specifically establish:
|
|
|
|
- How PromptKit's rules compose with an application's configuration definition,
|
|
including defaults, normalization, identities, validation, and sensitivity.
|
|
- How the public handoff accepts an application-owned resolved result while
|
|
retaining usable field contexts and native inspection evidence.
|
|
- How selected bundled defaults and standalone fragments join the original load,
|
|
with the intended header/version rules.
|
|
- How native scoped effective output, metadata/history, explanations, and
|
|
comparisons support the inspection boundary, including absent sections.
|
|
|
|
If public APIs cannot support these responsibilities cleanly, identify the
|
|
specific gap and propose a focused upstream capability request before designing
|
|
workarounds. Keep such requests about public consumer capabilities, not ConfigKit
|
|
internals. A map-copy/reload adapter or an application-maintained duplicate of
|
|
PromptKit's configuration rules would defeat the accepted design.
|
|
|
|
### Implementation Scope And Validation
|
|
|
|
Then specify input/resolved Go shapes, registration and constructor signatures,
|
|
source-helper adaptations, and migration examples. Update identity registrations,
|
|
normalization, validation, bundled underlays, and inspection paths together.
|
|
Keep the repair-default and resolved-configuration changes separately reviewable;
|
|
the repair work need not wait for upstream integration capabilities. Neither needs
|
|
a new execution subsystem or a compatibility resolver.
|
|
|
|
Include focused checks for:
|
|
|
|
- Mode defaults after composition, null clearing an inherited repair budget,
|
|
explicit zero, explicit positive budgets, and the existing rejection of positive
|
|
budgets for `none`; cover typed and runtime inputs as well as YAML.
|
|
- Concrete budgets in inspection and prepared snapshots, with actual repair
|
|
counters retaining their existing meaning.
|
|
- An application-owned configuration type with sibling settings, one native load,
|
|
and a whole-result handoff that performs no second configuration load.
|
|
- Equivalent effective PromptKit resources through registered application loading
|
|
and standalone convenience loading when supplied equivalent sources.
|
|
- Mixed embedded/operator collections, source-relative message/schema references,
|
|
native inheritance and overrides, and field provenance surviving the handoff.
|
|
- Missing `promptkit` with bundled defaults enabled and disabled, application-owned
|
|
root keys that resemble legacy settings, and unknown fields inside `promptkit`.
|
|
- Inspection and comparison excluding sibling application values, including a
|
|
sibling-only change, while preserving native paths, provenance, and redaction.
|
|
|
|
The product direction is accepted. Exact API shapes, upstream capability gaps,
|
|
and their consequences remain planning work. If feasibility requires changing the
|
|
agreed consumer workflow, surface that decision rather than narrowing the goal to
|
|
root-key relocation alone. No implementation feasibility is claimed by this roadmap.
|
|
|
|
## Further Candidates
|
|
|
|
Append additional pre-release considerations here as they arise.
|