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.
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)
- Clone the repository:
git clone https://github.com/markolofsen/pydantic3.git
cd pydantic3
- Install dependencies:
poetry install
- Run tests:
poetry run pytest
Using pip
- Clone the repository:
git clone https://github.com/markolofsen/pydantic3.git
cd pydantic3
- Create and activate a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install development dependencies:
pip install -e ".[dev]"
- 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:
- Models Database: Stores information about models, parameters, and capabilities
- Usage Database: Tracks requests, tokens, costs, and usage statistics
- 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
fde2abbb54b70a093e633f93cae855deeb1be9d1afb52ee263931a8ce1031779
|
|
MD5 |
ff86b7d6e24aad81c88493d5986b0258
|
|
BLAKE2b-256 |
449881711944e04c514a83a90bcb4aa7adba1e431031b89191d58a17e5a4428e
|
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
507ddc9ef39220cd9e90cccc68c68c0f9e57f0f0a04af2846af17b57ea2d7519
|
|
MD5 |
d60dd4d182fe93875ed6b51ef1e1bdb9
|
|
BLAKE2b-256 |
288cfe6e10f4b91517f1ef9db5c05c960b920860abbc8f01a875aaeba807ddc5
|