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
- Handling retries and timeouts
Quick Reference
from catsu import Client
# Initialize client
client = Client(
max_retries=3, # Retry attempts (default: 3)
timeout=30, # Request timeout in seconds (default: 30)
)
# Generate embeddings (sync)
response = client.embed("openai:text-embedding-3-small", ["Text"])
# Generate embeddings (async)
response = await client.aembed("openai:text-embedding-3-small", ["Text"])
# List available models
models = client.list_models("openai") # Optional provider 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 info
class Usage:
tokens: int # Total tokens processedExample Usage
from catsu import Client
# Initialize with configuration
client = Client(
max_retries=5,
timeout=60
)
# Generate embeddings
response = client.embed(
"voyageai:voyage-3",
["Query 1", "Query 2"],
input_type="query"
)
# Access results
for i, embedding in enumerate(response.embeddings):
print(f"Embedding {i+1}: {len(embedding)} dimensions")
# Convert to numpy
arr = response.to_numpy()
print(arr.shape) # (2, 1024)