forked from Rockachopa/Timmy-time-dashboard
9f4c809f70
Complete the module consolidation planned in REFACTORING_PLAN.md: Modules merged: - work_orders/ + task_queue/ → swarm/ (subpackages) - self_modify/ + self_tdd/ + upgrades/ → self_coding/ (subpackages) - tools/ → creative/tools/ - chat_bridge/ + telegram_bot/ + shortcuts/ + voice/ → integrations/ (new) - ws_manager/ + notifications/ + events/ + router/ → infrastructure/ (new) - agents/ + agent_core/ + memory/ → timmy/ (subpackages) Updated across codebase: - 66 source files: import statements rewritten - 13 test files: import + patch() target strings rewritten - pyproject.toml: wheel includes (28→14), entry points updated - CLAUDE.md: singleton paths, module map, entry points table - AGENTS.md: file convention updates - REFACTORING_PLAN.md: execution status, success metrics Extras: - Module-level CLAUDE.md added to 6 key packages (Phase 6.2) - Zero test regressions: 1462 tests passing https://claude.ai/code/session_01JNjWfHqusjT3aiN4vvYgUk
116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
# CLAUDE.md — AI Assistant Guide for Timmy Time
|
|
|
|
**Tech stack:** Python 3.11+ · FastAPI · Jinja2 + HTMX · SQLite · Agno ·
|
|
Ollama · pydantic-settings · WebSockets · Docker
|
|
|
|
For agent roster and conventions, see [`AGENTS.md`](AGENTS.md).
|
|
|
|
---
|
|
|
|
## Architecture Patterns
|
|
|
|
### Config access
|
|
|
|
```python
|
|
from config import settings
|
|
url = settings.ollama_url # never use os.environ.get() directly in app code
|
|
```
|
|
|
|
### Singletons
|
|
|
|
```python
|
|
from dashboard.store import message_log
|
|
from infrastructure.notifications.push import notifier
|
|
from infrastructure.ws_manager.handler import ws_manager
|
|
from swarm.coordinator import coordinator
|
|
```
|
|
|
|
### HTMX response pattern
|
|
|
|
```python
|
|
return templates.TemplateResponse(
|
|
"partials/chat_message.html",
|
|
{"request": request, "role": "user", "content": message}
|
|
)
|
|
```
|
|
|
|
### Graceful degradation
|
|
|
|
Optional services (Ollama, Redis, AirLLM) degrade gracefully — log the error,
|
|
return a fallback, never crash.
|
|
|
|
### Route registration
|
|
|
|
New routes: `src/dashboard/routes/<name>.py` → register in `src/dashboard/app.py`.
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
make test # Quick run (no Ollama needed)
|
|
make test-cov # With coverage (term-missing + XML)
|
|
```
|
|
|
|
- **Stubs in conftest:** `agno`, `airllm`, `pyttsx3`, `telegram`, `discord`
|
|
stubbed via `sys.modules.setdefault()` — tests run without those packages
|
|
- **Test mode:** `TIMMY_TEST_MODE=1` set automatically in conftest
|
|
- **FastAPI testing:** Use the `client` fixture
|
|
- **Async:** `asyncio_mode = "auto"` — async tests detected automatically
|
|
- **Coverage threshold:** 60% (`fail_under` in `pyproject.toml`)
|
|
|
|
---
|
|
|
|
## Key Conventions
|
|
|
|
1. **Tests must stay green.** Run `make test` before committing.
|
|
2. **No cloud AI dependencies.** All inference on localhost.
|
|
3. **Keep the root directory clean.** No new top-level files without purpose.
|
|
4. **Follow existing patterns** — singletons, graceful degradation, pydantic config.
|
|
5. **Security defaults:** Never hard-code secrets.
|
|
6. **XSS prevention:** Never use `innerHTML` with untrusted content.
|
|
7. **Keep routes thin** — business logic lives in the module, not the route.
|
|
8. **Prefer editing existing files** over creating new ones.
|
|
9. **Use `from config import settings`** for all env-var access.
|
|
|
|
---
|
|
|
|
## Security-Sensitive Areas
|
|
|
|
- `src/swarm/coordinator.py` — requires review before changes
|
|
- `src/timmy_serve/l402_proxy.py` — Lightning payment gating
|
|
- `src/lightning/` — payment backend abstraction
|
|
- Any file handling secrets or authentication tokens
|
|
|
|
---
|
|
|
|
## Entry Points
|
|
|
|
| Command | Module | Purpose |
|
|
|---------|--------|---------|
|
|
| `timmy` | `src/timmy/cli.py` | Chat, think, status |
|
|
| `timmy-serve` | `src/timmy_serve/cli.py` | L402-gated API server (port 8402) |
|
|
| `self-tdd` | `src/self_coding/self_tdd/watchdog.py` | Continuous test watchdog |
|
|
| `self-modify` | `src/self_coding/self_modify/cli.py` | Self-modification CLI |
|
|
|
|
---
|
|
|
|
## Module Map (14 packages)
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| `timmy/` | Core agent, personas, agent interface, semantic memory |
|
|
| `dashboard/` | FastAPI web UI, routes, templates |
|
|
| `swarm/` | Multi-agent coordinator, task queue, work orders |
|
|
| `self_coding/` | Self-modification, test watchdog, upgrade queue |
|
|
| `creative/` | Media generation, MCP tools |
|
|
| `infrastructure/` | WebSocket, notifications, events, LLM router |
|
|
| `integrations/` | Discord, Telegram, Siri Shortcuts, voice NLU |
|
|
| `lightning/` | L402 payment gating (security-sensitive) |
|
|
| `mcp/` | MCP tool registry and discovery |
|
|
| `spark/` | Event capture and advisory engine |
|
|
| `hands/` | 6 autonomous Hand agents |
|
|
| `scripture/` | Biblical text integration |
|
|
| `timmy_serve/` | L402-gated API server |
|
|
| `config.py` | Pydantic settings (foundation for all modules) |
|