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
90// ── Core re-exports ────────────────────────────────────────────────
91//
92// Only the types that appear in nearly every program are re-exported
93// at the crate root. Everything else lives in its submodule:
94//
95//   llm_stack::tool::*        — tool execution, loop handles, events
96//   llm_stack::provider::*    — capabilities, metadata, retry config
97//   llm_stack::chat::*        — StopReason, ImageSource, ChatRole
98//   llm_stack::stream::*      — ChatStream, StreamEvent
99//   llm_stack::usage::*       — Cost, ModelPricing, UsageTracker
100//   llm_stack::context::*     — ContextWindow, token estimation
101//   llm_stack::registry::*    — ProviderRegistry, ProviderFactory
102//   llm_stack::mcp::*         — McpService, McpRegistryExt
103//   llm_stack::structured::*  — generate_object, stream_object_async
104//   llm_stack::mock::*        — MockProvider (test-utils feature)
105
106pub use chat::{ChatMessage, ChatResponse, ContentBlock, ToolCall, ToolResult};
107pub use error::LlmError;
108pub use provider::{ChatParams, DynProvider, JsonSchema, Provider, ToolChoice, ToolDefinition};
109pub use registry::ProviderRegistry;
110pub use stream::{ChatStream, StreamEvent};
111pub use tool::{ToolHandler, ToolLoopConfig, ToolRegistry};
112pub use usage::Usage;
llm_stack/lib.rs

llm_stack/
lib.rs
