eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document completed spell catalog baseline

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-20 19:44:31 +00:00
parent 3d0d79360e
commit 87c57681f6
6 changed files with 57 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/integrations/dnd-spell-artifacts.md
View File

@@ -51,7 +51,10 @@ Each spell cast contains exactly these required fields:
IDs and evidence unit ranges. It must contain at least one entry. IDs and evidence unit ranges. It must contain at least one entry.
All four string fields must be non-empty. `caster` is the in-world caster, not All four string fields must be non-empty. `caster` is the in-world caster, not
the transcript speaker. Unknown fields are rejected. the transcript speaker. The `spell` value must resolve through the effective
SRD-plus-overlay catalog as either a canonical name or alias. Catalog
validation accepts aliases but does not rewrite them; unknown fields are
rejected.
## Source References ## Source References
@@ -81,10 +84,18 @@ manifest metadata:
"response_schema_id": "notarius.dnd.spells", "response_schema_id": "notarius.dnd.spells",
"response_schema_name": "notarius_dnd_spells_v1", "response_schema_name": "notarius_dnd_spells_v1",
"response_schema_version": "v1", "response_schema_version": "v1",
"response_schema_sha256": "sha256:..." "response_schema_sha256": "sha256:...",
"catalog_base_id": "dnd-5e-2014-srd-spells",
"catalog_digest": "sha256:...",
"catalog_overlay_ids": ["campaign.example"]
} }
} }
} }
``` ```
Raw prompt and schema content are not included in manifest metadata. `catalog_digest` identifies the effective semantic catalog, while
`catalog_overlay_ids` is sorted and empty for a base-only configuration. Raw
prompt, schema, catalog, alias, and local overlay-file content are not
included in manifest metadata. Overlay origin, media type, byte size, and raw
digest are recorded separately in the manifest's reference provenance; see
the [JSON output contract](json-output.md#manifestjson).

18
docs/internal/modules.md
View File

@@ -70,15 +70,15 @@ license details live beside the asset in `SOURCES.md`. This domain-owned data is
separate from `internal/modules/dnd/shared`, which is reserved for reusable separate from `internal/modules/dnd/shared`, which is reserved for reusable
prompt and source-reference machinery. prompt and source-reference machinery.
`ResolveEffectiveCatalog` builds the immutable recognition view used by later `ResolveEffectiveCatalog` builds the immutable recognition view used by the
D&D consumers. It starts with the embedded SRD catalog and optionally applies spell extractor and catalog validator. It starts with the embedded SRD catalog
one strict JSON overlay from the `spell_catalog` item in a materialized and optionally applies one strict JSON overlay from the `spell_catalog` item in
reference set. Overlay catalogs are ordered by ID, may add names and aliases, a materialized reference set. Overlay catalogs are ordered by ID, may add names
and may augment an existing canonical spell without replacing its display and aliases, and may augment an existing canonical spell without replacing its
name. Cross-spell lookup collisions are errors. The effective view exposes display name. Cross-spell lookup collisions are errors. The effective view
sorted canonical names, normalized lookup, overlay identities, and a semantic exposes sorted canonical names, normalized lookup, overlay identities, and a
digest; overlay content remains contextual reference material rather than semantic digest; overlay content remains contextual reference material rather
source evidence. Its external JSON contract is defined in the than source evidence. Its external JSON contract is defined in the
[spell-catalog overlay contract](../integrations/dnd-spell-catalog-overlays.md). [spell-catalog overlay contract](../integrations/dnd-spell-catalog-overlays.md).
## Input Adapter ## Input Adapter

4
docs/internal/overview.md
View File

@@ -87,7 +87,7 @@ Configuration. The implemented module packages are:
| `internal/modules/dnd` | Owns the canonical D&D spell-list and spell-cast artifact types. | | `internal/modules/dnd` | Owns the canonical D&D spell-list and spell-cast artifact types. |
| `internal/modules/dnd/codec/spells` | Strictly decodes and stably encodes the durable D&D spell-list representation. | | `internal/modules/dnd/codec/spells` | Strictly decodes and stably encodes the durable D&D spell-list representation. |
| `internal/modules/dnd/extract/spells` | Maps private structured model output to canonical source-grounded D&D spell lists. | | `internal/modules/dnd/extract/spells` | Maps private structured model output to canonical source-grounded D&D spell lists. |
| `internal/modules/dnd/spells/catalog` | Embeds and validates the versioned D&D 5e 2014 SRD spell catalog and provides immutable lookup. | | `internal/modules/dnd/spells/catalog` | Embeds and validates the versioned D&D 5e 2014 SRD catalog, composes optional overlays, and provides immutable effective lookup. |
| `internal/modules/generic/merge/appendorder` | Combines accepted extraction results in chunk order. | | `internal/modules/generic/merge/appendorder` | Combines accepted extraction results in chunk order. |
| `internal/modules/generic/normalize/noop` | Preserves accepted merged output. | | `internal/modules/generic/normalize/noop` | Preserves accepted merged output. |
| `internal/modules/generic/output/json` | Encodes manifests, lane payloads, warnings, and rejections as logical JSON files. | | `internal/modules/generic/output/json` | Encodes manifests, lane payloads, warnings, and rejections as logical JSON files. |
@@ -101,7 +101,7 @@ Generic validators under `internal/modules/generic/validate` provide
unconditional test decisions, JSON syntax validation, and JSON Schema unconditional test decisions, JSON syntax validation, and JSON Schema
validation. D&D spell validators under `internal/modules/dnd/validate/spells` validation. D&D spell validators under `internal/modules/dnd/validate/spells`
consume the canonical spell-list type directly to provide shape, consume the canonical spell-list type directly to provide shape,
source-reference, and source-relatedness decisions. effective-catalog, source-reference, and source-relatedness decisions.
Production composition is grouped behind package-family registrars, and every Production composition is grouped behind package-family registrars, and every
implemented production extension uses its domain-first tree: implemented production extension uses its domain-first tree:

28
docs/roadmap/dnd-spell-extraction.md
View File

@@ -2,9 +2,31 @@
## Status ## Status
The immediate baseline feature is accepted and pending implementation. The accepted baseline implementation is complete. It provides effective
Feedback-aware repair and semantic LLM validation are deferred until the SRD-plus-overlay catalog composition, canonical-name prompt grounding,
baseline has been evaluated. deterministic catalog validation, the maintained `retries: 2` policy, and
provenance and checkpoint identity coverage through the assembled offline
workflow.
External quality evaluation is pending. This repository contains the
maintained example and offline fake-LLM coverage, but no approved
human-reviewed transcript corpus or authorized live-model evaluation was
available for this implementation run. The maintained example can be run
from the repository root with:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells-production.config.yml \
--input examples/seriatim-minimal-transcript.json \
--chunk_cache bypass
```
That command requires the configured Scriptorium profile credential. When an
approved profile and reviewed corpus are available, record anonymized
aggregate false positives, false negatives, unknown-name rejections,
acceptance by attempt, and model-call cost here without committing transcripts
or raw prompts. Feedback-aware repair and semantic LLM validation remain
deferred until that baseline evaluation is available.
## Objective ## Objective

11
docs/roadmap/future.md
View File

@@ -9,14 +9,9 @@ not as committed release dates.
### Solidify Spell Extraction ### Solidify Spell Extraction
- Implement the immediate overlay-capable catalog-grounding and - Evaluate the implemented baseline in
deterministic-validation baseline in [D&D Spell Extraction Quality](dnd-spell-extraction.md), then reconsider its
[D&D Spell Extraction Quality](dnd-spell-extraction.md), using ordinary [deferred retry and validation work](dnd-spell-extraction.md#deferred-retry-and-validation-work).
`retries: 2` behavior as the comparison point.
- After evaluating that baseline, reconsider the roadmap's deferred structured
diagnostics, retryability classification, repair-capable extractor contract,
hybrid repair/fresh retry policy, and narrowly scoped semantic LLM
validation.
- Replace the no-op spell normalizer with a D&D-specific implementation that - Replace the no-op spell normalizer with a D&D-specific implementation that
canonicalizes recognized spell names, performs only high-confidence repairs, canonicalizes recognized spell names, performs only high-confidence repairs,
retains uncertain values for review, and emits scoped warnings. retains uncertain values for review, and emits scoped warnings.

7
docs/roadmap/implementation.md
View File

@@ -2,9 +2,10 @@
## Status ## Status
Ready for implementation. Follow the stages in order. This plan covers the The accepted baseline implementation is complete through the assembled
accepted baseline in [D&D Spell Extraction Quality](dnd-spell-extraction.md), offline workflow. External quality evaluation remains pending as recorded in
not its deferred repair-aware retry or semantic LLM-validation work. [D&D Spell Extraction Quality](dnd-spell-extraction.md). This plan covers that
baseline, not its deferred repair-aware retry or semantic LLM-validation work.
This active plan replaces the completed test-suite implementation record that This active plan replaces the completed test-suite implementation record that
previously occupied this filename. That review remains documented in previously occupied this filename. That review remains documented in