docs: update documentation for v0.2.0 tools release

README.md:
- Add Tatlock agent capabilities and tool descriptions
- Add requirements section (Ollama, SearXNG setup)
- Add configuration examples for external services
- Add tool usage examples and philosophy
- Add troubleshooting for Ollama and SearXNG
- Update test statistics

AGENTS.md:
- Refactor for LLM development focus
- Add PydanticAI tool registration pattern
- Add tool implementation guidelines
- Remove project status, focus on development instructions

IMPLEMENTATION_ROADMAP.md:
- Mark Phase 1 as "MOSTLY COMPLETE"
- Update detailed completion status
- Update current state summary
This commit is contained in:
2025-12-07 00:13:41 +01:00
parent 958363d44e
commit fd459e9ffb
3 changed files with 272 additions and 145 deletions
+51 -36
View File
@@ -4,69 +4,84 @@
This document outlines the phased implementation plan to transform the current OpenAI-compatible API into the full Tatlock household butler system.
## Current State (v0.1.1 - Basic Setup Complete)
## Current State (v0.1.1+ - Phase 1 Mostly Complete)
**What we have**:
-**The Orchestrator** - FastAPI infrastructure layer
- OpenAI-compatible API endpoints (Responses API + Chat Completions)
- Streaming coordination and conversation management
- Response format with reasoning support
- Test infrastructure (95 tests, 78.95% coverage)
-Mock agents (lorem-tester for testing, Tatlock placeholder)
- ✅ Agent interface abstraction ready for PydanticAI
- Test infrastructure (131 tests, 81.78% coverage)
-**Tatlock Agent** - Real PydanticAI integration
- Connected to Ollama (mistral-nemo:latest)
- British butler personality with research mindset
- Streaming responses with reasoning
- Tool calling framework functional
-**Permanent Tools**
- Calculator (safe mathematical expressions)
- Date/Time toolkit (current time, relative dates, time differences)
- Web search (SearXNG integration)
- ✅ Mock agent (lorem-tester for testing)
- ✅ Agent interface abstraction
**What we need**:
- **The Household** - PydanticAI agent implementations:
- **The Household** - Full multi-agent coordination:
- The Steward (first-tier request analysis)
- Tatlock Butler (second-tier coordination with personality)
- Tatlock coordination layer (expert agent delegation)
- Expert household staff agents (Librarian, Developer, Handyman, etc.)
- Real LLM integration (PydanticAI + Ollama)
- Multi-tenant database architecture
- Containerized service ecosystem
- MCP (Model Context Protocol) integration
- Dynamic model switching for specialized tasks
---
## Phase 1: Real LLM Integration - Ollama + PydanticAI
## Phase 1: Real LLM Integration - PydanticAI + Tools
**Goal**: Connect to actual language models and establish the base plumbing
**Note**: Ollama is an external service dependency (already running separately)
### Deliverables
1. **Ollama Setup**
- Docker compose configuration for Ollama
- Model download and management
- Base model selection (single model in VRAM)
- Health checking and monitoring
1. **PydanticAI Integration**
- PydanticAI → Ollama connection ✅
- Agent creation patterns ✅
- Streaming response handling ✅
- Error handling and retries ✅
2. **PydanticAI Integration**
- PydanticAI → Ollama connection
- Agent creation patterns
- Streaming response handling
- Error handling and retries
2. **Convert Tatlock Agent**
- Convert Tatlock agent from mock to PydanticAI ✅
- British butler personality prompt ✅
- Research-oriented mindset ✅
- Streaming to reasoning output ✅
- Tool calling framework setup ✅
3. **Replace Mock Agents**
- Convert Tatlock agent from mock to PydanticAI
- Basic personality prompt
- Streaming to reasoning output
- Tool calling framework setup
3. **Permanent Tools**
- Calculator: Safe mathematical expression evaluation ✅
- Date/Time toolkit: Current time, relative dates, time differences ✅
- Web search: SearXNG integration (external service) ✅
- Tool registration with PydanticAI ✅
4. **Testing Infrastructure**
- Integration tests with real LLM
- Prompt testing utilities
- Response quality validation
- Performance benchmarking
4. **Testing Infrastructure**
- Integration tests with real LLM
- Tool functionality tests ✅
- Response quality validation
- 131 tests, 81.78% coverage ✅
### Success Criteria
- [ ] Ollama running in Docker
- [ ] Base model loaded and responding
- [ ] PydanticAI agents can call Ollama
- [ ] Streaming works end-to-end
- [ ] Can switch models (e.g., Codestral for code)
- [ ] Tests pass with real LLM
- [x] **PydanticAI agents can call Ollama** (mistral-nemo:latest)
- [x] **Streaming works end-to-end**
- [x] **Tool calling framework functional**
- [x] **Permanent tools working** (calculator, date/time, search)
- [x] **Tests pass with real LLM**
- [ ] Can switch models dynamically (e.g., Codestral for code)
### Estimated Effort
**2-3 weeks** - Critical foundation for everything else
### Status
**✅ MOSTLY COMPLETE** - Tatlock agent functional with permanent tools
### Remaining Work
- Dynamic model switching for specialized tasks (e.g., Codestral for coding)
### Why First?
Without real LLM integration, we can't meaningfully implement the Steward/Butler pattern. Everything else depends on having actual AI agents working.