README
¶
Notarius
Notarius is a Go CLI for turning source material into structured artifacts with configured extraction pipelines. The implemented D&D workflow reads Seriatim transcript JSON and can produce NPC, location, and item registries; their source-grounded occurrences; scene descriptions, combat turns, enemy events, and spell casts.
Quickstart
Provide an OpenRouter API key through the environment, then run the maintained minimal example:
OPENROUTER_API_KEY=your-api-key \
go run ./cmd/notarius run dnd-session \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json
The command publishes a JSON output bundle. Its command syntax and exit behavior are documented in the CLI reference; configuration, credentials, and module selection are owned by the configuration reference.
For the complete ordered D&D workflow, use the complete configuration with its synthetic transcript. It demonstrates all implemented D&D lanes and the supporting campaign references.
Install A Source Release
Install a pinned source release with Go:
GOWORK=off go install \
gitea.maximumdirect.net/eric/notarius/cmd/notarius@<tag>
Replace <tag> with a stable release tag such as vMAJOR.MINOR.PATCH. The
installed command's diagnostic version is described in the CLI
reference; maintainers preparing a release should follow Source
Releases.
Documentation
- CLI reference — commands, flags, output streams, and exits.
- Configuration reference — configuration files, profiles, validation, and module selection.
- Operations — output, state, recovery, and debug handling.
- Integration contracts — Seriatim input and published artifact formats.
- Subprocess consumer guide — invoke Notarius from an orchestrator and consume a published result.
- Complete D&D consumer guide — run the full D&D pipeline as a subprocess and discover its structured artifacts.
- Internal overview — implemented component map for maintainers.
- Developer guide — contributor orientation and validation guidance.
- Future work — unimplemented ideas and priorities.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets exposes embedded LLM-facing content.
|
Package assets exposes embedded LLM-facing content. |
|
cmd
|
|
|
notarius
command
|
|
|
internal
|
|
|
buildinfo
Package buildinfo resolves the product version embedded in a Notarius build.
|
Package buildinfo resolves the product version embedded in a Notarius build. |
|
core/debugbundle
Package debugbundle owns explicitly requested per-run debug bundles.
|
Package debugbundle owns explicitly requested per-run debug bundles. |
|
core/fileio
Package fileio provides confined, atomic artifact writes.
|
Package fileio provides confined, atomic artifact writes. |
|
framework/chunkmap
Package chunkmap owns the durable accepted source chunk-map contract.
|
Package chunkmap owns the durable accepted source chunk-map contract. |
|
framework/diagnostics
Package diagnostics provides bounded local grouping for producer and validator diagnostic results.
|
Package diagnostics provides bounded local grouping for producer and validator diagnostic results. |
|
framework/evidencecontext
Package evidencecontext owns the durable source evidence-context contract.
|
Package evidencecontext owns the durable source evidence-context contract. |
|
framework/readonlyfs
Package readonlyfs provides an immutable filesystem backed by owned bytes.
|
Package readonlyfs provides an immutable filesystem backed by owned bytes. |
|
framework/semanticreconcile
Package semanticreconcile prepares, executes, and validates bounded domain-neutral semantic reconciliation requests.
|
Package semanticreconcile prepares, executes, and validates bounded domain-neutral semantic reconciliation requests. |
|
modules/dnd
Package dnd owns the canonical in-process artifact types for the D&D domain.
|
Package dnd owns the canonical in-process artifact types for the D&D domain. |
|
modules/dnd/codec/candidatejson
Package candidatejson provides strict JSON mechanics for D&D artifact candidates before artifact-specific validation.
|
Package candidatejson provides strict JSON mechanics for D&D artifact candidates before artifact-specific validation. |
|
modules/dnd/codec/enemyevents
Package enemyevents encodes durable D&D enemy-event artifacts.
|
Package enemyevents encodes durable D&D enemy-event artifacts. |
|
modules/dnd/codec/itemoccurrences
Package itemoccurrences encodes durable D&D item-occurrence artifacts.
|
Package itemoccurrences encodes durable D&D item-occurrence artifacts. |
|
modules/dnd/codec/itemregistry
Package itemregistry encodes durable D&D item-registry artifacts.
|
Package itemregistry encodes durable D&D item-registry artifacts. |
|
modules/dnd/codec/locationoccurrences
Package locationoccurrences encodes durable D&D location occurrence artifacts.
|
Package locationoccurrences encodes durable D&D location occurrence artifacts. |
|
modules/dnd/codec/locationregistry
Package locationregistry encodes durable D&D location-registry artifacts.
|
Package locationregistry encodes durable D&D location-registry artifacts. |
|
modules/dnd/codec/npcoccurrences
Package npcoccurrences encodes durable D&D NPC occurrence artifacts.
|
Package npcoccurrences encodes durable D&D NPC occurrence artifacts. |
|
modules/dnd/codec/sourcerange
Package sourcerange validates durable D&D source-reference ranges.
|
Package sourcerange validates durable D&D source-reference ranges. |
|
modules/dnd/enemyevents
Package enemyevents owns canonical ordering and identity policy for D&D enemy-event artifacts.
|
Package enemyevents owns canonical ordering and identity policy for D&D enemy-event artifacts. |
|
modules/dnd/extract/enemyevents
Package enemyevents prepares validated D&D combat grounding for enemy-event extraction.
|
Package enemyevents prepares validated D&D combat grounding for enemy-event extraction. |
|
modules/dnd/extract/itemoccurrences
Package itemoccurrences extracts source-grounded D&D item occurrences.
|
Package itemoccurrences extracts source-grounded D&D item occurrences. |
|
modules/dnd/extract/itemregistry
Package itemregistry extracts source-grounded D&D item-registry candidates.
|
Package itemregistry extracts source-grounded D&D item-registry candidates. |
|
modules/dnd/extract/locationoccurrences
Package locationoccurrences extracts source-grounded D&D location occurrences.
|
Package locationoccurrences extracts source-grounded D&D location occurrences. |
|
modules/dnd/extract/locationregistry
Package locationregistry extracts source-grounded D&D location-registry candidates.
|
Package locationregistry extracts source-grounded D&D location-registry candidates. |
|
modules/dnd/itemoccurrences
Package itemoccurrences owns canonical ordering and durable domain rules for D&D item-occurrence artifacts.
|
Package itemoccurrences owns canonical ordering and durable domain rules for D&D item-occurrence artifacts. |
|
modules/dnd/items/identity
Package identity owns the stable identity policy for D&D item types.
|
Package identity owns the stable identity policy for D&D item types. |
|
modules/dnd/items/registry
Package registry resolves normalized item artifacts into immutable grounding data for future D&D consumers.
|
Package registry resolves normalized item artifacts into immutable grounding data for future D&D consumers. |
|
modules/dnd/locations/identity
Package identity implements deterministic session-scoped location identity.
|
Package identity implements deterministic session-scoped location identity. |
|
modules/dnd/locations/registry
Package registry resolves normalized location artifacts into immutable ID-grounding data for D&D extraction modules.
|
Package registry resolves normalized location artifacts into immutable ID-grounding data for D&D extraction modules. |
|
modules/dnd/normalize/combatturns
Package combatturns normalizes merged D&D combat-turn candidates.
|
Package combatturns normalizes merged D&D combat-turn candidates. |
|
modules/dnd/normalize/enemyevents
Package enemyevents normalizes merged D&D enemy-event candidates.
|
Package enemyevents normalizes merged D&D enemy-event candidates. |
|
modules/dnd/normalize/itemoccurrences
Package itemoccurrences normalizes merged D&D item-occurrence candidates.
|
Package itemoccurrences normalizes merged D&D item-occurrence candidates. |
|
modules/dnd/normalize/itemregistry
Package itemregistry normalizes merged D&D item-registry candidates conservatively.
|
Package itemregistry normalizes merged D&D item-registry candidates conservatively. |
|
modules/dnd/normalize/locationoccurrences
Package locationoccurrences normalizes merged D&D location occurrence candidates.
|
Package locationoccurrences normalizes merged D&D location occurrence candidates. |
|
modules/dnd/normalize/locationregistry
Package locationregistry normalizes merged D&D location-registry candidates conservatively.
|
Package locationregistry normalizes merged D&D location-registry candidates conservatively. |
|
modules/dnd/normalize/npcoccurrences
Package npcoccurrences normalizes merged D&D NPC occurrence candidates.
|
Package npcoccurrences normalizes merged D&D NPC occurrence candidates. |
|
modules/dnd/normalize/npcregistry
Package npcregistry normalizes merged D&D non-player character records.
|
Package npcregistry normalizes merged D&D non-player character records. |
|
modules/dnd/normalize/scenedescriptions
Package scenedescriptions normalizes merged D&D scene descriptions.
|
Package scenedescriptions normalizes merged D&D scene descriptions. |
|
modules/dnd/npcoccurrences
Package npcoccurrences owns canonical ordering and exact-identity rules for D&D NPC occurrence artifacts.
|
Package npcoccurrences owns canonical ordering and exact-identity rules for D&D NPC occurrence artifacts. |
|
modules/dnd/npcs/identity
Package identity owns the stable identity policy for D&D non-player characters.
|
Package identity owns the stable identity policy for D&D non-player characters. |
|
modules/dnd/npcs/registry
Package registry resolves normalized NPC artifacts into immutable grounding data for D&D extraction modules.
|
Package registry resolves normalized NPC artifacts into immutable grounding data for D&D extraction modules. |
|
modules/dnd/register
Package register composes the production D&D module family.
|
Package register composes the production D&D module family. |
|
modules/dnd/scenedescriptions/registry
Package registry resolves scene-description artifacts into immutable combat eligibility data.
|
Package registry resolves scene-description artifacts into immutable combat eligibility data. |
|
modules/dnd/shared/diagnostics
Package diagnostics provides bounded, safe text for deterministic D&D decisions and findings.
|
Package diagnostics provides bounded, safe text for deterministic D&D decisions and findings. |
|
modules/dnd/shared/registryresolver
Package registryresolver provides the shared reference-selection and caching mechanics used by immutable D&D registry views.
|
Package registryresolver provides the shared reference-selection and caching mechanics used by immutable D&D registry views. |
|
modules/dnd/spells/catalog
Package catalog provides immutable D&D spell reference catalogs.
|
Package catalog provides immutable D&D spell reference catalogs. |
|
modules/dnd/validate/combatturns/invariants
Package invariants validates normalized D&D combat-turn artifacts.
|
Package invariants validates normalized D&D combat-turn artifacts. |
|
modules/dnd/validate/enemyevents/engagements
Package engagements prevents duplicate enemy engagements within one scene.
|
Package engagements prevents duplicate enemy engagements within one scene. |
|
modules/dnd/validate/enemyevents/invariants
Package invariants validates normalized D&D enemy-event artifacts.
|
Package invariants validates normalized D&D enemy-event artifacts. |
|
modules/dnd/validate/enemyevents/shape
Package shape validates the candidate shape of D&D enemy-event artifacts.
|
Package shape validates the candidate shape of D&D enemy-event artifacts. |
|
modules/dnd/validate/enemyevents/source_refs
Package sourcerefs validates enemy-event evidence against the current source document.
|
Package sourcerefs validates enemy-event evidence against the current source document. |
|
modules/dnd/validate/enemyevents/source_relatedness
Package sourcerelatedness reports advisory enemy-subject evidence concerns.
|
Package sourcerelatedness reports advisory enemy-subject evidence concerns. |
|
modules/dnd/validate/itemoccurrences/invariants
Package invariants validates normalized D&D item-occurrence artifacts.
|
Package invariants validates normalized D&D item-occurrence artifacts. |
|
modules/dnd/validate/itemoccurrences/registry
Package registry validates item occurrence identity against item grounding.
|
Package registry validates item occurrence identity against item grounding. |
|
modules/dnd/validate/itemoccurrences/shape
Package shape validates required D&D item-occurrence candidate fields.
|
Package shape validates required D&D item-occurrence candidate fields. |
|
modules/dnd/validate/itemoccurrences/source_refs
Package sourcerefs validates D&D item-occurrence transcript evidence.
|
Package sourcerefs validates D&D item-occurrence transcript evidence. |
|
modules/dnd/validate/itemoccurrences/source_relatedness
Package sourcerelatedness reports advisory findings when item-occurrence evidence does not mention its item.
|
Package sourcerelatedness reports advisory findings when item-occurrence evidence does not mention its item. |
|
modules/dnd/validate/itemregistry/identity
Package identity validates stable D&D item-type identity after normalization.
|
Package identity validates stable D&D item-type identity after normalization. |
|
modules/dnd/validate/itemregistry/shape
Package shape validates the required extracted item fields.
|
Package shape validates the required extracted item fields. |
|
modules/dnd/validate/itemregistry/source_refs
Package sourcerefs validates item citations against the current source.
|
Package sourcerefs validates item citations against the current source. |
|
modules/dnd/validate/itemregistry/source_relatedness
Package sourcerelatedness reports advisory findings when cited source text does not mention an item.
|
Package sourcerelatedness reports advisory findings when cited source text does not mention an item. |
|
modules/dnd/validate/locationoccurrences/invariants
Package invariants validates normalized D&D location occurrence artifacts.
|
Package invariants validates normalized D&D location occurrence artifacts. |
|
modules/dnd/validate/locationoccurrences/registry
Package registry validates location occurrence identity against location grounding.
|
Package registry validates location occurrence identity against location grounding. |
|
modules/dnd/validate/locationoccurrences/shape
Package shape validates required D&D location occurrence candidate fields.
|
Package shape validates required D&D location occurrence candidate fields. |
|
modules/dnd/validate/locationoccurrences/source_refs
Package sourcerefs validates location occurrence transcript evidence.
|
Package sourcerefs validates location occurrence transcript evidence. |
|
modules/dnd/validate/locationoccurrences/source_relatedness
Package sourcerelatedness reports advisory findings when cited source text does not mention a location occurrence.
|
Package sourcerelatedness reports advisory findings when cited source text does not mention a location occurrence. |
|
modules/dnd/validate/locationregistry/identity
Package identity validates stable, evidence-anchored location identity.
|
Package identity validates stable, evidence-anchored location identity. |
|
modules/dnd/validate/locationregistry/shape
Package shape validates the required extracted location fields.
|
Package shape validates the required extracted location fields. |
|
modules/dnd/validate/locationregistry/source_refs
Package sourcerefs validates location citations against the current source.
|
Package sourcerefs validates location citations against the current source. |
|
modules/dnd/validate/locationregistry/source_relatedness
Package sourcerelatedness reports advisory findings when cited source text does not mention a location.
|
Package sourcerelatedness reports advisory findings when cited source text does not mention a location. |
|
modules/dnd/validate/npcoccurrences/invariants
Package invariants validates normalized D&D NPC occurrence artifacts.
|
Package invariants validates normalized D&D NPC occurrence artifacts. |
|
modules/dnd/validate/npcoccurrences/registry
Package registry validates D&D NPC occurrence names against NPC grounding.
|
Package registry validates D&D NPC occurrence names against NPC grounding. |
|
modules/dnd/validate/npcoccurrences/shape
Package shape validates required D&D NPC occurrence candidate fields.
|
Package shape validates required D&D NPC occurrence candidate fields. |
|
modules/dnd/validate/npcoccurrences/source_refs
Package sourcerefs validates D&D NPC occurrence transcript evidence.
|
Package sourcerefs validates D&D NPC occurrence transcript evidence. |
|
modules/dnd/validate/npcoccurrences/source_relatedness
Package sourcerelatedness reports advisory findings about NPC occurrence evidence unrelated to its NPC.
|
Package sourcerelatedness reports advisory findings about NPC occurrence evidence unrelated to its NPC. |
|
modules/dnd/validate/npcregistry/identity
Package identity validates the stable identity invariants of D&D NPC registries.
|
Package identity validates the stable identity invariants of D&D NPC registries. |
|
modules/dnd/validate/scenedescriptions/invariants
Package invariants validates normalized D&D scene description artifacts.
|
Package invariants validates normalized D&D scene description artifacts. |
|
modules/dnd/validate/scenedescriptions/shape
Package shape validates required D&D scene description fields.
|
Package shape validates required D&D scene description fields. |
|
modules/dnd/validate/scenedescriptions/source_refs
Package sourcerefs validates D&D scene-description source identity.
|
Package sourcerefs validates D&D scene-description source identity. |
|
modules/dnd/validate/scenedescriptions/source_relatedness
Package sourcerelatedness reports advisory findings when scene prose has no lexical grounding.
|
Package sourcerelatedness reports advisory findings when scene prose has no lexical grounding. |
|
modules/generic/register
Package register composes the production domain-neutral module family.
|
Package register composes the production domain-neutral module family. |
|
modules/seriatim/register
Package register composes the production Seriatim module family.
|
Package register composes the production Seriatim module family. |
Click to show internal directories.
Click to hide internal directories.