### Install Python and Development Tools (Bash)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/contributing.md

This snippet shows how to install specific Python versions (3.11, 3.12, 3.13) using pyenv and then install development tools like uv and nox using pip. Finally, it demonstrates installing the package with development dependencies using 'make install' or 'uv sync'.

```bash
# Install Python versions
pyenv install 3.11 3.12 3.13

# Install development tools
pip install uv nox

# Install package with dev dependencies
make install
# or: uv sync --all-extras --dev
```

--------------------------------

### Streaming LLM Responses (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/getting-started.md

Demonstrates how to stream responses from LLM providers token-by-token using Chimeric. This is useful for real-time applications where immediate feedback is desired. The example iterates through the stream and prints each delta.

```python
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)
```

--------------------------------

### Installation and Configuration

Source: https://github.com/verdenroz/chimeric/blob/master/README.md

Instructions for installing the library via pip and setting up necessary API keys as environment variables.

```bash
pip install chimeric
export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"
```

--------------------------------

### Registering Functions for LLM Tool Usage (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/getting-started.md

Shows how to use Chimeric's decorator-based system to register functions that LLM models can invoke. The example defines an `analyze_financial_data` function and makes it available to models like GPT-4o for execution.

```python
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"}]
)
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/verdenroz/chimeric/blob/master/CONTRIBUTING.md

Steps to clone the Chimeric repository and install development dependencies using `make` or `uv`.

```bash
git clone https://github.com/yourusername/chimeric.git
cd chimeric
make install
# or directly with uv
uv sync --all-extras --dev
```

--------------------------------

### Model Discovery (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Shows how to list available models from all configured providers or a specific provider. This function helps in identifying usable models for generation tasks.

```python
# All providers
all_models = client.list_models()
for model in all_models:
    print(f"{model.id} ({model.provider})")

# One provider
openai_models = client.list_models("openai")
for model in openai_models:
    print(model.id)

# The async counterpart is `alist_models()`.
```

--------------------------------

### Automatic LLM Provider Detection and Generation (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/getting-started.md

Demonstrates how Chimeric automatically detects available LLM providers and routes generation requests based on model names. It shows how to initialize the client and send messages to different models like GPT-4o, Claude, and Gemini.

```python
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"}]
)
```

--------------------------------

### Provider Inspection (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Demonstrates how to list all configured providers available in the Chimeric client. This helps in understanding which LLM services are accessible.

```python
# List all configured providers
print(client.available_providers)  # ["openai", "anthropic", "google", ...]
```

--------------------------------

### Error Handling with Chimeric (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/getting-started.md

Provides an example of how to handle potential errors when interacting with Chimeric and its underlying LLM providers. It uses a try-except block to catch `ChimericError` and print informative error messages.

```python
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}")
```

--------------------------------

### Asynchronous LLM Generation and Streaming (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/getting-started.md

Demonstrates Chimeric's support for asynchronous operations, enabling high-performance applications. It shows how to use `agenerate` for non-streaming responses and asynchronous iteration for streaming responses.

```python
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())
```

--------------------------------

### Mixed API Key Configuration (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Demonstrates combining environment variables with direct client initialization for API key configuration. Explicitly provided keys take precedence over environment variables for the specified providers.

```python
# Explicit key overrides env var; other providers read from env vars automatically
client = Chimeric(
    openai_api_key="sk-...",
    # ANTHROPIC_API_KEY, GOOGLE_API_KEY, etc. are picked up from the environment
)
```

--------------------------------

### Unified LLM Response Format Handling (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/getting-started.md

Illustrates the consistent response format provided by Chimeric across different LLM providers. It shows how to access the generated content, model name, metadata, and token usage information from the response object.

```python
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
```

--------------------------------

### Configure API Keys using Environment Variables (Bash)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Sets API keys for various LLM providers using environment variables. This is the recommended method for configuring API access. Providers with discoverable keys are automatically registered.

```bash
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Google (supports both variable names)
export GOOGLE_API_KEY="AIza..."
# or
export GEMINI_API_KEY="AIza..."

# Cohere (supports both variable names)
export COHERE_API_KEY="your-key"
# or
export CO_API_KEY="your-key"

# Groq
export GROQ_API_KEY="gsk_..."

# Cerebras
export CEREBRAS_API_KEY="csk-..."

# Grok / xAI (supports both variable names)
export GROK_API_KEY="xai-..."
# or
export XAI_API_KEY="xai-..."

# OpenRouter
export OPENROUTER_API_KEY="sk-or-..."
```

--------------------------------

### Basic Setup

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Initialize Chimeric with the base URL of your local inference server. An API key can be provided if required by the server, otherwise it defaults to 'local'.

```APIDOC
## Basic Setup

Pass `base_url` to `Chimeric`. The `api_key` defaults to "local" for servers that do not validate credentials:

```python
from chimeric import Chimeric

client = Chimeric(base_url="http://127.0.0.1:11434/v1")
```

For servers that require a key:

```python
client = Chimeric(
    base_url="http://127.0.0.1:11434/v1",
    api_key="my-server-secret",
)
```

The local endpoint is registered as a provider named "custom". All standard Chimeric features — streaming, tools, structured output, async — work identically.
```

--------------------------------

### Install Chimeric using pip

Source: https://github.com/verdenroz/chimeric/blob/master/docs/index.md

This command installs the Chimeric library using pip, making it available for use in your Python projects. Ensure you have pip installed and configured correctly.

```bash
pip install chimeric
```

--------------------------------

### Configure API Keys via Direct Client Initialization (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Initializes the Chimeric client by directly passing API keys as arguments. This method allows for programmatic configuration of API access. Explicitly provided keys override any corresponding environment variables.

```python
from chimeric import Chimeric

client = Chimeric(
    openai_api_key="sk-...",
    anthropic_api_key="sk-ant-...",
    google_api_key="AIza...",
    cohere_api_key="your-key",
    groq_api_key="gsk_...",
    cerebras_api_key="csk-...",
    grok_api_key="xai-...",
    openrouter_api_key="sk-or-...",
)
```

--------------------------------

### Run Tests (Bash)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/contributing.md

This snippet provides commands for running various test suites within the project. It includes commands for running all tests, unit tests, integration tests, and cross-version testing using nox.

```bash
# Run all tests
make test

# Run unit tests
make test-unit

# Run integration tests
make test-integration

# Cross-version testing
make nox
```

--------------------------------

### Async Generation with Tools in Python

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Demonstrates how to perform asynchronous generation with tool support using the `agenerate` method. This example shows a typical async main function that calls the AI with tools enabled and prints the response content.

```python
import asyncio

async def main():
    # Async generation with tools
    response = await client.agenerate(
        model="gpt-4o",
        messages="What's the current time?",
        auto_tool=True
    )
    print(response.content)

asyncio.run(main())
```

--------------------------------

### Accessing All Registered Tools

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Provides an example of how to retrieve a list of all functions that have been registered as tools with the Chimeric client. This allows for introspection and management of available tools.

```python
# Get all registered tools
all_tools = client.tools
print(f"Registered {len(all_tools)} tools:")
for tool in all_tools:
    print(f"- {tool.name}: {tool.description}")
```

--------------------------------

### Python Tool Function Design Best Practices

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Illustrates best practices for designing tool functions in Python, emphasizing clear docstrings, type hints for schema generation, parameter documentation, and robust error handling. The example function `fetch_user_profile` includes validation, data fetching, and exception management.

```python
@client.tool()
def fetch_user_profile(user_id: str, include_preferences: bool = False) -> dict:
    """Fetch user profile information from the database. 
    
    Args:
        user_id: Unique identifier for the user (UUID format)
        include_preferences: Whether to include user preference settings
        
    Returns:
        Dictionary containing user profile data, or error message if user not found
    """
    try:
        # Validate user_id format
        if not user_id or len(user_id) < 8:
            return {"error": "Invalid user_id format"}
            
        # Fetch user data
        profile = get_user_from_db(user_id)
        if not profile:
            return {"error": f"User {user_id} not found"}
            
        # Add preferences if requested
        if include_preferences:
            profile["preferences"] = get_user_preferences(user_id)
            
        return profile
        
    except Exception as e:
        return {"error": f"Failed to fetch user profile: {str(e)}"}
```

--------------------------------

### Provider Pass-Through Arguments (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Explains how extra keyword arguments passed to `generate()` or `agenerate()` are forwarded directly to the underlying provider's API. This allows for fine-tuning model behavior using provider-specific parameters.

```python
response = client.generate(
    model="gpt-4o",
    messages="Write a haiku",
    temperature=0.9,
    max_tokens=100,
)
```

--------------------------------

### Automatic Model Routing (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Illustrates how Chimeric automatically routes requests to the correct provider based on the model name. Routing is performed at initialization time and cached for efficiency.

```python
client = Chimeric()

# Each call is automatically routed to the right provider
client.generate("gpt-4o", "Hello")                      # → OpenAI
client.generate("claude-3-5-sonnet-20241022", "Hello")  # → Anthropic
client.generate("gemini-1.5-pro", "Hello")              # → Google
```

--------------------------------

### Explicit Provider Selection (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Shows how to force a specific provider for a request using either a string identifier or the `Provider` enum. This overrides automatic routing.

```python
from chimeric import Chimeric, Provider

client = Chimeric()

# String form
response = client.generate(
    model="llama-3.3-70b-versatile",
    messages="Hello",
    provider="groq",
)

# Enum form
response = client.generate(
    model="llama-3.3-70b-versatile",
    messages="Hello",
    provider=Provider.GROQ,
)
```

--------------------------------

### Streaming Responses with Tools in Python

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Illustrates how to use tools with streaming responses, allowing real-time updates of both AI-generated text and tool execution results. The example defines two tools (`get_current_time` and `tell_joke`) and streams a response that utilizes them.

```python
from chimeric import Chimeric
from datetime import datetime

client = Chimeric()

@client.tool()
def get_current_time() -> str:
    """Get the current time."""
    now = datetime.now()
    return f"Current time: {now.strftime('%Y-%m-%d %H:%M:%S UTC')}"

@client.tool()
def tell_joke() -> str:
    """Tell a programming joke."""
    return "Why do programmers prefer dark mode? Because light attracts bugs! 🐛"

# Stream with tools enabled
stream = client.generate(
    model="gpt-4o",
    messages="What time is it and then tell me a programming joke?",
    stream=True
)

print("Streaming response with tools:\n")

for chunk in stream:
    if chunk.delta:
        print(chunk.delta, end="", flush=True)
    
    if chunk.finish_reason:
        print(f"\n\nStream finished: {chunk.finish_reason}")
```

--------------------------------

### Multi-Provider Text Generation with Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/index.md

Illustrates how to seamlessly switch between different LLM providers for text generation by specifying the desired model. This example shows generating responses from OpenAI's GPT-4o, Anthropic's Claude, and Google's Gemini.

```python
# Seamlessly switch between providers - string input
gpt_response = client.generate(model="gpt-4o", messages="Explain quantum computing")
claude_response = client.generate(model="claude-3-5-haiku-latest", messages="Write a poem about AI")
gemini_response = client.generate(model="gemini-2.5-flash", messages="Summarize climate change")
```

--------------------------------

### GET list_models()

Source: https://context7.com/verdenroz/chimeric/llms.txt

Retrieves a list of available models from configured providers for discovery and validation.

```APIDOC
## GET list_models()

### Description
List available models from configured providers for discovery and validation. Can filter by provider.

### Method
GET

### Endpoint
client.list_models(provider=None)

### Parameters
#### Query Parameters
- **provider** (string|Enum) - Optional - Filter models by specific provider (e.g., "openai", Provider.ANTHROPIC).

### Response
#### Success Response (200)
- **models** (list) - A list of model objects containing id, name, description, and provider.
```

--------------------------------

### Configure HTTP Client Options (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/configuration.md

Configures the underlying httpx transport for Chimeric, including request timeout, maximum retries, and default headers. These settings apply to all providers and mirror native SDK options.

```python
client = Chimeric(
    timeout=120.0,  # longer timeout for slow models
    max_retries=3,  # retry up to 3 times before raising
)

# Set to 0 to disable retries entirely
client = Chimeric(max_retries=0)

client = Chimeric(
    openai_api_key="sk-...",
    default_headers={
        "OpenAI-Organization": "org-...",
        "X-Trace-ID": "my-trace-id",
    },
)
```

--------------------------------

### Async Text Streaming with Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/streaming.md

Provides an example of how to perform asynchronous streaming of AI model responses using Chimeric. This is suitable for high-performance applications where non-blocking I/O is crucial.

```python
import asyncio

async def stream_example():
    client = Chimeric()
    
    stream = await client.agenerate(
        model="gpt-4o",
        messages="Write a poem about artificial intelligence",
        stream=True
    )
    
    async for chunk in stream:
        if chunk.delta:
            print(chunk.delta, end="", flush=True)
        
        if chunk.finish_reason:
            print(f"\nFinished: {chunk.finish_reason}")

asyncio.run(stream_example())
```

--------------------------------

### Basic and Streaming LLM Generation

Source: https://github.com/verdenroz/chimeric/blob/master/README.md

Demonstrates how to initialize the Chimeric client and perform both standard and streaming text generation requests.

```python
from chimeric import Chimeric

client = Chimeric()

# Basic usage
response = client.generate(model="gpt-4o", messages="Hello!")
print(response.content)

# Streaming usage
stream = client.generate(
    model="claude-3-5-sonnet-latest",
    messages="Tell me a story about space exploration",
    stream=True
)
for chunk in stream:
    print(chunk.content, end="", flush=True)
```

--------------------------------

### Initialize Chimeric Client and Generate Text

Source: https://github.com/verdenroz/chimeric/blob/master/docs/index.md

Demonstrates how to initialize the Chimeric client, which automatically detects API keys from environment variables. It then shows a basic text generation request and prints the response content.

```python
from chimeric import Chimeric

client = Chimeric()  # Auto-detects API keys from environment

response = client.generate(
    model="gpt-4o",
    messages="Hello!"
)
print(response.content)
```

--------------------------------

### Using Tools with Compatible Providers in Python

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Shows how to use tools with AI models, specifically highlighting the importance of selecting providers known to support function calling. It mentions OpenAI, Anthropic, and Google as reliable options and advises against providers with inconsistent tool use behavior.

```python
# Use tools only with providers known to support function calling
response = client.generate(
    model="gpt-4o",
    messages="Process this data for me",
    # registered tools are included automatically
)
```

--------------------------------

### Run Tests

Source: https://github.com/verdenroz/chimeric/blob/master/CONTRIBUTING.md

Commands to run different sets of tests, including all tests, unit tests, integration tests, provider-specific tests, and cross-version testing using `make` and `nox`.

```bash
# All tests
make test

# Unit tests only (fast)
make test-unit

# Integration tests (requires API keys or existing cassettes)
make test-integration

# Provider-specific tests
make test-openai
make test-anthropic
# etc.

# Cross-version testing
make nox

# Coverage reports
nox --session=coverage
```

--------------------------------

### Asynchronous Embedding Generation (Python)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/embeddings.md

Provides an example of using the asynchronous `aembed()` method for generating embeddings in an async Python context. It covers both single and batch embedding requests.

```python
import asyncio
from chimeric import Chimeric


async def main():
    client = Chimeric()

    # Single
    result = await client.aembed(
        model="text-embedding-3-small",
        input="Hello from async",
    )
    print(len(result.embedding))

    # Batch
    result = await client.aembed(
        model="text-embedding-3-small",
        input=["text one", "text two"],
    )
    print(len(result.embeddings))  # 2


asyncio.run(main())
```

--------------------------------

### Initialize Chimeric with Local Server (With Auth)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Shows how to initialize the Chimeric client when the local inference server requires an API key for authentication. Both `base_url` and `api_key` are provided.

```python
client = Chimeric(
    base_url="http://127.0.0.1:11434/v1",
    api_key="my-server-secret",
)
```

--------------------------------

### Model Discovery

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Chimeric automatically discovers and caches models exposed by the local server by querying the `GET /models` endpoint at startup. This allows for automatic model name routing.

```APIDOC
## Model Discovery

Chimeric queries `GET /models` at startup and caches the results, so model names are routed automatically:

```python
# List everything the local server exposes
for model in client.list_models():
    print(f"{model.id}")
```
```

--------------------------------

### Tool Calling and Function Execution

Source: https://github.com/verdenroz/chimeric/blob/master/README.md

Shows how to define tools using the @client.tool() decorator and execute them within a generation request.

```python
@client.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Sunny, 72°F in {city}"

@client.tool()
def calculate_tip(bill_amount: float, tip_percentage: float = 18.0) -> dict:
    """Calculate tip and total amount for a restaurant bill."""
    tip = bill_amount * (tip_percentage / 100)
    total = bill_amount + tip
    return {"tip": tip, "total": total, "tip_percentage": tip_percentage}

response = client.generate(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in NYC?"}]
)
```

--------------------------------

### Generate Text with Local Model

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Provides an example of generating text content using a specified model from the local server. This function mirrors the standard `generate()` method used with cloud providers.

```python
response = client.generate(
    model="qwen2.5:3b",
    messages="Explain neural networks in one sentence.",
)
print(response.content)
```

--------------------------------

### Register and Use Specific Tools in Python

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Demonstrates how to register multiple tools using decorators and then selectively use them in a client generation call. It shows how to limit tool usage by passing a list of desired tools and how `auto_tool=False` prevents the inclusion of other registered tools.

```python
# Register multiple tools
@client.tool()
def get_weather(city: str) -> str:
    return f"Weather in {city}"

@client.tool()
def get_stock_price(symbol: str) -> float:
    return 150.25

# Use specific tools only
response = client.generate(
    model="gpt-4o",
    messages="What's the weather in NYC? What is the stock price of AAPL?",
    tools=[client.tools[0]],  # Only weather tool
    auto_tool=False  # Don't auto-include other tools
)

print(response)

# Use all tools (default behavior)
response = client.generate(
    model="gpt-4o",
    messages="What's the weather in NYC? What is the stock price of AAPL?",
    auto_tool=True  # Automatically includes all registered tools
)

print(response)
```

--------------------------------

### Tool Registration with Google Style Docstrings

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Illustrates registering a Python function as a tool using Google-style docstrings for automatic parameter documentation. This format clearly defines arguments and return values, aiding AI model interpretation.

```python
@client.tool()
def analyze_data(data: list[float], method: str = "mean") -> dict:
    """Analyze numerical data using statistical methods.
    
    Args:
        data: List of numerical values to analyze
        method: Statistical method to use ('mean', 'median', 'mode')
        
    Returns:
        Dictionary containing analysis results
    """
    # Implementation here
    pass
```

--------------------------------

### Initialize Chimeric with Local Server (No Auth)

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Demonstrates initializing the Chimeric client to connect to a local OpenAI-compatible inference server that does not require authentication. The `base_url` parameter points to the server's endpoint.

```python
from chimeric import Chimeric

client = Chimeric(base_url="http://127.0.0.1:11434/v1")
```

--------------------------------

### Chimeric Client Initialization

Source: https://context7.com/verdenroz/chimeric/llms.txt

Initialize the Chimeric client, which can automatically detect API keys from environment variables or accept them explicitly. You can also configure HTTP timeout, retry counts, and custom headers.

```APIDOC
## Chimeric Client Initialization

### Description
Initialize the Chimeric client. API keys can be automatically detected from environment variables or provided explicitly. Configuration options include HTTP timeout, maximum retries, and default headers.

### Method
Initialization

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from chimeric import Chimeric

# Auto-detect API keys from environment variables
client = Chimeric()

# Or provide keys explicitly (takes precedence over environment)
client = Chimeric(
    openai_api_key="sk-...",
    anthropic_api_key="sk-ant-...",
    google_api_key="AIza...",
    timeout=120.0,      # HTTP timeout in seconds (default: 60.0)
    max_retries=3,      # Retry count for failures (default: 2)
    default_headers={"X-Trace-ID": "my-trace-id"},  # Custom headers
)

# Check configured providers
print(client.available_providers)  # ["openai", "anthropic", "google", ...]
```

### Response
#### Success Response (Initialization)
- **client** (Chimeric) - An initialized Chimeric client instance.
- **client.available_providers** (list[str]) - A list of strings indicating the providers configured and available for use.

#### Response Example
```
['openai', 'anthropic', 'google']
```
```

--------------------------------

### Initialize Chimeric Client

Source: https://context7.com/verdenroz/chimeric/llms.txt

Initialize the Chimeric client. It can automatically detect API keys from environment variables or accept them explicitly. Optional parameters like timeout and retry count can be configured.

```python
from chimeric import Chimeric

# Auto-detect API keys from environment variables
client = Chimeric()

# Or provide keys explicitly (takes precedence over environment)
client = Chimeric(
    openai_api_key="sk-...",
    anthropic_api_key="sk-ant-...",
    google_api_key="AIza...",
    timeout=120.0,      # HTTP timeout in seconds (default: 60.0)
    max_retries=3,      # Retry count for failures (default: 2)
    default_headers={"X-Trace-ID": "my-trace-id"},  # Custom headers
)

# Check configured providers
print(client.available_providers)  # ["openai", "anthropic", "google", ...]
```

--------------------------------

### Configure API Keys for Chimeric

Source: https://context7.com/verdenroz/chimeric/llms.txt

Set environment variables for your API keys to enable automatic provider detection in Chimeric. This is the recommended way to configure credentials.

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="AIza..."
export COHERE_API_KEY="your-key"
export GROQ_API_KEY="gsk_..."
export CEREBRAS_API_KEY="csk-..."
export GROK_API_KEY="xai-..."
export OPENROUTER_API_KEY="sk-or-..."
```

--------------------------------

### Integrate Local OpenAI-Compatible AI Servers

Source: https://context7.com/verdenroz/chimeric/llms.txt

Connects the Chimeric client to local servers like Ollama or LM Studio using the base_url parameter. Supports streaming responses and mixing local models with cloud-based providers.

```python
from chimeric import Chimeric

# Connect to local Ollama server
client = Chimeric(base_url="http://127.0.0.1:11434/v1")

# Generate with local model
response = client.generate(
    model="qwen2.5:3b",
    messages="Explain neural networks"
)
print(response.content)

# Streaming with local model
stream = client.generate(
    model="llama3.2:3b",
    messages="Write a poem",
    stream=True
)
for chunk in stream:
    print(chunk.delta or "", end="", flush=True)
```

--------------------------------

### Tool Registration with NumPy Style Docstrings

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Demonstrates registering a Python function as a tool using NumPy-style docstrings for automatic parameter documentation. This format is suitable for scientific and numerical code, providing structured descriptions for parameters and return values.

```python
@client.tool()
def process_image(image_path: str, resize: bool = True) -> str:
    """Process an image file with optional resizing.
    
    Parameters
    ----------
    image_path : str
        Path to the image file to process
    resize : bool, optional
        Whether to resize the image, default True
        
    Returns
    -------
    str
        Path to the processed image file
    """
    # Implementation here
    pass
```

--------------------------------

### Run Quality Checks

Source: https://github.com/verdenroz/chimeric/blob/master/CONTRIBUTING.md

Command to execute all code quality checks, including linting, formatting, type checking, and spell checking, using `make`.

```bash
make lint
```

--------------------------------

### Tool Registration with Sphinx Style Docstrings

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Shows how to register a Python function as a tool using Sphinx-style docstrings for automatic parameter documentation. This format is commonly used in Python projects and clearly defines parameters and return types.

```python
@client.tool()
def send_email(recipient: str, subject: str, body: str = "") -> bool:
    """Send an email message.
    
    :param recipient: Email address of the recipient
    :param subject: Subject line of the email
    :param body: Email body content, optional
    :returns: True if email was sent successfully
    """
    # Implementation here
    pass
```

--------------------------------

### Generating Text

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Once the client is initialized, use the `generate()` method to produce text, similar to how you would with cloud providers. Specify the model and the message content.

```APIDOC
## Generating Text

Once the client is initialised, use `generate()` exactly as you would with any cloud provider:

```python
response = client.generate(
    model="qwen2.5:3b",
    messages="Explain neural networks in one sentence.",
)
print(response.content)
```
```

--------------------------------

### Register Function as Tool with @tool() Decorator

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Demonstrates basic registration of a Python function as a tool using the `@client.tool()` decorator. This makes the function callable by AI models. It requires the Chimeric library and a client instance.

```python
from chimeric import Chimeric

client = Chimeric()

@client.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city.
    
    Args:
        city: Name of the city to get weather for
        
    Returns:
        Weather description string
    """
    # Your weather API logic here
    return f"Sunny, 75°F in {city}"

# Function is now available to all models
response = client.generate(
    model="gpt-4o",
    messages="What's the weather in San Francisco?"
)
```

--------------------------------

### Asynchronous Text Generation with Local Model

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Shows how to perform text generation asynchronously using the `agenerate()` method with a local inference server. This requires an `asyncio` event loop.

```python
import asyncio
from chimeric import Chimeric


async def main():
    client = Chimeric(base_url="http://127.0.0.1:11434/v1")
    response = await client.agenerate(
        model="qwen2.5:3b",
        messages="What is 2 + 2?",
    )
    print(response.content)

asyncio.run(main())
```

--------------------------------

### POST /agenerate - Async Chat Completions

Source: https://context7.com/verdenroz/chimeric/llms.txt

Asynchronously generate chat completions using `async`/`await`. Supports both standard and streaming responses in an asynchronous context.

```APIDOC
## POST /agenerate - Async Chat Completions

### Description
Asynchronous version of the `generate` method for high-performance applications using `async`/`await`. Supports both non-streaming and streaming responses in an asynchronous context.

### Method
POST

### Endpoint
`/agenerate`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (str) - Required - The name of the model to use for generation.
- **messages** (str | dict | list[dict]) - Required - The message(s) to send to the model.
- **stream** (bool) - Optional - If True, enables streaming of response chunks (default: False).
- **temperature** (float) - Optional - Controls randomness.
- **max_tokens** (int) - Optional - The maximum number of tokens to generate.

### Request Example
```python
import asyncio
from chimeric import Chimeric

async def main():
    client = Chimeric()

    # Non-streaming async
    response = await client.agenerate(
        model="gpt-4o",
        messages="Hello, world!"
    )
    print(response.content)

    # Async streaming
    stream = await client.agenerate(
        model="claude-3-5-haiku-latest",
        messages="Write a haiku about coding",
        stream=True
    )

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

asyncio.run(main())
```

### Response
#### Success Response (200)
- **response** (object) - For non-streaming requests, returns a response object similar to `generate`.
- **stream** (AsyncGenerator) - For streaming requests, returns an asynchronous generator yielding response chunks.
  - **chunk** (object) - Each yielded chunk contains:
    - **delta** (str | None) - The newly generated text content in this chunk.
    - **content** (str) - The accumulated text content up to this chunk.
    - **finish_reason** (str | None) - The reason for finishing the stream, present only on the final chunk.
    - **metadata** (dict) - Provider-specific metadata for this chunk.

#### Response Example
```json
# Non-streaming response example:
{
  "content": "Hello, world!",
  "model": "gpt-4o",
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 3,
    "total_tokens": 8
  },
  "metadata": {}
}

# Streaming chunk example:
{
  "delta": "Code flows like",
  "content": "Code flows like",
  "finish_reason": null,
  "metadata": {}
}
```
```

--------------------------------

### Asynchronous Text Generation with Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/index.md

Shows how to perform text generation asynchronously using Chimeric's `agenerate` method. This is useful for non-blocking operations in applications, particularly in web frameworks or other I/O-bound scenarios.

```python
import asyncio


async def main():
    response = await client.agenerate(
        model="claude-3-5-sonnet-latest",
        messages=[{"role": "user", "content": "Analyze this data"},
                  {"role": "assistant",
                   "content": "I'd be happy to help analyze data. What data would you like me to look at?"},
                  {"role": "user", "content": "Sales figures from Q4"}]
    )
    print(response.content)


asyncio.run(main())
```

--------------------------------

### Add New Provider Sharing Existing Wire Format

Source: https://github.com/verdenroz/chimeric/blob/master/CONTRIBUTING.md

Python code snippet demonstrating how to add a new provider that shares an existing API format (e.g., OpenAI) by updating `PROVIDER_REGISTRY`.

```python
"myprovider": ProviderConfig(
    name="myprovider",
    base_url="https://api.myprovider.com/v1",
    adapter="openai",               # reuse the OpenAI adapter
    api_key_env_vars=("MYPROVIDER_API_KEY",),
),
```

--------------------------------

### Mix Local and Cloud Providers in Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Demonstrates how to configure a single Chimeric client to interact with both local inference servers and cloud-based providers simultaneously. Chimeric routes requests based on model availability.

```python
client = Chimeric(
    base_url="http://127.0.0.1:11434/v1",  # local
    openai_api_key="sk-...",               # cloud
)

# Routes to local server
local_resp = client.generate("qwen2.5:3b", "Hello from local!")

# Routes to OpenAI
cloud_resp = client.generate("gpt-4o", "Hello from the cloud!")
```

--------------------------------

### POST /generate

Source: https://context7.com/verdenroz/chimeric/llms.txt

Generates text responses using cloud or local AI models with support for streaming and provider routing.

```APIDOC
## POST /generate

### Description
Generates text using a specified model. Supports local OpenAI-compatible servers via base_url and explicit provider routing.

### Method
POST

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier.
- **messages** (string|list) - Required - The prompt or conversation history.
- **stream** (boolean) - Optional - Enable streaming response chunks.
- **provider** (string) - Optional - Force a specific provider (e.g., "groq").

### Response
#### Success Response (200)
- **content** (string) - The generated text response.
- **delta** (string) - The chunk content if streaming is enabled.
```

--------------------------------

### Implement Cross-Provider Consistency

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/responses.md

Shows how the unified interface allows the same function to work seamlessly across different AI models and providers.

```python
def summarize(model: str, text: str) -> str:
    response = client.generate(model=model, messages=f"Summarize: {text}")
    print(f"Used {response.usage.total_tokens} tokens")
    return response.content

# All three use the same interface
summarize("gpt-4o", "...")
summarize("claude-3-5-sonnet-20241022", "...")
summarize("gemini-1.5-pro", "...")
```

--------------------------------

### Function Calling with Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/index.md

Illustrates how to use Chimeric for function calling. A Python function `get_weather` is defined and decorated with `@client.tool()`. The client can then be used to generate responses that might invoke this function based on user input.

```python
@client.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Sunny, 72°F in {city}"


response = client.generate(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in NYC?"}]
)
```

--------------------------------

### List Models from Local Server

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Illustrates how to retrieve and display a list of all models exposed by the connected local inference server. Chimeric automatically discovers and caches these models upon initialization.

```python
# List everything the local server exposes
for model in client.list_models():
    print(f"{model.id}")
```

--------------------------------

### Create Feature Branch and Commit Changes

Source: https://github.com/verdenroz/chimeric/blob/master/CONTRIBUTING.md

Workflow for making changes, including creating a feature branch, making changes, adding tests, running tests and linting, and committing changes.

```bash
git checkout -b feature/your-feature-name
# Make your changes
# Add tests
make test
make lint
git commit -m "Descriptive commit message"
```

--------------------------------

### Generating Embeddings with Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/index.md

Demonstrates how to use Chimeric to generate embeddings for text. It covers generating an embedding for a single text input and for a batch of text inputs, printing the dimension of the embedding and the number of embeddings generated, respectively.

```python
# Single text
result = client.embed(model="text-embedding-3-small", input="Python developer")
print(len(result.embedding))   # e.g. 1536

# Batch
result = client.embed(
    model="text-embedding-3-small",
    input=["Python developer", "Go engineer", "React developer"],
)
print(len(result.embeddings))  # 3
```

--------------------------------

### Stream Text Generation from Local Model

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Demonstrates how to enable and process streaming responses for text generation from a local model. This functionality is identical to streaming with cloud-based providers.

```python
stream = client.generate(
    model="qwen2.5:3b",
    messages="Write a short poem.",
    stream=True,
)

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

--------------------------------

### Discover and List Available AI Models

Source: https://context7.com/verdenroz/chimeric/llms.txt

Retrieves a list of available models from configured providers. Allows filtering by specific providers to validate model availability.

```python
from chimeric import Chimeric, Provider

client = Chimeric()

# List models from all configured providers
all_models = client.list_models()
for model in all_models:
    print(f"{model.id} ({model.provider})")

# List models from a specific provider
openai_models = client.list_models("openai")
anthropic_models = client.list_models(Provider.ANTHROPIC)

for model in openai_models:
    print(model.id)
```

--------------------------------

### Type System Support: Basic Python Types

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/tools.md

Illustrates how Chimeric converts basic Python type hints (str, int, float, bool) into JSON schemas for AI model understanding. This enables precise parameter definition for tool calls.

```python
@client.tool()
def basic_types_example(
    text: str,           # → "string" 
    number: int,         # → "integer"
    decimal: float,      # → "number"
    flag: bool          # → "boolean"
) -> str:
    """Example of basic type support."""
    return f"{text}: {number}, {decimal}, {flag}"
```

--------------------------------

### Structured Output with Pydantic

Source: https://github.com/verdenroz/chimeric/blob/master/README.md

Utilizes Pydantic models to enforce structured output formats from LLM responses.

```python
from pydantic import BaseModel

class Sentiment(BaseModel):
    label: str
    score: float
    reasoning: str

response = client.generate(
    model="gpt-4o",
    messages="Analyse the sentiment: 'This library is fantastic!'",
    response_model=Sentiment,
)
print(response.parsed.label)
```

--------------------------------

### Define and Use Tools with Local Models

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/local-ai.md

Illustrates how to define and use tools (functions) with local models that support function calling. The `@client.tool()` decorator registers functions, and Chimeric handles their invocation.

```python
from chimeric import Chimeric


client = Chimeric(base_url="http://127.0.0.1:11434/v1")


@client.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city.

    Args:
        city: Name of the city.

    Returns:
        A short weather description.
    """
    return f"Sunny, 22°C in {city}"


response = client.generate(
    model="qwen2.5:3b",
    messages="What is the weather in Tokyo?",
)
print(response.content)
```

--------------------------------

### Basic Text Streaming with Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/usage/streaming.md

Demonstrates how to enable and process basic text streaming from an AI model using the Chimeric library. It iterates through stream chunks, printing new content as it arrives and indicating when the stream finishes.

```python
from chimeric import Chimeric

client = Chimeric()

# Basic streaming
stream = client.generate(
    model="gpt-4o",
    messages="Tell me a story about space exploration",
    stream=True
)

# Process chunks in real-time
for chunk in stream:
    if chunk.delta:  # New content in this chunk
        print(chunk.delta, end="", flush=True)
    
    if chunk.finish_reason:
        print(f"\nStreaming finished: {chunk.finish_reason}")
```

--------------------------------

### Streaming Text Generation with Chimeric

Source: https://github.com/verdenroz/chimeric/blob/master/docs/index.md

Shows how to enable and process streaming responses from the LLM. The `stream=True` argument activates streaming, and the code iterates through the received chunks, printing them as they arrive.

```python
stream = client.generate(
    model="gpt-4o",
    messages="Tell me a story about space exploration",
    stream=True
)

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