Module live

Expand description

Live — Fluent builder for callback-driven Gemini Live sessions.

Wraps L1’s LiveSessionBuilder with ergonomic callback registration and integration with composition modules (M, T, P).

§Callback Modes

Control-lane callbacks support two execution modes via gemini_adk_rs::live::ExecutionMode:

Default methods (e.g., .on_turn_complete()) → gemini_adk_rs::live::ExecutionMode::Blocking
_concurrent methods (e.g., .on_turn_complete_concurrent()) → gemini_adk_rs::live::ExecutionMode::Concurrent

Use concurrent mode for fire-and-forget work (logging, analytics, webhook dispatch). The lane rule for every callback is written once, at the top of the callbacks module (see the Live callback setters).

§Background Tool Execution

Mark tools for background execution to eliminate dead air in voice sessions:

Live::builder()
    .tools(tools)
    .tool_background("search_kb")
    .connect_from_env()
    .await?;

Structs§

BackendInputVad: Incremental VAD over arbitrary PCM16 byte chunks.
BackendVadSnapshot: Snapshot of backend VAD state for devtools and diagnostics.
BackgroundAgentDispatcher: Dispatcher for running TextAgent pipelines as background tasks.
BackgroundToolTracker: Tracks in-flight background tool executions for cancellation.
ComputedContract: A computed state declaration.
ComputedRegistry: Registry of computed variables with dependency-ordered evaluation.
ComputedVar: A computed state variable: a pure function of other state keys.
ConsecutiveFailureDetector: Fires when a named tool has failed threshold consecutive times.
ContextBuilder: Declarative state-to-narrative renderer.
ControlContract: Runtime control-plane settings.
DefaultResultFormatter: Default formatter that wraps results in a status object.
DeferredWriter: A SessionWriter wrapper that flushes pending context before user content.
DeliveryConfig: Per-event-class delivery (backpressure) policy for the fast lane.
EffectPolicy: Execution policy for an effect.
EventCallbacks: Typed callback registry for Live session events.
ExtractorContract: A turn extractor declaration.
FieldPromotion: Rule for promoting one raw extraction field into authoritative state.
FsPersistence: File-system persistence (good for development and single-server deployments).
InputAudioConfig: Input-audio hardening configuration accumulated by the builder and applied to the LiveHandle right after connect. Stages run over each outgoing frame in the order they were configured — chain the denoiser before the gate so the gate calibrates on clean levels (see Live::mic_denoise, Live::mic_noise_gate, Live::mic_processor, Live::input_vad, Live::client_interruption_authority).
LatencyBucket: One bucket of the response-latency histogram.
LatencyStats: Response-latency distribution for the session so far.
Live: Fluent builder for constructing and connecting Gemini Live sessions.
LiveEffectExecutor: Executes LiveEffect values emitted by the Live reactor.
LiveEventStream: A [futures_util::Stream] of LiveEvents from a Live session.
LiveHandle: Handle for interacting with a running Live session.
LiveReactor: Ordered collection of reactor rules.
LiveSessionBuilder: Builder for a callback-driven Live session.
LlmExtractor: LLM-backed turn extractor that sends transcript windows to an OOB LLM with a structured extraction prompt.
MemoryPersistence: In-memory persistence (good for tests).
NeedsFulfillment: Tracks need fulfillment per phase and recommends repair actions.
PendingContext: Thread-safe buffer for pending context turns awaiting delivery.
Phase: A conversation phase with instruction, tools, and transitions.
PhaseContract: A conversation phase declaration.
PhaseMachine: Evaluates transitions and manages phase entry/exit lifecycle.
PhasePreparation: A preparation effect that can materialize state before a phase is entered.
PreparationContract: A phase preparation declaration.
PromotionContract: A field promotion declaration.
RateDetector: Fires when at least count matching events occur within window.
Reaction: A policy-wrapped effect.
RepairConfig: Configuration for the conversation repair system.
ReplaySession: A replayed session: the live handle plus the replay controls.
RuntimeContract: Serializable description of a configured Live runtime.
SessionSignals: Tracks session-level signals automatically from events.
SessionSnapshot: Serializable snapshot of the control plane state.
SessionTelemetry: Zero-overhead telemetry collector for speech-to-speech sessions.
SoftTurnDetector: Detects proactive silence — user stopped speaking but model didn’t respond.
SustainedDetector: Fires when a state-based condition remains true for at least duration.
TemporalRegistry: Registry of temporal patterns evaluated on events and/or timer ticks.
ToolCallSummary: Summary of a tool call within a conversation turn.
ToolContract: A tool declaration in the runtime contract.
TranscriptBuffer: Accumulates input/output transcripts and segments them by turn boundaries.
TranscriptTurn: A single completed conversation turn with accumulated transcripts.
TranscriptWindow: A read-only snapshot of recent transcript turns for context construction.
Transition: A guard-based transition to a named target phase.
TransitionContract: A phase transition declaration.
TransitionRecord: Record of a single phase transition that already happened, kept in PhaseMachine::history. Distinct from Transition, the declared edge.
TransitionResult: Result of a phase transition, carrying the resolved instruction and any context to inject.
TurnCommitConfig: Operating point for turn commitment. All timings are measured from the VAD edge (which already includes the detector’s hangover).
TurnCommitPolicy: The policy state machine. Driven by a monotonic millisecond audio clock (advance it by the duration of each audio chunk, not wall time).
TurnCountDetector: Fires when a state-based condition is true for required consecutive evaluations (typically one evaluation per turn).
VoiceRuntimeState: Voice-flow state owned by the reactor.
Watcher: A single state watcher: observes one key, fires an async action when the predicate matches.
WatcherContract: A watcher declaration.
WatcherRegistry: Registry of state watchers, evaluated after each mutation cycle.

Enums§

ActivityAuthority: Who decides when user speech interrupts the model.
ContextDelivery: When to deliver model-role context turns to the wire.
Delivery: Backpressure (delivery) policy for a single class of fast-lane events.
ExecutionMode: How an async hook or effect runs relative to the control lane.
ExtractionTrigger: Controls WHEN an extractor runs.
InputStage: One stage of the input mic chain — the named stages the SDK ships plus an open Custom slot for any InputAudioProcessor.
InstructionModifier: A modifier that transforms a phase instruction based on runtime state.
LiveEffect: A typed runtime effect emitted by a reaction.
LiveEvent: Semantic events emitted by the Live session processor.
MergePolicy: How an extracted field should be merged into authoritative session state.
PersistenceError: Error returned by a SessionPersistence backend.
PhaseInstruction: Instruction source for a phase — either a fixed string or a closure over state.
ReactorEvent: A normalized event that can drive ADK-level reactions.
RepairAction: What action the repair system recommends.
SessionType: Session type determines the server-side duration limit.
SteeringMode: How the phase machine steers the model’s behavior.
ToolExecutionMode: Execution mode for a tool.
TransitionEvaluation: Result of evaluating outbound transitions.
TransitionTrigger: What caused a phase transition.
TurnSignal: A committed turn signal, produced at its commit time.
WatchPredicate: Condition under which a watcher fires, evaluated against (old, new) values.

Constants§

DEFAULT_COMPRESSION_TARGET_TOKENS: Token count the default sliding window compresses the history down to.
DEFAULT_COMPRESSION_TRIGGER_TOKENS: Token count at which the default context window compression kicks in.

Traits§

InputAudioProcessor: A per-frame processor applied to outgoing microphone audio inside LiveHandle::send_audio — the L1 seam the L2 voice chain (denoiser, noise gate) plugs into so hosted surfaces (web bridge, API server) get the same hardened path as native pumps. Runs on the send path: keep it fast and allocation-light.
PatternDetector: A detector that evaluates whether a temporal pattern has been triggered.
ReactorRule: A rule that reacts to normalized events and emits typed effects.
ResultFormatter: Formats tool responses for background execution lifecycle.
SessionPersistence: Trait for persisting session state across process restarts.
TurnExtractor: Trait for between-turn extraction from transcript windows.

Functions§

attach_session: Attach the full L1 control plane (three-lane processor, phase machine, extractors, watchers, tool dispatch, …) to an already connected L0 session.
collect_events_until_idle: Collect LiveEvents until the stream stays idle for idle (or max elapses). Useful for settling an as-fast-as-possible replay where “done” means “no more effects are propagating”.
replay_session: Replay a recorded wire log through the real L1 processor, offline.

Type Aliases§

PredicateFn: Custom predicate function type for state change watchers.
SessionHook: An async session hook: receives a clone of the shared State and the session writer. The shape of phase on_enter/on_exit, phase preparations, and temporal-pattern actions.

Module live

Module live Copy item path

§Callback Modes

§Background Tool Execution

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Module live