Getting Started

Chimeric provides a unified interface for accessing multiple LLM providers through a single, consistent API. This guide demonstrates fundamental concepts and usage patterns to get you productive quickly.

Prerequisites

• Python 3.11 or higher
• API keys for your chosen providers
• Basic familiarity with async/await patterns (for async usage)

Core Concepts

Automatic Provider Detection

Chimeric intelligently routes requests based on model names, eliminating the need for manual provider selection:

from chimeric import Chimeric

client = Chimeric()  # Auto-detects available providers from environment

# Each model automatically routes to its respective provider
gpt_response = client.generate(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze market trends"}]
)

# Messages can also be provided as a string
claude_response = client.generate(
    model="claude-3-5-haiku-latest",
    messages="Hello, world!"
)

gemini_response = client.generate(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Summarize research findings"}]
)

Unified Response Format

All providers return responses in a consistent format:

response = client.generate(model="gpt-4o", messages="Explain quantum physics")

print(response.content)              # str | list — generated text
print(response.model)                # str | None — model that responded
print(response.metadata)             # dict | None — provider-specific extras

if response.usage:
    print(response.usage.prompt_tokens)      # int — input tokens
    print(response.usage.completion_tokens)  # int — output tokens
    print(response.usage.total_tokens)       # int — total tokens

Provider-specific details (e.g. stop reason, request ID) are available in response.metadata.

Streaming Responses

Stream responses token-by-token for real-time applications:

stream = client.generate(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.delta:
        print(chunk.delta, end="", flush=True)

Function Registration and Execution

Chimeric provides a decorator-based system for registering functions that models can invoke:

client = Chimeric()

@client.tool()
def analyze_financial_data(
    symbol: str,
    period: str = "1y",
    metrics: list[str] | None = None
) -> dict:
    """Analyze financial performance metrics for a given symbol.

    Args:
        symbol: Stock symbol (e.g., 'AAPL', 'MSFT')
        period: Analysis period ('1y', '6m', '3m')
        metrics: Specific metrics to analyze

    Returns:
        Dict containing analysis results and recommendations
    """
    return {
        "symbol": symbol,
        "period": period,
        "performance": "positive",
        "volatility": "moderate",
        "recommendation": "hold"
    }

# Functions are automatically available to all compatible models
response = client.generate(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze Tesla's performance over the last year"}]
)

Async Support

Chimeric supports async operations for high-performance applications:

import asyncio
from chimeric import Chimeric


async def main():
    client = Chimeric()

    response = await client.agenerate(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )

    print(response.content)


# Async streaming
async def stream_example():
    client = Chimeric()

    stream = await client.agenerate(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Tell me a joke"}],
        stream=True
    )

    async for chunk in stream:
        if chunk.delta:
            print(chunk.delta, end="", flush=True)


asyncio.run(main())

Error Handling

Handle errors gracefully across providers:

from chimeric import Chimeric
from chimeric.exceptions import ChimericError

client = Chimeric()

try:
    response = client.generate(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except ChimericError as e:
    print(f"Chimeric error: {e}")