The world of embedding API clients is broken. (details)

• Everyone defaults to OpenAI's client for embeddings, even though it wasn't designed for that purpose
• Provider-specific libraries (VoyageAI, Cohere, etc.) are inconsistent, poorly maintained, or outright broken
• Universal clients like LiteLLM and any-llm-sdk don't focus on embeddings at all—they rely on native client libraries, inheriting all their problems
• Every provider has different capabilities—some support dimension changes, others don't—with no standardized way to discover what's available
• Most clients lack basic features like retry logic, proper error handling, and usage tracking
• There's no single source of truth for model metadata, pricing, or capabilities

Catsu fixes this. It's a high-performance, unified client built specifically for embeddings with:

🎯 A clean, consistent API across all providers
🔄 Built-in retry logic with exponential backoff
💰 Automatic usage and cost tracking
📚 Rich model metadata and capability discovery
⚡ Rust core with Python bindings for maximum performance

📦 Rust

Add to your Cargo.toml:

[dependencies]
catsu = "0.1"
tokio = { version = "1", features = ["full"] }

Quick Start

use catsu::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client (reads API keys from environment)
    let client = Client::new()?;

    // Generate embeddings
    let response = client.embed(
        "openai:text-embedding-3-small",
        vec!["Hello, world!".to_string(), "How are you?".to_string()],
    ).await?;

    println!("Dimensions: {}", response.dimensions);
    println!("Tokens used: {}", response.usage.tokens);
    println!("Embedding: {:?}", &response.embeddings[0][..5]);

    Ok(())
}

With Options

use catsu::{Client, InputType};

let response = client.embed_with_options(
    "openai:text-embedding-3-small",
    vec!["Search query".to_string()],
    Some(InputType::Query),  // input type hint
    Some(256),               // output dimensions
).await?;

Model Catalog

// List all available models
let models = client.list_models(None);

// Filter by provider
let openai_models = client.list_models(Some("openai"));
for model in openai_models {
    println!("{}: {} dims", model.name, model.dimensions);
}

🐍 Python

Looking for Python? See the Python documentation.

pip install catsu

from catsu import Client

client = Client()
response = client.embed("openai:text-embedding-3-small", ["Hello, world!"])
print(f"Dimensions: {response.dimensions}")

🤝 Contributing

Can't find your favorite model or provider? Open an issue and we'll add it!

For guidelines on contributing, see CONTRIBUTING.md.