# Timmy Telemetry — Sovereign Monitoring Stack

Prometheus + Grafana + custom exporter for the Timmy Foundation infrastructure.
Zero cloud dependencies. Runs entirely on Hermes.

## What You Get

### Sovereignty Index (0-100)
Composite score across 7 dimensions:
| Dimension | What it measures | Weight |
|---|---|---|
| **Inference** | % of model calls going local vs cloud | 25% |
| **Compute** | Local GPU/CPU vs rented cloud | 20% |
| **Data** | Local storage (Gitea/SQLite/JSONL) vs cloud | 15% |
| **Infrastructure** | Self-hosted services vs SaaS | 15% |
| **Tools** | Local tools vs cloud-dependent ones | 15% |
| **Identity** | Self-managed keys vs platform accounts | 5% |
| **Financial** | Lightning/Cashu vs fiat rails | 5% |

### Top 5 Common Sense Metrics
1. **Commit Velocity** — commits/24h per repo (from Gitea API)
2. **Issues & PRs** — open counts, burn rate (from Gitea API)
3. **Heartbeat Health** — tick rate, consecutive OK, last tick age (from `~/.timmy/heartbeat/`)
4. **Local Inference** — calls today, success rate, avg response length (from `~/.timmy/metrics/`)
5. **Model Health** — Ollama up/down, API responding, inference OK, models loaded (from `~/.hermes/model_health.json`)

### Bonus
- Agent activity (commits per agent: claude, gemini, kimi, grok, perplexity, Timmy)
- DPO training pairs staged
- Sovereignty trend over time

## Deploy on Hermes

```bash
# Clone to Hermes
cd ~/.timmy
git clone <this-repo> timmy-telemetry
cd timmy-telemetry

# Set your Gitea token (or it uses the default)
export GITEA_TOKEN=130c3811bf4bae84a724cc165d677573d0f89636

# Launch
docker compose up -d
```

## Access

| Service | URL | Credentials |
|---|---|---|
| Grafana | http://localhost:3033 | admin / timmy |
| Prometheus | http://localhost:9090 | — |
| Exporter | http://localhost:9101/metrics | — |

Grafana auto-loads the "Timmy Sovereign Command" dashboard on first boot.

## Architecture

```
┌──────────────┐     scrape/30s     ┌──────────────┐
│  Prometheus  │◄────────────────── │   Exporter   │
│  :9090       │                    │   :9101      │
└──────┬───────┘                    └──────┬───────┘
       │                                   │ reads
       │                           ┌───────┴────────┐
┌──────▼───────┐                   │ ~/.timmy/       │
│   Grafana    │                   │   heartbeat/    │
│   :3033      │                   │   metrics/      │
│              │                   │ ~/.hermes/      │
│  Dashboards  │                   │   model_health  │
└──────────────┘                   │ Gitea API       │
                                   └────────────────┘
```

## Sovereignty Score Logic

The score starts pessimistic and improves as you migrate off cloud:
- **Every local inference call** pushes the inference dimension up
- **Deploying Nostr identity** (#13) will unlock the identity dimension
- **Lightning/Cashu** (#554, #555) will unlock the financial dimension
- **Replacing cloud agent workers** with local models pushes compute + tools up

Target: 100 = fully sovereign, $0 cloud bill, no external dependencies.