119 lines
3.3 KiB
Markdown
119 lines
3.3 KiB
Markdown
# 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.
|
|
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"id": "session-alpha",
|
|
"title": "Synthetic D&D spell session"
|
|
},
|
|
"segments": [
|
|
{
|
|
"id": 1,
|
|
"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](../../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 not positive integer JSON numbers or numeric
|
|
strings;
|
|
- non-string `speaker` or `text`;
|
|
- 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 integer `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 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.
|