tatlock/README.md

Tatlock - Your Homelab Butler

📖 For the complete system vision and architectural philosophy, see 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 (<think> 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 <think> 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

# 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

uvicorn src.main:app --reload

API available at http://localhost:8000

Usage Examples

Responses API

Generate a response with reasoning:

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:

{
  "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)

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

curl http://localhost:8000/v1/models

Conversation History

Optionally track conversations using metadata:

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:

# 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 <think> 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

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=term-missing

# Current: 95 tests, 78.95% coverage

Deployment

Production Server

# 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:

# 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 <think> 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.

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 - Vision, goals, and architectural patterns
• User Guide: This file - Installation, usage, and examples
• Developer Guidelines: AGENTS.md - LLM agent development patterns
• Version History: 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.).