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, ToolContext, 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(
89//!         &self,
90//!         args: Self::Arguments,
91//!         _cx: ToolContext,
92//!     ) -> aither_core::Result<Self::Res> {
93//!         Ok(ToolResult::text(format!("Weather in {}: 22°C, sunny", args.location)))
94//!     }
95//! }
96//!
97//! // Advertise the tool on a request. The model replies with a ToolCall event;
98//! // executing it is up to the caller (see `aither-agent`).
99//! let request = LLMRequest::new([Message::user("What is the weather in Tokyo?")])
100//!     .with_tool(&WeatherTool);
101//! ```
102//!
103//! See [`llm::tool`] for more details on using tools with language models.
104//!
105//! ### Semantic Search with Embeddings
106//!
107//! ```rust
108//! use aither_core::EmbeddingModel;
109//!
110//! async fn embed_query(
111//!     model: impl EmbeddingModel,
112//!     query: &str,
113//! ) -> aither_core::Result<Vec<f32>> {
114//!     // Compare this against your stored document embeddings with cosine
115//!     // similarity, or hand it to `aither-rag`.
116//!     model.embed(query).await
117//! }
118//! ```
119//!
120//! ### Progressive Image Generation
121//!
122//! ```rust,ignore
123//! use aither_core::{ImageGenerator, image::{Prompt, Size}};
124//! use futures_lite::StreamExt;
125//!
126//! async fn generate_image(generator: impl ImageGenerator) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
127//!     let prompt = Prompt::new("A beautiful sunset over mountains");
128//!     let size = Size::square(1024);
129//!     
130//!     let mut image_stream = generator.create(prompt, size);
131//!     let mut final_image = Vec::new();
132//!     
133//!     // Each iteration gives us a complete image with progressively better quality
134//!     while let Some(image_result) = image_stream.next().await {
135//!         let current_image = image_result?;
136//!         final_image = current_image; // Keep the latest (highest quality) version
137//!         
138//!         // Optional: Display preview of current quality level
139//!         println!("Received image update, {} bytes", final_image.len());
140//!     }
141//!     
142//!     Ok(final_image) // Return the final highest-quality image
143//! }
144//! ```
145//!
146//! ## Modules
147//!
148//! - [`audio`] — text-to-speech and transcription traits.
149//! - [`embedding`] — turn text into dense vectors.
150//! - [`image`] — image generation + editing APIs.
151//! - [`llm`] — request builders, messages, provider traits, reasoning streams.
152//! - [`moderation`] — moderation scoring traits.
153//!
154//!
155
156#![doc(
157    html_logo_url = "https://raw.githubusercontent.com/lexoliu/aither/main/logo.svg",
158    html_favicon_url = "https://raw.githubusercontent.com/lexoliu/aither/main/logo.svg"
159)]
160#![no_std]
161extern crate alloc;
162
163/// Audio generation and transcription.
164///
165/// Contains [`AudioGenerator`] and [`AudioTranscriber`] traits.
166pub mod audio;
167/// Text embeddings.
168pub mod embedding;
169/// Text-to-image generation.
170///
171/// Contains [`ImageGenerator`] trait for creating images from text.
172pub mod image;
173pub mod llm;
174
175/// Content moderation utilities.
176///
177/// Contains traits and types for detecting and handling unsafe or inappropriate content.
178pub mod moderation;
179
180use alloc::string::String;
181
182#[doc(inline)]
183pub use audio::{AudioGenerator, AudioTranscriber};
184#[doc(inline)]
185pub use embedding::EmbeddingModel;
186#[doc(inline)]
187pub use image::ImageGenerator;
188#[doc(inline)]
189pub use llm::LanguageModel;
190#[doc(inline)]
191pub use moderation::Moderation;
192
193/// Result type used throughout the crate.
194///
195/// Type alias for [`anyhow::Result<T>`](anyhow::Result) with [`String`] as default success type.
196pub type Result<T = String> = anyhow::Result<T>;
197
198pub use anyhow::Error;
199
200// Re-export procedural macros
201#[cfg(feature = "derive")]
202pub use crate::llm::tool::tool;
aither_core/lib.rs

aither_core/
lib.rs
