Document backend configuration inheritance

This commit is contained in:
2026-10-03 17:43:58 +00:00
parent 70f7e96d02
commit ddcba9c639
6 changed files with 71 additions and 20 deletions

View File

@@ -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)

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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