flowcat_core/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2//
3//! # flowcat-core
4//!
5//! A native-Rust real-time voice-agent runtime. It carries a phone/WebRTC
6//! call's audio, runs a speech-to-speech model (Gemini Live first), and lets a
7//! pluggable "brain" drive the conversation — all in one `tokio` process, no
8//! GIL, no FFI.
9//!
10//! `flowcat-core` knows **nothing** about any embedder, web routing, SQL, or any
11//! wire contract — it is a self-contained Apache-2.0 runtime library. The
12//! embedder-specific glue lives in the consumer crate.
13//!
14//! ## The seams (traits)
15//!
16//! - [`MediaTransport`] — the transport-agnostic *decoded-audio* seam the
17//!   pipeline drives (carrier WS frames or RTP look identical to it).
18//! - [`MediaSocket`] — a raw bidirectional WS text/binary frame pipe.
19//! - [`MediaSerializer`] — pure per-carrier WS framing (Plivo).
20//!   [`WsCarrierTransport`] composes a `MediaSocket` + `MediaSerializer` into a
21//!   [`MediaTransport`] (the WS/Plivo path).
22//! - [`RealtimeLlm`] — streaming speech-to-speech model ([`GeminiLive`]).
23//! - [`AgentBrain`] — conversation decision-maker (the host wires the engine).
24//! - [`SessionSource`] — call bootstrap + finalize (the host wires `/internal`).
25//!
26//! [`pipeline::build_s2s_task`] / [`pipeline::build_cascaded_task`] assemble the
27//! processor pipeline that orchestrates them for one call.
28//!
29//! See `DESIGN.md` for the full design (crate layout, trait contracts, audio
30//! path, Gemini Live protocol).
31
32pub mod agent;
33pub mod audio;
34pub mod brain;
35pub mod codec;
36pub mod error;
37pub mod observer;
38pub mod pipeline;
39pub mod processor;
40pub mod realtime;
41pub mod serializer;
42pub mod service;
43pub mod session;
44pub mod sip;
45pub mod transcript;
46pub mod transport;
47pub mod types;
48
49/// Deprecated re-export shim: `crate::frame` was renamed to [`crate::types`]
50/// (PROCESSOR-DESIGN §8.4, step M0). Kept for one release so existing call sites
51/// (`crate::frame::AudioChunk`, …) keep compiling; new code should use
52/// [`crate::types`]. Do **not** confuse with [`crate::processor::frame`] (the
53/// pipeline `Frame` enum).
54#[deprecated(note = "renamed to `crate::types`; use that instead (see §8.4 M0)")]
55pub mod frame {
56    pub use crate::types::*;
57}
58
59// ---- Public contract surface (flat re-exports for ergonomic use) ----
60
61pub use error::{FlowcatError, Result};
62
63pub use types::{
64    AudioChunk, BrainAction, Finalize, RealtimeEvent, RealtimeSetup, ResolvedCall, SerIn, ToolDecl,
65    UploadTarget, Usage, WsIn, WsOut,
66};
67
68// ---- The processor framework: the live call orchestration. ----
69
70pub use observer::{FrameEvent, FrameObserver, FramePushEvent, Observer};
71pub use pipeline::{
72    ParallelPipeline, Pipeline, PipelineRunner, PipelineTask, PipelineTaskParams, SourceHandle,
73    SourcePump,
74};
75pub use processor::frame::{
76    AudioFrame, CustomFrame, Direction, Frame, FrameClass, FrameMeta, KeypadEntry, Language,
77    LlmContext, StartParams, VadParams,
78};
79pub use processor::metrics::{LlmTokenUsage, MetricsData};
80pub use processor::{Envelope, FrameProcessor, Link, ProcessorSetup, StopReason};
81
82// The trait seams.
83pub use brain::AgentBrain;
84pub use realtime::{RealtimeBackend, RealtimeKickoff, RealtimeLlm};
85pub use serializer::MediaSerializer;
86pub use session::SessionSource;
87pub use transport::{MediaSocket, MediaTransport};
88
89// The transport-agnostic inbound event.
90pub use transport::MediaIn;
91
92// Concrete implementations.
93pub use realtime::{GeminiLive, ServiceRealtimeAdapter};
94pub use serializer::PlivoSerializer;
95pub use transport::{WsCarrierTransport, WsMediaTransport};
96
97// Native SIP/RTP (a `MediaTransport` over a real SIP trunk).
98pub use sip::{
99    InboundInvite, SipAgent, SipConfig, SipTransport, DEFAULT_RTP_PORT_BASE, DEFAULT_RTP_PORT_TRIES,
100};
flowcat_core/lib.rs

flowcat_core/
lib.rs
