llm_stack/
lib.rs

1//! # llm-stack
2//!
3//! Provider-agnostic types and traits for interacting with large language models.
4//!
5//! This crate defines the shared vocabulary that every LLM provider implementation
6//! speaks: messages, responses, tool calls, streaming events, usage tracking, and
7//! errors. It intentionally contains **zero** provider-specific code — concrete
8//! providers live in sibling crates and implement [`Provider`] (or its
9//! object-safe counterpart [`DynProvider`]).
10//!
11//! # Provider Crates
12//!
13//! Official provider implementations:
14//!
15//! | Crate | Provider | Features |
16//! |-------|----------|----------|
17//! | [`llm-stack-anthropic`](https://docs.rs/llm-stack-anthropic) | Claude (Anthropic) | Streaming, tools, vision, caching |
18//! | [`llm-stack-openai`](https://docs.rs/llm-stack-openai) | GPT (`OpenAI`) | Streaming, tools, structured output |
19//! | [`llm-stack-ollama`](https://docs.rs/llm-stack-ollama) | Ollama (local) | Streaming, tools |
20//!
21//! # Architecture
22//!
23//! ```text
24//!  ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
25//!  │ llm-stack-anthropic│ │  llm-stack-openai │ │  llm-stack-ollama │
26//!  └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘
27//!            │                     │                     │
28//!            └──────────┬──────────┴──────────┬──────────┘
29//!                       │                     │
30//!                       ▼                     ▼
31//!              ┌─────────────────────────────────────┐
32//!              │             llm-stack               │  ← you are here
33//!              │  (Provider trait, ChatParams, etc.) │
34//!              └─────────────────────────────────────┘
35//! ```
36//!
37//! # Quick start
38//!
39//! ```rust,no_run
40//! use llm_stack::{ChatMessage, ChatParams, Provider};
41//!
42//! # async fn example(provider: impl Provider) -> Result<(), llm_stack::LlmError> {
43//! let params = ChatParams {
44//!     messages: vec![ChatMessage::user("Explain ownership in Rust")],
45//!     max_tokens: Some(1024),
46//!     ..Default::default()
47//! };
48//!
49//! let response = provider.generate(&params).await?;
50//! # Ok(())
51//! # }
52//! ```
53//!
54//! # Modules
55//!
56//! | Module | Purpose |
57//! |--------|---------|
58//! | [`chat`] | Messages, content blocks, tool calls, and responses |
59//! | [`context`] | Token-budgeted conversation history management |
60//! | [`error`] | Unified [`LlmError`] across all providers |
61//! | [`intercept`] | Unified interceptor system for LLM calls and tool executions |
62//! | [`provider`] | The [`Provider`] trait and request parameters |
63//! | [`stream`] | Server-sent event types and the [`ChatStream`] alias |
64//! | [`structured`] | Typed LLM responses with schema validation (feature-gated) |
65//! | [`tool`] | Tool execution engine with registry and approval hooks |
66//! | [`registry`] | Dynamic provider instantiation from configuration |
67//! | [`usage`] | Token counts and cost tracking |
68
69#![warn(missing_docs)]
70
71pub mod chat;
72pub mod context;
73pub mod error;
74pub mod intercept;
75pub mod provider;
76pub mod registry;
77pub mod stream;
78pub mod structured;
79pub mod tool;
80pub mod usage;
81
82pub mod mcp;
83
84#[cfg(any(test, feature = "test-utils"))]
85pub mod mock;
86
87#[cfg(any(test, feature = "test-utils"))]
88pub mod test_helpers;
89
90pub use chat::{
91    ChatMessage, ChatResponse, ChatRole, ContentBlock, ImageSource, StopReason, ToolCall,
92    ToolResult,
93};
94pub use error::LlmError;
95pub use provider::{
96    Capability, ChatParams, DynProvider, JsonSchema, Provider, ProviderMetadata, RetryPredicate,
97    ToolChoice, ToolDefinition, ToolRetryConfig,
98};
99pub use stream::{ChatStream, StreamEvent};
100pub use tool::{
101    FnToolHandler, LoopAction, LoopDepth, LoopDetectionConfig, NoCtxToolHandler, StopConditionFn,
102    StopContext, StopDecision, TerminationReason, ToolApproval, ToolError, ToolHandler,
103    ToolLoopConfig, ToolLoopEvent, ToolLoopResult, ToolOutput, ToolRegistry, tool_fn,
104    tool_fn_with_ctx, tool_loop_channel,
105};
106pub use usage::{Cost, ModelPricing, Usage, UsageTracker};
107
108pub use context::{ContextWindow, estimate_message_tokens, estimate_tokens};
109pub use registry::{ProviderConfig, ProviderFactory, ProviderRegistry};
110
111pub use mcp::{McpError, McpRegistryExt, McpService};
112
113#[cfg(feature = "schema")]
114pub use structured::{
115    GenerateObjectConfig, GenerateObjectResult, PartialObject, collect_stream_object,
116    generate_object, stream_object_async,
117};
118
119#[cfg(any(test, feature = "test-utils"))]
120pub use mock::{MockError, MockProvider};
llm_stack/lib.rs

llm_stack/
lib.rs
