pydantic3 🚀

A powerful Python framework for building AI applications with structured responses, powered by Pydantic AI and OpenRouter.

Features 🌟

• 🔒 Type-Safe Responses: Built on Pydantic AI for robust type validation
• 🌐 Online Search: Real-time internet access for up-to-date information
• 💰 Budget Control: Built-in cost tracking and budget management
• 📊 Usage Monitoring: Detailed token and cost tracking
• 🔄 Async Support: Both sync and async interfaces
• 🛡️ Error Handling: Comprehensive exception system
• 🎨 Colored Logging: Beautiful console output with detailed logs
• 🔍 Database Viewer: Built-in CLI tools to inspect models and usage databases

Installation 📦

Using Poetry (Recommended)

If you're using Poetry for dependency management, you can install the package with:

poetry add pydantic3

Using pip

If you're using pip, you can install the package with:

pip install pydantic3

Development Installation

Using Poetry (Recommended)

1. Clone the repository:

git clone https://github.com/markolofsen/pydantic3.git
cd pydantic3

2. Install dependencies:

poetry install

3. Run tests:

poetry run pytest

Using pip

1. Clone the repository:

git clone https://github.com/markolofsen/pydantic3.git
cd pydantic3

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install development dependencies:

pip install -e ".[dev]"

4. Run tests:

pytest

Quick Start ⚡

from typing import List
from pydantic import BaseModel, Field
from pydantic3 import PydanticAIClient


class ChatResponse(BaseModel):
    """Response format for chat messages."""
    message: str = Field(description="The chat response message")
    sources: List[str] = Field(default_factory=list, description="Sources used in the response")
    confidence: float = Field(ge=0, le=1, description="Confidence score of the response")


def main():
    # Initialize client with usage tracking using context manager
    with PydanticAIClient(
        model_name="openai/gpt-4o-mini-2024-07-18",
        client_id="test_client",
        user_id="test_user",
        verbose=False,
        retries=3,
        online=True,
        # max_budget=0.0003
    ) as client:
        try:
            # Set up the conversation with system message
            client.message_handler.add_message_system(
                "You are a helpful AI assistant. Be concise but informative."
            )

            # Add user message
            client.message_handler.add_message_user("What is the capital of France?")

            # Add structured data block (optional)
            client.message_handler.add_message_block(
                "CONTEXT",
                {
                    "topic": "Geography",
                    "region": "Europe",
                    "country": "France"
                }
            )

            # Generate response (synchronously)
            response: ChatResponse = client.generate(
                result_type=ChatResponse
            )

            # Print the response
            print("\nAI Response:")
            print(response.model_dump_json(indent=2))

            # Print usage statistics
            stats = client.get_usage_stats()
            if stats:
                print("\nUsage Statistics:")
                print(f"Total Requests: {stats.get('total_requests', 0)}")
                print(f"Total Cost: ${stats.get('total_cost', 0):.4f}")

        except Exception as e:
            print(f"\nError: {str(e)}")


if __name__ == "__main__":
    main()

CLI Tools 🔍

pydantic3 provides a convenient CLI tool for viewing and managing databases. The tool automatically opens your default browser when starting a database viewer.

# Launch interactive database viewer
pydantic3 --db

# Show help
pydantic3 --help

The interactive database viewer allows you to:

• View Models Database
• View Usage Database
• View Sessions Database
• Kill processes on specific ports
• Exit the viewer

The databases are automatically created and maintained as you use the library:

1. Models Database: Stores information about models, parameters, and capabilities
2. Usage Database: Tracks requests, tokens, costs, and usage statistics
3. Sessions Database: Stores conversation history and context

Key Features 🔑

Type-Safe Responses

from pydantic import BaseModel, Field
from typing import List

class Analysis(BaseModel):
    summary: str = Field(description="Brief summary")
    key_points: List[str] = Field(description="Main points")
    sentiment: float = Field(ge=-1, le=1, description="Sentiment score")

Online Search Mode

client = PydanticAIClient(
    model_name="openai/gpt-4o-mini",
    online=True  # Enables real-time internet access
)

Budget Management

client = PydanticAIClient(
    max_budget=1.0,  # Set $1 limit
    verbose=True     # See detailed cost tracking
)

try:
    response = client.generate(...)
except BudgetExceeded as e:
    print(f"Budget exceeded: ${e.current_cost:.4f} / ${e.budget_limit:.4f}")

Async Support

async def get_analysis():
    async with PydanticAIClient() as client:
        return await client.generate_async(
            result_type=Analysis,
            user_prompt="Analyze this text..."
        )

Error Handling

from pydantic3.client.exceptions import (
    BudgetExceeded, ValidationError, NetworkError, PydanticAIError
)

try:
    response = client.generate(...)
except BudgetExceeded as e:
    print(f"Budget limit reached: ${e.budget_limit:.4f}")
except ValidationError as e:
    print(f"Invalid response format: {e.errors}")
except NetworkError as e:
    print(f"Network error ({e.status_code}): {e.message}")
except PydanticAIError as e:
    print(f"Other error: {e}")

Usage Tracking

stats = client.get_usage_stats()
print(f"Total Requests: {stats['total_requests']}")
print(f"Total Tokens: {stats['total_tokens']}")
print(f"Total Cost: ${stats['total_cost']:.4f}")

Advanced Usage 🔧

Custom Response Models

class ProductAnalysis(BaseModel):
    name: str = Field(description="Product name")
    pros: List[str] = Field(description="Advantages")
    cons: List[str] = Field(description="Disadvantages")
    rating: float = Field(ge=0, le=10, description="Overall rating")
    recommendation: str = Field(description="Buy/Hold/Sell recommendation")

client = PydanticAIClient(online=True)
analysis = client.generate(
    result_type=ProductAnalysis,
    user_prompt="Analyze the latest iPhone"
)

Message Handling

# Add system context
client.message_handler.add_message_system(
    "You are a professional product analyst."
)

# Add user message
client.message_handler.add_message_user(
    "What are the pros and cons of Product X?"
)

# Generate structured response
response = client.generate(result_type=ProductAnalysis)

Support & Community 👥

• GitHub Issues
• Documentation
• GitHub Discussions

License 📝

This project is licensed under the MIT License - see the LICENSE file for details.

Credits ✨

Developed by Unrealos Inc. - We create innovative AI-powered solutions for business. Meet our team.