Client API
Complete reference for the Catsu Client class
The Client class is the main interface for interacting with embedding providers through Catsu.
Overview
The Client class provides a unified interface for:
- Generating embeddings (sync and async)
- Listing available models
- Managing API keys and configuration
- Handling retries and timeouts
Quick Reference
from catsu import Client
# Initialize client
client = Client(
verbose=False, # Enable debug logging
max_retries=3, # Retry attempts
timeout=30, # Request timeout (seconds)
api_keys={} # Optional API key dict
)
# Generate embeddings (sync)
response = client.embed(model="voyage-3", input="Text")
# Generate embeddings (async)
response = await client.aembed(model="voyage-3", input="Text")
# List available models
models = client.list_models(provider="voyageai") # Optional filterAvailable Methods
Core Methods
embed()- Generate embeddings (synchronous)aembed()- Generate embeddings (asynchronous)list_models()- List available models
Configuration
- Initialization - Client constructor parameters
- Context Managers - Using
withstatements
Response Structure
All embed() and aembed() methods return an EmbedResponse object:
class EmbedResponse:
embeddings: List[List[float]] # List of embedding vectors
dimensions: int # Embedding dimensions
usage: Usage # Token usage and cost info
class Usage:
tokens: int # Total tokens processed
cost: float # Cost in USD
latency: float # Request latency in secondsExample Usage
import catsu
# Initialize with configuration
client = catsu.Client(
verbose=True,
max_retries=5,
timeout=60
)
# Generate embeddings
response = client.embed(
model="voyage-3",
input=["Query 1", "Query 2"],
input_type="query"
)
# Access results
for i, embedding in enumerate(response.embeddings):
print(f"Embedding {i+1}: {len(embedding)} dimensions")
print(f"Total cost: ${response.usage.cost:.6f}")
print(f"Latency: {response.usage.latency:.3f}s")