README.md: - Add household staff table with current status - Update requirements to list external services - Add Redis, Qdrant to configuration section - Update project structure with new modules - Update version to 1.2.0 IMPLEMENTATION_ROADMAP.md: - Update current state to v1.2.0 - Mark Phase 2 (Steward) as complete - Mark Phase 3 (Butler coordination) as complete - Update Phase 4 with Librarian and Biographer complete - Mark Phase 6 (Services) as complete - Update Phase 8 (Memory) with completed items - Update next steps 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.5
@@ -6,12 +6,25 @@ A privacy-first, offline-capable personal assistant system that coordinates spec
|
||||
|
||||
## Current Status
|
||||
|
||||
- ✅ **Production-ready testing API** with OpenAI Responses API format
|
||||
- ✅ **Production-ready API** with OpenAI Responses API format
|
||||
- ✅ **Open WebUI integration** with reasoning bubbles (`<think>` tags)
|
||||
- ✅ **Conversation history** with auto-generated IDs and context management
|
||||
- ✅ **Tatlock PydanticAI Agent** - Real LLM integration with Ollama + permanent tools
|
||||
- ✅ **Permanent Tools** - Calculator, date/time toolkit, web search (SearXNG)
|
||||
- ✅ **Comprehensive testing** - 131 tests, 81.78% coverage
|
||||
- ✅ **Two-tier architecture** - The Steward analyzes requests, Tatlock coordinates execution
|
||||
- ✅ **Multi-agent coordination** - Expert household staff for specialized tasks
|
||||
- ✅ **Memory system** - User profile, preferences, and semantic recall
|
||||
- ✅ **Comprehensive testing** - 399 tests with good coverage
|
||||
|
||||
### The Household Staff
|
||||
|
||||
| Agent | Role | Status |
|
||||
|-------|------|--------|
|
||||
| **Tatlock** | The Butler - Primary interface with witty personality | ✅ Active |
|
||||
| **The Steward** | Request analysis and capability recommendation | ✅ Active |
|
||||
| **The Librarian** | Research, wiki management, knowledge synthesis | ✅ Active |
|
||||
| **The Biographer** | User memory - profiles, preferences, facts | ✅ Active |
|
||||
| **The Developer** | Code assistance, debugging, architecture | 🔜 Planned |
|
||||
| **The Secretary** | Scheduling, calendars, reminders | 🔜 Planned |
|
||||
| **The Handyman** | System administration, monitoring | 🔜 Planned |
|
||||
| **The Housekeeper** | Home automation (Home Assistant) | 🔜 Planned |
|
||||
|
||||
## Features
|
||||
|
||||
@@ -45,24 +58,27 @@ A privacy-first, offline-capable personal assistant system that coordinates spec
|
||||
- Error triggers for testing (rate_limit, context_overflow)
|
||||
|
||||
- **Tatlock**: Real PydanticAI agent with butler personality
|
||||
- **LLM Backend**: Ollama (mistral-nemo:latest)
|
||||
- **LLM Backend**: Ollama (mistral-nemo:latest by default)
|
||||
- **Personality**: Witty British butler, research-oriented
|
||||
- **Permanent Tools**:
|
||||
- **Calculator**: Safe mathematical expression evaluation (arithmetic, algebra, trigonometry, logarithms)
|
||||
- **Date/Time Toolkit**: Current time, relative dates ("1 week ago"), time differences
|
||||
- **Core Tools**:
|
||||
- **Calculator**: Safe mathematical expression evaluation
|
||||
- **Date/Time Toolkit**: Current time, relative dates, time differences
|
||||
- **Web Search**: Privacy-preserving search via SearXNG
|
||||
- **Capabilities**: Streaming, reasoning, tool calling
|
||||
- **Phase**: Phase 1 - Basic Integration (full household coordination coming in future phases)
|
||||
- **Household Coordination**:
|
||||
- **The Steward**: Analyzes requests and recommends capabilities
|
||||
- **The Librarian**: Research via library-desk HybridRAG + wiki
|
||||
- **The Biographer**: User memory and preference management
|
||||
- **Capabilities**: Streaming, reasoning, tool calling, multi-agent delegation
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.12+ (Python 3.12.11 recommended)
|
||||
- **Ollama** (for Tatlock agent): Running locally or network-accessible
|
||||
- Download: https://ollama.ai/
|
||||
- Model: `ollama pull mistral-nemo:latest`
|
||||
- **SearXNG** (for web search tool): Optional but recommended
|
||||
- Docker: `docker run -d -p 8087:8080 searxng/searxng`
|
||||
- Or use public instance (less private)
|
||||
- **External Services** (must be running separately):
|
||||
- **Ollama**: LLM inference (mistral-nemo:latest, nomic-embed-text)
|
||||
- **Redis**: Caching and session memory
|
||||
- **Qdrant**: Vector storage for The Biographer's memory
|
||||
- **SearXNG**: Web search (optional)
|
||||
- **library-desk**: Research API for The Librarian (optional)
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -251,15 +267,18 @@ Interactive documentation available at:
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run unit tests only (no external services needed)
|
||||
pytest --ignore=tests/e2e --ignore=tests/integration
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=src --cov-report=term-missing
|
||||
|
||||
# Current: 131 tests, 81.78% coverage
|
||||
# Current: ~400 tests
|
||||
```
|
||||
|
||||
**Test Categories:**
|
||||
- Unit tests: Agent tools, streaming, schemas
|
||||
- Integration tests: Full API stack with real Ollama calls
|
||||
- Unit tests: Agent tools, capabilities, schemas, memory service
|
||||
- Integration tests: Full API stack with real Ollama
|
||||
- End-to-end tests: Chat completions, responses API
|
||||
|
||||
## Deployment
|
||||
@@ -291,9 +310,25 @@ API_PORT=8000
|
||||
# Ollama Configuration
|
||||
OLLAMA_HOST=http://localhost:11434
|
||||
OLLAMA_DEFAULT_MODEL=mistral-nemo:latest
|
||||
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
|
||||
OLLAMA_TIMEOUT=120
|
||||
|
||||
# SearXNG Configuration (for web search tool)
|
||||
# Redis Configuration
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
REDIS_MEMORY_DB=2
|
||||
REDIS_MEMORY_TTL_HOURS=24
|
||||
|
||||
# Qdrant Configuration (for memory)
|
||||
QDRANT_HOST=localhost
|
||||
QDRANT_PORT=6333
|
||||
QDRANT_EMBEDDING_DIM=768
|
||||
|
||||
# Library-desk Configuration (for The Librarian)
|
||||
LIBRARY_DESK_HOST=http://localhost:8089
|
||||
LIBRARY_DESK_TIMEOUT=60
|
||||
|
||||
# SearXNG Configuration (for web search)
|
||||
SEARXNG_HOST=http://localhost:8087
|
||||
SEARXNG_TIMEOUT=30
|
||||
|
||||
@@ -339,23 +374,32 @@ See `.env.example` for full configuration options.
|
||||
```
|
||||
tatlock/
|
||||
├── src/
|
||||
│ ├── agents/ # Agent interface and implementations
|
||||
│ │ ├── base.py # AgentInterface abstract class
|
||||
│ │ ├── lorem_tester.py # Mock agent for testing
|
||||
│ │ ├── tatlock.py # Real PydanticAI butler agent
|
||||
│ │ ├── tools.py # Permanent tools (calculator, date/time, search)
|
||||
│ │ └── registry.py # Model registry
|
||||
│ ├── 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 (131 tests)
|
||||
├── AGENTS.md # LLM agent development guidelines
|
||||
├── PHILOSOPHY.md # System vision and architecture
|
||||
├── IMPLEMENTATION_ROADMAP.md # Development phases
|
||||
├── CHANGELOG.md # Version history
|
||||
└── README.md # This file
|
||||
│ ├── agents/ # Agent implementations
|
||||
│ │ ├── biographer/ # The Biographer - memory management
|
||||
│ │ ├── librarian/ # The Librarian - research & wiki
|
||||
│ │ ├── steward/ # The Steward - request analysis
|
||||
│ │ ├── tatlock_core/ # Core butler tools
|
||||
│ │ ├── tatlock.py # Tatlock PydanticAI agent
|
||||
│ │ ├── coordination.py # Multi-agent coordination
|
||||
│ │ ├── delegation.py # Expert delegation wrappers
|
||||
│ │ └── protocol.py # Agent communication protocol
|
||||
│ ├── responses/ # Responses API (primary endpoint)
|
||||
│ ├── chat/ # Chat Completions wrapper
|
||||
│ ├── models/ # Models listing
|
||||
│ ├── core/ # Shared infrastructure
|
||||
│ │ ├── config.py # Configuration management
|
||||
│ │ ├── context.py # Request context (ContextVar)
|
||||
│ │ ├── memory_service.py # Direct memory access
|
||||
│ │ ├── memory_cache.py # Redis session cache
|
||||
│ │ ├── embeddings.py # Ollama embedding client
|
||||
│ │ ├── qdrant.py # Vector database client
|
||||
│ │ └── multi_tenancy.py # User isolation utilities
|
||||
│ └── main.py # Application entry point
|
||||
├── tests/ # Comprehensive test suite
|
||||
├── PHILOSOPHY.md # System vision and architecture
|
||||
├── IMPLEMENTATION_ROADMAP.md # Development phases
|
||||
├── CHANGELOG.md # Version history
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Development
|
||||
@@ -388,8 +432,8 @@ For LLM agent development guidelines and architectural decisions, see [AGENTS.md
|
||||
|
||||
## Version
|
||||
|
||||
Current version: **0.2.5** - Phase 2: The Steward (Two-Tier Architecture)
|
||||
Current version: **1.2.0** - Phase F: Memory System (The Biographer)
|
||||
|
||||
---
|
||||
|
||||
**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.).
|
||||
**Note**: Tatlock is a production-ready homelab butler. All household staff use PydanticAI with Ollama for local LLM inference.
|
||||
|
||||
Reference in New Issue
Block a user