Compose reusable configuration rules at the PromptKit path

This commit is contained in:
2026-11-21 14:18:15 +00:00
parent 76c8789e65
commit 34c0cf3f14
7 changed files with 207 additions and 88 deletions

38
configuration.go Normal file
View File

@@ -0,0 +1,38 @@
package promptkit
import (
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit/internal/configuration"
)
// Configure composes PromptKit's settings rules with an application definition.
// selectSettings identifies the application's PromptKit section and must be
// non-nil. A nil selected section is left untouched. Existing resolution and
// validation callbacks run first; callers may wrap the returned callbacks to
// run additional work afterward. Defaults and version policy are preserved.
func Configure[T any](definition configkit.Definition[T], selectSettings func(*T) *Settings) configkit.Definition[T] {
previousResolve := definition.Resolve
previousValidate := definition.Validate
previousSensitive := definition.Sensitive
identities := append([]configkit.SequenceIdentity(nil), definition.SequenceIdentities...)
definition.SequenceIdentities = append(identities, configuration.SequenceIdentities()...)
definition.Resolve = func(value *T, resolution *configkit.Resolution) error {
if previousResolve != nil {
if err := previousResolve(value, resolution); err != nil {
return err
}
}
configuration.Resolve(selectSettings(value), resolution)
return nil
}
definition.Validate = func(value *T, validation *configkit.Validation) {
if previousValidate != nil {
previousValidate(value, validation)
}
configuration.Validate(selectSettings(value), validation)
}
definition.Sensitive = func(path configkit.Path) bool {
return (previousSensitive != nil && previousSensitive(path)) || configuration.Sensitive(path)
}
return definition
}

View File

@@ -0,0 +1,99 @@
package promptkit_test
import (
"errors"
"strings"
"sync"
"testing"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
type rulesApplication struct {
Version string `yaml:"version"`
Other []rulesOther `yaml:"other"`
PromptKit *promptkit.Settings `yaml:"promptkit"`
}
type rulesOther struct {
ID string `yaml:"id"`
}
func TestConfigureComposesApplicationRules(t *testing.T) {
var events []string
definition := configkit.Definition[rulesApplication]{
Defaults: func() rulesApplication { return rulesApplication{Version: "app"} },
Version: &configkit.VersionRule{Path: configkit.Keys("version"), Check: func(v configkit.Version, validation *configkit.Validation) error {
events = append(events, "version")
return nil
}},
SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("other"), "id")},
Resolve: func(_ *rulesApplication, _ *configkit.Resolution) error {
events = append(events, "application resolve")
return nil
},
Validate: func(_ *rulesApplication, _ *configkit.Validation) { events = append(events, "application validate") },
Sensitive: func(path configkit.Path) bool { return path.String() == "/application_secret" },
}
configured := promptkit.Configure(definition, func(v *rulesApplication) *promptkit.Settings { return v.PromptKit })
if len(definition.SequenceIdentities) != 1 || len(configured.SequenceIdentities) != 7 {
t.Fatalf("registrations: %d, %d", len(definition.SequenceIdentities), len(configured.SequenceIdentities))
}
priorValidate := configured.Validate
configured.Validate = func(value *rulesApplication, validation *configkit.Validation) {
priorValidate(value, validation)
if value.PromptKit == nil || value.PromptKit.Backends[0].Endpoint == nil || strings.TrimSpace(*value.PromptKit.Backends[0].Endpoint) != *value.PromptKit.Backends[0].Endpoint {
validation.Error(configkit.Keys("promptkit"), "normalization did not run")
}
events = append(events, "after validate")
}
source := configkit.Bytes("rules", []byte("promptkit:\n backends:\n - id: local\n endpoint: ' https://example.test/v1/ '\n extra_params: {api_key: hidden}\nother: [{id: one}]\n"))
result, err := configkit.Load(source, configkit.Options[rulesApplication]{Definition: configured})
if err != nil {
var loadError *configkit.LoadError
if errors.As(err, &loadError) {
t.Fatalf("%v: %+v", err, loadError.Diagnostics())
}
t.Fatal(err)
}
if result.Config.Version != "app" || strings.Join(events, ",") != "version,application resolve,application validate,after validate" {
t.Fatalf("callbacks: %+v, %+v", result.Config, events)
}
if !configured.Sensitive(configkit.Keys("application_secret")) || !configured.Sensitive(configkit.Keys("promptkit", "backends").Index(0).Key("extra_params").Key("api_key")) || configured.Sensitive(configkit.Keys("backends").Index(0).Key("extra_params").Key("api_key")) {
t.Fatal("sensitivity composition failed")
}
var rendered strings.Builder
if err := result.WriteEffective(&rendered); err != nil || strings.Contains(rendered.String(), "hidden") {
t.Fatalf("redaction: %q, %v", rendered.String(), err)
}
}
func TestConfigurePropagatesResolveError(t *testing.T) {
want := errors.New("resolve failed")
definition := promptkit.Configure(configkit.Definition[rulesApplication]{Resolve: func(*rulesApplication, *configkit.Resolution) error { return want }}, func(v *rulesApplication) *promptkit.Settings { return v.PromptKit })
err := definition.Resolve(&rulesApplication{}, nil)
if !errors.Is(err, want) {
t.Fatalf("resolve error = %v", err)
}
}
func TestConfigureReusableAcrossConcurrentLoads(t *testing.T) {
definition := promptkit.Configure(configkit.Definition[rulesApplication]{}, func(v *rulesApplication) *promptkit.Settings { return v.PromptKit })
var group sync.WaitGroup
for range 8 {
group.Go(func() {
for _, source := range []string{"{}", "promptkit: {prompts: [{id: test, output: {format: text, validation_mode: basic}}]}"} {
result, err := configkit.Load(configkit.Bytes("settings", []byte(source)), configkit.Options[rulesApplication]{Definition: definition})
if err != nil {
t.Error(err)
continue
}
if result.Config.PromptKit != nil && *result.Config.PromptKit.Prompts[0].Output.RepairAttempts != 1 {
t.Error("default was not resolved")
}
}
})
}
group.Wait()
}

View File

@@ -323,6 +323,10 @@ adapter settings share one declaration set with no conversion layer between them
## Stage 5 — Extract Stateless Component Rules At Native Paths ## Stage 5 — Extract Stateless Component Rules At Native Paths
Status: complete. Focused registration tests passed under the race detector;
the old adapter tests do not compile against the new envelope and remain scheduled
for migration, while metadata capture moves to the next stage.
Focus: `internal/configuration/load.go`, `resolve_prompts.go`, Focus: `internal/configuration/load.go`, `resolve_prompts.go`,
`resolve_targets.go`, sensitivity paths, and public `Configure` wiring. `resolve_targets.go`, sensitivity paths, and public `Configure` wiring.

View File

@@ -48,12 +48,17 @@ func Diff(left, right Inspection) ([]configkit.Difference, error) {
return configkit.Diff(leftResult, rightResult) return configkit.Diff(leftResult, rightResult)
} }
func secretProviderPath(path configkit.Path) bool { // Sensitive marks credential-shaped provider values beneath PromptKit settings.
func Sensitive(path configkit.Path) bool {
pointer := path.String() pointer := path.String()
if pointer == "" { if pointer == "" {
return false return false
} }
parts := strings.Split(strings.TrimPrefix(pointer, "/"), "/") parts := strings.Split(strings.TrimPrefix(pointer, "/"), "/")
if len(parts) == 0 || parts[0] != "promptkit" {
return false
}
parts = parts[1:]
if !providerExtraParamsPath(parts) { if !providerExtraParamsPath(parts) {
return false return false
} }

View File

@@ -17,8 +17,8 @@ import (
) )
type document struct { type document struct {
Version *string `yaml:"version"` PromptKit settings.Settings `yaml:"promptkit"`
settings.Settings `yaml:",inline"` Application map[string]any `yaml:",inline"`
} }
type collectionConfig = settings.CollectionSettings type collectionConfig = settings.CollectionSettings
@@ -72,20 +72,20 @@ type resourceSet struct {
func rootResourceBases() resourceBases { func rootResourceBases() resourceBases {
return resourceBases{ return resourceBases{
backends: configkit.Keys("backends"), backends: configkit.Keys("promptkit", "backends"),
profiles: configkit.Keys("profiles"), profiles: configkit.Keys("promptkit", "profiles"),
prompts: configkit.Keys("prompts"), prompts: configkit.Keys("promptkit", "prompts"),
} }
} }
func resourceSets(config *document) []resourceSet { func resourceSets(config *settings.Settings) []resourceSet {
sets := make([]resourceSet, 0, len(config.Collections)+1) sets := make([]resourceSet, 0, len(config.Collections)+1)
sets = append(sets, resourceSet{ sets = append(sets, resourceSet{
bases: rootResourceBases(), backends: config.Backends, profiles: config.Profiles, prompts: config.Prompts, bases: rootResourceBases(), backends: config.Backends, profiles: config.Profiles, prompts: config.Prompts,
}) })
for _, namespace := range sortedKeys(config.Collections) { for _, namespace := range sortedKeys(config.Collections) {
collection := config.Collections[namespace] collection := config.Collections[namespace]
base := configkit.Keys("collections", namespace) base := configkit.Keys("promptkit", "collections", namespace)
sets = append(sets, resourceSet{ sets = append(sets, resourceSet{
isCollection: true, isCollection: true,
namespace: namespace, namespace: namespace,
@@ -113,7 +113,7 @@ func indexedResourceID(namespace, localKey string) string {
return namespace + "/" + localKey return namespace + "/" + localKey
} }
func indexedBackends(config *document) map[string]backendConfig { func indexedBackends(config *settings.Settings) map[string]backendConfig {
backends := make(map[string]backendConfig) backends := make(map[string]backendConfig)
for _, resources := range resourceSets(config) { for _, resources := range resourceSets(config) {
for _, definition := range resources.backends { for _, definition := range resources.backends {
@@ -123,7 +123,7 @@ func indexedBackends(config *document) map[string]backendConfig {
return backends return backends
} }
func indexedProfiles(config *document) map[string]profileConfig { func indexedProfiles(config *settings.Settings) map[string]profileConfig {
profiles := make(map[string]profileConfig) profiles := make(map[string]profileConfig)
for _, resources := range resourceSets(config) { for _, resources := range resourceSets(config) {
for _, definition := range resources.profiles { for _, definition := range resources.profiles {
@@ -140,34 +140,47 @@ func Load(main configkit.Input, underlays []configkit.Underlay) (*loaded, error)
return load(main, underlays) return load(main, underlays)
} }
func configurationDefinition(state *loaded) configkit.Definition[document] { // 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]{ return configkit.Definition[document]{
SequenceIdentities: []configkit.SequenceIdentity{ SequenceIdentities: SequenceIdentities(),
configkit.SequenceIdentityAt(configkit.Keys("backends"), "id"), Sensitive: Sensitive,
configkit.SequenceIdentityAt(configkit.Keys("profiles"), "id"),
configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
configkit.SequenceIdentityMatching(configkit.SequenceSelector{configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey(), configkit.SequenceLiteralKey("backends")}, "id"),
configkit.SequenceIdentityMatching(configkit.SequenceSelector{configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey(), configkit.SequenceLiteralKey("profiles")}, "id"),
configkit.SequenceIdentityMatching(configkit.SequenceSelector{configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey(), configkit.SequenceLiteralKey("prompts")}, "id"),
},
Version: &configkit.VersionRule{
Path: configkit.Keys("version"),
Check: checkConfigurationVersion,
},
Sensitive: secretProviderPath,
Resolve: func(config *document, resolution *configkit.Resolution) error { Resolve: func(config *document, resolution *configkit.Resolution) error {
for _, resources := range resourceSets(config) { Resolve(&config.PromptKit, resolution)
capturePromptMetadata(resources.prompts, resources.bases.prompts, resources.namespace, resolution, state.promptMetadata)
}
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)
}
return nil return nil
}, },
Validate: func(config *document, validation *configkit.Validation) { Validate: func(config *document, validation *configkit.Validation) {
validateEffective(config, validation) Validate(&config.PromptKit, validation)
}, },
} }
} }
@@ -178,9 +191,8 @@ func load(main configkit.Input, underlays []configkit.Underlay) (*loaded, error)
promptMetadata: make(map[string][]promptInputPresence), promptMetadata: make(map[string][]promptInputPresence),
} }
result, err := configkit.LoadLayered(main, configkit.LayeredOptions[document]{ result, err := configkit.LoadLayered(main, configkit.LayeredOptions[document]{
Underlays: underlays, Underlays: underlays,
SourceVersionMode: configkit.SourceVersionModeIfPresent, Definition: configurationDefinition(),
Definition: configurationDefinition(state),
}) })
if err != nil { if err != nil {
return nil, fmt.Errorf("load configuration: %w", err) return nil, fmt.Errorf("load configuration: %w", err)
@@ -192,7 +204,7 @@ func load(main configkit.Input, underlays []configkit.Underlay) (*loaded, error)
if err := state.buildExecutionProfiles(); err != nil { if err := state.buildExecutionProfiles(); err != nil {
return nil, fmt.Errorf("load configuration: %w", err) return nil, fmt.Errorf("load configuration: %w", err)
} }
state.backendIDs = sortedKeys(indexedBackends(&state.result.Config)) state.backendIDs = sortedKeys(indexedBackends(&state.result.Config.PromptKit))
state.profileIDs = sortedKeys(state.indexedProfiles) state.profileIDs = sortedKeys(state.indexedProfiles)
for _, id := range sortedKeys(state.prompts) { for _, id := range sortedKeys(state.prompts) {
state.promptIDs = append(state.promptIDs, domain.PromptIdentity{ID: id}) state.promptIDs = append(state.promptIDs, domain.PromptIdentity{ID: id})
@@ -202,8 +214,8 @@ func load(main configkit.Input, underlays []configkit.Underlay) (*loaded, error)
"profile": resourceNamespaces(state.profileIDs), "profile": resourceNamespaces(state.profileIDs),
"prompt": promptNamespaces(state.promptIDs), "prompt": promptNamespaces(state.promptIDs),
} }
for _, namespace := range sortedKeys(result.Config.Collections) { for _, namespace := range sortedKeys(result.Config.PromptKit.Collections) {
collection := result.Config.Collections[namespace] collection := result.Config.PromptKit.Collections[namespace]
state.collections = append(state.collections, CollectionIdentity{ state.collections = append(state.collections, CollectionIdentity{
Namespace: namespace, ReleaseVersion: stringPointerValue(collection.ReleaseVersion), Namespace: namespace, ReleaseVersion: stringPointerValue(collection.ReleaseVersion),
}) })
@@ -229,51 +241,12 @@ func promptNamespaces(prompts []domain.PromptIdentity) []string {
return resourceNamespaces(ids) return resourceNamespaces(ids)
} }
func checkConfigurationVersion(version configkit.Version, validation *configkit.Validation) error {
if !version.Present {
return nil
}
if version.Null || version.Text != "2" {
validation.Error(configkit.Keys("version"), "unsupported configuration specification version")
}
return nil
}
type promptInputPresence struct { type promptInputPresence struct {
required fieldState required fieldState
contentType fieldState contentType fieldState
description fieldState description fieldState
} }
func capturePromptMetadata(prompts []promptConfig, basePath configkit.Path, namespace string, resolution *configkit.Resolution, destination map[string][]promptInputPresence) {
for promptIndex, prompt := range prompts {
inputs := prompt.Inputs
states := make([]promptInputPresence, len(inputs))
base := basePath.Index(promptIndex).Key("inputs")
for index := range inputs {
path := base.Index(index)
states[index] = promptInputPresence{
required: captureFieldState(path.Key("required"), resolution),
contentType: captureFieldState(path.Key("content_type"), resolution),
description: captureFieldState(path.Key("description"), resolution),
}
}
destination[indexedResourceID(namespace, prompt.ID)] = states
}
}
func captureFieldState(path configkit.Path, resolution *configkit.Resolution) fieldState {
info, exists := resolution.EntryInfo(path)
switch {
case !exists || !info.Explicit:
return fieldAbsent
case info.Null:
return fieldNull
default:
return fieldValue
}
}
// eligibleResourceList leaves invalid identities to the existing validation // eligibleResourceList leaves invalid identities to the existing validation
// boundaries, without mutating a list that cannot be recorded by identity. // boundaries, without mutating a list that cannot be recorded by identity.
func eligibleResourceList[T any](entries []T, identity func(T) string) bool { func eligibleResourceList[T any](entries []T, identity func(T) string) bool {
@@ -306,12 +279,12 @@ func sortedKeys[T any](entries map[string]T) []string {
return keys return keys
} }
func validateEffective(config *document, validation *configkit.Validation) { func validateEffective(config *settings.Settings, validation *configkit.Validation) {
sets := resourceSets(config) sets := resourceSets(config)
backendIDs := make(map[string]struct{}) backendIDs := make(map[string]struct{})
for _, resources := range sets { for _, resources := range sets {
if resources.isCollection && !domain.IsValidResourceNamespace(resources.namespace) { if resources.isCollection && !domain.IsValidResourceNamespace(resources.namespace) {
validation.Error(configkit.Keys("collections", resources.namespace), "collection namespace must be nonblank and contain no slash") validation.Error(configkit.Keys("promptkit", "collections", resources.namespace), "collection namespace must be nonblank and contain no slash")
} }
for _, backend := range resources.backends { for _, backend := range resources.backends {
backendIDs[indexedResourceID(resources.namespace, backend.ID)] = struct{}{} backendIDs[indexedResourceID(resources.namespace, backend.ID)] = struct{}{}

View File

@@ -40,20 +40,20 @@ func (state *loaded) materializePrompts() error {
} }
return metadata.Lookup(path) return metadata.Lookup(path)
} }
applicationRoot, err := state.captureSchemaRoot(state.result.Config.SchemaRoot, configkit.Keys("schema_root"), lookupOrigin) applicationRoot, err := state.captureSchemaRoot(state.result.Config.PromptKit.SchemaRoot, configkit.Keys("promptkit", "schema_root"), lookupOrigin)
if err != nil { if err != nil {
return err return err
} }
roots := make(map[string]*domain.ResourceBinding, len(state.result.Config.Collections)) roots := make(map[string]*domain.ResourceBinding, len(state.result.Config.PromptKit.Collections))
for _, name := range sortedKeys(state.result.Config.Collections) { for _, name := range sortedKeys(state.result.Config.PromptKit.Collections) {
collection := state.result.Config.Collections[name] collection := state.result.Config.PromptKit.Collections[name]
root, err := state.captureSchemaRoot(collection.SchemaRoot, configkit.Keys("collections", name, "schema_root"), lookupOrigin) root, err := state.captureSchemaRoot(collection.SchemaRoot, configkit.Keys("promptkit", "collections", name, "schema_root"), lookupOrigin)
if err != nil { if err != nil {
return err return err
} }
roots[name] = root roots[name] = root
} }
for _, resources := range resourceSets(&state.result.Config) { for _, resources := range resourceSets(&state.result.Config.PromptKit) {
root := applicationRoot root := applicationRoot
if selected := roots[resources.namespace]; resources.isCollection && selected != nil { if selected := roots[resources.namespace]; resources.isCollection && selected != nil {
root = selected root = selected

View File

@@ -12,8 +12,8 @@ import (
) )
func (state *loaded) buildExecutionProfiles() error { func (state *loaded) buildExecutionProfiles() error {
backendConfigs := indexedBackends(&state.result.Config) backendConfigs := indexedBackends(&state.result.Config.PromptKit)
profileConfigs := indexedProfiles(&state.result.Config) profileConfigs := indexedProfiles(&state.result.Config.PromptKit)
state.backendRecords = backendConfigs state.backendRecords = backendConfigs
state.profileRecords = profileConfigs state.profileRecords = profileConfigs
definitions := make(map[string]domain.Backend, len(backendConfigs)) definitions := make(map[string]domain.Backend, len(backendConfigs))