581 lines
37 KiB
Markdown
581 lines
37 KiB
Markdown
# Configuration
|
|
|
|
This is the canonical reference for Notarius configuration fields, defaults,
|
|
source selection, and selectable modules. The sole application version is
|
|
`6` (also accepted as `"6"`). [CLI Reference](cli.md) owns invocation syntax;
|
|
[Operations](operations.md) owns physical state and recovery; integration
|
|
contracts own artifact payloads.
|
|
|
|
Upgrading an older deployment or caller? Use the
|
|
[native migration guide](consumers/native-migration.md).
|
|
|
|
## Configuration Discovery And Precedence
|
|
|
|
Configuration-consuming commands select one main file:
|
|
|
|
1. Explicit `--config`, which must not be empty.
|
|
2. Nonblank `NOTARIUS_CONFIG`.
|
|
3. `notarius.yml`, then `notarius.yaml`, in the working directory.
|
|
4. Go's user configuration directory: first its `notarius/` subdirectory,
|
|
trying `notarius.yml`, `notarius.yaml`, `config.yml`, `config.yaml`,
|
|
`main.yml`, `main.yaml`; then the two `notarius.*` names directly beneath it.
|
|
5. `/usr/local/etc/notarius/`, then `/etc/notarius/`, with those six names;
|
|
finally `/etc/notarius.yml` and `/etc/notarius.yaml`.
|
|
|
|
Generic working-directory filenames and home-directory searches are not enabled.
|
|
Missing discovery candidates advance the search; a selected missing, unreadable,
|
|
or invalid explicit source fails without fallback. Exhausted discovery fails.
|
|
Discovery selects a main file rather than layering every candidate.
|
|
Use explicit selection for services and subprocesses.
|
|
|
|
One ConfigKit result contains the application and native PromptKit settings.
|
|
Its source layers, from lower to higher priority, are:
|
|
|
|
1. The bundled OpenRouter resource underlay.
|
|
2. Embedded Notarius prompts/profiles and their filesystem-backed schema root.
|
|
3. Optional operator companions beside the **actual selected main file**:
|
|
`prompts.yml` and recursively selected `*.yml`/`*.yaml` files in `prompts/`.
|
|
These form one strict peer group: filenames do not confer priority and
|
|
conflicting contributions fail.
|
|
4. The selected application main source and its native import graph.
|
|
5. The selected ConfigKit overlay.
|
|
|
|
Companions are wrapperless native PromptKit settings mounted at `/promptkit`.
|
|
They are optional only when absent; malformed or unreadable selected content
|
|
fails. The loader does not search the invocation directory for substitute
|
|
companions. A companion's imports and content-file paths retain its native
|
|
source context. Main imports use their declared destinations; main-file native
|
|
settings belong beneath `promptkit`.
|
|
|
|
Source assembly, inheritance, typed defaults/decoding, explicit configuration
|
|
overrides, application normalization, and validation use ConfigKit's native
|
|
processing order. Overrides cannot repair earlier parse, composition, version,
|
|
inheritance, or decoding errors. The same captured result serves inspection and
|
|
engine construction, not a separate profile loader.
|
|
|
|
The overlay selector is a name: `development` selects
|
|
`overlays/development.yml` under the selected main source's configuration root.
|
|
Empty and exact lowercase `default` select the base. A missing selected overlay
|
|
fails; there is no overlay stack or extension fallback. Application overlays are
|
|
distinct from PromptKit profiles. See [ConfigKit's selected-overlay contract][overlays].
|
|
|
|
Only `NOTARIUS_CONFIG` participates in application environment selection.
|
|
Credential environment names are native PromptKit settings, not field-level
|
|
application environment overlays.
|
|
|
|
## Maintained Examples
|
|
|
|
- [Minimal](../examples/dnd-minimal/config.yml): embedded resources only, Seriatim
|
|
input, generic chunking, and one spell lane.
|
|
- [Complete](../examples/dnd-complete/config.yml): ordered steps and all D&D
|
|
families, generated references, independent state roots, workers, cache/mode/
|
|
turn controls, and selected domain auxiliaries. Its
|
|
[companion](../examples/dnd-complete/prompts.yml) demonstrates native profile
|
|
and backend inheritance without replacing native queue defaults.
|
|
- The complete [pipeline fragment](../examples/dnd-complete/pipelines/dnd-session.yml)
|
|
and [first-step fragment](../examples/dnd-complete/pipelines/dnd-session.describe-session.yml)
|
|
retain declaration-relative imports and references. Its development pipeline
|
|
selects a derived profile and zero semantic correction turns. The
|
|
[development overlay](../examples/dnd-complete/overlays/development.yml)
|
|
demonstrates serial workers and cache bypass.
|
|
|
|
The examples use separate directories so complete-example companions do not
|
|
alter minimal-example selection. Use these full files as starting points;
|
|
the fragments below illustrate individual settings.
|
|
|
|
## File Shape And Defaults
|
|
|
|
Application fields are strict. Unknown application fields, duplicate mapping
|
|
keys, blank identifiers, and identifiers duplicated after trimming are rejected.
|
|
PromptKit-owned resource records use the [native format][formats], including its
|
|
extension-field and strict nested-object rules; arbitrary extension fields are
|
|
not automatically secret.
|
|
|
|
| Root field | Type | Default / meaning |
|
|
| --- | --- | --- |
|
|
| `version` | integer or quoted string | Required; `6` only, without translation of older versions. |
|
|
| `promptkit` | native settings | Embedded and bundled resources, overlaid by selected sources. |
|
|
| `pipelines` | map | Empty; maps IDs to pipeline definitions. |
|
|
| `concurrency.workers` | positive integer | `64`; one shared ready-job pool. |
|
|
| `output.directory` | nonempty path | `./notarius-output`. |
|
|
| `cache_directory` | path | Omitted or empty selects `os.UserCacheDir()/notarius`. |
|
|
| `debug.directory` | path | Omitted selects `/tmp/notarius-debug`; explicit empty disables capture. |
|
|
|
|
Nonempty relative application destinations and reference paths resolve from the
|
|
file contributing the surviving declaration, including imported, overlaid, or
|
|
inherited values. A child replacement keeps the child's origin. Built-in relative
|
|
destinations use the selected main file's directory; invocation path overrides
|
|
use the working directory. Absolute paths remain absolute.
|
|
|
|
An empty output directory is invalid. Empty cache selection deliberately chooses
|
|
the per-user default; on Linux this normally follows `XDG_CACHE_HOME` or
|
|
`~/.cache`. Null is not a universal substitute for omission or empty: effective
|
|
types and application validation still apply. Directory selection does not
|
|
configure filesystem access policy or enable debug. See
|
|
[Operations](operations.md) for lifecycle, permissions, and provisioning.
|
|
|
|
## Imports And Sibling Inheritance
|
|
|
|
Root `config` contains native controls such as imports and sequence declarations.
|
|
For example:
|
|
|
|
~~~yaml
|
|
config:
|
|
imports:
|
|
- path: pipelines/dnd-session.yml
|
|
required: true
|
|
~~~
|
|
|
|
Imports are optional by default. Paths, directory selection, destinations,
|
|
sequence-item placement, source containment, and dependency-ready assembly order
|
|
follow [ConfigKit's import contract][imports]. Imported fragments need not repeat
|
|
the application version. A nested application field named `config` is ordinary
|
|
data, not another source-control block.
|
|
|
|
Mapping inheritance names a sibling, such as `extends: production` inside
|
|
`pipelines`. Identified-list inheritance uses an identity mapping such as
|
|
`extends: {id: parent}`. Parents must survive in the same sibling collection;
|
|
these are not paths or cross-namespace references.
|
|
|
|
Child mappings recursively overlay parents. Scalars and null replace inherited
|
|
values; an empty mapping does not clear existing fields. Lists follow their
|
|
native registered/declared composition policy. Pipeline steps are identified by
|
|
`id`: native upsert replaces a matching **whole record** in place and appends
|
|
new IDs. It does not patch fields of a matching step. Unidentified lists replace
|
|
as whole values across layers. Explicit replace with `[]` clears a list; empty
|
|
append/upsert does not. Validator lists are not automatically identified.
|
|
|
|
An identified record's `extends` can retain a distinct sibling's fields before
|
|
applying child changes. All surviving records remain real validated records,
|
|
not template-only definitions. Every final pipeline step executes and lane IDs
|
|
must be unique across the pipeline; inheriting a step's lanes does not remove
|
|
them. Pipeline-level inheritance with step upsert is suitable for full variants.
|
|
|
|
Omitted fields inherit; explicit zero, false, and empty collections retain their
|
|
presence. Null can clear an inherited value but remains subject to that field's
|
|
type and fallback semantics. Omitting `extends` retains a lower relationship;
|
|
`extends: null` cancels that relationship rather than independently deleting
|
|
other composed fields. `extends` is a reserved native configuration key, not
|
|
ordinary module-option data. See [native inheritance][inheritance] and
|
|
[sequence composition][sequences] for full rules.
|
|
|
|
Explicit configuration assignments use native mapping paths. They cannot walk
|
|
sequence indexes, assign the version, or introduce inheritance controls. Mapping
|
|
values overlay; list values replace the whole decoded list. Inheritance/defaulting
|
|
does not run again afterward. [CLI Reference](cli.md#configuration-selection)
|
|
owns assignment syntax.
|
|
|
|
## PromptKit Profiles
|
|
|
|
Native `promptkit` settings contain identified `backends`, `profiles`, and
|
|
`prompts` lists, plus a `collections` mapping. Notarius embeds its resources
|
|
in `collections.notarius`. Runtime IDs are qualified, for example
|
|
`notarius/dnd-extraction` and `notarius/dnd.spells`; the bundled root backend
|
|
is `openrouter`. Resource IDs are literal, not resource-version paths.
|
|
A collection's local record ID omits its namespace; references to resources in
|
|
that collection use the qualified runtime ID.
|
|
|
|
A wrapperless companion can add a profile variant:
|
|
|
|
~~~yaml
|
|
collections:
|
|
notarius:
|
|
profiles:
|
|
- id: campaign
|
|
extends: {id: dnd-extraction}
|
|
model: example-model
|
|
~~~
|
|
|
|
The pipeline can then select `llm_profile: notarius/campaign`. In the main
|
|
application file, place that same mapping beneath `promptkit`. The parent
|
|
reference is local to the same profile list; profile/backend references otherwise
|
|
name their intended exact ID. The [complete companion](../examples/dnd-complete/prompts.yml)
|
|
shows a runnable inherited backend/profile combination.
|
|
|
|
Later same-ID resources replace complete lower records, not selected fields.
|
|
Use a distinct inherited sibling to retain a parent's fields; replacing a record
|
|
with only one changed field does not implicitly keep the old definition.
|
|
Native `extends`, explicit null, list policy, and source contexts apply to
|
|
resources just as to other configuration. See [resource inheritance][resource-inheritance].
|
|
|
|
The embedded D&D profile selects `openrouter`, model `openai/gpt-5.6-luna`,
|
|
a `240` second timeout, and `flex` service tier, leaving reasoning unset.
|
|
Initial/correction pairs share their bundled default profile. Explicit application
|
|
profile selections and run overrides reach producers, validators, and correction
|
|
requests; validators can otherwise select their own profile.
|
|
|
|
A native backend supplies endpoint, credential-environment name, optional
|
|
capacity/queue controls, provider parameters, and explicit smoke metadata.
|
|
Profiles may supply backend or endpoint, model, sampling/token controls, timeout,
|
|
service tier, reasoning, credential policy, and provider parameters. Partial
|
|
profiles are valid; preparation must complete the actual target. Resource
|
|
inspection is not a backend-completed or run-overridden target prediction.
|
|
|
|
Notarius injects **no backend concurrency or queue defaults**. Native admission
|
|
is shared by backend ID within the engine, independently of workers; distinct
|
|
IDs do not automatically share capacity even if their endpoints match. An
|
|
endpoint-only profile has no backend identity. Configure native backend limits
|
|
when desired; the [upstream backend contract][backends] owns defaults and queue
|
|
semantics.
|
|
|
|
Profile omission, explicit values, and null differ. For example, native null
|
|
`endpoint` or `api_key_env` permits backend fallback, while an explicitly empty
|
|
string clears those sources; zero sampling values remain intentional. Blank/null
|
|
reasoning suppresses the outbound control. Changing backend/model does not
|
|
automatically clear unrelated explicit inherited settings. Use the
|
|
[native defaults table][profile-defaults], not inferred old-wrapper behavior.
|
|
|
|
Only credential environment **names** belong in files, never values. Native
|
|
secret-aware inspection preserves marked secret omissions; arbitrary prompt,
|
|
source, or extension data is not promised safe to disclose.
|
|
|
|
### Prompt Output Contracts And Schemas
|
|
|
|
Prompt declarations select response format, validation mode, and schema. Bundled
|
|
initial, correction, and validator prompts omit structural-repair counts:
|
|
Notarius inherits the upstream default, not an independent application-pinned
|
|
count. Native prompt customization can explicitly change that budget. Transient
|
|
provider retries are also native, distinct from application semantic turns.
|
|
See [native output contracts][output-contract].
|
|
|
|
Schemas may be inline, `schema_file` relative to its contributing source, or
|
|
`schema_path` within an explicit applicable `schema_root`. Exactly one schema
|
|
selection is used for JSON Schema mode. Null clears an alternative; switching
|
|
forms can require clearing the inherited selection. Native preparation reads
|
|
and compiles schemas; configuration/preflight does not read them.
|
|
|
|
Embedded Notarius prompts use their collection's filesystem-rooted schemas.
|
|
A nonnull collection root takes precedence over the root `promptkit.schema_root`;
|
|
absent/null collection roots fall back to that application root. A nonnull blank
|
|
root is invalid. Replacing `collections.notarius.schema_root` selects the new
|
|
context for its remaining path-based schemas. A missing file does not fall back
|
|
to embedded or working-directory roots. Other collections are unaffected.
|
|
Schema resources must be self-contained; native schema rules are in
|
|
[PromptKit's schema reference][schemas].
|
|
|
|
## Concurrency, Output, Cache, And Debug
|
|
|
|
`concurrency.workers` bounds active ready extraction and lane-completion jobs
|
|
together, including their validation/correction. It must be positive, has no
|
|
application maximum, and is independent of CPU count and native backend limits.
|
|
Explicit `1` gives serial jobs. Waiting for prerequisites occupies no worker;
|
|
nested validators do not request another worker. It is not a cross-backend
|
|
provider-call ceiling.
|
|
|
|
`output.directory`, `cache_directory`, and `debug.directory` select independent
|
|
roots. `/var/cache/notarius` is the convention for an explicitly provisioned
|
|
system-wide cache, not the per-user default. No directory setting creates a
|
|
permission policy or retention service.
|
|
|
|
A configured debug destination alone does not enable capture. Explicit empty
|
|
disables it; a nonempty invocation override can re-enable it. Native debug
|
|
selection and presentation modes are independent. See [CLI Reference](cli.md#run)
|
|
for invocation controls and [Operations](operations.md) for state handling.
|
|
|
|
## Pipelines
|
|
|
|
Each nonblank `pipelines` key defines a configured pipeline.
|
|
|
|
| Field | Type | Default / rules |
|
|
| --- | --- | --- |
|
|
| `llm_profile` | string | Optional qualified profile selection; explicit blank/null is invalid. |
|
|
| `mode` | `strict\|permissive` | Producer terminal mode; see below. |
|
|
| `max_additional_turns` | nonnegative integer | Semantic correction allowance excluding the initial response. |
|
|
| `cache` | `auto\|bypass\|refresh` | Eligible model-result reuse policy. |
|
|
| `input` | binding | Required. |
|
|
| `chunk` | binding | Defaults to `generic`. |
|
|
| `output` | binding | Defaults to `json`. |
|
|
| `artifacts` | lane map | Compact single-step form, mutually exclusive with `steps`. |
|
|
| `steps` | ordered list | Nonempty when selected; each record has a unique nonblank `id`, `artifacts`, and optional `references`. |
|
|
| `references` | map | External reference defaults for compatible targets. |
|
|
|
|
A lane ID is unique across all steps. Each lane requires `extract`, defaults
|
|
`merge` to `appendorder`, and defaults `normalize` to `noop`. References and
|
|
validator overrides belong on eligible bindings, not lane-wide fields.
|
|
Ordered steps finish before their generated artifacts feed later steps.
|
|
|
|
For each selected LLM role, profile precedence is explicit invocation override,
|
|
binding `llm_profile`, pipeline `llm_profile`, then native prompt default.
|
|
Deterministic roles do not receive LLM defaults/overrides and reject explicit
|
|
profile assignments. A supplied empty invocation profile clears the application
|
|
selection and lets the prompt default apply; configured blank profiles are invalid.
|
|
|
|
### Producer Controls
|
|
|
|
Chunk, extract, merge, and normalize bindings resolve controls before execution:
|
|
|
|
| Control | Precedence, highest first | Default |
|
|
| --- | --- | --- |
|
|
| `mode` | Binding, pipeline, application | `strict` |
|
|
| `max_additional_turns` | Binding, pipeline, application | `2` |
|
|
| `cache` | Explicit invocation cache, binding, pipeline, application | `auto` |
|
|
|
|
Omission inherits. Zero turns disables semantic correction; a positive allowance
|
|
is not a requirement to use every turn. The complete applicable validator chain
|
|
assesses each usable initial/revised candidate, including the final permitted
|
|
response. Native coordination owns conversation/iteration; the allowance does
|
|
not count transport retries or structural repair. Deterministic work does not
|
|
acquire conversations or generic retries.
|
|
|
|
Strict requires an accepted result. Permissive explicitly permits only the
|
|
module's supported fallback, with intrinsic shape/source/downstream checks,
|
|
without claiming ordinary semantic approval or rerunning the normal chain.
|
|
A whole-source D&D scene plan, empty extraction collection where valid, or safe
|
|
final normalization groups/merged input are supported directions. Scene
|
|
descriptions cannot use an invalid empty collection or fabricated description.
|
|
Unsupported fallback construction fails; cancellation stops without fallback.
|
|
|
|
Eligible cacheable work uses `auto` to read/store accepted results, `bypass`
|
|
for neither, and `refresh` to skip reads and replace only after new acceptance.
|
|
Failures preserve earlier acceptance. Fallback and actually affected dependent
|
|
work skip both lookup and storage; unrelated predecessors remain reusable.
|
|
Settings/policy changes may still reuse old accepted content; select bypass/
|
|
refresh when deliberately applying changed policy. Best-effort cache I/O does
|
|
not fail otherwise successful work. [Operations](operations.md) owns recovery
|
|
and physical storage, not a checkpoint/resume contract.
|
|
|
|
## Module Bindings And Validators
|
|
|
|
Every module binding is an object containing `module`, even without options.
|
|
|
|
| Binding field | Meaning |
|
|
| --- | --- |
|
|
| `module` | Registered compatible key; required. |
|
|
| `llm_profile` | Optional nonblank qualified profile for an LLM-backed role. |
|
|
| `mode`, `max_additional_turns`, `cache` | Resolved producer controls above. |
|
|
| `options` | Selected module's strict option object. |
|
|
| `references` | Declared slots on chunk/extract/merge/normalize bindings. |
|
|
| `validators` | Ordered replacement chain on those producer bindings. |
|
|
|
|
Omitted validators use the production default. `validators: []` replaces it
|
|
with an empty chain; a nonempty list replaces it in listed order. Null is not an
|
|
empty list. Validator bindings accept only `module`, optional LLM-backed
|
|
`llm_profile`, and `options`; they have no separate producer mode, semantic-turn
|
|
allowance, references, or nested validators. Each validator executes once per
|
|
candidate assessment. Intrinsic typed codec/source checks remain even with an
|
|
empty configured chain.
|
|
|
|
The `json` output options are:
|
|
|
|
| Option | Default / rules |
|
|
| --- | --- |
|
|
| `include_chunk_map` | Boolean, default false; publish when enabled and available. |
|
|
| `evidence_context` | Omitted disables publication; otherwise a strict object. |
|
|
| `evidence_context.enabled` | Required boolean; false permits no other evidence fields. |
|
|
| `evidence_context.lanes` | When enabled, required nonempty list of unique trimmed configured lane IDs. |
|
|
| `evidence_context.window_units` | When enabled, nonnegative integer, default `3`; zero keeps only directly cited units. |
|
|
|
|
Filtered-out configured lanes contribute no evidence. Unknown or incompatible
|
|
options fail. Evidence is opt-in because it can persist source text and metadata.
|
|
Logical formats belong to [chunk-map](integrations/chunk-map.md) and
|
|
[evidence-context](integrations/evidence-context.md) contracts.
|
|
|
|
## References And Ordered Handoffs
|
|
|
|
Reference maps bind named slots that the selected target declares. An external
|
|
reference is an object with `path`. Pipeline-level maps accept only external
|
|
paths; step-local and binding-local maps may also select a normalized artifact
|
|
from an earlier step:
|
|
|
|
~~~yaml
|
|
steps:
|
|
- id: describe-session
|
|
artifacts:
|
|
npc-registry:
|
|
extract:
|
|
module: dnd/npc-registry
|
|
normalize:
|
|
module: dnd/npc-registry
|
|
- id: extract-events
|
|
references:
|
|
npc_registry:
|
|
artifact:
|
|
step: describe-session
|
|
lane: npc-registry
|
|
artifacts:
|
|
spells:
|
|
extract:
|
|
module: dnd/spells
|
|
normalize:
|
|
module: dnd/spells
|
|
~~~
|
|
|
|
An artifact selector contains only **step** and **lane**. The producer must be
|
|
an earlier step and the selected artifact must be compatible with the consumer
|
|
slot. A generated binding supplies one normalized artifact in memory, including a
|
|
supported qualified fallback; it does not name a file. A configured generated
|
|
dependency remains required even when that consumer slot is otherwise optional.
|
|
|
|
Pipeline references are configuration defaults. A matching step-local or
|
|
binding-local external path overrides a pipeline default. CLI reference
|
|
bindings are then operational overrides of configured external paths; their
|
|
pipeline, lane, and binding scopes and precedence are defined by the
|
|
[CLI reference](cli.md#reference-selectors). A CLI file reference cannot
|
|
replace a configured generated artifact handoff. Required slots must be bound
|
|
after configuration and CLI reference actions are applied. A YAML reference
|
|
path resolves from the file that supplies its surviving declaration, including
|
|
an imported fragment or selected overlay. CLI reference paths resolve relative
|
|
to the process working directory.
|
|
|
|
### D&D Reference Slots
|
|
|
|
The following slot names are accepted by the implemented D&D modules when the
|
|
selected target declares them:
|
|
|
|
| Slot | Source and use |
|
|
| --- | --- |
|
|
| **party** | Optional text campaign context. This is the canonical party-roster spelling. |
|
|
| **roster** | Accepted compatibility alias for **party**. |
|
|
| **players** | Optional text player context. |
|
|
| **glossary** | Optional text campaign glossary. |
|
|
| **spell_catalog** | Optional JSON spell-catalog overlay for spell extraction and normalization. See [spell-catalog overlays](integrations/dnd-spell-catalog-overlays.md). |
|
|
| **location_registry** | Required normalized location registry for location-occurrence extraction and normalization. |
|
|
| **item_registry** | Required normalized item registry for item-occurrence extraction and normalization. |
|
|
| **npc_registry** | Normalized NPC registry. Optional for spells and combat turns; required for NPC occurrences and enemy-event extraction and normalization. |
|
|
| **scene_descriptions** | Required normalized scene-description artifact for combat-turn and enemy-event extraction. |
|
|
| **combat_turns** | Required normalized combat-turn artifact for enemy-event extraction. |
|
|
| **npc_occurrences** | Required normalized NPC-occurrence artifact for enemy-event extraction. |
|
|
|
|
Registry-backed occurrence and enemy-event artifact slots have the following
|
|
exact binding contracts. Durable semantics and wire shapes remain in their
|
|
[NPC occurrence](integrations/dnd-npc-occurrence-artifacts.md),
|
|
[location occurrence](integrations/dnd-location-occurrence-artifacts.md),
|
|
[item occurrence](integrations/dnd-item-occurrence-artifacts.md), and
|
|
[enemy-event](integrations/dnd-enemy-event-artifacts.md) contracts.
|
|
|
|
| Slot | Accepted artifact kind | Media type | Maximum size | Required stage |
|
|
| --- | --- | --- | --- | --- |
|
|
| `npc_registry` | `dnd/npc-registry` | `application/json` | 1,048,576 bytes | extract and normalize |
|
|
| `scene_descriptions` | `dnd/scene-description-list` | `application/json` | 1,048,576 bytes | extract only |
|
|
| `combat_turns` | `dnd/combat-turn-list` | `application/json` | 1,048,576 bytes | extract only |
|
|
| `npc_occurrences` | `dnd/npc-occurrence-list` | `application/json` | 1,048,576 bytes | extract only |
|
|
| `location_registry` | `dnd/location-registry` | `application/json` | 1,048,576 bytes | location-occurrence extract and normalize |
|
|
| `item_registry` | `dnd/item-registry` | `application/json` | 1,048,576 bytes | item-occurrence extract and normalize |
|
|
|
|
Scene descriptions accept **party**, **players**, and **glossary**, but not
|
|
**roster**. NPC occurrences require **npc_registry** for both extraction and
|
|
normalization. Combat turns require **scene_descriptions** for extraction; the
|
|
normalized combat-turn module may use optional **npc_registry**. Location occurrences
|
|
require **location_registry** for extraction and normalization. Item occurrences require
|
|
**item_registry** for extraction and normalization. Enemy-event extraction requires all
|
|
four of its JSON artifact slots; its normalizer requires **npc_registry**.
|
|
The [complete example](../examples/dnd-complete/config.yml) shows the ordered
|
|
generated bindings.
|
|
|
|
## Production Module Keys
|
|
|
|
| Kind | Keys |
|
|
| --- | --- |
|
|
| Input | **seriatim** |
|
|
| Chunk | **generic**, **dnd/scenes** |
|
|
| Extract | **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** |
|
|
| Merge | **appendorder** |
|
|
| Normalize | **noop**, **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** |
|
|
| Output | **json** |
|
|
|
|
`dnd/scenes` and every D&D extractor are `llm_backed`. The
|
|
`dnd/npc-registry`, `dnd/location-registry`, and `dnd/item-registry`
|
|
normalizers are also `llm_backed` for bounded duplicate proposals; every other
|
|
D&D normalizer is `deterministic`. LLM-backed bindings use the effective
|
|
[PromptKit profile](#promptkit-profiles). The complete example binds each
|
|
registry in an earlier step before its occurrence consumer.
|
|
|
|
The D&D artifact contracts define each emitted schema:
|
|
[spells](integrations/dnd-spell-artifacts.md),
|
|
[NPC registry](integrations/dnd-npc-registry-artifacts.md),
|
|
[NPC occurrences](integrations/dnd-npc-occurrence-artifacts.md),
|
|
[combat turns](integrations/dnd-combat-turn-artifacts.md),
|
|
[item registry](integrations/dnd-item-registry-artifacts.md),
|
|
[item occurrences](integrations/dnd-item-occurrence-artifacts.md),
|
|
[scene descriptions](integrations/dnd-scene-description-artifacts.md),
|
|
[enemy events](integrations/dnd-enemy-event-artifacts.md),
|
|
[location registry](integrations/dnd-location-registry-artifacts.md), and
|
|
[location occurrences](integrations/dnd-location-occurrence-artifacts.md).
|
|
|
|
## Production Validator Keys And Default Chains
|
|
|
|
Available validator keys are:
|
|
|
|
| Family | Keys |
|
|
| --- | --- |
|
|
| Generic | **generic/always_accept**, **generic/always_reject**, **generic/valid_json**, **generic/valid_json_schema** |
|
|
| Spells | **extract/dnd/spells/shape**, **extract/dnd/spells/catalog**, **extract/dnd/spells/source_refs**, **extract/dnd/spells/source_relatedness** |
|
|
| NPC registry | **extract/dnd/npc-registry/shape**, **extract/dnd/npc-registry/source_refs**, **extract/dnd/npc-registry/source_relatedness**, **normalize/dnd/npc-registry/identity** |
|
|
| Combat turns | **extract/dnd/combat-turns/shape**, **extract/dnd/combat-turns/source_refs**, **extract/dnd/combat-turns/source_relatedness**, **normalize/dnd/combat-turns/invariants** |
|
|
| Item occurrences | **extract/dnd/item-occurrences/shape**, **extract/dnd/item-occurrences/registry**, **extract/dnd/item-occurrences/source_refs**, **extract/dnd/item-occurrences/source_relatedness**, **normalize/dnd/item-occurrences/invariants** |
|
|
| Item registry | **extract/dnd/item-registry/shape**, **extract/dnd/item-registry/source_refs**, **extract/dnd/item-registry/source_relatedness**, **normalize/dnd/item-registry/identity** |
|
|
| NPC occurrences | **extract/dnd/npc-occurrences/shape**, **extract/dnd/npc-occurrences/registry**, **extract/dnd/npc-occurrences/source_refs**, **extract/dnd/npc-occurrences/source_relatedness**, **normalize/dnd/npc-occurrences/invariants** |
|
|
| Scene descriptions | **extract/dnd/scene-descriptions/shape**, **extract/dnd/scene-descriptions/source_refs**, **extract/dnd/scene-descriptions/source_relatedness**, **extract/dnd/scene-descriptions/combat_semantics** (LLM-backed, opt-in), **normalize/dnd/scene-descriptions/invariants** |
|
|
| Enemy events | **extract/dnd/enemy-events/shape**, **extract/dnd/enemy-events/engagements**, **extract/dnd/enemy-events/source_refs**, **extract/dnd/enemy-events/source_relatedness**, **normalize/dnd/enemy-events/invariants** |
|
|
| Location registry | **extract/dnd/location-registry/shape**, **extract/dnd/location-registry/source_refs**, **extract/dnd/location-registry/source_relatedness**, **normalize/dnd/location-registry/identity** |
|
|
| Location occurrences | **extract/dnd/location-occurrences/shape**, **extract/dnd/location-occurrences/registry**, **extract/dnd/location-occurrences/source_refs**, **extract/dnd/location-occurrences/source_relatedness**, **normalize/dnd/location-occurrences/invariants** |
|
|
|
|
`extract/dnd/scene-descriptions/combat_semantics` is not in a production default chain. To opt in, replace the scene extractor validator chain with the current ordered chain plus the semantic validator last, and retain a positive semantic-turn allowance if a rejection should request a corrected scene:
|
|
|
|
~~~yaml
|
|
extract:
|
|
module: dnd/scene-descriptions
|
|
max_additional_turns: 1
|
|
validators:
|
|
- module: generic/valid_json
|
|
- module: extract/dnd/scene-descriptions/shape
|
|
- module: extract/dnd/scene-descriptions/source_refs
|
|
- module: generic/valid_json_schema
|
|
- module: extract/dnd/scene-descriptions/source_relatedness
|
|
- module: extract/dnd/scene-descriptions/combat_semantics
|
|
~~~
|
|
|
|
An override replaces, rather than extends, the default chain. See [Module Bindings And Validators](#module-bindings-and-validators) for binding and profile rules, and [producer controls](#producer-controls) for semantic correction and terminal mode.
|
|
|
|
The validator runs once per candidate assessment. Native transient retries and
|
|
structural repair remain internal to that execution; there is no separate
|
|
validator semantic-turn allowance.
|
|
|
|
When no override is configured, production D&D bindings use the following
|
|
ordered chains. Each row lists extract then normalize; spell chains are the
|
|
same at both stages.
|
|
|
|
| Lane | Extract | Normalize |
|
|
| --- | --- | --- |
|
|
| Spells | generic/valid_json, extract/dnd/spells/shape, extract/dnd/spells/catalog, extract/dnd/spells/source_refs, generic/valid_json_schema, extract/dnd/spells/source_relatedness | Same as extract |
|
|
| NPC registry | generic/valid_json, extract/dnd/npc-registry/shape, extract/dnd/npc-registry/source_refs, generic/valid_json_schema, extract/dnd/npc-registry/source_relatedness | generic/valid_json, extract/dnd/npc-registry/shape, normalize/dnd/npc-registry/identity, extract/dnd/npc-registry/source_refs, generic/valid_json_schema, extract/dnd/npc-registry/source_relatedness |
|
|
| Combat turns | generic/valid_json, extract/dnd/combat-turns/shape, extract/dnd/combat-turns/source_refs, generic/valid_json_schema, extract/dnd/combat-turns/source_relatedness | generic/valid_json, extract/dnd/combat-turns/shape, normalize/dnd/combat-turns/invariants, extract/dnd/combat-turns/source_refs, generic/valid_json_schema, extract/dnd/combat-turns/source_relatedness |
|
|
| Item occurrences | generic/valid_json, extract/dnd/item-occurrences/shape, extract/dnd/item-occurrences/registry, extract/dnd/item-occurrences/source_refs, generic/valid_json_schema, extract/dnd/item-occurrences/source_relatedness | generic/valid_json, extract/dnd/item-occurrences/shape, extract/dnd/item-occurrences/registry, normalize/dnd/item-occurrences/invariants, extract/dnd/item-occurrences/source_refs, generic/valid_json_schema, extract/dnd/item-occurrences/source_relatedness |
|
|
| Item registry | generic/valid_json, extract/dnd/item-registry/shape, extract/dnd/item-registry/source_refs, generic/valid_json_schema, extract/dnd/item-registry/source_relatedness | generic/valid_json, extract/dnd/item-registry/shape, normalize/dnd/item-registry/identity, extract/dnd/item-registry/source_refs, generic/valid_json_schema, extract/dnd/item-registry/source_relatedness |
|
|
| NPC occurrences | generic/valid_json, extract/dnd/npc-occurrences/shape, extract/dnd/npc-occurrences/registry, extract/dnd/npc-occurrences/source_refs, generic/valid_json_schema, extract/dnd/npc-occurrences/source_relatedness | generic/valid_json, extract/dnd/npc-occurrences/shape, extract/dnd/npc-occurrences/registry, normalize/dnd/npc-occurrences/invariants, extract/dnd/npc-occurrences/source_refs, generic/valid_json_schema, extract/dnd/npc-occurrences/source_relatedness |
|
|
| Scene descriptions | generic/valid_json, extract/dnd/scene-descriptions/shape, extract/dnd/scene-descriptions/source_refs, generic/valid_json_schema, extract/dnd/scene-descriptions/source_relatedness | generic/valid_json, extract/dnd/scene-descriptions/shape, normalize/dnd/scene-descriptions/invariants, extract/dnd/scene-descriptions/source_refs, generic/valid_json_schema, extract/dnd/scene-descriptions/source_relatedness |
|
|
| Enemy events | generic/valid_json, extract/dnd/enemy-events/shape, extract/dnd/enemy-events/engagements, extract/dnd/enemy-events/source_refs, generic/valid_json_schema, extract/dnd/enemy-events/source_relatedness | generic/valid_json, extract/dnd/enemy-events/shape, normalize/dnd/enemy-events/invariants, extract/dnd/enemy-events/source_refs, generic/valid_json_schema, extract/dnd/enemy-events/source_relatedness |
|
|
| Location registry | generic/valid_json, extract/dnd/location-registry/shape, extract/dnd/location-registry/source_refs, generic/valid_json_schema, extract/dnd/location-registry/source_relatedness | generic/valid_json, extract/dnd/location-registry/shape, normalize/dnd/location-registry/identity, extract/dnd/location-registry/source_refs, generic/valid_json_schema, extract/dnd/location-registry/source_relatedness |
|
|
| Location occurrences | generic/valid_json, extract/dnd/location-occurrences/shape, extract/dnd/location-occurrences/registry, extract/dnd/location-occurrences/source_refs, generic/valid_json_schema, extract/dnd/location-occurrences/source_relatedness | generic/valid_json, extract/dnd/location-occurrences/shape, extract/dnd/location-occurrences/registry, normalize/dnd/location-occurrences/invariants, extract/dnd/location-occurrences/source_refs, generic/valid_json_schema, extract/dnd/location-occurrences/source_relatedness |
|
|
|
|
Chains are only registered for the D&D extract and normalize modules shown
|
|
above; select an explicit override when a different compatible chain is
|
|
required.
|
|
|
|
## Validation And Inspection
|
|
|
|
Configuration validation checks the selected native application document.
|
|
Pipeline validation additionally resolves production modules/options, validator
|
|
targets, references, generated handoffs, and statically known prompt/profile
|
|
dependencies. It needs no transcript, reference bytes, credential values,
|
|
provider calls, or state directories. Partial profiles pass; request-time data
|
|
and dynamic selections remain runtime checks. [CLI Reference](cli.md#pipeline-commands)
|
|
owns commands for both boundaries.
|
|
|
|
Native whole-app and focused PromptKit inspection use the same selected result
|
|
and secret-aware provenance. Profile inspection describes stored fields, not a
|
|
prediction of a completed request; prepared preview is the native request boundary.
|
|
See [configuration commands](cli.md#configuration-commands) and
|
|
[PromptKit commands](cli.md#promptkit-commands).
|
|
|
|
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md
|
|
[backends]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#backend-definitions
|
|
[profile-defaults]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#defaults-and-overrides
|
|
[resource-inheritance]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#resource-inheritance
|
|
[output-contract]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#output-contract
|
|
[schemas]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#schemas
|
|
[imports]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#explicit-imports
|
|
[overlays]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#selected-overlays
|
|
[inheritance]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#sibling-inheritance
|
|
[sequences]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#strict-document-composition
|