From ddcba9c6397668960b7a08c003979bdcb12857a9 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 3 Oct 2026 17:43:58 +0000 Subject: [PATCH] Document backend configuration inheritance --- README.md | 3 +- docs/cli.md | 7 +++-- docs/config.md | 49 +++++++++++++++++++++++---------- docs/internal/sources.md | 6 ++++ docs/roadmap/implementation.md | 8 +++++- examples/config.inheritance.yml | 18 ++++++++++++ 6 files changed, 71 insertions(+), 20 deletions(-) create mode 100644 examples/config.inheritance.yml diff --git a/README.md b/README.md index a6d0922..5ba7254 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,8 @@ a model. For complete invocation and output behavior, see the - [Minimal configuration](examples/config.yml) and [complete configuration](examples/config.full.yml), plus a - [composed import/overlay example](examples/config.composed.yml) + [composed import/overlay example](examples/config.composed.yml) and + [backend inheritance example](examples/config.inheritance.yml) - [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/) - [Render script](examples/render-markdown-summary.sh) diff --git a/docs/cli.md b/docs/cli.md index 31b78f2..ca327aa 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -252,9 +252,10 @@ The empty string selects the root; `/server/addr` selects a field; `~1` and according to the containing mapping or sequence. Dotted paths, file paths, and URL fragments are not accepted. ConfigKit writes a human-readable account of the effective value and its chronological default, base, overlay, CLI, -and normalization history, including removed historical values. This is not a -JSON schema or a byte-for-byte stable prose format. Unknown and malformed paths -exit 1 without successful explanation output. +normalization, and structural-inheritance history, including consumed +`extends` directives and removed values. This is not a JSON schema or a +byte-for-byte stable prose format. Unknown and malformed paths exit 1 without +successful explanation output. Diagnostics and warnings go to stderr, never into successful stdout. Parse, load, output, and diagnostic-write failures exit 1. Ordinary output writes may diff --git a/docs/config.md b/docs/config.md index d3948e6..c437393 100644 --- a/docs/config.md +++ b/docs/config.md @@ -22,7 +22,9 @@ exist and decode successfully. The maintained [minimal configuration](../examples/config.yml), [complete configuration](../examples/config.full.yml), and -[composed configuration](../examples/config.composed.yml) are copyable examples. +[composed configuration](../examples/config.composed.yml), and +[backend inheritance configuration](../examples/config.inheritance.yml) are +copyable examples. ## Application Configuration File @@ -113,24 +115,41 @@ claims to identify arbitrary secrets in unclassified parameter values. ### Application mapping inheritance -Application input mappings may use ConfigKit's `extends: sibling-name` -directive to inherit settings from a sibling mapping. Inheritance is resolved -after imports, a selected overlay, and explicit CLI overrides have been -assembled, and before typed decoding. Explicit child values replace inherited -values, and `extends: null` cancels inheritance. Parents remain ordinary -configured entries; for example, a parent backend is still registered and -validated with its child. See the pinned [ConfigKit v0.5.0 inheritance +Any application input mapping may use ConfigKit's `extends: sibling-name` +directive to inherit from a mapping among its immediate siblings. Names are +exact, and lookup does not search ancestor or unrelated mappings. ConfigKit +resolves inheritance after imports, a selected overlay, and explicit CLI +overrides have been assembled, and before typed decoding. It resolves every +effective relationship, even for a backend the selected profile does not use; +an invalid relationship in such a mapping still fails the load. + +The child retains its own mapping name. Explicit child values replace inherited +values, including zero, false, empty strings, sequences, and null where the +application field permits null; omitted values inherit. `extends: null` +cancels inheritance and keeps the child's own settings. The parent remains an +ordinary configured entry: a parent backend is registered and validated by +Promptkit along with other configured backends, not treated as an abstract +template. Inheritance copies settings but does not create a shared capacity +pool across distinct backend IDs. The maintained [backend inheritance +example](../examples/config.inheritance.yml) shows a complete parent and child. + +ConfigKit retains inherited origins and displaced values for inspection: +`show` presents the resolved result and `explain` describes derivation and +history. Inherited application paths retain their working-directory-relative +meaning. An inherited `api_key_env` remains a visible environment-variable +name passed to Promptkit; ConfigKit does not read its value. Promptkit prompt, +profile, and schema formats and HTTP request payloads are independently parsed +and do not acquire this directive. See the pinned [ConfigKit v0.5.0 inheritance contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance) -for detailed semantics. +for exact semantics. `extends` is reserved across application input mappings, not only under `backends`; quoting the key does not make it ordinary data. This can affect a -mapping entry named `extends` or a literal provider parameter with that name. -Rename an application-owned name where appropriate. A provider-required literal -key cannot generally be renamed without provider support, and this ConfigKit -version has no escape or opt-out; a concrete need must be addressed upstream. -The directive does not apply to separately parsed Promptkit definitions or -HTTP request payloads. +mapping name (such as a backend ID) or a literal provider parameter with that +name. Rename an application-owned name where appropriate. A provider-required +literal key cannot generally be renamed without provider support, and this +ConfigKit version has no escape or opt-out; a concrete need must be addressed +upstream. ## Custom Backends diff --git a/docs/internal/sources.md b/docs/internal/sources.md index 98694d3..a8a87e4 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -45,6 +45,12 @@ select one named overlay when requested. ConfigKit uses the selected file's canonical directory as the source root; the application does not widen it. Application path values retain process-working-directory-relative meaning. +ConfigKit resolves effective sibling inheritance after source assembly and +overrides, before typed decoding. Runtime conversion and Promptkit registration +consume those resolved values through the existing `Settings` path. The +[configuration reference](../config.md#application-mapping-inheritance) owns +the application-visible inheritance behavior. + Every configuration-loading command uses this boundary. The CLI maps only explicitly visited application flags to ConfigKit overrides and prints structured load diagnostics before engine construction. The old application diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 3b454f2..ee8373e 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -269,7 +269,13 @@ and all configured backends follow existing registration rules. ## Stage 4: Deliver A Maintained Example And Finish Current Documentation -Status: Pending. Depends on Stage 3. +Status: Complete. Depends on Stage 3. + +Completion evidence: added and linked the complete inheritance example, finished +the configuration contract, and updated CLI-history and source-internals +summaries. All five documented validate/show/sources/explain/render commands +succeeded without provider access; affected local and pinned upstream links, +current dependency references, and `git diff --check` passed. Files: new `examples/config.inheritance.yml`, `README.md`, `docs/config.md`, `docs/cli.md`, `docs/internal/sources.md`, and diff --git a/examples/config.inheritance.yml b/examples/config.inheritance.yml new file mode 100644 index 0000000..f6453c1 --- /dev/null +++ b/examples/config.inheritance.yml @@ -0,0 +1,18 @@ +# Application paths are relative to the repository invocation directory. +prompt_dir: ./examples/prompts +profile_dir: ./examples/profiles +schema_dir: ./examples/schemas + +backends: + local-base: + endpoint: http://localhost:11434/v1 + api_key_env: LOCAL_GPU_API_KEY + concurrency_limit: 2 + queue_capacity: 4 + extra_params: + provider_option: true + local-gpu: + extends: local-base + queue_capacity: 0 + extra_params: + provider_option: false