2026-11-20 15:28:08 +00:00
|
|
|
# Feature Considerations Before The Next Release
|
|
|
|
|
|
2026-11-20 19:13:46 +00:00
|
|
|
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
|
2026-11-20 16:24:16 +00:00
|
|
|
[format reference](../formats.md#schemas).
|
2026-11-20 15:28:08 +00:00
|
|
|
|
|
|
|
|
## 1. Enable One Structured-Output Repair Attempt By Default
|
|
|
|
|
|
2026-11-20 19:10:24 +00:00
|
|
|
**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 |
|
|
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
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
|
2026-11-20 19:10:24 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-20 19:10:24 +00:00
|
|
|
Implementation planning must specify the presence-aware Go shape and migration
|
2026-11-20 19:20:32 +00:00
|
|
|
from the current integer field, and cover omission, null, and explicit zero across
|
2026-11-20 19:10:24 +00:00
|
|
|
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.
|
2026-11-20 15:28:08 +00:00
|
|
|
|
|
|
|
|
## 2. Place Configuration Under A Root-Level `promptkit` Key
|
|
|
|
|
|
2026-11-20 19:13:46 +00:00
|
|
|
**Accepted:** move all PromptKit-owned configuration beneath the fixed root-level
|
|
|
|
|
`promptkit` key. This gives applications a distinct configuration section for
|
|
|
|
|
PromptKit alongside their other settings. Do not add a configurable mounting key.
|
2026-11-20 15:28:08 +00:00
|
|
|
|
2026-11-20 19:13:46 +00:00
|
|
|
The resolved structure includes `promptkit.backends`, `promptkit.profiles`,
|
|
|
|
|
`promptkit.prompts`, `promptkit.collections`, and `promptkit.schema_root`.
|
|
|
|
|
Collection-local fields remain inside their collection. ConfigKit-owned source
|
|
|
|
|
headers and directives retain their native semantics and locations; they do not
|
|
|
|
|
automatically move inside `promptkit`.
|
2026-11-20 15:28:08 +00:00
|
|
|
|
2026-11-20 19:13:46 +00:00
|
|
|
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. This is fragment composition, not support for two
|
|
|
|
|
alternative application configuration layouts. Source-relative resource context
|
|
|
|
|
must continue to follow the effective contributing field.
|
|
|
|
|
|
|
|
|
|
PromptKit owns validation of its section, not sibling application settings.
|
|
|
|
|
Implementation planning must verify the ConfigKit loading boundary so that
|
|
|
|
|
unrelated application sections can coexist without PromptKit interpreting or
|
|
|
|
|
rejecting their contents. Keep field validation within PromptKit's section.
|
|
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
An absent `promptkit` section contributes no application-supplied PromptKit
|
|
|
|
|
settings; bundled defaults can still operate. Old root-level keys such as
|
|
|
|
|
`prompts` and `profiles` are neither consumed nor specially rejected by PromptKit:
|
|
|
|
|
they may be legitimate application-owned settings. Unknown fields inside
|
|
|
|
|
`promptkit` remain configuration errors. This does not bypass ConfigKit's own
|
|
|
|
|
document/composition validation. Migration documentation must explain that an
|
|
|
|
|
unmigrated application document can load without contributing its intended
|
|
|
|
|
resources, with a missing prompt becoming apparent when selected. Do not add
|
|
|
|
|
legacy-layout detection to compensate for that consequence.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2026-11-20 19:13:46 +00:00
|
|
|
Implementation planning must cover:
|
|
|
|
|
|
|
|
|
|
- Updating bundled underlays, source helpers, import destinations, identity
|
|
|
|
|
registrations, normalization, and validation to the new paths using ordinary
|
|
|
|
|
ConfigKit composition.
|
|
|
|
|
- Reflecting nested paths in configuration inspection and diagnostics while
|
|
|
|
|
preserving resource inspection and runtime IDs.
|
|
|
|
|
- Migration guidance for application documents and explicit import destinations,
|
|
|
|
|
including schema roots; standalone fragments should not need extra wrappers.
|
|
|
|
|
- Focused coverage for sibling application settings, mounted collections and
|
|
|
|
|
resources, default overlays, and source-relative message/schema resolution.
|
|
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
## Guidance For Implementation Planning
|
|
|
|
|
|
|
|
|
|
The product decisions above are accepted. Begin planning with a focused feasibility
|
|
|
|
|
check of ConfigKit's public loading and inspection APIs: establish how to validate
|
|
|
|
|
the `promptkit` section while allowing siblings, and how to scope effective-value
|
|
|
|
|
reports, explanations, and comparisons while retaining native paths, provenance,
|
|
|
|
|
and redaction. Do not reconstruct resolved configuration or source history, add a
|
|
|
|
|
second composition pass, or quietly broaden inspection to the whole application.
|
|
|
|
|
If the public API cannot support this boundary, report the specific gap and options
|
|
|
|
|
before committing to an implementation design.
|
|
|
|
|
|
|
|
|
|
Then specify the concrete input/resolved Go shapes, source-helper adaptations,
|
|
|
|
|
and migration examples. Keep the repair-default and configuration-root changes
|
|
|
|
|
separately reviewable even if delivered in the same release. 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.
|
|
|
|
|
- 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
|
|
|
|
|
change confined to a sibling section, while PromptKit paths and explanations
|
|
|
|
|
retain native provenance and redaction behavior.
|
|
|
|
|
|
|
|
|
|
No further product decisions are currently identified. Public API details and the
|
|
|
|
|
ConfigKit feasibility check remain planning work, not evidence that implementation
|
|
|
|
|
has already been validated.
|
2026-11-20 15:28:08 +00:00
|
|
|
|
|
|
|
|
## Further Candidates
|
|
|
|
|
|
|
|
|
|
Append additional pre-release considerations here as they arise.
|