Skip to main content

A powerful AI framework with structured Pydantic responses, flexible LLM integration, and advanced agent capabilities

Project description

pydantic3 🚀

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

Documentation PyPI version License: MIT Security Policy PyUp Safety Known Vulnerabilities GitGuardian scan

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
  1. Install dependencies:
poetry install
  1. Run tests:
poetry run pytest

Using pip

  1. Clone the repository:
git clone https://github.com/markolofsen/pydantic3.git
cd pydantic3
  1. Create and activate a virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install development dependencies:
pip install -e ".[dev]"
  1. 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 👥

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydantic3-1.0.14.tar.gz (1.5 MB view details)

Uploaded Source

Built Distribution

pydantic3-1.0.14-py3-none-any.whl (87.7 kB view details)

Uploaded Python 3

File details

Details for the file pydantic3-1.0.14.tar.gz.

File metadata

  • Download URL: pydantic3-1.0.14.tar.gz
  • Upload date:
  • Size: 1.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.1 CPython/3.12.7 Darwin/23.3.0

File hashes

Hashes for pydantic3-1.0.14.tar.gz
Algorithm Hash digest
SHA256 fde2abbb54b70a093e633f93cae855deeb1be9d1afb52ee263931a8ce1031779
MD5 ff86b7d6e24aad81c88493d5986b0258
BLAKE2b-256 449881711944e04c514a83a90bcb4aa7adba1e431031b89191d58a17e5a4428e

See more details on using hashes here.

File details

Details for the file pydantic3-1.0.14-py3-none-any.whl.

File metadata

  • Download URL: pydantic3-1.0.14-py3-none-any.whl
  • Upload date:
  • Size: 87.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.1 CPython/3.12.7 Darwin/23.3.0

File hashes

Hashes for pydantic3-1.0.14-py3-none-any.whl
Algorithm Hash digest
SHA256 507ddc9ef39220cd9e90cccc68c68c0f9e57f0f0a04af2846af17b57ea2d7519
MD5 d60dd4d182fe93875ed6b51ef1e1bdb9
BLAKE2b-256 288cfe6e10f4b91517f1ef9db5c05c960b920860abbc8f01a875aaeba807ddc5

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page