127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# Checkpoint 5: Seriatim Input Module
|
|
|
|
## Status
|
|
|
|
This document describes planned work, not implemented behavior.
|
|
|
|
## Goal
|
|
|
|
Add the first real input source while keeping transcript-specific behavior
|
|
isolated inside an input-stage module.
|
|
|
|
This checkpoint should allow Seriatim minimal transcript JSON to become a
|
|
generic `SourceDocument`.
|
|
|
|
## Scope
|
|
|
|
In scope:
|
|
|
|
- `internal/modules/input/seriatim`;
|
|
- parser for Seriatim minimal output JSON;
|
|
- mapping into `SourceDocument` and `SourceUnit`;
|
|
- source-document validation;
|
|
- input adapter registry wiring;
|
|
- module metadata/capabilities for pipeline validation;
|
|
- fixtures and tests;
|
|
- config path to use the input module through a named pipeline profile if
|
|
config loading exists.
|
|
|
|
Out of scope:
|
|
|
|
- D&D extraction;
|
|
- LLM extraction calls;
|
|
- transcript-specific behavior in runner/core packages;
|
|
- support for every possible Seriatim schema variant.
|
|
|
|
## Proposed Stages
|
|
|
|
### Seriatim Source Model
|
|
|
|
Define module-local structs for the Seriatim minimal output schema.
|
|
|
|
Expected external shape:
|
|
|
|
- top-level `metadata`;
|
|
- top-level `segments`;
|
|
- segment `id`;
|
|
- segment `start`;
|
|
- segment `end`;
|
|
- segment `speaker`;
|
|
- segment `text`.
|
|
|
|
Keep these structs in the Seriatim input module package.
|
|
|
|
### Parse And Validate
|
|
|
|
Implement parser and validation behavior.
|
|
|
|
Validation should cover:
|
|
|
|
- valid JSON;
|
|
- required metadata fields;
|
|
- required segment fields;
|
|
- unique segment IDs;
|
|
- non-empty segment text;
|
|
- valid start/end values as appropriate.
|
|
|
|
Prefer clear module-specific errors.
|
|
|
|
### Map To SourceDocument
|
|
|
|
Map Seriatim data into the generic source model:
|
|
|
|
- segment `id` becomes `SourceUnit.ID`;
|
|
- segment `text` becomes `SourceUnit.Text`;
|
|
- unit kind should identify transcript-like units without requiring core
|
|
packages to know transcript semantics;
|
|
- `speaker`, `start`, and `end` become unit metadata;
|
|
- Seriatim metadata becomes document metadata.
|
|
|
|
The resulting `SourceDocument` should pass core source validation.
|
|
|
|
### Registry And CLI Wiring
|
|
|
|
Register the module under a stable input adapter key, likely `seriatim`.
|
|
|
|
Declare module metadata for pipeline validation. Initial provided capabilities
|
|
should include transcript-oriented metadata such as `speaker` and `timestamps`
|
|
if those fields are preserved from Seriatim input.
|
|
|
|
If config and CLI support exist, add a minimal pipeline-profile fixture or test
|
|
config using the Seriatim input module:
|
|
|
|
```sh
|
|
notarius run dnd-session --input ./transcript.json --only spells
|
|
```
|
|
|
|
The command may still use fake extract, merge, normalize, and output modules
|
|
until checkpoint 6.
|
|
|
|
### Fixtures And Tests
|
|
|
|
Add fixtures and tests for:
|
|
|
|
- valid Seriatim minimal transcript;
|
|
- malformed JSON;
|
|
- missing metadata;
|
|
- missing or duplicate segment IDs;
|
|
- empty segment text;
|
|
- source-reference compatibility with generated unit IDs.
|
|
|
|
## Done Criteria
|
|
|
|
- `go test ./...` passes.
|
|
- Seriatim minimal transcript JSON maps into `SourceDocument`.
|
|
- Transcript fields do not appear in core runner contracts.
|
|
- The input module is selectable through the registry and pipeline-profile
|
|
configuration when config support exists.
|
|
- The input module declares capabilities needed for pipeline validation.
|
|
- Tests prove transcript-specific assumptions are isolated to the input module.
|
|
|
|
## Review Questions
|
|
|
|
- Are segment, speaker, and timestamp assumptions contained inside the input module?
|
|
- Are unit IDs stable and suitable for source references?
|
|
- Does the input module preserve enough metadata for transcript-oriented output later?
|
|
- Should the input module accept only Seriatim minimal output for now?
|