Alchemy

A unified LLM API abstraction layer in Rust that supports 8+ providers through a consistent interface.

Alchemy-rs

Heavily inspired by and ported from: pi-mono/packages/ai by @badlogic

Supported Providers

Anthropic (Claude)
OpenAI (GPT-4, GPT-3.5)
Google (Gemini)
AWS Bedrock
Mistral
xAI (Grok)
Groq
Cerebras
OpenRouter

Features

Streaming-first - All providers use async streams
Type-safe - Leverages Rust's type system
Provider-agnostic - Switch providers without code changes
Tool calling - Function/tool support across providers
Message transformation - Cross-provider message compatibility

Quick Start

use alchemy::{stream, types::*};
use futures::StreamExt;

#[tokio::main]
async fn main() -> alchemy::Result<()> {
    let model = alchemy::get_model("claude-sonnet-4-20250514")
        .ok_or("Model not found")?;

    let context = Context {
        messages: vec![Message::user("Hello, Claude!")],
        ..Default::default()
    };

    let mut stream = stream(&model, &context, &[])?;

    while let Some(event) = stream.next().await {
        println!("{:?}", event);
    }

    Ok(())
}

Setup

Clone the repository

git clone https://github.com/alchemiststudiosDOTai/alchemy-rs.git
cd alchemy-rs

Configure API keys

cp .env.example .env
# Edit .env and add your API keys

Build the project
```
cargo build
```
Run tests
```
cargo test
```
Run the example
```
cargo run --example api_lifecycle
```

Development

See AGENTS.md for detailed development guidelines, architecture, and quality gates.

Quality Checks

Pre-commit hooks automatically run:

cargo fmt - Code formatting
cargo clippy - Linting with complexity checks
cargo check - Compilation

Run all quality checks:

make quality-full     # All checks including complexity and duplicates
make quality-quick    # Fast checks (fmt, clippy, check)
make complexity       # Cyclomatic complexity analysis
make duplicates       # Duplicate code detection

Or run individually:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo check --all-targets --all-features

Tools used:

Clippy - Cognitive complexity warnings (threshold: 20)
polydup - Duplicate code detection (install: cargo install polydup-cli)

License

MIT

alchemy-llm 0.1.1