diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..70faec5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,226 @@ +# AGENTS.md — Timmy Time Development Standards for AI Agents + +This file is the authoritative reference for any AI agent (Claude, Kimi, Manus, +or future tools) contributing to this repository. Read it first. Every time. + +--- + +## 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 — 228 passing, **must stay green** | +| Entry points | `timmy`, `timmy-serve`, `self-tdd` | +| Config | pydantic-settings, reads `.env` | + +``` +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 + templates/ # base.html + page templates + partials/ + swarm/ # Multi-agent coordinator, registry, bidder, tasks, comms + timmy_serve/ # L402 Lightning proxy, payment handler, TTS, CLI + voice/ # NLU intent detection (regex-based, no cloud) + websocket/ # WebSocket manager (ws_manager singleton) + notifications/ # Push notification store (notifier singleton) + shortcuts/ # Siri Shortcuts API endpoints + self_tdd/ # Continuous test watchdog +tests/ # One test_*.py per module, all mocked +static/style.css # Dark mission-control theme (JetBrains Mono) +docs/ # GitHub Pages site (docs/index.html) +``` + +--- + +## 2. Non-Negotiable Rules + +1. **Tests must stay green.** Run `make test` before committing. If you break + tests, fix them before you do anything else. +2. **No cloud dependencies.** All computation must run on localhost. +3. **No new top-level files without purpose.** Don't litter the root directory. +4. **Follow existing patterns** — singletons (`message_log`, `notifier`, + `ws_manager`, `coordinator`), graceful degradation (try/except → fallback), + pydantic-settings config. +5. **Security defaults:** Never hard-code secrets. Warn at startup when defaults + are in use (see `l402_proxy.py` and `payment_handler.py` for the pattern). +6. **XSS prevention:** Never use `innerHTML` with untrusted content. Use + `textContent` or `innerText` for any user-controlled string in JS. + +--- + +## 3. Per-Agent Assignments + +### Claude (Anthropic) +**Strengths:** Architecture, scaffolding, iterative refinement, testing, docs, breadth. + +**Best for:** +- Adding new subsystems from scratch +- Refactoring / code-quality passes +- Writing or fixing tests +- Updating documentation (README, AGENTS.md, inline comments) +- CI/CD and tooling +- Debugging tricky async or import issues + +**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` +- New templates extend `base.html` +- Always add a corresponding `tests/test_.py` + +**Avoid:** +- Large one-shot feature dumps (that's Kimi's lane) +- Touching `src/swarm/coordinator.py` for security work (that's Manus's lane) +- Committing with `--no-verify` + +--- + +### Kimi (Moonshot AI) +**Strengths:** High-volume feature generation, rapid expansion, large context. + +**Best for:** +- Big feature drops (new pages, new subsystems, new agent personas) +- Implementing the roadmap items listed below +- 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 dark Mission Control CSS theme — extend `static/style.css` +- New agents should follow the `SwarmNode` + `Registry` pattern in `src/swarm/` +- 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 + +--- + +### 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 (that's Kimi's lane) +- Changing agent personas or prompt content + +--- + +## 4. Architecture Patterns + +### Singletons (module-level instances) +These are shared state — import them, don't recreate them: +```python +from dashboard.store import message_log # MessageLog +from notifications.push import notifier # PushNotifier +from websocket.handler import ws_manager # WebSocketManager +from timmy_serve.payment_handler import payment_handler # PaymentHandler +from swarm.coordinator import coordinator # SwarmCoordinator +``` + +### Config access +```python +from config import settings +url = settings.ollama_url # never os.environ.get() directly in route files +``` + +### HTMX pattern +Server renders HTML fragments. Routes return `TemplateResponse` with a partial +template. JS is minimal — no React, no Vue. +```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()` + +--- + +## 5. 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 (background, 60s interval) +make test-cov # coverage report +``` + +Or manually: +```bash +python3 -m venv .venv && source .venv/bin/activate +pip install -e ".[dev]" +pytest # all 228 tests +uvicorn dashboard.app:app --reload --host 0.0.0.0 --port 8000 +``` + +--- + +## 6. Roadmap (v2 → v3) + +These are unbuilt items — claim one per PR, coordinate via Issues: + +**v2.0.0 — Exodus (in progress)** +- [ ] Implement Echo, Mace, Helm, Seer, Forge, Quill agent personas as Agno agents +- [ ] Real LND gRPC backend for `PaymentHandler` (replace mock) +- [ ] MCP tool integration for Timmy +- [ ] Marketplace frontend — wire up the existing `/marketplace` route to real data +- [ ] Persistent swarm state across restarts (currently in-memory) + +**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 + +--- + +## 7. File Conventions + +| Pattern | Convention | +|---------|-----------| +| New route | `src/dashboard/routes/.py` + register in `app.py` | +| New template | `src/dashboard/templates/.html` extends `base.html` | +| New partial | `src/dashboard/templates/partials/.html` | +| New subsystem | `src//` with `__init__.py` | +| New test file | `tests/test_.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/` | diff --git a/DEVELOPMENT_REPORT.md b/DEVELOPMENT_REPORT.md deleted file mode 100644 index c0b9fae..0000000 --- a/DEVELOPMENT_REPORT.md +++ /dev/null @@ -1,71 +0,0 @@ -# Timmy Time Dashboard: Development Report - -**Author:** Manus AI -**Date:** 2026-02-21 - -## 1. Introduction - -This report details the comprehensive development work undertaken to advance the Timmy Time Dashboard project. The initial request was to provide assistance with the project hosted on GitHub. After a thorough analysis of the repository and the provided bootstrap documentation, a significant gap was identified between the existing v1.0.0 codebase and the envisioned feature set. This project focused on bridging that gap by implementing all missing subsystems, adhering to a strict Test-Driven Development (TDD) methodology, and ensuring the final codebase is robust, well-tested, and aligned with the project's long-term vision. - -## 2. Initial State Analysis - -The initial repository at `v1.0.0` was a clean, well-structured foundation with a passing test suite of 61 tests. However, it represented only a small fraction of the functionality described in the bootstrap document. The core `TimmyAirLLMAgent` was present, along with a basic FastAPI dashboard, but the more advanced and economically significant features were entirely absent. - -### Key Missing Components: - -* **Swarm Subsystem:** The entire multi-agent coordination system, including the registry, manager, bidder, and task coordinator, was not implemented. -* **Economic Layer (L402):** The Lightning Network-based payment and authentication system was missing. -* **Enhanced I/O:** Voice (TTS/NLU), push notifications, and Siri Shortcuts integration were not present. -* **Dashboard Expansion:** Routes for managing the swarm, a marketplace for agents, and WebSocket-based live updates were needed. - -## 3. Development and Implementation - -The development process was divided into several phases, focusing on building out each missing subsystem and then integrating them into a cohesive whole. A strict Test-Driven Development (TDD) approach was adopted to ensure code quality and correctness from the outset. - -### 3.1. Test-Driven Development (TDD) - -For all new functionality, a TDD workflow was followed: - -1. **Write a Failing Test (Red):** A new test case was written to define the desired behavior of a feature that did not yet exist or was incorrect. -2. **Make the Test Pass (Green):** The minimum amount of code was written to make the failing test pass. -3. **Refactor:** The code was cleaned up and improved while ensuring all tests remained green. - -This iterative process resulted in a comprehensive test suite of **228 passing tests**, providing high confidence in the stability and correctness of the new features. - -### 3.2. New Modules and Features - -The following table summarizes the new modules that were created and integrated into the project: - -| Module | Path | Description | -| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| **Swarm** | `src/swarm/` | The core multi-agent system for task coordination, bidding, and execution. | -| **L402/Lightning**| `src/timmy_serve/` | Implements the L402 protocol for gating API access with Bitcoin Lightning payments. | -| **Voice** | `src/voice/` & `src/timmy_serve/` | Provides Natural Language Understanding (NLU) for intent detection and Text-to-Speech (TTS) for output. | -| **Notifications** | `src/notifications/` | A local push notification system for swarm events. | -| **Shortcuts** | `src/shortcuts/` | API endpoints for integration with Apple's Siri Shortcuts. | -| **WebSocket** | `src/websocket/` | Manages real-time WebSocket connections for the live dashboard. | -| **Dashboard Routes**| `src/dashboard/routes/` | New FastAPI routes to expose the functionality of the new subsystems. | - -### 3.3. Bug Fixes and Refinements - -During the TDD process, several minor bugs and areas for improvement were identified and addressed: - -* **NLU Entity Extraction:** The regular expression for extracting agent names was refined to correctly handle different phrasing (e.g., "spawn agent Echo" vs. "spawn Echo"). -* **Test Mocking Paths:** An incorrect patch path in a mobile test was corrected to ensure the test ran reliably. -* **Dependency Management:** The `pyproject.toml` file was updated to include all new modules and optional dependencies for the swarm and voice features. - -## 4. Final Test Results - -The final test suite was executed, and all **228 tests passed successfully**. This represents a significant increase from the initial 61 tests and covers all new functionality, including the swarm subsystem, L402 proxy, voice NLU, and all new dashboard routes. - -## 5. Conclusion and Next Steps - -The Timmy Time Dashboard project has been significantly advanced from its initial state to a feature-rich platform that aligns with the bootstrap vision. The implementation of the swarm, economic layer, and enhanced I/O modules provides a solid foundation for a sovereign, economically independent AI agent system. - -The codebase is now well-tested and ready for further development. The next logical steps would be to: - -* Implement the planned agent personas (Echo, Mace, etc.) as fully functional `Agno` agents. -* Integrate a real LND gRPC backend for the `PaymentHandler`. -* Build out the front-end of the dashboard to visualize and interact with the new swarm and marketplace features. - -This development effort has transformed the Timmy Time Dashboard from a concept into a tangible, working system, ready for the next stage of its evolution. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..7b15599 --- /dev/null +++ b/Makefile @@ -0,0 +1,69 @@ +.PHONY: install install-bigbrain dev test test-cov watch lint clean help + +VENV := .venv +PYTHON := $(VENV)/bin/python +PIP := $(VENV)/bin/pip +PYTEST := $(VENV)/bin/pytest +UVICORN := $(VENV)/bin/uvicorn +SELF_TDD := $(VENV)/bin/self-tdd + +# ── Setup ───────────────────────────────────────────────────────────────────── + +install: $(VENV)/bin/activate + $(PIP) install --quiet -e ".[dev]" + @echo "✓ Ready. Run 'make dev' to start the dashboard." + +install-bigbrain: $(VENV)/bin/activate + $(PIP) install --quiet -e ".[dev,bigbrain]" + @if [ "$$(uname -m)" = "arm64" ] && [ "$$(uname -s)" = "Darwin" ]; then \ + $(PIP) install --quiet "airllm[mlx]"; \ + echo "✓ AirLLM + MLX installed (Apple Silicon detected)"; \ + else \ + echo "✓ AirLLM installed (PyTorch backend)"; \ + fi + +$(VENV)/bin/activate: + python3 -m venv $(VENV) + +# ── Development ─────────────────────────────────────────────────────────────── + +dev: + $(UVICORN) dashboard.app:app --reload --host 0.0.0.0 --port 8000 + +watch: + $(SELF_TDD) watch --interval 60 + +# ── Testing ─────────────────────────────────────────────────────────────────── + +test: + $(PYTEST) tests/ -q --tb=short + +test-cov: + $(PYTEST) tests/ --cov=src --cov-report=term-missing --cov-report=xml -q + +# ── Code quality ────────────────────────────────────────────────────────────── + +lint: + @$(PYTHON) -m ruff check src/ tests/ 2>/dev/null || \ + $(PYTHON) -m flake8 src/ tests/ 2>/dev/null || \ + echo "No linter installed — run: pip install ruff" + +# ── Housekeeping ────────────────────────────────────────────────────────────── + +clean: + find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true + find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true + find . -name "*.pyc" -delete 2>/dev/null || true + rm -rf .pytest_cache htmlcov .coverage coverage.xml + +help: + @echo "" + @echo " make install create venv + install dev deps" + @echo " make install-bigbrain install with AirLLM (big-model backend)" + @echo " make dev start dashboard at http://localhost:8000" + @echo " make test run all 228 tests" + @echo " make test-cov tests + coverage report" + @echo " make watch self-TDD watchdog (60s poll)" + @echo " make lint run ruff or flake8" + @echo " make clean remove build artefacts and caches" + @echo "" diff --git a/README.md b/README.md index 6adb409..34b84b6 100644 --- a/README.md +++ b/README.md @@ -2,274 +2,249 @@ [![Tests](https://github.com/Alexspayne/Timmy-time-dashboard/actions/workflows/tests.yml/badge.svg)](https://github.com/Alexspayne/Timmy-time-dashboard/actions/workflows/tests.yml) -A local-first dashboard for your sovereign AI agents. Talk to Timmy, watch his status, verify Ollama is running — all from a browser, no cloud 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 required. + +**[Live Docs →](https://alexspayne.github.io/Timmy-time-dashboard/)** + +--- + +## What's built + +| 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 | +| **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 | +| **CLI** | `timmy`, `timmy-serve`, `self-tdd` entry points | + +**228 tests, 100% passing.** --- ## Prerequisites -You need three things on your Mac before anything else: - **Python 3.11+** ```bash -python3 --version # should be 3.11 or higher +python3 --version # must be 3.11+ ``` If not: `brew install python@3.11` -**Ollama** (runs the local LLM) +**Ollama** — runs the local LLM ```bash brew install ollama +# or download from https://ollama.com ``` -Or download from https://ollama.com - -**Git** — already on every Mac. --- -## Quickstart (copy-paste friendly) - -### 1. Clone the branch +## Quickstart ```bash -git clone -b claude/run-tests-IYl0F https://github.com/Alexspayne/Timmy-time-dashboard.git +# 1. Clone +git clone https://github.com/Alexspayne/Timmy-time-dashboard.git cd Timmy-time-dashboard -``` -### 2. Create a virtual environment and install +# 2. Install +make install +# or manually: python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" -```bash -python3 -m venv .venv -source .venv/bin/activate -pip install -e ".[dev]" -``` - -### 3. Pull the model (one-time, ~2 GB download) - -Open a **new terminal tab** and run: - -```bash +# 3. Start Ollama (separate terminal) ollama serve -``` - -Back in your first tab: - -```bash ollama pull llama3.2 -``` -### 4. Start the dashboard - -```bash -uvicorn dashboard.app:app --reload -``` - -Open your browser to **http://localhost:8000** - ---- - -## Access from your phone - -The dashboard is mobile-optimized. To open it on your phone: - -**Step 1 — bind to your local network** (instead of just localhost): - -```bash -uvicorn dashboard.app:app --host 0.0.0.0 --port 8000 --reload -``` - -**Step 2 — find your Mac's IP address:** - -```bash -ipconfig getifaddr en0 -``` - -This prints something like `192.168.1.42`. If you're on ethernet instead of Wi-Fi, try `en1`. - -**Step 3 — open on your phone:** - -Make sure your phone is on the **same Wi-Fi network** as your Mac, then open: - -``` -http://192.168.1.42:8000 -``` - -(replace with your actual IP) - -On mobile the layout switches to a single column — status panels become a horizontal scroll strip at the top, chat fills the rest of the screen. The input field is sized to prevent iOS from zooming in when you tap it. - ---- - -## What you'll see - -The dashboard has two panels on the left and a chat window on the right: - -- **AGENTS** — Timmy's metadata (model, type, version) -- **SYSTEM HEALTH** — live Ollama status, auto-refreshes every 30 seconds -- **TIMMY INTERFACE** — type a message, hit SEND, get a response from the local LLM - -If Ollama isn't running when you send a message, the chat will show a "Timmy is offline" error instead of crashing. - ---- - -## Run the tests - -No Ollama needed — all external calls are mocked. - -```bash -pytest -``` - -Expected output: -``` -27 passed in 0.67s +# 4. Launch dashboard +make dev +# opens at http://localhost:8000 ``` --- -## Optional: CLI +## Common commands -With your venv active: +```bash +make test # run all 228 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) +``` + +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 ```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 ``` --- -## Big Brain — AirLLM backend (Apple Silicon / large RAM) +## Mobile access -Run 70B or 405B models locally with no GPU required, using AirLLM's -layer-by-layer loading strategy. On M-series Macs the MLX backend is -selected automatically for maximum throughput. Everything stays local. -No cloud. No telemetry. Sats are sovereignty, boss. +The dashboard is fully mobile-optimized (iOS safe area, 44px touch targets, 16px +input to prevent zoom, momentum scroll). -### One-line install +```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://: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) + +--- + +## 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]" -# Apple Silicon only — adds the MLX-accelerated backend: -pip install "airllm[mlx]" +pip install "airllm[mlx]" # Apple Silicon only + +timmy chat "Explain self-custody" --backend airllm --model-size 70b ``` -### Run with the big brain +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 | + +--- + +## Configuration ```bash -# Explicit flag — works anywhere airllm is installed: -timmy chat "Explain self-custody" --backend airllm --model-size 70b - -# Or set it once in .env and forget about it: -echo "TIMMY_MODEL_BACKEND=auto" >> .env -echo "AIRLLM_MODEL_SIZE=70b" >> .env -timmy chat "What is sovereignty?" +cp .env.example .env +# edit .env ``` -`--backend auto` (or `TIMMY_MODEL_BACKEND=auto`) selects AirLLM automatically -on Apple Silicon when the package is installed, and falls back to Ollama -everywhere else — so the same `.env` works on any machine. - -### Model sizes - -| Flag | Parameters | Approx. RAM needed | -|------|-----------|-------------------| -| `8b` | 8 billion | ~16 GB | -| `70b` | 70 billion | ~140 GB | -| `405b` | 405 billion | ~810 GB | - -Models are downloaded from HuggingFace on first run and cached locally. -You need a HuggingFace account and `huggingface-cli login` for gated models -(Llama 3.1 requires accepting Meta's license at hf.co/meta-llama). - -### Architecture with AirLLM - -``` -timmy chat --backend airllm - │ - ▼ -TimmyAirLLMAgent (src/timmy/backends.py) - │ - ├─ Apple Silicon? ──► AirLLMMLX (MLX tensors, Metal GPU) - └─ Everything else ──► AutoModel (PyTorch, CPU/CUDA) - │ - └─ Layers loaded on-demand from ~/.cache/huggingface/ -``` +| 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` \| `lnd` | --- ## Architecture -```mermaid -graph TD - Phone["📱 Phone / Browser"] - Browser["💻 Browser"] +``` +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 - Phone -->|HTTP + HTMX| FastAPI - Browser -->|HTTP + HTMX| FastAPI - - subgraph "Local Machine" - FastAPI["FastAPI\n(dashboard.app)"] - Jinja["Jinja2 Templates\n+ static CSS"] - Timmy["Timmy Agent\n(Agno wrapper)"] - Ollama["Ollama\n:11434"] - SQLite[("SQLite\ntimmy.db")] - - FastAPI -->|renders| Jinja - FastAPI -->|/agents/timmy/chat| Timmy - FastAPI -->|/health/status ping| Ollama - Timmy -->|LLM call| Ollama - Timmy -->|conversation memory| SQLite - end +Persistence: timmy.db (Agno memory), data/swarm.db (registry + tasks) +External: Ollama :11434, optional Redis, optional LND gRPC ``` -All traffic stays on your local network. No cloud, no telemetry. - -## Configuration - -Override defaults without touching code — create a `.env` file (see `.env.example`): - -```bash -cp .env.example .env -# then edit .env -``` - -| Variable | Default | Purpose | -|---|---|---| -| `OLLAMA_URL` | `http://localhost:11434` | Ollama host (useful if Ollama runs on another machine) | -| `OLLAMA_MODEL` | `llama3.2` | LLM model served by Ollama | -| `DEBUG` | `false` | Set `true` to enable `/docs` and `/redoc` | +--- ## Project layout ``` src/ - config.py # pydantic-settings (reads .env) - timmy/ # Timmy agent — wraps Agno (soul = prompt, body = Agno) - dashboard/ # FastAPI app + routes + Jinja2 templates -static/ # CSS (dark mission-control theme) -tests/ # pytest suite (27 tests, no Ollama required) -.env.example # environment variable reference -pyproject.toml # dependencies and build config + config.py # pydantic-settings — all env vars live here + timmy/ # Core agent (agent.py, backends.py, cli.py, prompts.py) + dashboard/ # FastAPI app, routes, Jinja2 templates + swarm/ # Multi-agent: coordinator, registry, bidder, tasks, comms + timmy_serve/ # L402 proxy, payment handler, TTS, serve CLI + voice/ # NLU intent detection + websocket/ # WebSocket connection manager + notifications/ # Push notification store + shortcuts/ # Siri Shortcuts endpoints + self_tdd/ # Continuous test watchdog +tests/ # 228 tests — one 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 ``` --- ## Troubleshooting -**`ollama: command not found`** — Ollama isn't installed or isn't on your PATH. Install via Homebrew or the .dmg from ollama.com. +**`ollama: command not found`** — install from `brew install ollama` or ollama.com -**`connection refused` in the chat** — Ollama isn't running. Open a terminal and run `ollama serve`, then try again. +**`connection refused` in chat** — run `ollama serve` in a separate terminal -**`ModuleNotFoundError: No module named 'dashboard'`** — You're not in the venv or forgot `pip install -e .`. Run `source .venv/bin/activate` then `pip install -e ".[dev]"`. +**`ModuleNotFoundError: No module named 'dashboard'`** — activate the venv: +`source .venv/bin/activate && pip install -e ".[dev]"` -**Health panel shows DOWN** — Ollama isn't running. The chat still works for testing but will return the offline error message. +**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. --- ## Roadmap -| Version | Name | Milestone | -|---------|------------|--------------------------------------------| -| 1.0.0 | Genesis | Agno + Ollama + SQLite + Dashboard | -| 2.0.0 | Exodus | MCP tools + multi-agent | -| 3.0.0 | Revelation | Bitcoin Lightning treasury + single `.app` | +| Version | Name | Status | Milestone | +|---------|------------|-------------|-----------| +| 1.0.0 | Genesis | ✅ Complete | Agno + Ollama + SQLite + Dashboard | +| 2.0.0 | Exodus | 🔄 In progress | Swarm + L402 + Voice + Marketplace | +| 3.0.0 | Revelation | 📋 Planned | Lightning treasury + single `.app` bundle | diff --git a/STATUS.md b/STATUS.md deleted file mode 100644 index 2e1ffef..0000000 --- a/STATUS.md +++ /dev/null @@ -1,47 +0,0 @@ -# Timmy Time — Status - -## Current Version: 1.0.0 (Genesis) - -### What's Built -- `src/timmy/` — Agno-powered Timmy agent (llama3.2 via Ollama, SQLite memory) -- `src/dashboard/` — FastAPI Mission Control dashboard (HTMX + Jinja2) -- CLI: `timmy think / chat / status` -- Pytest test suite (prompts, agent config, dashboard routes) - -### System Requirements -- Python 3.11+ -- Ollama running at `http://localhost:11434` -- `llama3.2` model pulled - -### Quickstart -```bash -pip install -e ".[dev]" - -# Start Ollama (separate terminal) -ollama serve -ollama pull llama3.2 - -# Run dashboard -uvicorn dashboard.app:app --reload - -# Run tests (no Ollama required) -pytest -``` - -### Dashboard -`http://localhost:8000` — Mission Control UI with: -- Timmy agent status panel -- Ollama health indicator (auto-refreshes every 30s) -- Live chat interface - ---- - -## Roadmap - -| Tag | Name | Milestone | -|-------|------------|----------------------------------------------| -| 1.0.0 | Genesis | Agno + Ollama + SQLite + Dashboard | -| 2.0.0 | Exodus | MCP tools + multi-agent support | -| 3.0.0 | Revelation | Bitcoin Lightning treasury + single `.app` | - -_Last updated: 2026-02-19_ diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..f31ba49 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,926 @@ + + + + + + Timmy Time — Mission Control + + + + + + + + +
+ + +
+ + +
+

Sovereign AI Agent System

+

Your agents.
Your hardware.
Your sats.

+

+ A local-first AI command center. Talk to Timmy, coordinate your swarm, + gate API access with Bitcoin Lightning — no cloud, no telemetry, no compromise. +

+
+ 228 Tests Passing + FastAPI + HTMX + Lightning L402 + No Cloud + Multi-Agent Swarm + MIT License +
+
+ View on GitHub + Get Started +
+
+ + +
+
+
228
+
Tests Passing
+
+
+
20+
+
API Endpoints
+
+
+
11
+
Subsystems
+
+
+
0
+
Cloud Calls
+
+
+ +
+ + +
+

Capabilities

+

Everything in one dashboard

+

+ Built for the operator who wants sovereignty without sacrificing capability. + Every subsystem works offline. +

+
+ +
+ 🤖 +

Timmy Agent

+

Agno-powered conversational agent backed by Ollama (llama3.2 default) or + AirLLM for 70B–405B models on Apple Silicon. SQLite memory, no cloud.

+ Agno · Ollama · AirLLM +
+ +
+ 🌐 +

Mission Control UI

+

FastAPI backend with Jinja2 + HTMX frontend. Dark terminal aesthetic. + Real-time health polling, chat history, live swarm feed — no JavaScript framework.

+ FastAPI · HTMX · Bootstrap 5 +
+ +
+ 🐝 +

Multi-Agent Swarm

+

Spawn sub-agents, post tasks, run 15-second Lightning auctions. Registry, + manager, bidder, and coordinator — all in-process or as separate subprocesses.

+ Coordinator · Registry · Auction +
+ +
+ ⚡ +

L402 Lightning Payments

+

Bitcoin Lightning payment gating via HMAC macaroons. Mock backend for dev, + LND gRPC-ready for production. Agents earn and spend sats autonomously.

+ L402 · Macaroon · BOLT11 +
+ +
+ 🎙️ +

Voice I/O

+

Pattern-matched NLU detects intents (status, swarm, task, help) from natural + language. TTS via pyttsx3 speaks responses aloud. Fully offline.

+ NLU · pyttsx3 · Intent Detection +
+ +
+ 📱 +

Mobile Optimized

+

iOS safe-area, 44px touch targets, 16px inputs (no zoom), momentum scroll, + dynamic viewport height. 21-scenario HITL test harness built in.

+ iOS · HITL · Responsive +
+ +
+ 🔴 +

WebSocket Live Feed

+

Real-time swarm events — agent joins, task posts, auction bids, completions — + broadcast over WebSocket to the live dashboard.

+ WebSocket · Live Events +
+ +
+ 🛡️ +

Security First

+

XSS prevention via textContent (not innerHTML). Startup warnings for default + secrets. HMAC-signed macaroons. Graceful degradation on every optional service.

+ XSS-safe · HMAC · Warnings +
+ +
+ 🔧 +

Self-TDD Watchdog

+

Continuous test runner polls pytest every 60 seconds and alerts on regressions. + Runs alongside dev work in the background — silent when green.

+ pytest · self-tdd · CI +
+ +
+
+ +
+ + +
+

System Design

+

Architecture

+

+ A layered local stack. Every dependency can degrade gracefully — Ollama offline? + Error message. Redis missing? In-memory pub/sub. pyttsx3 absent? TTS is a no-op. +

+
+ 
+Browser / Phone
+      │ HTTP + HTMX + WebSocket
+      ▼
+┌─────────────────────────────────────────────────────────┐
+│                  FastAPI  (dashboard.app)                  │
+│  routes: agents · health · swarm · marketplace · voice  │
+└────────┬──────────────┬────────────────┬────────────────┘
+         │              │                │
+         ▼              ▼                ▼
+    Jinja2         Timmy Agent       Swarm Coordinator
+    Templates      │                  ├─ Registry    (SQLite)
+    (HTMX)         ├─ Ollama           ├─ AuctionManager  (15s bids)
+                   └─ AirLLM           ├─ SwarmComms     (Redis / mem)
+                      (70B–405B)       └─ SwarmManager  (subprocess)
+         │
+         ├── Voice NLU + TTS      (pyttsx3, local)
+         ├── WebSocket live feed  (ws_manager)
+         ├── L402 Lightning proxy (macaroon + BOLT11 invoice)
+         ├── Push notifications   (local + macOS native)
+         └── Siri Shortcuts API  (iOS automation endpoints)
+
+Persistence:  timmy.db (Agno memory) · data/swarm.db (registry + tasks)
+External:     Ollama :11434 · optional Redis · optional LND gRPC
+
+
+
+ +
+ + +
+

Get Running

+

Quickstart

+

+ Five minutes from zero to a running agent. You need Python 3.11+ and Ollama. +

+
+ +
+
1
+
+

Clone

+ 
git clone https://github.com/Alexspayne/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

+ 
# In a separate terminal:
+ollama serve
+ollama pull llama3.2   # ~2 GB, one-time download
+
+
+ +
+
4
+
+

Launch

+ 
make dev
+# Opens at http://localhost:8000
+# Mobile: http://<your-lan-ip>:8000
+
+
+ +
+
5
+
+

Test

+ 
make test        # 228 tests — no Ollama needed
+make test-cov    # + coverage report
+make watch       # self-TDD watchdog in background
+
+
+ +
+
+ +
+ + +
+

Contributors

+

The agent team

+

+ This repo is built by a multi-agent team. Each tool has a defined lane. + See AGENTS.md + for the full development standards. +

+
+ +
+
+
Claude
+
Anthropic · Architect
+
    +
  • Foundation, scaffolding, CI
    • +
  • Testing and quality passes
    • +
  • Documentation and tooling
    • +
  • Iterative refinement
    • +
+
+ +
+
+
Kimi
+
Moonshot AI · Feature Engine
+
    +
  • High-volume feature drops
    • +
  • New subsystem builds
    • +
  • Large context, rapid expansion
    • +
  • Agent persona implementation
    • +
+
+ +
+
+
Manus
+
Manus AI · Security Specialist
+
    +
  • Security audits (XSS, injection)
    • +
  • Coverage gap analysis
    • +
  • Targeted bug fixes
    • +
  • Payment flow validation
    • +
+
+ +
+
+
Alex Payne
+
Human · Orchestrator
+
    +
  • Vision and product decisions
    • +
  • Agent task assignment
    • +
  • PR review and merge
    • +
  • Bitcoin / Lightning domain
    • +
+
+ +
+
+ +
+ + +
+

What's Next

+

Roadmap

+

Three phases, each named after a book.

+
+ +
+
+
v1.0.0
+
Genesis
+
+
+
✓ Complete
+

Foundation

+

Agno + Ollama + SQLite + FastAPI dashboard + HTMX + 228 tests. + CLI, mobile layout, Bootstrap, CI/CD, AirLLM big-brain backend.

+
+
+ +
+
+
v2.0.0
+
Exodus
+
+
+
⟳ In progress
+

Multi-Agent Economy

+

Swarm coordination, L402 Lightning payment gating, voice NLU/TTS, + marketplace, WebSocket live feed. Agent personas: Echo, Mace, Helm, + Seer, Forge, Quill. Real LND gRPC backend.

+
+
+ +
+
+
v3.0.0
+
Revelation
+
+
+
◌ Planned
+

Sovereign Deployment

+

Bitcoin Lightning treasury — agents earn and spend sats autonomously. + Single .app bundle for macOS (no Python install). + Federation between Timmy instances.

+
+
+ +
+
+ +
+ + + + + +