refactor: consolidate project structure and clean up documentation

- Move docs to docs/ (philosophy, roadmap, orchestration scenarios, claude integration, testing improvements) - Strip completed phases from roadmap and claude integration docs - Move dependencies from requirements*.txt into pyproject.toml - Move pytest config from pytest.ini into pyproject.toml - Add Makefile replacing wakeup.sh (setup, run, test, lint, etc.) - Add CI test gate in Gitea Actions workflow - Consolidate caches into .cache/ (pytest, mypy, ruff) - Consolidate build output into build/ (coverage, logs) - Update Dockerfile for pyproject.toml install - Update cross-references in README, AGENTS.md, CLAUDE.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-05 20:44:25 +01:00
parent 901a04825d
commit a3c7fcf8c3
19 changed files with 464 additions and 1574 deletions
@@ -0,0 +1,208 @@
+# Tatlock Implementation Roadmap
+
+> **Reference**: See [philosophy.md](philosophy.md) for the target architecture and vision
+
+This document tracks open/planned work. Completed phases have been removed.
+
+## Current State (v2.0.5)
+
+**What we have**:
+- OpenAI-compatible API (Responses API + Chat Completions)
+- Two-tier architecture (Steward → Tatlock)
+- Household staff: Tatlock (Butler), Steward, Librarian, Biographer
+- Core tools: Calculator, Date/Time, Web search (SearXNG)
+- Memory system: Qdrant (vector), Redis (session cache), multi-tenancy via ContextVar
+- Dual backend: Claude (preferred) + Ollama (fallback)
+- 439 tests with good coverage
+
+---
+
+## Phase 4: Expert Household Staff — Remaining Agents
+
+**Goal**: Implement remaining domain-specific expert agents
+
+### Planned Agents
+
+1. **The Developer** (Software Development)
+   - Code generation assistance
+   - Debugging support
+   - Documentation generation
+   - Architecture guidance
+
+2. **The Handyman** (System Maintenance)
+   - System status queries
+   - Log analysis
+   - Basic troubleshooting
+   - Infrastructure monitoring
+
+3. **The Secretary** (Scheduling & Organization)
+   - Calendar integration
+   - Task management
+   - Reminder system
+   - Schedule conflict detection
+
+4. **The Housekeeper** (Home Automation)
+   - Home Assistant integration
+   - Device control interface
+   - Status queries
+   - Automation triggers
+
+### Each Agent Includes
+- Specialized prompt and personality
+- Domain-specific tools
+- MCP integration points (where applicable)
+- Integration with Butler orchestration
+
+### Success Criteria
+- [ ] Each agent implemented as separate module
+- [ ] Agents callable via tool framework
+- [ ] Can invoke specialized models (e.g., Codestral for Developer)
+
+---
+
+## Phase 5: Persistence Layer — Database & Multi-Tenancy
+
+**Goal**: Add persistent storage and multi-user support
+
+### Deliverables
+
+1. **PostgreSQL Integration**
+   - Docker compose configuration
+   - Database schema with tenant isolation
+   - Alembic migrations
+   - SQLAlchemy models
+
+2. **Multi-Tenant Architecture**
+   - Tenant identification middleware
+   - Tenant-scoped database sessions
+   - User authentication system
+   - Per-tenant data isolation
+
+3. **Core Data Models**
+   - Users and tenants
+   - Conversations and messages (migrate from in-memory)
+   - Agent interactions log
+   - System configuration and preferences
+
+### Success Criteria
+- [ ] PostgreSQL container running
+- [ ] Multiple users authenticate separately
+- [ ] Each user sees only their own data
+- [ ] Conversations persist across restarts
+- [ ] Database migrations work correctly
+
+---
+
+## Phase 7: MCP (Model Context Protocol) Integration
+
+**Goal**: Enable rich tool integrations via MCP
+
+See also [claude-integration.md](claude-integration.md) for MCP server implementation details.
+
+### Deliverables
+
+1. **MCP Server Framework**
+   - MCP server implementation
+   - Tool registration via MCP
+   - Schema validation
+   - Error handling
+
+2. **MCP Client in Agents**
+   - PydanticAI MCP integration
+   - Tool discovery from MCP servers
+   - Dynamic tool loading
+
+3. **Initial MCP Tools**
+   - File system operations
+   - Database queries
+   - API integrations
+   - System commands
+
+### Success Criteria
+- [ ] MCP server running
+- [ ] Tools exposed via MCP protocol
+- [ ] Agents can discover and use MCP tools
+- [ ] New tools addable without code changes
+- [ ] MCP tools visible in Steward recommendations
+
+---
+
+## Phase 8: Advanced Memory & Context — Remaining Work
+
+**Goal**: Implement sophisticated context management and personalization
+
+### Open Deliverables
+
+1. **Context Management**
+   - Smart context window trimming
+   - Conversation branching
+   - Topic tracking
+
+2. **Personalization**
+   - User preference learning
+   - Interaction pattern analysis
+   - Adaptive responses
+   - Custom agent personalities per user
+
+### Success Criteria
+- [ ] Conversations automatically embedded to Qdrant
+- [ ] Memory improves over time (learning from interactions)
+
+---
+
+## Phase 9: Extended Household Staff
+
+**Goal**: Add specialized agents for additional domains
+
+### Future Agents
+- **The Accountant** — Expense tracking, budgets, financial reports
+- **The Chef** — Meal planning, recipes, nutrition tracking
+- Others as needs emerge
+
+---
+
+## Phase 10: User Experience Refinement
+
+**Goal**: Polish the interaction experience
+
+- Personality tuning and consistency
+- Better progress indicators
+- Response time improvements
+- Streaming smoothness
+
+---
+
+## Phase 11: Production Hardening
+
+**Goal**: Make the system production-ready for homelab deployment
+
+- Complete docker-compose stack
+- Health checks and monitoring
+- Authentication hardening and rate limiting
+- Installation and troubleshooting documentation
+
+---
+
+## Dependencies
+
+```
+Phase 4 (Remaining Agents)
+    ↓
+Phase 5 (Database/Multi-Tenancy) ← Can be deferred
+    ↓
+Phase 7 (MCP) → Phase 8 (Advanced Memory)
+    ↓
+Phase 9 (Extended Staff) → Phase 10 (UX) → Phase 11 (Production)
+```
+
+**Can Be Deferred**: Phase 5 until you need persistence
+**Parallel Opportunities**: Phases 7 and 8 can overlap; 9 and 10 ongoing
+
+---
+
+## Next Steps
+
+1. Implement The Developer agent for code assistance
+2. Add Home Assistant integration for The Housekeeper
+3. Integrate scheduling service for The Secretary
+4. MCP server for external Claude access