Document D&D scene description artifacts
This commit is contained in:
@@ -377,12 +377,14 @@ production validators do not call the LLM and must not set `llm_profile`.
|
|||||||
| extract | `dnd/npcs` | Extracts typed D&D NPC-list artifacts. |
|
| extract | `dnd/npcs` | Extracts typed D&D NPC-list artifacts. |
|
||||||
| extract | `dnd/combat-turns` | Extracts typed D&D combat-turn-list artifacts. |
|
| extract | `dnd/combat-turns` | Extracts typed D&D combat-turn-list artifacts. |
|
||||||
| extract | `dnd/npc-interactions` | Extracts typed D&D NPC-interaction-list artifacts from a supplied NPC registry. |
|
| extract | `dnd/npc-interactions` | Extracts typed D&D NPC-interaction-list artifacts from a supplied NPC registry. |
|
||||||
|
| extract | `dnd/scene-descriptions` | Extracts one typed D&D scene description for each accepted chunk. |
|
||||||
| merge | `appendorder` | Combines typed artifacts in chunk order. |
|
| merge | `appendorder` | Combines typed artifacts in chunk order. |
|
||||||
| normalize | `noop` | Passes merged typed artifacts through unchanged. |
|
| normalize | `noop` | Passes merged typed artifacts through unchanged. |
|
||||||
| normalize | `dnd/spells` | Deterministically canonicalizes and de-duplicates typed D&D spell-list artifacts. |
|
| normalize | `dnd/spells` | Deterministically canonicalizes and de-duplicates typed D&D spell-list artifacts. |
|
||||||
| normalize | `dnd/npcs` | Deterministically consolidates typed D&D NPC-list artifacts by canonical name and unions exact evidence. |
|
| normalize | `dnd/npcs` | Deterministically consolidates typed D&D NPC-list artifacts by canonical name and unions exact evidence. |
|
||||||
| normalize | `dnd/combat-turns` | Deterministically canonicalizes, orders, and de-duplicates typed D&D combat-turn artifacts. |
|
| normalize | `dnd/combat-turns` | Deterministically canonicalizes, orders, and de-duplicates typed D&D combat-turn artifacts. |
|
||||||
| normalize | `dnd/npc-interactions` | Canonicalizes registry NPC names, orders interaction occurrences, and removes only exact duplicates. |
|
| normalize | `dnd/npc-interactions` | Canonicalizes registry NPC names, orders interaction occurrences, and removes only exact duplicates. |
|
||||||
|
| normalize | `dnd/scene-descriptions` | Validates, orders, trims, and de-duplicates typed D&D scene-description artifacts. |
|
||||||
| output | `json` | Produces JSON output files for normalized `application/json` lanes and can opt in to an accepted chunk map. |
|
| output | `json` | Produces JSON output files for normalized `application/json` lanes and can opt in to an accepted chunk map. |
|
||||||
|
|
||||||
## Implemented Production Validators
|
## Implemented Production Validators
|
||||||
@@ -410,6 +412,10 @@ production validators do not call the LLM and must not set `llm_profile`.
|
|||||||
| `extract/dnd/npc-interactions/source_refs` | deterministic | Rejects missing, invalid, or extract-chunk-external D&D interaction source references. |
|
| `extract/dnd/npc-interactions/source_refs` | deterministic | Rejects missing, invalid, or extract-chunk-external D&D interaction source references. |
|
||||||
| `extract/dnd/npc-interactions/source_relatedness` | deterministic | Emits bounded warnings when an interaction name is not found in its cited source text. |
|
| `extract/dnd/npc-interactions/source_relatedness` | deterministic | Emits bounded warnings when an interaction name is not found in its cited source text. |
|
||||||
| `normalize/dnd/npc-interactions/invariants` | deterministic | Rejects normalized interaction identity, evidence-order, and chronology violations. |
|
| `normalize/dnd/npc-interactions/invariants` | deterministic | Rejects normalized interaction identity, evidence-order, and chronology violations. |
|
||||||
|
| `extract/dnd/scene-descriptions/shape` | deterministic | Rejects malformed D&D scene-description-list artifacts. |
|
||||||
|
| `extract/dnd/scene-descriptions/source_refs` | deterministic | Rejects invalid current-source references and extract records not exactly attached to their chunk. |
|
||||||
|
| `extract/dnd/scene-descriptions/source_relatedness` | deterministic | Emits bounded advisory warnings for title or summary text not grounded in its cited transcript range. |
|
||||||
|
| `normalize/dnd/scene-descriptions/invariants` | deterministic | Rejects non-normalized scene order, exact duplicates, and ID or range conflicts. |
|
||||||
|
|
||||||
The production default chain for `dnd/spells` is used for both its extract and
|
The production default chain for `dnd/spells` is used for both its extract and
|
||||||
normalize stages:
|
normalize stages:
|
||||||
@@ -486,6 +492,26 @@ normalize:
|
|||||||
- extract/dnd/npc-interactions/source_relatedness
|
- extract/dnd/npc-interactions/source_relatedness
|
||||||
```
|
```
|
||||||
|
|
||||||
|
The production default chains for `dnd/scene-descriptions` are:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
extract:
|
||||||
|
validators:
|
||||||
|
- generic/valid_json
|
||||||
|
- extract/dnd/scene-descriptions/shape
|
||||||
|
- extract/dnd/scene-descriptions/source_refs
|
||||||
|
- generic/valid_json_schema
|
||||||
|
- extract/dnd/scene-descriptions/source_relatedness
|
||||||
|
normalize:
|
||||||
|
validators:
|
||||||
|
- 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
|
||||||
|
```
|
||||||
|
|
||||||
Empty chains approve output by default.
|
Empty chains approve output by default.
|
||||||
|
|
||||||
The `generic` chunker accepts:
|
The `generic` chunker accepts:
|
||||||
@@ -542,6 +568,13 @@ accepts no references. The maintained
|
|||||||
accepted normalized output to the later spell and combat targets through an
|
accepted normalized output to the later spell and combat targets through an
|
||||||
explicit ordered step.
|
explicit ordered step.
|
||||||
|
|
||||||
|
The `dnd/scene-descriptions` extractor accepts only the optional `players`,
|
||||||
|
`party`, and `glossary` campaign slots. They can disambiguate terms in the
|
||||||
|
model-facing title and summary but are never source evidence. Its normalizer
|
||||||
|
accepts no references. No NPC registry or generated artifact is required. See
|
||||||
|
the [D&D scene-description artifact contract](integrations/dnd-scene-description-artifacts.md)
|
||||||
|
and the copyable [scene-description configuration](../examples/dnd-scene-descriptions.config.yml).
|
||||||
|
|
||||||
The `dnd/combat-turns` extractor declares the optional campaign slots and the
|
The `dnd/combat-turns` extractor declares the optional campaign slots and the
|
||||||
structured `npcs` slot. Campaign references guide only the LLM extraction
|
structured `npcs` slot. Campaign references guide only the LLM extraction
|
||||||
stage. The deterministic normalizer declares only `npcs`, whose operation-time
|
stage. The deterministic normalizer declares only `npcs`, whose operation-time
|
||||||
|
|||||||
120
docs/integrations/dnd-scene-description-artifacts.md
Normal file
120
docs/integrations/dnd-scene-description-artifacts.md
Normal file
@@ -0,0 +1,120 @@
|
|||||||
|
# D&D Scene Description Artifact Contract
|
||||||
|
|
||||||
|
This document defines the durable `dnd/scene-description-list` artifact
|
||||||
|
emitted by the D&D scene-description lane.
|
||||||
|
|
||||||
|
## Artifact identity
|
||||||
|
|
||||||
|
| Property | Value |
|
||||||
|
| --- | --- |
|
||||||
|
| Artifact kind | `dnd/scene-description-list` |
|
||||||
|
| Schema ID | `notarius.dnd.scene_descriptions` |
|
||||||
|
| Schema name | `notarius_dnd_scene_descriptions_v1` |
|
||||||
|
| Schema version | `v1` |
|
||||||
|
| Media type | `application/json` |
|
||||||
|
|
||||||
|
The normalized payload is written by the JSON output module to
|
||||||
|
`lanes/<lane-id>.json`. See [JSON output](json-output.md) for the surrounding
|
||||||
|
output bundle.
|
||||||
|
|
||||||
|
## JSON shape
|
||||||
|
|
||||||
|
The payload is a JSON object containing exactly one required field, `scenes`.
|
||||||
|
Each scene object contains exactly these required fields:
|
||||||
|
|
||||||
|
| Field | Shape and ownership |
|
||||||
|
| --- | --- |
|
||||||
|
| `id` | Non-empty accepted chunk ID, assigned by Notarius. |
|
||||||
|
| `source_ref` | Exact inclusive accepted chunk range, assigned by Notarius. |
|
||||||
|
| `kind` | One of `combat`, `narrative`, `recap`, or `meta`. |
|
||||||
|
| `title` | Non-empty, trimmed, source-grounded title. |
|
||||||
|
| `summary` | Non-empty, trimmed, source-grounded summary. |
|
||||||
|
|
||||||
|
All object layers reject unknown fields. The `scenes` array must be present and
|
||||||
|
non-empty. `source_ref` has exactly `source_id`, `start_unit_id`, and
|
||||||
|
`end_unit_id`; its source ID is non-empty and its unit IDs are positive
|
||||||
|
integers.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"scenes": [
|
||||||
|
{
|
||||||
|
"id": "chunk-000001",
|
||||||
|
"source_ref": {
|
||||||
|
"source_id": "session-alpha",
|
||||||
|
"start_unit_id": 1,
|
||||||
|
"end_unit_id": 3
|
||||||
|
},
|
||||||
|
"kind": "narrative",
|
||||||
|
"title": "Arrival at the watchtower",
|
||||||
|
"summary": "The party reaches the ruined watchtower and begins to investigate it."
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`id` and `source_ref` are application-owned identity and evidence. The model
|
||||||
|
provides only `kind`, `title`, and `summary`; it is not asked for chunk IDs,
|
||||||
|
source IDs, unit IDs, ranges, participants, or confidence.
|
||||||
|
|
||||||
|
## Scene kinds
|
||||||
|
|
||||||
|
| Kind | Meaning |
|
||||||
|
| --- | --- |
|
||||||
|
| `combat` | Active combat is a substantive central activity. |
|
||||||
|
| `narrative` | Current-session in-world play that is not principally combat, recap, or meta discussion. |
|
||||||
|
| `recap` | The table is primarily recounting a previous session. |
|
||||||
|
| `meta` | Sustained out-of-character discussion is the scene's primary purpose. |
|
||||||
|
|
||||||
|
For a mixed accepted chunk, classification prefers `combat`, then `recap`,
|
||||||
|
then `meta`, then `narrative`. Brief table talk, rules clarification, or a
|
||||||
|
short recollection does not replace the main current-session activity.
|
||||||
|
|
||||||
|
## Extraction and evidence
|
||||||
|
|
||||||
|
The extractor runs once for each accepted chunk and maps one successful model
|
||||||
|
response to one scene record. It copies the current chunk ID and exact chunk
|
||||||
|
range, preserves the model kind without repair, and trims only surrounding
|
||||||
|
whitespace from title and summary. A model response cannot represent an empty
|
||||||
|
result; extraction failure follows the configured retry and rejection policy.
|
||||||
|
|
||||||
|
Optional `players`, `party`, and `glossary` campaign references can help
|
||||||
|
disambiguate names or setting terms. They never supply scene evidence or add
|
||||||
|
events absent from the accepted chunk. The lane requires no NPC registry or
|
||||||
|
other generated artifact reference.
|
||||||
|
|
||||||
|
## Merge and normalization
|
||||||
|
|
||||||
|
Accepted per-chunk lists are appended in chunk order. Normalization then:
|
||||||
|
|
||||||
|
1. validates the current-source range, non-empty ID and prose, and closed kind;
|
||||||
|
2. trims only title and summary whitespace;
|
||||||
|
3. sorts records by source-document start position, then ID;
|
||||||
|
4. removes records only when all five durable fields are identical;
|
||||||
|
5. rejects a reused ID when any remaining durable field differs; and
|
||||||
|
6. rejects the same exact range when `kind`, `title`, or `summary` differs.
|
||||||
|
|
||||||
|
Two different IDs with the same range and identical model-owned content remain
|
||||||
|
separate records. Normalization does not join adjacent ranges, rewrite prose,
|
||||||
|
repair kinds, infer missing scenes, or use chunk annotations.
|
||||||
|
|
||||||
|
## Validation and warnings
|
||||||
|
|
||||||
|
Extraction validation requires exactly one record with an ID and range exactly
|
||||||
|
equal to its current chunk. Later validation checks source membership without a
|
||||||
|
current chunk. Shape, source-range, kind, ID, and normalized-invariant failures
|
||||||
|
reject the artifact.
|
||||||
|
|
||||||
|
Relatedness checks are advisory. They separately warn when a scene title or
|
||||||
|
summary has no significant lexical token in its cited transcript range. The
|
||||||
|
check ignores short tokens and common function words, uses transcript text only,
|
||||||
|
and does not treat campaign references as evidence. Warning diagnostics are
|
||||||
|
bounded and do not copy transcript or campaign-reference content.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Use `dnd/scenes` to form accepted scene chunks, then select
|
||||||
|
`dnd/scene-descriptions` for extraction and normalization. The maintained
|
||||||
|
[scene-description configuration](../../examples/dnd-scene-descriptions.config.yml)
|
||||||
|
is a copyable minimal lane. Selectable keys and default validator chains are
|
||||||
|
defined in [Configuration](../config.md).
|
||||||
@@ -162,7 +162,8 @@ contains the codec-owned JSON bytes pretty-printed.
|
|||||||
The schema of each lane payload is owned by that artifact contract. For the
|
The schema of each lane payload is owned by that artifact contract. For the
|
||||||
current D&D lanes, see [D&D Spell Artifact](dnd-spell-artifacts.md),
|
current D&D lanes, see [D&D Spell Artifact](dnd-spell-artifacts.md),
|
||||||
[D&D NPC Artifact](dnd-npc-artifacts.md), and
|
[D&D NPC Artifact](dnd-npc-artifacts.md), and
|
||||||
[D&D Combat-Turn Artifact](dnd-combat-turn-artifacts.md).
|
[D&D Combat-Turn Artifact](dnd-combat-turn-artifacts.md), and
|
||||||
|
[D&D Scene Description Artifact](dnd-scene-description-artifacts.md).
|
||||||
|
|
||||||
## `rejected.json`
|
## `rejected.json`
|
||||||
|
|
||||||
|
|||||||
@@ -39,7 +39,8 @@ without exposing Scriptorium types through stage contracts.
|
|||||||
7. injecting that one shared client into complete pipeline preparation before
|
7. injecting that one shared client into complete pipeline preparation before
|
||||||
the source file is read or the runner is invoked.
|
the source file is read or the runner is invoked.
|
||||||
|
|
||||||
The D&D scene chunker and spell, NPC, and combat extractors retain this
|
The D&D scene chunker and spell, NPC, combat-turn, NPC-interaction, and
|
||||||
|
scene-description extractors retain this
|
||||||
injected client and use it for every structured completion. Operation requests
|
injected client and use it for every structured completion. Operation requests
|
||||||
do not carry an LLM client.
|
do not carry an LLM client.
|
||||||
|
|
||||||
@@ -98,7 +99,8 @@ D&D prompt content. `internal/framework/promptfs` provides the domain-neutral
|
|||||||
filesystem composition helper used to combine module-owned files with shared
|
filesystem composition helper used to combine module-owned files with shared
|
||||||
domain prompt fragments.
|
domain prompt fragments.
|
||||||
|
|
||||||
The D&D scene chunker and spell, NPC, combat-turn, and NPC-interaction extractors each declare an
|
The D&D scene chunker and spell, NPC, combat-turn, NPC-interaction, and
|
||||||
|
scene-description extractors each declare an
|
||||||
ordered prompt asset manifest. The manifest lists the package-owned YAML and
|
ordered prompt asset manifest. The manifest lists the package-owned YAML and
|
||||||
Markdown files, then the exact shared fragments rendered by that prompt; the
|
Markdown files, then the exact shared fragments rendered by that prompt; the
|
||||||
same ordered list drives both filesystem mounting and the prompt fingerprint.
|
same ordered list drives both filesystem mounting and the prompt fingerprint.
|
||||||
@@ -132,7 +134,8 @@ prompt places its final boundary on its lane-specific instructions, immediately
|
|||||||
before the transcript. The transcript does not carry cache control because no
|
before the transcript. The transcript does not carry cache control because no
|
||||||
reusable content follows it.
|
reusable content follows it.
|
||||||
|
|
||||||
Accordingly, the common prefix of all four extraction prompts is system,
|
Accordingly, the common prefix of the spell, NPC, combat, and interaction
|
||||||
|
extraction prompts is system,
|
||||||
extraction evidence, identity, and campaign references. The NPC prompt then
|
extraction evidence, identity, and campaign references. The NPC prompt then
|
||||||
renders task, instructions, and transcript. Spell renders the NPC registry,
|
renders task, instructions, and transcript. Spell renders the NPC registry,
|
||||||
catalog, task, instructions, and transcript. Combat renders the NPC registry,
|
catalog, task, instructions, and transcript. Combat renders the NPC registry,
|
||||||
@@ -142,6 +145,14 @@ scene chunker is not an extraction lane: it retains its separate system,
|
|||||||
transcript, campaign-reference, task, and instruction order and marks its
|
transcript, campaign-reference, task, and instruction order and marks its
|
||||||
transcript and campaign-reference messages ephemeral.
|
transcript and campaign-reference messages ephemeral.
|
||||||
|
|
||||||
|
The scene-description extractor deliberately omits the citation-oriented
|
||||||
|
`common-dnd-extraction-evidence.md` asset because Notarius attaches the whole
|
||||||
|
accepted chunk range itself. Its manifest is system, shared identity, shared
|
||||||
|
campaign references, lane task, lane instructions, then the transcript. The
|
||||||
|
identity, campaign-reference, and instruction messages are ephemeral cache
|
||||||
|
boundaries; the transcript is last and has no cache control. Compatible shared
|
||||||
|
messages remain canonical shared assets rather than copied package text.
|
||||||
|
|
||||||
Shared wording belongs in the canonical assets under
|
Shared wording belongs in the canonical assets under
|
||||||
`internal/modules/dnd/shared`; extraction packages reference those assets in
|
`internal/modules/dnd/shared`; extraction packages reference those assets in
|
||||||
their manifests instead of copying similar text into package-local files.
|
their manifests instead of copying similar text into package-local files.
|
||||||
@@ -155,7 +166,8 @@ return defensive copies, and expose a diagnostics map that omits schema bytes.
|
|||||||
The small framework registry contains only generic test schemas; production
|
The small framework registry contains only generic test schemas; production
|
||||||
schemas remain package-owned.
|
schemas remain package-owned.
|
||||||
|
|
||||||
The spell, NPC, combat, and NPC-interaction extractors' package-owned prompts declare their
|
The spell, NPC, combat, NPC-interaction, and scene-description extractors'
|
||||||
|
package-owned prompts declare their
|
||||||
structured JSON inputs and private response schemas. Each private response
|
structured JSON inputs and private response schemas. Each private response
|
||||||
schema remains separate from its durable artifact codec schema; this work does
|
schema remains separate from its durable artifact codec schema; this work does
|
||||||
not use shared schema fragments or schema generation. Those private schemas own
|
not use shared schema fragments or schema generation. Those private schemas own
|
||||||
|
|||||||
@@ -17,16 +17,16 @@ validator registry. Package-family registrars compose those leaf registrations
|
|||||||
into the production catalog and own family-level policy such as default
|
into the production catalog and own family-level policy such as default
|
||||||
validator chains and prompt asset collection.
|
validator chains and prompt asset collection.
|
||||||
|
|
||||||
Production input, chunk, output, and D&D spell-, combat-, and interaction-extract packages
|
Production input, chunk, output, and D&D spell-, NPC-, combat-, interaction-, and scene-description-extract packages
|
||||||
register strict option decoders and run-local builders. Preparation decodes their options into
|
register strict option decoders and run-local builders. Preparation decodes their options into
|
||||||
implementation-owned values and injects dependencies plus the materialized
|
implementation-owned values and injects dependencies plus the materialized
|
||||||
reference set for the selected target. Each builder receives an isolated clone
|
reference set for the selected target. Each builder receives an isolated clone
|
||||||
of that set; input and output builders receive no references. The spell,
|
of that set; input and output builders receive no references. The spell, NPC,
|
||||||
combat, and interaction extractors are typed over the canonical D&D model. D&D validators, merge,
|
combat, interaction, and scene-description extractors are typed over the canonical D&D model. D&D validators, merge,
|
||||||
and normalize use typed variants; JSON representation validators use serialized
|
and normalize use typed variants; JSON representation validators use serialized
|
||||||
requests; and unconditional validators expose separate chunk and typed
|
requests; and unconditional validators expose separate chunk and typed
|
||||||
variants. The D&D production registrar registers the canonical typed spell,
|
variants. The D&D production registrar registers the canonical typed spell,
|
||||||
NPC, combat, and interaction implementations, including their kind-specific merge and
|
NPC, combat, interaction, and scene-description implementations, including their kind-specific merge and
|
||||||
normalize behavior.
|
normalize behavior.
|
||||||
|
|
||||||
For D&D artifact defaults, generic JSON syntax validation runs first. Rejecting
|
For D&D artifact defaults, generic JSON syntax validation runs first. Rejecting
|
||||||
@@ -54,7 +54,7 @@ package-local embedded assets. Shared filesystem composition belongs in
|
|||||||
`internal/framework/promptfs`; reusable D&D prompt fragments, reference
|
`internal/framework/promptfs`; reusable D&D prompt fragments, reference
|
||||||
declarations, prompt-input assembly, and source-unit/citation helpers belong in
|
declarations, prompt-input assembly, and source-unit/citation helpers belong in
|
||||||
`internal/modules/dnd/shared`, which also owns bounded D&D diagnostics. The
|
`internal/modules/dnd/shared`, which also owns bounded D&D diagnostics. The
|
||||||
D&D scene chunker and spell, NPC, combat-turn, and NPC-interaction extractors use ordered
|
D&D scene chunker and spell, NPC, combat-turn, NPC-interaction, and scene-description extractors use ordered
|
||||||
package-local prompt manifests for both rendering and prompt fingerprinting, so
|
package-local prompt manifests for both rendering and prompt fingerprinting, so
|
||||||
only the shared fragments each prompt actually renders participate in either
|
only the shared fragments each prompt actually renders participate in either
|
||||||
operation. Extraction prompts place stable shared and lane-specific context
|
operation. Extraction prompts place stable shared and lane-specific context
|
||||||
@@ -128,6 +128,12 @@ It is registered by the production D&D family registrar for the selectable
|
|||||||
interaction lane. Its external contract is documented in the
|
interaction lane. Its external contract is documented in the
|
||||||
[D&D NPC interaction artifact contract](../integrations/dnd-npc-interaction-artifacts.md).
|
[D&D NPC interaction artifact contract](../integrations/dnd-npc-interaction-artifacts.md).
|
||||||
|
|
||||||
|
The `internal/modules/dnd/codec/scenedescriptions` package owns the durable
|
||||||
|
`dnd/scene-description-list` schema and candidate versus approved JSON boundary.
|
||||||
|
It is registered by the production D&D family registrar. Its external contract
|
||||||
|
is documented in the
|
||||||
|
[D&D scene-description artifact contract](../integrations/dnd-scene-description-artifacts.md).
|
||||||
|
|
||||||
## Input Adapter
|
## Input Adapter
|
||||||
|
|
||||||
### `internal/modules/seriatim/input/transcript`
|
### `internal/modules/seriatim/input/transcript`
|
||||||
@@ -268,6 +274,18 @@ integer source-unit candidates unchanged. Required semantic content, non-empty
|
|||||||
evidence, and valid source ranges are rejected by the deterministic shape and
|
evidence, and valid source ranges are rejected by the deterministic shape and
|
||||||
source-reference validators.
|
source-reference validators.
|
||||||
|
|
||||||
|
### `internal/modules/dnd/extract/scenedescriptions`
|
||||||
|
|
||||||
|
The scene-description extractor makes one structured completion for each
|
||||||
|
accepted chunk and maps its private `kind`, `title`, and `summary` response to
|
||||||
|
one `dnd.SceneDescription`. It assigns the current chunk ID and exact range,
|
||||||
|
preserves kind without repair, and trims only title and summary whitespace.
|
||||||
|
Optional players, party, and glossary references can disambiguate prompt terms
|
||||||
|
but do not supply evidence. The package owns its private schema, prompt assets,
|
||||||
|
and mapping fingerprint; deterministic validators own the durable semantic
|
||||||
|
checks. The durable contract is defined in the
|
||||||
|
[D&D scene-description artifact contract](../integrations/dnd-scene-description-artifacts.md).
|
||||||
|
|
||||||
### `internal/modules/dnd/extract/combatturns`
|
### `internal/modules/dnd/extract/combatturns`
|
||||||
|
|
||||||
The combat extractor prepares one structured request per supplied chunk using
|
The combat extractor prepares one structured request per supplied chunk using
|
||||||
@@ -382,6 +400,15 @@ merge, or summarize distinct occurrences. Its metadata and fingerprints expose
|
|||||||
the normalization and NPC identity policies; generated registry identity stays
|
the normalization and NPC identity policies; generated registry identity stays
|
||||||
in framework provenance and checkpoint dependencies.
|
in framework provenance and checkpoint dependencies.
|
||||||
|
|
||||||
|
### `internal/modules/dnd/normalize/scenedescriptions`
|
||||||
|
|
||||||
|
The scene-description normalizer has no options or references. It validates
|
||||||
|
each source range against the source document, trims title and summary
|
||||||
|
whitespace, orders records by source position then ID, removes only exactly
|
||||||
|
identical records, and rejects conflicting reused IDs or ranges. Its policy
|
||||||
|
fingerprint identifies this deterministic behavior; the matching invariant
|
||||||
|
validator checks the normalized result in the production chain.
|
||||||
|
|
||||||
## Output Encoder
|
## Output Encoder
|
||||||
|
|
||||||
### `internal/modules/generic/output/json`
|
### `internal/modules/generic/output/json`
|
||||||
@@ -484,6 +511,18 @@ order, chronology, and exact duplicate identity. The production chains run
|
|||||||
shape, registry, and source-reference checks before JSON Schema validation;
|
shape, registry, and source-reference checks before JSON Schema validation;
|
||||||
relatedness remains warning-only and last.
|
relatedness remains warning-only and last.
|
||||||
|
|
||||||
|
## D&D Scene Description Validators
|
||||||
|
|
||||||
|
Scene-description shape validation owns the non-empty list, trimmed ID and
|
||||||
|
prose, closed kind, and basic source-reference shape. Extract-stage source
|
||||||
|
validation additionally requires the one record to attach exactly to the
|
||||||
|
current accepted chunk; later source validation checks source membership.
|
||||||
|
Relatedness checks the title and summary independently against only their cited
|
||||||
|
transcript range and emits bounded advisory warnings. The normalized-invariants
|
||||||
|
validator owns ordering, exact duplicate elimination, and conflicting ID or
|
||||||
|
range detection. The production chains run shape and source-reference checks
|
||||||
|
before JSON Schema validation; the warning-only relatedness check is last.
|
||||||
|
|
||||||
## Production Registration
|
## Production Registration
|
||||||
|
|
||||||
Production composition occurs through family registrars. The CLI allocates one
|
Production composition occurs through family registrars. The CLI allocates one
|
||||||
@@ -492,7 +531,7 @@ complete framework registry set and one LLM asset registry. It invokes
|
|||||||
`internal/modules/seriatim/register`, and `internal/modules/dnd/register` in
|
`internal/modules/seriatim/register`, and `internal/modules/dnd/register` in
|
||||||
that order, then exposes the matching catalog for resolution. The generic and
|
that order, then exposes the matching catalog for resolution. The generic and
|
||||||
Seriatim registrars own their production leaf registrations. The D&D registrar
|
Seriatim registrars own their production leaf registrations. The D&D registrar
|
||||||
owns D&D leaf registrations, typed spell, NPC, combat, and interaction default-validator
|
owns D&D leaf registrations, typed spell, NPC, combat, interaction, and scene-description default-validator
|
||||||
chains, typed append-order specializations, and D&D prompt/schema asset
|
chains, typed append-order specializations, and D&D prompt/schema asset
|
||||||
collection. Its registration helpers group module, validator, prompt-asset, and
|
collection. Its registration helpers group module, validator, prompt-asset, and
|
||||||
chain composition while retaining artifact-specific merge and clone behavior in
|
chain composition while retaining artifact-specific merge and clone behavior in
|
||||||
|
|||||||
@@ -68,9 +68,10 @@ run-local construction closures. Preparation injects shared dependencies and
|
|||||||
constructs input, chunk, validators, ordered lanes, and output before source
|
constructs input, chunk, validators, ordered lanes, and output before source
|
||||||
parsing. Production modules use strict construction-time option decoding, and
|
parsing. Production modules use strict construction-time option decoding, and
|
||||||
LLM-backed modules retain the injected shared client. The D&D family registers
|
LLM-backed modules retain the injected shared client. The D&D family registers
|
||||||
the canonical `dnd/spell-list`, `dnd/npc-list`, `dnd/combat-turn-list`, and
|
the canonical `dnd/spell-list`, `dnd/npc-list`, `dnd/combat-turn-list`,
|
||||||
`dnd/npc-interaction-list` codecs, typed spell, NPC, combat, and interaction
|
`dnd/npc-interaction-list`, and `dnd/scene-description-list` codecs, typed
|
||||||
extractors and normalizers, validators,
|
spell, NPC, combat, interaction, and scene-description extractors and
|
||||||
|
normalizers, validators,
|
||||||
plus kind-specific generic merge strategies; generic JSON validators use the
|
plus kind-specific generic merge strategies; generic JSON validators use the
|
||||||
serialized-validation contract. The runner executes lanes through
|
serialized-validation contract. The runner executes lanes through
|
||||||
private exact-type-checked closures, coordinates extract results independently
|
private exact-type-checked closures, coordinates extract results independently
|
||||||
@@ -89,20 +90,24 @@ Configuration. The implemented module packages are:
|
|||||||
| `internal/modules/seriatim/input/transcript` | Parses the supported Seriatim transcript format into the generic source model. |
|
| `internal/modules/seriatim/input/transcript` | Parses the supported Seriatim transcript format into the generic source model. |
|
||||||
| `internal/modules/generic/chunk/units` | Splits ordered source units by unit count and overlap. |
|
| `internal/modules/generic/chunk/units` | Splits ordered source units by unit count and overlap. |
|
||||||
| `internal/modules/dnd/chunk/scenes` | Produces contiguous D&D scene chunks from structured model output. |
|
| `internal/modules/dnd/chunk/scenes` | Produces contiguous D&D scene chunks from structured model output. |
|
||||||
| `internal/modules/dnd` | Owns the canonical D&D spell-list, spell-cast, NPC-list, NPC, combat-turn-list, combat-turn, NPC-interaction-list, and NPC-interaction artifact types. |
|
| `internal/modules/dnd` | Owns the canonical D&D spell-list, spell-cast, NPC-list, NPC, combat-turn-list, combat-turn, NPC-interaction-list, and scene-description-list 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/codec/npcs` | Strictly decodes and stably encodes the durable D&D NPC-list representation. |
|
| `internal/modules/dnd/codec/npcs` | Strictly decodes and stably encodes the durable D&D NPC-list representation. |
|
||||||
| `internal/modules/dnd/codec/combatturns` | Strictly decodes and stably encodes the durable D&D combat-turn-list representation. |
|
| `internal/modules/dnd/codec/combatturns` | Strictly decodes and stably encodes the durable D&D combat-turn-list representation. |
|
||||||
| `internal/modules/dnd/codec/npcinteractions` | Strictly decodes and stably encodes the durable D&D NPC-interaction-list representation. |
|
| `internal/modules/dnd/codec/npcinteractions` | Strictly decodes and stably encodes the durable D&D NPC-interaction-list representation. |
|
||||||
|
| `internal/modules/dnd/codec/scenedescriptions` | Strictly decodes and stably encodes the durable D&D scene-description-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/extract/npcs` | Maps private structured model output to canonical source-grounded D&D NPC lists. |
|
| `internal/modules/dnd/extract/npcs` | Maps private structured model output to canonical source-grounded D&D NPC lists. |
|
||||||
| `internal/modules/dnd/extract/combatturns` | Maps private structured model output to source-grounded D&D combat-turn candidates and preserves chronology and invalid candidate values for validators. |
|
| `internal/modules/dnd/extract/combatturns` | Maps private structured model output to source-grounded D&D combat-turn candidates and preserves chronology and invalid candidate values for validators. |
|
||||||
| `internal/modules/dnd/extract/npcinteractions` | Maps private structured model output to current-source NPC interaction candidates grounded by a required registry. |
|
| `internal/modules/dnd/extract/npcinteractions` | Maps private structured model output to current-source NPC interaction candidates grounded by a required registry. |
|
||||||
|
| `internal/modules/dnd/extract/scenedescriptions` | Maps one private scene description to the current accepted chunk's ID and exact range. |
|
||||||
| `internal/modules/dnd/npcinteractions` | Owns canonical source-reference ordering, occurrence ordering, valid-evidence checks, and exact interaction identity shared by normalization and invariant validation. |
|
| `internal/modules/dnd/npcinteractions` | Owns canonical source-reference ordering, occurrence ordering, valid-evidence checks, and exact interaction identity shared by normalization and invariant validation. |
|
||||||
| `internal/modules/dnd/normalize/combatturns` | Canonicalizes and orders merged combat turns, applies exact NPC identity matches, and collapses only exact valid-evidence duplicates. |
|
| `internal/modules/dnd/normalize/combatturns` | Canonicalizes and orders merged combat turns, applies exact NPC identity matches, and collapses only exact valid-evidence duplicates. |
|
||||||
| `internal/modules/dnd/normalize/npcinteractions` | Canonicalizes required-registry names, orders interaction occurrences, and collapses only exact valid-evidence duplicates. |
|
| `internal/modules/dnd/normalize/npcinteractions` | Canonicalizes required-registry names, orders interaction occurrences, and collapses only exact valid-evidence duplicates. |
|
||||||
|
| `internal/modules/dnd/normalize/scenedescriptions` | Trims, source-orders, and removes only exactly identical scene descriptions while rejecting ID and range conflicts. |
|
||||||
| `internal/modules/dnd/validate/combatturns` | Provides deterministic shape, source-reference, source-relatedness, and normalized-invariant validation for the production combat chains. |
|
| `internal/modules/dnd/validate/combatturns` | Provides deterministic shape, source-reference, source-relatedness, and normalized-invariant validation for the production combat chains. |
|
||||||
| `internal/modules/dnd/validate/npcinteractions` | Provides deterministic shape, registry, source-reference, source-relatedness, and normalized-invariant validation for interaction chains. |
|
| `internal/modules/dnd/validate/npcinteractions` | Provides deterministic shape, registry, source-reference, source-relatedness, and normalized-invariant validation for interaction chains. |
|
||||||
|
| `internal/modules/dnd/validate/scenedescriptions` | Provides deterministic shape, exact extraction attachment, source-relatedness, and normalized-invariant validation for scene-description chains. |
|
||||||
| `internal/modules/dnd/npcs/registry` | Resolves validated normalized NPC references into immutable grounding data and exact identity lookup. |
|
| `internal/modules/dnd/npcs/registry` | Resolves validated normalized NPC references into immutable grounding data and exact identity lookup. |
|
||||||
| `internal/modules/dnd/npcs/identity` | Owns Unicode-aware NPC identity, ID derivation, and registry collision validation. |
|
| `internal/modules/dnd/npcs/identity` | Owns Unicode-aware NPC identity, ID derivation, and registry collision validation. |
|
||||||
| `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/dnd/spells/catalog` | Embeds and validates the versioned D&D 5e 2014 SRD catalog, composes optional overlays, and provides immutable effective lookup. |
|
||||||
|
|||||||
@@ -119,10 +119,10 @@ extractor's artifact kind, so variants under one reusable key may declare
|
|||||||
different capabilities and reference slots. Kind-neutral registry inspection
|
different capabilities and reference slots. Kind-neutral registry inspection
|
||||||
selects the first registered artifact kind in sorted order.
|
selects the first registered artifact kind in sorted order.
|
||||||
|
|
||||||
Production composition registers the D&D spell-list codec and typed extractor,
|
Production composition registers the D&D spell-list, NPC-list, combat-turn-list,
|
||||||
matching typed merge, normalize, and semantic-validator variants, and
|
NPC-interaction-list, and scene-description-list codecs and typed lane
|
||||||
serialized JSON validators. Every artifact lane resolves through the typed
|
variants, plus serialized JSON validators. Every artifact lane resolves through
|
||||||
registries and a matching codec.
|
the typed registries and a matching codec.
|
||||||
|
|
||||||
A `ModuleSpec` declares its stage plus required and provided capabilities.
|
A `ModuleSpec` declares its stage plus required and provided capabilities.
|
||||||
Chunk, extract, merge, and normalize specs may also declare reference slots.
|
Chunk, extract, merge, and normalize specs may also declare reference slots.
|
||||||
|
|||||||
@@ -1,6 +1,8 @@
|
|||||||
# D&D Scene Descriptions
|
# D&D Scene Descriptions
|
||||||
|
|
||||||
Status: Accepted
|
Status: Implemented
|
||||||
|
|
||||||
|
The durable output contract is [D&D Scene Description Artifact Contract](../integrations/dnd-scene-description-artifacts.md).
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
|
|||||||
@@ -16,13 +16,6 @@ not as committed release dates.
|
|||||||
validator, and normalizer development. Treat model-quality review as an
|
validator, and normalizer development. Treat model-quality review as an
|
||||||
iterative human evaluation aid, not a deterministic correctness gate.
|
iterative human evaluation aid, not a deterministic correctness gate.
|
||||||
|
|
||||||
### Extract D&D Scene Descriptions
|
|
||||||
|
|
||||||
Add one minimal, source-bounded description for each accepted D&D scene chunk.
|
|
||||||
The proposed durable contract, scene-kind policy, evidence boundary, and
|
|
||||||
relationship to later chunker minimization are defined in
|
|
||||||
[D&D Scene Descriptions](dnd-scene-descriptions.md).
|
|
||||||
|
|
||||||
### Minimize And Use D&D Scene Chunking
|
### Minimize And Use D&D Scene Chunking
|
||||||
|
|
||||||
- Reduce the D&D scene chunker toward its narrow responsibility: identifying
|
- Reduce the D&D scene chunker toward its narrow responsibility: identifying
|
||||||
|
|||||||
20
examples/dnd-scene-descriptions.config.yml
Normal file
20
examples/dnd-scene-descriptions.config.yml
Normal file
@@ -0,0 +1,20 @@
|
|||||||
|
version: 3
|
||||||
|
output:
|
||||||
|
directory: ./notarius-output
|
||||||
|
cache:
|
||||||
|
chunk_plans:
|
||||||
|
mode: bypass
|
||||||
|
directory: ./notarius-cache/chunk-plans
|
||||||
|
checkpoints:
|
||||||
|
enabled: false
|
||||||
|
directory: ./notarius-cache/checkpoints
|
||||||
|
debug:
|
||||||
|
directory: ./notarius-debug
|
||||||
|
pipelines:
|
||||||
|
dnd-scene-descriptions:
|
||||||
|
input: seriatim
|
||||||
|
chunk: dnd/scenes
|
||||||
|
artifacts:
|
||||||
|
scene-descriptions:
|
||||||
|
extract: dnd/scene-descriptions
|
||||||
|
normalize: dnd/scene-descriptions
|
||||||
@@ -544,6 +544,7 @@ func maintainedExampleFiles(t *testing.T) []maintainedExample {
|
|||||||
{name: "combat", path: repositoryPath("examples", "dnd-combat-turns.config.yml"), pipelineIDs: []string{"dnd-combat"}},
|
{name: "combat", path: repositoryPath("examples", "dnd-combat-turns.config.yml"), pipelineIDs: []string{"dnd-combat"}},
|
||||||
{name: "npc-grounded", path: repositoryPath("examples", "dnd-npc-grounded.config.yml"), pipelineIDs: []string{"dnd-npc-grounded"}},
|
{name: "npc-grounded", path: repositoryPath("examples", "dnd-npc-grounded.config.yml"), pipelineIDs: []string{"dnd-npc-grounded"}},
|
||||||
{name: "npc-interactions", path: repositoryPath("examples", "dnd-npc-interactions.config.yml"), pipelineIDs: []string{"dnd-npc-interactions"}},
|
{name: "npc-interactions", path: repositoryPath("examples", "dnd-npc-interactions.config.yml"), pipelineIDs: []string{"dnd-npc-interactions"}},
|
||||||
|
{name: "scene-descriptions", path: repositoryPath("examples", "dnd-scene-descriptions.config.yml"), pipelineIDs: []string{"dnd-scene-descriptions"}},
|
||||||
{name: "scene-chunk-map", path: repositoryPath("examples", "dnd-scene-chunk-map.config.yml"), pipelineIDs: []string{"dnd-scene-chunk-map"}},
|
{name: "scene-chunk-map", path: repositoryPath("examples", "dnd-scene-chunk-map.config.yml"), pipelineIDs: []string{"dnd-scene-chunk-map"}},
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user