eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Add trim configuration contract

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-08 16:54:17 +00:00
parent 38dae8b584
commit ea39594b33
7 changed files with 345 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
README.md
View File

@@ -32,6 +32,40 @@ Narratio expects two YAML files:
YAML decoding is strict (`KnownFields(true)`), so unknown fields fail fast.
## Trim Configuration (Scaffold)
`pipeline.trim` is optional. If omitted, no trim config is loaded. If `trim.enabled` is omitted, it defaults to `false`.
When `trim.enabled: true`:
- `trim.output_path` is required
- `trim.bounds.prompt_id` is required
- `trim.bounds.transcript_input_name` is required
- `trim.bounds.output_path` is required
- `trim.bounds.timeout` must be a valid Go duration when provided
- `trim.bounds.render_debug: true` requires `trim.bounds.render_output_path`
- `trim.bounds.profile_id` may be empty to use the prompt default profile
Trim paths are treated as session-workdir-relative when not absolute.
Example trim scaffold config:
```yaml
trim:
enabled: true
output_path: "transcripts/trimmed.json"
bounds:
prompt_id: "dnd_session.bounds"
profile_id: ""
transcript_input_name: "transcript"
output_path: "artifacts/session_bounds.json"
timeout: "10m"
render_debug: false
render_output_path: "artifacts/session_bounds.render.json"
seriatim:
report: false
```
## Scriptorium Configuration
`pipeline.scriptorium` is optional. When present, Narratio validates and uses it for analyze-stage artifact generation.

37
architecture.md
View File

@@ -94,6 +94,25 @@ Adapter behavior:
`pipeline.scriptorium` is optional. Existing pipelines without Scriptorium continue to work.
`pipeline.trim` is optional. Existing pipelines without trim config continue to work.
When `pipeline.trim` is present:
- `enabled` is optional and defaults to `false` when omitted
- relative `output_path`, `bounds.output_path`, and `bounds.render_output_path` values are session-workdir-relative paths
- do not store secrets in trim config values
When `pipeline.trim.enabled: true`:
- `output_path` is required and non-empty
- `bounds.prompt_id` is required and non-empty
- `bounds.transcript_input_name` is required and non-empty
- `bounds.output_path` is required and non-empty
- `bounds.timeout` must parse as a Go duration when provided
- `bounds.render_debug: true` requires non-empty `bounds.render_output_path`
- `bounds.profile_id` may be empty to use the prompt default profile
- prompt IDs are config values, not hardcoded stage logic
When `pipeline.scriptorium` is present:
- `binary` is required and non-empty
@@ -116,6 +135,24 @@ For each artifact definition:
Prompt IDs and profile IDs are configuration values, not hardcoded stage logic.
Trim scaffold config shape:
```yaml
trim:
enabled: true
output_path: "transcripts/trimmed.json"
bounds:
prompt_id: "dnd_session.bounds"
profile_id: ""
transcript_input_name: "transcript"
output_path: "artifacts/session_bounds.json"
timeout: "10m"
render_debug: false
render_output_path: "artifacts/session_bounds.render.json"
seriatim:
report: false
```
## 6. Analyze Stage (Current Implementation)
The current real analyze implementation supports only `scriptorium.artifacts.session_recap`.

16
examples/pipeline.minimal.yml
View File

@@ -43,6 +43,22 @@ audita:
validation_llm_concurrency: 1
report: true
trim:
enabled: true
# Session-workdir-relative when not absolute.
output_path: "transcripts/trimmed.json"
bounds:
prompt_id: "dnd_session.bounds"
# Empty means use prompt default profile.
profile_id: ""
transcript_input_name: "transcript"
output_path: "artifacts/session_bounds.json"
timeout: "10m"
render_debug: false
render_output_path: "artifacts/session_bounds.render.json"
seriatim:
report: false
scriptorium:
binary: "scriptorium"
config_path: "/etc/scriptorium/config.yml"

25
internal/config/config.go
View File

@@ -15,6 +15,7 @@ type PipelineConfig struct {
WhisperX WhisperXConfig `yaml:"whisperx"`
Seriatim SeriatimConfig `yaml:"seriatim"`
Audita AuditaConfig `yaml:"audita"`
Trim *TrimConfig `yaml:"trim"`
Scriptorium *ScriptoriumConfig `yaml:"scriptorium"`
Analyzer AnalyzerConfig `yaml:"analyzer"`
Notification NotificationConfig `yaml:"notification"`
@@ -83,6 +84,30 @@ type AuditaConfig struct {
Report *bool `yaml:"report"`
}
// TrimConfig configures the future trim stage boundary.
type TrimConfig struct {
Enabled bool `yaml:"enabled"`
OutputPath string `yaml:"output_path"`
Bounds TrimBoundsConfig `yaml:"bounds"`
Seriatim TrimSeriatimConfig `yaml:"seriatim"`
}
// TrimBoundsConfig configures Scriptorium bounds prompt execution for trim.
type TrimBoundsConfig struct {
PromptID string `yaml:"prompt_id"`
ProfileID string `yaml:"profile_id"`
TranscriptInputName string `yaml:"transcript_input_name"`
OutputPath string `yaml:"output_path"`
Timeout string `yaml:"timeout"`
RenderDebug bool `yaml:"render_debug"`
RenderOutputPath string `yaml:"render_output_path"`
}
// TrimSeriatimConfig configures Seriatim options for trim output construction.
type TrimSeriatimConfig struct {
Report *bool `yaml:"report"`
}
// ScriptoriumConfig configures Scriptorium-backed artifact generation.
type ScriptoriumConfig struct {
Binary string `yaml:"binary"`

13
internal/config/load.go
View File

@@ -84,6 +84,7 @@ func applyPipelineDefaults(cfg *PipelineConfig) {
applyWhisperXDefaults(&cfg.WhisperX)
applySeriatimDefaults(&cfg.Seriatim)
applyAuditaDefaults(&cfg.Audita)
applyTrimDefaults(cfg.Trim)
applyScriptoriumDefaults(cfg.Scriptorium)
}
@@ -175,6 +176,18 @@ func applyScriptoriumDefaults(cfg *ScriptoriumConfig) {
}
}
func applyTrimDefaults(cfg *TrimConfig) {
if cfg == nil {
return
}
if cfg.Bounds.Timeout == "" {
cfg.Bounds.Timeout = "10m"
}
if cfg.Seriatim.Report == nil {
cfg.Seriatim.Report = boolPtr(false)
}
}
func float64Ptr(v float64) *float64 {
p := v
return &p

187
internal/config/trim_test.go Normal file
View File

@@ -0,0 +1,187 @@
package config
import (
"strings"
"testing"
)
func TestTrimLoadAndValidate(t *testing.T) {
tests := []struct {
name string
trimYAML string
wantLoadErr string
wantValidateErr string
assert func(t *testing.T, cfg *Config)
}{
{
name: "valid trim config",
trimYAML: `trim:
enabled: true
output_path: transcripts/trimmed.json
bounds:
prompt_id: dnd_session.bounds
profile_id: ""
transcript_input_name: transcript
output_path: artifacts/session_bounds.json
timeout: 10m
render_debug: false
render_output_path: artifacts/session_bounds.render.json
seriatim:
report: false
`,
assert: func(t *testing.T, cfg *Config) {
t.Helper()
if cfg.Pipeline.Trim == nil {
t.Fatal("trim config should be present")
}
if cfg.Pipeline.Trim.Enabled != true {
t.Fatalf("trim.enabled = %t, want true", cfg.Pipeline.Trim.Enabled)
}
if cfg.Pipeline.Trim.Bounds.ProfileID != "" {
t.Fatalf("trim.bounds.profile_id = %q, want empty", cfg.Pipeline.Trim.Bounds.ProfileID)
}
},
},
{
name: "enabled omitted defaults disabled",
trimYAML: `trim:
output_path: transcripts/trimmed.json
bounds:
prompt_id: dnd_session.bounds
transcript_input_name: transcript
output_path: artifacts/session_bounds.json
`,
assert: func(t *testing.T, cfg *Config) {
t.Helper()
if cfg.Pipeline.Trim == nil {
t.Fatal("trim config should be present")
}
if cfg.Pipeline.Trim.Enabled {
t.Fatal("trim.enabled should default to false when omitted")
}
},
},
{
name: "missing prompt id fails when enabled",
trimYAML: `trim:
enabled: true
output_path: transcripts/trimmed.json
bounds:
transcript_input_name: transcript
output_path: artifacts/session_bounds.json
`,
wantValidateErr: "pipeline.trim.bounds.prompt_id is required when pipeline.trim.enabled is true",
},
{
name: "missing transcript input name fails when enabled",
trimYAML: `trim:
enabled: true
output_path: transcripts/trimmed.json
bounds:
prompt_id: dnd_session.bounds
output_path: artifacts/session_bounds.json
`,
wantValidateErr: "pipeline.trim.bounds.transcript_input_name is required when pipeline.trim.enabled is true",
},
{
name: "missing bounds output path fails when enabled",
trimYAML: `trim:
enabled: true
output_path: transcripts/trimmed.json
bounds:
prompt_id: dnd_session.bounds
transcript_input_name: transcript
`,
wantValidateErr: "pipeline.trim.bounds.output_path is required when pipeline.trim.enabled is true",
},
{
name: "missing trimmed output path fails when enabled",
trimYAML: `trim:
enabled: true
bounds:
prompt_id: dnd_session.bounds
transcript_input_name: transcript
output_path: artifacts/session_bounds.json
`,
wantValidateErr: "pipeline.trim.output_path is required when pipeline.trim.enabled is true",
},
{
name: "invalid timeout fails",
trimYAML: `trim:
enabled: true
output_path: transcripts/trimmed.json
bounds:
prompt_id: dnd_session.bounds
transcript_input_name: transcript
output_path: artifacts/session_bounds.json
timeout: definitely-not-a-duration
`,
wantValidateErr: "pipeline.trim.bounds.timeout must be a valid duration",
},
{
name: "render debug true requires render output path",
trimYAML: `trim:
enabled: true
output_path: transcripts/trimmed.json
bounds:
prompt_id: dnd_session.bounds
transcript_input_name: transcript
output_path: artifacts/session_bounds.json
render_debug: true
`,
wantValidateErr: "pipeline.trim.bounds.render_output_path is required when pipeline.trim.bounds.render_debug is true",
},
{
name: "unknown trim field fails strict decoding",
trimYAML: `trim:
enabled: true
output_path: transcripts/trimmed.json
bounds:
prompt_id: dnd_session.bounds
transcript_input_name: transcript
output_path: artifacts/session_bounds.json
bogus: true
`,
wantLoadErr: "strict decode failed",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
pipelineYAML := testPipelineBaseYAML + "\n" + tt.trimYAML
pipelinePath, sessionPath := writeConfigFiles(t, pipelineYAML, testSessionBaseYAML)
cfg, err := Load(pipelinePath, sessionPath)
if tt.wantLoadErr != "" {
if err == nil {
t.Fatalf("expected load error containing %q, got nil", tt.wantLoadErr)
}
if !strings.Contains(err.Error(), tt.wantLoadErr) {
t.Fatalf("load error = %q, want to contain %q", err.Error(), tt.wantLoadErr)
}
return
}
if err != nil {
t.Fatalf("Load() error = %v", err)
}
if tt.assert != nil {
tt.assert(t, cfg)
}
err = Validate(cfg)
if tt.wantValidateErr != "" {
if err == nil {
t.Fatalf("expected validation error containing %q, got nil", tt.wantValidateErr)
}
if !strings.Contains(err.Error(), tt.wantValidateErr) {
t.Fatalf("validation error = %q, want to contain %q", err.Error(), tt.wantValidateErr)
}
return
}
if err != nil {
t.Fatalf("Validate() error = %v", err)
}
})
}
}

33
internal/config/validate.go
View File

@@ -42,6 +42,9 @@ func validatePipeline(cfg *PipelineConfig) error {
if err := validateAudita(cfg.Audita); err != nil {
return err
}
if err := validateTrim(cfg.Trim); err != nil {
return err
}
if err := validateScriptorium(cfg.Scriptorium); err != nil {
return err
}
@@ -55,6 +58,36 @@ func validatePipeline(cfg *PipelineConfig) error {
return nil
}
func validateTrim(cfg *TrimConfig) error {
if cfg == nil {
return nil
}
if !cfg.Enabled {
return nil
}
if strings.TrimSpace(cfg.OutputPath) == "" {
return fmt.Errorf("pipeline.trim.output_path is required when pipeline.trim.enabled is true")
}
if strings.TrimSpace(cfg.Bounds.PromptID) == "" {
return fmt.Errorf("pipeline.trim.bounds.prompt_id is required when pipeline.trim.enabled is true")
}
if strings.TrimSpace(cfg.Bounds.TranscriptInputName) == "" {
return fmt.Errorf("pipeline.trim.bounds.transcript_input_name is required when pipeline.trim.enabled is true")
}
if strings.TrimSpace(cfg.Bounds.OutputPath) == "" {
return fmt.Errorf("pipeline.trim.bounds.output_path is required when pipeline.trim.enabled is true")
}
if err := validateDuration("pipeline.trim.bounds.timeout", cfg.Bounds.Timeout); err != nil {
return err
}
if cfg.Bounds.RenderDebug && strings.TrimSpace(cfg.Bounds.RenderOutputPath) == "" {
return fmt.Errorf("pipeline.trim.bounds.render_output_path is required when pipeline.trim.bounds.render_debug is true")
}
return nil
}
func validateWhisperX(cfg WhisperXConfig) error {
if strings.TrimSpace(cfg.TranscribeURL) == "" {
return fmt.Errorf("pipeline.whisperx.transcribe_url is required")