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//! let response = result?;
56//! cleanup?;
57//! // Preserve response.message unchanged for subsequent function continuation.
58//! let _assistant_message = response.message;
59//! # Ok(())
60//! # }
61//! ```
62//!
63//! # Choose a workflow
64//!
65//! | Audience | Start here |
66//! | --- | --- |
67//! | Application builders | [Generation and exact assistant replay](generation), [embeddings](embedding), [owned files](files), [batch lifecycle](batch), and [interactive Sessions](session) |
68//! | Custom-backend implementers | The complete local hierarchy on [`ProviderBackend`], then the sessionless [`ModelBackend`] companion |
69//!
70//! The supplied Session dispatcher supports **OpenAI only**. Supplied Gemini,
71//! Anthropic and Ollama Models return Unsupported from `open_session`. Stateless
72//! OpenAI audio input/audio-chat models are also unsupported; this does not remove
73//! OpenAI Realtime Session support. These supplied-backend restrictions do not
74//! constrain an independently implemented [`SessionBackend`].
75//!
76//! The examples demonstrate API use, not current account/model availability or
77//! native qualification. Model ids are exact, and the selected operation decides
78//! whether a requested combination is supported.
79#![doc(html_logo_url = "../assets/ai-kit-logo.png")]
80#![forbid(unsafe_code)]
81
82pub mod batch;
83mod batch_ownership;
84pub mod config;
85mod core;
86pub mod embedding;
87pub mod error;
88pub mod files;
89pub mod generation;
90pub mod hosted;
91pub mod models;
92mod provider;
93mod providers;
94pub mod runtime;
95pub mod session;
96mod transport;
97
98pub use crate::config::ProviderConfig;
99pub use crate::error::KitError;
100pub use crate::models::{Model, ModelBackend, ModelId};
101pub use crate::provider::{Provider, ProviderBackend};
102pub use crate::session::{Session, SessionBackend};