flowgentra_ai/
lib.rs

1//! ## Project Hygiene
2//!
3//! - Enforce `cargo fmt` and `clippy` in CI.
4//! - Maintain a `CHANGELOG.md` for releases.
5//! - Keep `CONTRIBUTING.md` up to date.
6//!
7//! FlowgentraAI: A Rust library for building AI agents with graphs
8//!
9//! Build AI agent workflows using a declarative graph structure with:
10//! - **Nodes**: Computational steps (handlers)
11//! - **Edges**: Connections with optional conditional logic
12//! - **State**: Shared JSON data flowing between nodes
13//! - **LLM Integration**: Built-in support for OpenAI, Anthropic, Mistral, etc.
14//! - **Auto-Discovery**: Automatic handler registration via `#[register_handler]`
15//!
16//! # Quick Start
17//!
18//! ```ignore
19//! use flowgentra_ai::prelude::*;
20//! use serde_json::json;
21//!
22//! pub async fn my_handler(state: SharedState) -> Result<SharedState> {
23//!     let input = state.get("input").and_then(|v| v.as_str().map(|s| s.to_string())).unwrap_or_default();
24//!     state.set("output", json!(input.to_uppercase()));
25//!     Ok(state)
26//! }
27//!
28//! #[tokio::main]
29//! async fn main() -> Result<()> {
30//!     let mut agent = from_config_path("config.yaml")?;
31//!     agent.state.set("input", json!("hello"));
32//!     let result = agent.run().await?;
33//!     Ok(())
34//! }
35//! ```
36//!
37//! # Architecture
38//!
39//! The library is organized by layer:
40//! - [`core::agent`] - High-level agent API and handler registration
41//! - [`core::runtime`] - Execution engine and graph orchestration
42//! - [`core::graph`] - Graph structure (nodes and edges)
43//! - [`core::state`] - State management and validation
44//! - [`core::config`] - YAML configuration loading
45//! - [`core::llm`] - LLM provider integration
46//! - [`core::mcp`] - Model Context Protocol support
47//!
48//! For most use cases, import from the [`prelude`] module.
49
50pub mod core;
51
52pub use crate::prelude::*;
53// Re-export from core submodules
54pub use core::agent::{
55    from_config_path, Agent, ArcHandler, Handler, HandlerEntry, HandlerRegistry,
56};
57pub use core::config::AgentConfig;
58pub use core::error::{FlowgentraError, Result};
59pub use core::graph::Graph;
60pub use core::AgentRuntime;
61// These are re-exported via prelude; remove direct pub use to avoid unresolved import errors.
62pub use flowgentra_ai_macros::register_handler;
63
64/// Prelude module for commonly used types and macros.
65///
66/// Import everything you need for building agents:
67///
68/// ```no_run
69/// use flowgentra_ai::prelude::*;
70/// ```
71///
72/// This re-exports:
73/// - `#[register_handler]` - Attribute macro for handler registration
74/// - `from_config_path()` - Create agents with auto-discovered handlers
75/// - `Agent`, `State`, `Result` - Core types
76/// - `AgentConfig`, `LLMConfig` - Configuration types
77/// - And other commonly used utilities
78pub mod prelude {
79    pub use crate::core::agent::from_config_path;
80    pub use crate::core::agent::{Agent, ArcHandler, Handler, HandlerEntry, HandlerRegistry};
81    pub use crate::core::{
82        config::{
83            AgentConfig, EmbeddingsConfig, PdfSettings, RAGGraphConfig, RetrievalSettings,
84            StateField, VectorStoreConfig,
85        },
86        error::{FlowgentraError, Result},
87        graph::{
88            routing::{ComparisonOp, Condition, RoutingCondition},
89            Graph,
90        },
91        llm::{
92            CachedLLMClient, FallbackLLMClient, LLMConfig, LLMProvider, Message, MessageRole,
93            ResponseFormat, ToolCall, ToolDefinition,
94        },
95        mcp::MCPConfig,
96        memory::{
97            BufferWindowConfig, Checkpoint, CheckpointMetadata, Checkpointer, ConversationMemory,
98            ConversationMemoryConfig, InMemoryConversationMemory, MemoryCheckpointer, MemoryConfig,
99            SummaryConfig, SummaryMemory, TokenBufferMemory,
100        },
101        node::{Node, NodeFunction},
102        runtime::{AgentRuntime, CloneStats, OptimizedState},
103        state::{PlainState, SharedState, StateExt, TypedState},
104        state_graph::{
105            create_tool_node, store_tool_calls, tools_condition, MessageGraphBuilder, StateGraph,
106            StateGraphBuilder,
107        },
108        State,
109    };
110
111    pub use crate::core::rag::{
112        bm25_score,
113        // PDF utilities
114        chunk_text,
115        chunk_text_by_tokens,
116        dedup_by_id,
117        dedup_by_similarity,
118        estimate_tokens,
119        evaluate,
120        extract_and_chunk,
121        extract_text,
122        hit_rate,
123        hybrid_merge,
124        load_directory,
125        load_document,
126        mean_ndcg,
127        mrr,
128        // Search & retrieval
129        CachedEmbeddings,
130        // Core types
131        ChromaStore,
132        // Text splitters
133        ChunkMetadata,
134        CodeTextSplitter,
135        CrossEncoderReranker,
136        Document,
137        EmbeddingError,
138        EmbeddingModel,
139        Embeddings,
140        EmbeddingsProvider,
141        EvalQuery,
142        EvalResults,
143        FileType,
144        HTMLTextSplitter,
145        HuggingFaceEmbeddings,
146        InMemoryVectorStore,
147        IngestionPipeline,
148        IngestionStats,
149        LLMReranker,
150        Language,
151        LoadedDocument,
152        MarkdownTextSplitter,
153        MetadataFilter,
154        MistralEmbeddings,
155        MockEmbeddings,
156        NoopReranker,
157        OllamaEmbeddings,
158        OpenAIEmbeddings,
159        PdfDocument,
160        QueryExpander,
161        QueryResult as EvalQueryResult,
162        RAGConfig,
163        RAGHandlers,
164        RAGNodeConfig,
165        RRFReranker,
166        RecursiveCharacterTextSplitter,
167        RerankStrategy,
168        Reranker,
169        RetrievalConfig,
170        Retriever,
171        RetrieverStrategy,
172        SearchResult,
173        TextChunk,
174        TextSplitter,
175        TokenTextSplitter,
176        VectorStore,
177        VectorStoreBackend,
178        VectorStoreError,
179        VectorStoreType,
180    };
181
182    pub use crate::register_handler;
183
184    // ── Library utility functions users can call inside their own handlers ──
185    // These are the same functions the built-in nodes use internally, exposed
186    // so users can compose their own logic without re-implementing them.
187    pub use crate::core::node::evaluation_node::evaluate_output_score;
188}
flowgentra_ai/lib.rs

flowgentra_ai/
lib.rs
