Document prompt-owned schemas and finalize migration
This commit is contained in:
@@ -83,20 +83,25 @@ promptInputs, err := promptkit.DirectoryInputs("prompts")
|
||||
if err != nil { return err }
|
||||
profileInputs, err := promptkit.DirectoryInputs("profiles")
|
||||
if err != nil { return err }
|
||||
filesystem := configkit.NewFilesystem("application schemas", os.DirFS("."))
|
||||
schemaInput := configkit.Input{
|
||||
Source: promptkit.SchemaRootSource("application schemas", "schemas"),
|
||||
Filesystem: &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."},
|
||||
}
|
||||
engine, err := promptkit.NewEngine(promptkit.Config{
|
||||
Sources: promptkit.ConfigurationSources{Underlays: []configkit.Underlay{
|
||||
{Inputs: promptInputs},
|
||||
{Inputs: profileInputs},
|
||||
{Inputs: []configkit.Input{schemaInput}},
|
||||
}},
|
||||
SchemaDir: "schemas",
|
||||
})
|
||||
```
|
||||
|
||||
For a single highest-priority document, set `Sources.Main` to a
|
||||
`*configkit.Input`; omit it for ordinary layered construction. A single file
|
||||
can use `configkit.File` directly. `PromptSource`, `ProfileSource`, `BackendSource`, and raw
|
||||
`configkit.Mapping` supply programmatic definitions. Schema and runtime
|
||||
collaborator options remain available. Construction validates the final
|
||||
`configkit.Mapping` supply programmatic definitions. Runtime collaborator
|
||||
options remain available. Construction validates the final
|
||||
effective configuration and captures referenced prompt content; construct a
|
||||
new engine to observe configuration edits. See the [constructor GoDoc](../../engine.go)
|
||||
for the exact public contract and the [framework format reference](../formats.md)
|
||||
@@ -705,7 +710,7 @@ corrected automatically:
|
||||
request.Validation = &promptkit.OutputContract{
|
||||
Format: promptkit.FormatJSON,
|
||||
ValidationMode: promptkit.ValidationJSONSchema,
|
||||
SchemaPath: "events.schema.json",
|
||||
Schema: map[string]any{"type": "object"},
|
||||
RepairAttempts: 1,
|
||||
}
|
||||
```
|
||||
@@ -1119,10 +1124,20 @@ secret-handling policies.
|
||||
## Extension Interfaces
|
||||
|
||||
JSON Schema validation and native structured output use a self-contained root
|
||||
document. Internal references are supported; references to other files or
|
||||
network resources fail during preparation. `WithSchemaFile` selects one root
|
||||
file, while `WithSchemaFS` and `SchemaDir` select a root source. Prepared
|
||||
executions retain their captured schema even if the source later changes.
|
||||
document. See [schema selection and resource context](../formats.md#schemas).
|
||||
Prepared executions retain their captured schema even if the source later changes.
|
||||
|
||||
### Migrating Schema Sources
|
||||
|
||||
`Config.SchemaDir`, `WithSchemaFS`, and `WithSchemaFile` have been removed.
|
||||
Supply a context-backed `SchemaRootSource` at the desired ConfigKit layer, as
|
||||
shown above, or declare `schema_root` in application or collection mappings.
|
||||
For a former single-file source, configure `schema_file` relative to its
|
||||
contributing source, or supply its directory as a root and use its basename in
|
||||
`schema_path`. To substitute an unrelated file per request, read and decode it
|
||||
in the caller and supply its value as `OutputContract.Schema`. There is no
|
||||
implicit working-directory root. Public structs gained fields; change any
|
||||
positional struct literals to keyed literals when migrating.
|
||||
|
||||
Inject an [`LLMClient` or `ArtifactReader`](../../types.go) when the built-in
|
||||
behavior does not fit the application. Their GoDoc defines concurrent use,
|
||||
|
||||
@@ -201,11 +201,19 @@ messages; the integration contract defines its wire representation.
|
||||
| --- | --- | --- |
|
||||
| `format` | yes | `text`, `markdown`, or `json` |
|
||||
| `validation_mode` | yes | `none`, `basic`, `json`, or `json_schema` |
|
||||
| `schema_path` | for `json_schema` | Path in the selected schema source |
|
||||
| `schema` | one selection for `json_schema` | Inline JSON Schema value |
|
||||
| `schema_file` | one selection for `json_schema` | File relative to the contributing field's source context |
|
||||
| `schema_path` | one selection for `json_schema` | Path within the applicable explicit schema root |
|
||||
| `repair_attempts` | no | Integer 0–3; default 0. Positive values need `basic`, `json`, or `json_schema` |
|
||||
|
||||
`none` skips content validation; `basic` requires nonempty content; `json`
|
||||
accepts any valid JSON value; `json_schema` checks the selected schema.
|
||||
In `json_schema` mode exactly one nonnull `schema`, `schema_file`, or
|
||||
`schema_path` must be selected. Null clears a selection; `false`, `true`, and
|
||||
`{}` are values. Blank references are invalid. Other modes ignore these fields
|
||||
for schema selection and loading. ConfigKit composes inline mappings normally;
|
||||
switching forms can require explicitly clearing an inherited alternative.
|
||||
Replacing an identified prompt record replaces its complete earlier record.
|
||||
`format` determines output artifact metadata. JSON Schema mode also supplies
|
||||
structured-output metadata to compatible clients. Plain `json` does not
|
||||
request a provider-native JSON-object constraint. A positive repair budget
|
||||
@@ -433,14 +441,31 @@ generic inheritance and layer mechanics, consult
|
||||
|
||||
## Schemas
|
||||
|
||||
Schemas are JSON documents selected by a prompt or request `schema_path`.
|
||||
Directory and `fs.FS` schema paths resolve within the configured root. Each
|
||||
schema must be self-contained: in-document references, IDs, and anchors are
|
||||
Schemas can be inline, source-relative files, or files under an explicit root.
|
||||
An optional `schema_root` may be set at the application root and in each
|
||||
collection. A collection's nonnull root takes precedence over the application
|
||||
root for its prompts; an absent or null collection root falls back to the
|
||||
application root. A nonnull blank root is invalid. There is no implicit
|
||||
working-directory root. Roots and `schema_file` references resolve using the
|
||||
effective field's contributing ConfigKit filesystem and base directory;
|
||||
missing usable context is a configuration error. An explicit `.` is valid
|
||||
with usable context. A `schema_path` requires an applicable root. Root choice
|
||||
is made before reading: a missing file never triggers another-root search.
|
||||
Schema selection and context are captured during construction without reading
|
||||
schema files. Files are read and compiled during preparation; a missing,
|
||||
malformed, or unresolvable file is an operational validation error. Inline
|
||||
configuration values follow native ConfigKit composition and null handling.
|
||||
For request-level replacement, inline `Schema` needs no root and `SchemaPath`
|
||||
uses the selected prompt's applicable root. A replacement does not inherit the
|
||||
configured schema selection or `schema_file` context.
|
||||
Runtime inline values are encoded as JSON before preparation; file-backed JSON
|
||||
uses the existing number-preserving decoder. No additional numerical equivalence
|
||||
between input representations is implied.
|
||||
|
||||
Each schema must be self-contained: in-document references, IDs, and anchors are
|
||||
supported, but references requiring another file or network resource fail.
|
||||
References must also work without the source filename as a base; use fragment
|
||||
references or explicit schema IDs rather than relying on that filename.
|
||||
`WithSchemaFile` exposes one schema under its base name. An unreadable,
|
||||
invalid, or unresolvable schema causes an operational validation error.
|
||||
Valid JSON that fails the schema instead yields a failed validation result.
|
||||
Schema documents are detached without applying the provider extra-parameter
|
||||
copy limits; this does not change the schema decoder, compiler, or
|
||||
|
||||
@@ -28,7 +28,7 @@ contributor workflow and validation.
|
||||
| `internal/profile` | Provides a narrow captured-profile lookup contract and not-found identity. | [Profile lookup](../../internal/profile/repository.go), [framework formats](../formats.md) |
|
||||
| `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data, and conservatively enumerates dependencies from captured template syntax. | [Go-template renderer](../../internal/prompt/go_renderer.go), [requirement discovery](../../internal/prompt/requirements.go) |
|
||||
| `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) |
|
||||
| `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources and creates operation-local validation plans with canonical contained schema resources. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
|
||||
| `internal/validate` | Creates operation-local validation plans from inline schema documents or bound filesystem resources and validates basic, JSON, and JSON Schema output. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
|
||||
| `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including bounded response decoding, authentication, deadline handling, per-invocation HTTP evidence and built-in diagnostic probes, and ownership of the OpenAI-compatible reserved request-field policy. | [Internal model client](llm.md) |
|
||||
| `internal/observation` | Owns invocation-local run IDs, presence-aware usage and phase accounting, synchronous metadata event delivery and composition, and explicit terminal-based group aggregation; smoke diagnostics keep their private evidence outside ordinary observer events. | [Internal execution observation](observation.md) |
|
||||
| `internal/usecase` | Selects captured prompts and profiles, enumerates requirements from captured prompt syntax, applies request overrides and completion checks, coordinates ordinary and single-claim prepared execution across rendering, artifact loading, operation-local validation plans, generation, capacity, and bounded repair, advances a single conversation branch, and runs explicit smoke diagnostics with private cases, shared generation/capacity, and optional built-in HTTP probes. | [Internal runner](runner.md), [requirement inspection](../../internal/usecase/requirements_inspection.go), [prepared-execution implementation](../../internal/usecase/prepared_execution.go) |
|
||||
|
||||
@@ -126,12 +126,12 @@ performs only the work needed to validate routing and admission:
|
||||
|
||||
1. validate the required prompt selection and normalize any direct session ID;
|
||||
2. select the captured prompt definition and hash;
|
||||
3. select the request profile or the prompt's default profile;
|
||||
4. retain the profile's selected backend identity, when present;
|
||||
5. apply explicit request overrides to its captured backend-completed target;
|
||||
6. validate endpoint, model, numeric overrides, and credential requirements;
|
||||
7. resolve and validate the effective output contract without loading its
|
||||
schema; and
|
||||
3. resolve and validate the effective output contract and select its applicable
|
||||
bound file without loading its schema;
|
||||
4. select the request profile or the prompt's default profile;
|
||||
5. retain the profile's selected backend identity, when present;
|
||||
6. apply explicit request overrides to its captured backend-completed target;
|
||||
7. validate endpoint, model, numeric overrides, and credential requirements; and
|
||||
8. retain the definition, source identities, effective settings, output
|
||||
contract, and preparation start time in invocation-local state.
|
||||
|
||||
|
||||
@@ -86,7 +86,10 @@ returning and retains no source capability for public inspection.
|
||||
Prompt materialization shares a lazy metadata snapshot across root and collection
|
||||
resources during construction, avoiding a full metadata copy per collection.
|
||||
Input metadata, message content and templates, and output contracts are captured
|
||||
separately before the definition, inspection, and hash are assembled.
|
||||
separately before the definition, inspection, and hash are assembled. Schema
|
||||
root and source-relative file bindings capture the effective field context
|
||||
without opening schema files; capabilities are excluded from the hash. Inline
|
||||
schema values and file-reference strings participate in the definition hash.
|
||||
|
||||
Normalization and defaults are recorded at individual resolved field paths,
|
||||
including message roles and cache controls. List indexes identify fields for
|
||||
@@ -212,18 +215,20 @@ buffer-to-string copy. The
|
||||
|
||||
## Schemas And Output Validation
|
||||
|
||||
`internal/validate` provides validators backed by an operating-system
|
||||
filesystem or an `fs.FS`. Invalid generated content is returned as a validation
|
||||
`internal/validate` prepares a source-neutral input containing an output contract
|
||||
and an optional bound `fs.FS` file. Invalid generated content is returned as a validation
|
||||
result; inability to load, register, or compile a schema is an operational
|
||||
error. Basic validation checks body emptiness on the byte slice directly
|
||||
instead of first making a response-sized string copy.
|
||||
|
||||
Every preparation operation creates one operation-local validation plan. None,
|
||||
basic, and JSON modes retain the effective output contract without source
|
||||
access. JSON Schema mode loads the root document once, compiles its declared
|
||||
access. JSON Schema mode uses the captured inline document or loads the bound
|
||||
root document once, compiles its declared
|
||||
schema locations, and retains the compiled root validator. External resources
|
||||
are rejected without file or network loading; in-document references remain
|
||||
supported. Root resources use canonical escaped file or private-scheme URLs. The
|
||||
supported. Bound files use canonical escaped private-scheme URLs; inline values
|
||||
use a stable private retrieval URL. The
|
||||
provider-facing structured-output metadata uses the root document captured by
|
||||
the same plan. Its detached schema document is not revalidated against the
|
||||
runtime provider-value copier's traversal limits. Smoke inference uses a
|
||||
|
||||
@@ -372,6 +372,8 @@ covered end to end without application-managed mounts or live infrastructure.
|
||||
|
||||
## Stage 8 — Migrate Documentation And Validate The Assembled Sprint
|
||||
|
||||
Status: complete.
|
||||
|
||||
1. Update GoDoc and [formats.md](../formats.md) for selection/null/composition,
|
||||
source context, root scope, inactive modes, preparation failures, and removed
|
||||
implicit root. Update the [consumer guide](../consumers/pkg-promptkit.md) with
|
||||
|
||||
Reference in New Issue
Block a user