providers_kit/lib.rs
1//! Portable provider resources with exact model selection.
2//!
3//! The hierarchy is [`Provider`] → [`Model`] → [`Session`]. Import
4//! [`ProviderBackend`], [`ModelBackend`], and [`SessionBackend`] to call behavior
5//! on supplied handles. Caller implementations use these traits directly with
6//! their own associated children; no normalization constructor is required.
7//!
8//! [`config`] owns credentials and transport settings; [`models`] owns exact
9//! model identity and discovery. Requests and returned values live in
10//! [`generation`], [`embedding`], [`files`], [`batch`], [`hosted`], and [`session`].
11//! Inspect typed failures through [`error`] and health results through [`runtime`].
12//!
13//! Provider and Model clones share shutdown. Sessions are unique and close by
14//! consumption. Keep the runtime driven until accepted cleanup settles.
15//!
16//! # Local construction
17//!
18//! Creating a provider and selecting an exact model performs no service request:
19//!
20//! ```
21//! # #[tokio::main(flavor = "current_thread")]
22//! # async fn main() -> Result<(), providers_kit::KitError> {
23//! use providers_kit::{Provider, ProviderBackend, ProviderConfig, ModelBackend, ModelId};
24//! use providers_kit::config::{ProviderKind, OllamaConfig, TransportConfig};
25//! let provider = Provider::from_config(ProviderConfig::new(
26//! ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default(),
27//! ))?;
28//! let model = provider.model(ModelId::new("exact-local-model-id")?)?;
29//! assert_eq!(model.model_id().as_str(), "exact-local-model-id");
30//! provider.shutdown().await?;
31//! # Ok(())
32//! # }
33//! ```
34//!
35//! # Generation
36//!
37//! This example requires a running Ollama service with the exact model installed.
38//! Selection does not fall back or prove availability; the operation is authoritative.
39//!
40//! ```no_run
41//! # #[tokio::main(flavor = "current_thread")]
42//! # async fn main() -> Result<(), providers_kit::KitError> {
43//! use providers_kit::{Provider, ProviderBackend, ProviderConfig, ModelBackend, ModelId};
44//! use providers_kit::config::{ProviderKind, OllamaConfig, TransportConfig};
45//! use providers_kit::generation::{GenerateRequest, Message};
46//! let provider = Provider::from_config(ProviderConfig::new(
47//! ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default(),
48//! ))?;
49//! let result = async {
50//! let model = provider.model(ModelId::new("exact-local-model-id")?)?;
51//! let request = GenerateRequest::new(vec![Message::user_text("Hello")?])?;
52//! model.generate(&request).await
53//! }.await;
54//! let cleanup = provider.shutdown().await;
55//! if let Err(error) = &cleanup {
56//! eprintln!("Cleanup failed: {error}");
57//! }
58//! let response = result?;
59//! cleanup?;
60//! // Preserve response.message unchanged for subsequent function continuation.
61//! let _assistant_message = response.message;
62//! # Ok(())
63//! # }
64//! ```
65//!
66//! # Choose a workflow
67//!
68//! | Audience | Start here |
69//! | --- | --- |
70//! | Application builders | [Generation and exact assistant replay](generation), [embeddings](embedding), [owned files](files), [batch lifecycle](batch), and [interactive Sessions](session) |
71//! | Custom-backend implementers | The complete local hierarchy on [`ProviderBackend`], then the sessionless [`ModelBackend`] companion |
72//!
73//! The supplied Session dispatcher supports **OpenAI only**. Supplied Gemini,
74//! Anthropic and Ollama Models return Unsupported from `open_session`. Stateless
75//! OpenAI audio input/audio-chat models are also unsupported; this does not remove
76//! OpenAI Realtime Session support. These supplied-backend restrictions do not
77//! constrain an independently implemented [`SessionBackend`].
78//!
79//! The examples demonstrate API use, not current account/model availability or
80//! native qualification. Model ids are exact, and the selected operation decides
81//! whether a requested combination is supported.
82#![doc(html_logo_url = "../assets/ai-kit-logo.png")]
83#![forbid(unsafe_code)]
84
85pub mod batch;
86mod batch_ownership;
87pub mod config;
88mod core;
89pub mod embedding;
90pub mod error;
91pub mod files;
92pub mod generation;
93pub mod hosted;
94pub mod models;
95mod provider;
96mod providers;
97pub mod runtime;
98pub mod session;
99mod transport;
100
101pub use crate::config::ProviderConfig;
102pub use crate::error::KitError;
103pub use crate::models::{Model, ModelBackend, ModelId};
104pub use crate::provider::{Provider, ProviderBackend};
105pub use crate::session::{Session, SessionBackend};