Crate flowcat_core 

flowcat-core

A native-Rust real-time voice-agent runtime. It carries a phone/WebRTC call’s audio, runs a speech-to-speech model (Gemini Live first), and lets a pluggable “brain” drive the conversation — all in one tokio process, no GIL, no FFI.

flowcat-core knows nothing about any embedder, web routing, SQL, or any wire contract — it is a self-contained Apache-2.0 runtime library. The embedder-specific glue lives in the consumer crate.

The seams (traits)

• MediaTransport — the transport-agnostic decoded-audio seam the pipeline drives (carrier WS frames or RTP look identical to it).
• MediaSocket — a raw bidirectional WS text/binary frame pipe.
• MediaSerializer — pure per-carrier WS framing (Plivo). WsCarrierTransport composes a MediaSocket + MediaSerializer into a MediaTransport (the WS/Plivo path).
• RealtimeLlm — streaming speech-to-speech model (GeminiLive).
• AgentBrain — conversation decision-maker (the host wires the engine).
• SessionSource — call bootstrap + finalize (the host wires /internal).

[pipeline::build_s2s_task] / pipeline::build_cascaded_task assemble the processor pipeline that orchestrates them for one call.

See DESIGN.md for the full design (crate layout, trait contracts, audio path, Gemini Live protocol).

Re-exports

pub use error::FlowcatError;

pub use error::Result;

pub use types::AudioChunk;

pub use types::BrainAction;

pub use types::Finalize;

pub use types::RealtimeEvent;

pub use types::RealtimeSetup;

pub use types::ResolvedCall;

pub use types::SerIn;

pub use types::ToolDecl;

pub use types::UploadTarget;

pub use types::Usage;

pub use types::WsIn;

pub use types::WsOut;

pub use observer::FrameEvent;

pub use observer::FrameObserver;

pub use observer::FramePushEvent;

pub use observer::Observer;

pub use pipeline::ParallelPipeline;

pub use pipeline::Pipeline;

pub use pipeline::PipelineRunner;

pub use pipeline::PipelineTask;

pub use pipeline::PipelineTaskParams;

pub use pipeline::SourceHandle;

pub use pipeline::SourcePump;

pub use processor::frame::AudioFrame;

pub use processor::frame::CustomFrame;

pub use processor::frame::Direction;

pub use processor::frame::Frame;

pub use processor::frame::FrameClass;

pub use processor::frame::FrameMeta;

pub use processor::frame::KeypadEntry;

pub use processor::frame::Language;

pub use processor::frame::LlmContext;

pub use processor::frame::StartParams;

pub use processor::frame::VadParams;

pub use processor::metrics::LlmTokenUsage;

pub use processor::metrics::MetricsData;

pub use processor::Envelope;

pub use processor::FrameProcessor;

pub use processor::Link;

pub use processor::ProcessorSetup;

pub use processor::StopReason;

pub use brain::AgentBrain;

pub use realtime::RealtimeBackend;

pub use realtime::RealtimeKickoff;

pub use realtime::RealtimeLlm;

pub use serializer::MediaSerializer;

pub use session::SessionSource;

pub use transport::MediaSocket;

pub use transport::MediaTransport;

pub use transport::MediaIn;

pub use realtime::GeminiLive;

pub use realtime::ServiceRealtimeAdapter;

pub use serializer::PlivoSerializer;

pub use transport::WsCarrierTransport;

pub use transport::WsMediaTransport;

pub use sip::InboundInvite;

pub use sip::SipAgent;

pub use sip::SipConfig;

pub use sip::SipTransport;

pub use sip::DEFAULT_RTP_PORT_BASE;

pub use sip::DEFAULT_RTP_PORT_TRIES;

Modules

agent

Higher-level pure-logic conversation features (no network).

audio

Audio intelligence + call recording (PROCESSOR-DESIGN §6.1).

brain

The conversation decision-maker seam.

codec

Audio codec helpers: G.711 (μ-law / A-law) ↔ PCM16 and sample-rate conversion.

error

The crate-wide error type.

frameDeprecated

Deprecated re-export shim: crate::frame was renamed to crate::types (PROCESSOR-DESIGN §8.4, step M0). Kept for one release so existing call sites (crate::frame::AudioChunk, …) keep compiling; new code should use crate::types. Do not confuse with crate::processor::frame (the pipeline Frame enum).

observer

Non-intrusive pipeline monitoring (PROCESSOR-DESIGN §5.1).

pipeline

Pipeline + ParallelPipeline + PipelineTask + PipelineRunner (PROCESSOR-DESIGN §3/§4).

processor

The FrameProcessor trait + the channel-runtime building blocks (PROCESSOR-DESIGN §2).

realtime

The speech-to-speech model abstraction. GeminiLive is the first impl.

serializer

Per-carrier WebSocket framing. Pure (no I/O): turns inbound frames into normalized SerIn events and encodes outbound audio/clears into WsOut.

service

Service-processor trait signatures the cascaded path builds against (PROCESSOR-DESIGN §6.1) + no-op mock impls + the audio-intelligence traits.

session

Call bootstrap + finalize seam.

sip

Native SIP/RTP: Flowcat speaks SIP directly (no FreeSWITCH).

transcript

Transcript collection.

transport

Transport layer.

types

Shared data types that flow across the trait seams.