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 compatibility through named pipeline profiles.

Out of scope:

D&D extraction;
LLM extraction calls;
transcript-specific behavior in runner/core packages;
support for every possible Seriatim schema variant.

Target End State

The repository should contain a real Seriatim input-stage module that translates Seriatim minimal transcript JSON into the generic source model.

The Seriatim module should be registered under the stable input adapter key seriatim. It should be selectable through the existing input adapter registry and through pipeline-profile resolution when a profile binds input: seriatim.

The module should accept the Seriatim minimal output shape:

top-level metadata;
top-level segments;
segment id;
segment start;
segment end;
segment speaker;
segment text.

The module should map Seriatim data into generic source values:

segment id becomes SourceUnit.ID;
segment text becomes SourceUnit.Text;
the document and unit kind strings identify transcript-like source material without adding transcript-specific fields or types to core packages;
speaker, start, and end become source-unit metadata;
top-level Seriatim metadata becomes source-document metadata;
the resulting source document passes core source validation.

The module should reject invalid Seriatim input with clear module-specific errors. Validation should cover:

valid JSON;
required top-level metadata and segments;
required segment fields;
unique segment IDs;
non-empty segment text;
valid start and end values.

The module should declare flat capabilities for pipeline validation. Initial capabilities should describe transcript-oriented source properties preserved by the adapter, including speaker and timestamp metadata.

Implementation staging belongs in implementation.md.

Fixtures And Tests

The checkpoint should add synthetic fixtures and focused 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?

3.5 KiB Raw Blame History