diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 2529c34..c7b8f94 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -170,6 +170,8 @@ runtime filesystem API or truthiness-based loss of schemas. ## Stage 2 — Capture Roots Through Native Configuration Inputs +Status: complete. + Work in `internal/configuration/load.go`, its normalization/capture helpers, the new root source helper, `engine.go`, and internal engine construction. diff --git a/engine.go b/engine.go index b5a6824..c5b9cda 100644 --- a/engine.go +++ b/engine.go @@ -4,7 +4,6 @@ import ( "context" "errors" "fmt" - "io/fs" "net/http" "time" @@ -126,9 +125,6 @@ type ConfigurationSources struct { type Config struct { // Sources combines maintained definitions with caller-selected inputs. Sources ConfigurationSources - // SchemaDir is the root for JSON Schema files. An empty value uses the - // current directory. WithSchemaFS or WithSchemaFile replaces this source. - SchemaDir string // Timeout is the transport-wide safety cap for the built-in LLM client // when HTTPClient is absent or has a non-positive timeout. A zero or negative // value selects the 10-minute default. @@ -148,7 +144,7 @@ type Config struct { // Option customizes engine construction. // // NewEngine applies options in argument order and ignores nil options. Within -// each schema-source, model-client, and artifact-reader category, the last +// each model-client and artifact-reader category, the last // non-nil valid option replaces earlier options. An invalid option fails // construction even if a later option would replace it. type Option interface { @@ -207,30 +203,6 @@ func WithArtifactReader(reader ArtifactReader) Option { }) } -// WithSchemaFS loads JSON Schema documents from fsys under root. -// -// Prompt schema_path values resolve within this source when schema validation -// or structured output is requested. fsys must be non-nil and root must be -// non-empty; otherwise NewEngine fails with ErrInvalidConfig. This option -// replaces Config.SchemaDir and earlier schema-source options. -func WithSchemaFS(fsys fs.FS, root string) Option { - return optionFunc(func(options *engineOptions) error { - return options.internal.SetSchemaFS(fsys, root) - }) -} - -// WithSchemaFile loads JSON Schema documents from the single schema file at path. -// -// Prompt schema_path values refer to the file's base name. path must name an -// existing non-directory file when NewEngine applies the option. This option -// replaces Config.SchemaDir and earlier schema-source options. The selected -// schema must be self-contained; external resources are not loaded. -func WithSchemaFile(path string) Option { - return optionFunc(func(options *engineOptions) error { - return options.internal.SetSchemaFile(path) - }) -} - // NewEngine constructs an Engine from configuration and options. // // ConfigKit composes caller-selected underlays in their given order, followed @@ -259,7 +231,7 @@ func NewEngine(cfg Config, opts ...Option) (*Engine, error) { } assembled, err := internalengine.New( - internalengine.Config{Sources: internalengine.ConfigurationSources{Underlays: cfg.Sources.Underlays, Main: cfg.Sources.Main}, SchemaDir: cfg.SchemaDir, Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient, TransientRetries: copyIntPtr(cfg.TransientRetries)}, + internalengine.Config{Sources: internalengine.ConfigurationSources{Underlays: cfg.Sources.Underlays, Main: cfg.Sources.Main}, Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient, TransientRetries: copyIntPtr(cfg.TransientRetries)}, options.internal, ) if err != nil { diff --git a/internal/configuration/load.go b/internal/configuration/load.go index a189e07..7bc40ab 100644 --- a/internal/configuration/load.go +++ b/internal/configuration/load.go @@ -17,6 +17,7 @@ import ( type document struct { Version *string `yaml:"version"` + SchemaRoot *string `yaml:"schema_root"` Backends []backendConfig `yaml:"backends"` Profiles []profileConfig `yaml:"profiles"` Prompts []promptConfig `yaml:"prompts"` @@ -25,6 +26,7 @@ type document struct { type collectionConfig struct { ReleaseVersion *string `yaml:"release_version"` + SchemaRoot *string `yaml:"schema_root"` Backends []backendConfig `yaml:"backends"` Profiles []profileConfig `yaml:"profiles"` Prompts []promptConfig `yaml:"prompts"` diff --git a/internal/configuration/prompts.go b/internal/configuration/prompts.go index 0f40d63..0e04db1 100644 --- a/internal/configuration/prompts.go +++ b/internal/configuration/prompts.go @@ -40,6 +40,19 @@ func (state *loaded) materializePrompts() error { } return metadata.Lookup(path) } + applicationRoot, err := state.captureSchemaRoot(state.result.Config.SchemaRoot, configkit.Keys("schema_root"), lookupOrigin) + if err != nil { + return err + } + roots := make(map[string]*domain.ResourceBinding, len(state.result.Config.Collections)) + for _, name := range sortedKeys(state.result.Config.Collections) { + collection := state.result.Config.Collections[name] + root, err := state.captureSchemaRoot(collection.SchemaRoot, configkit.Keys("collections", name, "schema_root"), lookupOrigin) + if err != nil { + return err + } + roots[name] = root + } for _, resources := range resourceSets(&state.result.Config) { for index, raw := range resources.prompts { promptBase := resources.bases.prompts.Index(index) @@ -51,12 +64,39 @@ func (state *loaded) materializePrompts() error { if err != nil { return err } + entry.definition.SchemaRoot = applicationRoot + if root := roots[resources.namespace]; resources.isCollection && root != nil { + entry.definition.SchemaRoot = root + } state.prompts[fullID] = entry } } return nil } +func (state *loaded) captureSchemaRoot(root *string, fieldPath configkit.Path, lookupOrigin func(configkit.Path) (configkit.FieldInfo, bool)) (*domain.ResourceBinding, error) { + if root == nil { + return nil, nil + } + if strings.TrimSpace(*root) == "" { + return nil, fmt.Errorf("%s: schema_root must not be blank", fieldPath) + } + field, found := lookupOrigin(fieldPath) + if !found || len(field.Origin.Locations) != 1 { + return nil, fmt.Errorf("%s: schema_root needs one contributing source with a filesystem context", fieldPath) + } + sourceID := field.Origin.Locations[0].SourceID + context, found := state.result.SourceContext(sourceID) + if !found || context.FS == nil { + return nil, fmt.Errorf("%s: schema_root source %s has no filesystem context", fieldPath, sourceID) + } + resolved, _, err := filecatalog.ResolveFSPath(".", context.BaseDir, *root) + if err != nil { + return nil, fmt.Errorf("%s: invalid schema_root: %w", fieldPath, err) + } + return &domain.ResourceBinding{FS: context.FS, Path: resolved}, nil +} + func (state *loaded) materializePrompt(id string, raw promptConfig, base configkit.Path, lookupOrigin func(configkit.Path) (configkit.FieldInfo, bool)) (*promptEntry, error) { if len(raw.Messages) == 0 { return nil, fmt.Errorf("%s: at least one message is required", base.Key("messages")) @@ -275,6 +315,14 @@ func (state *loaded) lookupPromptEntry(id string) (*promptEntry, error) { func ownPromptDefinition(definition domain.PromptDefinition) *domain.PromptDefinition { definition.Validation = ownOutputContract(definition.Validation) + if definition.SchemaRoot != nil { + root := *definition.SchemaRoot + definition.SchemaRoot = &root + } + if definition.SchemaFile != nil { + file := *definition.SchemaFile + definition.SchemaFile = &file + } definition.Inputs = append([]domain.PromptInput(nil), definition.Inputs...) definition.Templates = append([]domain.PromptMessageTemplate(nil), definition.Templates...) for index := range definition.Templates { diff --git a/internal/configuration/schema_roots_test.go b/internal/configuration/schema_roots_test.go new file mode 100644 index 0000000..e4b7fa0 --- /dev/null +++ b/internal/configuration/schema_roots_test.go @@ -0,0 +1,102 @@ +package configuration + +import ( + "errors" + "io/fs" + "testing" + "testing/fstest" + + "go.maximumdirect.net/configkit" +) + +type countingSchemaFS struct { + opens int + files fstest.MapFS +} + +func (f *countingSchemaFS) Open(name string) (fs.File, error) { + if name != "." && name != "app" && name != "operator" { + f.opens++ + } + return f.files.Open(name) +} + +func TestSchemaRootsCaptureEffectiveContexts(t *testing.T) { + first := &countingSchemaFS{files: fstest.MapFS{"app/placeholder": {Data: []byte("application")}}} + second := &countingSchemaFS{files: fstest.MapFS{"operator/placeholder": {Data: []byte("operator")}}} + firstFS := configkit.NewFilesystem("application", first) + secondFS := configkit.NewFilesystem("override", second) + prompt := map[string]any{"id": "p", "messages": []any{map[string]any{"role": "user", "content": "hello"}}, "output": map[string]any{"format": "text", "validation_mode": "none"}} + base := configkit.Input{Source: configkit.Mapping("base", map[string]any{ + "schema_root": "schemas", "prompts": []any{prompt}, + "collections": map[string]any{"alpha": map[string]any{"schema_root": "old", "prompts": []any{prompt}}, "beta": map[string]any{"schema_root": "old", "prompts": []any{prompt}}}, + }), Filesystem: &configkit.FilesystemContext{FS: &firstFS, Root: ".", BaseDir: "app"}} + override := configkit.Input{Source: configkit.Mapping("override", map[string]any{"collections": map[string]any{"alpha": map[string]any{"schema_root": "new"}, "beta": map[string]any{"schema_root": nil}}}), Filesystem: &configkit.FilesystemContext{FS: &secondFS, Root: ".", BaseDir: "operator"}} + state, err := load(override, []configkit.Underlay{{Inputs: []configkit.Input{base}}}) + if err != nil { + var loadErr *configkit.LoadError + if errors.As(err, &loadErr) { + t.Fatalf("%v: %+v", err, loadErr.Diagnostics()) + } + t.Fatal(err) + } + for id, want := range map[string]string{"p": "app/schemas", "alpha/p": "operator/new", "beta/p": "app/schemas"} { + definition, _, err := state.prompt(id) + if err != nil || definition.SchemaRoot == nil || definition.SchemaRoot.Path != want { + t.Fatalf("%s root = %+v, %v", id, definition, err) + } + } + if first.opens != 0 || second.opens != 0 { + t.Fatalf("root capture opened files: %d, %d", first.opens, second.opens) + } + for id, resource := range map[string]string{"p": "app/placeholder", "alpha/p": "operator/placeholder", "beta/p": "app/placeholder"} { + definition, _, err := state.prompt(id) + if err != nil { + t.Fatal(err) + } + content, err := fs.ReadFile(definition.SchemaRoot.FS, resource) + want := "application" + if id == "alpha/p" { + want = "operator" + } + if err != nil || string(content) != want { + t.Fatalf("%s source = %q, %v", id, content, err) + } + } +} + +func TestSchemaRootRequiresValueAndContext(t *testing.T) { + filesystem := configkit.NewFilesystem("fixture", fstest.MapFS{}) + for _, tc := range []struct { + name string + root any + context *configkit.FilesystemContext + valid bool + }{ + {"absent", nil, nil, true}, + {"blank", " ", &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."}, false}, + {"missing context", "schemas", nil, false}, + {"explicit dot", ".", &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."}, true}, + } { + t.Run(tc.name, func(t *testing.T) { + input := configkit.Input{Source: configkit.Mapping("root", map[string]any{"schema_root": tc.root}), Filesystem: tc.context} + _, err := load(input, nil) + if (err == nil) != tc.valid { + var loadErr *configkit.LoadError + if errors.As(err, &loadErr) { + t.Fatalf("%v: %+v", err, loadErr.Diagnostics()) + } + t.Fatalf("root error = %v", err) + } + }) + } +} + +func TestSchemaRootValidationUsesEffectiveValue(t *testing.T) { + filesystem := configkit.NewFilesystem("fixture", fstest.MapFS{}) + underlay := configkit.Input{Source: configkit.Mapping("old", map[string]any{"schema_root": " "})} + main := configkit.Input{Source: configkit.Mapping("new", map[string]any{"schema_root": "."}), Filesystem: &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."}} + if _, err := load(main, []configkit.Underlay{{Inputs: []configkit.Input{underlay}}}); err != nil { + t.Fatalf("overwritten invalid root was validated: %v", err) + } +} diff --git a/internal/defaults/defaults.go b/internal/defaults/defaults.go index bc8c80f..7b7003e 100644 --- a/internal/defaults/defaults.go +++ b/internal/defaults/defaults.go @@ -7,7 +7,6 @@ import ( ) const ( - SchemaDirDefault = "." OutputArtifactName = "output" ContentTypeTextPlain = "text/plain" ContentTypeTextMarkdown = "text/markdown" diff --git a/internal/engine/engine.go b/internal/engine/engine.go index 1819b94..f1ddaa6 100644 --- a/internal/engine/engine.go +++ b/internal/engine/engine.go @@ -4,10 +4,7 @@ package engine import ( "context" "fmt" - "io/fs" "net/http" - "os" - "path/filepath" "strings" "time" @@ -15,7 +12,6 @@ import ( "go.maximumdirect.net/promptkit/internal/artifact" "go.maximumdirect.net/promptkit/internal/capacity" "go.maximumdirect.net/promptkit/internal/configuration" - "go.maximumdirect.net/promptkit/internal/defaults" "go.maximumdirect.net/promptkit/internal/domain" "go.maximumdirect.net/promptkit/internal/generation" "go.maximumdirect.net/promptkit/internal/llm" @@ -27,7 +23,6 @@ import ( // Config carries construction settings selected by the public facade. type Config struct { Sources ConfigurationSources - SchemaDir string Timeout time.Duration HTTPClient *http.Client TransientRetries *int @@ -43,8 +38,6 @@ type ConfigurationSources struct { type Options struct { llmClient llm.Client artifactReader artifact.Reader - validator validate.ValidationPreparer - validatorSource bool artifactSource bool disableBundledOpenRouter bool } @@ -61,27 +54,6 @@ func (o *Options) SetArtifactReader(reader artifact.Reader) { o.artifactSource = true } -// SetSchemaFS selects a schema source rooted in fsys. -func (o *Options) SetSchemaFS(fsys fs.FS, root string) error { - if err := validateSourceFS(fsys, root); err != nil { - return err - } - o.validator = validate.NewFSValidator(fsys, root) - o.validatorSource = true - return nil -} - -// SetSchemaFile selects a single schema file. -func (o *Options) SetSchemaFile(path string) error { - fsys, root, err := fileSource(path) - if err != nil { - return err - } - o.validator = validate.NewFSValidator(fsys, root) - o.validatorSource = true - return nil -} - // Engine forwards domain operations to the single assembled use-case runner. type Engine struct { runner *usecase.Runner @@ -153,14 +125,7 @@ func New(cfg Config, options Options) (*Engine, error) { return nil, fmt.Errorf("failed to construct backend capacity manager: %w", err) } - validator := options.validator - if !options.validatorSource { - schemaDir := cfg.SchemaDir - if strings.TrimSpace(schemaDir) == "" { - schemaDir = defaults.SchemaDirDefault - } - validator = validate.NewStandardValidator(schemaDir) - } + validator := validate.NewValidator() var client llm.Client var diagnosticHTTPClient *llm.OpenAICompatibleClient if options.llmClient == nil { @@ -203,35 +168,6 @@ func (e *Engine) InspectConfiguration() configuration.Inspection { return e.inspection } -func validateSourceFS(fsys fs.FS, root string) error { - if fsys == nil { - return fmt.Errorf("source filesystem is nil") - } - if strings.TrimSpace(root) == "" { - return fmt.Errorf("source root is required") - } - return nil -} - -func fileSource(name string) (fs.FS, string, error) { - if strings.TrimSpace(name) == "" { - return nil, "", fmt.Errorf("source path is required") - } - directory := filepath.Dir(name) - base := filepath.Base(name) - if base == "." || base == string(filepath.Separator) { - return nil, "", fmt.Errorf("source path must name a file") - } - info, err := os.Stat(name) - if err != nil { - return nil, "", fmt.Errorf("failed to access source file %q: %w", name, err) - } - if info.IsDir() { - return nil, "", fmt.Errorf("source path %q must be a file", name) - } - return os.DirFS(directory), filepath.ToSlash(base), nil -} - func (e *Engine) InspectPrompt(ctx context.Context, id string) (*configuration.PromptResource, error) { if strings.TrimSpace(id) == "" { return nil, fmt.Errorf("%w: prompt id is required", usecase.ErrInvalidRequest) diff --git a/prepared_execution_contract_test.go b/prepared_execution_contract_test.go index c575573..1eaa540 100644 --- a/prepared_execution_contract_test.go +++ b/prepared_execution_contract_test.go @@ -36,9 +36,8 @@ func TestPreparedExecutionFreezesSourcesAndReturnsIndependentDetails(t *testing. t.Fatal(err) } engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Underlays: []configkit.Underlay{ - {Inputs: profileInputs}, {Inputs: promptInputs}, + {Inputs: profileInputs}, {Inputs: promptInputs}, {Inputs: []configkit.Input{schemaRootInput(schemaSource, ".")}}, }}}, - promptkit.WithSchemaFS(schemaSource, "."), promptkit.WithArtifactReader(reader), promptkit.WithLLMClient(client), ) @@ -351,8 +350,9 @@ func TestPreparedExecutionRepairsEmptyBasicOutput(t *testing.T) { func TestPreparedExecutionIsolatesMutatingClientAcrossRepair(t *testing.T) { client := &mutatingRepairClient{} - engine, err := promptkit.NewEngine(preparedContractConfig("original message", false), - promptkit.WithSchemaFS(preparedSchemaSource(), "."), promptkit.WithLLMClient(client)) + config := preparedContractConfig("original message", false) + config.Sources.Underlays = append(config.Sources.Underlays, configkit.Underlay{Inputs: []configkit.Input{schemaRootInput(preparedSchemaSource(), ".")}}) + engine, err := promptkit.NewEngine(config, promptkit.WithLLMClient(client)) if err != nil { t.Fatal(err) } diff --git a/prompts.go b/prompts.go index e224853..a4db48e 100644 --- a/prompts.go +++ b/prompts.go @@ -44,6 +44,11 @@ type PromptOutputConfig struct { RepairAttempts *int } +// SchemaRootSource supplies a schema root as a native configuration mapping. +func SchemaRootSource(label, root string) configkit.Source { + return configkit.Mapping(label, map[string]any{"schema_root": root}) +} + // PromptSource creates a labeled ConfigKit mapping in caller order. Nil // top-level input supplies an empty prompts sequence. Records may be partial: // sibling inheritance and layered sources can complete them before NewEngine diff --git a/schema_root_source_test.go b/schema_root_source_test.go new file mode 100644 index 0000000..2652b4c --- /dev/null +++ b/schema_root_source_test.go @@ -0,0 +1,22 @@ +package promptkit + +import ( + "testing" + + "go.maximumdirect.net/configkit" +) + +func TestSchemaRootSourceUsesNativeLayerPrecedence(t *testing.T) { + type document struct { + SchemaRoot *string `yaml:"schema_root"` + } + underlay := configkit.Input{Source: SchemaRootSource("defaults", "defaults")} + main := configkit.Input{Source: configkit.Mapping("operator", map[string]any{"schema_root": "operator"})} + result, err := configkit.LoadLayered(main, configkit.LayeredOptions[document]{Underlays: []configkit.Underlay{{Inputs: []configkit.Input{underlay}}}}) + if err != nil { + t.Fatal(err) + } + if result.Config.SchemaRoot == nil || *result.Config.SchemaRoot != "operator" { + t.Fatalf("effective root = %v", result.Config.SchemaRoot) + } +} diff --git a/schema_source_test.go b/schema_source_test.go new file mode 100644 index 0000000..db0bf09 --- /dev/null +++ b/schema_source_test.go @@ -0,0 +1,16 @@ +package promptkit_test + +import ( + "io/fs" + + "go.maximumdirect.net/configkit" + "go.maximumdirect.net/promptkit" +) + +func schemaRootInput(fsys fs.FS, root string) configkit.Input { + filesystem := configkit.NewFilesystem("schemas", fsys) + return configkit.Input{ + Source: promptkit.SchemaRootSource("schemas", root), + Filesystem: &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."}, + } +}