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

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