notarius/docs/integrations/seriatim.md

Seriatim Minimal Transcript JSON

This document is the external input contract for the implemented seriatim input adapter.

Adapter

• Module key: seriatim
• Document kind: transcript
• Unit kind: transcript_segment
• Source format: application/vnd.seriatim.minimal+json

The adapter parses raw Seriatim JSON into a generic source document. It owns transcript-specific JSON parsing and metadata mapping; core source and pipeline code stay source-format agnostic.

Accepted Shape

The input must be one JSON object with top-level metadata and segments fields:

{
  "metadata": {
    "id": "session-alpha",
    "title": "Synthetic D&D spell session"
  },
  "segments": [
    {
      "id": "seg-001",
      "start": 0,
      "end": 4,
      "speaker": "Aria",
      "text": "Aria raises her holy symbol and casts Cure Wounds."
    }
  ]
}

The maintained example is examples/seriatim-minimal-transcript.json.

Top-level metadata entries are preserved. Other segment fields are ignored.

Multiple top-level JSON values are rejected.

Validation

The adapter rejects:

• empty raw input;
• malformed JSON;
• top-level JSON that is not an object;
• missing, null, or non-object metadata;
• missing, null, non-array, or empty segments;
• segment values that are not objects;
• non-string id, speaker, or text;
• empty segment IDs;
• segment IDs with leading or trailing whitespace;
• duplicate segment IDs;
• missing or empty speaker;
• missing, empty, invalid, non-finite, or negative start;
• missing, empty, invalid, non-finite, or negative end;
• end values before start;
• missing or empty text.

Segment text is preserved as provided, but it must not be empty after trimming.

Source Mapping

The adapter maps input to SourceDocument:

• metadata becomes SourceDocument.Metadata;
• SourceDocument.Kind is transcript;
• SourceDocument.Format is application/vnd.seriatim.minimal+json;
• SourceDocument.Digest is sha256:<hex> of the exact raw input bytes.

SourceDocument.ID is selected in this order:

1. the parse request source ID, after trimming;
2. metadata.id, when it is a non-empty string after trimming;
3. metadata.source_id, when it is a non-empty string after trimming;
4. seriatim:<first-16-hex-chars-of-raw-sha256>.

Each segment becomes one SourceUnit:

• segment.id becomes SourceUnit.ID;
• segment.text becomes SourceUnit.Text;
• SourceUnit.Kind is transcript_segment;
• speaker, start, and end are stored in source-unit metadata.

Metadata Keys

Seriatim unit metadata uses these keys:

• speaker: string speaker label;
• start: json.Number start value;
• end: json.Number end value.

The internal/modules/input/seriatim package exposes typed accessors for these values.

Capabilities

The module declares these provided capabilities:

• source.transcript
• transcript.speaker
• transcript.timestamps

Compatibility Limit

This contract covers only the minimal transcript JSON shape described here.