Comprehensive examples demonstrating all features of chuk-llm with modern Pydantic-native architecture.

Start here if you're new to chuk-llm!

1. 00_quick_start.py - One line to ask a question
2. 01_basic_ask.py - Basic async and sync patterns
3. 02_streaming.py - Real-time streaming responses

4. 03_registry_discovery.py - Intelligent model selection
5. registry_provider_discovery.py - Deep dive into discovery

6. 04_tools_basic.py - Function calling basics
7. 05_tools_advanced.py - Auto-execution with Tools class
8. 06_conversations.py - Stateful conversations

9. 07_json_mode.py - Structured outputs and data extraction
10. 08_multimodal.py - Vision and image understanding

The examples directory is now clean and well-organized:

examples/
├── README.md                                   # This file
│
├── 🆕 CORE EXAMPLES (Root directory - Start Here!)
│   ├── 00_quick_start.py                      # Simplest possible example
│   ├── 01_basic_ask.py                        # Basic usage patterns
│   ├── 02_streaming.py                        # Real-time streaming
│   ├── 03_registry_discovery.py               # 🧠 Registry-based selection
│   ├── 04_tools_basic.py                      # Tool calling basics
│   ├── 05_tools_advanced.py                   # Auto-execution
│   ├── 06_conversations.py                    # Stateful chatbots
│   ├── 07_json_mode.py                        # Structured outputs
│   ├── 08_multimodal.py                       # Vision/images
│   └── registry_provider_discovery.py         # Registry deep dive
│
├── providers/                                  # Provider-specific examples (17 files)
│   ├── run_all_providers.py                   # ⭐ Test all providers
│   ├── openai_usage_examples.py               # OpenAI (GPT-5, o1, GPT-4o)
│   ├── openai_chat_completions_example.py     # Chat completions format
│   ├── openai_responses_example.py            # Responses API (stateful)
│   ├── openai_compatible_example.py           # OpenAI-compatible providers
│   ├── anthropic_usage_examples.py            # Claude 3.5
│   ├── gemini_usage_examples.py               # Gemini 2.0
│   ├── groq_usage_examples.py                 # Ultra-fast inference
│   ├── mistral_usage_examples.py              # Mistral AI
│   ├── azure_usage_examples.py                # Enterprise Azure
│   ├── watsonx_usage_examples.py              # IBM Watsonx
│   ├── advantage_usage_examples.py            # IBM Advantage
│   ├── deepseek_usage_examples.py             # DeepSeek V3
│   ├── perplexity_usage_examples.py           # Web search + citations
│   ├── openrouter_usage_examples.py           # 100+ models via one API
│   ├── conversation_isolation_demo.py         # Architecture deep dive
│   └── session_isolation_demo.py              # Session management
│
└── advanced/                                   # Advanced features (6 files)
    ├── registry_demo.py                       # Registry system demo
    ├── performance_demo.py                    # Performance benchmarks
    ├── dynamic_provider_workflow.py           # Dynamic provider selection
    ├── streaming_usage.py                     # Advanced streaming
    ├── tools_execution_demo.py                # Tool execution patterns
    └── common_demos.py                        # Common usage patterns

Total: 33 focused, well-organized examples (10 core + 17 provider + 6 advanced)

The examples directory was massively cleaned up to remove:

• ❌ 34+ duplicate, debug, and outdated examples
• ❌ Pirate-themed examples (fun but not core)
• ❌ Legacy discovery examples (replaced by registry)
• ❌ Test and scratch files

Result: Crystal clear learning path with only essential, well-documented examples!

Run the master test suite to verify all providers work:

python providers/run_all_providers.py
python providers/run_all_providers.py --provider openai --verbose

We provide 3 comprehensive OpenAI examples covering different use cases:

File: openai_chat_completions_example.py

OpenAI's traditional Chat Completions API (/v1/chat/completions):

python examples/providers/openai_chat_completions_example.py
python examples/providers/openai_chat_completions_example.py --model gpt-5
python examples/providers/openai_chat_completions_example.py --demo 3  # Function calling

Features (11 demos):

• ✅ Basic completion, streaming, function calling
• ✅ Vision, JSON mode, structured outputs
• ✅ GPT-5 and GPT-5-mini support
• ✅ Model comparison (4 models)
• ✅ Manual conversation history management
• ⚠️ You manage conversation state yourself

Use this for: Standard OpenAI requests, maximum control, custom history management

File: openai_responses_example.py

OpenAI's next-generation Responses API (/v1/responses) with built-in conversation state:

python examples/providers/openai_responses_example.py
python examples/providers/openai_responses_example.py --model gpt-5
python examples/providers/openai_responses_example.py --demo 3  # Stateful conversation

Features (13 demos):

• ✅ Stateful conversations with previous_response_id
• ✅ Automatic history management by OpenAI (store=true)
• ✅ Response retrieval and deletion by ID
• ✅ Background processing mode
• ✅ JSON mode with full json_schema validation
• ✅ GPT-5 with reasoning configuration
• ✅ Vision, function calling, structured outputs

Use this for: Multi-turn conversations, complex workflows, automatic state management

File: openai_compatible_example.py

Using other providers (Groq, DeepSeek, Together, Mistral, Perplexity) with the same API:

python examples/providers/openai_compatible_example.py
python examples/providers/openai_compatible_example.py --provider groq
python examples/providers/openai_compatible_example.py --demo 4  # Provider comparison

Features (6 demos):

• ✅ 5 providers (Groq, DeepSeek, Together, Mistral, Perplexity)
• ✅ Same API across all providers
• ✅ Basic completion, streaming, function calling
• ✅ Provider comparison and multi-provider apps
• ✅ Easy provider switching (just change base_url + api_key)

Use this for: Provider flexibility, cost optimization, avoiding vendor lock-in

ChukLLM supports 12 LLM providers with modern Pydantic clients (100% coverage):

Each provider example demonstrates:

• ✅ Basic Completion - Standard text generation
• ✅ Streaming - Real-time response streaming
• ✅ Tool Calling - Function/tool invocation (where supported)
• ✅ System Prompts - Custom system instructions
• ✅ Vision - Multi-modal image understanding (where supported)
• ✅ JSON Mode - Structured output (where supported)
• ✅ Error Handling - Graceful error management

pip install -e .
# or with all features
pip install -e .[all]

Create a .env file in the project root:

# Core providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI-compatible
GROQ_API_KEY=gsk_...
DEEPSEEK_API_KEY=sk-...
TOGETHER_API_KEY=...
PERPLEXITY_API_KEY=pplx-...
MISTRAL_API_KEY=...

# Ollama (optional, defaults to localhost)
OLLAMA_BASE_URL=http://localhost:11434

# Enterprise
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com

# IBM providers
ADVANTAGE_API_KEY=...
ADVANTAGE_API_BASE=...
WATSONX_API_KEY=...
WATSONX_PROJECT_ID=...

# Google
GEMINI_API_KEY=...

# Test all available providers
python providers/run_all_providers.py

# Test specific provider
python providers/run_all_providers.py --provider openai --verbose

# Run comprehensive provider examples
python providers/openai_usage_examples.py
python providers/anthropic_usage_examples.py
python providers/gemini_usage_examples.py

from chuk_llm.api import ask

response = await ask(
    "Explain quantum computing in simple terms",
    provider="openai",
    model="gpt-4o-mini"
)
print(response)

from chuk_llm.api import stream

async for chunk in stream(
    "Write a haiku about AI",
    provider="anthropic",
    model="claude-3-5-haiku-20241022"
):
    print(chunk, end="", flush=True)

from chuk_llm.api import ask

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            }
        }
    }
}]

response = await ask(
    "What's the weather in Tokyo?",
    provider="openai",
    tools=tools
)

from chuk_llm.api import ask

response = await ask(
    [
        {"type": "text", "text": "Describe this image"},
        {"type": "image_url", "image_url": {"url": "https://..."}}
    ],
    provider="gemini",
    model="gemini-2.0-flash-exp"
)

• Latest models: GPT-5, GPT-5-mini (newest, most capable)
• Full support for GPT-4, GPT-4o, O-series models
• Vision supported with gpt-5, gpt-4o, gpt-4-turbo
• JSON mode available
• Function calling fully supported

• Claude 3.5 Sonnet/Haiku with enhanced reasoning
• Vision supported with Claude 3+ models
• Different tool format than OpenAI (auto-converted)

• Ultra-fast inference (<1s responses)
• Llama 3.3, Mixtral, Gemma models
• Tool calling supported

• Google's latest models with multimodal support
• Vision natively integrated
• Uses REST API (no heavy SDK)

• Enterprise OpenAI deployment
• Requires endpoint + deployment name
• Same models as OpenAI

• IBM's enterprise LLM platform
• Granite models optimized for business
• Wraps IBM SDK with modern patterns

• Local model hosting
• No API key needed for localhost
• Supports Llama, Mistral, CodeLlama, etc.

❌ OPENAI_API_KEY not set
   export OPENAI_API_KEY='sk-...'

Solution: Set the required environment variable or add to .env

❌ Model 'gpt-5' not found

Solution: Check available models for the provider in their documentation

❌ Rate limit exceeded

Solution: Reduce request frequency or upgrade API tier

❌ Connection failed to http://localhost:11434

Solution: For Ollama, ensure server is running: ollama serve

Run the comprehensive test suite:

# Test all providers
python providers/run_all_providers.py

# Test specific provider
python providers/run_all_providers.py --provider gemini --verbose

# Quick test (basic features only)
python providers/run_all_providers.py --quick

✅ 100% Complete - All 12 providers migrated to modern Pydantic clients

• Type-safe with Pydantic V2
• Fast JSON with orjson
• Connection pooling with httpx
• Clean architecture (no fallbacks)
• Zero breaking changes

When adding new examples:

1. Place provider-specific examples in providers/
2. Name files descriptively: {provider}_usage_examples.py
3. Include comprehensive tests for all features
4. Add provider to run_all_providers.py
5. Update this README

• Migration Progress - 100% migration details
• Session Summary - What was accomplished
• Documentation - Full API documentation

Last Updated: 2025-11-19 Migration Status: 100% Complete (12/12 providers) Modern Clients: OpenAIClient, AnthropicClient, AzureOpenAIClient, OpenAICompatibleClient, GeminiClient, WatsonxClient