### Manual Deployment

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/README.md

Guides for manually building the package, testing its local installation, and deploying it to TestPyPI or PyPI using `twine`.

```bash
# Build package
uv build

# Test installation locally
uv pip install dist/pyaibridge-*.whl

# Deploy using scripts
uv run python scripts/deploy_testpypi.py  # TestPyPI
uv run twine upload dist/*                # PyPI
```

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

### Quick Start: Basic Chat Completion

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Home.md

Demonstrates how to create an LLM provider (e.g., OpenAI), construct a chat request with user messages, and send it to the provider to get a text response. It utilizes the `LLMFactory` for provider creation and `asyncio` for asynchronous operations.

```python
import asyncio
from pyaibridge import LLMFactory, ChatRequest, Message, MessageRole

async def main():
    # Create provider
    provider = LLMFactory.create("openai", api_key="your-api-key")
    
    # Create request
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.USER, content="Hello!")
        ],
        model="gpt-4.1-mini"
    )
    
    # Get response
    async with provider:
        response = await provider.chat(request)
        print(response.content)

asyncio.run(main())
```

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

### Install PyAIBridge

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/README.md

Installs the PyAIBridge library using pip. This is the first step to using the library.

```bash
pip install pyaibridge
```

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

### Quick Start: Basic Chat Completion

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Home

Demonstrates how to create an LLM provider (e.g., OpenAI), construct a chat request with user messages, and send it to the provider to get a text response. It utilizes the `LLMFactory` for provider creation and `asyncio` for asynchronous operations.

```python
import asyncio
from pyaibridge import LLMFactory, ChatRequest, Message, MessageRole

async def main():
    # Create provider
    provider = LLMFactory.create("openai", api_key="your-api-key")
    
    # Create request
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.USER, content="Hello!")
        ],
        model="gpt-4.1-mini"
    )
    
    # Get response
    async with provider:
        response = await provider.chat(request)
        print(response.content)

asyncio.run(main())
```

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

### Installation

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Home.md

Provides the command to install the PyAIBridge library using pip, the standard Python package installer.

```bash
pip install pyaibridge
```

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

### Installation

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Home

Provides the command to install the PyAIBridge library using pip, the standard Python package installer.

```bash
pip install pyaibridge
```

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

### Quick Start: Basic Chat

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/README.md

Demonstrates how to create an LLM provider, send a chat request, and print the response. It covers provider creation, request formatting, and asynchronous execution.

```python
import asyncio
from pyaibridge import LLMFactory, ChatRequest, Message, MessageRole, ProviderConfig

async def main():
    # Create provider
    config = ProviderConfig(api_key="your-api-key")
    provider = LLMFactory.create_provider("openai", config)
    
    # Create request
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.USER, content="Hello, world!")
        ],
        model="gpt-4.1-mini",
        max_tokens=100,
    )
    
    # Generate response
    async with provider:
        response = await provider.chat(request)
        print(response.content)

asyncio.run(main())
```

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

### Cost Tracking Example

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Demonstrates how to track API costs and token usage for multiple requests using the metrics utility. It initializes an LLM provider, sends several chat requests, calculates the cost for each, and records token and cost metrics. Finally, it prints a summary of the total cost and tokens used.

```python
from pyaibridge.utils.metrics import metrics
import asyncio
import os
from pyaibridge.llm import LLMFactory
from pyaibridge.chat import ChatRequest, Message, MessageRole

async def cost_tracking_example():
    """Track costs across multiple requests."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_API_KEY"))
    
    prompts = [
        "Explain machine learning",
        "Write a Python function",
        "Describe quantum physics",
        "Create a marketing plan"
    ]
    
    total_cost = 0.0
    
    async with provider:
        for i, prompt in enumerate(prompts, 1):
            request = ChatRequest(
                messages=[Message(role=MessageRole.USER, content=prompt)],
                model="gpt-4.1-mini",
                max_tokens=200
            )
            
            # Start timing
            metrics.start_timer("chat", "openai")
            
            try:
                response = await provider.chat(request)
                
                # Calculate cost
                cost = provider.calculate_cost(response.usage, response.model)
                total_cost += cost
                
                # Record metrics
                metrics.record_tokens(
                    "openai",
                    response.usage.prompt_tokens,
                    response.usage.completion_tokens
                )
                metrics.record_cost("openai", cost)
                
                print(f"Request {i}:")
                print(f"  Tokens: {response.usage.total_tokens}")
                print(f"  Cost: ${cost:.6f}")
                print(f"  Running total: ${total_cost:.6f}")
                print()
                
            finally:
                metrics.end_timer("chat", "openai")
    
    # Get final metrics
    final_metrics = metrics.get_summary()
    print("Final Statistics:")
    print(f"Total requests: {len(prompts)}")
    print(f"Total cost: ${total_cost:.6f}")
    print(f"Average cost per request: ${total_cost/len(prompts):.6f}")
    print(f"Total tokens: {final_metrics['openai']['total_tokens']}")

asyncio.run(cost_tracking_example())
```

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

### Cost Tracking Example

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Examples.md

Demonstrates how to track API costs and token usage for multiple requests using the metrics utility. It initializes an LLM provider, sends several chat requests, calculates the cost for each, and records token and cost metrics. Finally, it prints a summary of the total cost and tokens used.

```python
from pyaibridge.utils.metrics import metrics
import asyncio
import os
from pyaibridge.llm import LLMFactory
from pyaibridge.chat import ChatRequest, Message, MessageRole

async def cost_tracking_example():
    """Track costs across multiple requests."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_API_KEY"))
    
    prompts = [
        "Explain machine learning",
        "Write a Python function",
        "Describe quantum physics",
        "Create a marketing plan"
    ]
    
    total_cost = 0.0
    
    async with provider:
        for i, prompt in enumerate(prompts, 1):
            request = ChatRequest(
                messages=[Message(role=MessageRole.USER, content=prompt)],
                model="gpt-4.1-mini",
                max_tokens=200
            )
            
            # Start timing
            metrics.start_timer("chat", "openai")
            
            try:
                response = await provider.chat(request)
                
                # Calculate cost
                cost = provider.calculate_cost(response.usage, response.model)
                total_cost += cost
                
                # Record metrics
                metrics.record_tokens(
                    "openai",
                    response.usage.prompt_tokens,
                    response.usage.completion_tokens
                )
                metrics.record_cost("openai", cost)
                
                print(f"Request {i}:")
                print(f"  Tokens: {response.usage.total_tokens}")
                print(f"  Cost: ${cost:.6f}")
                print(f"  Running total: ${total_cost:.6f}")
                print()
                
            finally:
                metrics.end_timer("chat", "openai")
    
    # Get final metrics
    final_metrics = metrics.get_summary()
    print("Final Statistics:")
    print(f"Total requests: {len(prompts)}")
    print(f"Total cost: ${total_cost:.6f}")
    print(f"Average cost per request: ${total_cost/len(prompts):.6f}")
    print(f"Total tokens: {final_metrics['openai']['total_tokens']}")

asyncio.run(cost_tracking_example())
```

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

### Compare AI Provider Responses

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Compares responses from multiple AI providers (OpenAI, Google, Claude) for the same prompt. It initializes different providers, sets up corresponding models, and sends a chat request to each. The results, including content, token usage, and model name, are collected and printed. This example requires API keys for all providers to be set in the environment and skips providers for which keys are not available. Includes error handling for individual provider requests.

```python
async def compare_providers():
    """Compare responses across different providers."""
    
    providers = {
        "openai": LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY")),
        "google": LLMFactory.create("google", api_key=os.getenv("GOOGLE_API_KEY")),
        "claude": LLMFactory.create("claude", api_key=os.getenv("CLAUDE_API_KEY"))
    }
    
    models = {
        "openai": "gpt-4.1-mini",
        "google": "gemini-2.5-flash",
        "claude": "claude-4-haiku"
    }
    
    prompt = "Explain quantum computing in simple terms."
    message = Message(role=MessageRole.USER, content=prompt)
    
    results = {}
    
    for name, provider in providers.items():
        if provider is None:  # Skip if API key not available
            continue
            
        request = ChatRequest(
            messages=[message],
            model=models[name],
            max_tokens=200,
            temperature=0.7
        )
        
        try:
            async with provider:
                response = await provider.chat(request)
                
                results[name] = {
                    "content": response.content,
                    "tokens": response.usage.total_tokens,
                    "model": response.model
                }
                
        except Exception as e:
            results[name] = {"error": str(e)}
    
    # Display results
    for provider, result in results.items():
        print(f"\n{'='*50}")
        print(f"Provider: {provider.upper()}")
        print(f"{'='*50}")
        
        if "error" in result:
            print(f"Error: {result['error']}")
        else:
            print(f"Model: {result['model']}")
            print(f"Tokens: {result['tokens']}")
            print(f"Response: {result['content']}")

asyncio.run(compare_providers())
```

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

### Compare AI Provider Responses

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Examples.md

Compares responses from multiple AI providers (OpenAI, Google, Claude) for the same prompt. It initializes different providers, sets up corresponding models, and sends a chat request to each. The results, including content, token usage, and model name, are collected and printed. This example requires API keys for all providers to be set in the environment and skips providers for which keys are not available. Includes error handling for individual provider requests.

```python
async def compare_providers():
    """Compare responses across different providers."""
    
    providers = {
        "openai": LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY")),
        "google": LLMFactory.create("google", api_key=os.getenv("GOOGLE_API_KEY")),
        "claude": LLMFactory.create("claude", api_key=os.getenv("CLAUDE_API_KEY"))
    }
    
    models = {
        "openai": "gpt-4.1-mini",
        "google": "gemini-2.5-flash",
        "claude": "claude-4-haiku"
    }
    
    prompt = "Explain quantum computing in simple terms."
    message = Message(role=MessageRole.USER, content=prompt)
    
    results = {}
    
    for name, provider in providers.items():
        if provider is None:  # Skip if API key not available
            continue
            
        request = ChatRequest(
            messages=[message],
            model=models[name],
            max_tokens=200,
            temperature=0.7
        )
        
        try:
            async with provider:
                response = await provider.chat(request)
                
                results[name] = {
                    "content": response.content,
                    "tokens": response.usage.total_tokens,
                    "model": response.model
                }
                
        except Exception as e:
            results[name] = {"error": str(e)}
    
    # Display results
    for provider, result in results.items():
        print(f"\n{'='*50}")
        print(f"Provider: {provider.upper()}")
        print(f"{'='*50}")
        
        if "error" in result:
            print(f"Error: {result['error']}")
        else:
            print(f"Model: {result['model']}")
            print(f"Tokens: {result['tokens']}")
            print(f"Response: {result['content']}")

asyncio.run(compare_providers())
```

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

### Dynamic Model Selection in Python

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Demonstrates how to dynamically select the most appropriate AI model based on request characteristics such as prompt content and desired response length. It includes logic for handling long responses, code-related prompts, creative tasks, and a default cost-effective model. The example also shows how to use the `LLMFactory` to create a provider, send chat requests, calculate costs, and handle potential errors.

```python
import asyncio
import os

from pyaibridge.llm.factory import LLMFactory
from pyaibridge.llm.schema import ChatRequest, Message, MessageRole

async def dynamic_model_selection():
    """Dynamically select the best model based on request characteristics."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    def select_model(prompt: str, max_tokens: int) -> str:
        """Select the most appropriate model based on request characteristics."""
        
        # For long responses, use models with larger context
        if max_tokens > 1000:
            return "gpt-4.1"
        
        # For code-related prompts, use reasoning models
        code_keywords = ["python", "javascript", "function", "class", "algorithm", "code"]
        if any(keyword in prompt.lower() for keyword in code_keywords):
            return "o4-mini"  # Reasoning model for code
        
        # For creative tasks, use balanced model
        creative_keywords = ["story", "poem", "creative", "imagine", "artistic"]
        if any(keyword in prompt.lower() for keyword in creative_keywords):
            return "gpt-4.1-mini"
        
        # Default to cost-effective model
        return "gpt-4o-mini"
    
    test_prompts = [
        ("Write a Python function to sort a list", 200),
        ("Tell me a creative story about dragons", 500),
        ("Explain quantum mechanics in detail", 1200),
        ("What is the capital of France?", 50)
    ]
    
    async with provider:
        for prompt, max_tokens in test_prompts:
            # Dynamic model selection
            selected_model = select_model(prompt, max_tokens)
            
            request = ChatRequest(
                messages=[Message(role=MessageRole.USER, content=prompt)],
                model=selected_model,
                max_tokens=max_tokens
            )
            
            try:
                response = await provider.chat(request)
                cost = provider.calculate_cost(response.usage, response.model)
                
                print(f"Prompt: {prompt}")
                print(f"Selected model: {selected_model}")
                print(f"Tokens used: {response.usage.total_tokens}")
                print(f"Cost: ${cost:.6f}")
                print(f"Response: {response.content[:100]}...")
                print("-" * 50)
                
            except Exception as e:
                print(f"Error with prompt '{prompt}': {e}")

asyncio.run(dynamic_model_selection())
```

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

### Streaming with Progress Indicators

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Examples.md

Shows how to stream AI responses while providing real-time progress indicators. This example tracks the number of chunks received, word count, and words per second, offering insights into the generation process for longer outputs.

```python
import time
import os
import asyncio
from pyaibridge import LLMFactory, Message, MessageRole, ChatRequest

async def streaming_with_progress():
    """Streaming with progress indicators."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.USER, content="Write a detailed story about space exploration.")
        ],
        model="gpt-4.1-mini",
        max_tokens=1000,
        stream=True
    )
    
    start_time = time.time()
    chunk_count = 0
    word_count = 0
    
    print("Story Generation Starting...\n")
    
    async with provider:
        async for chunk in provider.stream_chat(request):
            if chunk.content:
                print(chunk.content, end='', flush=True)
                chunk_count += 1
                word_count += len(chunk.content.split())
                
                # Show progress every 100 chunks
                if chunk_count % 100 == 0:
                    elapsed = time.time() - start_time
                    wps = word_count / elapsed if elapsed > 0 else 0
                    print(f"\n[Progress: {chunk_count} chunks, {word_count} words, {wps:.1f} words/sec]\n", end='')
            
            if chunk.finish_reason:
                elapsed = time.time() - start_time
                print(f"\n\n[Completed in {elapsed:.1f}s - {chunk_count} chunks, {word_count} words]")
                break

asyncio.run(streaming_with_progress())
```

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

### Dynamic Model Selection in Python

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Examples.md

Demonstrates how to dynamically select the most appropriate AI model based on request characteristics such as prompt content and desired response length. It includes logic for handling long responses, code-related prompts, creative tasks, and a default cost-effective model. The example also shows how to use the `LLMFactory` to create a provider, send chat requests, calculate costs, and handle potential errors.

```python
import asyncio
import os

from pyaibridge.llm.factory import LLMFactory
from pyaibridge.llm.schema import ChatRequest, Message, MessageRole

async def dynamic_model_selection():
    """Dynamically select the best model based on request characteristics."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    def select_model(prompt: str, max_tokens: int) -> str:
        """Select the most appropriate model based on request characteristics."""
        
        # For long responses, use models with larger context
        if max_tokens > 1000:
            return "gpt-4.1"
        
        # For code-related prompts, use reasoning models
        code_keywords = ["python", "javascript", "function", "class", "algorithm", "code"]
        if any(keyword in prompt.lower() for keyword in code_keywords):
            return "o4-mini"  # Reasoning model for code
        
        # For creative tasks, use balanced model
        creative_keywords = ["story", "poem", "creative", "imagine", "artistic"]
        if any(keyword in prompt.lower() for keyword in creative_keywords):
            return "gpt-4.1-mini"
        
        # Default to cost-effective model
        return "gpt-4o-mini"
    
    test_prompts = [
        ("Write a Python function to sort a list", 200),
        ("Tell me a creative story about dragons", 500),
        ("Explain quantum mechanics in detail", 1200),
        ("What is the capital of France?", 50)
    ]
    
    async with provider:
        for prompt, max_tokens in test_prompts:
            # Dynamic model selection
            selected_model = select_model(prompt, max_tokens)
            
            request = ChatRequest(
                messages=[Message(role=MessageRole.USER, content=prompt)],
                model=selected_model,
                max_tokens=max_tokens
            )
            
            try:
                response = await provider.chat(request)
                cost = provider.calculate_cost(response.usage, response.model)
                
                print(f"Prompt: {prompt}")
                print(f"Selected model: {selected_model}")
                print(f"Tokens used: {response.usage.total_tokens}")
                print(f"Cost: ${cost:.6f}")
                print(f"Response: {response.content[:100]}...")
                print("-" * 50)
                
            except Exception as e:
                print(f"Error with prompt '{prompt}': {e}")

asyncio.run(dynamic_model_selection())
```

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

### Streaming with Progress Indicators

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Shows how to stream AI responses while providing real-time progress indicators. This example tracks the number of chunks received, word count, and words per second, offering insights into the generation process for longer outputs.

```python
import time
import os
import asyncio
from pyaibridge import LLMFactory, Message, MessageRole, ChatRequest

async def streaming_with_progress():
    """Streaming with progress indicators."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.USER, content="Write a detailed story about space exploration.")
        ],
        model="gpt-4.1-mini",
        max_tokens=1000,
        stream=True
    )
    
    start_time = time.time()
    chunk_count = 0
    word_count = 0
    
    print("Story Generation Starting...\n")
    
    async with provider:
        async for chunk in provider.stream_chat(request):
            if chunk.content:
                print(chunk.content, end='', flush=True)
                chunk_count += 1
                word_count += len(chunk.content.split())
                
                # Show progress every 100 chunks
                if chunk_count % 100 == 0:
                    elapsed = time.time() - start_time
                    wps = word_count / elapsed if elapsed > 0 else 0
                    print(f"\n[Progress: {chunk_count} chunks, {word_count} words, {wps:.1f} words/sec]\n", end='')
            
            if chunk.finish_reason:
                elapsed = time.time() - start_time
                print(f"\n\n[Completed in {elapsed:.1f}s - {chunk_count} chunks, {word_count} words]")
                break

asyncio.run(streaming_with_progress())
```

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

### Budget Management Example

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Illustrates how to manage API usage within a predefined budget. This function sets a maximum budget and tracks spending across multiple requests. It checks the budget before each request and stops if the budget limit is reached or exceeded. It uses a cheaper model to stay within the budget.

```python
import asyncio
import os
from pyaibridge.llm import LLMFactory
from pyaibridge.chat import ChatRequest, Message, MessageRole

async def budget_management():
    """Manage API usage within budget constraints."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    max_budget = 0.10  # $0.10 budget
    current_spend = 0.0
    
    prompts = [
        "Explain Python",
        "Write JavaScript code",
        "Describe databases",
        "Create API documentation",
        "Design system architecture"
    ]
    
    async with provider:
        for prompt in prompts:
            # Check budget before request
            if current_spend >= max_budget:
                print(f"Budget limit reached: ${current_spend:.6f}")
                break
            
            request = ChatRequest(
                messages=[Message(role=MessageRole.USER, content=prompt)],
                model="gpt-4o-mini",  # Cheaper model
                max_tokens=100
            )
            
            try:
                response = await provider.chat(request)
                cost = provider.calculate_cost(response.usage, response.model)
                current_spend += cost
                
                print(f"Prompt: {prompt[:30]}...")
                print(f"Cost: ${cost:.6f} (Total: ${current_spend:.6f})")
                print(f"Response: {response.content[:100]}...")
                print(f"Remaining budget: ${max_budget - current_spend:.6f}")
                print("-" * 50)
                
            except Exception as e:
                print(f"Error with prompt '{prompt}': {e}")

asyncio.run(budget_management())
```

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

### Budget Management Example

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Examples.md

Illustrates how to manage API usage within a predefined budget. This function sets a maximum budget and tracks spending across multiple requests. It checks the budget before each request and stops if the budget limit is reached or exceeded. It uses a cheaper model to stay within the budget.

```python
import asyncio
import os
from pyaibridge.llm import LLMFactory
from pyaibridge.chat import ChatRequest, Message, MessageRole

async def budget_management():
    """Manage API usage within budget constraints."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    max_budget = 0.10  # $0.10 budget
    current_spend = 0.0
    
    prompts = [
        "Explain Python",
        "Write JavaScript code",
        "Describe databases",
        "Create API documentation",
        "Design system architecture"
    ]
    
    async with provider:
        for prompt in prompts:
            # Check budget before request
            if current_spend >= max_budget:
                print(f"Budget limit reached: ${current_spend:.6f}")
                break
            
            request = ChatRequest(
                messages=[Message(role=MessageRole.USER, content=prompt)],
                model="gpt-4o-mini",  # Cheaper model
                max_tokens=100
            )
            
            try:
                response = await provider.chat(request)
                cost = provider.calculate_cost(response.usage, response.model)
                current_spend += cost
                
                print(f"Prompt: {prompt[:30]}...")
                print(f"Cost: ${cost:.6f} (Total: ${current_spend:.6f})")
                print(f"Response: {response.content[:100]}...")
                print(f"Remaining budget: ${max_budget - current_spend:.6f}")
                print("-" * 50)
                
            except Exception as e:
                print(f"Error with prompt '{prompt}': {e}")

asyncio.run(budget_management())
```

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

### Basic Streaming Example

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Streaming

Demonstrates how to enable and receive streaming responses from an LLM provider in real-time. It initializes a provider, creates a chat request with streaming enabled, and iterates through the streamed chunks, printing their content as they arrive.

```python
import asyncio
from pyaibridge import LLMFactory, ChatRequest, Message, MessageRole

async def basic_streaming():
    provider = LLMFactory.create("openai", api_key="sk-...")
    
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.USER, content="Write a story about a robot")
        ],
        model="gpt-4.1-mini",
        max_tokens=500,
        stream=True  # Enable streaming
    )
    
    async with provider:
        async for chunk in provider.stream_chat(request):
            print(chunk.content, end='', flush=True)
        print()  # New line at end

asyncio.run(basic_streaming())
```

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

### Basic Streaming Example

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Streaming.md

Demonstrates how to enable and receive streaming responses from an LLM provider in real-time. It initializes a provider, creates a chat request with streaming enabled, and iterates through the streamed chunks, printing their content as they arrive.

```python
import asyncio
from pyaibridge import LLMFactory, ChatRequest, Message, MessageRole

async def basic_streaming():
    provider = LLMFactory.create("openai", api_key="sk-...")
    
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.USER, content="Write a story about a robot")
        ],
        model="gpt-4.1-mini",
        max_tokens=500,
        stream=True  # Enable streaming
    )
    
    async with provider:
        async for chunk in provider.stream_chat(request):
            print(chunk.content, end='', flush=True)
        print()  # New line at end

asyncio.run(basic_streaming())
```

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

### Interactive Conversation

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Enables an interactive chat session where the user can converse with an AI model, maintaining conversation history. The example continuously prompts the user for input, adds it to the conversation, retrieves a response from the AI, and prints it. It handles user input for quitting and includes basic error handling for the AI interaction. Requires an API key for the specified provider to be set in the environment.

```python
async def interactive_conversation():
    """Interactive chat with conversation history."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    conversation = [
        Message(role=MessageRole.SYSTEM, content="You are a knowledgeable tutor.")
    ]
    
    async with provider:
        while True:
            # Get user input
            user_input = input("\nYou: ")
            if user_input.lower() in ['quit', 'exit']:
                break
            
            # Add user message
            conversation.append(
                Message(role=MessageRole.USER, content=user_input)
            )
            
            # Get response
            request = ChatRequest(
                messages=conversation,
                model="gpt-4.1-mini",
                max_tokens=300
            )
            
            try:
                response = await provider.chat(request)
                print(f"Assistant: {response.content}")
                
                # Add assistant response to conversation
                conversation.append(
                    Message(role=MessageRole.ASSISTANT, content=response.content)
                )
                
            except Exception as e:
                print(f"Error: {e}")

asyncio.run(interactive_conversation())
```

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

### Interactive Conversation

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Examples.md

Enables an interactive chat session where the user can converse with an AI model, maintaining conversation history. The example continuously prompts the user for input, adds it to the conversation, retrieves a response from the AI, and prints it. It handles user input for quitting and includes basic error handling for the AI interaction. Requires an API key for the specified provider to be set in the environment.

```python
async def interactive_conversation():
    """Interactive chat with conversation history."""
    
    provider = LLMFactory.create("openai", api_key=os.getenv("OPENAI_API_KEY"))
    
    conversation = [
        Message(role=MessageRole.SYSTEM, content="You are a knowledgeable tutor.")
    ]
    
    async with provider:
        while True:
            # Get user input
            user_input = input("\nYou: ")
            if user_input.lower() in ['quit', 'exit']:
                break
            
            # Add user message
            conversation.append(
                Message(role=MessageRole.USER, content=user_input)
            )
            
            # Get response
            request = ChatRequest(
                messages=conversation,
                model="gpt-4.1-mini",
                max_tokens=300
            )
            
            try:
                response = await provider.chat(request)
                print(f"Assistant: {response.content}")
                
                # Add assistant response to conversation
                conversation.append(
                    Message(role=MessageRole.ASSISTANT, content=response.content)
                )
                
            except Exception as e:
                print(f"Error: {e}")

asyncio.run(interactive_conversation())
```

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

### Best Practice: Provider Context Manager

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Factory-Pattern.md

Illustrates the use of the provider as an asynchronous context manager. This ensures proper setup and teardown (e.g., connection management) for the provider instance, simplifying resource handling.

```python
async def example():
    provider = LLMFactory.create("openai", api_key="...")
    
    async with provider:
        # Provider is connected and ready
        response = await provider.chat(request)
        # Provider is automatically disconnected
```

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

### Best Practice: Provider Context Manager

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Factory-Pattern

Illustrates the use of the provider as an asynchronous context manager. This ensures proper setup and teardown (e.g., connection management) for the provider instance, simplifying resource handling.

```python
async def example():
    provider = LLMFactory.create("openai", api_key="...")
    
    async with provider:
        # Provider is connected and ready
        response = await provider.chat(request)
        # Provider is automatically disconnected
```

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

### Google Gemini Provider Streaming

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Streaming.md

Illustrates streaming with the Google Gemini provider. This example shows how to initialize the provider and make a streaming request, noting that Gemini may provide larger content chunks compared to other providers.

```python
async def gemini_streaming():
    provider = LLMFactory.create("google", api_key="AIza...")
    
    request = ChatRequest(
        messages=[Message(role=MessageRole.USER, content="Explain machine learning")],
        model="gemini-2.5-flash",
        stream=True
    )
    
    async with provider:
        async for chunk in provider.stream_chat(request):
            # Gemini may provide larger chunks
            if chunk.content:
                print(chunk.content, end='', flush=True)
```

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

### Google Gemini Provider Streaming

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Streaming

Illustrates streaming with the Google Gemini provider. This example shows how to initialize the provider and make a streaming request, noting that Gemini may provide larger content chunks compared to other providers.

```python
async def gemini_streaming():
    provider = LLMFactory.create("google", api_key="AIza...")
    
    request = ChatRequest(
        messages=[Message(role=MessageRole.USER, content="Explain machine learning")],
        model="gemini-2.5-flash",
        stream=True
    )
    
    async with provider:
        async for chunk in provider.stream_chat(request):
            # Gemini may provide larger chunks
            if chunk.content:
                print(chunk.content, end='', flush=True)
```

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

### Model Selection Guide: General Use

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Model-Support.md

Provides recommendations for AI models suitable for general use, categorized by quality (High, Balanced, Cost-Effective). This helps users choose a model that best fits their needs for everyday tasks.

```APIDOC
Model Selection Guide - General Use:

High Quality: `gpt-4.1`, `claude-opus-4-20250514`, `gemini-2.5-pro`, `grok-4-0709`
Balanced: `gpt-4.1-mini`, `claude-sonnet-4-20250514`, `gemini-2.5-flash`, `grok-3`
Cost-Effective: `gpt-4.1-nano`, `gemini-2.5-flash-lite-preview-06-17`, `grok-3-mini`, `claude-3-haiku-20240307`
```

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

### Model Selection Guide: General Use

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Model-Support

Provides recommendations for AI models suitable for general use, categorized by quality (High, Balanced, Cost-Effective). This helps users choose a model that best fits their needs for everyday tasks.

```APIDOC
Model Selection Guide - General Use:

High Quality: `gpt-4.1`, `claude-opus-4-20250514`, `gemini-2.5-pro`, `grok-4-0709`
Balanced: `gpt-4.1-mini`, `claude-sonnet-4-20250514`, `gemini-2.5-flash`, `grok-3`
Cost-Effective: `gpt-4.1-nano`, `gemini-2.5-flash-lite-preview-06-17`, `grok-3-mini`, `claude-3-haiku-20240307`
```

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

### Fallback Provider Pattern

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Demonstrates how to use multiple AI providers in a fallback sequence. If the primary provider fails or is unavailable, the system attempts to use the next provider in the list. This ensures greater resilience and availability of AI services.

```python
import os
import asyncio
from pyaibridge import LLMFactory, Message, MessageRole, ChatRequest

async def fallback_providers():
    """Use multiple providers as fallbacks."""
    
    # Priority order of providers
    provider_configs = [
        ("openai", "gpt-4.1-mini", os.getenv("OPENAI_API_KEY")),
        ("google", "gemini-2.5-flash", os.getenv("GOOGLE_API_KEY")),
        ("claude", "claude-4-haiku", os.getenv("CLAUDE_API_KEY"))
    ]
    
    message = Message(role=MessageRole.USER, content="Write a haiku about coding.")
    
    for provider_name, model, api_key in provider_configs:
        if not api_key:
            continue
            
        try:
            provider = LLMFactory.create(provider_name, api_key=api_key)
            request = ChatRequest(messages=[message], model=model)
            
            async with provider:
                response = await provider.chat(request)
                print(f"Success with {provider_name}: {response.content}")
                return response
                
        except Exception as e:
            print(f"Failed with {provider_name}: {e}")
            continue
    
    print("All providers failed!")

asyncio.run(fallback_providers())
```

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

### Contributing Guidelines

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/README.md

Outlines the steps for contributing to the project, including forking the repository, creating feature branches, adding tests, running linters, and submitting pull requests.

```bash
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Add tests for new functionality
4. Ensure all tests pass (`uv run pytest`)
5. Run linting (`uv run ruff check src/`)
6. Submit a pull request
```

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

### Model Selection Guide: Speed & Performance

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Model-Support.md

Guides users in selecting AI models based on speed and performance requirements, categorized as Fastest, Fast, and Balanced. This is useful for time-sensitive applications or when optimizing for throughput.

```APIDOC
Model Selection Guide - Speed & Performance:

Fastest: `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite`, `gpt-4.1-nano`, `grok-3-fast`
Fast: `gemini-2.5-flash`, `gemini-2.0-flash`, `claude-3-5-haiku-20241022`, `grok-3-mini`
Balanced: `gpt-4.1-mini`, `claude-sonnet-4-20250514`, `grok-3`
```

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

### Simple Chat Completion

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Examples

Demonstrates a basic chat completion using a single AI provider. It initializes the provider, creates a chat request with system and user messages, sends the request, and prints the response content and token usage. Requires an API key for the specified provider to be set in the environment.

```python
import asyncio
import os
from pyaibridge import LLMFactory, ChatRequest, Message, MessageRole

async def simple_chat():
    """Basic chat completion example."""
    
    # Create provider
    provider = LLMFactory.create(
        "openai", 
        api_key=os.getenv("OPENAI_API_KEY")
    )
    
    # Create request
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.SYSTEM, content="You are a helpful assistant."),
            Message(role=MessageRole.USER, content="What is Python?")
        ],
        model="gpt-4.1-mini",
        max_tokens=150,
        temperature=0.7
    )
    
    # Get response
    async with provider:
        response = await provider.chat(request)
        print(f"Response: {response.content}")
        print(f"Tokens used: {response.usage.total_tokens}")

asyncio.run(simple_chat())
```

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

### Simple Chat Completion

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Examples.md

Demonstrates a basic chat completion using a single AI provider. It initializes the provider, creates a chat request with system and user messages, sends the request, and prints the response content and token usage. Requires an API key for the specified provider to be set in the environment.

```python
import asyncio
import os
from pyaibridge import LLMFactory, ChatRequest, Message, MessageRole

async def simple_chat():
    """Basic chat completion example."""
    
    # Create provider
    provider = LLMFactory.create(
        "openai", 
        api_key=os.getenv("OPENAI_API_KEY")
    )
    
    # Create request
    request = ChatRequest(
        messages=[
            Message(role=MessageRole.SYSTEM, content="You are a helpful assistant."),
            Message(role=MessageRole.USER, content="What is Python?")
        ],
        model="gpt-4.1-mini",
        max_tokens=150,
        temperature=0.7
    )
    
    # Get response
    async with provider:
        response = await provider.chat(request)
        print(f"Response: {response.content}")
        print(f"Tokens used: {response.usage.total_tokens}")

asyncio.run(simple_chat())
```

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

### Model Selection Guide: Speed & Performance

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Model-Support

Guides users in selecting AI models based on speed and performance requirements, categorized as Fastest, Fast, and Balanced. This is useful for time-sensitive applications or when optimizing for throughput.

```APIDOC
Model Selection Guide - Speed & Performance:

Fastest: `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite`, `gpt-4.1-nano`, `grok-3-fast`
Fast: `gemini-2.5-flash`, `gemini-2.0-flash`, `claude-3-5-haiku-20241022`, `grok-3-mini`
Balanced: `gpt-4.1-mini`, `claude-sonnet-4-20250514`, `grok-3`
```

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

### Model Selection Guide: Reasoning & Analysis

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Model-Support.md

Recommends AI models for reasoning and analysis tasks, categorized by performance level (Best, Good, Budget). This guide assists users in selecting models optimized for complex analytical workloads.

```APIDOC
Model Selection Guide - Reasoning & Analysis:

Best: `o3-pro`, `claude-opus-4-20250514`, `grok-4-0709`, `claude-3-7-sonnet-20250219`
Good: `o3`, `claude-sonnet-4-20250514`, `grok-3`
Budget: `o4-mini`, `claude-3-5-haiku-20241022`, `grok-3-mini`
```

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

### Model Selection Guide: Reasoning & Analysis

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Model-Support

Recommends AI models for reasoning and analysis tasks, categorized by performance level (Best, Good, Budget). This guide assists users in selecting models optimized for complex analytical workloads.

```APIDOC
Model Selection Guide - Reasoning & Analysis:

Best: `o3-pro`, `claude-opus-4-20250514`, `grok-4-0709`, `claude-3-7-sonnet-20250219`
Good: `o3`, `claude-sonnet-4-20250514`, `grok-3`
Budget: `o4-mini`, `claude-3-5-haiku-20241022`, `grok-3-mini`
```

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

### Deployment to PyPI

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/README.md

Initiates automated deployment to PyPI by creating a GitHub release. This process is managed by GitHub Actions upon release creation.

```bash
gh release create v0.1.3 --title "Release v0.1.3"
```

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

### Using Context Managers

Source: https://github.com/sixteen-dev/pyaibridge/wiki/Chat-Completion

Demonstrates the recommended practice of using context managers (`async with`) with providers to ensure proper resource management and cleanup.

```python
async with provider:
    response = await provider.chat(request)
```

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

### Using Context Managers

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Chat-Completion.md

Demonstrates the recommended practice of using context managers (`async with`) with providers to ensure proper resource management and cleanup.

```python
async with provider:
    response = await provider.chat(request)
```

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

### Create LLM Provider Instances

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/wiki/Factory-Pattern.md

Demonstrates how to create instances of different LLM providers (OpenAI, Google, Claude) using the LLMFactory. Requires the 'pyaibridge' library.

```python
from pyaibridge import LLMFactory

# Create providers
openai_provider = LLMFactory.create("openai", api_key="sk-...")
google_provider = LLMFactory.create("google", api_key="AIza...")
claude_provider = LLMFactory.create("claude", api_key="sk-ant...")
```

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

### Development Workflow

Source: https://github.com/sixteen-dev/pyaibridge/blob/main/README.md

Provides commands for setting up the development environment, running tests, and performing linting and type checking. It utilizes `uv` for package management and `pytest`, `ruff`, and `mypy` for code quality assurance.

```bash
# Clone repository
git clone https://github.com/sixteen-dev/pyaibridge.git
cd pyaibridge

# Install with development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check src/
uv run ruff format src/

# Run type checking
uv run mypy src/
```