forked from Rockachopa/Timmy-time-dashboard
19af4ae540
Adds the `bigbrain` optional dependency group (airllm>=2.9.0) and a
complete second inference path that runs 8B / 70B / 405B Llama models
locally via layer-by-layer loading — no GPU required, no cloud, fully
sovereign.
Key changes:
- src/timmy/backends.py — TimmyAirLLMAgent (same print_response interface
as Agno Agent); auto-selects AirLLMMLX on Apple
Silicon, AutoModel (PyTorch) everywhere else
- src/timmy/agent.py — _resolve_backend() routing with explicit override,
env-config, and 'auto' Apple-Silicon detection
- src/timmy/cli.py — --backend / --model-size flags on all commands
- src/config.py — timmy_model_backend + airllm_model_size settings
- src/timmy/prompts.py — mentions AirLLM "even bigger brains, still fully
sovereign"
- pyproject.toml — bigbrain optional dep; wheel includes updated
- .env.example — TIMMY_MODEL_BACKEND + AIRLLM_MODEL_SIZE docs
- tests/conftest.py — stubs 'airllm' module so tests run without GPU
- tests/test_backends.py — 13 new tests covering helpers + TimmyAirLLMAgent
- tests/test_agent.py — 7 new tests for backend routing
- README.md — Big Brain section with one-line install
- activate_self_tdd.sh — bootstrap script (venv + install + tests +
watchdog + dashboard); --big-brain flag
All 61 tests pass. Self-TDD watchdog unaffected.
https://claude.ai/code/session_01DMjQ5qMZ8iHeyix1j3GS7c
276 lines
7.0 KiB
Markdown
276 lines
7.0 KiB
Markdown
# Timmy Time — Mission Control
|
|
|
|
[](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.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
You need three things on your Mac before anything else:
|
|
|
|
**Python 3.11+**
|
|
```bash
|
|
python3 --version # should be 3.11 or higher
|
|
```
|
|
If not: `brew install python@3.11`
|
|
|
|
**Ollama** (runs the local LLM)
|
|
```bash
|
|
brew install ollama
|
|
```
|
|
Or download from https://ollama.com
|
|
|
|
**Git** — already on every Mac.
|
|
|
|
---
|
|
|
|
## Quickstart (copy-paste friendly)
|
|
|
|
### 1. Clone the branch
|
|
|
|
```bash
|
|
git clone -b claude/run-tests-IYl0F https://github.com/Alexspayne/Timmy-time-dashboard.git
|
|
cd Timmy-time-dashboard
|
|
```
|
|
|
|
### 2. Create a virtual environment and install
|
|
|
|
```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
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## Optional: CLI
|
|
|
|
With your venv active:
|
|
|
|
```bash
|
|
timmy chat "What is sovereignty?"
|
|
timmy think "Bitcoin and self-custody"
|
|
timmy status
|
|
```
|
|
|
|
---
|
|
|
|
## Big Brain — AirLLM backend (Apple Silicon / large RAM)
|
|
|
|
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.
|
|
|
|
### One-line install
|
|
|
|
```bash
|
|
pip install ".[bigbrain]"
|
|
# Apple Silicon only — adds the MLX-accelerated backend:
|
|
pip install "airllm[mlx]"
|
|
```
|
|
|
|
### Run with the big brain
|
|
|
|
```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?"
|
|
```
|
|
|
|
`--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/
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
graph TD
|
|
Phone["📱 Phone / Browser"]
|
|
Browser["💻 Browser"]
|
|
|
|
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
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
**`ollama: command not found`** — Ollama isn't installed or isn't on your PATH. Install via Homebrew or the .dmg from ollama.com.
|
|
|
|
**`connection refused` in the chat** — Ollama isn't running. Open a terminal and run `ollama serve`, then try again.
|
|
|
|
**`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]"`.
|
|
|
|
**Health panel shows DOWN** — Ollama isn't running. The chat still works for testing but will return the offline error message.
|
|
|
|
---
|
|
|
|
## 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` |
|