// Package configuration adapts ConfigKit's effective configuration to // Promptkit's definition and execution boundaries. package configuration import ( "fmt" "regexp" "sort" "strings" "go.maximumdirect.net/configkit" "go.maximumdirect.net/promptkit/internal/backend" "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 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. type fieldState uint8 const ( fieldAbsent fieldState = iota fieldValue fieldNull ) type loaded struct { view configkit.Inspection diagnostics []configkit.Diagnostic promptMetadata map[string][]promptInputPresence prompts map[string]*promptEntry registry *backend.Registry backendRecords map[string]backendConfig profileRecords map[string]profileConfig indexedProfiles map[string]domain.ExecutionProfile backendIDs []string profileIDs []string promptIDs []domain.PromptIdentity namespaces map[string][]string collections []CollectionIdentity } // Snapshot holds configuration resources captured for engine assembly. type Snapshot = loaded type resourceBases struct { backends configkit.Path profiles configkit.Path prompts configkit.Path } type resourceSet struct { isCollection bool namespace string bases resourceBases backends []backendConfig profiles []profileConfig prompts []promptConfig } func rootResourceBases() resourceBases { return resourceBases{ backends: configkit.Keys("promptkit", "backends"), profiles: configkit.Keys("promptkit", "profiles"), prompts: configkit.Keys("promptkit", "prompts"), } } func resourceSets(config *settings.Settings) []resourceSet { sets := make([]resourceSet, 0, len(config.Collections)+1) sets = append(sets, resourceSet{ bases: rootResourceBases(), backends: config.Backends, profiles: config.Profiles, prompts: config.Prompts, }) for _, namespace := range sortedKeys(config.Collections) { collection := config.Collections[namespace] base := configkit.Keys("promptkit", "collections", namespace) sets = append(sets, resourceSet{ isCollection: true, namespace: namespace, bases: resourceBases{ backends: base.Key("backends"), profiles: base.Key("profiles"), prompts: base.Key("prompts"), }, backends: collection.Backends, profiles: collection.Profiles, prompts: collection.Prompts, }) } return sets } func indexedResourceID(namespace, localKey string) string { qualified, valid := domain.QualifyLocalResourceID(namespace, localKey) if valid { return qualified } if namespace == "" { return localKey } return namespace + "/" + localKey } func indexedBackends(config *settings.Settings) map[string]backendConfig { backends := make(map[string]backendConfig) for _, resources := range resourceSets(config) { for _, definition := range resources.backends { backends[indexedResourceID(resources.namespace, definition.ID)] = definition } } return backends } func indexedProfiles(config *settings.Settings) map[string]profileConfig { profiles := make(map[string]profileConfig) for _, resources := range resourceSets(config) { for _, definition := range resources.profiles { profiles[indexedResourceID(resources.namespace, definition.ID)] = definition } } return profiles } var envName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`) // SequenceIdentities returns the component's native sequence registrations. func SequenceIdentities() []configkit.SequenceIdentity { return []configkit.SequenceIdentity{ configkit.SequenceIdentityAt(configkit.Keys("promptkit", "backends"), "id"), configkit.SequenceIdentityAt(configkit.Keys("promptkit", "profiles"), "id"), configkit.SequenceIdentityAt(configkit.Keys("promptkit", "prompts"), "id"), configkit.SequenceIdentityMatching(configkit.SequenceSelector{configkit.SequenceLiteralKey("promptkit"), configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey(), configkit.SequenceLiteralKey("backends")}, "id"), configkit.SequenceIdentityMatching(configkit.SequenceSelector{configkit.SequenceLiteralKey("promptkit"), configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey(), configkit.SequenceLiteralKey("profiles")}, "id"), configkit.SequenceIdentityMatching(configkit.SequenceSelector{configkit.SequenceLiteralKey("promptkit"), configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey(), configkit.SequenceLiteralKey("prompts")}, "id"), } } // Resolve normalizes the selected effective settings in place. func Resolve(config *settings.Settings, resolution *configkit.Resolution) { if config == nil { return } for _, resources := range resourceSets(config) { resolveBackends(resources.backends, resources.bases.backends, resolution) resolveProfiles(resources.profiles, resources.bases.profiles, resolution) resolvePrompts(resources.prompts, resources.bases.prompts, resolution) } } // Validate checks the selected effective settings. func Validate(config *settings.Settings, validation *configkit.Validation) { if config != nil { validateEffective(config, validation) } } // 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) state := &loaded{view: view, diagnostics: ownDiagnostics(diagnostics), promptMetadata: make(map[string][]promptInputPresence)} metadata := view.Metadata() for _, resources := range resourceSets(&config) { for index, entry := range resources.prompts { presence := make([]promptInputPresence, len(entry.Inputs)) for i := range entry.Inputs { path := resources.bases.prompts.Index(index).Key("inputs").Index(i) presence[i] = promptInputPresence{required: finalFieldState(metadata, path.Key("required")), contentType: finalFieldState(metadata, path.Key("content_type")), description: finalFieldState(metadata, path.Key("description"))} if entry.Inputs[i].Required { presence[i].required = fieldValue } } state.promptMetadata[indexedResourceID(resources.namespace, entry.ID)] = presence } } if err := state.materializePrompts(&config, metadata); err != nil { return nil, fmt.Errorf("load configuration: %w", err) } if err := state.buildExecutionProfiles(&config); err != nil { return nil, fmt.Errorf("load configuration: %w", err) } state.backendIDs = sortedKeys(indexedBackends(&config)) state.profileIDs = sortedKeys(state.indexedProfiles) for _, id := range sortedKeys(state.prompts) { state.promptIDs = append(state.promptIDs, domain.PromptIdentity{ID: id}) } state.namespaces = map[string][]string{ "backend": resourceNamespaces(state.backendIDs), "profile": resourceNamespaces(state.profileIDs), "prompt": promptNamespaces(state.promptIDs), } for _, namespace := range sortedKeys(config.Collections) { collection := config.Collections[namespace] state.collections = append(state.collections, CollectionIdentity{ Namespace: namespace, ReleaseVersion: stringPointerValue(collection.ReleaseVersion), }) } return state, nil } func finalFieldState(metadata configkit.Metadata, path configkit.Path) fieldState { info, exists := metadata.Lookup(path) if !exists || !info.Explicit { return fieldAbsent } if info.Null { return fieldNull } return fieldValue } func ownDiagnostics(values []configkit.Diagnostic) []configkit.Diagnostic { if values == nil { return nil } result := append([]configkit.Diagnostic(nil), values...) for i := range result { result[i].Primary = copyPointer(result[i].Primary) result[i].Related = append([]configkit.Location(nil), result[i].Related...) } return result } func resourceNamespaces(ids []string) []string { namespaces := make(map[string]struct{}) for _, id := range ids { if namespace, _, qualified := strings.Cut(id, "/"); qualified { namespaces[namespace] = struct{}{} } } return sortedKeys(namespaces) } func promptNamespaces(prompts []domain.PromptIdentity) []string { ids := make([]string, len(prompts)) for index := range prompts { ids[index] = prompts[index].ID } return resourceNamespaces(ids) } type promptInputPresence struct { required fieldState contentType fieldState description fieldState } // eligibleResourceList leaves invalid identities to the existing validation // boundaries, without mutating a list that cannot be recorded by identity. func eligibleResourceList[T any](entries []T, identity func(T) string) bool { seen := make(map[string]struct{}, len(entries)) for _, entry := range entries { id := identity(entry) if !domain.IsValidLocalResourceKey(id) { return false } if _, exists := seen[id]; exists { return false } seen[id] = struct{}{} } return true } func recordStringNormalization(value **string, path configkit.Path, resolution *configkit.Resolution, normalized string) { if *value != nil && **value != normalized { configkit.Normalize(resolution, path, value, &normalized, "Normalize configured value") } } func sortedKeys[T any](entries map[string]T) []string { keys := make([]string, 0, len(entries)) for key := range entries { keys = append(keys, key) } sort.Strings(keys) return keys } func validateEffective(config *settings.Settings, validation *configkit.Validation) { sets := resourceSets(config) backendIDs := make(map[string]struct{}) for _, resources := range sets { if resources.isCollection && !domain.IsValidResourceNamespace(resources.namespace) { validation.Error(configkit.Keys("promptkit", "collections", resources.namespace), "collection namespace must be nonblank and contain no slash") } for _, backend := range resources.backends { backendIDs[indexedResourceID(resources.namespace, backend.ID)] = struct{}{} } } for _, resources := range sets { for index, backend := range resources.backends { validateBackendRecord(backend, resources.bases.backends.Index(index), validation) } for index, profile := range resources.profiles { validateProfileRecord(profile, resources.bases.profiles.Index(index), backendIDs, validation) } for index, prompt := range resources.prompts { validatePromptRecord(prompt, resources.bases.prompts.Index(index), validation) } } } func validateBackendRecord(backend backendConfig, base configkit.Path, validation *configkit.Validation) { validateBackendEndpoints(backend, base, validation) if !domain.IsValidLocalResourceKey(backend.ID) { validation.Error(base.Key("id"), "backend ID must be a nonblank local key without a slash") } if backend.Endpoint == nil || *backend.Endpoint == "" { validation.Error(base.Key("endpoint"), "endpoint is required") } if backend.APIKeyEnv != nil && *backend.APIKeyEnv != "" && !envName.MatchString(*backend.APIKeyEnv) { validation.Error(base.Key("api_key_env"), "environment variable name is invalid") } if backend.ConcurrencyLimit != nil && *backend.ConcurrencyLimit < 0 { validation.Error(base.Key("concurrency_limit"), "concurrency limit must not be negative") } if backend.QueueCapacity != nil { if *backend.QueueCapacity < 0 { validation.Error(base.Key("queue_capacity"), "queue capacity must not be negative") } if backend.ConcurrencyLimit == nil || *backend.ConcurrencyLimit <= 0 { validation.Error(base.Key("queue_capacity"), "queue capacity requires a positive concurrency limit") } else if *backend.QueueCapacity > int(^uint(0)>>1)-*backend.ConcurrencyLimit { validation.Error(base.Key("queue_capacity"), "total capacity overflows int") } } validateExtraParams(backend.ExtraParams, base.Key("extra_params"), true, validation) if smokeTests := backend.SmokeTests; smokeTests != nil { smokePath := base.Key("smoke_tests") if smokeTests.DefaultProfile != nil { if strings.TrimSpace(*smokeTests.DefaultProfile) == "" { validation.Error(smokePath.Key("default_profile"), "default profile must not be blank") } else if !domain.IsValidResourceID(*smokeTests.DefaultProfile) { validation.Error(smokePath.Key("default_profile"), "default profile reference is malformed") } } if authentication := smokeTests.Authentication; authentication != nil { kindPath := smokePath.Key("authentication").Key("kind") if authentication.Kind == nil { validation.Error(kindPath, "authentication kind is required") } else if *authentication.Kind != "none" && *authentication.Kind != "openrouter_key" { validation.Error(kindPath, "authentication kind must be none or openrouter_key") } } } } func validateProfileRecord(profile profileConfig, base configkit.Path, backendIDs map[string]struct{}, validation *configkit.Validation) { if profile.Endpoint != nil && *profile.Endpoint != "" { if _, err := domain.NormalizeOpenAICompatibleBaseEndpoint(*profile.Endpoint); err != nil { validation.Error(base.Key("endpoint"), err.Error()) } } if !domain.IsValidLocalResourceKey(profile.ID) { validation.Error(base.Key("id"), "profile ID must be a nonblank local key without a slash") } if profile.Backend != nil && *profile.Backend != "" { if !domain.IsValidResourceID(*profile.Backend) { validation.Error(base.Key("backend"), "backend reference is malformed") } else if _, exists := backendIDs[*profile.Backend]; !exists { validation.Error(base.Key("backend"), "backend is not defined") } } if profile.Model != nil && *profile.Model != "" && strings.TrimSpace(*profile.Model) == "" { validation.Error(base.Key("model"), "model must not be blank") } if profile.Temperature != nil { if err := domain.ValidateExecutionTargetSettings(domain.ExecutionTarget{Temperature: *profile.Temperature}); err != nil { validation.Error(base.Key("temperature"), err.Error()) } } if profile.TopP != nil { if err := domain.ValidateExecutionTargetSettings(domain.ExecutionTarget{TopP: *profile.TopP}); err != nil { validation.Error(base.Key("top_p"), err.Error()) } } if profile.MaxTokens != nil { if err := domain.ValidateExecutionTargetSettings(domain.ExecutionTarget{MaxTokens: *profile.MaxTokens}); err != nil { validation.Error(base.Key("max_tokens"), err.Error()) } } if profile.TimeoutSeconds != nil { if err := domain.ValidateExecutionTargetSettings(domain.ExecutionTarget{TimeoutSeconds: *profile.TimeoutSeconds}); err != nil { validation.Error(base.Key("timeout_seconds"), err.Error()) } } validateExtraParams(profile.ExtraParams, base.Key("extra_params"), false, validation) } func validatePromptRecord(prompt promptConfig, base configkit.Path, validation *configkit.Validation) { if !domain.IsValidLocalResourceKey(prompt.ID) { validation.Error(base.Key("id"), "prompt ID must be a nonblank local key without a slash") } if prompt.DefaultProfile != nil && *prompt.DefaultProfile != "" && !domain.IsValidResourceID(*prompt.DefaultProfile) { validation.Error(base.Key("default_profile"), "default profile reference is malformed") } } func validateExtraParams(values map[string]any, path configkit.Path, backend bool, validation *configkit.Validation) { if values == nil { return } if _, err := jsonvalue.CopyMap(values); err != nil { validation.Error(path, "extra parameters must be a JSON-compatible map with nonempty keys") return } if backend { for key := range values { if llm.IsReservedOpenAIChatRequestField(key) { validation.Error(path.Key(key), "extra parameter conflicts with a request field") } } } }