From 74a77b3c324eeb71ac054a8c558920b41455bc50 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 14:24:30 +0000 Subject: [PATCH] Construct engines from resolved application configuration --- configuration_handoff_test.go | 76 ++++++++++++++++++++++ docs/roadmap/implementation.md | 3 + engine.go | 112 ++++++++++++++++++++++++++++++--- internal/configuration/load.go | 47 +------------- internal/engine/engine.go | 34 ++-------- 5 files changed, 191 insertions(+), 81 deletions(-) create mode 100644 configuration_handoff_test.go diff --git a/configuration_handoff_test.go b/configuration_handoff_test.go new file mode 100644 index 0000000..7c82b02 --- /dev/null +++ b/configuration_handoff_test.go @@ -0,0 +1,76 @@ +package promptkit_test + +import ( + "context" + "errors" + "testing" + + "go.maximumdirect.net/configkit" + "go.maximumdirect.net/promptkit" +) + +type handoffApplication struct { + PromptKit promptkit.Settings `yaml:"promptkit"` +} + +type handoffWrapper struct { + result *configkit.Result[handoffApplication] + override any + useOverride bool + inspection bool +} + +func (w *handoffWrapper) Value(path configkit.Path) (any, bool) { + if w.useOverride { + return w.override, true + } + return w.result.Value(path) +} +func (w *handoffWrapper) InspectSubtree(path configkit.Path) (configkit.Inspection, bool) { + if !w.inspection { + return configkit.Inspection{}, false + } + return w.result.InspectSubtree(path) +} +func (w *handoffWrapper) Diagnostics() []configkit.Diagnostic { return w.result.Diagnostics() } + +func TestConstructorsShareCapturedResources(t *testing.T) { + source := configkit.Bytes("prompt", []byte("promptkit:\n prompts:\n - id: example\n messages: [{role: user, content: hello}]\n output: {format: text, validation_mode: basic}\n")) + definition := promptkit.Configure(configkit.Definition[handoffApplication]{}, func(value *handoffApplication) *promptkit.Settings { return &value.PromptKit }) + result, err := configkit.Load(source, configkit.Options[handoffApplication]{Definition: definition}) + if err != nil { + t.Fatal(err) + } + wrapped := &handoffWrapper{result: result, inspection: true} + applicationEngine, err := promptkit.NewFromConfig(wrapped, promptkit.RuntimeConfig{}, promptkit.WithBundledOpenRouter(true)) + if err != nil { + t.Fatal(err) + } + input := configkit.Input{Source: source} + standalone, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &input}}, promptkit.WithBundledOpenRouter(false)) + if err != nil { + t.Fatal(err) + } + for _, engine := range []*promptkit.Engine{applicationEngine, standalone} { + prompt, err := engine.InspectPrompt(context.Background(), "example") + if err != nil || prompt.Messages[0].Content != "hello" || prompt.OutputContract.RepairAttempts != 1 { + t.Fatalf("prompt = %+v, %v", prompt, err) + } + backends, err := engine.ListBackends(context.Background()) + if err != nil || len(backends) != 0 { + t.Fatalf("backends = %+v, %v", backends, err) + } + } +} + +func TestNewFromConfigRejectsInvalidHandoff(t *testing.T) { + var nilResult *handoffWrapper + if _, err := promptkit.NewFromConfig(nilResult, promptkit.RuntimeConfig{}); !errors.Is(err, promptkit.ErrInvalidConfig) { + t.Fatalf("nil result: %v", err) + } + for _, wrapper := range []*handoffWrapper{{inspection: false}, {inspection: true, useOverride: true, override: "wrong"}} { + if _, err := promptkit.NewFromConfig(wrapper, promptkit.RuntimeConfig{}); !errors.Is(err, promptkit.ErrInvalidConfig) { + t.Fatalf("invalid handoff: %v", err) + } + } +} diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 9d6ea9b..74968fa 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -443,6 +443,9 @@ location, with no shape recognition or second merge pass. ## Stage 9 — Wire Whole-Result And Standalone Engine Construction +Status: complete. Focused constructor tests passed for shared capture, explicit +bundle behavior, and invalid handoffs; broader integration coverage follows. + Focus: root `engine.go`, new configuration facade wiring, `internal/engine/engine.go`, and the former adapter load entry point. diff --git a/engine.go b/engine.go index ff4c8aa..566880c 100644 --- a/engine.go +++ b/engine.go @@ -5,10 +5,12 @@ import ( "errors" "fmt" "net/http" + "reflect" "time" "go.maximumdirect.net/configkit" "go.maximumdirect.net/promptkit/internal/backend" + "go.maximumdirect.net/promptkit/internal/configuration" "go.maximumdirect.net/promptkit/internal/domain" internalengine "go.maximumdirect.net/promptkit/internal/engine" "go.maximumdirect.net/promptkit/internal/observation" @@ -158,14 +160,15 @@ func (f optionFunc) apply(options *engineOptions) error { } type engineOptions struct { - internal internalengine.Options + internal internalengine.Options + disableBundledOpenRouter bool } // WithBundledOpenRouter enables or disables the built-in OpenRouter underlay. // It is enabled by default; when repeated, the last option wins. func WithBundledOpenRouter(enabled bool) Option { return optionFunc(func(options *engineOptions) error { - options.internal.SetBundledOpenRouter(enabled) + options.disableBundledOpenRouter = !enabled return nil }) } @@ -220,26 +223,121 @@ func WithArtifactReader(reader ArtifactReader) Option { // does not perform model requests or require credentials. A negative // Config.TransientRetries is invalid. func NewEngine(cfg Config, opts ...Option) (*Engine, error) { + options, err := applyEngineOptions(opts) + if err != nil { + return nil, err + } + runtime := RuntimeConfig{Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient, TransientRetries: cfg.TransientRetries} + if _, err := domain.ResolveTransientRetries(2, runtime.TransientRetries); err != nil { + return nil, newPublicOperationError(ErrInvalidConfig, err) + } + underlays := append([]configkit.Underlay(nil), cfg.Sources.Underlays...) + if !options.disableBundledOpenRouter { + underlays = append([]configkit.Underlay{BundledOpenRouterUnderlay()}, underlays...) + } + main := configkit.Input{Source: configkit.NoSource()} + if cfg.Sources.Main != nil { + main = *cfg.Sources.Main + } + definition := Configure(configkit.Definition[standaloneConfiguration]{}, func(value *standaloneConfiguration) *Settings { return &value.PromptKit }) + result, err := configkit.LoadLayered(main, configkit.LayeredOptions[standaloneConfiguration]{Underlays: underlays, Definition: definition}) + if err != nil { + return nil, newPublicOperationError(ErrInvalidConfig, err) + } + return newFromConfig(result, runtime, options) +} + +type standaloneConfiguration struct { + PromptKit Settings `yaml:"promptkit"` + Application map[string]any `yaml:",inline"` +} + +// Configuration is the completed application-owned configuration evidence +// needed to capture PromptKit resources without loading configuration again. +type Configuration interface { + Value(configkit.Path) (any, bool) + InspectSubtree(configkit.Path) (configkit.Inspection, bool) + Diagnostics() []configkit.Diagnostic +} + +// RuntimeConfig selects runtime-only client and retry settings for NewFromConfig. +// Its fields have the same semantics as the corresponding Config fields. +type RuntimeConfig struct { + Timeout time.Duration + HTTPClient *http.Client + TransientRetries *int +} + +// NewFromConfig captures resources from an application-owned completed load. +// The application must register PromptKit rules during that load. Callers must +// not mutate its selected settings between loading and this handoff. After +// construction, later settings mutations do not alter the engine. This method +// does not load sources, rerun callbacks, or select bundled underlays. +func NewFromConfig(result Configuration, cfg RuntimeConfig, opts ...Option) (*Engine, error) { + options, err := applyEngineOptions(opts) + if err != nil { + return nil, err + } + return newFromConfig(result, cfg, options) +} + +func applyEngineOptions(opts []Option) (engineOptions, error) { var options engineOptions for _, opt := range opts { if opt == nil { continue } if err := opt.apply(&options); err != nil { - return nil, newPublicOperationError(ErrInvalidConfig, err) + return engineOptions{}, newPublicOperationError(ErrInvalidConfig, err) } } + return options, nil +} - assembled, err := internalengine.New( - 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, - ) +func newFromConfig(result Configuration, cfg RuntimeConfig, options engineOptions) (*Engine, error) { + if result == nil || isNilConfiguration(result) { + return nil, newPublicOperationError(ErrInvalidConfig, errors.New("configuration result is nil")) + } + if _, err := domain.ResolveTransientRetries(2, cfg.TransientRetries); err != nil { + return nil, newPublicOperationError(ErrInvalidConfig, err) + } + value, available := result.Value(configkit.Keys("promptkit")) + var selected *Settings + if available && value != nil { + switch section := value.(type) { + case Settings: + selected = §ion + case *Settings: + selected = section + default: + return nil, newPublicOperationError(ErrInvalidConfig, fmt.Errorf("promptkit section has incompatible type %T", value)) + } + } + view, ok := result.InspectSubtree(configkit.Keys("promptkit")) + if !ok { + return nil, newPublicOperationError(ErrInvalidConfig, errors.New("configuration inspection is unavailable")) + } + snapshot, err := configuration.Capture(selected, view, result.Diagnostics()) + if err != nil { + return nil, newPublicOperationError(ErrInvalidConfig, err) + } + assembled, err := internalengine.New(snapshot, internalengine.Config{Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient, TransientRetries: copyIntPtr(cfg.TransientRetries)}, options.internal) if err != nil { return nil, newPublicOperationError(ErrInvalidConfig, err) } return &Engine{internal: assembled}, nil } +func isNilConfiguration(result Configuration) bool { + value := reflect.ValueOf(result) + switch value.Kind() { + case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Ptr, reflect.Slice: + return value.IsNil() + default: + return false + } +} + // InspectPrompt resolves one prompt ID without selecting a profile or starting // execution work. // diff --git a/internal/configuration/load.go b/internal/configuration/load.go index 6ae50c7..cfeb9aa 100644 --- a/internal/configuration/load.go +++ b/internal/configuration/load.go @@ -16,11 +16,6 @@ import ( "go.maximumdirect.net/promptkit/internal/settings" ) -type document struct { - PromptKit settings.Settings `yaml:"promptkit"` - Application map[string]any `yaml:",inline"` -} - type collectionConfig = settings.CollectionSettings type backendConfig = settings.BackendSettings type profileConfig = settings.ProfileSettings @@ -56,6 +51,9 @@ type loaded struct { collections []CollectionIdentity } +// Snapshot holds configuration resources captured for engine assembly. +type Snapshot = loaded + type resourceBases struct { backends configkit.Path profiles configkit.Path @@ -136,11 +134,6 @@ func indexedProfiles(config *settings.Settings) map[string]profileConfig { var envName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`) -// Load captures one immutable effective configuration for internal consumers. -func Load(main configkit.Input, underlays []configkit.Underlay) (*loaded, error) { - return load(main, underlays) -} - // SequenceIdentities returns the component's native sequence registrations. func SequenceIdentities() []configkit.SequenceIdentity { return []configkit.SequenceIdentity{ @@ -172,40 +165,6 @@ func Validate(config *settings.Settings, validation *configkit.Validation) { } } -func configurationDefinition() configkit.Definition[document] { - return configkit.Definition[document]{ - SequenceIdentities: SequenceIdentities(), - Sensitive: Sensitive, - Resolve: func(config *document, resolution *configkit.Resolution) error { - Resolve(&config.PromptKit, resolution) - return nil - }, - Validate: func(config *document, validation *configkit.Validation) { - Validate(&config.PromptKit, validation) - }, - } -} - -// load performs one ConfigKit lifecycle over the selected source tiers. -func load(main configkit.Input, underlays []configkit.Underlay) (*loaded, error) { - result, err := configkit.LoadLayered(main, configkit.LayeredOptions[document]{ - Underlays: underlays, - Definition: configurationDefinition(), - }) - if err != nil { - return nil, fmt.Errorf("load configuration: %w", err) - } - view, ok := result.InspectSubtree(configkit.Keys("promptkit")) - if !ok { - return nil, fmt.Errorf("load configuration: inspection unavailable") - } - state, err := Capture(&result.Config.PromptKit, view, result.Diagnostics()) - if err != nil { - return nil, fmt.Errorf("load configuration: %w", err) - } - return state, nil -} - // Capture builds owned runtime resources from effective settings and native evidence. func Capture(input *settings.Settings, view configkit.Inspection, diagnostics []configkit.Diagnostic) (*loaded, error) { config := ownSettings(input) diff --git a/internal/engine/engine.go b/internal/engine/engine.go index f1ddaa6..6b5d485 100644 --- a/internal/engine/engine.go +++ b/internal/engine/engine.go @@ -8,7 +8,6 @@ import ( "strings" "time" - "go.maximumdirect.net/configkit" "go.maximumdirect.net/promptkit/internal/artifact" "go.maximumdirect.net/promptkit/internal/capacity" "go.maximumdirect.net/promptkit/internal/configuration" @@ -22,29 +21,18 @@ import ( // Config carries construction settings selected by the public facade. type Config struct { - Sources ConfigurationSources Timeout time.Duration HTTPClient *http.Client TransientRetries *int } -// ConfigurationSources identifies caller-selected ConfigKit layers. -type ConfigurationSources struct { - Underlays []configkit.Underlay - Main *configkit.Input -} - // Options collects construction choices from the public facade. type Options struct { - llmClient llm.Client - artifactReader artifact.Reader - artifactSource bool - disableBundledOpenRouter bool + llmClient llm.Client + artifactReader artifact.Reader + artifactSource bool } -// SetBundledOpenRouter selects whether the built-in OpenRouter source is installed. -func (o *Options) SetBundledOpenRouter(enabled bool) { o.disableBundledOpenRouter = !enabled } - // SetLLMClient selects the client collaborator for one engine. func (o *Options) SetLLMClient(client llm.Client) { o.llmClient = client } @@ -101,25 +89,11 @@ type ListingFilter struct { } // New assembles an engine from facade-selected configuration and collaborators. -func New(cfg Config, options Options) (*Engine, error) { +func New(snapshot *configuration.Snapshot, cfg Config, options Options) (*Engine, error) { defaultRetries, err := domain.ResolveTransientRetries(2, cfg.TransientRetries) if err != nil { return nil, err } - underlays := cfg.Sources.Underlays - if !options.disableBundledOpenRouter { - underlays = make([]configkit.Underlay, 1, len(cfg.Sources.Underlays)+1) - underlays[0] = configuration.BundledOpenRouterUnderlay() - underlays = append(underlays, cfg.Sources.Underlays...) - } - main := configkit.Input{Source: configkit.NoSource()} - if cfg.Sources.Main != nil { - main = *cfg.Sources.Main - } - snapshot, err := configuration.Load(main, underlays) - if err != nil { - return nil, err - } manager, err := capacity.NewManager(snapshot.CapacityPolicies()) if err != nil { return nil, fmt.Errorf("failed to construct backend capacity manager: %w", err)