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,100 @@
+# Claude Integration Plan
+
+## Overview
+
+Tatlock uses a bidirectional Claude architecture:
+- **Scenario A**: Tatlock powered by Claude backend (with Ollama fallback) — **COMPLETE**
+- **Scenario B**: Tatlock exposed as MCP server for external Claude instances — **OPEN**
+- **Scenario C**: Offline operation via Ollama — **COMPLETE**
+
+---
+
+## MCP Server (Expose Tools to Claude) — NOT STARTED
+
+Create an MCP server that exposes Tatlock's household tools to external Claude instances.
+
+### New Files
+
+```
+src/mcp/
+├── __init__.py
+├── server.py         # MCP server using mcp Python SDK
+├── tool_adapters.py  # Convert PydanticAI tools → MCP schemas
+├── auth.py           # API key authentication
+└── transport.py      # Streamable HTTP transport
+```
+
+### Docker Stack Addition
+
+```yaml
+tatlock-mcp:
+  image: git.schweitz.internal/jpmschweitzer/tatlock:latest
+  command: ["python", "-m", "src.mcp.server"]
+  ports:
+    - "8002:8002"
+  environment:
+    - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
+  networks:
+    - docker-dataplane
+```
+
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "tatlock": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.schweitz.net/sse", "--header", "Authorization: Bearer ${MCP_AUTH_TOKEN}"]
+    }
+  }
+}
+```
+
+### Checklist
+
+- [ ] Create `src/mcp/` module
+- [ ] Tool adapters (PydanticAI → MCP schema)
+- [ ] Authentication middleware
+- [ ] Streamable HTTP transport
+- [ ] Docker stack configuration
+
+---
+
+## Future Phases
+
+- **LiteLLM Gateway** — Unified endpoint for all models, config-driven routing
+- **Multi-Provider** — Add OpenAI, Vertex AI, etc.
+- **Smart Routing** — Context-aware model selection, cost ceiling enforcement
+
+---
+
+## Offline Behavior
+
+| Scenario | Behavior |
+|----------|----------|
+| No API key | Use Ollama exclusively |
+| API unreachable | Use Ollama, log warning |
+| API rate limited | Fallback to Ollama |
+
+| Aspect | Claude | Ollama |
+|--------|--------|--------|
+| Context | 200k tokens | ~8k tokens |
+| Latency | 1-3s (network) | 0.5-1s (local) |
+| Personality | Preserved | Preserved |
+| Tools | All work | All work |
+| Cost | API charges | Free |
+
+---
+
+## Related Repo Handovers
+
+Handover documents created in each repo: `PROJECT_CLAUDIFICATION_HANDOVER.md`
+
+### Open Items
+
+- **library-desk**: Review HybridRAG response size limits, smart_create endpoint, response formats
+- **core-api**: Review list_devices response format, error messages, rate limiting
+- **portainer-core**: Update stack with new env vars, configure secrets, update CONTAINERS.md
+- **webber**: Review content truncation limits, extraction quality
+- **tatlock-ui**: Test streaming with Claude backend, conversation history, tool call display