From fbe3d427a22d68c220813faa39e29b8e23f1ef5b Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 15:20:29 +0000 Subject: [PATCH] Add schema selection values and ownership --- convert.go | 2 ++ docs/roadmap/implementation.md | 2 ++ internal/configuration/load.go | 2 ++ internal/configuration/prompts.go | 9 ++++++ internal/configuration/resources.go | 2 ++ internal/domain/domain.go | 11 +++++++ internal/domain/output_contract.go | 22 ++++++++++++-- internal/domain/output_contract_test.go | 31 ++++++++++++++++++++ internal/usecase/output_contract_test.go | 20 +++++++++++++ internal/usecase/runner.go | 11 +++++-- internal/validate/standard_validator.go | 9 ++++++ internal/validate/validator.go | 6 ++++ output_contract_contract_test.go | 7 +++++ prompt_sources_contract_test.go | 37 ++++++++++++++++++++++++ prompts.go | 17 +++++++++-- resource_inspection.go | 2 ++ types.go | 5 ++-- 17 files changed, 186 insertions(+), 9 deletions(-) diff --git a/convert.go b/convert.go index 30938bb..9dbf4e5 100644 --- a/convert.go +++ b/convert.go @@ -330,6 +330,7 @@ func toDomainOutputContract(contract OutputContract) domain.OutputContract { return domain.OutputContract{ Format: domain.OutputFormat(contract.Format), ValidationMode: domain.ValidationMode(contract.ValidationMode), + Schema: contract.Schema, SchemaPath: contract.SchemaPath, RepairAttempts: contract.RepairAttempts, } @@ -339,6 +340,7 @@ func fromDomainOutputContract(contract domain.OutputContract) OutputContract { return OutputContract{ Format: OutputFormat(contract.Format), ValidationMode: ValidationMode(contract.ValidationMode), + Schema: jsonvalue.CloneTrusted(contract.Schema), SchemaPath: contract.SchemaPath, RepairAttempts: contract.RepairAttempts, } diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index b0c329e..2529c34 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -139,6 +139,8 @@ not a list to search. Root selection happens before opening the requested file. ## Stage 1 — Add Schema Value Shapes And Ownership +Status: complete. + Read `types.go`, `prompts.go`, `resource_inspection.go`, `convert.go`, domain output contracts, and the existing schema-document ownership/decoder helpers. diff --git a/internal/configuration/load.go b/internal/configuration/load.go index fd0c5dc..a189e07 100644 --- a/internal/configuration/load.go +++ b/internal/configuration/load.go @@ -103,6 +103,8 @@ type cacheControlConfig struct { type promptOutputConfig struct { Format *string `yaml:"format"` ValidationMode *string `yaml:"validation_mode"` + Schema any `yaml:"schema"` + SchemaFile *string `yaml:"schema_file"` SchemaPath *string `yaml:"schema_path"` RepairAttempts int `yaml:"repair_attempts"` } diff --git a/internal/configuration/prompts.go b/internal/configuration/prompts.go index 50cb65b..0f40d63 100644 --- a/internal/configuration/prompts.go +++ b/internal/configuration/prompts.go @@ -11,6 +11,7 @@ import ( "go.maximumdirect.net/configkit" "go.maximumdirect.net/promptkit/internal/domain" "go.maximumdirect.net/promptkit/internal/filecatalog" + "go.maximumdirect.net/promptkit/internal/jsonvalue" "go.maximumdirect.net/promptkit/internal/prompt" "go.maximumdirect.net/promptkit/internal/promptdef" ) @@ -273,6 +274,7 @@ func (state *loaded) lookupPromptEntry(id string) (*promptEntry, error) { } func ownPromptDefinition(definition domain.PromptDefinition) *domain.PromptDefinition { + definition.Validation = ownOutputContract(definition.Validation) definition.Inputs = append([]domain.PromptInput(nil), definition.Inputs...) definition.Templates = append([]domain.PromptMessageTemplate(nil), definition.Templates...) for index := range definition.Templates { @@ -285,10 +287,17 @@ func ownPromptDefinition(definition domain.PromptDefinition) *domain.PromptDefin } func ownPromptInspection(inspection domain.PromptInspection) *domain.PromptInspection { + inspection.OutputContract = ownOutputContract(inspection.OutputContract) inspection.Inputs = append([]domain.PromptInput(nil), inspection.Inputs...) return &inspection } +func ownOutputContract(contract domain.OutputContract) domain.OutputContract { + contract.Schema = jsonvalue.CloneTrusted(contract.Schema) + contract.SchemaFile = stringPointerValue(contract.SchemaFile) + return contract +} + func promptLookupError(err error) error { if errors.Is(err, errPromptNotFound) { return promptdef.ErrPromptDefinitionNotFound diff --git a/internal/configuration/resources.go b/internal/configuration/resources.go index 197e9a3..205d76a 100644 --- a/internal/configuration/resources.go +++ b/internal/configuration/resources.go @@ -60,6 +60,8 @@ type PromptCacheControlResource struct { type PromptOutputResource struct { Format domain.OutputFormat ValidationMode domain.ValidationMode + Schema any + SchemaFile *string SchemaPath *string RepairAttempts *int } diff --git a/internal/domain/domain.go b/internal/domain/domain.go index 0b513f3..e835d89 100644 --- a/internal/domain/domain.go +++ b/internal/domain/domain.go @@ -2,6 +2,7 @@ package domain import ( "context" + "io/fs" "time" ) @@ -156,6 +157,8 @@ type PromptDefinition struct { Inputs []PromptInput `yaml:"inputs"` Templates []PromptMessageTemplate `yaml:"templates"` Validation OutputContract `yaml:"validation"` + SchemaRoot *ResourceBinding `json:"-" yaml:"-"` + SchemaFile *ResourceBinding `json:"-" yaml:"-"` } // PromptInspection is lightweight metadata for prompt requirement selection. @@ -253,10 +256,18 @@ type ExecutionTarget struct { type OutputContract struct { Format OutputFormat `yaml:"format"` ValidationMode ValidationMode `yaml:"validation_mode"` + Schema any `yaml:"schema,omitempty" json:"schema,omitempty"` + SchemaFile *string `yaml:"schema_file,omitempty" json:"schema_file,omitempty"` SchemaPath string `yaml:"schema_path"` RepairAttempts int `yaml:"repair_attempts"` } +// ResourceBinding identifies a resource in its originating filesystem. +type ResourceBinding struct { + FS fs.FS + Path string +} + // RenderedPrompt represents the prompt after template application. type RenderedPrompt struct { SessionID string `json:"session_id,omitempty"` diff --git a/internal/domain/output_contract.go b/internal/domain/output_contract.go index 76ef23c..05bf33c 100644 --- a/internal/domain/output_contract.go +++ b/internal/domain/output_contract.go @@ -22,8 +22,26 @@ func ValidateOutputContract(contract OutputContract) error { return fmt.Errorf("invalid validation mode: %q", contract.ValidationMode) } - if contract.ValidationMode == ValidationJSONSchema && strings.TrimSpace(contract.SchemaPath) == "" { - return errors.New("schema_path is required when validation_mode is json_schema") + if contract.ValidationMode == ValidationJSONSchema { + count := 0 + if contract.Schema != nil { + count++ + } + if contract.SchemaFile != nil { + if strings.TrimSpace(*contract.SchemaFile) == "" { + return errors.New("schema_file must not be blank") + } + count++ + } + if contract.SchemaPath != "" { + if strings.TrimSpace(contract.SchemaPath) == "" { + return errors.New("schema_path must not be blank") + } + count++ + } + if count != 1 { + return errors.New("exactly one of schema, schema_file, or schema_path is required when validation_mode is json_schema") + } } if contract.RepairAttempts < 0 { return errors.New("repair_attempts must be greater than or equal to 0") diff --git a/internal/domain/output_contract_test.go b/internal/domain/output_contract_test.go index 70086b4..db3c180 100644 --- a/internal/domain/output_contract_test.go +++ b/internal/domain/output_contract_test.go @@ -85,3 +85,34 @@ func TestValidateOutputContract(t *testing.T) { }) } } + +func TestSchemaSelection(t *testing.T) { + file, blank := "schema.json", " " + for _, tt := range []struct { + name string + schema any + file *string + path string + valid bool + }{ + {"missing", nil, nil, "", false}, + {"false", false, nil, "", true}, + {"true", true, nil, "", true}, + {"empty object", map[string]any{}, nil, "", true}, + {"file", nil, &file, "", true}, + {"blank file", nil, &blank, "", false}, + {"conflict", false, &file, "", false}, + {"path conflict", map[string]any{}, nil, "schema.json", false}, + } { + t.Run(tt.name, func(t *testing.T) { + contract := OutputContract{Format: FormatJSON, ValidationMode: ValidationJSONSchema, Schema: tt.schema, SchemaFile: tt.file, SchemaPath: tt.path} + if err := ValidateOutputContract(contract); (err == nil) != tt.valid { + t.Fatalf("active selection error = %v", err) + } + contract.ValidationMode = ValidationNone + if err := ValidateOutputContract(contract); err != nil { + t.Fatalf("inactive selection: %v", err) + } + }) + } +} diff --git a/internal/usecase/output_contract_test.go b/internal/usecase/output_contract_test.go index b348e5c..8bd3644 100644 --- a/internal/usecase/output_contract_test.go +++ b/internal/usecase/output_contract_test.go @@ -36,6 +36,26 @@ func newOutputContractTestRunner() (*Runner, outputContractTestCollaborators) { ), collaborators } +func TestResolveInlineSchemaOwnsRuntimeValue(t *testing.T) { + value := map[string]any{"properties": map[string]any{"name": map[string]any{"type": "string"}}} + override := domain.OutputContract{Format: domain.FormatJSON, ValidationMode: domain.ValidationJSONSchema, Schema: value} + contract, err := resolveOutputContract(context.Background(), &domain.PromptDefinition{}, &override) + if err != nil { + t.Fatal(err) + } + value["properties"].(map[string]any)["name"] = false + if _, ok := contract.Schema.(map[string]any)["properties"].(map[string]any)["name"].(map[string]any); !ok { + t.Fatal("schema shares caller storage") + } + var null map[string]any + override.Schema = null + override.SchemaPath = "schema.json" + contract, err = resolveOutputContract(context.Background(), &domain.PromptDefinition{}, &override) + if err != nil || contract.Schema != nil { + t.Fatalf("typed null selection: %#v, %v", contract.Schema, err) + } +} + func TestRunnerPreparationNormalizesOutputContractConsistently(t *testing.T) { tests := []struct { name string diff --git a/internal/usecase/runner.go b/internal/usecase/runner.go index ac50749..8bb8d65 100644 --- a/internal/usecase/runner.go +++ b/internal/usecase/runner.go @@ -351,7 +351,7 @@ func (r *Runner) resolvePreparation( recorder.UpdateSelection(observation.Selection{PromptID: def.ID}) } promptDefinitionHash := promptSelection.hash - effectiveContract, err := resolveOutputContract(def, req.Validation) + effectiveContract, err := resolveOutputContract(ctx, def, req.Validation) if err != nil { return nil, fmt.Errorf("%w: output contract: %v", ErrInvalidRequest, err) } @@ -649,13 +649,20 @@ func validateAPIKey(apiKeyEnv string, apiKey string, apiKeyRequired bool) error return nil } -func resolveOutputContract(def *domain.PromptDefinition, override *domain.OutputContract) (domain.OutputContract, error) { +func resolveOutputContract(ctx context.Context, def *domain.PromptDefinition, override *domain.OutputContract) (domain.OutputContract, error) { contract := def.Validation if override != nil { contract = *override if contract.Format == "" { contract.Format = domain.FormatText } + if contract.ValidationMode == domain.ValidationJSONSchema && contract.Schema != nil { + value, err := validate.DecodeInlineSchema(ctx, contract.Schema) + if err != nil { + return domain.OutputContract{}, fmt.Errorf("invalid inline schema value: %w", err) + } + contract.Schema = value + } } if err := domain.ValidateOutputContract(contract); err != nil { return domain.OutputContract{}, err diff --git a/internal/validate/standard_validator.go b/internal/validate/standard_validator.go index e36d91f..389f2df 100644 --- a/internal/validate/standard_validator.go +++ b/internal/validate/standard_validator.go @@ -183,6 +183,15 @@ func validateArtifact(ctx context.Context, artifact *domain.Artifact, contract d } } +// DecodeInlineSchema converts a caller-supplied value to an owned JSON document. +func DecodeInlineSchema(ctx context.Context, value any) (any, error) { + encoded, err := json.Marshal(value) + if err != nil { + return nil, err + } + return decodeJSONValue(ctx, encoded) +} + func decodeJSONValue(ctx context.Context, body []byte) (any, error) { if err := ctx.Err(); err != nil { return nil, err diff --git a/internal/validate/validator.go b/internal/validate/validator.go index 67a9a90..0cc3b9e 100644 --- a/internal/validate/validator.go +++ b/internal/validate/validator.go @@ -6,6 +6,12 @@ import ( "go.maximumdirect.net/promptkit/internal/domain" ) +// Input describes the selected contract and its optional bound schema file. +type Input struct { + Contract domain.OutputContract + File *domain.ResourceBinding +} + // PreparedValidation validates artifacts against one frozen output contract. // Its cancellation boundary is synchronous: Validate does not detach schema // execution, and an observed context error prevents publication of a result. diff --git a/output_contract_contract_test.go b/output_contract_contract_test.go index 8648274..2371c17 100644 --- a/output_contract_contract_test.go +++ b/output_contract_contract_test.go @@ -15,6 +15,13 @@ func TestPreparationRejectsInvalidOutputContractWithPublicError(t *testing.T) { name string contract promptkit.OutputContract }{ + { + name: "inline schema cannot be encoded", + contract: promptkit.OutputContract{ + Format: promptkit.FormatJSON, ValidationMode: promptkit.ValidationJSONSchema, + Schema: make(chan int), + }, + }, { name: "unsupported format", contract: promptkit.OutputContract{ diff --git a/prompt_sources_contract_test.go b/prompt_sources_contract_test.go index ccfa3f2..a917561 100644 --- a/prompt_sources_contract_test.go +++ b/prompt_sources_contract_test.go @@ -104,3 +104,40 @@ func TestNilTypedPromptSourceSuppliesEmptySequence(t *testing.T) { t.Fatalf("empty source = %v, %v", prompts, err) } } + +func TestTypedPromptSourceSchemaValues(t *testing.T) { + var absent map[string]any + object := map[string]any{"type": "object"} + file := "schema.json" + source := promptkit.PromptSource("schemas", []promptkit.PromptConfig{ + {ID: "false", Output: &promptkit.PromptOutputConfig{Schema: false}}, + {ID: "true", Output: &promptkit.PromptOutputConfig{Schema: true}}, + {ID: "empty", Output: &promptkit.PromptOutputConfig{Schema: map[string]any{}}}, + {ID: "absent", Output: &promptkit.PromptOutputConfig{Schema: absent}}, + {ID: "object", Output: &promptkit.PromptOutputConfig{Schema: object, SchemaFile: &file}}, + }) + object["type"] = "changed" + type document struct { + Prompts []struct { + ID string `yaml:"id"` + Output map[string]any `yaml:"output"` + } `yaml:"prompts"` + } + result, err := configkit.LoadLayered(configkit.Input{Source: source}, configkit.LayeredOptions[document]{}) + if err != nil { + t.Fatal(err) + } + values := result.Config.Prompts + if values[0].Output["schema"] != false || values[1].Output["schema"] != true { + t.Fatalf("boolean schemas: %#v", values) + } + if empty, ok := values[2].Output["schema"].(map[string]any); !ok || len(empty) != 0 { + t.Fatalf("empty schema: %#v", values[2]) + } + if _, ok := values[3].Output["schema"]; ok { + t.Fatalf("nil schema emitted: %#v", values[3]) + } + if captured, ok := values[4].Output["schema"].(map[string]any); !ok || captured["type"] != "object" || values[4].Output["schema_file"] != file { + t.Fatalf("captured schema: %#v", values[4]) + } +} diff --git a/prompts.go b/prompts.go index 982b7e5..e224853 100644 --- a/prompts.go +++ b/prompts.go @@ -1,6 +1,10 @@ package promptkit -import "go.maximumdirect.net/configkit" +import ( + "reflect" + + "go.maximumdirect.net/configkit" +) // PromptConfig is a presence-aware source input for one prompt. Extends names // a sibling prompt. Nil optional pointers and slices are omitted; non-nil @@ -35,8 +39,9 @@ type PromptCacheControlConfig struct{ Type, TTL *string } // PromptOutputConfig supplies optional output contract source fields. type PromptOutputConfig struct { - Format, ValidationMode, SchemaPath *string - RepairAttempts *int + Format, ValidationMode, SchemaPath, SchemaFile *string + Schema any + RepairAttempts *int } // PromptSource creates a labeled ConfigKit mapping in caller order. Nil @@ -118,6 +123,12 @@ func PromptSource(label string, prompts []PromptConfig) configkit.Source { if config.Output.SchemaPath != nil { output["schema_path"] = *config.Output.SchemaPath } + if value := reflect.ValueOf(config.Output.Schema); value.IsValid() && !((value.Kind() == reflect.Pointer || value.Kind() == reflect.Map || value.Kind() == reflect.Slice || value.Kind() == reflect.Interface) && value.IsNil()) { + output["schema"] = config.Output.Schema + } + if config.Output.SchemaFile != nil { + output["schema_file"] = *config.Output.SchemaFile + } if config.Output.RepairAttempts != nil { output["repair_attempts"] = *config.Output.RepairAttempts } diff --git a/resource_inspection.go b/resource_inspection.go index 4a12c97..310ca81 100644 --- a/resource_inspection.go +++ b/resource_inspection.go @@ -80,6 +80,8 @@ type PromptCacheControlInspection struct { type PromptOutputInspection struct { Format OutputFormat `json:"format" yaml:"format"` ValidationMode ValidationMode `json:"validation_mode" yaml:"validation_mode"` + Schema any `json:"schema,omitempty" yaml:"schema,omitempty"` + SchemaFile *string `json:"schema_file,omitempty" yaml:"schema_file,omitempty"` SchemaPath *string `json:"schema_path,omitempty" yaml:"schema_path,omitempty"` RepairAttempts *int `json:"repair_attempts,omitempty" yaml:"repair_attempts,omitempty"` } diff --git a/types.go b/types.go index d03008a..36ac32c 100644 --- a/types.go +++ b/types.go @@ -502,8 +502,9 @@ type OutputContract struct { // ValidationMode selects the content check. Use one of the declared // ValidationMode constants. ValidationMode ValidationMode `json:"validation_mode"` - // SchemaPath is required when ValidationMode is ValidationJSONSchema and is - // ignored by other modes. + // Schema supplies an inline JSON Schema. Nil means no inline selection. + Schema any `json:"schema,omitempty"` + // SchemaPath identifies a schema under the applicable configured root. SchemaPath string `json:"schema_path"` // RepairAttempts is an additional generation-call budget from zero through // three. Zero is single-pass. A positive value is valid only with basic,