kcode-speaker-v3-analysis 0.2.0

Speaker V3 analysis execution and provenance
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# kcode-speaker-v3-analysis 0.2.0

Executes the fixed Speaker V3 Gemini and Terra analysis flow while preserving provider-independent results and provenance. The active operation accepts only complete in-memory Ogg Opus bytes and reports every LLM job; the compatibility operation retains its former caller-supplied metadata API.

## Public analysis values

The crate re-exports the frozen prompt constants and the public schema values `FeatureVector24`, `LocalSpeakerLabel`, `OggAudioMetadata`, `StructuredAnalysis`, `StructuredSpeaker`, `ValidationError`, and related constants and enums.

```rust
pub struct GeminiCohort {
    pub model_id: String,
    pub transcript_prompt_revision: String,
    pub feature_prompt_revisions: [String; 3],
    pub feature_schema_revision: String,
}

pub struct StructurerProvenance {
    pub model_id: String,
    pub prompt_revision: String,
}

pub struct AnalysisEnvelope {
    pub audio: OggAudioMetadata,
    pub analysis: StructuredAnalysis,
    pub gemini: GeminiCohort,
    pub structurer: StructurerProvenance,
}

pub struct ExecutedAnalysis {
    pub envelope: AnalysisEnvelope,
    pub label_extractor: StructurerProvenance,
}
```

The provenance constructors and validators reject blank identifiers or revisions. `AnalysisEnvelope::validate` validates all retained metadata, structured analysis, and provenance. Public retained values implement the applicable `Debug`, `Clone`, `PartialEq`, and Serde traits documented by their defining packages.

## Progress

```rust
pub enum AnalysisStage {
    Transcript,
    SpeakerLabels,
    SpeakerFeatures,
    Structuring,
}

pub enum AnalysisJob {
    Transcript,
    SpeakerLabels,
    SpeakerFeature {
        speaker: LocalSpeakerLabel,
        packet: u8,
    },
    Structuring,
}

pub enum AnalysisProgress {
    JobStarted { sequence: u64, job: AnalysisJob },
    JobSucceeded { sequence: u64 },
    JobFailed { sequence: u64, error: String },
    StageCompleted { stage: AnalysisStage },
}
```

These progress values implement `Debug`, `Clone`, `PartialEq`, and `Eq`. Sequences are deterministic within one analysis: transcript is 1, speaker labels is 2, feature jobs begin at 3 in label-major and packet-1-through-3 order, and structuring follows the final possible feature sequence. Feature terminal events are reported in actual completion order while their sequence identifies deterministic input order. A stage completes only after its required jobs and local validation succeed.

## Errors

```rust
pub enum AnalysisError {
    Input(String),
    Progress(String),
    GeminiTranscript(String),
    TerraLabels(String),
    GeminiCache(String),
    GeminiFeature {
        speaker: LocalSpeakerLabel,
        packet: u8,
        message: String,
    },
    TerraStructuring(String),
    TranscriptMismatch,
    SpeakerSetMismatch,
}
```

Errors implement `Debug`, `Clone`, `PartialEq`, `Eq`, `Display`, and `Error`. Provider and deterministic protocol diagnostics are preserved inside their stage-specific variants. A reporter error becomes `Progress` and immediately drops outstanding local futures; already-submitted provider work may have an ambiguous remote cancellation outcome.

## Provider API

`Analyzer` is available only with the default-disabled `providers` feature.

```rust
pub struct Analyzer { /* private fields */ }

impl Analyzer {
    pub fn new(
        gemini: kcode_gemini_3_1_pro::Gemini31Pro,
        terra: kcode_codex_terra::CodexTerra,
    ) -> Self;

    pub async fn analyze_ogg_with_progress<F>(
        &self,
        bytes: &[u8],
        report: F,
    ) -> Result<ExecutedAnalysis, AnalysisError>
    where
        F: FnMut(AnalysisProgress) -> Result<(), String>;

    pub async fn analyze_ogg(
        &self,
        bytes: &[u8],
        duration_ms: u64,
        filename: Option<String>,
    ) -> Result<ExecutedAnalysis, AnalysisError>;
}
```

`analyze_ogg_with_progress` is the active API. Before progress or provider effects, it strictly verifies one complete mapping-family-zero mono/stereo Ogg Opus stream, derives duration, rejects zero duration and clips over 150 seconds, and retains no filename. `analyze_ogg` is the compatibility API: it retains the former shallow Ogg check and trusted caller-supplied duration and filename, and runs the same orchestration with a no-op reporter.

## Execution

Both operations execute one fixed flow without retry:

1. Gemini produces one readable diarized transcript.
2. Terra extracts ordered unique `Speaker N` labels.
3. For each label, three Gemini feature jobs run concurrently through one cached prefix. All job starts and completion-order terminal outcomes are reported. Empty labels skip cache and feature calls but still complete the feature stage.
4. Terra structures the transcript and feature evidence into the frozen 24-feature schema.
5. The facade requires byte-identical transcript output and an identical speaker-label set, validates all retained values, and attaches fixed Gemini, label-extractor, and structurer provenance.

A cache-creation failure has no fabricated LLM job. When several feature jobs fail, every failure is reported and the returned `GeminiFeature` remains the deterministic earliest label/packet failure. No terminal feature failure is reported twice.

Gemini receives the Ogg bytes. Terra receives only rendered text and tool metadata. The package performs no retry, timeout, cache deletion, persistence, K1 transaction, identity decision, training, status projection, queue watching, or worker management.

## Performance and concurrency

Strict admission is linear in audio bytes. Local orchestration is linear in returned speakers and evidence apart from set validation. Feature execution makes one cache call and three concurrent generations per speaker with no analysis-layer cap. Independent analyses share no package-owned lock, queue, mutable state, or serialization. Remote latency and provider-side cancellation are not bounded by this package. Provider-free tests cover admission, sequence mapping, completion-order reporting, failures, reporter cancellation, cross-stage validation, compatibility behavior, and unrelated-analysis concurrency.