iron_providers/
lib.rs

1#![warn(
2    rustdoc::broken_intra_doc_links,
3    rustdoc::private_intra_doc_links,
4    rustdoc::redundant_explicit_links
5)]
6//! iron-providers: Semantic provider boundary for protocol-oriented LLM providers
7//!
8//! This crate provides a function-oriented provider API that normalizes
9//! inference requests and responses across different LLM backends.
10//! Supports Responses, Chat Completions, and Messages protocol families via a
11//! profile-driven provider connection and registry.
12//!
13//! # Architecture
14//!
15//! The crate is organized around a few core concepts:
16//!
17//! - **[`Provider`] trait**: The async interface for performing inference.
18//!   Callers use [`Provider::infer`] for non-streaming and
19//!   [`Provider::infer_stream`] for streaming requests.
20//!
21//! - **[`InferenceRequest`]**: The normalized request type carrying model ID,
22//!   instructions, tools, and an [`InferenceContext`].
23//!
24//! - **[`InferenceContext`]**: Separates model-visible conversation
25//!   ([`Transcript`]) from runtime-only records ([`RuntimeRecord`]).
26//!   Provider adapters project only the transcript into model-visible request
27//!   fields. Runtime records may influence request assembly through explicit
28//!   provider-specific mapping logic but are never replayed as assistant text.
29//!
30//! - **[`ProviderEvent`]**: Normalized streaming events. The stream
31//!   termination contract is:
32//!   - [`ProviderEvent::Complete`] is emitted **only** on successful stream
33//!     termination.
34//!   - If a provider encounters an unrecoverable error, the stream ends with
35//!     [`ProviderEvent::Error`] and does **not** emit `Complete`.
36//!
37//! - **[`ProviderProfile`]**: Declarative provider configuration including
38//!   API family, base URL, auth strategy, default headers, and quirks.
39//!   All provider families (Responses, Chat Completions, Messages)
40//!   honor the full profile model consistently.
41//!
42//! - **[`ProviderConnection`]**: Resolved provider state that implements
43//!   [`Provider`]. Construct directly from a [`ProviderProfile`] and
44//!   [`RuntimeConfig`], or obtain from [`ProviderRegistry::get`].
45//!
46//! - **[`ProviderRegistry`]**: Registry for looking up providers by slug or
47//!   URL pattern, with built-in profiles for common providers. Includes
48//!   `local` for OpenAI-compatible local endpoints (Ollama, LM Studio, etc.)
49//!   via `/v1/chat/completions`, `ollama-cloud` for the Ollama cloud API, and
50//!   `openai` for public OpenAI Responses API-key access.
51//!
52//! # Streaming
53//!
54//! Streaming is determined by which method you call (`infer` vs `infer_stream`),
55//! not by a field on the request. There is no `stream` field on
56//! [`InferenceRequest`].
57
58pub mod connection;
59pub mod error;
60pub mod model;
61pub mod profile;
62pub mod provider;
63pub mod registry;
64
65pub(crate) mod apis;
66pub(crate) mod auth;
67pub(crate) mod http_client;
68pub(crate) mod provider_overrides;
69pub(crate) mod sse;
70pub(crate) mod stream_util;
71
72#[cfg(test)]
73mod mock_provider_tests;
74
75pub use connection::ProviderConnection;
76pub use error::{ProviderError, ProviderResult};
77pub use model::{
78    ChoiceItem, ChoiceRequest, ChoiceSelectionMode, GenerationConfig, InferenceContext,
79    InferenceRequest, Message, ProviderEvent, RuntimeRecord, TokenUsage, ToolCall, ToolDefinition,
80    ToolPolicy, Transcript, CHOICE_REQUEST_TOOL_NAME,
81};
82pub use profile::{
83    ApiFamily, AuthStrategy, CredentialAuthConfig, CredentialKind, EndpointPurpose,
84    ProviderCredential, ProviderProfile, ProviderQuirks, RuntimeConfig, RuntimeConfigSource,
85};
86pub use provider::{Provider, ProviderFuture};
87pub use registry::ProviderRegistry;
88
89pub mod prelude {
90    pub use crate::{
91        ApiFamily, AuthStrategy, ChoiceItem, ChoiceRequest, ChoiceSelectionMode, CredentialKind,
92        EndpointPurpose, GenerationConfig, InferenceContext, InferenceRequest, Message, Provider,
93        ProviderCredential, ProviderError, ProviderEvent, ProviderProfile, ProviderRegistry,
94        ProviderResult, RuntimeConfig, RuntimeConfigSource, RuntimeRecord, TokenUsage, ToolCall,
95        ToolDefinition, ToolPolicy, Transcript, CHOICE_REQUEST_TOOL_NAME,
96    };
97}
iron_providers/lib.rs

iron_providers/
lib.rs
