feat: add Pydantic AI integration

[lfnovo]

Summary

• Add .to_pydantic_ai() method to all language models for seamless Pydantic AI agent integration
• Implement EsperantoPydanticModel adapter supporting tool calling, streaming, and structured output
• Enable provider switching (15+ providers) without changing agent code

Changes

New Files

• src/esperanto/integrations/pydantic_ai.py - Core adapter implementation
• src/esperanto/integrations/__init__.py - Module exports
• docs/advanced/pydantic-ai-integration.md - Full usage documentation
• examples/pydantic_ai_example.py - 6 example use cases
• tests/unit/test_pydantic_ai_adapter.py - 32 unit tests
• tests/integration/test_pydantic_ai_integration.py - 11 integration tests

Modified Files

• src/esperanto/providers/llm/base.py - Added to_pydantic_ai() method
• src/esperanto/providers/llm/google.py - Schema cleaning and tool response fixes
• pyproject.toml - Added pydantic-ai optional dependency
• README.md - Added feature mention and usage example
• CHANGELOG.md - Added release notes

Provider-Specific Fixes

• Google: Remove additionalProperties from JSON schemas (not supported)
• Google: Ensure tool responses are always dict/Struct (not primitives)
• Ollama: Return Tool objects instead of dicts for tool conversion

Testing

• 43 tests total (32 unit + 11 integration)
• Manually tested providers: OpenAI, Anthropic, Google, Groq, Mistral, Azure, xAI, Ollama, DeepSeek

Usage

from esperanto import AIFactory
from pydantic_ai import Agent

# Create model and convert to Pydantic AI
model = AIFactory.create_language("openai", "gpt-4o").to_pydantic_ai()

# Use with Pydantic AI Agent
agent = Agent(model)
result = await agent.run("What is the capital of France?")

Test plan

• Unit tests pass (uv run pytest tests/unit/test_pydantic_ai_adapter.py -v)
• Integration tests pass (uv run pytest tests/integration/test_pydantic_ai_integration.py -v)
• Manual testing with real APIs (OpenAI, Anthropic, Google, etc.)

[cubic-dev-ai]

No issues found across 15 files

[claude]

Code Review

Found 2 CLAUDE.md compliance issues that need to be addressed:

Issue 1: Missing integrations/ in Project Structure

File: CLAUDE.md (lines 13-30)

The Project Structure section doesn't include the new integrations/ directory added in this PR.

According to CLAUDE.md line 230-231:

AI docs: Keep CLAUDE.md files updated for AI context (this file structure)
Consistency: Documentation should reflect actual implementation

The structure should include:

├── src/esperanto/
│   ├── __init__.py                 # Public API exports
│   ├── factory.py                  # AIFactory for creating provider instances
│   ├── model_discovery.py          # Static model discovery system
│   ├── providers/                  # Provider implementations
│   ├── integrations/               # Third-party framework integrations
│   ├── common_types/               # Shared type definitions
│   └── utils/                      # Cross-cutting utilities

---

Issue 2: Missing integrations/ in Module Documentation

File: CLAUDE.md (lines 32-41)

The Module Documentation section doesn't reference the new src/esperanto/integrations/CLAUDE.md file.

According to CLAUDE.md line 29:

See detailed documentation in subdirectory CLAUDE.md files.

The Module Documentation section should include:

- **[src/esperanto/integrations/](src/esperanto/integrations/CLAUDE.md)**: Third-party framework integrations

This should be added alongside the existing entries for providers/, common_types/, and utils/.

---

Summary: The implementation itself is solid with no bugs found. These are documentation consistency issues that ensure the root CLAUDE.md accurately reflects the new project structure.