notarius/docs/integrations/seriatim.md

Seriatim 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+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. This covers the maintained minimal fixture and Seriatim intermediate output that provides the same required segment 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, such as categories, 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;
• segment id values that are neither strings nor numbers;
• non-string 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+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; numeric IDs are converted to their JSON number text, so 1 becomes "1";
• 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 Seriatim transcript JSON with the top-level metadata object and segments array described here. Broader Seriatim output schemas are compatible only when they provide these required fields with the accepted types.