eric/seriatim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Implement artifact-level render command with Markdown output and update docs

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-24 22:55:56 +00:00
parent a90859114a
commit c37ea70dcb
28 changed files with 1619 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/cli.md
View File

@@ -16,6 +16,7 @@ go run ./cmd/seriatim merge \
| `merge` | Merge one or more raw transcript JSON inputs into one seriatim artifact. |
| `trim` | Keep or remove segment IDs from an existing seriatim artifact. |
| `normalize` | Canonicalize transcript-like JSON into a seriatim artifact. |
| `render` | Render an existing seriatim artifact as Markdown. |
Root usage:
@@ -130,6 +131,34 @@ Flags:
- Does not run merge modules.
- When `--output-schema` is omitted, schema resolution is: `SERIATIM_OUTPUT_SCHEMA` -> default `seriatim-intermediate`.
## `render`
Usage:
```text
seriatim render [flags]
```
Flags:
| Flag | Required | Default | Description |
| --- | --- | --- | --- |
| `--input-file string` | Yes | none | Input seriatim artifact JSON file. |
| `--output-file string` | Yes | none | Rendered output file path. |
| `--format string` | Yes | none | Output format. Current supported value: `markdown`. |
| `--title string` | No | `Transcript` | Markdown document title. |
| `--include-timestamps` | No | `true` | Include `[HH:MM:SS–HH:MM:SS]` per segment. |
| `--include-segment-ids` | No | `false` | Include `[#id]` marker per segment. |
| `--include-metadata` | No | `false` | Include artifact metadata block near the top. |
`render` behavior:
- Input must be a valid existing seriatim output artifact (`seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`).
- Raw WhisperX-style JSON is rejected.
- `render` does not execute merge/trim/normalize transformations.
- Markdown output is deterministic for the same input artifact and render flags.
- Category names are not printed directly; `background`, `backchannel`, and `filler` only influence italics.
## Common workflows
Merge with a speaker map and report output:
@@ -160,6 +189,15 @@ go run ./cmd/seriatim normalize \
--output-file /tmp/seriatim-example-normalize-object.json
```
Render an existing artifact as Markdown:
```sh
go run ./cmd/seriatim render \
--input-file examples/render/input-intermediate.json \
--output-file /tmp/seriatim-example-render.md \
--format markdown
```
## Exit and errors
- Commands return exit code `0` on success.

16
docs/config.md
View File

@@ -23,6 +23,17 @@ For `trim`:
- If `--output-schema` is omitted, output preserves the input artifact schema.
- If `--output-schema` is set, it must be one of `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`.
## Render format and defaults
`render` requires `--format`. Current supported value is `markdown`.
Render defaults:
- `--title`: `Transcript`
- `--include-timestamps`: `true`
- `--include-segment-ids`: `false`
- `--include-metadata`: `false`
## Merge module defaults
Default merge module selections:
@@ -152,6 +163,11 @@ All commands:
- Validates `--output-schema` through the same schema set as `merge`.
- Currently accepts only `json` in `--output-modules`.
`render`:
- Requires `--input-file`, `--output-file`, and `--format`.
- Validates `--format` as `markdown`.
## Related docs
- CLI reference: [cli.md](cli.md)

3
docs/integrations/output-schemas.md
View File

@@ -8,7 +8,8 @@ seriatim emits one of three public JSON output contracts:
- `seriatim-intermediate`
- `seriatim-full`
These are used by `merge`, `trim`, and `normalize`.
These are used by `merge`, `trim`, and `normalize`, and are accepted as input
by `render`.
## Schema roles

132
docs/internal/artifacts.md
View File

@@ -2,8 +2,8 @@
## Purpose
Describes public artifact conversion and validation internals for merge output,
trim, and normalize.
Describes implemented artifact parsing, conversion, validation, and render-model
normalization internals.
## Artifact contracts
@@ -19,35 +19,40 @@ Machine-readable schemas:
- `schema/intermediate-output.schema.json`
- `schema/minimal-output.schema.json`
## Schema selection
## Shared output-artifact parser
Merge pipeline conversion uses `internal/artifact.SelectedFromMerged`:
`internal/artifact/output_artifact.go` provides schema-aware parsing for
existing seriatim output artifacts.
Behavior:
- accepts only valid full, intermediate, or minimal seriatim output artifacts
- validates through `schema` semantic + JSON schema checks
- rejects malformed JSON
- rejects raw WhisperX-style JSON and other non-seriatim shapes
Consumers:
- `internal/trim` artifact-level trim flow
- `internal/render` artifact-level render flow
## Merge conversion behavior
`internal/artifact/transcript.go` converts `model.MergedTranscript` to public
contracts:
- full schema preserves source/provenance, overlap groups, and metadata module
lists
- intermediate schema emits segment timing/text/speaker with optional
categories and compact metadata
- minimal schema emits compact segment timing/text/speaker and compact metadata
Schema selection uses `internal/artifact.SelectedFromMerged`:
- `seriatim-full` -> `artifact.FromMerged`
- `seriatim-intermediate` -> `artifact.IntermediateFromMerged`
- `seriatim-minimal` -> `artifact.MinimalFromMerged`
Unknown/empty selection falls back to intermediate conversion.
## Merge conversion behavior
`internal/artifact` converts `model.MergedTranscript` to public contracts:
- full schema preserves source/provenance, overlap groups, and metadata module
lists.
- intermediate schema emits segment timing/text/speaker with optional
categories and compact metadata.
- minimal schema emits compact segment timing/text/speaker and compact
metadata.
## Validation behavior
`schema/output.go` validates both structure and semantics:
- embedded JSON Schema validation via `jsonschema/v6`
- semantic checks for sequential segment IDs starting at `1`
- semantic checks for non-inverted segment timing (`end >= start`)
- full schema overlap-group timing checks (`group.end >= group.start`)
- unknown/empty -> intermediate fallback
## Trim internals
@@ -72,9 +77,8 @@ Apply layer (`apply.go`):
- schema-specific segment reconstruction for full/intermediate/minimal outputs
- overlap-group recomputation only for full-schema outputs
Artifact layer (`artifact.go`):
Artifact conversion layer (`artifact.go`):
- schema detection for full/intermediate/minimal artifacts
- schema-preserving trim application
- supported schema conversions:
- full -> intermediate/minimal
@@ -85,10 +89,10 @@ Artifact layer (`artifact.go`):
Trim invariants:
- selected IDs must exist in input.
- input IDs must be positive, unique, sequential.
- retained segment order follows input transcript order.
- output IDs are reassigned to `1..N`.
- selected IDs must exist in input
- input IDs must be positive, unique, sequential
- retained segment order follows input transcript order
- output IDs are reassigned to `1..N`
## Normalize internals
@@ -117,13 +121,64 @@ Run layer (`normalize.go`):
Normalize invariant:
- report events do not embed transcript text.
- report events do not embed transcript text
## Render internals
`internal/render` is an artifact-level, downstream-only renderer.
Model normalization (`normalize.go`):
- converts full/intermediate/minimal artifacts into a common render model
- preserves segment order and segment IDs
- normalizes per-segment fields to ID, start, end, speaker, text, categories
- emits empty categories slice when categories are absent in input
Renderer registry (`registry.go`):
- resolves renderers by public format name
- currently registers `markdown`
Markdown renderer (`markdown.go`):
- writes title header `# {title}`
- renders optional `[HH:MM:SS–HH:MM:SS]` timestamps
- renders optional `[#id]` segment references
- renders `**speaker:** text`
- italicizes text when categories include `background`, `backchannel`, or
`filler`
- ignores unknown categories
- optionally includes metadata summary block
Run layer (`run.go`):
1. Read input artifact JSON.
2. Parse via shared output-artifact parser.
3. Normalize to render model.
4. Resolve renderer by `--format`.
5. Render text output.
6. Write output file.
Render invariants:
- does not run merge/trim/normalize modules
- does not expose report output
- deterministic for identical input artifact and render flags
## Validation behavior
`schema/output.go` validates both structure and semantics:
- embedded JSON Schema validation via `jsonschema/v6`
- semantic checks for sequential segment IDs starting at `1`
- semantic checks for non-inverted segment timing (`end >= start`)
- full schema overlap-group timing checks (`group.end >= group.start`)
## Boundaries
- CLI flag semantics belong to `docs/cli.md`.
- Runtime config/env surfaces belong to `docs/config.md`.
- This doc describes internal conversion/validation behavior only.
- This document describes internal conversion/validation behavior only.
## Failure behavior
@@ -133,22 +188,29 @@ Representative failure classes:
- schema validation failure for parsed artifact or built output
- unsupported schema conversion path (trim)
- selector or input-ID consistency errors (trim)
- unsupported renderer format (render)
- output/report file write failures from command paths
## Tests to inspect before changes
- `schema/output_test.go`
- `internal/artifact/transcript_test.go`
- `internal/artifact/output_artifact_test.go`
- `internal/trim/selector_test.go`
- `internal/trim/artifact_test.go`
- `internal/trim/apply_test.go`
- `internal/normalize/parse_test.go`
- `internal/render/normalize_test.go`
- `internal/render/markdown_test.go`
- `internal/render/registry_test.go`
- `internal/cli/trim_test.go`
- `internal/cli/normalize_test.go`
- `internal/cli/render_test.go`
## Invariants
- Public artifacts are validated through `schema` before acceptance.
- Segment IDs in emitted artifacts are sequential and deterministic.
- Internal-only fields are not emitted in minimal/intermediate contracts.
- Trim and normalize stay artifact-level and do not execute merge modules.
- Trim, normalize, and render stay artifact-level and do not execute merge
modules.

3
docs/internal/pipeline.md
View File

@@ -73,7 +73,8 @@ coalesce gap and overlap thresholds).
- Pipeline does not parse CLI flags.
- Pipeline does not normalize raw CLI strings.
- Pipeline delegates conversion to public output contracts to `internal/artifact`.
- Artifact-level commands `trim` and `normalize` are outside this pipeline.
- Artifact-level commands `trim`, `normalize`, and `render` are outside this
pipeline.
## Failure behavior

30
docs/operations.md
View File

@@ -7,6 +7,7 @@ This document covers runtime operation of the implemented CLI commands:
- `merge`
- `trim`
- `normalize`
- `render`
## Runtime model
@@ -29,6 +30,7 @@ Command-specific expectations:
- `merge`: requires at least one `--input-file`; optional `--speakers` and `--autocorrect` paths must exist when provided.
- `trim`: input must be an existing valid seriatim artifact JSON file.
- `normalize`: input must be a JSON object with `segments` or a top-level segment array.
- `render`: input must be an existing valid seriatim artifact JSON file.
## Normal workflow
@@ -80,11 +82,28 @@ go run ./cmd/seriatim normalize \
--report-file normalize-report.json
```
### Render
1. Provide existing seriatim artifact with `--input-file`.
2. Provide `--output-file`.
3. Provide `--format markdown`.
4. Optionally provide `--title`, `--include-timestamps`, `--include-segment-ids`, and `--include-metadata`.
Example:
```sh
go run ./cmd/seriatim render \
--input-file normalized.json \
--output-file transcript.md \
--format markdown
```
## Output and report artifacts
Primary output:
Primary outputs:
- `--output-file` writes JSON transcript artifact in selected schema.
- `merge`, `trim`, `normalize`: `--output-file` writes JSON transcript artifact in the selected schema.
- `render`: `--output-file` writes presentation Markdown.
Optional report output:
@@ -92,6 +111,7 @@ Optional report output:
- `merge` report metadata records reader/modules and event sequence.
- `trim` report includes a `trim-audit` event with mode/selector/counts and old-to-new ID mapping.
- `normalize` report includes a `normalize-audit` event with input shape, repair stats, and output selection details.
- `render` has no report output in the current implementation.
## Failure and retry behavior
@@ -106,9 +126,10 @@ Retry guidance:
2. Re-run the same command.
3. If a prior run created a partial or unwanted output/report file, remove it and rerun.
Operational note:
Operational notes:
- With identical inputs/config/version, merge behavior is deterministic and input files are sorted before processing.
- With identical inputs/config/version, `merge` behavior is deterministic and input files are sorted before processing.
- With identical input artifact and render flags, `render` output is deterministic.
## Cleanup
@@ -124,6 +145,7 @@ Transcript artifacts and reports are local files and may contain sensitive conve
- Store outputs in controlled directories with appropriate OS permissions.
- Share report files carefully; they include file paths and processing diagnostics.
- Normalize report events intentionally avoid embedding transcript text, but output artifacts contain transcript content.
- Rendered Markdown is human-readable transcript content and should be handled as sensitive output when applicable.
## Related docs

31
docs/policy/architecture.md
View File

@@ -14,7 +14,7 @@ must describe current behavior only; planned or speculative work belongs under
## Project Shape
seriatim is a Go CLI for transcript artifact processing. The implemented
commands are `merge`, `trim`, and `normalize`.
commands are `merge`, `trim`, `normalize`, and `render`.
`merge` reads one or more JSON transcript files, optionally maps input files to
canonical speakers, runs a registry-selected preprocessing chain, merges
@@ -22,11 +22,12 @@ canonical segments into deterministic chronological order, runs a
registry-selected postprocessing chain, validates the selected output schema,
and writes JSON output plus an optional JSON report.
`trim` and `normalize` are artifact-level commands outside the merge pipeline.
`trim` reads an existing seriatim output artifact and projects it by segment ID.
`normalize` reads transcript-like JSON and emits one of seriatim's supported
output schemas. Neither command runs merge preprocessing or postprocessing
modules.
`trim`, `normalize`, and `render` are artifact-level commands outside the merge
pipeline. `trim` reads an existing seriatim output artifact and projects it by
segment ID. `normalize` reads transcript-like JSON and emits one of seriatim's
supported output schemas. `render` reads an existing seriatim output artifact
and emits human-readable Markdown. None of these commands runs merge
preprocessing or postprocessing modules.
The supported public output schemas are `seriatim-minimal`,
`seriatim-intermediate`, and `seriatim-full`. For command and flag details, use
@@ -66,9 +67,9 @@ collects report events, converts the final transcript, and writes optional
reports. Built-in adapters and modules are registered from `internal/builtin`.
CLI code in `internal/cli` should parse flags, build validated config values,
and delegate. `merge` delegates to `pipeline.Run`; `trim` and `normalize`
perform artifact-level orchestration and delegate deterministic parsing,
validation, and transformation work to their internal packages.
and delegate. `merge` delegates to `pipeline.Run`; `trim`, `normalize`, and
`render` perform artifact-level orchestration and delegate deterministic
parsing, validation, and transformation work to their internal packages.
Config loading and validation belongs in `internal/config`. Filesystem reads and
writes are adapter concerns and should not spread into pure transformation
@@ -166,10 +167,10 @@ correction or annotation modules, inspect the package tests for overlap,
coalesce, danglers, backchannel, filler, and autocorrect behavior.
When changing artifact-level commands, inspect `internal/trim`,
`internal/normalize`, and their CLI tests. When changing public output shape or
schema validation, inspect `schema` and `internal/artifact` tests. Report and
diagnostic changes should be covered through the command or package tests that
emit the affected events.
`internal/normalize`, `internal/render`, and their CLI tests. When changing
public output shape or schema validation, inspect `schema` and
`internal/artifact` tests. Report and diagnostic changes should be covered
through the command or package tests that emit the affected events.
## Dependency Policy
@@ -202,8 +203,8 @@ free of secrets or private transcript data.
registry name.
- Preserve deterministic ordering, final segment ID assignment, and schema
validation before output acceptance.
- Keep `trim` and `normalize` artifact-level; do not run merge modules from
those commands.
- Keep `trim`, `normalize`, and `render` artifact-level; do not run merge
modules from those commands.
- Keep public output schemas validated through `schema`.
- Keep optional reports ordered, concise, and diagnostic.
- Avoid broad dependencies without a concrete maintainability benefit.

2
docs/policy/development.md
View File

@@ -16,6 +16,7 @@ It complements [architecture policy](architecture.md) and
- `internal/artifact/`: conversion from internal merged model to public shapes.
- `internal/trim/`: artifact-level trim logic.
- `internal/normalize/`: artifact-level normalize parsing/building.
- `internal/render/`: artifact-level rendering and renderer registry.
- `internal/*` domain packages: overlap, coalesce, danglers, filler,
backchannel, speaker, autocorrect, report, model.
- `schema/`: public structs plus embedded JSON Schemas and validation.
@@ -36,6 +37,7 @@ go run ./cmd/seriatim --help
go run ./cmd/seriatim merge --help
go run ./cmd/seriatim trim --help
go run ./cmd/seriatim normalize --help
go run ./cmd/seriatim render --help
```
Current toolchain note: