aither_core/
lib.rs

1//! # aither
2//!
3//! **Write AI applications that work with any provider** 🚀
4//!
5//! `aither-core` hosts the no-std trait APIs that power the rest of the workspace. Use it directly
6//! (or through the top-level [`aither`](https://crates.io/crates/aither) crate) to describe portable
7//! language models, embeddings, moderation, image/audio generators, and more.
8//! Every provider crate simply implements these traits.
9//!
10//!
11//! ```text
12//! ┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
13//! │   Your App      │───▶│    aither        │◀───│   Providers     │
14//! │                 │    │   (this crate)   │    │                 │
15//! │ - Chat bots     │    │                  │    │ - openai        │
16//! │ - Search        │    │ - LanguageModel  │    │ - anthropic     │
17//! │ - Content gen   │    │ - EmbeddingModel │    │ - llama.cpp     │
18//! │ - Voice apps    │    │ - ImageGenerator │    │ - whisper       │
19//! └─────────────────┘    └──────────────────┘    └─────────────────┘
20//! ```
21
22//!
23//! ## Supported AI Capabilities
24//!
25//! | Capability | Trait | Description |
26//! |------------|-------|-------------|
27//! | **Language Models** | [`LanguageModel`] | Streaming events (text, reasoning, tool calls) |
28//! | **Embeddings** | [`EmbeddingModel`] | Convert text to vectors for semantic search |
29//! | **Image Generation** | [`ImageGenerator`] | Create images with progressive quality improvement |
30//! | **Text-to-Speech** | [`AudioGenerator`] | Generate speech audio from text |
31//! | **Speech-to-Text** | [`AudioTranscriber`] | Transcribe audio to text |
32//! | **Content Moderation** | [`Moderation`] | Detect policy violations with confidence scores |
33//!
34//! ## Examples
35//!
36//! ### Streaming Responses with Events
37//!
38//! ```rust,ignore
39//! use aither_core::llm::{LanguageModel, Event, Message, LLMRequest, model::Parameters};
40//! use futures_lite::StreamExt;
41//!
42//! async fn event_demo(model: impl LanguageModel) -> aither_core::Result {
43//!     let request = LLMRequest::new([
44//!         Message::user("Explain how rainbows form like I'm five."),
45//!     ])
46//!     .with_parameters(Parameters::default().include_reasoning(true));
47//!
48//!     let mut stream = model.respond(request);
49//!     let mut answer = String::new();
50//!
51//!     while let Some(event) = stream.next().await {
52//!         match event? {
53//!             Event::Text(text) => answer.push_str(&text),
54//!             Event::Reasoning(thought) => println!("thinking: {}", thought),
55//!             Event::ToolCall(call) => println!("tool requested: {}", call.name),
56//!             _ => {}
57//!         }
58//!     }
59//!     Ok(answer)
60//! }
61//! ```
62//!
63//! ### Structured Output with Tools
64//!
65//! ```rust
66//! use aither_core::llm::{LLMRequest, Message, Tool, ToolResult};
67//! use schemars::JsonSchema;
68//! use serde::Deserialize;
69//! use std::borrow::Cow;
70//!
71//! /// Get current weather for a location.
72//! #[derive(JsonSchema, Deserialize)]
73//! struct WeatherQuery {
74//!     /// City to report on, e.g. "Tokyo".
75//!     location: String,
76//! }
77//!
78//! struct WeatherTool;
79//!
80//! impl Tool for WeatherTool {
81//!     fn name(&self) -> Cow<'static, str> {
82//!         Cow::Borrowed("get_weather")
83//!     }
84//!
85//!     type Arguments = WeatherQuery;
86//!     type Res = ToolResult;
87//!
88//!     async fn call(&self, args: Self::Arguments) -> aither_core::Result<Self::Res> {
89//!         Ok(ToolResult::text(format!("Weather in {}: 22°C, sunny", args.location)))
90//!     }
91//! }
92//!
93//! // Advertise the tool on a request. The model replies with a ToolCall event;
94//! // executing it is up to the caller (see `aither-agent`).
95//! let request = LLMRequest::new([Message::user("What is the weather in Tokyo?")])
96//!     .with_tool(&WeatherTool);
97//! ```
98//!
99//! See [`llm::tool`] for more details on using tools with language models.
100//!
101//! ### Semantic Search with Embeddings
102//!
103//! ```rust
104//! use aither_core::EmbeddingModel;
105//!
106//! async fn embed_query(
107//!     model: impl EmbeddingModel,
108//!     query: &str,
109//! ) -> aither_core::Result<Vec<f32>> {
110//!     // Compare this against your stored document embeddings with cosine
111//!     // similarity, or hand it to `aither-rag`.
112//!     model.embed(query).await
113//! }
114//! ```
115//!
116//! ### Progressive Image Generation
117//!
118//! ```rust,ignore
119//! use aither_core::{ImageGenerator, image::{Prompt, Size}};
120//! use futures_lite::StreamExt;
121//!
122//! async fn generate_image(generator: impl ImageGenerator) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
123//!     let prompt = Prompt::new("A beautiful sunset over mountains");
124//!     let size = Size::square(1024);
125//!     
126//!     let mut image_stream = generator.create(prompt, size);
127//!     let mut final_image = Vec::new();
128//!     
129//!     // Each iteration gives us a complete image with progressively better quality
130//!     while let Some(image_result) = image_stream.next().await {
131//!         let current_image = image_result?;
132//!         final_image = current_image; // Keep the latest (highest quality) version
133//!         
134//!         // Optional: Display preview of current quality level
135//!         println!("Received image update, {} bytes", final_image.len());
136//!     }
137//!     
138//!     Ok(final_image) // Return the final highest-quality image
139//! }
140//! ```
141//!
142//! ## Modules
143//!
144//! - [`audio`] — text-to-speech and transcription traits.
145//! - [`embedding`] — turn text into dense vectors.
146//! - [`image`] — image generation + editing APIs.
147//! - [`llm`] — request builders, messages, provider traits, reasoning streams.
148//! - [`moderation`] — moderation scoring traits.
149//!
150//!
151
152#![doc(
153    html_logo_url = "https://raw.githubusercontent.com/lexoliu/aither/main/logo.svg",
154    html_favicon_url = "https://raw.githubusercontent.com/lexoliu/aither/main/logo.svg"
155)]
156#![no_std]
157extern crate alloc;
158
159/// Audio generation and transcription.
160///
161/// Contains [`AudioGenerator`] and [`AudioTranscriber`] traits.
162pub mod audio;
163/// Text embeddings.
164pub mod embedding;
165/// Text-to-image generation.
166///
167/// Contains [`ImageGenerator`] trait for creating images from text.
168pub mod image;
169pub mod llm;
170
171/// Content moderation utilities.
172///
173/// Contains traits and types for detecting and handling unsafe or inappropriate content.
174pub mod moderation;
175
176use alloc::string::String;
177
178#[doc(inline)]
179pub use audio::{AudioGenerator, AudioTranscriber};
180#[doc(inline)]
181pub use embedding::EmbeddingModel;
182#[doc(inline)]
183pub use image::ImageGenerator;
184#[doc(inline)]
185pub use llm::LanguageModel;
186#[doc(inline)]
187pub use moderation::Moderation;
188
189/// Result type used throughout the crate.
190///
191/// Type alias for [`anyhow::Result<T>`](anyhow::Result) with [`String`] as default success type.
192pub type Result<T = String> = anyhow::Result<T>;
193
194pub use anyhow::Error;
195
196// Re-export procedural macros
197#[cfg(feature = "derive")]
198pub use crate::llm::tool::tool;
aither_core/lib.rs

aither_core/
lib.rs
