ailloy 0.3.1

Ailloy provides a unified interface for interacting with multiple AI providers from Rust — both as a CLI tool for quick tasks and scripting, and as a library for integration into your own projects.

Quick Start

Install the CLI

# Homebrew (macOS/Linux)
brew install mklab-se/tap/ailloy

# Cargo
cargo install ailloy

# Cargo binstall (pre-built binary)
cargo binstall ailloy

Configure a provider

ailloy config

Send a message

ailloy "Explain the Rust borrow checker in one sentence"

Use as a Library

Add ailloy to your project without CLI dependencies:

[dependencies]
ailloy = { version = "0.2", default-features = false }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
anyhow = "1"

Async (recommended)

use ailloy::{Client, Message};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::from_config()?;
    let response = client.chat(&[Message::user("Hello!")]).await?;
    println!("{}", response.content);
    Ok(())
}

Blocking (sync)

use ailloy::blocking::Client;
use ailloy::Message;

fn main() -> anyhow::Result<()> {
    let client = Client::from_config()?;
    let response = client.chat(&[Message::user("Hello!")])?;
    println!("{}", response.content);
    Ok(())
}

Programmatic (no config file needed)

use ailloy::{Client, Message};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::openai("sk-...", "gpt-4o")?;
    let response = client.chat(&[Message::user("Hello!")]).await?;
    println!("{}", response.content);
    Ok(())
}

Builder pattern

use ailloy::{Client, Message};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::builder()
        .anthropic()
        .api_key("sk-ant-...")
        .model("claude-sonnet-4-6")
        .build()?;
    let response = client.chat(&[Message::user("Hello!")]).await?;
    println!("{}", response.content);
    Ok(())
}

Providers

Configuration

Ailloy stores its configuration at ~/.config/ailloy/config.yaml:

defaults:
  chat: openai
  image: dalle
providers:
  openai:
    kind: open-ai
    api_key: sk-...
    model: gpt-4o
  anthropic:
    kind: anthropic
    api_key: sk-ant-...
    model: claude-sonnet-4-6
  dalle:
    kind: open-ai
    api_key: sk-...
    model: dall-e-3
    task: image-generation
  ollama:
    kind: ollama
    model: llama3.2
  claude:
    kind: local-agent
    binary: claude

Local project config

Create .ailloy.yaml in your project root to override or add providers for that project. Local config is merged with global config.

CLI Commands

Options

ailloy "message" --provider ollama       # Use a specific provider
ailloy "message" --system "Be brief"     # Set a system prompt
ailloy "message" --stream                # Stream response tokens
ailloy "message" --max-tokens 100        # Limit response length
ailloy "message" --temperature 0.7       # Control randomness
ailloy "message" -o response.txt         # Save response to file
ailloy "message" -o image.png            # Generate an image
ailloy "message" -o diagram.svg          # Generate SVG via chat
echo "prompt" | ailloy                   # Pipe input via stdin
ailloy -v chat "message"                 # Debug logging
ailloy -q chat "message"                 # Quiet mode

Feature Flags

Ailloy uses feature flags to keep the library lean:

Library users should disable default features:

ailloy = { version = "0.2", default-features = false }

Development

cargo build                              # Build everything
cargo build --no-default-features --lib  # Build library only
cargo test                               # Run tests
cargo clippy -- -D warnings              # Lint (zero warnings)
cargo fmt --all -- --check               # Format check
cargo run -- chat "hello"                # Run the CLI

License

MIT