From ec26591b275bd74f89120bdea69c5f6459dfcafb Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 29 Sep 2026 15:07:21 +0000 Subject: [PATCH] Request named configuration inheritance for PromptKit --- .../feature-request-promptkit-inheritance.md | 131 ++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 docs/roadmap/feature-request-promptkit-inheritance.md diff --git a/docs/roadmap/feature-request-promptkit-inheritance.md b/docs/roadmap/feature-request-promptkit-inheritance.md new file mode 100644 index 0000000..9bf937a --- /dev/null +++ b/docs/roadmap/feature-request-promptkit-inheritance.md @@ -0,0 +1,131 @@ +# PromptKit Feature Request: Opt-In Named Configuration Inheritance + +Status: downstream proposal for ConfigKit consideration, not an approved scope +change, API design, or implementation plan. + +## Consumer Need + +PromptKit defines named execution profiles. A consumer can give an application +profile a stable name, reference another profile as its base, and override only +the settings it wants to change. Changing that base later does not require +updating every prompt or application setting that selects the application name. + +For example, an application-owned `weather-light` profile might derive from a +maintained standard profile and explicitly set a reasoning level or timeout. +Another profile can derive from `weather-light`, creating a chain. Multiple +children can share the same base. The selected child retains its own identity +while obtaining effective settings from its ancestors. + +PromptKit requests consideration of a reusable, opt-in named-inheritance +capability in ConfigKit. The goal is shared semantics for this structural +relationship, not knowledge of LLM models, endpoints, or execution policy. +ConfigKit should decide whether this belongs within its scope and what public +contract, if any, would be appropriate. + +## Distinction From Layered Loading + +The separate [filesystem and layered-loading request](feature-request-promptkit.md) +concerns acquiring configuration from different sources and combining it under +explicit composition or precedence rules. + +Named inheritance concerns relationships between configuration entries: a child +identifies a base, which may itself identify another base. The relationship +determines which entries contribute to the child's effective settings. Source +precedence and inheritance are different: choosing which definition owns an ID +does not itself resolve that definition's relationship to another ID. + +The earlier request assumes PromptKit retains relationship interpretation. This +proposal asks ConfigKit to reconsider that particular boundary; it does not +replace or expand the two already-requested prerequisites by implication. +Named inheritance remains optional for PromptKit's adoption of ConfigKit. + +## Desired Consumer Behavior + +- A caller can explicitly opt a collection of named entries into inheritance. + Ordinary configuration strings or similarly named fields must not acquire + reference semantics accidentally. +- An entry can reference one base by name, inherit its effective settings, and + override selected values. Single inheritance is sufficient for PromptKit; + this request does not seek multiple-parent conflict resolution. +- Chains and shared bases behave consistently regardless of declaration order. + A child's resolution does not mutate its base or change sibling results. +- Missing bases, self-reference, and longer cycles produce actionable errors + identifying the relevant entries and source locations where available. +- Omitted settings remain distinguishable from explicit zero, false, empty, + and null values. The chosen inheritance contract must explain which of these + inherit, replace, or clear rather than relying on Go zero-value heuristics. +- Consumers can identify the origins of inherited and overridden settings. + Sources may be embedded, file-backed, or programmatic; a host file path is + not always available. +- Callers can perform their domain validation on resolved settings without + teaching ConfigKit what those settings mean. + +These are behavior requests, not a proposed reserved `extends` key or API +signature. How a caller declares the collection, identity, and relationship is +for ConfigKit to decide. No automatic interpretation of arbitrary application +relationships is requested. + +## PromptKit Semantics To Consider + +PromptKit's proposed refactor uses a single effective definition for each profile +ID after source precedence has been applied. A base reference resolves within +that effective collection, including application overrides of maintained profiles. +Partial base profiles are useful even when they are not independently executable. + +Its current design direction is omission-based inheritance: explicit zero, false, +and empty values replace inherited settings where meaningful, while null means +unspecified for optional settings. Provider-parameter maps are atomic replacements, +including an explicitly empty map, rather than recursive combinations of keys. + +These details expose questions a shared contract must address; they are not a +request to build PromptKit-specific merge policies into ConfigKit. In particular, +generic recursive mapping overlay may not have the same meaning as a complete +provider-parameter replacement. PromptKit is pre-1.0 and can reconsider syntax +and semantics when a coherent shared design warrants it. Any remaining domain +exceptions should be explicit, not disguised as universal configuration rules. + +## Standardization Benefit + +The main benefit is consistency across consumers, not a large reduction in +PromptKit's code size. Applications can each write a small resolver, but differ +subtly in missing-reference handling, cycles, declaration-order dependence, +precedence, empty/null behavior, collection replacement, or inherited origins. +Those differences make configuration harder to transfer, explain, and maintain. + +A shared opt-in contract could let users learn these rules once and give +libraries a common diagnostic and provenance model. Similar needs could arise +in named processing presets, connection settings, or reusable job definitions; +these are potential use cases, not claims of existing consumer demand. + +The benefit depends on consumers adopting a meaningful common contract. If the +result requires arbitrary per-consumer merge and lookup strategies, much of that +standardization disappears. ConfigKit may reasonably conclude that keeping +relationship interpretation downstream is the better boundary. + +## Efficiency And Scope + +PromptKit expects to resolve definitions during construction and reuse the +results for ordinary executions. Large collections with shared ancestors should +not require repeated source loading, decoding, or avoidable repeated ancestor +work. Evaluate processing cost relative to entries, relationships, materialized +values, and retained provenance; this is not a fixed runtime or unconditional +linear-memory guarantee. No internal algorithm or storage representation is +prescribed here. + +The request excludes automatic hot reload, multiple inheritance, provider +availability checks, model selection policy, credential lookup timing, and +prompt execution. PromptKit continues to own LLM-specific validation and behavior +whether or not ConfigKit adopts structural inheritance. + +## Decision Requested From ConfigKit + +Please evaluate whether explicit, domain-neutral named inheritance fits +ConfigKit's scope, considering its [current configuration contract](../config.md) +and [deliberate exclusions](deferred.md). This request does not assert that an +earlier rejection exists or that any existing decision has been superseded. + +If accepted, define the shared consumer semantics and their relationship to +layered loading, including presence, collection handling, and origins. If deferred +or declined, PromptKit can retain its named-profile resolver while still adopting +ConfigKit's generic filesystem and layered-loading capabilities. Neither outcome +requires ConfigKit to understand the domain meaning of profile settings.