catsu 0.0.1a0

🐱 The embedding client that always lands on its feet 🚀

🌐 catsu 🐱

A unified, batteries-included client for embedding APIs that actually works.

The world of embedding API clients is broken.

• 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 lightweight, 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
⚠️ Proper error handling and type hints
⚡ First-class support for both sync and async

📦 Install

Install with pip:

pip install catsu

Or with uv (recommended):

uv pip install catsu

🚀 Quick Start

Get started in seconds! Just import catsu, create a client, and start embedding:

import catsu

# Initialize the client
client = catsu.Client()

# Generate embeddings (auto-detects provider from model name)
response = client.embed(
    model="voyage-3",
    input="Hello, embeddings!"
)

# Access your results
print(f"Dimensions: {response.dimensions}")
print(f"Tokens used: {response.usage.tokens}")
print(f"Cost: ${response.usage.cost:.6f}")
print(f"Embedding: {response.embeddings[0][:5]}...")  # First 5 dims

That's it! No configuration needed—catsu picks up your API keys from environment variables automatically (VOYAGE_API_KEY, OPENAI_API_KEY, etc.).

Want more control? Specify the provider explicitly:

# Method 1: Separate parameters
response = client.embed(provider="voyageai", model="voyage-3", input="Hello!")

# Method 2: Provider prefix
response = client.embed(model="voyageai:voyage-3", input="Hello!")

Need async? Just use aembed:

response = await client.aembed(model="voyage-3", input="Hello, async world!")