Capture schema roots from configuration sources

This commit is contained in:
2026-11-20 15:25:00 +00:00
parent fbe3d427a2
commit 596e985cff
11 changed files with 204 additions and 100 deletions

View File

@@ -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.

View File

@@ -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 {

View File

@@ -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"`

View File

@@ -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 {

View File

@@ -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)
}
}

View File

@@ -7,7 +7,6 @@ import (
)
const (
SchemaDirDefault = "."
OutputArtifactName = "output"
ContentTypeTextPlain = "text/plain"
ContentTypeTextMarkdown = "text/markdown"

View File

@@ -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)

View File

@@ -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)
}

View File

@@ -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

View File

@@ -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)
}
}

16
schema_source_test.go Normal file
View File

@@ -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: "."},
}
}