From e9a12d43c2c8a7f3492d50ad6e8c64dece8e74a8 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 15:46:39 +0000 Subject: [PATCH] Document prompt-owned schemas and finalize migration --- docs/consumers/pkg-promptkit.md | 31 ++++-- docs/formats.md | 37 ++++++-- docs/internal/overview.md | 2 +- docs/internal/runner.md | 12 +-- docs/internal/sources.md | 15 ++- docs/roadmap/implementation.md | 2 + engine.go | 6 +- examples/go-library/observe/main.go | 4 +- .../observe/prompts/assessment.yaml | 9 +- .../observe/schemas/assessment.schema.json | 10 -- internal/jsonvalue/trusted.go | 94 ++++++++----------- internal/jsonvalue/trusted_test.go | 10 ++ output_contract_contract_test.go | 21 +++++ prompts.go | 8 +- resource_inspection.go | 4 +- types.go | 15 ++- 16 files changed, 174 insertions(+), 106 deletions(-) delete mode 100644 examples/go-library/observe/schemas/assessment.schema.json diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index 0fd4c7f..2838cbb 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -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, diff --git a/docs/formats.md b/docs/formats.md index 4740bba..4a6f438 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -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 diff --git a/docs/internal/overview.md b/docs/internal/overview.md index acc054a..dddeb1c 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -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) | diff --git a/docs/internal/runner.md b/docs/internal/runner.md index b5a2692..37b4c67 100644 --- a/docs/internal/runner.md +++ b/docs/internal/runner.md @@ -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. diff --git a/docs/internal/sources.md b/docs/internal/sources.md index 12832d9..a30cd1d 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 4693523..88a6512 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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 diff --git a/engine.go b/engine.go index c5b9cda..ff4c8aa 100644 --- a/engine.go +++ b/engine.go @@ -253,13 +253,13 @@ func NewEngine(cfg Config, opts ...Option) (*Engine, error) { // unrendered messages are returned in definition order. DefaultProfileID is // declared metadata only and is not // resolved. OutputContract is the normalized declared contract, with a JSON -// Schema path when declared but without loading or compiling that schema. +// Schema selection when declared but without loading or compiling schema files. // PromptHash is the same opaque equality value as PreparedRun.PromptHash for // the selected captured definition; its spelling, length, // encoding, algorithm, and security properties are not contracts. // -// This method does not return parsed templates, source paths, schemas, -// rendered messages, or execution settings. It does not resolve a profile or +// This method does not return parsed templates, filesystem capabilities, +// schema file contents, rendered messages, or execution settings. It does not resolve a profile or // credential, read artifacts or schemas, render, validate, admit capacity, // contact a provider, or generate model output. The returned PromptInspection // and its input slice are caller-owned. Inspection does not reload configuration diff --git a/examples/go-library/observe/main.go b/examples/go-library/observe/main.go index 80fe960..2c7f50b 100644 --- a/examples/go-library/observe/main.go +++ b/examples/go-library/observe/main.go @@ -91,9 +91,11 @@ func run() (summary, error) { return summary{}, err } backendID, proposalModel, assessmentModel := "offline-backend", "proposal-model", "assessment-model" + filesystem := configkit.NewFilesystem("example schemas", assets) backend := promptkit.LocalBackend("https://example.invalid/v1", 1) backend.ID = backendID inputs = append(inputs, + configkit.Input{Source: promptkit.SchemaRootSource("example schemas", "schemas"), Filesystem: &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."}}, configkit.Input{Source: promptkit.BackendSource("example backend", []promptkit.BackendConfig{ backend, })}, @@ -105,7 +107,7 @@ func run() (summary, error) { engine, err := promptkit.NewEngine(promptkit.Config{ Sources: promptkit.ConfigurationSources{Underlays: []configkit.Underlay{{Inputs: inputs}}}, HTTPClient: &http.Client{Transport: transport}, - }, promptkit.WithBundledOpenRouter(false), promptkit.WithSchemaFS(assets, "schemas")) // Keep the example's configuration self-contained. + }, promptkit.WithBundledOpenRouter(false)) // Keep the example's configuration self-contained. if err != nil { return summary{}, err } diff --git a/examples/go-library/observe/prompts/assessment.yaml b/examples/go-library/observe/prompts/assessment.yaml index 285720f..9ba40e5 100644 --- a/examples/go-library/observe/prompts/assessment.yaml +++ b/examples/go-library/observe/prompts/assessment.yaml @@ -14,4 +14,11 @@ prompts: output: format: json validation_mode: json_schema - schema_path: assessment.schema.json + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: [recommendation, confidence] + properties: + recommendation: {type: string} + confidence: {type: number} + additionalProperties: false diff --git a/examples/go-library/observe/schemas/assessment.schema.json b/examples/go-library/observe/schemas/assessment.schema.json deleted file mode 100644 index b74adfe..0000000 --- a/examples/go-library/observe/schemas/assessment.schema.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "type": "object", - "required": ["recommendation", "confidence"], - "properties": { - "recommendation": {"type": "string"}, - "confidence": {"type": "number"} - }, - "additionalProperties": false -} diff --git a/internal/jsonvalue/trusted.go b/internal/jsonvalue/trusted.go index d2e0234..41826c5 100644 --- a/internal/jsonvalue/trusted.go +++ b/internal/jsonvalue/trusted.go @@ -2,93 +2,73 @@ package jsonvalue import "reflect" -func cloneTrustedMap(src map[string]any) map[string]any { - if src == nil { - return nil - } - out := make(map[string]any, len(src)) - for k, v := range src { - out[k] = CloneTrusted(v) - } - return out +type cloneReference struct { + typeOf reflect.Type + pointer uintptr + length int } // CloneTrusted detaches a previously accepted value without revalidating it. +// Cyclic values can also occur in inactive, uninterpreted request fields. func CloneTrusted(value any) any { if value == nil { return nil } - switch v := value.(type) { - case map[string]any: - return cloneTrustedMap(v) - case []any: - out := make([]any, len(v)) - for i, item := range v { - out[i] = CloneTrusted(item) - } - return out - case []string: - if v == nil { - return []string(nil) - } - return append([]string{}, v...) - case []byte: - if v == nil { - return []byte(nil) - } - return append([]byte{}, v...) - default: - return cloneTrustedReflect(reflect.ValueOf(value)).Interface() - } + return cloneTrustedReflect(reflect.ValueOf(value), make(map[cloneReference]reflect.Value)).Interface() } -func cloneTrustedReflect(value reflect.Value) reflect.Value { +func cloneTrustedReflect(value reflect.Value, active map[cloneReference]reflect.Value) reflect.Value { if !value.IsValid() { return value } - switch value.Kind() { case reflect.Interface: if value.IsNil() { return reflect.Zero(value.Type()) } - copied := cloneTrustedReflect(value.Elem()) - if copied.IsValid() && copied.Type().AssignableTo(value.Type()) { - return copied - } out := reflect.New(value.Type()).Elem() - out.Set(copied) + out.Set(cloneTrustedReflect(value.Elem(), active)) return out - case reflect.Pointer: + case reflect.Pointer, reflect.Map, reflect.Slice: if value.IsNil() { return reflect.Zero(value.Type()) } - out := reflect.New(value.Type().Elem()) - out.Elem().Set(cloneTrustedReflect(value.Elem())) - return out - case reflect.Map: - if value.IsNil() { - return reflect.Zero(value.Type()) + key := cloneReference{typeOf: value.Type(), pointer: uintptr(value.UnsafePointer())} + if value.Kind() == reflect.Slice { + key.length = value.Len() } - out := reflect.MakeMapWithSize(value.Type(), value.Len()) - iter := value.MapRange() - for iter.Next() { - out.SetMapIndex(cloneTrustedReflect(iter.Key()), cloneTrustedReflect(iter.Value())) + if existing, found := active[key]; found { + return existing } - return out - case reflect.Slice: - if value.IsNil() { - return reflect.Zero(value.Type()) + var out reflect.Value + switch value.Kind() { + case reflect.Pointer: + out = reflect.New(value.Type().Elem()) + case reflect.Map: + out = reflect.MakeMapWithSize(value.Type(), value.Len()) + case reflect.Slice: + out = reflect.MakeSlice(value.Type(), value.Len(), value.Cap()) } - out := reflect.MakeSlice(value.Type(), value.Len(), value.Cap()) - for i := 0; i < value.Len(); i++ { - out.Index(i).Set(cloneTrustedReflect(value.Index(i))) + active[key] = out + defer delete(active, key) + switch value.Kind() { + case reflect.Pointer: + out.Elem().Set(cloneTrustedReflect(value.Elem(), active)) + case reflect.Map: + iter := value.MapRange() + for iter.Next() { + out.SetMapIndex(cloneTrustedReflect(iter.Key(), active), cloneTrustedReflect(iter.Value(), active)) + } + case reflect.Slice: + for i := 0; i < value.Len(); i++ { + out.Index(i).Set(cloneTrustedReflect(value.Index(i), active)) + } } return out case reflect.Array: out := reflect.New(value.Type()).Elem() for i := 0; i < value.Len(); i++ { - out.Index(i).Set(cloneTrustedReflect(value.Index(i))) + out.Index(i).Set(cloneTrustedReflect(value.Index(i), active)) } return out default: diff --git a/internal/jsonvalue/trusted_test.go b/internal/jsonvalue/trusted_test.go index 21bd55c..db9d5ac 100644 --- a/internal/jsonvalue/trusted_test.go +++ b/internal/jsonvalue/trusted_test.go @@ -25,3 +25,13 @@ func TestCloneTrustedPreservesTypesAndDetaches(t *testing.T) { t.Fatal("nil/empty shape changed") } } + +func TestCloneTrustedDetachesCycles(t *testing.T) { + original := map[string]any{} + original["self"] = original + copy := CloneTrusted(original).(map[string]any) + copy["self"].(map[string]any)["changed"] = true + if copy["changed"] != true || original["changed"] != nil { + t.Fatal("cyclic copy did not preserve its cycle independently") + } +} diff --git a/output_contract_contract_test.go b/output_contract_contract_test.go index 2371c17..9cbb102 100644 --- a/output_contract_contract_test.go +++ b/output_contract_contract_test.go @@ -10,11 +10,17 @@ import ( func TestPreparationRejectsInvalidOutputContractWithPublicError(t *testing.T) { engine := newSimpleEngine(t, "message") + cycle := map[string]any{} + cycle["self"] = cycle for _, tc := range []struct { name string contract promptkit.OutputContract }{ + { + name: "cyclic inline schema", + contract: promptkit.OutputContract{Format: promptkit.FormatJSON, ValidationMode: promptkit.ValidationJSONSchema, Schema: cycle}, + }, { name: "inline schema cannot be encoded", contract: promptkit.OutputContract{ @@ -67,3 +73,18 @@ func TestPreparationRejectsInvalidOutputContractWithPublicError(t *testing.T) { }) } } + +func TestInactiveSchemaDoesNotInterpretCyclicValue(t *testing.T) { + cycle := map[string]any{} + cycle["self"] = cycle + engine := newSimpleEngine(t, "message") + prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{PromptID: "prompt", Validation: &promptkit.OutputContract{Format: promptkit.FormatText, ValidationMode: promptkit.ValidationNone, Schema: cycle}}) + if err != nil { + t.Fatal(err) + } + copy := prepared.OutputContract.Schema.(map[string]any) + copy["self"].(map[string]any)["changed"] = true + if copy["changed"] != true || cycle["changed"] != nil { + t.Fatal("inactive schema copy shares caller storage") + } +} diff --git a/prompts.go b/prompts.go index a4db48e..2ac0cc1 100644 --- a/prompts.go +++ b/prompts.go @@ -37,7 +37,9 @@ type PromptMessageConfig struct { // PromptCacheControlConfig supplies optional cache-control source fields. type PromptCacheControlConfig struct{ Type, TTL *string } -// PromptOutputConfig supplies optional output contract source fields. +// PromptOutputConfig supplies optional output contract source fields. Schema +// supplies a nonnull inline value, and SchemaFile and SchemaPath are reference +// selections. Raw ConfigKit mappings can express explicit null to clear one. type PromptOutputConfig struct { Format, ValidationMode, SchemaPath, SchemaFile *string Schema any @@ -45,6 +47,8 @@ type PromptOutputConfig struct { } // SchemaRootSource supplies a schema root as a native configuration mapping. +// The caller chooses the input layer and supplies its filesystem context. The +// helper neither validates the value nor opens resources. func SchemaRootSource(label, root string) configkit.Source { return configkit.Mapping(label, map[string]any{"schema_root": root}) } @@ -54,7 +58,7 @@ func SchemaRootSource(label, root string) configkit.Source { // sibling inheritance and layered sources can complete them before NewEngine // validates the final configuration. Mapping snapshots supported values when // constructed; the helper neither resolves inheritance nor reads files. -// Relative content files use the ConfigKit Input filesystem context of the +// Relative content and schema files use the ConfigKit Input filesystem context of the // contributing field. Raw mappings remain available for explicit null and // generic ConfigKit operations. func PromptSource(label string, prompts []PromptConfig) configkit.Source { diff --git a/resource_inspection.go b/resource_inspection.go index 310ca81..9b14ca8 100644 --- a/resource_inspection.go +++ b/resource_inspection.go @@ -75,8 +75,8 @@ type PromptCacheControlInspection struct { TTL *string `json:"ttl,omitempty" yaml:"ttl,omitempty"` } -// PromptOutputInspection describes a prompt's output contract. SchemaPath is -// a reference and is not loaded by inspection. +// PromptOutputInspection describes a prompt's configured output contract. +// SchemaFile and SchemaPath are references and are not loaded by inspection. type PromptOutputInspection struct { Format OutputFormat `json:"format" yaml:"format"` ValidationMode ValidationMode `json:"validation_mode" yaml:"validation_mode"` diff --git a/types.go b/types.go index 36ac32c..97f0477 100644 --- a/types.go +++ b/types.go @@ -39,7 +39,7 @@ const ( ValidationBasic ValidationMode = "basic" // ValidationJSON requires syntactically valid JSON. ValidationJSON ValidationMode = "json" - // ValidationJSONSchema requires JSON that satisfies OutputContract.SchemaPath. + // ValidationJSONSchema requires JSON satisfying the selected schema. ValidationJSONSchema ValidationMode = "json_schema" ) @@ -494,7 +494,11 @@ type ExecutionTargetPresence struct { // // A non-nil RunRequest.Validation replaces the complete prompt contract. It // does not merge fields. The public Engine performs bounded correction after a -// failed eligible validation when RepairAttempts is positive. +// failed eligible validation when RepairAttempts is positive. A JSON Schema +// request replacement requires exactly one of Schema and SchemaPath; other +// modes ignore them. A replacement uses the prompt's configured root for +// SchemaPath. For a configured source-relative file, prepared output contracts +// expose neither selection; StructuredOutput contains the selected document. type OutputContract struct { // Format selects generated artifact metadata. An empty value in a non-nil // request replacement defaults to FormatText. @@ -502,7 +506,9 @@ type OutputContract struct { // ValidationMode selects the content check. Use one of the declared // ValidationMode constants. ValidationMode ValidationMode `json:"validation_mode"` - // Schema supplies an inline JSON Schema. Nil means no inline selection. + // Schema supplies an inline JSON Schema. Nil or a value encoding as JSON + // null means no selection; false and an empty object are selections. In + // JSON Schema mode the value must be JSON-encodable. Schema any `json:"schema,omitempty"` // SchemaPath identifies a schema under the applicable configured root. SchemaPath string `json:"schema_path"` @@ -522,7 +528,8 @@ type ValidationResult struct { Mode ValidationMode `json:"mode"` // Errors contains validation diagnostics when Status is ValidationFailed. Errors []string `json:"errors,omitempty"` - // SchemaPath is the effective schema path for JSON Schema validation. + // SchemaPath is the explicit-root path for JSON Schema validation. It is + // empty for inline and source-relative schema selections. SchemaPath string `json:"schema_path,omitempty"` // RepairAttempts is the number of corrective generation calls actually // started for this result.