Files
promptkit/internal/configuration/load.go

464 lines
17 KiB
Go

// 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 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
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
}
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_]*$`)
// 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{
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)
}
}
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)
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"))}
}
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")
}
}
}
}