tatlock/docs/roadmap.md

Tatlock Implementation Roadmap

Reference: See 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 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