159 lines
4.8 KiB
Markdown
159 lines
4.8 KiB
Markdown
# Operations Guide
|
|
|
|
## Scope
|
|
|
|
This document covers runtime operation of the implemented CLI commands:
|
|
|
|
- `merge`
|
|
- `trim`
|
|
- `normalize`
|
|
- `render`
|
|
|
|
## Runtime model
|
|
|
|
seriatim is a single-process, filesystem-only CLI.
|
|
|
|
- Each invocation reads input files, processes in memory, and writes output files.
|
|
- There is no daemon, queue, database, resume checkpoint, remote storage, or background worker.
|
|
- On error, the command exits non-zero; there is no built-in retry/resume flow.
|
|
|
|
## Filesystem expectations
|
|
|
|
All commands require accessible local files and existing parent directories for outputs.
|
|
|
|
- Input paths must exist and must be files.
|
|
- Output/report parent directories must already exist.
|
|
- Output and report files are created with `os.Create`, so existing files at those paths are overwritten.
|
|
|
|
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
|
|
|
|
### Merge
|
|
|
|
1. Provide one or more `--input-file` values.
|
|
2. Optionally provide `--speakers`, `--autocorrect`, and `--report-file`.
|
|
3. Provide `--output-file`.
|
|
4. Run command.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
go run ./cmd/seriatim merge \
|
|
--input-file speaker-a.json \
|
|
--input-file speaker-b.json \
|
|
--output-file merged.json \
|
|
--report-file merge-report.json
|
|
```
|
|
|
|
### Trim
|
|
|
|
1. Provide existing artifact with `--input-file`.
|
|
2. Select segments with exactly one of `--keep` or `--remove`.
|
|
3. Provide `--output-file`.
|
|
4. Optionally provide `--output-schema`, `--allow-empty`, and `--report-file`.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
go run ./cmd/seriatim trim \
|
|
--input-file merged.json \
|
|
--output-file trimmed.json \
|
|
--keep "1-20,25"
|
|
```
|
|
|
|
### Normalize
|
|
|
|
1. Provide `--input-file` containing supported JSON shape.
|
|
2. Provide `--output-file`.
|
|
3. Optionally provide `--output-schema`, `--output-modules`, and `--report-file`.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
go run ./cmd/seriatim normalize \
|
|
--input-file external.json \
|
|
--output-file normalized.json \
|
|
--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 outputs:
|
|
|
|
- `merge`, `trim`, `normalize`: `--output-file` writes JSON transcript artifact in the selected schema.
|
|
- `render`: `--output-file` writes presentation Markdown.
|
|
|
|
Optional report output:
|
|
|
|
- `--report-file` writes deterministic JSON report events.
|
|
- `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
|
|
|
|
Failure behavior:
|
|
|
|
- Errors are printed once to stderr by the root command and exit status is `1`.
|
|
- There is no partial-state recovery mechanism.
|
|
|
|
Retry guidance:
|
|
|
|
1. Fix the reported input/config/path issue.
|
|
2. Re-run the same command.
|
|
3. If a prior run created a partial or unwanted output/report file, remove it and rerun.
|
|
|
|
Operational notes:
|
|
|
|
- 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
|
|
|
|
seriatim does not manage retention.
|
|
|
|
- Remove unneeded output/report artifacts manually.
|
|
- No cache, state directory, or lock files are maintained by the application.
|
|
|
|
## Privacy considerations
|
|
|
|
Transcript artifacts and reports are local files and may contain sensitive conversational data.
|
|
|
|
- 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
|
|
|
|
- CLI reference: [cli.md](cli.md)
|
|
- Configuration reference: [config.md](config.md)
|
|
- Troubleshooting: [troubleshooting.md](troubleshooting.md)
|
|
- Integration notes:
|
|
- [integrations/whisperx-json.md](integrations/whisperx-json.md)
|
|
- [integrations/output-schemas.md](integrations/output-schemas.md)
|
|
- Synthetic examples: [../examples/README.md](../examples/README.md)
|