From 76c8789e65dec251fa5eb1d999618d0729a557ff Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 14:15:14 +0000 Subject: [PATCH] Share configuration settings across the public boundary --- backends.go | 35 ----- docs/roadmap/implementation.md | 3 + internal/configuration/load.go | 103 ++------------ internal/configuration/prompts_test.go | 7 +- internal/settings/settings.go | 187 +++++++++++++++++++++++++ settings.go | 39 ++++++ settings_contract_test.go | 67 +++++++++ 7 files changed, 310 insertions(+), 131 deletions(-) create mode 100644 internal/settings/settings.go create mode 100644 settings.go create mode 100644 settings_contract_test.go diff --git a/backends.go b/backends.go index 4343a98..ac629be 100644 --- a/backends.go +++ b/backends.go @@ -41,41 +41,6 @@ type BackendConfig struct { SmokeTests *BackendSmokeTestConfig } -// BackendSmokeTestConfig contains optional diagnostic settings associated with -// a backend. Nil nested fields are omitted by BackendSource. -type BackendSmokeTestConfig struct { - // DefaultProfile is the exact profile ID selected as the backend's - // diagnostic inference default. A supplied value must not be blank; the ID - // is resolved only when that default is selected. - DefaultProfile *string `json:"default_profile,omitempty" yaml:"default_profile,omitempty"` - // Reachability optionally selects a full HTTP destination for reachability - // diagnostics. A nil endpoint uses the effective backend endpoint. - Reachability *ReachabilityProbeConfig `json:"reachability,omitempty" yaml:"reachability,omitempty"` - // Authentication optionally declares a named authentication diagnostic. - // A supplied object requires Kind. - Authentication *AuthenticationProbeConfig `json:"authentication,omitempty" yaml:"authentication,omitempty"` -} - -// ReachabilityProbeConfig configures an optional reachability destination. -type ReachabilityProbeConfig struct { - // Endpoint is an absolute HTTP(S) URL, including any desired path or query. - // Nil selects the effective backend endpoint; an explicit blank value is - // invalid. - Endpoint *string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"` -} - -// AuthenticationProbeConfig configures an optional named authentication -// diagnostic. -type AuthenticationProbeConfig struct { - // Kind selects the authentication adapter. Supported values are "none" and - // "openrouter_key"; surrounding whitespace and case are normalized. - Kind *string `json:"kind,omitempty" yaml:"kind,omitempty"` - // Endpoint is an absolute HTTP(S) URL, including any desired path or query. - // Nil selects the adapter's backend-relative destination; an explicit blank - // value is invalid. - Endpoint *string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"` -} - // BackendSource creates a labeled ConfigKit mapping containing backend records // in caller order. IDs are explicit and duplicates are left for loading to reject. // It encodes fields without validating them; NewEngine validates the final diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index e5ffdc9..e834ec1 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -291,6 +291,9 @@ assigned to Stages 11 and 12; do not retain a legacy request-input alternative. ## Stage 4 — Add The Shared Settings Schema And Root Aliases +Status: complete. Adapter tests and external settings-decoding tests passed; +the standalone envelope retains its existing version field until loader migration. + Focus: `internal/settings`, root settings aliases, `backends.go`, and the configuration adapter's data declarations. diff --git a/internal/configuration/load.go b/internal/configuration/load.go index 6cf96fa..296cc47 100644 --- a/internal/configuration/load.go +++ b/internal/configuration/load.go @@ -13,103 +13,22 @@ import ( "go.maximumdirect.net/promptkit/internal/domain" "go.maximumdirect.net/promptkit/internal/jsonvalue" "go.maximumdirect.net/promptkit/internal/llm" + "go.maximumdirect.net/promptkit/internal/settings" ) type document struct { - Version *string `yaml:"version"` - SchemaRoot *string `yaml:"schema_root"` - Backends []backendConfig `yaml:"backends"` - Profiles []profileConfig `yaml:"profiles"` - Prompts []promptConfig `yaml:"prompts"` - Collections map[string]collectionConfig `yaml:"collections"` + Version *string `yaml:"version"` + settings.Settings `yaml:",inline"` } -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"` -} - -type backendConfig struct { - ID string `yaml:"id"` - Endpoint *string `yaml:"endpoint"` - APIKeyEnv *string `yaml:"api_key_env"` - ConcurrencyLimit *int `yaml:"concurrency_limit"` - QueueCapacity *int `yaml:"queue_capacity"` - ExtraParams map[string]any `yaml:"extra_params"` - SmokeTests *backendSmokeTestConfig `yaml:"smoke_tests"` -} - -type backendSmokeTestConfig struct { - DefaultProfile *string `yaml:"default_profile"` - Reachability *reachabilityProbeConfig `yaml:"reachability"` - Authentication *authenticationProbeConfig `yaml:"authentication"` -} - -type reachabilityProbeConfig struct { - Endpoint *string `yaml:"endpoint"` -} - -type authenticationProbeConfig struct { - Kind *string `yaml:"kind"` - Endpoint *string `yaml:"endpoint"` -} - -type profileConfig struct { - ID string `yaml:"id"` - Backend *string `yaml:"backend"` - Endpoint *string `yaml:"endpoint"` - Model *string `yaml:"model"` - Temperature *float64 `yaml:"temperature"` - TopP *float64 `yaml:"top_p"` - MaxTokens *int `yaml:"max_tokens"` - TimeoutSeconds *int `yaml:"timeout_seconds"` - ServiceTier *string `yaml:"service_tier"` - ReasoningEffort *string `yaml:"reasoning_effort"` - APIKeyEnv *string `yaml:"api_key_env"` - APIKeyRequired *bool `yaml:"api_key_required"` - ExtraParams map[string]any `yaml:"extra_params"` -} - -type promptConfig struct { - ID string `yaml:"id"` - DefaultProfile *string `yaml:"default_profile"` - Description *string `yaml:"description"` - SessionID *string `yaml:"session_id"` - Inputs []promptInputConfig `yaml:"inputs"` - Messages []promptMessageConfig `yaml:"messages"` - Output *promptOutputConfig `yaml:"output"` -} - -type promptInputConfig struct { - Name string `yaml:"name"` - Required bool `yaml:"required"` - ContentType *string `yaml:"content_type"` - Description *string `yaml:"description"` -} - -type promptMessageConfig struct { - Role *string `yaml:"role"` - Content *string `yaml:"content"` - ContentFile *string `yaml:"content_file"` - CacheControl *cacheControlConfig `yaml:"cache_control"` -} - -type cacheControlConfig struct { - Type *string `yaml:"type"` - TTL *string `yaml:"ttl"` -} - -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"` -} +type collectionConfig = settings.CollectionSettings +type backendConfig = settings.BackendSettings +type profileConfig = settings.ProfileSettings +type promptConfig = settings.PromptSettings +type promptInputConfig = settings.PromptInputSettings +type promptMessageConfig = settings.PromptMessageSettings +type cacheControlConfig = settings.PromptCacheControlSettings +type promptOutputConfig = settings.PromptOutputSettings // fieldState distinguishes omission, an explicit value, and an explicit null. // Inherited values are explicit because ConfigKit has already expanded them. diff --git a/internal/configuration/prompts_test.go b/internal/configuration/prompts_test.go index 507ce15..71eeb1b 100644 --- a/internal/configuration/prompts_test.go +++ b/internal/configuration/prompts_test.go @@ -373,14 +373,13 @@ func TestLoadAcceptsEmptyInlineContentAndRejectsInvalidPromptFields(t *testing.T if _, _, err := state.prompt("exact.id"); !errors.Is(err, errPromptNotFound) { t.Fatalf("trimmed prompt identity unexpectedly matched: %v", err) } - _, err = load(mapping("obsolete-field", map[string]any{"prompts": []any{map[string]any{ + extended, err := load(mapping("application-field", map[string]any{"prompts": []any{map[string]any{ "version": "v1", "id": "example", "messages": []any{map[string]any{"role": "user", "content": "ok"}}, "output": map[string]any{"format": "text", "validation_mode": "basic"}, }}}), nil) - var loadError *configkit.LoadError - if !errors.As(err, &loadError) { - t.Fatalf("obsolete identity field should fail strict decoding: %v", err) + if err != nil || extended.result.Config.Prompts[0].Application["version"] != "v1" { + t.Fatalf("application field not retained: %+v, %v", extended, err) } _, err = load(mapping("null-prompt", map[string]any{"prompts": []any{nil}}), nil) if err == nil { diff --git a/internal/settings/settings.go b/internal/settings/settings.go new file mode 100644 index 0000000..118ef9c --- /dev/null +++ b/internal/settings/settings.go @@ -0,0 +1,187 @@ +// Package settings contains the shared public configuration data declarations. +package settings + +// Settings is the effective PromptKit configuration section. +type Settings struct { + // SchemaRoot is the default root for schema_path references. + SchemaRoot *string `yaml:"schema_root"` + // Backends defines the root backend resources. + Backends []BackendSettings `yaml:"backends"` + // Profiles defines the root profile resources. + Profiles []ProfileSettings `yaml:"profiles"` + // Prompts defines the root prompt resources. + Prompts []PromptSettings `yaml:"prompts"` + // Collections holds namespaced resources. + Collections map[string]CollectionSettings `yaml:"collections"` + // Application retains unrecognized application-owned fields. + Application map[string]any `yaml:",inline"` +} + +// CollectionSettings contains resources within one namespace. +type CollectionSettings struct { + // ReleaseVersion is descriptive collection metadata. + ReleaseVersion *string `yaml:"release_version"` + // SchemaRoot overrides the root schema directory for this collection. + SchemaRoot *string `yaml:"schema_root"` + // Backends defines collection backends. + Backends []BackendSettings `yaml:"backends"` + // Profiles defines collection profiles. + Profiles []ProfileSettings `yaml:"profiles"` + // Prompts defines collection prompts. + Prompts []PromptSettings `yaml:"prompts"` + // Application retains unrecognized application-owned fields. + Application map[string]any `yaml:",inline"` +} + +// BackendSettings describes an effective backend. +type BackendSettings struct { + // ID identifies the backend in its resource list. + ID string `yaml:"id"` + // Endpoint is the backend's absolute base URL. + Endpoint *string `yaml:"endpoint"` + // APIKeyEnv names an environment variable containing a credential. + APIKeyEnv *string `yaml:"api_key_env"` + // ConcurrencyLimit controls simultaneous generations; zero is unlimited. + ConcurrencyLimit *int `yaml:"concurrency_limit"` + // QueueCapacity controls waiting requests when concurrency is limited. + QueueCapacity *int `yaml:"queue_capacity"` + // ExtraParams supplies provider request defaults. + ExtraParams map[string]any `yaml:"extra_params"` + // SmokeTests supplies diagnostic settings. + SmokeTests *BackendSmokeTestConfig `yaml:"smoke_tests"` + // Application retains unrecognized application-owned fields. + Application map[string]any `yaml:",inline"` +} + +// ProfileSettings describes an effective execution profile. +type ProfileSettings struct { + // ID identifies the profile in its resource list. + ID string `yaml:"id"` + // Backend selects a backend by ID. + Backend *string `yaml:"backend"` + // Endpoint overrides the backend endpoint. + Endpoint *string `yaml:"endpoint"` + // Model selects the provider model. + Model *string `yaml:"model"` + // Temperature controls sampling temperature. + Temperature *float64 `yaml:"temperature"` + // TopP controls nucleus sampling. + TopP *float64 `yaml:"top_p"` + // MaxTokens limits generated tokens. + MaxTokens *int `yaml:"max_tokens"` + // TimeoutSeconds limits the model request duration. + TimeoutSeconds *int `yaml:"timeout_seconds"` + // ServiceTier selects a provider service tier. + ServiceTier *string `yaml:"service_tier"` + // ReasoningEffort selects provider reasoning effort. + ReasoningEffort *string `yaml:"reasoning_effort"` + // APIKeyEnv names an environment variable containing a credential. + APIKeyEnv *string `yaml:"api_key_env"` + // APIKeyRequired controls whether a credential is required. + APIKeyRequired *bool `yaml:"api_key_required"` + // ExtraParams supplies provider request parameters. + ExtraParams map[string]any `yaml:"extra_params"` + // Application retains unrecognized application-owned fields. + Application map[string]any `yaml:",inline"` +} + +// PromptSettings describes an effective prompt. +type PromptSettings struct { + // ID identifies the prompt in its resource list. + ID string `yaml:"id"` + // DefaultProfile selects the default profile ID. + DefaultProfile *string `yaml:"default_profile"` + // Description describes the prompt. + Description *string `yaml:"description"` + // SessionID is a session template. + SessionID *string `yaml:"session_id"` + // Inputs declares named prompt inputs. + Inputs []PromptInputSettings `yaml:"inputs"` + // Messages defines the prompt message templates. + Messages []PromptMessageSettings `yaml:"messages"` + // Output defines the output contract. + Output *PromptOutputSettings `yaml:"output"` + // Application retains unrecognized application-owned fields. + Application map[string]any `yaml:",inline"` +} + +// PromptInputSettings describes a declared prompt input. +type PromptInputSettings struct { + // Name is the input name. + Name string `yaml:"name"` + // Required indicates whether the input is required. + Required bool `yaml:"required"` + // ContentType identifies the input content type. + ContentType *string `yaml:"content_type"` + // Description describes the input. + Description *string `yaml:"description"` +} + +// PromptMessageSettings describes one prompt message. +type PromptMessageSettings struct { + // Role is the message role. + Role *string `yaml:"role"` + // Content is inline message template text. + Content *string `yaml:"content"` + // ContentFile names a source-relative message template. + ContentFile *string `yaml:"content_file"` + // CacheControl specifies message cache metadata. + CacheControl *PromptCacheControlSettings `yaml:"cache_control"` +} + +// PromptCacheControlSettings describes message cache metadata. +type PromptCacheControlSettings struct { + // Type identifies the cache-control mode. + Type *string `yaml:"type"` + // TTL selects an optional cache duration. + TTL *string `yaml:"ttl"` +} + +// PromptOutputSettings describes the configured output contract. +type PromptOutputSettings struct { + // Format identifies the output format. + Format *string `yaml:"format"` + // ValidationMode selects the output validation mode. + ValidationMode *string `yaml:"validation_mode"` + // Schema provides an inline JSON Schema. + Schema any `yaml:"schema"` + // SchemaFile names a source-relative JSON Schema. + SchemaFile *string `yaml:"schema_file"` + // SchemaPath names a JSON Schema under the selected schema root. + SchemaPath *string `yaml:"schema_path"` + // RepairAttempts sets an optional correction budget. + RepairAttempts *int `yaml:"repair_attempts"` +} + +// BackendSmokeTestConfig contains optional diagnostic settings associated with a backend. +type BackendSmokeTestConfig struct { + // DefaultProfile is the exact profile ID selected as the backend's + // diagnostic inference default. A supplied value must not be blank; the ID + // is resolved only when that default is selected. + DefaultProfile *string `json:"default_profile,omitempty" yaml:"default_profile,omitempty"` + // Reachability optionally selects a full HTTP destination for reachability + // diagnostics. A nil endpoint uses the effective backend endpoint. + Reachability *ReachabilityProbeConfig `json:"reachability,omitempty" yaml:"reachability,omitempty"` + // Authentication optionally declares a named authentication diagnostic. + // A supplied object requires Kind. + Authentication *AuthenticationProbeConfig `json:"authentication,omitempty" yaml:"authentication,omitempty"` +} + +// ReachabilityProbeConfig configures an optional reachability destination. +type ReachabilityProbeConfig struct { + // Endpoint is an absolute HTTP(S) URL, including any desired path or query. + // Nil selects the effective backend endpoint; an explicit blank value is + // invalid. + Endpoint *string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"` +} + +// AuthenticationProbeConfig configures an optional named authentication diagnostic. +type AuthenticationProbeConfig struct { + // Kind selects the authentication adapter. Supported values are "none" and + // "openrouter_key"; surrounding whitespace and case are normalized. + Kind *string `json:"kind,omitempty" yaml:"kind,omitempty"` + // Endpoint is an absolute HTTP(S) URL, including any desired path or query. + // Nil selects the adapter's backend-relative destination; an explicit blank + // value is invalid. + Endpoint *string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"` +} diff --git a/settings.go b/settings.go new file mode 100644 index 0000000..1fb5224 --- /dev/null +++ b/settings.go @@ -0,0 +1,39 @@ +package promptkit + +import "go.maximumdirect.net/promptkit/internal/settings" + +// Settings is the effective PromptKit configuration; see its field declarations. +type Settings = settings.Settings + +// CollectionSettings describes a namespace; see its field declarations. +type CollectionSettings = settings.CollectionSettings + +// BackendSettings describes a backend; see its field declarations. +type BackendSettings = settings.BackendSettings + +// ProfileSettings describes a profile; see its field declarations. +type ProfileSettings = settings.ProfileSettings + +// PromptSettings describes a prompt; see its field declarations. +type PromptSettings = settings.PromptSettings + +// PromptInputSettings describes a prompt input; see its field declarations. +type PromptInputSettings = settings.PromptInputSettings + +// PromptMessageSettings describes a message; see its field declarations. +type PromptMessageSettings = settings.PromptMessageSettings + +// PromptCacheControlSettings describes cache metadata; see its field declarations. +type PromptCacheControlSettings = settings.PromptCacheControlSettings + +// PromptOutputSettings describes an output contract; see its field declarations. +type PromptOutputSettings = settings.PromptOutputSettings + +// BackendSmokeTestConfig describes backend diagnostic settings; see its field declarations. +type BackendSmokeTestConfig = settings.BackendSmokeTestConfig + +// ReachabilityProbeConfig describes a diagnostic destination; see its field declarations. +type ReachabilityProbeConfig = settings.ReachabilityProbeConfig + +// AuthenticationProbeConfig describes authentication diagnostics; see its field declarations. +type AuthenticationProbeConfig = settings.AuthenticationProbeConfig diff --git a/settings_contract_test.go b/settings_contract_test.go new file mode 100644 index 0000000..9863696 --- /dev/null +++ b/settings_contract_test.go @@ -0,0 +1,67 @@ +package promptkit_test + +import ( + "encoding/json" + "strings" + "testing" + + "go.maximumdirect.net/configkit" + "go.maximumdirect.net/promptkit" +) + +func TestSharedSettingsDecode(t *testing.T) { + type application struct { + PromptKit promptkit.Settings `yaml:"promptkit"` + } + result, err := configkit.Load[application](configkit.Bytes("settings", []byte(`promptkit: + owner: application + backends: + - id: local + smoke_tests: + reachability: {endpoint: https://example.test/health} + authentication: {kind: none} + label: owned + collections: + group: + prompts: + - id: example + inputs: [] + messages: [{role: user, content: hello}] + output: {format: text, validation_mode: basic} + custom: true +`))) + if err != nil { + t.Fatal(err) + } + got := result.Config.PromptKit + if got.Application["owner"] != "application" || got.Backends[0].Application["label"] != "owned" || got.Collections["group"].Prompts[0].Application["custom"] != true { + t.Fatalf("application fields: %+v", got) + } + if got.Profiles != nil || got.Collections["group"].Prompts[0].Inputs == nil { + t.Fatalf("container presence: %+v", got) + } + encoded, err := json.Marshal(got.Backends[0].SmokeTests) + if err != nil || !strings.Contains(string(encoded), `"reachability":{"endpoint":"https://example.test/health"}`) { + t.Fatalf("smoke JSON = %s, %v", encoded, err) + } + _ = promptkit.Settings{Collections: map[string]promptkit.CollectionSettings{"group": {Backends: []promptkit.BackendSettings{{SmokeTests: &promptkit.BackendSmokeTestConfig{Reachability: &promptkit.ReachabilityProbeConfig{}, Authentication: &promptkit.AuthenticationProbeConfig{}}}}, Profiles: []promptkit.ProfileSettings{{}}, Prompts: []promptkit.PromptSettings{{Inputs: []promptkit.PromptInputSettings{{}}, Messages: []promptkit.PromptMessageSettings{{CacheControl: &promptkit.PromptCacheControlSettings{}}}, Output: &promptkit.PromptOutputSettings{}}}}}} +} + +func TestSharedSettingsKeepNestedFieldsStrict(t *testing.T) { + type application struct { + PromptKit promptkit.Settings `yaml:"promptkit"` + } + _, err := configkit.Load[application](configkit.Bytes("invalid", []byte("promptkit:\n prompts:\n - id: example\n output: {unknown: true}\n"))) + if err == nil { + t.Fatal("unknown nested field accepted") + } +} + +func TestSharedSmokeSettingsWorkWithBackendSource(t *testing.T) { + kind := "none" + source := promptkit.BackendSource("backend", []promptkit.BackendConfig{{ID: "example", SmokeTests: &promptkit.BackendSmokeTestConfig{Authentication: &promptkit.AuthenticationProbeConfig{Kind: &kind}}}}) + result, err := configkit.Load[promptkit.Settings](source) + if err != nil || result.Config.Backends[0].SmokeTests == nil || *result.Config.Backends[0].SmokeTests.Authentication.Kind != kind { + t.Fatalf("backend source = %+v, %v", result, err) + } +}