# Purpose
Executes the fixed Speaker V3 Gemini and Terra analysis protocol while preserving its provider-independent analysis values and provenance. Focused concrete dependencies own Gemini and Terra request adaptation; this package owns input admission, end-to-end stage order, cross-stage agreement, provenance, and the stable caller-facing facade.
# Public API
```rust
pub use kcode_speaker_v3_schema::{
FEATURE_NAMES, FEATURE_SCHEMA_REVISION, FeatureVector24, LocalSpeakerLabel,
MAX_AUDIO_DURATION_MS, OGG_MEDIA_TYPE, OggAudioMetadata, StructuredAnalysis,
StructuredSpeaker, ValidationError, VocalGenderPresentation,
};
pub use kcode_speaker_v3_llm_protocol::{
GEMINI_FEATURE_PROMPT_ONE, GEMINI_FEATURE_PROMPT_ONE_REVISION,
GEMINI_FEATURE_PROMPT_REVISIONS, GEMINI_FEATURE_PROMPT_THREE,
GEMINI_FEATURE_PROMPT_THREE_REVISION, GEMINI_FEATURE_PROMPT_TWO,
GEMINI_FEATURE_PROMPT_TWO_REVISION, GEMINI_TRANSCRIPT_PROMPT,
GEMINI_TRANSCRIPT_PROMPT_REVISION, GPT_STRUCTURING_PROMPT,
GPT_STRUCTURING_PROMPT_REVISION,
};
pub struct GeminiCohort {
pub model_id: String,
pub transcript_prompt_revision: String,
pub feature_prompt_revisions: [String; 3],
pub feature_schema_revision: String,
}
impl GeminiCohort {
pub fn new(model_id: impl Into<String>) -> Self;
pub fn validate(&self) -> Result<(), ValidationError>;
}
pub struct StructurerProvenance {
pub model_id: String,
pub prompt_revision: String,
}
impl StructurerProvenance {
pub fn new(model_id: impl Into<String>) -> Self;
pub fn validate(&self) -> Result<(), ValidationError>;
}
pub struct AnalysisEnvelope {
pub audio: OggAudioMetadata,
pub analysis: StructuredAnalysis,
pub gemini: GeminiCohort,
pub structurer: StructurerProvenance,
}
impl AnalysisEnvelope {
pub fn validate(&self) -> Result<(), ValidationError>;
}
pub enum AnalysisError {
Input(String),
GeminiTranscript(String),
TerraLabels(String),
GeminiCache(String),
GeminiFeature {
speaker: LocalSpeakerLabel,
packet: u8,
message: String,
},
TerraStructuring(String),
TranscriptMismatch,
SpeakerSetMismatch,
}
impl Display for AnalysisError;
impl Error for AnalysisError;
pub struct ExecutedAnalysis {
pub envelope: AnalysisEnvelope,
pub label_extractor: StructurerProvenance,
}
#[cfg(feature = "providers")]
pub struct Analyzer { /* private fields */ }
#[cfg(feature = "providers")]
impl Analyzer {
pub fn new(
gemini: kcode_gemini_3_1_pro::Gemini31Pro,
terra: kcode_codex_terra::CodexTerra,
) -> Self;
pub async fn analyze_ogg(
&self,
bytes: &[u8],
duration_ms: u64,
filename: Option<String>,
) -> Result<ExecutedAnalysis, AnalysisError>;
}
```
`GeminiCohort`, `StructurerProvenance`, and `AnalysisError` implement `Debug`, `Clone`, `PartialEq`, and `Eq`; the two provenance values also implement Serde serialization and deserialization. `AnalysisEnvelope` and `ExecutedAnalysis` implement `Debug`, `Clone`, `PartialEq`, and Serde serialization and deserialization. Re-exported declarations retain the exact traits and semantics documented by their defining packages.
# Values and validation
`GeminiCohort::new` records the supplied model identifier with the frozen transcript, three feature-prompt, and 24-feature schema revisions. `StructurerProvenance::new` records the supplied model identifier with the frozen final-structuring revision. Their validators reject blank identifiers or revisions.
`AnalysisEnvelope::validate` validates retained Ogg metadata, the complete structured analysis, Gemini provenance, and final structurer provenance. `ExecutedAnalysis::label_extractor` separately records the fixed Terra model and speaker-label prompt revision used before feature collection.
# Provider execution
`Analyzer` is available only with the default-disabled `providers` feature. `analyze_ogg` performs these stages in order:
1. Validate Ogg bytes, trusted duration, and optional filename before provider effects.
2. Make one Gemini transcript generation and decode exactly one nonblank textual candidate.
3. Make one Terra speaker-label run and decode ordered unique canonical `Speaker N` labels.
4. With nonempty labels, create one one-hour Gemini cached prefix and await three concurrent feature generations per label in label-major, packet-major order. Empty labels skip cache and feature calls.
5. Make one Terra final-structuring run, including when labels are empty.
6. Require the final transcript to byte-equal Gemini's transcript and the final speaker-label set to equal the extracted set.
7. Construct and validate fixed Gemini, label-extractor, and final-structurer provenance.
Gemini receives the Ogg audio. Terra receives only rendered text and tool metadata. There is no analysis-layer retry, timeout, cache deletion, speaker cap, configurable cache lifetime, persistence, identity operation, or training operation. Feature calls all finish before ordered results are inspected, so multiple failures resolve to the earliest failed label/packet in deterministic input order.
Each provider or deterministic protocol failure maps to the corresponding `AnalysisError` stage without rewriting its diagnostic. `GeminiFeature::packet` is one-based. `TranscriptMismatch` and `SpeakerSetMismatch` report cross-stage disagreement after final decoding. Cancellation after provider submission and provider-side accounting can be ambiguous; this package performs no retry to conceal that boundary.
# Performance and concurrency
Ogg admission is linear in the retained first-page bytes and precedes remote work. Local orchestration outside focused dependencies is O(labels plus returned speakers) time and O(labels plus returned speakers) temporary memory for the final set comparison and result values. Audio, transcript, provider request, response, cache, and feature-fanout work follows the focused dependency contracts. Remote completion latency is provider-owned and is not bounded here.
Independent analyses share no package-owned lock, queue, mutable state, or serialization and may proceed concurrently. The concrete provider clients retain their own concurrency and accounting contracts. The reproducible local canary is `cargo test` in the Kennedy hardened rootless Podman validation image on one x86-64 vCPU. Synthetic zero-, one-, forty-, and one-thousand-speaker orchestration, cross-stage checks, stage failures, and an unrelated-analysis concurrency case complete within 10 seconds without credentials or provider calls. The fixtures are measurements, not accepted-input limits.