# Tatlock - Your Homelab Butler > **📖 For the complete system vision and architectural philosophy, see [PHILOSOPHY.md](PHILOSOPHY.md)** A privacy-first, offline-capable personal assistant system that coordinates specialized AI agents to help with research, development, home automation, and daily organization. ## Current Status - ✅ **Production-ready testing API** with OpenAI Responses API format - ✅ **Open WebUI integration** with reasoning bubbles (`` tags) - ✅ **Conversation history** with auto-generated IDs and context management - ✅ **Comprehensive testing** - 95 tests, 78.95% coverage - 🚧 **PydanticAI integration** prepared for future real LLM connection ## Features ### API Endpoints - **Responses API** (`/v1/responses`) - OpenAI Responses API format with structured output - Reasoning items for displaying thinking process - Function call items for tool execution - Message items for assistant responses - Streaming and non-streaming support - **Chat Completions** (`/v1/chat/completions`) - OpenAI Chat Completions compatibility - Automatic reasoning conversion to `` tags for Open WebUI - Full OpenAI API compatibility - Streaming support - **Models** (`/v1/models`) - List available models ### Advanced Capabilities - **Conversation History**: Auto-generated IDs, configurable max turns (default: 20) - **Context Management**: Token counting, automatic trimming, usage statistics - **Parameter Validation**: Temperature (0.0-2.0), reasoning effort levels, max tokens, stop sequences - **Real-time Enforcement**: Stop sequence detection and max token limits during streaming ### Testing Models - **lorem-tester**: Full-featured mock agent with realistic behavior - Configurable reasoning effort levels - Random tool/function calls - Error triggers for testing (rate_limit, context_overflow) - **tatlock**: Placeholder for future PydanticAI agent ## Requirements - Python 3.12+ (Python 3.12.11 recommended) - No external dependencies for mock API - (Future: Network access for PydanticAI integration) ## Quick Start ### Installation ```bash # Clone the repository git clone https://git.schweitz.net/jpmschweitzer/tatlock.git cd tatlock # Create virtual environment python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # Install dependencies pip install -r requirements.txt ``` ### Run the Server ```bash uvicorn src.main:app --reload ``` API available at `http://localhost:8000` ## Usage Examples ### Responses API Generate a response with reasoning: ```bash curl http://localhost:8000/v1/responses \ -H "Content-Type: application/json" \ -d '{ "model": "lorem-tester", "input": [ {"role": "user", "content": "Explain quantum computing"} ], "reasoning": { "effort": "medium", "summary": "auto" }, "max_output_tokens": 500, "stream": false }' ``` **Response Structure:** ```json { "id": "resp_abc123", "object": "response", "created_at": 1733529600, "model": "lorem-tester", "status": "completed", "output": [ { "type": "reasoning", "summary": ["Analyzing the request...", "Considering quantum mechanics..."] }, { "type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Quantum computing uses..."}] } ], "usage": { "input_tokens": 10, "output_tokens": 50, "reasoning_tokens": 20, "total_tokens": 80 } } ``` ### Chat Completions (OpenAI-compatible) ```bash curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "lorem-tester", "messages": [ {"role": "user", "content": "Hello!"} ], "temperature": 0.7, "stream": true }' ``` ### List Models ```bash curl http://localhost:8000/v1/models ``` ### Conversation History Optionally track conversations using metadata: ```bash curl http://localhost:8000/v1/responses \ -H "Content-Type: application/json" \ -d '{ "model": "lorem-tester", "input": [{"role": "user", "content": "Hello"}], "metadata": {"conversation_id": "conv_abc123"} }' ``` **Note**: Client must send full conversation history in `input` array (OpenAI compatible). Server optionally tracks via `metadata.conversation_id` for future features. ## Open WebUI Integration ### Connection If running Open WebUI in Docker and API on host: ```bash # Use Docker bridge gateway IP http://172.17.0.1:8000/v1/chat/completions ``` ### Reasoning Display The Chat Completions endpoint automatically: 1. Enables reasoning generation 2. Converts reasoning to `` tags 3. Streams thinking before the response Open WebUI displays this as thought bubbles separate from the main response. ### Testing Error Handling Use special triggers in user messages: - `"trigger_rate_limit"` - Simulates rate limit error - `"trigger_context_overflow"` - Simulates context length error ## API Documentation Interactive documentation available at: - **Swagger UI**: `http://localhost:8000/docs` - **ReDoc**: `http://localhost:8000/redoc` ## Testing ```bash # Run all tests pytest # Run with coverage pytest --cov=src --cov-report=term-missing # Current: 95 tests, 78.95% coverage ``` ## Deployment ### Production Server ```bash # Multiple workers for production uvicorn src.main:app --host 0.0.0.0 --port 8000 --workers 4 ``` ### Recommendations - Use reverse proxy (nginx/caddy) for HTTPS - Enable rate limiting - Set up monitoring and logging - Configure resource limits - Use process manager (systemd/supervisor) ## Configuration Create a `.env` file for custom configuration: ```env # API Configuration API_HOST=0.0.0.0 API_PORT=8000 # Logging LOG_LEVEL=INFO # CORS (default: allow all) CORS_ORIGINS=["*"] # Future: LLM configuration ``` ## Troubleshooting ### Streaming not working - Verify SSE-Starlette is installed - Check client supports Server-Sent Events - Test with: `pytest tests/responses/ -k streaming` ### Open WebUI can't connect - Use Docker bridge gateway IP: `172.17.0.1:8000` - Check firewall settings - Verify server is running on `0.0.0.0` ### Reasoning not showing - Ensure using Chat Completions endpoint (auto-enables reasoning) - Or manually enable in Responses API: `"reasoning": {"effort": "medium", "summary": "auto"}` - Check Open WebUI version supports `` tags ## Project Structure ``` tatlock/ ├── src/ │ ├── agents/ # Agent interface and implementations │ ├── responses/ # Responses API (primary endpoint) │ ├── chat/ # Chat Completions wrapper │ ├── models/ # Models listing │ ├── core/ # Shared utilities and config │ └── main.py # Application entry point ├── tests/ # Comprehensive test suite ├── AGENTS.md # LLM agent development guidelines ├── CHANGELOG.md # Version history └── README.md # This file ``` ## Development For LLM agent development guidelines and architectural decisions, see [AGENTS.md](AGENTS.md). ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make changes with tests 4. Ensure tests pass: `pytest` 5. Submit pull request ## Documentation - **System Philosophy**: [PHILOSOPHY.md](PHILOSOPHY.md) - Vision, goals, and architectural patterns - **User Guide**: This file - Installation, usage, and examples - **Developer Guidelines**: [AGENTS.md](AGENTS.md) - LLM agent development patterns - **Version History**: [CHANGELOG.md](CHANGELOG.md) - Changes and releases ### External References - **OpenAI Responses API**: https://platform.openai.com/docs/api-reference/responses - **FastAPI**: https://fastapi.tiangolo.com/ - **PydanticAI**: https://ai.pydantic.dev/ ## License [Add your license here] ## Version Current version: **0.1.1** - Basic setup complete --- **Note**: This is a production-ready testing API with mock responses. The architecture is designed for easy integration with real LLM backends (PydanticAI, Ollama, OpenAI, etc.).