xz_provider/
lib.rs

1// Allow unwrap/expect in test code — `.unwrap()` in tests is acceptable
2// as per project policy (AGENTS.md §Agent Pre-Commit Enforcement).
3#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
4
5//! # xz-provider
6//!
7//! LLM service-provider abstraction — the HTTP + protocol layer for model calls.
8//!
9//! ## Minimal surface
10//!
11//! | Item | Role |
12//! |------|------|
13//! | [`LlmProvider`] | Trait: `complete` / `complete_stream` |
14//! | [`GenericProvider`] | Sole HTTP client; uses a [`ProtocolAdapter`] |
15//! | [`ProviderBuilder`] | Config → router of providers |
16//! | [`CompletionRequest`] / [`CompletionResponse`] / [`StreamEvent`] | Data plane |
17//! | [`RequestOptions`] | Control plane (timeout, cancel) |
18//! | [`ProviderError`] | Errors |
19//!
20//! Protocol adapters live under [`protocol`]. Advanced routing / layers under
21//! [`router`] and [`layer`]. Prefer `use xz_provider::types::…` for niche
22//! types (thinking blocks, citations, …).
23//!
24//! ## Quick start
25//!
26//! ```rust,no_run
27//! use xz_provider::{ProviderBuilder, ProviderConfig, LlmProvider};
28//!
29//! # async fn example() {
30//! let router = ProviderBuilder::new()
31//!     .with_config(ProviderConfig::from_json(r#"{
32//!         "default_model": "gpt-4o",
33//!         "providers": {
34//!             "openai": {
35//!                 "provider_type": "open_ai",
36//!                 "api_key": "sk-xxx",
37//!                 "models": [{"name": "gpt-4o", "capabilities": {"context_window": 128000, "max_output_tokens": 4096}}]
38//!             }
39//!         },
40//!         "routing": {}
41//!     }"#).unwrap())
42//!     .build().await.unwrap();
43//!
44//! let resp = router.complete(
45//!     &xz_provider::RouteContext::default(),
46//!     xz_provider::CompletionRequest::new("gpt-4o", vec![
47//!         xz_provider::Message::user("Hello!"),
48//!     ]),
49//!     xz_provider::RequestOptions::default(),
50//! ).await.unwrap();
51//! # }
52//! ```
53
54pub mod accumulator;
55pub mod builder;
56pub mod cancel;
57pub mod config;
58pub mod error;
59pub mod http;
60pub mod key_source;
61pub mod layer;
62pub mod observability;
63pub mod protocol;
64pub mod providers;
65pub mod router;
66pub mod traits;
67pub mod types;
68
69// ── Core public API (prefer these) ─────────────────────────────────────────
70pub use builder::ProviderBuilder;
71pub use cancel::CancellationToken;
72pub use config::{ApiProtocol, ProviderConfig, ProviderDefinition, ProviderType};
73pub use error::{ProviderError, RetryStrategy};
74pub use protocol::{AuthMethod, ProtocolAdapter};
75pub use providers::GenericProvider;
76pub use router::{ProviderRouter, RouteContext, RouteDecision};
77pub use traits::LlmProvider;
78pub use types::{
79    CompletionRequest, CompletionResponse, FinishReason, Message, MessageContent, ModelInfo,
80    RequestOptions, StreamEvent, TokenUsage, ToolCall, ToolChoice, ToolDefinition, ToolResult,
81};
82
83// ── Extended re-exports (also available via modules) ───────────────────────
84pub use accumulator::ToolCallAccumulator;
85pub use config::{
86    ConfigWatcher, FallbackCondition as ConfigFallbackCondition,
87    FallbackEntry as ConfigFallbackEntry, ModelConfig, RouteRule,
88};
89pub use key_source::KeySource;
90pub use layer::{
91    LayerService, Layered as ProviderLayered, ProviderLayer, RetryLayer, TelemetryLayer,
92};
93pub use router::{
94    CostPreference, FallbackCondition, FallbackEntry, HealthState, LatencyTracker,
95};
96pub use types::{
97    CacheControl, CacheInfo, CapabilityRequest, Citation, CitationConfig, ContentPart, EffortLevel,
98    ImageDetail, Modality, ModelCapabilities, ModelLimits, ModelPricing, OutputConfig,
99    ReasoningEffort, RedactedThinkingBlock, ResponseFormat, ServiceTier, ThinkingBlock,
100    ThinkingConfig, ThinkingDisplay, ThinkingType,
101};
102
103#[cfg(test)]
104mod test_sse;
xz_provider/lib.rs

xz_provider/
lib.rs
