tatlock/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.2.0 - 2025-12-06

Added

PydanticAI Integration (Phase 1)

• Real Tatlock agent using PydanticAI with Ollama backend (mistral-nemo:latest)
• British butler personality with research-oriented mindset
• Lazy agent initialization to avoid connection issues in tests
• Streaming response integration with reasoning output
• Error handling for PydanticAI-specific exceptions

Permanent Tools (Phase 1)

• Calculator tool (src/agents/tools.py):
  • Safe mathematical expression evaluation using restricted namespace
  • Support for arithmetic, algebra, trigonometry, logarithms
  • Math functions: sqrt, sin, cos, tan, log, exp, etc.
  • Constants: pi, e
  • Integer result formatting (removes unnecessary decimals)
• Date/Time toolkit:
  • get_current_datetime: Current date/time in multiple formats
  • calculate_time_offset: Relative date calculations ("1 week ago", "2 months from now")
  • time_difference: Human-readable time differences between dates
• Web Search tool:
  • SearXNG integration for privacy-preserving web search
  • Automatic fallback from production to localhost in development
  • Formatted search results with titles, URLs, and snippets
  • Configurable result limits (max 10)

Tool Framework

• PydanticAI tool registration with @agent.tool decorator
• Tool descriptions visible to LLM for intelligent usage
• Async tool support for I/O operations
• Error handling with string-based error messages
• Tool usage guidelines in system prompt

Configuration

• SearXNG configuration in src/core/config.py:
  • SEARXNG_HOST with development fallback
  • SEARXNG_TIMEOUT setting
• Updated .env.example with SearXNG configuration
• Ollama configuration documentation

Testing

• 26 new tool tests (tests/agents/test_tools.py):
  • 7 calculator tests (arithmetic, functions, error handling)
  • 14 date/time tests (current time, offsets, differences)
  • 5 web search tests (mocked HTTP client)
• Updated registry tests for tools capability
• Total: 131 tests, 81.78% coverage (up from 95 tests, 78.95%)

Documentation

• Comprehensive README.md updates:
  • Tatlock agent capabilities and tool descriptions
  • Requirements section with Ollama and SearXNG setup
  • Configuration examples for external services
  • Tool usage examples and philosophy
  • Troubleshooting for Ollama and SearXNG
  • Updated test statistics
• AGENTS.md refactored for LLM development:
  • PydanticAI tool registration pattern
  • Tool implementation guidelines
  • Removed project status, focused on development instructions
• IMPLEMENTATION_ROADMAP.md updates:
  • Phase 1 marked as "MOSTLY COMPLETE"
  • Detailed completion status for each deliverable
  • Updated current state summary

Changed

• Tatlock agent converted from mock to real PydanticAI implementation
• Tatlock capabilities updated: tools: True
• Streaming coordination now handles chunk-based delivery (50 chars) to preserve markdown
• Chat service streaming updated to preserve formatting
• System prompt enhanced with tool usage guidelines and research mindset
• Agent initialization changed to lazy pattern for better testability

Fixed

• Text duplication bug in streaming responses (proper delta calculation)
• Markdown formatting preservation in streamed responses
• GeneratorExit errors from async context managers in generators
• PydanticAI API usage (result.output instead of result.data)

0.1.1 - 2025-12-06

Added

Agent Interface (Phase 1)

• Abstract AgentInterface base class for model abstraction
• LoremTesterAgent: Full-featured mock agent with realistic behavior
  • Configurable reasoning effort levels (none, minimal, low, medium, high, xhigh)
  • Random tool/function call generation for testing
  • Error triggers: rate_limit, context_overflow, invalid_tool
  • Temperature-based response variation
• TatlockAgent: Placeholder for future PydanticAI integration
• ModelRegistry: Centralized model management and discovery
• 18 agent tests with comprehensive coverage

Responses API (Phases 2, 3, 6)

• OpenAI Responses API format with structured output (/v1/responses)
  • Reasoning items (thinking summaries with configurable effort)
  • Function call items (tool execution simulation)
  • Message items (assistant responses with output_text)
  • Streaming and non-streaming modes
• Real-time streaming with SSE-Starlette
• Conversation history management (Phase 3):
  • Hybrid client/server approach (client maintains state, server tracks)
  • Auto-generated deterministic conversation IDs from message hash
  • Configurable max turns with automatic trimming (default: 20)
  • Context window management with approximate token counting
  • Token usage statistics
  • Placeholder for future vector memory (Qdrant)
• Advanced features (Phase 6):
  • Parameter validation with Pydantic field validators
  • Temperature: 0.0-2.0 range enforcement
  • Reasoning effort: 6 levels validation
  • Max output tokens: positive integer enforcement
  • Stop sequences: up to 4, non-empty strings
  • Real-time stop sequence detection during streaming
  • Real-time max tokens enforcement with token counting
• 45 Responses API tests (router, error handling, history, advanced features)

Chat Completions Wrapper (Phase 5)

• OpenAI Chat Completions compatibility layer (/v1/chat/completions)
• Single source of truth architecture (wraps Responses API)
• Automatic reasoning generation
• Converts reasoning items to <think> tags for Open WebUI
• Pipeline prefix preservation
• System message support
• Enhanced error types (RateLimitError, ContextLengthError)
• 12 Chat Completions tests (router + streaming wrapper)

Application Infrastructure

• FastAPI application factory pattern
• CORS middleware with configurable origins
• Global exception handlers:
  • AppException handler for custom errors
  • RequestValidationError handler for Pydantic validation
  • General exception handler for unexpected errors
• Lifespan management for startup/shutdown
• OpenAPI schema with interactive documentation
• 16 main application tests

Testing Infrastructure

• Comprehensive test suite: 95 tests, 78.95% coverage (up from 62%)
• Async test support with pytest-asyncio
• Test fixtures for sync and async clients
• Integration tests for all API endpoints
• Streaming functionality tests
• Parameter validation tests
• Error handling tests
• Conversation history tests

Documentation

• Complete README.md rewrite with hybrid architecture
• Architecture diagrams and decision documentation
• AGENTS.md with technical implementation details
• API usage examples for all endpoints
• Conversation history guide
• Open WebUI integration instructions
• Troubleshooting section
• Implementation planning documents

Changed

• Hybrid architecture with Responses API as primary endpoint
• Chat Completions now wraps Responses API (no duplicate logic)
• Enhanced error handling with OpenAI-compatible format
• Improved streaming with word-by-word delivery
• Better test organization with domain-based structure

Security

• Minor version locking for all dependencies
• All packages CVE-checked (as of 2025-12-06)
• Environment variable protection via .gitignore
• No known vulnerabilities in dependency tree
• Input validation on all API endpoints

0.1.0 - 2025-12-06

Added

• Project initialization
• Python 3.12.11 environment
• FastAPI 0.123.9 web framework
• PydanticAI 1.27.0 dependency (ready for future integration)
• Mock chat completions (lorem ipsum responses)
• Mock model listing (mistral-nemo:latest)
• Testing infrastructure (pytest, coverage, ruff, mypy)
• Configuration management with pydantic-settings
• CORS middleware
• Exception handlers (OpenAI-compatible error format)