Document backend configuration inheritance
This commit is contained in:
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
18
examples/config.inheritance.yml
Normal file
18
examples/config.inheritance.yml
Normal 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
|
||||
Reference in New Issue
Block a user