|
|
|
|
@@ -1,7 +1,7 @@
|
|
|
|
|
# Configuration
|
|
|
|
|
|
|
|
|
|
This is the canonical reference for Notarius configuration. Configuration files
|
|
|
|
|
are YAML and must declare version 5. They select pipelines and their modules;
|
|
|
|
|
are YAML; the main file must declare version 5. They select pipelines and their modules;
|
|
|
|
|
the [CLI reference](cli.md) owns invocation syntax, and
|
|
|
|
|
[Operations](operations.md) owns run-state procedures.
|
|
|
|
|
|
|
|
|
|
@@ -11,17 +11,30 @@ Commands that load configuration choose a file in this order:
|
|
|
|
|
|
|
|
|
|
1. a non-empty **--config** CLI value;
|
|
|
|
|
2. a non-empty **NOTARIUS_CONFIG** environment value;
|
|
|
|
|
3. the installed default file at **/usr/local/etc/notarius/config.yml**, when
|
|
|
|
|
it exists.
|
|
|
|
|
3. `notarius.yml`, then `notarius.yaml` in the working directory;
|
|
|
|
|
4. the user configuration directory; then
|
|
|
|
|
5. the Unix system configuration directories.
|
|
|
|
|
|
|
|
|
|
The command fails if none of these paths provides a configuration file.
|
|
|
|
|
The user search checks `<user-config>/notarius/` for `notarius.yml`,
|
|
|
|
|
`notarius.yaml`, `config.yml`, `config.yaml`, `main.yml`, and `main.yaml`, in
|
|
|
|
|
that order, then `<user-config>/notarius.yml` and `notarius.yaml`. The system
|
|
|
|
|
search uses the same groups under `/usr/local/etc/notarius/` and `/etc/notarius/`,
|
|
|
|
|
then `/etc/notarius.yml` and `/etc/notarius.yaml`. Generic filenames in the
|
|
|
|
|
working directory are not candidates. Home-directory search is not enabled.
|
|
|
|
|
|
|
|
|
|
Discovery selects one main file; it does not layer all candidates. A missing
|
|
|
|
|
candidate advances the search, but an explicitly selected missing file, access
|
|
|
|
|
error, or invalid selected file fails without fallback. An exhausted search
|
|
|
|
|
fails. Use an explicit `--config` for services and subprocesses that need a
|
|
|
|
|
fixed selection independent of their working directory.
|
|
|
|
|
|
|
|
|
|
For configuration values, precedence is:
|
|
|
|
|
|
|
|
|
|
1. built-in defaults;
|
|
|
|
|
2. composed YAML sources, including imports;
|
|
|
|
|
3. the selected ConfigKit overlay; and
|
|
|
|
|
4. explicitly supplied configuration-valued run flags.
|
|
|
|
|
3. the selected ConfigKit overlay and inheritance;
|
|
|
|
|
4. typed decoding and explicitly supplied configuration-valued run flags; and
|
|
|
|
|
5. Notarius resolution and validation.
|
|
|
|
|
|
|
|
|
|
`--config-overlay` selects a ConfigKit overlay from `overlays/<name>.yml`
|
|
|
|
|
beneath the selected configuration root. Empty and `default` select no overlay.
|
|
|
|
|
@@ -38,7 +51,8 @@ have no effect; `NOTARIUS_CONFIG` remains a source-discovery input.
|
|
|
|
|
ordered steps, all implemented D&D lanes, generated references, state
|
|
|
|
|
settings, bounded LLM concurrency, and the maintained
|
|
|
|
|
[LLM profile](../examples/llm-profiles/dnd-extraction.yml) and imports its
|
|
|
|
|
pipeline from [a fragment](../examples/pipelines/dnd-session.yml).
|
|
|
|
|
pipeline from [a fragment](../examples/pipelines/dnd-session.yml), which imports
|
|
|
|
|
its [first step](../examples/pipelines/dnd-session.describe-session.yml).
|
|
|
|
|
|
|
|
|
|
The complete fragment also defines `dnd-session-development`, which inherits
|
|
|
|
|
the complete pipeline and profile while setting
|
|
|
|
|
@@ -102,24 +116,42 @@ Built-in relative destinations use the selected main configuration file's
|
|
|
|
|
directory; explicit `--output-dir` and `--debug-dir` values use the invocation
|
|
|
|
|
working directory. Absolute values remain unchanged.
|
|
|
|
|
|
|
|
|
|
The root file can use ConfigKit imports to compose disjoint definitions. Imports
|
|
|
|
|
and selected overlays remain under the configuration root; they do not merge or
|
|
|
|
|
append a pipeline's `steps` sequence. An overlay replaces sequences as defined
|
|
|
|
|
by ConfigKit, so changing an individual ordered binding requires supplying the
|
|
|
|
|
whole replacement sequence.
|
|
|
|
|
Use source-root `config` controls for imports and collection declarations. For
|
|
|
|
|
example, an essential fragment should explicitly be required:
|
|
|
|
|
|
|
|
|
|
~~~yaml
|
|
|
|
|
config:
|
|
|
|
|
imports:
|
|
|
|
|
- path: pipelines/session.yml
|
|
|
|
|
required: true
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
Imports are optional by default. ConfigKit supports paths, lists, directories,
|
|
|
|
|
globs, exclusions, recursive selection, destinations, and sequence-item placement;
|
|
|
|
|
its native input-root rules apply. Imported fragments need not declare a version.
|
|
|
|
|
The complete example places a mapping fragment at a step-list destination. Nested
|
|
|
|
|
application data named `config` is ordinary data, not a control block.
|
|
|
|
|
|
|
|
|
|
When migrating application files, rename genuine root `configkit` control
|
|
|
|
|
blocks to `config` in the main file and fragments. This is not a compatibility
|
|
|
|
|
alias: `configkit` is ordinary data under the new reader. PromptKit profile
|
|
|
|
|
documents still use their separate older engine and retain `configkit` controls;
|
|
|
|
|
see [PromptKit Profiles](#promptkit-profiles).
|
|
|
|
|
|
|
|
|
|
## Sibling Inheritance
|
|
|
|
|
|
|
|
|
|
ConfigKit v0.5.0 supports native `extends` composition in mappings. A directive
|
|
|
|
|
ConfigKit supports native `extends` composition in mappings and identified
|
|
|
|
|
sequence records. A directive
|
|
|
|
|
names exactly one immediate sibling in the same mapping; it is not a path or a
|
|
|
|
|
cross-scope lookup. Imports, the selected overlay, and explicit overrides are
|
|
|
|
|
composed before inheritance, which runs before typed decoding and normal
|
|
|
|
|
Notarius validation. Every definition, including a parent and definitions not
|
|
|
|
|
cross-scope lookup. Imports and the selected overlay are composed before
|
|
|
|
|
inheritance and typed decoding. Explicit CLI assignments follow decoding and
|
|
|
|
|
inheritance, before Notarius resolution and validation; they cannot repair an
|
|
|
|
|
earlier structural or decoding error. Every definition, including a parent and definitions not
|
|
|
|
|
selected for a run, remains subject to ordinary validation.
|
|
|
|
|
|
|
|
|
|
Child mappings recursively overlay parent mappings. A child sequence, scalar,
|
|
|
|
|
or null replaces the inherited value. This makes pipeline inheritance useful
|
|
|
|
|
for reusing a complete pipeline while replacing whole ordered lists:
|
|
|
|
|
Child mappings recursively overlay parent mappings. Scalars and null replace
|
|
|
|
|
inherited values. Unidentified sequences replace as whole values; pipeline
|
|
|
|
|
steps are identified by `id` and use native upsert by default:
|
|
|
|
|
|
|
|
|
|
~~~yaml
|
|
|
|
|
pipelines:
|
|
|
|
|
@@ -133,10 +165,31 @@ pipelines:
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
Pipeline names are siblings within `pipelines`; nested mappings such as named
|
|
|
|
|
artifact lanes also have their own sibling namespace. Step entries are a
|
|
|
|
|
sequence, so a step cannot extend another step. Replacing `steps` or a validator
|
|
|
|
|
chain supplies the complete replacement sequence; entries are not appended or
|
|
|
|
|
merged by identifier.
|
|
|
|
|
artifact lanes also have their own sibling namespace. Distinct imported step IDs
|
|
|
|
|
combine in source order; duplicate peer IDs conflict. Across an overlay or
|
|
|
|
|
inheritance, upsert replaces a matching step as a complete record in place and
|
|
|
|
|
appends new IDs. It does not merge individual fields of a matching step. An
|
|
|
|
|
identified record can itself use native `extends`. Authors may select `replace`
|
|
|
|
|
or `append` with a `config.sequences` declaration at the relevant destination;
|
|
|
|
|
an explicit replacement with `[]` clears the list, while empty append or upsert
|
|
|
|
|
does not. Notarius then validates the resulting pipeline, including its nonempty
|
|
|
|
|
step requirement. Validator chains are not automatically identified. Authors
|
|
|
|
|
may declare identities for other lists when needed. CLI list assignment replaces
|
|
|
|
|
the complete decoded list.
|
|
|
|
|
|
|
|
|
|
For example, an overlay can opt into replacing a pipeline's steps:
|
|
|
|
|
|
|
|
|
|
~~~yaml
|
|
|
|
|
config:
|
|
|
|
|
sequences:
|
|
|
|
|
- destination: [pipelines, production, steps]
|
|
|
|
|
mode: replace
|
|
|
|
|
pipelines:
|
|
|
|
|
production:
|
|
|
|
|
steps:
|
|
|
|
|
- id: extract
|
|
|
|
|
artifacts: {spells: {extract: {module: dnd/spells}}}
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
Inherited values count as explicit input for Notarius's existing
|
|
|
|
|
presence-sensitive rules: zero, false, and empty-list overrides stay explicit
|
|
|
|
|
|