gemini_adk_fluent_rs/
lib.rs

1#![warn(missing_docs)]
2//! # gemini-adk-fluent-rs
3//!
4//! Fluent developer experience layer for the Gemini Live agent stack.
5//! This is the highest-level crate in the workspace, providing a builder API,
6//! operator algebra, and composition modules that sit on top of
7//! [`gemini_adk_rs`] (agent runtime) and [`gemini_genai_rs`] (wire protocol).
8//!
9//! ## Module Organization
10//!
11//! | Module | Purpose |
12//! |--------|---------|
13//! | [`builder`] | Copy-on-write immutable `AgentBuilder` for declarative agent configuration |
14//! | [`compose`] | S·C·T·P·M·A operator algebra for composing agent primitives |
15//! | [`live`] | `Live` session handle — callback-driven full-duplex event handling |
16//! | [`live_builders`] | Builder types for live session configuration |
17//! | [`operators`] | Operator combinators for composing agents |
18//! | [`patterns`] | Pre-built composition patterns for common use cases |
19//! | [`testing`] | Test utilities and mock helpers |
20//!
21//! ## Quick Start
22//!
23//! ```rust,ignore
24//! use gemini_adk_fluent_rs::prelude::*;
25//!
26//! let agent = AgentBuilder::new("my-agent")
27//!     .model(GeminiModel::Gemini2_0Flash)
28//!     .instruction("You are a helpful assistant.")
29//!     .build();
30//! ```
31//!
32//! ## Relationship to Other Crates
33//!
34//! - **`gemini-live`** (L0): Wire protocol, transport, types — re-exported via [`gemini_genai_rs`]
35//! - **`gemini-adk-rs`** (L1): Agent runtime, tools, sessions — re-exported via [`gemini_adk_rs`]
36//! - **`gemini-adk-fluent-rs`** (L2): This crate — ergonomic builder API and composition
37
38pub mod a2a;
39pub mod builder;
40pub mod compose;
41pub mod conversation;
42pub mod flow_macros;
43pub mod live;
44pub mod live_builders;
45pub mod motifs;
46pub mod operators;
47pub mod patterns;
48pub mod policy;
49pub mod simulation;
50pub mod testing;
51
52pub use gemini_adk_rs;
53pub use gemini_genai_rs;
54
55// ---------------------------------------------------------------------------
56// Curated submodule homes (gap #9 — prelude hard carve).
57//
58// The kernel `prelude` (below) re-exports only the ~30 types a typical app
59// touches. Everything else lives in these focused, discoverable modules so
60// `use gemini_adk_fluent_rs::prelude::*` stays small and the rest is one
61// `use gemini_adk_fluent_rs::{live, text, tools, …}` away. Import from the
62// highest-level crate you need.
63// ---------------------------------------------------------------------------
64
65/// Text-agent runtime and combinators (carved out of the kernel `prelude`).
66///
67/// `LlmTextAgent`, the sequential/parallel/loop/fallback/route/race/timeout/map
68/// combinators, and the `TextAgent` trait.
69pub mod text {
70    pub use gemini_adk_rs::text::*;
71}
72
73/// Tool definitions, dispatch, toolsets, the confirmation flow, and frames.
74pub mod tools {
75    pub use gemini_adk_rs::confirmation::*;
76    pub use gemini_adk_rs::extract::{Recognizer, RecordExtractor};
77    pub use gemini_adk_rs::frame::{
78        ConfirmPolicy, FrameSpec, SlotRecognizer, SlotSpec, SlotValidator,
79    };
80    pub use gemini_adk_rs::tool::*;
81    pub use gemini_adk_rs::toolset::*;
82}
83
84/// LLM abstraction: params, requests/responses, and the registry.
85pub mod llm {
86    pub use gemini_adk_rs::llm::*;
87}
88
89/// Concurrent typed state: `State`, `PrefixedState`, `StateKey`, prefix scopes.
90pub mod state {
91    pub use gemini_adk_rs::state::*;
92}
93
94/// Governed-conversation flow primitives: `Flow`, `Step`, `Guard`, `FlowMonitor`.
95pub mod flow {
96    pub use gemini_adk_rs::flow::*;
97}
98
99/// Agent builders, the agent trait, and the operator/pattern combinators.
100///
101/// Note: the L1 [`gemini_adk_rs::agent::Agent`] *trait* is re-exported here as
102/// `AgentTrait` to avoid colliding with the L2 `Agent` (the [`AgentBuilder`](crate::builder::AgentBuilder))
103/// builder alias.
104pub mod agents {
105    pub use crate::builder::*;
106    pub use crate::operators::*;
107    pub use crate::patterns::*;
108    #[doc(inline)]
109    pub use gemini_adk_rs::agent::Agent as AgentTrait;
110    pub use gemini_adk_rs::agent_session::*;
111    pub use gemini_adk_rs::orchestration::{
112        self, call as call_agent, provenance, Mode as AgentMode, Resolver,
113    };
114}
115
116/// L0 wire-protocol types for raw WebSocket access.
117pub mod wire {
118    pub use gemini_genai_rs::prelude::*;
119}
120
121/// Clone multiple bindings for use in `move` closures, reducing Arc/clone boilerplate.
122///
123/// # Example
124///
125/// ```rust,ignore
126/// use gemini_adk_fluent_rs::let_clone;
127/// use std::sync::Arc;
128///
129/// let state = Arc::new(42);
130/// let writer = Arc::new("hello");
131///
132/// let_clone!(state, writer);
133/// tokio::spawn(async move {
134///     println!("{state} {writer}");
135/// });
136/// ```
137#[macro_export]
138macro_rules! let_clone {
139    ($($name:ident),+ $(,)?) => {
140        $(let $name = $name.clone();)+
141    };
142}
143
144/// The kernel prelude — the ~40 types a typical application touches.
145///
146/// Gap #9 carved this down from the previous everything-prelude. Anything not
147/// here now lives in a focused submodule and is one import away:
148///
149/// | Need | Import |
150/// |------|--------|
151/// | Full Live control plane (persistence, repair, steering, transcripts, contracts) | `use gemini_adk_fluent_rs::live::*;` |
152/// | Text-agent runtime details | `use gemini_adk_fluent_rs::text::*;` |
153/// | Toolsets, confirmation, frames | `use gemini_adk_fluent_rs::tools::*;` |
154/// | State prefixes / `SlotEvidence` | `use gemini_adk_fluent_rs::state::*;` |
155/// | Full flow vocabulary (`CompiledFlow`, `StepAction`, `Violation`, …) | `use gemini_adk_fluent_rs::flow::*;` |
156/// | Agent trait + operator/pattern internals | `use gemini_adk_fluent_rs::agents::*;` |
157/// | Conversation compiler (`Conversation`, `ConversationSpec`, …) | `use gemini_adk_fluent_rs::conversation::*;` |
158/// | A2A, motifs, policy, simulation, testing, orchestration, credentials, run_config | the same-named module, e.g. `use gemini_adk_fluent_rs::simulation::*;` |
159/// | Raw L0 wire types | `use gemini_adk_fluent_rs::wire::*;` |
160pub mod prelude {
161    // ── Builders, composition algebra, operators, patterns (headline DX) ──
162    pub use crate::builder::*;
163    pub use crate::compose::{Ctx, A, C, E, G, M, P, S, T};
164    pub use crate::live::Live;
165    pub use crate::operators::*;
166    pub use crate::patterns::*;
167    // Build-time validation DX (contract checking, data-flow inference, harness).
168    pub use crate::testing::{
169        check_contracts, diagnose, infer_data_flow, AgentHarness, ContractViolation, DataFlowEdge,
170    };
171
172    // The L1 `gemini_adk_rs::agent::Agent` *trait* collides with the L2 `Agent`
173    // type alias (= AgentBuilder), so it is re-exported under the disambiguated
174    // name `AgentTrait` (also available at `gemini_adk_fluent_rs::agents::AgentTrait`).
175    #[doc(inline)]
176    pub use gemini_adk_rs::agent::Agent as AgentTrait;
177
178    // ── Errors ──
179    pub use gemini_adk_rs::error::{AgentError, AgentResult, ToolError};
180
181    // ── Governed flow (core vocabulary; full set in `crate::flow`) ──
182    pub use gemini_adk_rs::flow::{
183        Enforcement as FlowMode, Flow, FlowMonitor, Guard, ToolPolicy, Verdict,
184    };
185
186    // ── State (prefix scopes + `SlotEvidence` in `crate::state`) ──
187    pub use gemini_adk_rs::state::{State, StateKey};
188
189    // ── LLM (core; params/request/response/registry in `crate::text`) ──
190    pub use gemini_adk_rs::llm::{BaseLlm, GeminiLlm};
191
192    // ── Tools ──
193    pub use gemini_adk_rs::tool::{SimpleTool, ToolDispatcher, ToolFunction, TypedTool};
194    // The `#[tool]` attribute macro — turns an `async fn` into a registrable tool.
195    pub use gemini_adk_rs::tool;
196    // Brings in both the `Extract` struct and the `#[derive(Extract)]` macro.
197    pub use gemini_adk_rs::Extract;
198    // The `#[derive(Frame)]` macro.
199    pub use gemini_adk_rs::Frame;
200
201    // ── Callback contexts (used in `M::` hooks) ──
202    pub use gemini_adk_rs::context::{CallbackContext, ToolContext};
203
204    // ── Common Live session types (full control plane in `crate::live`) ──
205    pub use gemini_adk_rs::live::{
206        ContextDelivery, EventCallbacks, ExtractionTrigger, FsPersistence, LiveHandle,
207        LlmExtractor, MemoryPersistence, RepairConfig, SessionPersistence, SoftTurnDetector,
208        SteeringMode, TranscriptBuffer, TranscriptTurn, TurnExtractor,
209    };
210
211    // ── Text-agent combinators (runtime details in `crate::text`) ──
212    pub use gemini_adk_rs::text::{
213        DispatchTextAgent, FallbackTextAgent, FnTextAgent, JoinTextAgent, LlmTextAgent,
214        LoopTextAgent, MapOverTextAgent, ParallelTextAgent, RaceTextAgent, RouteRule,
215        RouteTextAgent, SequentialTextAgent, TapTextAgent, TaskRegistry, TextAgent,
216        TimeoutTextAgent,
217    };
218
219    // ── L0 wire protocol (GeminiModel, Voice, Content, Part, Role, …) ──
220    pub use gemini_genai_rs::prelude::*;
221}
gemini_adk_fluent_rs/lib.rs

gemini_adk_fluent_rs/
lib.rs
