- Add Dockerfile for containerized deployment (Python 3.12-slim, port 8000)
- Add Gitea Actions workflow triggered on release publish
- Builds and pushes to git.schweitz.net registry with latest and version tags
- Bump version to 1.0.0 marking production-ready release
- Update CHANGELOG with CI/CD and deployment configuration
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Document streaming bug fixes and new E2E test suite in changelog.
**Added:**
- End-to-End test suite documentation (17 tests)
- OpenAI API spec compliance verification
- Tool usage indicators and flexible LLM assertions
**Fixed:**
- Streaming text repetition (delta mode implementation)
- Broken tool execution in streaming
- Invalid schema parameters
- Case sensitivity in model routing
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Fix streaming issues that caused text repetition and broken tool execution
in Open WebUI. Implements real LLM streaming using PydanticAI's run_stream()
with delta=True instead of artificial word-by-word chunking.
**Fixed:**
- Text repetition in streaming output (was accumulating instead of deltas)
- Broken tool execution (tools now execute properly in streaming mode)
- Invalid 'thinking' parameter in ReasoningOutputItem schema
**Changes:**
- Add run_with_scoped_tools_stream() method to TatlockAgent
- Uses PydanticAI's run_stream() with delta=True for real deltas
- Properly streams LLM output with tool execution
- Update StreamingCoordinator.stream_response_with_steward()
- Uses new streaming method instead of fake word-by-word streaming
- Removes invalid thinking parameter from ReasoningOutputItem
- All streaming now uses actual LLM deltas, not accumulated text
Resolves streaming issues reported in Open WebUI where responses showed
repetitive text and tool calls appeared as raw JSON instead of executed results.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Update [Unreleased] section with:
Added:
- Conversation history support for multi-turn conversations
- PydanticAI message format conversion
- Full context passing via message_history
- Empty message filtering
- Tool call logging to reasoning output
- ToolCallTracker dependency system
- Emoji indicators for different tools (🔍🧮🕐)
- Visibility in <think> tags
Changed:
- Enhanced Tatlock agent with conversation memory
- All tools now log usage via RunContext
- Improved debug logging
Fixed:
- Conversation context maintenance across turns
- Tool usage transparency for users
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add comprehensive test suite covering:
Conversation History Tests:
- test_tatlock_conversation_history_memory: Verify Tatlock remembers user's
name and preferences across turns
- test_tatlock_multi_turn_context: Ensure context maintained over multiple
turns with topic references
- test_tatlock_conversation_history_with_tools: Test memory works correctly
when tools are used
Tool Call Logging Tests:
- test_tatlock_tool_call_logging_search: Verify search queries appear in
reasoning output with 🔍 emoji
- test_tatlock_tool_call_logging_calculator: Check calculator expressions
logged with 🧮 emoji
- test_tatlock_tool_call_logging_datetime: Ensure date/time operations shown
with 🕐 emoji
- test_tatlock_no_tool_calls_no_logging: Confirm tool logging only appears
when tools are actually used
All tests verify tool usage appears in <think> tags visible in Open WebUI.
Tests use non-streaming responses for deterministic assertions.
14/15 tests passing consistently (93% pass rate).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add two major features to enhance Tatlock's capabilities:
1. Conversation History Support:
- Convert OpenAI-format messages to PydanticAI ModelRequest/ModelResponse
- Pass full conversation context via message_history parameter
- Filter empty messages to prevent Ollama errors
- Add debug logging for message history construction
- Tatlock now remembers previous turns in multi-turn conversations
2. Tool Call Logging:
- Implement ToolCallTracker dependency for per-request tracking
- Tools log usage via RunContext deps parameter
- Web search: "🔍 Searching for: 'query'"
- Calculator: "🧮 Calculating: expression"
- Date/time: "🕐 Calculating date offset: description"
- Tool logs appear in reasoning output as <think> tags in Open WebUI
Both features improve user experience by maintaining conversation context
and providing transparency into tool usage.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add wakeup.sh script for convenient development server startup:
- Port 8000 availability check before starting
- Automatic virtual environment activation
- Log file management in logs/ directory
- Fresh log file on each startup (clears previous logs)
- Colored output for better visibility
- Real-time logging to both console and file
- Helpful error messages with troubleshooting commands
Convert Tatlock from mock to real PydanticAI agent:
- Connect to Ollama backend (mistral-nemo:latest)
- British butler personality with research-oriented mindset
- Lazy initialization pattern for better testability
- Register permanent tools (calculator, date/time, search)
- Streaming response support with reasoning output
- Error handling for PydanticAI exceptions
- Update registry tests for tools capability
- Add integration test for streaming functionality
- Add SEARXNG_HOST config with localhost:8087 default
- Add SEARXNG_TIMEOUT setting (30 seconds default)
- Update .env.example with SearXNG configuration
- Supports both local and production SearXNG instances
Created PHILOSOPHY.md to establish the foundational vision and
architectural patterns for the Tatlock system.
PHILOSOPHY.md:
- Establishes Tatlock as a homelab butler coordinating expert agents
- Defines the British household metaphor and two-tier architecture
- Documents the Steward (request analysis) and Butler (orchestration)
- Describes household staff roles (Handyman, Housekeeper, Secretary, Developer)
- Explains real-time reasoning transparency for UX
- Details model efficiency strategy (unified base model, specialized when needed)
- Sets modification policy: only update for architectural deviations
README.md:
- Streamlined header with link to PHILOSOPHY.md
- Simplified description to focus on practical usage
- Updated documentation section to prioritize PHILOSOPHY.md
- Maintained all usage examples and technical guides
AGENTS.md:
- Added prominent link to PHILOSOPHY.md at header
- Emphasized that development should align with philosophy
Documentation hierarchy:
1. PHILOSOPHY.md - Vision and architectural patterns (stable)
2. README.md - User guide and practical usage
3. AGENTS.md - LLM agent development guidelines
4. CHANGELOG.md - Version history
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Restructured README.md and AGENTS.md to eliminate duplication:
README.md (user-focused):
- Simplified to focus on project description and usage
- Quick start guide with installation steps
- API usage examples with curl commands
- Open WebUI integration guide
- Troubleshooting section
- Deployment recommendations
- Removed internal architectural details
AGENTS.md (LLM agent instructions):
- Retained detailed architectural decisions and rationale
- FastAPI best practices and patterns
- Development guidelines and code structure
- Documentation references for frameworks
- Testing strategy and coverage details
- Updated test coverage: 78.95% (95 tests)
- Common implementation patterns
Changes:
- README.md: Streamlined from 497 to 310 lines
- AGENTS.md: Updated test coverage numbers
- Clear separation: README for users, AGENTS for AI developers
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Version increment to mark basic setup completion milestone.
Changes:
- Updated APP_VERSION to 0.1.1 in src/core/config.py
- Released CHANGELOG.md [Unreleased] section as [0.1.1]
- Updated version links to use git.schweitz.net repository
This version represents the completion of all core infrastructure:
- Agent interface and implementations
- Responses API with full feature set
- Chat Completions wrapper
- Comprehensive test coverage (95 tests, 78.95%)
- Production-ready architecture
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
IMPLEMENTATION_PLAN.md:
- Phase-by-phase implementation plan
- Success criteria for each phase
- Testing requirements
- Dependencies and prerequisites
CLEANUP_TODO.md:
- Architecture decision log
- Future considerations and trade-offs
- Migration path notes
- Technical debt tracking
These documents provide context for implementation decisions
and serve as a reference for future development.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Application Configuration:
- FastAPI application factory pattern
- CORS middleware for cross-origin support
- Global exception handlers for consistent error responses
- AppException handler for custom errors
- RequestValidationError handler for Pydantic validation
- General exception handler for unexpected errors
- Lifespan management for startup/shutdown events
- Router registration for all API endpoints
- OpenAPI schema with interactive documentation
Models Service:
- Integration with ModelRegistry
- List available models endpoint
- Model capability discovery
Test Infrastructure:
- Pytest configuration with async support
- Test client fixtures for sync and async testing
- Comprehensive main application tests (14 tests):
- App creation and metadata
- Router registration verification
- CORS middleware and functionality
- Exception handler registration and behavior
- Lifespan event handling
- OpenAPI schema generation
- Documentation accessibility
- Validation error handling
- Models API tests (2 tests)
- Total: 95 tests, 78.95% coverage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements Phase 5: OpenAI Chat Completions compatibility layer
Features:
- Wraps Responses API for single source of truth
- Automatically enables reasoning generation
- Converts reasoning items to <think> tags for Open WebUI
- Maintains OpenAI-compatible chat completion format
- Supports both streaming and non-streaming modes
- Pipeline prefix preservation for model names
- System message handling
Architecture:
- Service layer calls Responses API internally
- Streams word-by-word for smooth UX
- Reasoning displayed in thought bubbles (Open WebUI)
- Main response shown separately from thinking
Error Handling:
- Enhanced exception types (RateLimitError, ContextLengthError)
- OpenAI-compatible error format
- Graceful error propagation from Responses API
Testing:
- 6 unit tests for chat router functionality
- 6 unit tests for streaming wrapper behavior
- Total: 12 tests with comprehensive coverage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements Phases 2, 3, and 6: Complete Responses API implementation
Core API (Phase 2):
- OpenAI Responses API format with structured output items
- Streaming and non-streaming support via SSE-Starlette
- Reasoning items (thinking summaries)
- Function call items (tool execution)
- Message items (assistant responses)
- Router, schemas, service, and streaming coordinator
Conversation History (Phase 3):
- Hybrid client/server approach
- Auto-generated deterministic conversation IDs
- Configurable max turns with automatic trimming
- Context window management with token counting
- Token usage statistics
- Placeholder for future vector memory integration
Advanced Features (Phase 6):
- Parameter validation with Pydantic field validators:
- Temperature: 0.0-2.0 range enforcement
- Reasoning effort: 6 levels (none to xhigh)
- 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
- Graceful error handling and OpenAI-compatible error format
Testing:
- 9 unit tests for API endpoints and streaming
- 11 unit tests for error handling
- 13 unit tests for conversation history and context
- 12 unit tests for advanced features and validation
- Total: 45 tests with comprehensive coverage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements Phase 1: Agent abstraction layer with multiple model support
Features:
- Abstract AgentInterface base class with standard contract
- LoremTesterAgent: Full-featured mock agent with realistic behavior
- Configurable reasoning effort levels (none to xhigh)
- Random tool/function call generation
- Error triggers for testing (rate_limit, context_overflow)
- Temperature-based response variation
- TatlockAgent: Placeholder for future PydanticAI integration
- ModelRegistry: Centralized model management and discovery
Testing:
- 9 unit tests for lorem-tester agent behavior
- 9 unit tests for registry operations
- Coverage: Agent abstraction fully tested
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement application factory pattern with clean main.py.
Separate routers for each domain, centralized exception handling.
Core Router (src/core/router.py):
- Root endpoint (/)
- Health check endpoint (/health)
- Simple status responses
- No prefix (mounted at root)
Main Application (src/main.py):
- create_application() factory function
- Clean configuration-focused main.py
- CORS middleware setup
- Exception handler registration
- Router registration with proper prefixes
- Global config integration
Application Architecture:
- Application factory pattern for testability
- Routers imported from separate controllers
- Exception handlers in dedicated function
- All routes cleanly separated by domain
Exception Handling:
- OpenAI-compatible error format
- Custom AppException handler
- Validation error handler (422)
- Generic exception handler (500)
Following Best Practices:
- Separation of concerns
- Factory pattern for DI
- Clean main.py (config only)
- Type hints throughout
Status: Production-ready structure
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add OpenAI-compatible models listing endpoint.
Currently returns mock model (mistral-nemo:latest).
Models Router (src/models/router.py):
- GET /v1/models endpoint
- OpenAI-compatible response format
- Lists available models
Models Schemas (src/models/schemas.py):
- Model object with id, created, owned_by
- ModelsListResponse with data array
- Full OpenAI API compatibility
Models Service (src/models/service.py):
- list_models() function
- Mock model listing (ready for Ollama integration)
- Returns mistral-nemo:latest as default
Following Best Practices:
- Business logic in service layer
- Router only handles HTTP concerns
- Type hints throughout
- Async/await pattern
Model: mistral-nemo:latest
Status: Mock implementation (ready for Ollama integration)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add OpenAI-compatible chat completions endpoint with streaming support.
Currently returns mock lorem ipsum responses (Ollama integration pending).
Chat Router (src/chat/router.py):
- POST /v1/chat/completions endpoint
- Streaming and non-streaming support
- SSE format with EventSourceResponse
- 20-second timeout protection
- OpenAI-compatible response format
Chat Schemas (src/chat/schemas.py):
- ChatMessage, ChatCompletionRequest
- ChatCompletionResponse, ChatCompletionChoice
- ChatCompletionChunk for streaming
- Full OpenAI API compatibility
Chat Service (src/chat/service.py):
- create_chat_completion() - non-streaming
- create_chat_completion_stream() - streaming word-by-word
- Mock lorem ipsum responses
- Token usage calculation
Chat Constants (src/chat/constants.py):
- OpenAI API constants for consistency
- Object types, roles, finish reasons
Following Best Practices:
- Business logic in service layer
- Router only handles HTTP concerns
- Async generators for streaming
- Type hints throughout
Model: mistral-nemo:latest
Status: Mock implementation (ready for Ollama integration)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add production-ready async HTTP client for Ollama API communication
with proper error handling and dependency injection.
Ollama Client (src/ollama/client.py):
- Async context manager for connection lifecycle
- Non-streaming chat endpoint
- Streaming chat endpoint with async generator
- Model listing endpoint
- Health check endpoint
- Timeout configuration per request
- Comprehensive error handling with custom exceptions
- FastAPI dependency injection support
Ollama Schemas (src/ollama/schemas.py):
- OllamaMessage: Chat message format
- OllamaChatRequest: Request with model, messages, options
- OllamaChatResponse: Complete chat response
- OllamaModelInfo: Model metadata
- OllamaModelsResponse: Model list response
Features:
- Async/await throughout for non-blocking I/O
- Connection pooling via httpx.AsyncClient
- Configurable timeouts (default: 120s)
- Proper exception mapping (connection errors, timeouts)
- Ready for integration (currently not connected to routes)
Following Best Practices:
- Async context manager pattern
- Dependency injection for FastAPI routes
- Separation of concerns (client vs schemas)
- Type hints throughout
- Comprehensive logging
Status: Ready for integration (mock responses used in routes currently)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement global application configuration and custom Pydantic models
following FastAPI best practices.
Core Configuration (src/core/config.py):
- BaseSettings with environment variable support
- Split configuration by domain (following best practices)
- Ollama connection settings (host, model, timeouts)
- API configuration (host, port, prefix)
- CORS settings
- 20-second streaming timeout per turn
- Cached configuration with @lru_cache
Custom Base Models (src/core/models.py):
- CustomBaseModel for consistent serialization
- ISO datetime formatting
- Alias population support
- Enum value serialization
- Validation on assignment
- serializable_dict() for logging/debugging
Exception Handling (src/core/exceptions.py):
- Base AppException with status codes
- OllamaConnectionError (503)
- OllamaTimeoutError (504)
- ModelNotFoundError (404)
- ValidationError (422)
- OpenAI-compatible error structure
Benefits:
- Consistent configuration across domains
- Type-safe settings with validation
- Easy environment override via .env
- Predictable error responses
- Better debugging with serializable models
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Set up Python 3.12.11 FastAPI project with security-focused dependency management.
Dependencies:
- FastAPI 0.123.9: Modern web framework
- Uvicorn 0.38.0: ASGI server with standard extras
- Pydantic 2.12.5: Data validation (updated for pydantic-ai)
- PydanticAI 1.27.0: LLM agent framework with Ollama support
- HTTPX 0.28.1: Async HTTP client
- SSE-Starlette 3.0.2: Server-Sent Events for streaming
- python-dotenv 1.2.1: Environment configuration
Security:
- All packages checked for CVEs (as of 2025-12-06)
- Minor version locking (>=X.Y,<X.(Y+1)) for supply chain protection
- CVE status documented in requirements.txt
Development tools:
- pytest 8.3.5 + pytest-asyncio for async testing
- pytest-cov 6.0.0 for coverage reporting
- ruff 0.8.6 for linting and formatting
- mypy 1.14.1 for type checking
Configuration:
- pyproject.toml: Build system, coverage, ruff, and mypy config
- .env.example: Environment variable template
- .gitignore: Comprehensive Python/FastAPI patterns
Target model: mistral-nemo:latest on external Ollama instance
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
jpmschweitzerandClaude Opus 4.5