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

Added a new JSON public schema as the default output artifact

Browse Source
This commit is contained in:
Eric Rakestraw
2026-04-28 21:32:43 -05:00
parent 80ac7e97dd
commit cc80a123ef
14 changed files with 533 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
internal/artifact/transcript.go
View File

@@ -57,6 +57,31 @@ func FromMerged(cfg config.Config, merged model.MergedTranscript) schema.Transcr
}
}
// DefaultFromMerged converts the internal merged transcript model into the
// compact default public serialized output contract.
func DefaultFromMerged(cfg config.Config, merged model.MergedTranscript) schema.DefaultTranscript {
segments := make([]schema.DefaultSegment, len(merged.Segments))
for index, segment := range merged.Segments {
segments[index] = schema.DefaultSegment{
ID: segment.ID,
Start: segment.Start,
End: segment.End,
Speaker: segment.Speaker,
Text: segment.Text,
Categories: append([]string(nil), segment.Categories...),
}
}
return schema.DefaultTranscript{
Metadata: schema.DefaultMetadata{
Application: ApplicationName,
Version: buildinfo.Version,
OutputSchema: config.OutputSchemaDefault,
},
Segments: segments,
}
}
// MinimalFromMerged converts the internal merged transcript model into the
// compact public serialized output contract.
func MinimalFromMerged(cfg config.Config, merged model.MergedTranscript) schema.MinimalTranscript {
@@ -85,8 +110,12 @@ func MinimalFromMerged(cfg config.Config, merged model.MergedTranscript) schema.
// runtime-selected public output contract.
func SelectedFromMerged(cfg config.Config, merged model.MergedTranscript) any {
switch cfg.OutputSchema {
case config.OutputSchemaDefault:
return DefaultFromMerged(cfg, merged)
case config.OutputSchemaMinimal:
return MinimalFromMerged(cfg, merged)
case config.OutputSchemaSeriatim:
return FromMerged(cfg, merged)
default:
return FromMerged(cfg, merged)
}

51
internal/artifact/transcript_test.go
View File

@@ -30,6 +30,57 @@ func TestSelectedFromMergedDefaultsToSeriatimTranscript(t *testing.T) {
}
}
func TestSelectedFromMergedUsesDefaultWhenConfigured(t *testing.T) {
got := SelectedFromMerged(config.Config{OutputSchema: config.OutputSchemaDefault}, model.MergedTranscript{})
if _, ok := got.(schema.DefaultTranscript); !ok {
t.Fatalf("selected artifact type = %T, want schema.DefaultTranscript", got)
}
}
func TestSelectedFromMergedUsesSeriatimWhenConfigured(t *testing.T) {
got := SelectedFromMerged(config.Config{OutputSchema: config.OutputSchemaSeriatim}, model.MergedTranscript{})
if _, ok := got.(schema.Transcript); !ok {
t.Fatalf("selected artifact type = %T, want schema.Transcript", got)
}
}
func TestDefaultFromMergedEmitsOnlyDefaultShape(t *testing.T) {
merged := model.MergedTranscript{
Segments: []model.Segment{
{
ID: 1,
Source: "input.json",
SourceRef: "word-run:1:1:1",
DerivedFrom: []string{"input.json#0"},
Speaker: "Alice",
Start: 1,
End: 2,
Text: "hello",
Categories: []string{"backchannel"},
OverlapGroupID: 1,
},
},
OverlapGroups: []model.OverlapGroup{
{ID: 1, Start: 1, End: 2, Segments: []string{"input.json#0"}, Speakers: []string{"Alice"}, Class: "unknown", Resolution: "unresolved"},
},
}
got := DefaultFromMerged(config.Config{OutputSchema: config.OutputSchemaDefault}, merged)
want := schema.DefaultTranscript{
Metadata: schema.DefaultMetadata{
Application: ApplicationName,
Version: buildinfo.Version,
OutputSchema: config.OutputSchemaDefault,
},
Segments: []schema.DefaultSegment{
{ID: 1, Start: 1, End: 2, Speaker: "Alice", Text: "hello", Categories: []string{"backchannel"}},
},
}
if !reflect.DeepEqual(got, want) {
t.Fatalf("default transcript = %#v, want %#v", got, want)
}
}
func TestMinimalFromMergedEmitsOnlyMinimalShape(t *testing.T) {
merged := model.MergedTranscript{
Segments: []model.Segment{

2
internal/builtin/postprocess.go
View File

@@ -51,6 +51,8 @@ func (validateOutput) Process(ctx context.Context, in model.MergedTranscript, cf
selected := artifact.SelectedFromMerged(cfg, in)
var err error
switch transcript := selected.(type) {
case schema.DefaultTranscript:
err = schema.ValidateDefaultTranscript(transcript)
case schema.MinimalTranscript:
err = schema.ValidateMinimalTranscript(transcript)
case schema.Transcript:

33
internal/builtin/postprocess_test.go
View File

@@ -81,6 +81,38 @@ func TestValidateOutputUsesMinimalSchemaWhenConfigured(t *testing.T) {
}
}
func TestValidateOutputUsesSeriatimSchemaWhenConfigured(t *testing.T) {
merged := model.MergedTranscript{
Segments: []model.Segment{
{
ID: 1,
Source: "input.json",
SourceRef: "word-run:1:1:1",
DerivedFrom: []string{"input.json#0"},
Speaker: "Alice",
Start: 1,
End: 2,
Text: "hello",
Categories: []string{"backchannel"},
OverlapGroupID: 1,
},
},
}
cfg := testConfig()
cfg.OutputSchema = config.OutputSchemaSeriatim
got, events, err := validateOutput{}.Process(context.Background(), merged, cfg)
if err != nil {
t.Fatalf("validate output: %v", err)
}
if len(got.Segments) != 1 {
t.Fatalf("segment count = %d, want 1", len(got.Segments))
}
if len(events) != 1 || !strings.Contains(events[0].Message, "validated 1 output segment(s)") {
t.Fatalf("events = %#v", events)
}
}
func TestValidateOutputMinimalFailsBeforeAssignIDs(t *testing.T) {
merged := model.MergedTranscript{
Segments: []model.Segment{
@@ -103,6 +135,7 @@ func testConfig() config.Config {
return config.Config{
InputReader: config.DefaultInputReader,
InputFiles: []string{"input.json"},
OutputSchema: config.DefaultOutputSchema,
PreprocessingModules: []string{"validate-raw", "normalize-speakers", "trim-text"},
PostprocessingModules: []string{"assign-ids", "validate-output"},
OutputModules: []string{"json"},

2
internal/cli/merge.go
View File

@@ -32,7 +32,7 @@ func newMergeCommand() *cobra.Command {
flags.StringVar(&opts.AutocorrectFile, "autocorrect", "", "autocorrect rules file")
flags.StringVar(&opts.InputReader, "input-reader", config.DefaultInputReader, "input reader module")
flags.StringVar(&opts.OutputModules, "output-modules", config.DefaultOutputModules, "comma-separated output modules")
flags.StringVar(&opts.OutputSchema, "output-schema", config.DefaultOutputSchema, "output JSON schema: seriatim or minimal")
flags.StringVar(&opts.OutputSchema, "output-schema", config.DefaultOutputSchema, "output JSON schema: default, minimal, or seriatim")
flags.StringVar(&opts.PreprocessingModules, "preprocessing-modules", config.DefaultPreprocessingModules, "comma-separated preprocessing modules")
flags.StringVar(&opts.PostprocessingModules, "postprocessing-modules", config.DefaultPostprocessingModules, "comma-separated postprocessing modules")
flags.StringVar(&opts.CoalesceGap, "coalesce-gap", config.DefaultCoalesceGapValue, "maximum same-speaker gap in seconds for coalesce")

93
internal/cli/merge_test.go
View File

@@ -114,6 +114,81 @@ func TestMergeWritesMergedOutputAndReport(t *testing.T) {
}
}
func TestMergeWritesDefaultOutputSchema(t *testing.T) {
dir := t.TempDir()
input := writeJSONFile(t, dir, "input.json", `{
"segments": [
{"start": 1, "end": 1.6, "text": "yeah"}
]
}`)
output := filepath.Join(dir, "merged.json")
err := executeMergeRaw(
"--input-file", input,
"--output-file", output,
)
if err != nil {
t.Fatalf("merge failed: %v", err)
}
var transcript schema.DefaultTranscript
readJSON(t, output, &transcript)
if transcript.Metadata.OutputSchema != config.OutputSchemaDefault {
t.Fatalf("output_schema = %q, want default", transcript.Metadata.OutputSchema)
}
if len(transcript.Segments) != 1 {
t.Fatalf("segment count = %d, want 1", len(transcript.Segments))
}
segment := transcript.Segments[0]
if len(segment.Categories) != 1 || segment.Categories[0] != "backchannel" {
t.Fatalf("categories = %#v, want [backchannel]", segment.Categories)
}
outputBytes, err := os.ReadFile(output)
if err != nil {
t.Fatalf("read output: %v", err)
}
for _, forbidden := range []string{"overlap_groups", "source", "derived_from", "words"} {
if strings.Contains(string(outputBytes), forbidden) {
t.Fatalf("default output contains %q:\n%s", forbidden, outputBytes)
}
}
}
func TestMergeWritesSeriatimOutputSchema(t *testing.T) {
dir := t.TempDir()
input := writeJSONFile(t, dir, "input.json", `{
"segments": [
{"start": 1, "end": 1.6, "text": "yeah"}
]
}`)
output := filepath.Join(dir, "merged.json")
err := executeMergeRaw(
"--input-file", input,
"--output-file", output,
"--output-schema", "seriatim",
)
if err != nil {
t.Fatalf("merge failed: %v", err)
}
var transcript model.FinalTranscript
readJSON(t, output, &transcript)
if len(transcript.Segments) != 1 {
t.Fatalf("segment count = %d, want 1", len(transcript.Segments))
}
segment := transcript.Segments[0]
if len(segment.Categories) != 1 || segment.Categories[0] != "backchannel" {
t.Fatalf("categories = %#v, want [backchannel]", segment.Categories)
}
if segment.Source == "" {
t.Fatal("expected full output to include source")
}
if len(transcript.OverlapGroups) != 0 {
t.Fatalf("expected no overlap groups, got %d", len(transcript.OverlapGroups))
}
}
func TestMergeWritesMinimalOutputSchema(t *testing.T) {
dir := t.TempDir()
input := writeJSONFile(t, dir, "input.json", `{
@@ -1916,11 +1991,29 @@ func TestInvalidTimingFails(t *testing.T) {
}
func executeMerge(args ...string) error {
if !hasOutputSchemaFlag(args) {
// Most integration tests were written against the full envelope; keep
// that behavior unless the caller explicitly asks for another schema.
args = append(args, "--output-schema", config.OutputSchemaSeriatim)
}
return executeMergeRaw(args...)
}
func executeMergeRaw(args ...string) error {
cmd := NewRootCommand()
cmd.SetArgs(append([]string{"merge"}, args...))
return cmd.Execute()
}
func hasOutputSchemaFlag(args []string) bool {
for _, arg := range args {
if arg == "--output-schema" {
return true
}
}
return false
}
func writeJSONFile(t *testing.T, dir string, name string, content string) string {
t.Helper()

7
internal/config/config.go
View File

@@ -13,7 +13,7 @@ import (
const (
DefaultInputReader = "json-files"
DefaultOutputModules = "json"
DefaultOutputSchema = OutputSchemaSeriatim
DefaultOutputSchema = OutputSchemaDefault
DefaultPreprocessingModules = "validate-raw,normalize-speakers,trim-text"
DefaultPostprocessingModules = "detect-overlaps,resolve-overlaps,backchannel,filler,resolve-danglers,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output"
DefaultOverlapWordRunGap = 0.75
@@ -26,6 +26,7 @@ const (
WordRunReorderWindowEnv = "SERIATIM_OVERLAP_WORD_RUN_REORDER_WINDOW"
BackchannelMaxDurationEnv = "SERIATIM_BACKCHANNEL_MAX_DURATION"
FillerMaxDurationEnv = "SERIATIM_FILLER_MAX_DURATION"
OutputSchemaDefault = "default"
OutputSchemaSeriatim = "seriatim"
OutputSchemaMinimal = "minimal"
)
@@ -188,10 +189,10 @@ func parseModuleList(value string) ([]string, error) {
func validateOutputSchema(value string) error {
switch value {
case OutputSchemaSeriatim, OutputSchemaMinimal:
case OutputSchemaDefault, OutputSchemaSeriatim, OutputSchemaMinimal:
return nil
default:
return fmt.Errorf("--output-schema must be one of %q or %q", OutputSchemaSeriatim, OutputSchemaMinimal)
return fmt.Errorf("--output-schema must be one of %q, %q, or %q", OutputSchemaDefault, OutputSchemaMinimal, OutputSchemaSeriatim)
}
}

46
internal/config/config_test.go
View File

@@ -46,7 +46,7 @@ func TestDuplicateInputFilesFailValidation(t *testing.T) {
}
}
func TestOutputSchemaDefaultsToSeriatim(t *testing.T) {
func TestOutputSchemaDefaultsToDefault(t *testing.T) {
dir := t.TempDir()
input := writeTempFile(t, dir, "input.json")
output := filepath.Join(dir, "merged.json")
@@ -67,6 +67,28 @@ func TestOutputSchemaDefaultsToSeriatim(t *testing.T) {
}
}
func TestOutputSchemaAcceptsDefault(t *testing.T) {
dir := t.TempDir()
input := writeTempFile(t, dir, "input.json")
output := filepath.Join(dir, "merged.json")
cfg, err := NewMergeConfig(MergeOptions{
InputFiles: []string{input},
OutputFile: output,
InputReader: DefaultInputReader,
OutputModules: DefaultOutputModules,
OutputSchema: OutputSchemaDefault,
PreprocessingModules: DefaultPreprocessingModules,
PostprocessingModules: DefaultPostprocessingModules,
})
if err != nil {
t.Fatalf("config failed: %v", err)
}
if cfg.OutputSchema != OutputSchemaDefault {
t.Fatalf("output schema = %q, want %q", cfg.OutputSchema, OutputSchemaDefault)
}
}
func TestOutputSchemaAcceptsMinimal(t *testing.T) {
dir := t.TempDir()
input := writeTempFile(t, dir, "input.json")
@@ -89,6 +111,28 @@ func TestOutputSchemaAcceptsMinimal(t *testing.T) {
}
}
func TestOutputSchemaAcceptsSeriatim(t *testing.T) {
dir := t.TempDir()
input := writeTempFile(t, dir, "input.json")
output := filepath.Join(dir, "merged.json")
cfg, err := NewMergeConfig(MergeOptions{
InputFiles: []string{input},
OutputFile: output,
InputReader: DefaultInputReader,
OutputModules: DefaultOutputModules,
OutputSchema: OutputSchemaSeriatim,
PreprocessingModules: DefaultPreprocessingModules,
PostprocessingModules: DefaultPostprocessingModules,
})
if err != nil {
t.Fatalf("config failed: %v", err)
}
if cfg.OutputSchema != OutputSchemaSeriatim {
t.Fatalf("output schema = %q, want %q", cfg.OutputSchema, OutputSchemaSeriatim)
}
}
func TestOutputSchemaRejectsUnknownValue(t *testing.T) {
dir := t.TempDir()
input := writeTempFile(t, dir, "input.json")