# Purpose
Constructs and decodes the provider-independent Speaker V3 LLM protocol. It owns frozen prompt bytes, Gemini request ordering and text extraction, Terra tool contracts, ordered feature evidence, and strict conversion into the structured-analysis schema. It performs no provider calls, identity work, persistence, retries, or result limiting.
# Public API
```rust
pub use kcode_speaker_v3_schema::{
FEATURE_NAMES,
FeatureVector24,
LocalSpeakerLabel,
StructuredAnalysis,
StructuredSpeaker,
ValidationError as AnalysisValidationError,
VocalGenderPresentation,
};
pub const GEMINI_TRANSCRIPT_PROMPT_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_ONE_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_TWO_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_THREE_REVISION: &str;
pub const GPT_STRUCTURING_PROMPT_REVISION: &str;
pub const TERRA_SPEAKER_LABELS_PROMPT_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_REVISIONS: [&str; 3];
pub const GEMINI_TRANSCRIPT_PROMPT: &str;
pub const GEMINI_FEATURE_PROMPT_ONE: &str;
pub const GEMINI_FEATURE_PROMPT_TWO: &str;
pub const GEMINI_FEATURE_PROMPT_THREE: &str;
pub const GPT_STRUCTURING_PROMPT: &str;
pub const TERRA_SPEAKER_LABELS_PROMPT: &str;
pub const RECORD_SPEAKER_LABELS_TOOL_NAME: &str;
pub const RECORD_SPEAKER_LABELS_TOOL_DESCRIPTION: &str;
pub const RECORD_SPEAKER_ANALYSIS_TOOL_NAME: &str;
pub const RECORD_SPEAKER_ANALYSIS_TOOL_DESCRIPTION: &str;
pub const FEATURE_PACKETS: [FeaturePacket; 3];
pub enum GeminiRequestPart<'a> {
Audio {
media_type: &'static str,
bytes: &'a [u8],
},
Text(String),
}
pub enum FeaturePacket {
One,
Two,
Three,
}
impl FeaturePacket {
pub fn index(self) -> usize;
pub fn prompt(self) -> &'static str;
pub fn revision(self) -> &'static str;
}
pub enum ProtocolError {
Blank(&'static str),
InvalidGeminiResponse(String),
GeminiTextCandidateCount(usize),
InvalidSpeakerLabelsArguments(String),
DuplicateSpeakerLabel(LocalSpeakerLabel),
InvalidFinalArguments(String),
InvalidStructuredAnalysis(AnalysisValidationError),
}
impl Display for ProtocolError;
impl Error for ProtocolError;
pub struct ToolDefinition {
pub name: &'static str,
pub description: &'static str,
pub input_schema: serde_json::Value,
}
pub struct TerraSpeakerLabelsInput { /* private fields */ }
impl TerraSpeakerLabelsInput {
pub fn new(transcript: String) -> Result<Self, ProtocolError>;
pub fn instruction(&self) -> &'static str;
pub fn transcript(&self) -> &str;
pub fn render(&self) -> String;
}
pub struct SpeakerFeatureEvidence { /* private fields */ }
impl SpeakerFeatureEvidence {
pub fn new(
speaker: LocalSpeakerLabel,
packet_one: String,
packet_two: String,
packet_three: String,
) -> Result<Self, ProtocolError>;
pub fn speaker(&self) -> LocalSpeakerLabel;
pub fn packet(&self, packet: FeaturePacket) -> &str;
pub fn packets(&self) -> [&str; 3];
}
pub struct TerraFinalInput { /* private fields */ }
impl TerraFinalInput {
pub fn new(
transcript: String,
speakers: Vec<SpeakerFeatureEvidence>,
) -> Result<Self, ProtocolError>;
pub fn instruction(&self) -> &'static str;
pub fn transcript(&self) -> &str;
pub fn speakers(&self) -> &[SpeakerFeatureEvidence];
pub fn render(&self) -> String;
}
pub fn gemini_transcript_request(audio: &[u8]) -> [GeminiRequestPart<'_>; 2];
pub fn gemini_feature_cached_prefix<'a>(
audio: &'a [u8],
transcript: &str,
) -> [GeminiRequestPart<'a>; 2];
pub fn gemini_feature_suffix(
packet: FeaturePacket,
target: LocalSpeakerLabel,
) -> String;
pub fn extract_gemini_text(
response: &serde_json::Value,
) -> Result<String, ProtocolError>;
pub fn record_speaker_labels_tool() -> ToolDefinition;
pub fn decode_record_speaker_labels_arguments(
arguments: &serde_json::Value,
) -> Result<Vec<LocalSpeakerLabel>, ProtocolError>;
pub fn record_speaker_analysis_tool() -> ToolDefinition;
pub fn decode_record_speaker_analysis_arguments(
arguments: &serde_json::Value,
) -> Result<StructuredAnalysis, ProtocolError>;
```
All declared enums and structs implement `Debug`, `Clone`, and `PartialEq`, and implement `Eq` where their fields permit it. `FeaturePacket` is also `Copy`, `PartialOrd`, `Ord`, and `Hash`. `TerraSpeakerLabelsInput`, `SpeakerFeatureEvidence`, and `TerraFinalInput` implement Serde serialization. The re-exported analysis values retain the traits and semantics documented by the schema package.
# Requests and extraction
`gemini_transcript_request` returns borrowed Ogg audio with media type `audio/ogg` followed by the frozen transcript prompt. It accepts any byte slice and does not validate or copy the audio.
`gemini_feature_cached_prefix` returns the same borrowed Ogg audio followed by the shared feature instruction through the supplied transcript. Transcript bytes are copied exactly without trimming or placeholder substitution. `gemini_feature_suffix` returns the selected packet text after the transcript placeholder, substitutes only the exact target-speaker placeholder, and leaves the target label last. `FEATURE_PACKETS` and packet indices define order one, two, three.
`extract_gemini_text` reads a Gemini response value, concatenates each candidate's textual parts in part order without separators or trimming, ignores candidates whose concatenated text is blank, and succeeds only when exactly one nonblank textual candidate remains. It does not scan other response fields or impose candidate, part, or byte limits.
# Terra tools and inputs
`record_speaker_labels_tool` returns the exact `record_speaker_labels` name, frozen description, and an object schema containing only the required `speakers` array. Its items use exact `Speaker N` syntax and the schema has no item cap. `decode_record_speaker_labels_arguments` accepts only the returned argument value. It rejects extra fields, `Unknown`, malformed or noncanonical labels, and duplicates while preserving returned order. It does not scan transcript text.
`TerraSpeakerLabelsInput` owns the exact nonblank transcript. `render` returns the frozen label instruction immediately followed by `Input:\n` and the JSON serialization of that transcript object, preserving untrusted text as JSON data.
`SpeakerFeatureEvidence` owns exactly three nonblank Gemini outputs in packet-one, packet-two, packet-three order. `TerraFinalInput` owns the exact nonblank transcript and unique per-speaker evidence in caller-supplied order. Its serialized data is `{ "transcript": string, "speakers": [{ "speaker": "Speaker N", "feature_packets": [string, string, string] }] }`. `render` returns the frozen structuring instruction immediately followed by `Input:\n` and that JSON serialization.
`record_speaker_analysis_tool` requires `transcript` and `speakers`; each speaker requires `speaker`, `language`, `features`, and `features_usable_for_training`; and `features` requires all 24 frozen fields. Every feature is nullable, vocal-gender presentation uses the schema package's snake-case values, and every object schema sets `additionalProperties` to false.
`decode_record_speaker_analysis_arguments` requires that complete closed shape, constructs `StructuredAnalysis`, and calls `StructuredAnalysis::validate`. It preserves transcript, language, and nominal-feature text exactly.
# Performance and concurrency
All operations are deterministic and stateless. Independent calls share no state, locks, queue, wait, or serialization and can proceed concurrently. There is no filesystem, network, provider, clock, retry, timeout, callback, or persistence behavior.
Request construction is O(transcript bytes) time and memory while borrowing audio. Suffix construction is O(packet bytes). Gemini extraction is O(response bytes) time with peak memory O(response plus concatenated text). Label decoding is O(labels log labels) with O(labels) temporary memory. Final decoding is O(argument bytes + speakers log speakers) with O(argument bytes + speakers) memory. Tool-schema construction has fixed 24-field work. Rendering is O(transcript plus evidence bytes) time and output memory.
The reference canary is `cargo test` in the Kennedy hardened rootless Podman validation image on one x86-64 vCPU: the tested operations complete within 10 seconds for a 1 MiB response or transcript and 1,000 speakers with three 1 KiB packet outputs each. These fixture sizes are measurements, not accepted-input limits; the implementation imposes no byte, item, speaker, or packet count cap and performs no hidden retries or I/O.