gemini_genai_rs/
primitives.rs

1//! # The L0 contract — frames on a wire
2//!
3//! This module is the *engineered surface* of the wire layer: the closed set
4//! of primitives L0 exposes upward, curated and named. Everything a higher
5//! layer may rely on is here; everything absent is an implementation detail
6//! that can change without notice. (`prelude` remains the convenience glob;
7//! this module is the contract.)
8//!
9//! **L0 promises:** a duplex, authenticated, resumable frame stream to the
10//! Live API — connect, write frames (audio/text/video/tool responses), read
11//! events — plus the audio machinery a realtime client needs at the edge
12//! (lock-free buffers, jitter absorption, VAD, barge-in detection).
13//!
14//! **L0 never:** interprets a conversation, holds session state, dispatches a
15//! tool, or decides *when* to speak. It moves frames and tells the truth
16//! about time.
17//!
18//! The primitives, by concern:
19//!
20//! | Concern | Primitives |
21//! |---|---|
22//! | Connect | [`SessionConfig`], [`ConnectBuilder`], [`ApiEndpoint`], [`ResumeInfo`] |
23//! | Speak / listen | [`SessionHandle`], [`SessionWriter`], [`SessionReader`], [`SessionEvent`], [`SessionPhase`] |
24//! | Say things | [`Content`], [`Part`], [`Role`], [`ModelId`], [`Voice`], [`Modality`] |
25//! | Tools on the wire | [`Tool`], [`FunctionDeclaration`], [`FunctionCall`], [`FunctionResponse`], [`FunctionCallingBehavior`], [`FunctionResponseScheduling`] |
26//! | Real time | [`SpscRing`], [`AudioJitterBuffer`], [`bytes_to_i16`], [`i16_to_bytes`], [`BargeInDetector`], [`TurnDetector`] |
27//! | Access | [`AuthProvider`], [`GoogleAIAuth`], [`VertexAIAuth`], [`Transport`], [`TungsteniteTransport`], [`Codec`], [`JsonCodec`] |
28//! | Truth | [`UsageMetadata`], [`SessionError`] |
29
30pub use crate::protocol::types::{
31    ApiEndpoint, Content, FunctionCall, FunctionCallingBehavior, FunctionDeclaration,
32    FunctionResponse, FunctionResponseScheduling, Modality, ModelId, Part, Role, SessionConfig,
33    Tool, UsageMetadata, Voice,
34};
35
36pub use crate::session::{
37    ResumeInfo, SessionError, SessionEvent, SessionHandle, SessionPhase, SessionReader,
38    SessionWriter,
39};
40
41pub use crate::transport::auth::{AuthProvider, GoogleAIAuth, VertexAIAuth};
42pub use crate::transport::ws::{Transport, TungsteniteTransport};
43pub use crate::transport::{Codec, ConnectBuilder, JsonCodec};
44
45pub use crate::buffer::{
46    AudioJitterBuffer, SpscConsumer, SpscProducer, SpscRing, bytes_to_i16, i16_to_bytes,
47};
48pub use crate::turn::{BargeInDetector, TurnDetector};
49
50#[cfg(test)]
51mod contract {
52    //! The drift guard: every primitive the module docs name must exist and
53    //! be reachable from this path. A rename or removal fails compilation
54    //! here first — the contract cannot erode silently.
55    #[test]
56    fn every_named_primitive_is_reachable() {
57        use super::*;
58        fn is_type<T: ?Sized>() {}
59        is_type::<SessionConfig>();
60        is_type::<ConnectBuilder>();
61        is_type::<ApiEndpoint>();
62        is_type::<ResumeInfo>();
63        is_type::<SessionHandle>();
64        is_type::<dyn SessionWriter>();
65        is_type::<dyn SessionReader>();
66        is_type::<SessionEvent>();
67        is_type::<SessionPhase>();
68        is_type::<Content>();
69        is_type::<Part>();
70        is_type::<Role>();
71        is_type::<ModelId>();
72        is_type::<Voice>();
73        is_type::<Modality>();
74        is_type::<Tool>();
75        is_type::<FunctionDeclaration>();
76        is_type::<FunctionCall>();
77        is_type::<FunctionResponse>();
78        is_type::<FunctionCallingBehavior>();
79        is_type::<FunctionResponseScheduling>();
80        is_type::<SpscRing<i16>>();
81        is_type::<SpscProducer<i16>>();
82        is_type::<SpscConsumer<i16>>();
83        is_type::<AudioJitterBuffer>();
84        is_type::<BargeInDetector>();
85        is_type::<TurnDetector>();
86        is_type::<dyn AuthProvider>();
87        is_type::<GoogleAIAuth>();
88        is_type::<VertexAIAuth>();
89        is_type::<TungsteniteTransport>();
90        is_type::<dyn Codec>();
91        is_type::<JsonCodec>();
92        is_type::<UsageMetadata>();
93        is_type::<SessionError>();
94        fn transport_is_reachable<T: Transport>() {}
95        let _ = transport_is_reachable::<TungsteniteTransport>;
96        let _ = bytes_to_i16;
97        let _ = i16_to_bytes;
98    }
99}
gemini_genai_rs/primitives.rs

gemini_genai_rs/
primitives.rs
