refactor: Phase 1/4/6 — doc cleanup, config fix, token optimization
Phase 1 — Documentation cleanup: - Slim README 303→93 lines (remove duplicated architecture, config tables) - Slim CLAUDE.md 267→80 lines (remove project layout, env vars, CI section) - Slim AGENTS.md 342→72 lines (remove duplicated patterns, running locally) - Delete MEMORY.md, WORKSET_PLAN.md, WORKSET_PLAN_PHASE2.md (session docs) - Archive PLAN.md, IMPLEMENTATION_SUMMARY.md to docs/ - Move QUALITY_ANALYSIS.md, QUALITY_REVIEW_REPORT.md to docs/ - Move apply_security_fixes.py, activate_self_tdd.sh to scripts/ Phase 4 — Config & build cleanup: - Fix wheel build: add 11 missing modules to pyproject.toml include list - Add pytest markers (unit, integration, dashboard, swarm, slow) - Add data/self_modify_reports/ and .handoff/ to .gitignore Phase 6 — Token optimization: - Add docstrings to 15 __init__.py files that were empty - Create __init__.py for events/, memory/, upgrades/ modules Root markdown: 87KB → ~18KB (79% reduction) https://claude.ai/code/session_019oMFNvD8uSGSSmBMGkBfQN
This commit is contained in:
Claude
6
.gitignore
vendored
6
.gitignore
vendored
@@ -35,6 +35,12 @@ coverage.xml
|
||||
htmlcov/
|
||||
reports/
|
||||
|
||||
# Self-modify reports (auto-generated)
|
||||
data/self_modify_reports/
|
||||
|
||||
# Handoff context (session-scoped)
|
||||
.handoff/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
|
||||
345
AGENTS.md
345
AGENTS.md
@@ -1,342 +1,79 @@
|
||||
# AGENTS.md — Timmy Time Development Standards for AI Agents
|
||||
|
||||
This file is the authoritative reference for any AI agent contributing to
|
||||
this repository. Read it first. Every time.
|
||||
Read [`CLAUDE.md`](CLAUDE.md) for architecture patterns and conventions.
|
||||
|
||||
---
|
||||
|
||||
## 1. Project at a Glance
|
||||
|
||||
**Timmy Time** is a local-first, sovereign AI agent system. No cloud. No telemetry.
|
||||
Bitcoin Lightning economics baked in.
|
||||
|
||||
| Thing | Value |
|
||||
|------------------|----------------------------------------------------|
|
||||
| Language | Python 3.11+ |
|
||||
| Web framework | FastAPI + Jinja2 + HTMX |
|
||||
| Agent framework | Agno (wraps Ollama or AirLLM) |
|
||||
| Persistence | SQLite (`timmy.db`, `data/swarm.db`) |
|
||||
| Tests | pytest — must stay green |
|
||||
| Entry points | `timmy`, `timmy-serve`, `self-tdd` |
|
||||
| Config | pydantic-settings, reads `.env` |
|
||||
| Containers | Docker — each agent can run as an isolated service |
|
||||
|
||||
```
|
||||
src/
|
||||
config.py # Central settings (OLLAMA_URL, DEBUG, etc.)
|
||||
timmy/ # Core agent: agent.py, backends.py, cli.py, prompts.py
|
||||
dashboard/ # FastAPI app + routes + Jinja2 templates
|
||||
app.py
|
||||
store.py # In-memory MessageLog singleton
|
||||
routes/ # agents, health, swarm, swarm_ws, marketplace,
|
||||
│ # mobile, mobile_test, voice, voice_enhanced,
|
||||
│ # swarm_internal (HTTP API for Docker agents)
|
||||
templates/ # base.html + page templates + partials/
|
||||
swarm/ # Multi-agent coordinator, registry, bidder, tasks, comms
|
||||
docker_runner.py # Spawn agents as Docker containers
|
||||
timmy_serve/ # L402 Lightning proxy, payment handler, TTS, CLI
|
||||
spark/ # Intelligence engine — events, predictions, advisory
|
||||
creative/ # Creative director + video assembler pipeline
|
||||
tools/ # Git, image, music, video tools for persona agents
|
||||
lightning/ # Lightning backend abstraction (mock + LND)
|
||||
agent_core/ # Substrate-agnostic agent interface
|
||||
voice/ # NLU intent detection (regex-based, no cloud)
|
||||
ws_manager/ # WebSocket manager (ws_manager singleton)
|
||||
notifications/ # Push notification store (notifier singleton)
|
||||
shortcuts/ # Siri Shortcuts API endpoints
|
||||
telegram_bot/ # Telegram bridge
|
||||
self_tdd/ # Continuous test watchdog
|
||||
tests/ # One test_*.py per module, all mocked
|
||||
static/ # style.css + bg.svg (arcane theme)
|
||||
docs/ # GitHub Pages site
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Non-Negotiable Rules
|
||||
## Non-Negotiable Rules
|
||||
|
||||
1. **Tests must stay green.** Run `make test` before committing.
|
||||
2. **No cloud dependencies.** All AI computation runs on localhost.
|
||||
3. **No new top-level files without purpose.** Don't litter the root directory.
|
||||
4. **Follow existing patterns** — singletons, graceful degradation, pydantic-settings config.
|
||||
5. **Security defaults:** Never hard-code secrets. Warn at startup when defaults are in use.
|
||||
4. **Follow existing patterns** — singletons, graceful degradation, pydantic-settings.
|
||||
5. **Security defaults:** Never hard-code secrets.
|
||||
6. **XSS prevention:** Never use `innerHTML` with untrusted content.
|
||||
|
||||
---
|
||||
|
||||
## 3. Agent Roster
|
||||
## Agent Roster
|
||||
|
||||
Agents are divided into two tiers: **Builders** generate code and features;
|
||||
**Reviewers** provide quality gates, feedback, and hardening. The Local agent
|
||||
is the primary workhorse — use it as much as possible to minimise cost.
|
||||
### Build Tier
|
||||
|
||||
**Local (Ollama)** — Primary workhorse. Free. Unrestricted.
|
||||
Best for: everything, iterative dev, Docker swarm workers.
|
||||
|
||||
**Kimi (Moonshot)** — Paid. Large-context feature drops, new subsystems, persona agents.
|
||||
Avoid: touching CI/pyproject.toml, adding cloud calls, removing tests.
|
||||
|
||||
**DeepSeek** — Near-free. Second-opinion generation, large refactors (R1 for hard problems).
|
||||
Avoid: bypassing review tier for security modules.
|
||||
|
||||
### Review Tier
|
||||
|
||||
**Claude (Anthropic)** — Architecture, tests, docs, CI/CD, PR review.
|
||||
Avoid: large one-shot feature dumps.
|
||||
|
||||
**Gemini (Google)** — Docs, frontend polish, boilerplate, diff summaries.
|
||||
Avoid: security modules, Python business logic without Claude review.
|
||||
|
||||
**Manus AI** — Security audits, coverage gaps, L402 validation.
|
||||
Avoid: large refactors, new features, prompt changes.
|
||||
|
||||
---
|
||||
|
||||
### 🏗️ BUILD TIER
|
||||
## Docker Agents
|
||||
|
||||
---
|
||||
|
||||
### Local — Ollama (primary workhorse)
|
||||
**Model:** Any — `qwen2.5-coder`, `deepseek-coder-v2`, `codellama`, or whatever
|
||||
is loaded in Ollama. The owner decides the model; this agent is unrestricted.
|
||||
**Cost:** Free. Runs on the host machine.
|
||||
|
||||
**Best for:**
|
||||
- Everything. This is the default agent for all coding tasks.
|
||||
- Iterative development, fast feedback loops, bulk generation
|
||||
- Running as a Docker swarm worker — scales horizontally at zero marginal cost
|
||||
- Experimenting with new models without changing any other code
|
||||
|
||||
**Conventions to follow:**
|
||||
- Communicate with the coordinator over HTTP (`COORDINATOR_URL` env var)
|
||||
- Register capabilities honestly so the auction system routes tasks well
|
||||
- Write tests for anything non-trivial
|
||||
|
||||
**No restrictions.** If a model can do it, do it.
|
||||
|
||||
---
|
||||
|
||||
### Kimi (Moonshot AI)
|
||||
**Model:** Moonshot large-context models.
|
||||
**Cost:** Paid API.
|
||||
|
||||
**Best for:**
|
||||
- Large context feature drops (new pages, new subsystems, new agent personas)
|
||||
- Implementing roadmap items that require reading many files at once
|
||||
- Generating boilerplate for new agents (Echo, Mace, Helm, Seer, Forge, Quill)
|
||||
|
||||
**Conventions to follow:**
|
||||
- Deliver working code with accompanying tests (even if minimal)
|
||||
- Match the arcane CSS theme — extend `static/style.css`
|
||||
- New agents follow the `SwarmNode` + `Registry` + Docker pattern
|
||||
- Lightning-gated endpoints follow the L402 pattern in `src/timmy_serve/l402_proxy.py`
|
||||
|
||||
**Avoid:**
|
||||
- Touching CI/CD or pyproject.toml without coordinating
|
||||
- Adding cloud API calls
|
||||
- Removing existing tests
|
||||
|
||||
---
|
||||
|
||||
### DeepSeek (DeepSeek API)
|
||||
**Model:** `deepseek-chat` (V3) or `deepseek-reasoner` (R1).
|
||||
**Cost:** Near-free (~$0.14/M tokens).
|
||||
|
||||
**Best for:**
|
||||
- Second-opinion feature generation when Kimi is busy or context is smaller
|
||||
- Large refactors with reasoning traces (use R1 for hard problems)
|
||||
- Code review passes before merging Kimi PRs
|
||||
- Anything that doesn't need a frontier model but benefits from strong reasoning
|
||||
|
||||
**Conventions to follow:**
|
||||
- Same conventions as Kimi
|
||||
- Prefer V3 for straightforward tasks; R1 for anything requiring multi-step logic
|
||||
- Submit PRs for review by Claude before merging
|
||||
|
||||
**Avoid:**
|
||||
- Bypassing the review tier for security-sensitive modules
|
||||
- Touching `src/swarm/coordinator.py` without Claude review
|
||||
|
||||
---
|
||||
|
||||
### 🔍 REVIEW TIER
|
||||
|
||||
---
|
||||
|
||||
### Claude (Anthropic)
|
||||
**Model:** Claude Sonnet.
|
||||
**Cost:** Paid API.
|
||||
|
||||
**Best for:**
|
||||
- Architecture decisions and code-quality review
|
||||
- Writing and fixing tests; keeping coverage green
|
||||
- Updating documentation (README, AGENTS.md, inline comments)
|
||||
- CI/CD, tooling, Docker infrastructure
|
||||
- Debugging tricky async or import issues
|
||||
- Reviewing PRs from Local, Kimi, and DeepSeek before merge
|
||||
|
||||
**Conventions to follow:**
|
||||
- Prefer editing existing files over creating new ones
|
||||
- Keep route files thin — business logic lives in the module, not the route
|
||||
- Use `from config import settings` for all env-var access
|
||||
- New routes go in `src/dashboard/routes/`, registered in `app.py`
|
||||
- Always add a corresponding `tests/test_<module>.py`
|
||||
|
||||
**Avoid:**
|
||||
- Large one-shot feature dumps (use Local or Kimi)
|
||||
- Touching `src/swarm/coordinator.py` for security work (that's Manus's lane)
|
||||
|
||||
---
|
||||
|
||||
### Gemini (Google)
|
||||
**Model:** Gemini 2.0 Flash (free tier) or Pro.
|
||||
**Cost:** Free tier generous; upgrade only if needed.
|
||||
|
||||
**Best for:**
|
||||
- Documentation, README updates, inline docstrings
|
||||
- Frontend polish — HTML templates, CSS, accessibility review
|
||||
- Boilerplate generation (test stubs, config files, GitHub Actions)
|
||||
- Summarising large diffs for human review
|
||||
|
||||
**Conventions to follow:**
|
||||
- Submit changes as PRs; always include a plain-English summary of what changed
|
||||
- For CSS changes, test at mobile breakpoint (≤768px) before submitting
|
||||
- Never modify Python business logic without Claude review
|
||||
|
||||
**Avoid:**
|
||||
- Security-sensitive modules (that's Manus's lane)
|
||||
- Changing auction or payment logic
|
||||
- Large Python refactors
|
||||
|
||||
---
|
||||
|
||||
### Manus AI
|
||||
**Strengths:** Precision security work, targeted bug fixes, coverage gap analysis.
|
||||
|
||||
**Best for:**
|
||||
- Security audits (XSS, injection, secret exposure)
|
||||
- Closing test coverage gaps for existing modules
|
||||
- Performance profiling of specific endpoints
|
||||
- Validating L402/Lightning payment flows
|
||||
|
||||
**Conventions to follow:**
|
||||
- Scope tightly — one security issue per PR
|
||||
- Every security fix must have a regression test
|
||||
- Use `pytest-cov` output to identify gaps before writing new tests
|
||||
- Document the vulnerability class in the PR description
|
||||
|
||||
**Avoid:**
|
||||
- Large-scale refactors (that's Claude's lane)
|
||||
- New feature work (use Local or Kimi)
|
||||
- Changing agent personas or prompt content
|
||||
|
||||
---
|
||||
|
||||
## 4. Docker — Running Agents as Containers
|
||||
|
||||
Each agent can run as an isolated Docker container. Containers share the
|
||||
`data/` volume for SQLite and communicate with the coordinator over HTTP.
|
||||
|
||||
```bash
|
||||
make docker-build # build the image
|
||||
make docker-up # start dashboard + deps
|
||||
make docker-agent # spawn one agent worker (LOCAL model)
|
||||
make docker-down # stop everything
|
||||
make docker-logs # tail all service logs
|
||||
```
|
||||
|
||||
### How container agents communicate
|
||||
|
||||
Container agents cannot use the in-memory `SwarmComms` channel. Instead they
|
||||
poll the coordinator's internal HTTP API:
|
||||
Container agents poll the coordinator's HTTP API (not in-memory `SwarmComms`):
|
||||
|
||||
```
|
||||
GET /internal/tasks → list tasks open for bidding
|
||||
POST /internal/bids → submit a bid
|
||||
```
|
||||
|
||||
Set `COORDINATOR_URL=http://dashboard:8000` in the container environment
|
||||
(docker-compose sets this automatically).
|
||||
`COORDINATOR_URL=http://dashboard:8000` is set by docker-compose.
|
||||
|
||||
### Spawning a container agent from Python
|
||||
|
||||
```python
|
||||
from swarm.docker_runner import DockerAgentRunner
|
||||
|
||||
runner = DockerAgentRunner(coordinator_url="http://dashboard:8000")
|
||||
info = runner.spawn("Echo", image="timmy-time:latest")
|
||||
runner.stop(info["container_id"])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Architecture Patterns
|
||||
|
||||
### Singletons (module-level instances)
|
||||
```python
|
||||
from dashboard.store import message_log
|
||||
from notifications.push import notifier
|
||||
from ws_manager.handler import ws_manager
|
||||
from timmy_serve.payment_handler import payment_handler
|
||||
from swarm.coordinator import coordinator
|
||||
```
|
||||
|
||||
### Config access
|
||||
```python
|
||||
from config import settings
|
||||
url = settings.ollama_url # never os.environ.get() directly in route files
|
||||
```
|
||||
|
||||
### HTMX pattern
|
||||
```python
|
||||
return templates.TemplateResponse(
|
||||
"partials/chat_message.html",
|
||||
{"request": request, "role": "user", "content": message}
|
||||
)
|
||||
```
|
||||
|
||||
### Graceful degradation
|
||||
```python
|
||||
try:
|
||||
result = await some_optional_service()
|
||||
except Exception:
|
||||
result = fallback_value # log, don't crash
|
||||
```
|
||||
|
||||
### Tests
|
||||
- All heavy deps (`agno`, `airllm`, `pyttsx3`) are stubbed in `tests/conftest.py`
|
||||
- Use `pytest.fixture` for shared state; prefer function scope
|
||||
- Use `TestClient` from `fastapi.testclient` for route tests
|
||||
- No real Ollama required — mock `agent.run()`
|
||||
|
||||
---
|
||||
|
||||
## 6. Running Locally
|
||||
|
||||
```bash
|
||||
make install # create venv + install dev deps
|
||||
make test # run full test suite
|
||||
make dev # start dashboard (http://localhost:8000)
|
||||
make watch # self-TDD watchdog (60s poll)
|
||||
make test-cov # coverage report
|
||||
```
|
||||
|
||||
Or with Docker:
|
||||
```bash
|
||||
make docker-build # build image
|
||||
make docker-up # start dashboard
|
||||
make docker-agent # add a Local agent worker
|
||||
make docker-agent # add a worker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Roadmap (v2 → v3)
|
||||
|
||||
**v2.0.0 — Exodus (in progress)**
|
||||
- [x] Persistent swarm state across restarts
|
||||
- [x] Docker infrastructure for agent containers
|
||||
- [x] Implement Echo, Mace, Helm, Seer, Forge, Quill persona agents (+ Pixel, Lyra, Reel)
|
||||
- [x] MCP tool integration for Timmy
|
||||
- [ ] Real LND gRPC backend for `PaymentHandler` (replace mock)
|
||||
- [ ] Marketplace frontend — wire `/marketplace` route to real data
|
||||
|
||||
**v3.0.0 — Revelation (planned)**
|
||||
- [ ] Bitcoin Lightning treasury (agent earns and spends sats autonomously)
|
||||
- [ ] Single `.app` bundle for macOS (no Python install required)
|
||||
- [ ] Federation — multiple Timmy instances discover and bid on each other's tasks
|
||||
- [ ] Redis pub/sub replacing SQLite polling for high-throughput swarms
|
||||
|
||||
---
|
||||
|
||||
## 8. File Conventions
|
||||
## File Conventions
|
||||
|
||||
| Pattern | Convention |
|
||||
|---------|-----------|
|
||||
| New route | `src/dashboard/routes/<name>.py` + register in `app.py` |
|
||||
| New template | `src/dashboard/templates/<name>.html` extends `base.html` |
|
||||
| New partial | `src/dashboard/templates/partials/<name>.html` |
|
||||
| New subsystem | `src/<name>/` with `__init__.py` |
|
||||
| New test file | `tests/test_<module>.py` |
|
||||
| Secrets | Read via `os.environ.get("VAR", "default")` + startup warning if default |
|
||||
| DB files | `.db` files go in project root or `data/` — never in `src/` |
|
||||
| Docker | One service per agent type in `docker-compose.yml` |
|
||||
| New test | `tests/test_<module>.py` |
|
||||
| Secrets | Via `config.settings` + startup warning if default |
|
||||
| DB files | Project root or `data/` — never in `src/` |
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
**v2.0 Exodus (in progress):** Swarm + L402 + Voice + Marketplace + Hands
|
||||
**v3.0 Revelation (planned):** Lightning treasury + `.app` bundle + federation
|
||||
|
||||
227
CLAUDE.md
227
CLAUDE.md
@@ -1,77 +1,9 @@
|
||||
# CLAUDE.md — AI Assistant Guide for Timmy Time
|
||||
|
||||
This file provides context for AI assistants (Claude Code, Copilot, etc.)
|
||||
working in this repository. Read this before making any changes.
|
||||
**Tech stack:** Python 3.11+ · FastAPI · Jinja2 + HTMX · SQLite · Agno ·
|
||||
Ollama · pydantic-settings · WebSockets · Docker
|
||||
|
||||
For multi-agent development standards and agent-specific conventions, see
|
||||
[`AGENTS.md`](AGENTS.md).
|
||||
|
||||
---
|
||||
|
||||
## Project Summary
|
||||
|
||||
**Timmy Time** is a local-first, sovereign AI agent system with a browser-based
|
||||
Mission Control dashboard. No cloud AI — all inference runs on localhost via
|
||||
Ollama (or AirLLM for large models). Bitcoin Lightning economics are built in
|
||||
for API access gating.
|
||||
|
||||
**Tech stack:** Python 3.11+ · FastAPI · Jinja2 + HTMX · SQLite · Agno (agent
|
||||
framework) · Ollama · pydantic-settings · WebSockets · Docker
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Setup
|
||||
make install # Create venv + install dev deps
|
||||
cp .env.example .env # Configure environment
|
||||
|
||||
# Development
|
||||
make dev # Start dashboard at http://localhost:8000
|
||||
make test # Run full test suite (no Ollama needed)
|
||||
make test-cov # Tests + coverage report (terminal + XML)
|
||||
make lint # Run ruff or flake8
|
||||
|
||||
# Docker
|
||||
make docker-build # Build timmy-time:latest image
|
||||
make docker-up # Start dashboard container
|
||||
make docker-agent # Spawn one agent worker
|
||||
make docker-down # Stop all containers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Layout
|
||||
|
||||
```
|
||||
src/
|
||||
config.py # Central pydantic-settings (all env vars)
|
||||
timmy/ # Core agent: agent.py, backends.py, cli.py, prompts.py
|
||||
dashboard/ # FastAPI app + routes + Jinja2 templates
|
||||
app.py # App factory, lifespan, router registration
|
||||
store.py # In-memory MessageLog singleton
|
||||
routes/ # One file per route group (agents, health, swarm, etc.)
|
||||
templates/ # base.html + page templates + partials/
|
||||
swarm/ # Multi-agent coordinator, registry, bidder, tasks, comms
|
||||
coordinator.py # Central swarm orchestrator (security-sensitive)
|
||||
docker_runner.py # Spawn agents as Docker containers
|
||||
timmy_serve/ # L402 Lightning proxy, payment handler, TTS, CLI
|
||||
spark/ # Intelligence engine — events, predictions, advisory
|
||||
creative/ # Creative director + video assembler pipeline
|
||||
tools/ # Git, image, music, video tools for persona agents
|
||||
lightning/ # Lightning backend abstraction (mock + LND)
|
||||
agent_core/ # Substrate-agnostic agent interface
|
||||
voice/ # NLU intent detection (regex-based, local)
|
||||
ws_manager/ # WebSocket connection manager (ws_manager singleton)
|
||||
notifications/ # Push notification store (notifier singleton)
|
||||
shortcuts/ # Siri Shortcuts API endpoints
|
||||
telegram_bot/ # Telegram bridge
|
||||
self_tdd/ # Continuous test watchdog
|
||||
tests/ # One test_*.py per module, all mocked
|
||||
static/ # style.css + bg.svg (dark arcane theme)
|
||||
docs/ # GitHub Pages landing site
|
||||
```
|
||||
For agent roster and conventions, see [`AGENTS.md`](AGENTS.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -79,32 +11,22 @@ docs/ # GitHub Pages landing site
|
||||
|
||||
### Config access
|
||||
|
||||
All configuration goes through `src/config.py` using pydantic-settings:
|
||||
|
||||
```python
|
||||
from config import settings
|
||||
url = settings.ollama_url # never use os.environ.get() directly in app code
|
||||
```
|
||||
|
||||
Environment variables are read from `.env` automatically. See `.env.example` for
|
||||
all available settings.
|
||||
|
||||
### Singletons
|
||||
|
||||
Core services are module-level singleton instances imported directly:
|
||||
|
||||
```python
|
||||
from dashboard.store import message_log
|
||||
from notifications.push import notifier
|
||||
from ws_manager.handler import ws_manager
|
||||
from timmy_serve.payment_handler import payment_handler
|
||||
from swarm.coordinator import coordinator
|
||||
```
|
||||
|
||||
### HTMX response pattern
|
||||
|
||||
Routes return Jinja2 template partials for HTMX requests:
|
||||
|
||||
```python
|
||||
return templates.TemplateResponse(
|
||||
"partials/chat_message.html",
|
||||
@@ -115,147 +37,41 @@ return templates.TemplateResponse(
|
||||
### Graceful degradation
|
||||
|
||||
Optional services (Ollama, Redis, AirLLM) degrade gracefully — log the error,
|
||||
return a fallback, never crash:
|
||||
|
||||
```python
|
||||
try:
|
||||
result = await some_optional_service()
|
||||
except Exception:
|
||||
result = fallback_value
|
||||
```
|
||||
return a fallback, never crash.
|
||||
|
||||
### Route registration
|
||||
|
||||
New routes go in `src/dashboard/routes/<name>.py`, then register the router in
|
||||
`src/dashboard/app.py`:
|
||||
|
||||
```python
|
||||
from dashboard.routes.<name> import router as <name>_router
|
||||
app.include_router(<name>_router)
|
||||
```
|
||||
New routes: `src/dashboard/routes/<name>.py` → register in `src/dashboard/app.py`.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Running tests
|
||||
|
||||
```bash
|
||||
make test # Quick run (pytest -q --tb=short)
|
||||
make test # Quick run (no Ollama needed)
|
||||
make test-cov # With coverage (term-missing + XML)
|
||||
make test-cov-html # With HTML coverage report
|
||||
```
|
||||
|
||||
No Ollama or external services needed — all heavy dependencies are mocked.
|
||||
|
||||
### Test conventions
|
||||
|
||||
- **One test file per module:** `tests/test_<module>.py`
|
||||
- **Stubs in conftest:** `agno`, `airllm`, `pyttsx3`, `telegram` are stubbed in
|
||||
`tests/conftest.py` using `sys.modules.setdefault()` so tests run without
|
||||
those packages installed
|
||||
- **Test mode:** `TIMMY_TEST_MODE=1` is set automatically in conftest to disable
|
||||
auto-spawning of persona agents during tests
|
||||
- **FastAPI testing:** Use the `client` fixture (wraps `TestClient`)
|
||||
- **Database isolation:** SQLite files in `data/` are cleaned between tests;
|
||||
coordinator state is reset via autouse fixtures
|
||||
- **Async:** `asyncio_mode = "auto"` in pytest config — async test functions
|
||||
are detected automatically
|
||||
- **Coverage threshold:** CI fails if coverage drops below 60%
|
||||
(`fail_under = 60` in `pyproject.toml`)
|
||||
|
||||
### Adding a new test
|
||||
|
||||
```python
|
||||
# tests/test_my_feature.py
|
||||
from fastapi.testclient import TestClient
|
||||
|
||||
def test_my_endpoint(client):
|
||||
response = client.get("/my-endpoint")
|
||||
assert response.status_code == 200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD
|
||||
|
||||
GitHub Actions workflow (`.github/workflows/tests.yml`):
|
||||
|
||||
- Runs on every push and pull request to all branches
|
||||
- Python 3.11, installs `.[dev]` dependencies
|
||||
- Runs pytest with coverage + JUnit XML output
|
||||
- Publishes test results as PR comments and check annotations
|
||||
- Uploads coverage XML as a downloadable artifact (14-day retention)
|
||||
- **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 runs on localhost.
|
||||
3. **No new top-level files without purpose.** Keep the root directory clean.
|
||||
4. **Follow existing patterns** — singletons, graceful degradation,
|
||||
pydantic-settings config.
|
||||
5. **Security defaults:** Never hard-code secrets. Warn at startup when using
|
||||
default values.
|
||||
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.
|
||||
10. **Every new module gets a test:** `tests/test_<module>.py`.
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
Three CLI commands are installed via `pyproject.toml`:
|
||||
|
||||
| Command | Module | Purpose |
|
||||
|---------|--------|---------|
|
||||
| `timmy` | `src/timmy/cli.py` | Chat, think, status commands |
|
||||
| `timmy-serve` | `src/timmy_serve/cli.py` | L402-gated API server (port 8402) |
|
||||
| `self-tdd` | `src/self_tdd/watchdog.py` | Continuous test watchdog |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key variables (full list in `.env.example`):
|
||||
|
||||
| Variable | Default | Purpose |
|
||||
|----------|---------|---------|
|
||||
| `OLLAMA_URL` | `http://localhost:11434` | Ollama host |
|
||||
| `OLLAMA_MODEL` | `llama3.2` | Model served by Ollama |
|
||||
| `DEBUG` | `false` | Enable `/docs` and `/redoc` |
|
||||
| `TIMMY_MODEL_BACKEND` | `ollama` | `ollama` / `airllm` / `auto` |
|
||||
| `AIRLLM_MODEL_SIZE` | `70b` | `8b` / `70b` / `405b` |
|
||||
| `L402_HMAC_SECRET` | *(change in prod)* | HMAC signing for invoices |
|
||||
| `L402_MACAROON_SECRET` | *(change in prod)* | Macaroon signing |
|
||||
| `LIGHTNING_BACKEND` | `mock` | `mock` / `lnd` |
|
||||
| `SPARK_ENABLED` | `true` | Enable Spark intelligence engine |
|
||||
| `TELEGRAM_TOKEN` | *(empty)* | Telegram bot token |
|
||||
|
||||
---
|
||||
|
||||
## Persistence
|
||||
|
||||
- `timmy.db` — Agno agent memory (SQLite, project root)
|
||||
- `data/swarm.db` — Swarm registry + tasks (SQLite, `data/` directory)
|
||||
- All `.db` files are gitignored — never commit database files
|
||||
|
||||
---
|
||||
|
||||
## Docker
|
||||
|
||||
Containers share a `data/` volume for SQLite. Container agents communicate with
|
||||
the coordinator over HTTP (not in-memory `SwarmComms`):
|
||||
|
||||
```
|
||||
GET /internal/tasks → list tasks open for bidding
|
||||
POST /internal/bids → submit a bid
|
||||
```
|
||||
|
||||
`COORDINATOR_URL=http://dashboard:8000` is set automatically by docker-compose.
|
||||
|
||||
---
|
||||
|
||||
@@ -265,3 +81,14 @@ POST /internal/bids → submit a bid
|
||||
- `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_tdd/watchdog.py` | Continuous test watchdog |
|
||||
| `self-modify` | `src/self_modify/cli.py` | Self-modification CLI |
|
||||
|
||||
71
MEMORY.md
71
MEMORY.md
@@ -1,71 +0,0 @@
|
||||
# Timmy Hot Memory
|
||||
|
||||
> Working RAM — always loaded, ~300 lines max, pruned monthly
|
||||
> Last updated: 2026-02-26
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
**Agent State:** Operational
|
||||
**Mode:** Development
|
||||
**Model:** llama3.2 (local via Ollama)
|
||||
**Backend:** Ollama on localhost:11434
|
||||
**Dashboard:** http://localhost:8000
|
||||
|
||||
---
|
||||
|
||||
## Standing Rules
|
||||
|
||||
1. **Sovereignty First** — No cloud AI dependencies
|
||||
2. **Local-Only Inference** — Ollama on localhost
|
||||
3. **Privacy by Design** — Telemetry disabled
|
||||
4. **Tool Minimalism** — Use tools only when necessary
|
||||
5. **Memory Discipline** — Write handoffs at session end
|
||||
6. **Clean Output** — Never show JSON, tool calls, or function syntax
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
|
||||
**Memory Tiers:**
|
||||
- Tier 1 (Hot): This file (MEMORY.md) — always in context
|
||||
- Tier 2 (Vault): memory/ directory — notes, profiles, AARs
|
||||
- Tier 3 (Semantic): Vector search over vault content
|
||||
|
||||
**Swarm Agents:** Echo (research), Forge (code), Seer (data)
|
||||
**Dashboard Pages:** Briefing, Swarm, Spark, Market, Tools, Events, Ledger, Memory, Router, Upgrades, Creative
|
||||
|
||||
---
|
||||
|
||||
## Agent Roster
|
||||
|
||||
| Agent | Role | Status |
|
||||
|-------|------|--------|
|
||||
| Timmy | Core AI | Active |
|
||||
| Echo | Research & Summarization | Active |
|
||||
| Forge | Coding & Debugging | Active |
|
||||
| Seer | Analytics & Prediction | Active |
|
||||
|
||||
---
|
||||
|
||||
## User Profile
|
||||
|
||||
**Name:** (not set)
|
||||
**Interests:** (to be learned)
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions
|
||||
|
||||
(none yet)
|
||||
|
||||
---
|
||||
|
||||
## Pending Actions
|
||||
|
||||
- [ ] Learn user's name and preferences
|
||||
|
||||
---
|
||||
|
||||
*Prune date: 2026-03-25*
|
||||
308
README.md
308
README.md
@@ -2,184 +2,69 @@
|
||||
|
||||
[](https://github.com/AlexanderWhitestone/Timmy-time-dashboard/actions/workflows/tests.yml)
|
||||
|
||||
A local-first, sovereign AI agent system. Talk to Timmy, watch his swarm, gate API access with Bitcoin Lightning — all from a browser, no cloud AI required.
|
||||
A local-first, sovereign AI agent system. Talk to Timmy, watch his swarm, gate
|
||||
API access with Bitcoin Lightning — all from a browser, no cloud AI required.
|
||||
|
||||
**[Live Docs →](https://alexanderwhitestone.github.io/Timmy-time-dashboard/)**
|
||||
|
||||
---
|
||||
|
||||
## What's built
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
git clone https://github.com/AlexanderWhitestone/Timmy-time-dashboard.git
|
||||
cd Timmy-time-dashboard
|
||||
make install # create venv + install deps
|
||||
cp .env.example .env # configure environment
|
||||
|
||||
ollama serve # separate terminal
|
||||
ollama pull llama3.2
|
||||
|
||||
make dev # http://localhost:8000
|
||||
make test # no Ollama needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What's Here
|
||||
|
||||
| Subsystem | Description |
|
||||
|-----------|-------------|
|
||||
| **Timmy Agent** | Agno-powered agent (Ollama default, AirLLM optional for 70B/405B) |
|
||||
| **Mission Control** | FastAPI + HTMX dashboard — chat, health, swarm, marketplace |
|
||||
| **Swarm** | Multi-agent coordinator — spawn agents, post tasks, run Lightning auctions |
|
||||
| **L402 / Lightning** | Bitcoin Lightning payment gating for API access (mock backend; LND scaffolded) |
|
||||
| **Spark Intelligence** | Event capture, predictions, memory consolidation, advisory engine |
|
||||
| **Creative Studio** | Multi-persona creative pipeline — image, music, video generation |
|
||||
| **Tools** | Git, image, music, and video tools accessible by persona agents |
|
||||
| **Voice** | NLU intent detection + TTS (pyttsx3, no cloud) |
|
||||
| **WebSocket** | Real-time swarm live feed |
|
||||
| **Mobile** | Responsive layout with full iOS safe-area and touch support |
|
||||
| **Telegram** | Bridge Telegram messages to Timmy |
|
||||
| **Swarm** | Multi-agent coordinator — spawn agents, post tasks, Lightning auctions |
|
||||
| **L402 / Lightning** | Bitcoin Lightning payment gating for API access |
|
||||
| **Spark** | Event capture, predictions, memory consolidation, advisory |
|
||||
| **Creative Studio** | Multi-persona pipeline — image, music, video generation |
|
||||
| **Hands** | 6 autonomous scheduled agents — Oracle, Sentinel, Scout, Scribe, Ledger, Weaver |
|
||||
| **CLI** | `timmy`, `timmy-serve`, `self-tdd` entry points |
|
||||
|
||||
**Full test suite, 100% passing.**
|
||||
| **Self-Coding** | Codebase-aware self-modification with git safety |
|
||||
| **Integrations** | Telegram bridge, Siri Shortcuts, voice NLU, mobile layout |
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**Python 3.11+**
|
||||
```bash
|
||||
python3 --version # must be 3.11+
|
||||
```
|
||||
If not: `brew install python@3.11`
|
||||
|
||||
**Ollama** — runs the local LLM
|
||||
```bash
|
||||
brew install ollama
|
||||
# or download from https://ollama.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quickstart
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# 1. Clone
|
||||
git clone https://github.com/AlexanderWhitestone/Timmy-time-dashboard.git
|
||||
cd Timmy-time-dashboard
|
||||
|
||||
# 2. Install
|
||||
make install
|
||||
# or manually: python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
|
||||
|
||||
# 3. Start Ollama (separate terminal)
|
||||
ollama serve
|
||||
ollama pull llama3.2
|
||||
|
||||
# 4. Launch dashboard
|
||||
make dev
|
||||
# opens at http://localhost:8000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
make test # run all tests (no Ollama needed)
|
||||
make test-cov # test + coverage report
|
||||
make dev # start dashboard (http://localhost:8000)
|
||||
make watch # self-TDD watchdog (60s poll, alerts on regressions)
|
||||
make test # run all tests
|
||||
make test-cov # tests + coverage report
|
||||
make lint # run ruff/flake8
|
||||
make docker-up # start via Docker
|
||||
make help # see all commands
|
||||
```
|
||||
|
||||
Or with the bootstrap script (creates venv, tests, watchdog, server in one shot):
|
||||
```bash
|
||||
bash activate_self_tdd.sh
|
||||
bash activate_self_tdd.sh --big-brain # also installs AirLLM
|
||||
```
|
||||
**CLI tools:** `timmy`, `timmy-serve`, `self-tdd`, `self-modify`
|
||||
|
||||
---
|
||||
|
||||
## CLI
|
||||
## Documentation
|
||||
|
||||
```bash
|
||||
timmy chat "What is sovereignty?"
|
||||
timmy think "Bitcoin and self-custody"
|
||||
timmy status
|
||||
|
||||
timmy-serve start # L402-gated API server (port 8402)
|
||||
timmy-serve invoice # generate a Lightning invoice
|
||||
timmy-serve status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mobile access
|
||||
|
||||
The dashboard is fully mobile-optimized (iOS safe area, 44px touch targets, 16px
|
||||
input to prevent zoom, momentum scroll).
|
||||
|
||||
```bash
|
||||
# Bind to your local network
|
||||
uvicorn dashboard.app:app --host 0.0.0.0 --port 8000 --reload
|
||||
|
||||
# Find your IP
|
||||
ipconfig getifaddr en0 # Wi-Fi on macOS
|
||||
```
|
||||
|
||||
Open `http://<your-ip>:8000` on your phone (same Wi-Fi network).
|
||||
|
||||
Mobile-specific routes:
|
||||
- `/mobile` — single-column optimized layout
|
||||
- `/mobile-test` — 21-scenario HITL test harness (layout, touch, scroll, notch)
|
||||
|
||||
---
|
||||
|
||||
## Hands — Autonomous Agents
|
||||
|
||||
Hands are scheduled, autonomous agents that run on cron schedules. Each Hand has a `HAND.toml` manifest, `SYSTEM.md` prompt, and optional `skills/` directory.
|
||||
|
||||
**Built-in Hands:**
|
||||
|
||||
| Hand | Schedule | Purpose |
|
||||
|------|----------|---------|
|
||||
| **Oracle** | 7am, 7pm UTC | Bitcoin intelligence — price, on-chain, macro analysis |
|
||||
| **Sentinel** | Every 15 min | System health — dashboard, agents, database, resources |
|
||||
| **Scout** | Every hour | OSINT monitoring — HN, Reddit, RSS for Bitcoin/sovereign AI |
|
||||
| **Scribe** | Daily 9am | Content production — blog posts, docs, changelog |
|
||||
| **Ledger** | Every 6 hours | Treasury tracking — Bitcoin/Lightning balances, payment audit |
|
||||
| **Weaver** | Sunday 10am | Creative pipeline — orchestrates Pixel+Lyra+Reel for video |
|
||||
|
||||
**Dashboard:** `/hands` — manage, trigger, approve actions
|
||||
|
||||
**Example HAND.toml:**
|
||||
```toml
|
||||
[hand]
|
||||
name = "oracle"
|
||||
schedule = "0 7,19 * * *" # Twice daily
|
||||
enabled = true
|
||||
|
||||
[tools]
|
||||
required = ["mempool_fetch", "price_fetch"]
|
||||
|
||||
[approval_gates]
|
||||
broadcast = { action = "broadcast", description = "Post to dashboard" }
|
||||
|
||||
[output]
|
||||
dashboard = true
|
||||
channel = "telegram"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AirLLM — big brain backend
|
||||
|
||||
Run 70B or 405B models locally with no GPU, using AirLLM's layer-by-layer loading.
|
||||
Apple Silicon uses MLX automatically.
|
||||
|
||||
```bash
|
||||
pip install ".[bigbrain]"
|
||||
pip install "airllm[mlx]" # Apple Silicon only
|
||||
|
||||
timmy chat "Explain self-custody" --backend airllm --model-size 70b
|
||||
```
|
||||
|
||||
Or set once in `.env`:
|
||||
```bash
|
||||
TIMMY_MODEL_BACKEND=auto
|
||||
AIRLLM_MODEL_SIZE=70b
|
||||
```
|
||||
|
||||
| Flag | Parameters | RAM needed |
|
||||
|-------|-------------|------------|
|
||||
| `8b` | 8 billion | ~16 GB |
|
||||
| `70b` | 70 billion | ~140 GB |
|
||||
| `405b`| 405 billion | ~810 GB |
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| [CLAUDE.md](CLAUDE.md) | AI assistant development guide |
|
||||
| [AGENTS.md](AGENTS.md) | Multi-agent development standards |
|
||||
| [.env.example](.env.example) | Configuration reference |
|
||||
| [docs/](docs/) | Architecture docs, ADRs, audits |
|
||||
|
||||
---
|
||||
|
||||
@@ -187,117 +72,26 @@ AIRLLM_MODEL_SIZE=70b
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# edit .env
|
||||
```
|
||||
|
||||
| Variable | Default | Purpose |
|
||||
|----------|---------|---------|
|
||||
| `OLLAMA_URL` | `http://localhost:11434` | Ollama host |
|
||||
| `OLLAMA_MODEL` | `llama3.2` | Model served by Ollama |
|
||||
| `DEBUG` | `false` | Enable `/docs` and `/redoc` |
|
||||
| `TIMMY_MODEL_BACKEND` | `ollama` | `ollama` \| `airllm` \| `auto` |
|
||||
| `AIRLLM_MODEL_SIZE` | `70b` | `8b` \| `70b` \| `405b` |
|
||||
| `L402_HMAC_SECRET` | *(default — change in prod)* | HMAC signing key for macaroons |
|
||||
| `L402_MACAROON_SECRET` | *(default — change in prod)* | Macaroon secret |
|
||||
| `LIGHTNING_BACKEND` | `mock` | `mock` (production-ready) \| `lnd` (scaffolded, not yet functional) |
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Browser / Phone
|
||||
│ HTTP + HTMX + WebSocket
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ FastAPI (dashboard.app) │
|
||||
│ routes: agents, health, swarm, │
|
||||
│ marketplace, voice, mobile │
|
||||
└───┬─────────────┬──────────┬────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
Jinja2 Timmy Swarm
|
||||
Templates Agent Coordinator
|
||||
(HTMX) │ ├─ Registry (SQLite)
|
||||
├─ Ollama ├─ AuctionManager (L402 bids)
|
||||
└─ AirLLM ├─ SwarmComms (Redis / in-memory)
|
||||
└─ SwarmManager (subprocess)
|
||||
│
|
||||
├── Voice NLU + TTS (pyttsx3, local)
|
||||
├── WebSocket live feed (ws_manager)
|
||||
├── L402 Lightning proxy (macaroon + invoice)
|
||||
├── Push notifications (local + macOS native)
|
||||
└── Siri Shortcuts API endpoints
|
||||
|
||||
Persistence: timmy.db (Agno memory), data/swarm.db (registry + tasks)
|
||||
External: Ollama :11434, optional Redis, optional LND gRPC
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project layout
|
||||
|
||||
```
|
||||
src/
|
||||
config.py # pydantic-settings — all env vars live here
|
||||
timmy/ # Core agent (agent.py, backends.py, cli.py, prompts.py)
|
||||
hands/ # Autonomous scheduled agents (registry, scheduler, runner)
|
||||
dashboard/ # FastAPI app, routes, Jinja2 templates
|
||||
swarm/ # Multi-agent: coordinator, registry, bidder, tasks, comms
|
||||
timmy_serve/ # L402 proxy, payment handler, TTS, serve CLI
|
||||
spark/ # Intelligence engine — events, predictions, advisory
|
||||
creative/ # Creative director + video assembler pipeline
|
||||
tools/ # Git, image, music, video tools for persona agents
|
||||
lightning/ # Lightning backend abstraction (mock + LND)
|
||||
agent_core/ # Substrate-agnostic agent interface
|
||||
voice/ # NLU intent detection
|
||||
ws_manager/ # WebSocket connection manager
|
||||
notifications/ # Push notification store
|
||||
shortcuts/ # Siri Shortcuts endpoints
|
||||
telegram_bot/ # Telegram bridge
|
||||
self_tdd/ # Continuous test watchdog
|
||||
hands/ # Hand manifests — oracle/, sentinel/, etc.
|
||||
tests/ # one test file per module, all mocked
|
||||
static/style.css # Dark mission-control theme (JetBrains Mono)
|
||||
docs/ # GitHub Pages landing page
|
||||
AGENTS.md # AI agent development standards ← read this
|
||||
.env.example # Environment variable reference
|
||||
Makefile # Common dev commands
|
||||
```
|
||||
Key variables: `OLLAMA_URL`, `OLLAMA_MODEL`, `TIMMY_MODEL_BACKEND`,
|
||||
`L402_HMAC_SECRET`, `LIGHTNING_BACKEND`, `DEBUG`. Full list in `.env.example`.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**`ollama: command not found`** — install from `brew install ollama` or ollama.com
|
||||
|
||||
**`connection refused` in chat** — run `ollama serve` in a separate terminal
|
||||
|
||||
**`ModuleNotFoundError: No module named 'sqlalchemy'`** — re-run install to pick up the updated `agno[sqlite]` dependency:
|
||||
`make install`
|
||||
|
||||
**`ModuleNotFoundError: No module named 'dashboard'`** — activate the venv:
|
||||
`source .venv/bin/activate && pip install -e ".[dev]"`
|
||||
|
||||
**Health panel shows DOWN** — Ollama isn't running; chat still works but returns
|
||||
the offline error message
|
||||
|
||||
**L402 startup warnings** — set `L402_HMAC_SECRET` and `L402_MACAROON_SECRET` in
|
||||
`.env` to silence them (required for production)
|
||||
|
||||
---
|
||||
|
||||
## For AI agents contributing to this repo
|
||||
|
||||
Read [`AGENTS.md`](AGENTS.md). It covers per-agent assignments, architecture
|
||||
patterns, coding conventions, and the v2→v3 roadmap.
|
||||
- **`ollama: command not found`** — `brew install ollama` or ollama.com
|
||||
- **`connection refused`** — run `ollama serve` first
|
||||
- **`ModuleNotFoundError`** — `source .venv/bin/activate && make install`
|
||||
- **Health panel shows DOWN** — Ollama isn't running; chat returns offline message
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
| Version | Name | Status | Milestone |
|
||||
|---------|------------|-------------|-----------|
|
||||
| 1.0.0 | Genesis | ✅ Complete | Agno + Ollama + SQLite + Dashboard |
|
||||
| 2.0.0 | Exodus | 🔄 In progress | Swarm + L402 + Voice + Marketplace + Hands |
|
||||
| 3.0.0 | Revelation | 📋 Planned | Lightning treasury + single `.app` bundle |
|
||||
| Version | Name | Status |
|
||||
|---------|------|--------|
|
||||
| 1.0 | Genesis | Complete — Agno + Ollama + SQLite + Dashboard |
|
||||
| 2.0 | Exodus | In progress — Swarm + L402 + Voice + Marketplace + Hands |
|
||||
| 3.0 | Revelation | Planned — Lightning treasury + single `.app` bundle |
|
||||
|
||||
147
WORKSET_PLAN.md
147
WORKSET_PLAN.md
@@ -1,147 +0,0 @@
|
||||
# Timmy Time — Workset Plan (Post-Quality Review)
|
||||
|
||||
**Date:** 2026-02-25
|
||||
**Based on:** QUALITY_ANALYSIS.md + QUALITY_REVIEW_REPORT.md
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This workset addresses critical security vulnerabilities, hardens the tool system for reliability, improves privacy alignment with the "sovereign AI" vision, and enhances agent intelligence.
|
||||
|
||||
---
|
||||
|
||||
## Workset A: Security Fixes (P0) 🔒
|
||||
|
||||
### A1: XSS Vulnerabilities (SEC-01)
|
||||
**Priority:** P0 — Critical
|
||||
**Files:** `mobile.html`, `swarm_live.html`
|
||||
|
||||
**Issues:**
|
||||
- `mobile.html` line ~85 uses raw `innerHTML` with unsanitized user input
|
||||
- `swarm_live.html` line ~72 uses `innerHTML` with WebSocket agent data
|
||||
|
||||
**Fix:** Replace `innerHTML` string interpolation with safe DOM methods (`textContent`, `createTextNode`, or DOMPurify if available).
|
||||
|
||||
### A2: Hardcoded Secrets (SEC-02)
|
||||
**Priority:** P1 — High
|
||||
**Files:** `l402_proxy.py`, `payment_handler.py`
|
||||
|
||||
**Issue:** Default secrets are production-safe strings instead of `None` with startup assertion.
|
||||
|
||||
**Fix:**
|
||||
- Change defaults to `None`
|
||||
- Add startup assertion requiring env vars to be set
|
||||
- Fail fast with clear error message
|
||||
|
||||
---
|
||||
|
||||
## Workset B: Tool System Hardening ⚙️
|
||||
|
||||
### B1: SSL Certificate Fix
|
||||
**Priority:** P1 — High
|
||||
**File:** Web search via DuckDuckGo
|
||||
|
||||
**Issue:** `CERTIFICATE_VERIFY_FAILED` errors prevent web search from working.
|
||||
|
||||
**Fix Options:**
|
||||
- Option 1: Use `certifi` package for proper certificate bundle
|
||||
- Option 2: Add `verify_ssl=False` parameter (less secure, acceptable for local)
|
||||
- Option 3: Document SSL fix in troubleshooting
|
||||
|
||||
### B2: Tool Usage Instructions
|
||||
**Priority:** P2 — Medium
|
||||
**File:** `prompts.py`
|
||||
|
||||
**Issue:** Agent makes unnecessary tool calls for simple questions.
|
||||
|
||||
**Fix:** Add tool usage instructions to system prompt:
|
||||
- Only use tools when explicitly needed
|
||||
- For simple chat/questions, respond directly
|
||||
- Tools are for: web search, file operations, code execution
|
||||
|
||||
### B3: Tool Error Handling
|
||||
**Priority:** P2 — Medium
|
||||
**File:** `tools.py`
|
||||
|
||||
**Issue:** Tool failures show stack traces to user.
|
||||
|
||||
**Fix:** Add graceful error handling with user-friendly messages.
|
||||
|
||||
---
|
||||
|
||||
## Workset C: Privacy & Sovereignty 🛡️
|
||||
|
||||
### C1: Agno Telemetry (Privacy)
|
||||
**Priority:** P2 — Medium
|
||||
**File:** `agent.py`, `backends.py`
|
||||
|
||||
**Issue:** Agno sends telemetry to `os-api.agno.com` which conflicts with "sovereign" vision.
|
||||
|
||||
**Fix:**
|
||||
- Add `telemetry_enabled=False` parameter to Agent
|
||||
- Document how to disable for air-gapped deployments
|
||||
- Consider environment variable `TIMMY_TELEMETRY=0`
|
||||
|
||||
### C2: Secrets Validation
|
||||
**Priority:** P1 — High
|
||||
**File:** `config.py`, startup
|
||||
|
||||
**Issue:** Default secrets used without warning in production.
|
||||
|
||||
**Fix:**
|
||||
- Add production mode detection
|
||||
- Fatal error if default secrets in production
|
||||
- Clear documentation on generating secrets
|
||||
|
||||
---
|
||||
|
||||
## Workset D: Agent Intelligence 🧠
|
||||
|
||||
### D1: Enhanced System Prompt
|
||||
**Priority:** P2 — Medium
|
||||
**File:** `prompts.py`
|
||||
|
||||
**Enhancements:**
|
||||
- Tool usage guidelines (when to use, when not to)
|
||||
- Memory awareness ("You remember previous conversations")
|
||||
- Self-knowledge (capabilities, limitations)
|
||||
- Response style guidelines
|
||||
|
||||
### D2: Memory Improvements
|
||||
**Priority:** P2 — Medium
|
||||
**File:** `agent.py`
|
||||
|
||||
**Enhancements:**
|
||||
- Increase history runs from 10 to 20 for better context
|
||||
- Add memory summarization for very long conversations
|
||||
- Persistent session tracking
|
||||
|
||||
---
|
||||
|
||||
## Execution Order
|
||||
|
||||
| Order | Workset | Task | Est. Time |
|
||||
|-------|---------|------|-----------|
|
||||
| 1 | A | XSS fixes | 30 min |
|
||||
| 2 | A | Secrets hardening | 20 min |
|
||||
| 3 | B | SSL certificate fix | 15 min |
|
||||
| 4 | B | Tool instructions | 20 min |
|
||||
| 5 | C | Telemetry disable | 15 min |
|
||||
| 6 | C | Secrets validation | 20 min |
|
||||
| 7 | D | Enhanced prompts | 30 min |
|
||||
| 8 | — | Test everything | 30 min |
|
||||
|
||||
**Total: ~3 hours**
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] No XSS vulnerabilities (verified by code review)
|
||||
- [ ] Secrets fail fast in production
|
||||
- [ ] Web search works without SSL errors
|
||||
- [ ] Agent uses tools appropriately (not for simple chat)
|
||||
- [ ] Telemetry disabled by default
|
||||
- [ ] All 895+ tests pass
|
||||
- [ ] New tests added for security fixes
|
||||
@@ -1,133 +0,0 @@
|
||||
# Timmy Time — Workset Plan Phase 2 (Functional Hardening)
|
||||
|
||||
**Date:** 2026-02-25
|
||||
**Based on:** QUALITY_ANALYSIS.md remaining issues
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This workset addresses the core functional gaps that prevent the swarm system from operating as designed. The swarm currently registers agents in the database but doesn't actually spawn processes or execute bids. This workset makes the swarm operational.
|
||||
|
||||
---
|
||||
|
||||
## Workset E: Swarm System Realization 🐝
|
||||
|
||||
### E1: Real Agent Process Spawning (FUNC-01)
|
||||
**Priority:** P1 — High
|
||||
**Files:** `swarm/agent_runner.py`, `swarm/coordinator.py`
|
||||
|
||||
**Issue:** `spawn_agent()` creates a database record but no Python process is actually launched.
|
||||
|
||||
**Fix:**
|
||||
- Complete the `agent_runner.py` subprocess implementation
|
||||
- Ensure spawned agents can communicate with coordinator
|
||||
- Add proper lifecycle management (start, monitor, stop)
|
||||
|
||||
### E2: Working Auction System (FUNC-02)
|
||||
**Priority:** P1 — High
|
||||
**Files:** `swarm/bidder.py`, `swarm/persona_node.py`
|
||||
|
||||
**Issue:** Bidding system runs auctions but no actual agents submit bids.
|
||||
|
||||
**Fix:**
|
||||
- Connect persona agents to the bidding system
|
||||
- Implement automatic bid generation based on capabilities
|
||||
- Ensure auction resolution assigns tasks to winners
|
||||
|
||||
### E3: Persona Agent Auto-Bidding
|
||||
**Priority:** P1 — High
|
||||
**Files:** `swarm/persona_node.py`, `swarm/coordinator.py`
|
||||
|
||||
**Fix:**
|
||||
- Spawned persona agents should automatically bid on matching tasks
|
||||
- Implement capability-based bid decisions
|
||||
- Add bid amount calculation (base + jitter)
|
||||
|
||||
---
|
||||
|
||||
## Workset F: Testing & Reliability 🧪
|
||||
|
||||
### F1: WebSocket Reconnection Tests (TEST-01)
|
||||
**Priority:** P2 — Medium
|
||||
**Files:** `tests/test_websocket.py`
|
||||
|
||||
**Issue:** WebSocket tests don't cover reconnection logic or malformed payloads.
|
||||
|
||||
**Fix:**
|
||||
- Add reconnection scenario tests
|
||||
- Test malformed payload handling
|
||||
- Test connection failure recovery
|
||||
|
||||
### F2: Voice TTS Graceful Degradation
|
||||
**Priority:** P2 — Medium
|
||||
**Files:** `timmy_serve/voice_tts.py`, `dashboard/routes/voice.py`
|
||||
|
||||
**Issue:** Voice routes fail without clear message when `pyttsx3` not installed.
|
||||
|
||||
**Fix:**
|
||||
- Add graceful fallback message
|
||||
- Return helpful error suggesting `pip install ".[voice]"`
|
||||
- Don't crash, return 503 with instructions
|
||||
|
||||
### F3: Mobile Route Navigation
|
||||
**Priority:** P2 — Medium
|
||||
**Files:** `templates/base.html`
|
||||
|
||||
**Issue:** `/mobile` route not linked from desktop navigation.
|
||||
|
||||
**Fix:**
|
||||
- Add mobile link to base template nav
|
||||
- Make it easy to find mobile-optimized view
|
||||
|
||||
---
|
||||
|
||||
## Workset G: Performance & Architecture ⚡
|
||||
|
||||
### G1: SQLite Connection Pooling (PERF-01)
|
||||
**Priority:** P3 — Low
|
||||
**Files:** `swarm/registry.py`
|
||||
|
||||
**Issue:** New SQLite connection opened on every query.
|
||||
|
||||
**Fix:**
|
||||
- Implement connection pooling or singleton pattern
|
||||
- Reduce connection overhead
|
||||
- Maintain thread safety
|
||||
|
||||
### G2: Development Experience
|
||||
**Priority:** P2 — Medium
|
||||
**Files:** `Makefile`, `README.md`
|
||||
|
||||
**Issue:** No single command to start full dev environment.
|
||||
|
||||
**Fix:**
|
||||
- Add `make dev-full` that starts dashboard + Ollama check
|
||||
- Add better startup validation
|
||||
|
||||
---
|
||||
|
||||
## Execution Order
|
||||
|
||||
| Order | Workset | Task | Est. Time |
|
||||
|-------|---------|------|-----------|
|
||||
| 1 | E | Persona auto-bidding system | 45 min |
|
||||
| 2 | E | Fix auction resolution | 30 min |
|
||||
| 3 | F | Voice graceful degradation | 20 min |
|
||||
| 4 | F | Mobile nav link | 10 min |
|
||||
| 5 | G | SQLite connection pooling | 30 min |
|
||||
| 6 | — | Test everything | 30 min |
|
||||
|
||||
**Total: ~2.5 hours**
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Persona agents automatically bid on matching tasks
|
||||
- [ ] Auctions resolve with actual winners
|
||||
- [ ] Voice routes degrade gracefully without pyttsx3
|
||||
- [ ] Mobile route accessible from desktop nav
|
||||
- [ ] SQLite connections pooled/reused
|
||||
- [ ] All 895+ tests pass
|
||||
- [ ] New tests for bidding system
|
||||
@@ -81,25 +81,35 @@ self-modify = "self_modify.cli:main"
|
||||
[tool.hatch.build.targets.wheel]
|
||||
sources = {"src" = ""}
|
||||
include = [
|
||||
"src/config.py",
|
||||
"src/agent_core",
|
||||
"src/agents",
|
||||
"src/chat_bridge",
|
||||
"src/creative",
|
||||
"src/dashboard",
|
||||
"src/events",
|
||||
"src/hands",
|
||||
"src/lightning",
|
||||
"src/mcp",
|
||||
"src/memory",
|
||||
"src/notifications",
|
||||
"src/router",
|
||||
"src/scripture",
|
||||
"src/self_coding",
|
||||
"src/self_modify",
|
||||
"src/self_tdd",
|
||||
"src/shortcuts",
|
||||
"src/spark",
|
||||
"src/swarm",
|
||||
"src/task_queue",
|
||||
"src/telegram_bot",
|
||||
"src/timmy",
|
||||
"src/timmy_serve",
|
||||
"src/dashboard",
|
||||
"src/config.py",
|
||||
"src/self_tdd",
|
||||
"src/swarm",
|
||||
"src/ws_manager",
|
||||
"src/voice",
|
||||
"src/notifications",
|
||||
"src/shortcuts",
|
||||
"src/telegram_bot",
|
||||
"src/chat_bridge",
|
||||
"src/spark",
|
||||
"src/tools",
|
||||
"src/creative",
|
||||
"src/agent_core",
|
||||
"src/lightning",
|
||||
"src/self_modify",
|
||||
"src/scripture",
|
||||
"src/upgrades",
|
||||
"src/voice",
|
||||
"src/work_orders",
|
||||
"src/ws_manager",
|
||||
]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
@@ -108,6 +118,13 @@ pythonpath = ["src", "tests"]
|
||||
asyncio_mode = "auto"
|
||||
asyncio_default_fixture_loop_scope = "function"
|
||||
addopts = "-v --tb=short"
|
||||
markers = [
|
||||
"unit: Unit tests (fast, no I/O)",
|
||||
"integration: Integration tests (may use SQLite)",
|
||||
"dashboard: Dashboard route tests",
|
||||
"swarm: Swarm coordinator tests",
|
||||
"slow: Tests that take >1 second",
|
||||
]
|
||||
|
||||
[tool.coverage.run]
|
||||
source = ["src"]
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Agent Core — Substrate-agnostic agent interface and base classes."""
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Dashboard — FastAPI + HTMX Mission Control web application."""
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Dashboard route modules — one file per route group."""
|
||||
|
||||
1
src/events/__init__.py
Normal file
1
src/events/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""Events — Domain event dispatch and subscription."""
|
||||
1
src/memory/__init__.py
Normal file
1
src/memory/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""Memory — Persistent conversation and knowledge memory."""
|
||||
@@ -1 +1 @@
|
||||
|
||||
"""Notifications — Push notification store (notifier singleton)."""
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Self-Modify — Runtime self-modification with safety constraints."""
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Self-TDD — Continuous test watchdog with regression alerting."""
|
||||
|
||||
@@ -1 +1 @@
|
||||
|
||||
"""Shortcuts — Siri Shortcuts API endpoints."""
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Spark — Intelligence engine for events, predictions, and advisory."""
|
||||
|
||||
@@ -1 +1 @@
|
||||
|
||||
"""Swarm — Multi-agent coordinator with auction-based task assignment."""
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Telegram Bot — Bridge Telegram messages to Timmy."""
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Timmy — Core AI agent (Ollama/AirLLM backends, CLI, prompts)."""
|
||||
|
||||
@@ -1 +1 @@
|
||||
|
||||
"""Timmy Serve — L402 Lightning-gated API server (port 8402)."""
|
||||
|
||||
1
src/upgrades/__init__.py
Normal file
1
src/upgrades/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""Upgrades — System upgrade queue and execution pipeline."""
|
||||
@@ -1 +1 @@
|
||||
|
||||
"""Voice — NLU intent detection (regex-based, local, no cloud)."""
|
||||
|
||||
@@ -1 +1 @@
|
||||
|
||||
"""WebSocket Manager — Real-time connection handler (ws_manager singleton)."""
|
||||
|
||||
Reference in New Issue
Block a user