Construct engines from resolved application configuration

This commit is contained in:
2026-11-21 14:24:30 +00:00
parent 3a948a1e02
commit 74a77b3c32
5 changed files with 191 additions and 81 deletions

View File

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

View File

@@ -443,6 +443,9 @@ location, with no shape recognition or second merge pass.
## Stage 9 — Wire Whole-Result And Standalone Engine Construction ## 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, Focus: root `engine.go`, new configuration facade wiring,
`internal/engine/engine.go`, and the former adapter load entry point. `internal/engine/engine.go`, and the former adapter load entry point.

110
engine.go
View File

@@ -5,10 +5,12 @@ import (
"errors" "errors"
"fmt" "fmt"
"net/http" "net/http"
"reflect"
"time" "time"
"go.maximumdirect.net/configkit" "go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit/internal/backend" "go.maximumdirect.net/promptkit/internal/backend"
"go.maximumdirect.net/promptkit/internal/configuration"
"go.maximumdirect.net/promptkit/internal/domain" "go.maximumdirect.net/promptkit/internal/domain"
internalengine "go.maximumdirect.net/promptkit/internal/engine" internalengine "go.maximumdirect.net/promptkit/internal/engine"
"go.maximumdirect.net/promptkit/internal/observation" "go.maximumdirect.net/promptkit/internal/observation"
@@ -159,13 +161,14 @@ func (f optionFunc) apply(options *engineOptions) error {
type engineOptions struct { type engineOptions struct {
internal internalengine.Options internal internalengine.Options
disableBundledOpenRouter bool
} }
// WithBundledOpenRouter enables or disables the built-in OpenRouter underlay. // WithBundledOpenRouter enables or disables the built-in OpenRouter underlay.
// It is enabled by default; when repeated, the last option wins. // It is enabled by default; when repeated, the last option wins.
func WithBundledOpenRouter(enabled bool) Option { func WithBundledOpenRouter(enabled bool) Option {
return optionFunc(func(options *engineOptions) error { return optionFunc(func(options *engineOptions) error {
options.internal.SetBundledOpenRouter(enabled) options.disableBundledOpenRouter = !enabled
return nil return nil
}) })
} }
@@ -220,26 +223,121 @@ func WithArtifactReader(reader ArtifactReader) Option {
// does not perform model requests or require credentials. A negative // does not perform model requests or require credentials. A negative
// Config.TransientRetries is invalid. // Config.TransientRetries is invalid.
func NewEngine(cfg Config, opts ...Option) (*Engine, error) { 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 var options engineOptions
for _, opt := range opts { for _, opt := range opts {
if opt == nil { if opt == nil {
continue continue
} }
if err := opt.apply(&options); err != nil { if err := opt.apply(&options); err != nil {
return engineOptions{}, newPublicOperationError(ErrInvalidConfig, err)
}
}
return options, nil
}
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) 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 = &section
case *Settings:
selected = section
default:
return nil, newPublicOperationError(ErrInvalidConfig, fmt.Errorf("promptkit section has incompatible type %T", value))
} }
}
assembled, err := internalengine.New( view, ok := result.InspectSubtree(configkit.Keys("promptkit"))
internalengine.Config{Sources: internalengine.ConfigurationSources{Underlays: cfg.Sources.Underlays, Main: cfg.Sources.Main}, Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient, TransientRetries: copyIntPtr(cfg.TransientRetries)}, if !ok {
options.internal, 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 { if err != nil {
return nil, newPublicOperationError(ErrInvalidConfig, err) return nil, newPublicOperationError(ErrInvalidConfig, err)
} }
return &Engine{internal: assembled}, nil 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 // InspectPrompt resolves one prompt ID without selecting a profile or starting
// execution work. // execution work.
// //

View File

@@ -16,11 +16,6 @@ import (
"go.maximumdirect.net/promptkit/internal/settings" "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 collectionConfig = settings.CollectionSettings
type backendConfig = settings.BackendSettings type backendConfig = settings.BackendSettings
type profileConfig = settings.ProfileSettings type profileConfig = settings.ProfileSettings
@@ -56,6 +51,9 @@ type loaded struct {
collections []CollectionIdentity collections []CollectionIdentity
} }
// Snapshot holds configuration resources captured for engine assembly.
type Snapshot = loaded
type resourceBases struct { type resourceBases struct {
backends configkit.Path backends configkit.Path
profiles 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_]*$`) 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. // SequenceIdentities returns the component's native sequence registrations.
func SequenceIdentities() []configkit.SequenceIdentity { func SequenceIdentities() []configkit.SequenceIdentity {
return []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. // Capture builds owned runtime resources from effective settings and native evidence.
func Capture(input *settings.Settings, view configkit.Inspection, diagnostics []configkit.Diagnostic) (*loaded, error) { func Capture(input *settings.Settings, view configkit.Inspection, diagnostics []configkit.Diagnostic) (*loaded, error) {
config := ownSettings(input) config := ownSettings(input)

View File

@@ -8,7 +8,6 @@ import (
"strings" "strings"
"time" "time"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit/internal/artifact" "go.maximumdirect.net/promptkit/internal/artifact"
"go.maximumdirect.net/promptkit/internal/capacity" "go.maximumdirect.net/promptkit/internal/capacity"
"go.maximumdirect.net/promptkit/internal/configuration" "go.maximumdirect.net/promptkit/internal/configuration"
@@ -22,29 +21,18 @@ import (
// Config carries construction settings selected by the public facade. // Config carries construction settings selected by the public facade.
type Config struct { type Config struct {
Sources ConfigurationSources
Timeout time.Duration Timeout time.Duration
HTTPClient *http.Client HTTPClient *http.Client
TransientRetries *int 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. // Options collects construction choices from the public facade.
type Options struct { type Options struct {
llmClient llm.Client llmClient llm.Client
artifactReader artifact.Reader artifactReader artifact.Reader
artifactSource bool artifactSource bool
disableBundledOpenRouter 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. // SetLLMClient selects the client collaborator for one engine.
func (o *Options) SetLLMClient(client llm.Client) { o.llmClient = client } 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. // 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) defaultRetries, err := domain.ResolveTransientRetries(2, cfg.TransientRetries)
if err != nil { if err != nil {
return nil, err 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()) manager, err := capacity.NewManager(snapshot.CapacityPolicies())
if err != nil { if err != nil {
return nil, fmt.Errorf("failed to construct backend capacity manager: %w", err) return nil, fmt.Errorf("failed to construct backend capacity manager: %w", err)