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    Completed, FnToolHandler, LoopAction, LoopCommand, LoopContext, LoopDepth, LoopDetectionConfig,
102    LoopEvent, LoopStream, NoCtxToolHandler, OwnedToolLoopHandle, OwnedTurnResult, OwnedYielded,
103    StopConditionFn, StopContext, StopDecision, TerminationReason, ToolApproval, ToolError,
104    ToolHandler, ToolLoopConfig, ToolLoopHandle, ToolLoopResult, ToolOutput, ToolRegistry,
105    TurnError, TurnResult, Yielded, tool_fn, tool_fn_with_ctx,
106};
107pub use usage::{Cost, ModelPricing, Usage, UsageTracker};
108
109pub use context::{ContextWindow, estimate_message_tokens, estimate_tokens};
110pub use registry::{ProviderConfig, ProviderFactory, ProviderRegistry};
111
112pub use mcp::{McpError, McpRegistryExt, McpService};
113
114#[cfg(feature = "schema")]
115pub use structured::{
116    GenerateObjectConfig, GenerateObjectResult, PartialObject, collect_stream_object,
117    generate_object, stream_object_async,
118};
119
120#[cfg(any(test, feature = "test-utils"))]
121pub use mock::{MockError, MockProvider};
llm_stack/lib.rs

llm_stack/
lib.rs
