Quick Start

from catsu import Client

# Initialize the client (reads API keys from environment)
client = Client()

# Generate embeddings using provider:model format
response = client.embed(
    "openai:text-embedding-3-small",
    ["Hello, world!"]
)

# Access embeddings
print(response.embeddings)      # [[0.1, 0.2, 0.3, ...]]
print(response.dimensions)      # 1536

# Check usage
print(response.usage.tokens)    # 2

# Batch processing (more efficient)
response = client.embed(
    "openai:text-embedding-3-small",
    ["Text 1", "Text 2", "Text 3"]
)

# Results include all embeddings
print(len(response.embeddings))  # 3
print(response.usage.tokens)     # Total tokens for all inputs

# You can also pass a single string
response = client.embed(
    "openai:text-embedding-3-small",
    "Hello, world!"
)

import asyncio
from catsu import Client

async def main():
    client = Client()

    # Single async request
    response = await client.aembed(
        "openai:text-embedding-3-small",
        "Hello, async world!"
    )

    # Parallel requests
    responses = await asyncio.gather(
        client.aembed("openai:text-embedding-3-small", "Query 1"),
        client.aembed("openai:text-embedding-3-small", "Query 2"),
        client.aembed("openai:text-embedding-3-small", "Query 3"),
    )

    print(f"Processed {len(responses)} requests in parallel")

asyncio.run(main())

# Sync context manager
with Client() as client:
    response = client.embed("openai:text-embedding-3-small", "Hello!")
    print(response.embeddings)

# Async context manager
async with Client() as client:
    response = await client.aembed("openai:text-embedding-3-small", "Hello!")
    print(response.embeddings)

# With input_type (for search optimization)
response = client.embed(
    "voyageai:voyage-3",
    ["What is machine learning?"],
    input_type="query"  # or "document"
)

# With custom dimensions (Matryoshka embeddings)
response = client.embed(
    "openai:text-embedding-3-small",
    ["Sample text"],
    dimensions=256
)

response = client.embed(
    "openai:text-embedding-3-small",
    ["Text 1", "Text 2"]
)

# Convert to numpy array
arr = response.to_numpy()
print(arr.shape)  # (2, 1536)

# List all models
models = client.list_models()

# Filter by provider
openai_models = client.list_models("openai")
for m in openai_models:
    print(f"{m.name}: {m.dimensions} dims")