xz-provider 0.5.0

LLM 服务提供者抽象层 — 统一的 LLM 服务提供者接口
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

// Allow unwrap/expect in test code — `.unwrap()` in tests is acceptable
// as per project policy (AGENTS.md §Agent Pre-Commit Enforcement).
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]

//! # xz-provider
//!
//! LLM service-provider abstraction — the HTTP + protocol layer for model calls.
//!
//! ## Minimal surface
//!
//! | Item | Role |
//! |------|------|
//! | [`LlmProvider`] | Trait: `complete` / `complete_stream` |
//! | [`GenericProvider`] | Sole HTTP client; uses a [`ProtocolAdapter`] |
//! | [`ProviderBuilder`] | Config → router of providers |
//! | [`CompletionRequest`] / [`CompletionResponse`] / [`StreamEvent`] | Data plane |
//! | [`RequestOptions`] | Control plane (timeout, cancel) |
//! | [`ProviderError`] | Errors |
//!
//! Protocol adapters live under [`protocol`]. Advanced routing / layers under
//! [`router`] and [`layer`]. Prefer `use xz_provider::types::…` for niche
//! types (thinking blocks, citations, …).
//!
//! ## Quick start
//!
//! ```rust,no_run
//! use xz_provider::{ProviderBuilder, ProviderConfig, LlmProvider};
//!
//! # async fn example() {
//! let router = ProviderBuilder::new()
//!     .with_config(ProviderConfig::from_json(r#"{
//!         "default_model": "gpt-4o",
//!         "providers": {
//!             "openai": {
//!                 "provider_type": "open_ai",
//!                 "api_key": "sk-xxx",
//!                 "models": [{"name": "gpt-4o", "capabilities": {"context_window": 128000, "max_output_tokens": 4096}}]
//!             }
//!         },
//!         "routing": {}
//!     }"#).unwrap())
//!     .build().await.unwrap();
//!
//! let resp = router.complete(
//!     &xz_provider::RouteContext::default(),
//!     xz_provider::CompletionRequest::new("gpt-4o", vec![
//!         xz_provider::Message::user("Hello!"),
//!     ]),
//!     xz_provider::RequestOptions::default(),
//! ).await.unwrap();
//! # }
//! ```

pub mod accumulator;
pub mod builder;
pub mod cancel;
pub mod config;
pub mod error;
pub mod http;
pub mod key_source;
pub mod layer;
pub mod observability;
pub mod protocol;
pub mod providers;
pub mod router;
pub mod traits;
pub mod types;

// ── Core public API (prefer these) ─────────────────────────────────────────
pub use builder::ProviderBuilder;
pub use cancel::CancellationToken;
pub use config::{ApiProtocol, ProviderConfig, ProviderDefinition, ProviderType};
pub use error::{ProviderError, RetryStrategy};
pub use protocol::{AuthMethod, ProtocolAdapter};
pub use providers::GenericProvider;
pub use router::{ProviderRouter, RouteContext, RouteDecision};
pub use traits::LlmProvider;
pub use types::{
    CompletionRequest, CompletionResponse, FinishReason, Message, MessageContent, ModelInfo,
    RequestOptions, StreamEvent, TokenUsage, ToolCall, ToolChoice, ToolDefinition, ToolResult,
};

// ── Extended re-exports (also available via modules) ───────────────────────
pub use accumulator::ToolCallAccumulator;
pub use config::{
    ConfigWatcher, FallbackCondition as ConfigFallbackCondition,
    FallbackEntry as ConfigFallbackEntry, ModelConfig, RouteRule,
};
pub use key_source::KeySource;
pub use layer::{
    LayerService, Layered as ProviderLayered, ProviderLayer, RetryLayer, TelemetryLayer,
};
pub use router::{
    CostPreference, FallbackCondition, FallbackEntry, HealthState, LatencyTracker,
};
pub use types::{
    CacheControl, CacheInfo, CapabilityRequest, Citation, CitationConfig, ContentPart, EffortLevel,
    ImageDetail, Modality, ModelCapabilities, ModelLimits, ModelPricing, OutputConfig,
    ReasoningEffort, RedactedThinkingBlock, ResponseFormat, ServiceTier, ThinkingBlock,
    ThinkingConfig, ThinkingDisplay, ThinkingType,
};

#[cfg(test)]
mod test_sse;