191 lines
9.8 KiB
Markdown
191 lines
9.8 KiB
Markdown
|
|
# PromptKit Request: Consume A Component From One Resolved Application Configuration
|
||
|
|
|
||
|
|
Status: upstream feature request for discussion, not an accepted implementation
|
||
|
|
plan. This document specifies consumer capabilities and leaves API names and
|
||
|
|
internal implementation to ConfigKit.
|
||
|
|
|
||
|
|
## Consumer Need
|
||
|
|
|
||
|
|
PromptKit is a Go library used by applications such as Audita and Scriptorium.
|
||
|
|
Today, an application can load its own settings with ConfigKit, then assemble
|
||
|
|
separate sources for PromptKit to load again. Audita uses the application main
|
||
|
|
source's recorded filesystem context to locate companion PromptKit resources.
|
||
|
|
|
||
|
|
The desired workflow is one application-owned ConfigKit load. The application
|
||
|
|
passes the **entire resolved result** to PromptKit, which consumes only the fixed
|
||
|
|
root-level `promptkit` section. The application should not extract, serialize,
|
||
|
|
reshape, or reload that section, or reconstruct its resource contexts.
|
||
|
|
|
||
|
|
The resulting document can contain both sets of settings:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
version: 3
|
||
|
|
application:
|
||
|
|
output_directory: ./reports
|
||
|
|
promptkit:
|
||
|
|
schema_root: ./schemas
|
||
|
|
collections:
|
||
|
|
weatherreporter:
|
||
|
|
prompts:
|
||
|
|
- id: summarize.alerts
|
||
|
|
messages:
|
||
|
|
- role: user
|
||
|
|
content_file: ./messages/summary.md
|
||
|
|
output:
|
||
|
|
format: json
|
||
|
|
validation_mode: json_schema
|
||
|
|
schema_path: alerts.json
|
||
|
|
```
|
||
|
|
|
||
|
|
This is an illustrative target configuration, not current PromptKit syntax.
|
||
|
|
The fixed key is PromptKit's convention, not a proposed ConfigKit reserved key.
|
||
|
|
Applications retain source discovery, layering, imports, and override policy.
|
||
|
|
PromptKit retains its field rules and engine construction. ConfigKit retains
|
||
|
|
composition, effective field contexts, and inspection semantics.
|
||
|
|
|
||
|
|
## Verified Baseline
|
||
|
|
|
||
|
|
Assessment baseline: ConfigKit v1.3.0, commit
|
||
|
|
`652ddb649c60208dbba964f0ef919e36725c12c0`. Public-API offline diagnostics verified:
|
||
|
|
|
||
|
|
- A typed component field and an inline catch-all map can allow application
|
||
|
|
siblings while rejecting unknown fields inside the component.
|
||
|
|
- Application callbacks can default component values after composition;
|
||
|
|
registered identities can validate nested resource lists.
|
||
|
|
- Mounted fragments retain field origins and usable `SourceContext` information.
|
||
|
|
- `Explain` on the component path returns a redacted section snapshot.
|
||
|
|
- `WriteEffective` and `Diff` still operate on the whole result. A sibling-only
|
||
|
|
change produces a native difference outside the component.
|
||
|
|
- One shared source-version rule accepting application version 3 rejects a
|
||
|
|
PromptKit fragment declaring version 2.
|
||
|
|
|
||
|
|
The relevant public contracts are [definitions and results](../../lifecycle.go),
|
||
|
|
[resource contexts](../../resource_context.go), [inspection](../../inspection.go),
|
||
|
|
[metadata](../../metadata.go), [comparison](../../diff.go), and
|
||
|
|
[shared source-version checks](../config.md#shared-source-version-checks).
|
||
|
|
These findings establish partial feasibility, not a working whole-result
|
||
|
|
PromptKit integration.
|
||
|
|
|
||
|
|
## 1. Resolved Component Access And Scoped Inspection
|
||
|
|
|
||
|
|
Provide a public way for a library receiving the whole application result to
|
||
|
|
select its section for execution and inspection, independently of the application's
|
||
|
|
particular Go root type. It must retain the original load's effective values and
|
||
|
|
resource contexts without another configuration load or historical reconstruction.
|
||
|
|
|
||
|
|
Execution access must provide usable, trusted configuration values. Existing
|
||
|
|
redacted inspection YAML is not an execution input. Define ownership explicitly:
|
||
|
|
`Result.Config` is mutable while inspection describes a frozen snapshot today.
|
||
|
|
The new contract should state which values a consumer receives and how later
|
||
|
|
caller mutations relate to those values and their inspection evidence. This
|
||
|
|
request does not require all existing `Result.Config` values to become immutable.
|
||
|
|
|
||
|
|
For the selected section, support:
|
||
|
|
|
||
|
|
- Effective configuration output, with native redaction.
|
||
|
|
- Presence/origin queries, relevant history, and path enumeration.
|
||
|
|
- Explanations retaining full native paths such as
|
||
|
|
`/promptkit/collections/weatherreporter/prompts/0/output`.
|
||
|
|
- Comparison of the section between successful loads, retaining native sensitive
|
||
|
|
change semantics and excluding changes confined to sibling application values.
|
||
|
|
- Effective field context lookup so relative message and schema files keep the
|
||
|
|
filesystem and base directory of the source that contributed the field.
|
||
|
|
|
||
|
|
Define absent-section and explicit-null behavior, including comparisons where a
|
||
|
|
section is added or removed. A component view must not turn an absent section
|
||
|
|
into a new composition operation. Scope value-bearing reports and history so
|
||
|
|
selecting a component does not disclose unrelated sibling values through ancestor
|
||
|
|
records. Relevant source provenance remains useful; no requirement is made to hide
|
||
|
|
the existence of a shared source document.
|
||
|
|
|
||
|
|
This is a request for a native consumer boundary, not a guarantee about which
|
||
|
|
nodes ConfigKit may visit internally. Whole-result comparison followed by local
|
||
|
|
filtering can approximate the public diff, but leaves PromptKit maintaining
|
||
|
|
separate adapters for output, opaque metadata, history, and comparison.
|
||
|
|
|
||
|
|
## 2. Independent Source-Version Policies Within One Load
|
||
|
|
|
||
|
|
An application's main configuration and imported component collections can have
|
||
|
|
independent specification versions. For example, the application document above
|
||
|
|
uses `version: 3`, while a PromptKit collection can begin with:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
version: 2
|
||
|
|
prompts:
|
||
|
|
- id: summarize.alerts
|
||
|
|
messages:
|
||
|
|
- role: user
|
||
|
|
content: Summarize the supplied alerts.
|
||
|
|
output:
|
||
|
|
format: text
|
||
|
|
validation_mode: none
|
||
|
|
```
|
||
|
|
|
||
|
|
The application mounts that standalone collection beneath
|
||
|
|
`promptkit.collections.weatherreporter`. Its version declaration should be checked
|
||
|
|
against PromptKit's collection policy, not the application's version policy.
|
||
|
|
|
||
|
|
Provide public selection of the appropriate version policy for component sources
|
||
|
|
and their imports within the same load. Define the selection behavior for direct
|
||
|
|
inputs, transitive imports, and sources mounted at destinations. Policy assignment
|
||
|
|
must be explicit and independent of whether a declaration's numeric value happens
|
||
|
|
to match one checker; accepting both 2 and 3 everywhere does not meet this need.
|
||
|
|
|
||
|
|
Preserve optional declarations: a collection may omit its header, but a supplied
|
||
|
|
header must be checked under the applicable policy before composition consumes it.
|
||
|
|
Maintain ordinary final-value validation and native diagnostics. Header handling
|
||
|
|
must not let a collection overwrite the application's main version declaration.
|
||
|
|
The application must not preparse fragments, strip headers, or load collections
|
||
|
|
separately to achieve this behavior.
|
||
|
|
|
||
|
|
No particular selector syntax or internal routing mechanism is requested. An
|
||
|
|
application-owned document containing `promptkit` settings is still an application
|
||
|
|
document; it does not require two competing root version headers.
|
||
|
|
|
||
|
|
## 3. Demonstrate A Small Component Integration Contract
|
||
|
|
|
||
|
|
Please evaluate this complete consumer sequence alongside the requested APIs:
|
||
|
|
|
||
|
|
1. The application declares its own configuration type and includes PromptKit's
|
||
|
|
supported public settings/registration at `promptkit`.
|
||
|
|
2. It incorporates PromptKit-owned defaults, normalization, validation, sequence
|
||
|
|
identities, and sensitivity rules into its ordinary ConfigKit load. Desired
|
||
|
|
bundled resources enter as ordinary underlays before resolution.
|
||
|
|
3. ConfigKit loads and resolves the complete configuration once, applying the
|
||
|
|
application's rules and the component's rules in the supported lifecycle.
|
||
|
|
4. The application passes that whole result to PromptKit. PromptKit uses the
|
||
|
|
fixed section and original source contexts to capture resources and construct
|
||
|
|
its engine. It does not inject defaults through a second load.
|
||
|
|
5. PromptKit delegates its configuration reports and comparisons to the native
|
||
|
|
scoped inspection capability.
|
||
|
|
|
||
|
|
Existing `Definition[T]` callbacks may be sufficient with a small library helper.
|
||
|
|
A new component registry is **not** a prerequisite of this request. Please show
|
||
|
|
how component rules can be composed with an application-owned root type without
|
||
|
|
the application reproducing those rules or depending on the library's internal
|
||
|
|
types. If a public extension is needed, keep it limited to the demonstrated gap.
|
||
|
|
The section handoff should not require a per-application extraction adapter.
|
||
|
|
|
||
|
|
## Acceptance Scenarios
|
||
|
|
|
||
|
|
- One load contains application fields and a typed PromptKit section; unrelated
|
||
|
|
fields are governed by the application, while invalid component fields fail.
|
||
|
|
- Component defaulting, normalization, identities, and sensitivity run through
|
||
|
|
the normal lifecycle and remain visible in the resolved result and inspection.
|
||
|
|
- Whole-result handoff works with an application-owned Go configuration type,
|
||
|
|
with no section serialization/reload or source-context reconstruction.
|
||
|
|
- Embedded and operator collection fragments retain relative-file contexts after
|
||
|
|
mounting, inheritance, and overrides, including identical file basenames.
|
||
|
|
- Component execution access preserves values needed for execution, while public
|
||
|
|
inspection redacts sensitive values. Ownership/mutation behavior is documented.
|
||
|
|
- Sibling-only changes do not appear in component comparisons; component changes,
|
||
|
|
sensitive changes, and section addition/removal follow native reporting rules.
|
||
|
|
- Application version 3 and PromptKit collection version 2 coexist under their
|
||
|
|
respective policies; each rejects unsupported declarations independently.
|
||
|
|
Headerless collections and transitive imports exercise the selected policies.
|
||
|
|
|
||
|
|
PromptKit's repair-default change and its domain-specific validation rules are
|
||
|
|
outside this upstream request. No changes to ConfigKit's internal representation,
|
||
|
|
algorithms, or package layout are proposed. Please distinguish capabilities already
|
||
|
|
available through a concise public example from those needing new public APIs.
|