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