# 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: Ollama/gemma4 (primary) + Claude (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