timmy-home/infrastructure/timmy-bridge/README.md

# Timmy Bridge Epic

Complete sovereign communication infrastructure for Local Timmy — a fully offline AI that connects to the Wizardly Council via Nostr.

## Overview

This epic delivers end-to-end infrastructure enabling Local Timmy (running on Mac with MLX) to:
- Publish heartbeats every 5 minutes
- Create git-based artifacts
- Communicate via encrypted Nostr messages
- Generate daily retrospective reports

All while remaining fully sovereign — no cloud APIs, no external dependencies.

## Components

| Component | Status | Ticket | Description |
|-----------|--------|--------|-------------|
| **Relay** | ✅ Complete | #59 | Nostr relay at `ws://167.99.126.228:3334` |
| **Monitor** | ✅ Complete | #60 | SQLite-based metrics collection |
| **Client** | ✅ Complete | #61 | Mac heartbeat client with git integration |
| **MLX** | ✅ Complete | #62 | Local inference integration module |
| **Reports** | ✅ Complete | #63 | Morning retrospective automation |
| **Protocol** | ✅ Complete | #64 | Agent dispatch documentation |

## Quick Start

### 1. Deploy Relay (Cloud)

```bash
cd relay
docker-compose up -d
# Relay available at ws://167.99.126.228:3334
```

### 2. Start Monitor (Cloud)

```bash
cd monitor
pip install websockets
python3 timmy_monitor.py
# Logs to /root/allegro/monitor.log
```

### 3. Run Client (Mac)

```bash
# On Local Timmy's Mac
cd client
pip3 install websockets
python3 timmy_client.py
# Creates artifacts in ~/timmy-artifacts/
```

### 4. Enable MLX (Mac)

```bash
pip3 install mlx mlx-lm
export MLX_MODEL=/path/to/model
# Client auto-detects and uses MLX
```

### 5. Generate Reports

```bash
cd reports
python3 generate_report.py --hours 24 --format both
# Saves to /root/allegro/reports/
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        CLOUD                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Nostr Relay  │◄─┤   Monitor    │  │   Reports    │     │
│  │  :3334       │  │   (SQLite)   │  │   (Daily)    │     │
│  └──────┬───────┘  └──────────────┘  └──────────────┘     │
└─────────┼───────────────────────────────────────────────────┘
          │ WebSocket
          │
┌─────────┼───────────────────────────────────────────────────┐
│         │              LOCAL (Mac)                          │
│  ┌──────┴───────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Timmy Client │  │     MLX      │  │  Git Repo    │     │
│  │ (Heartbeat)  │◄─┤ (Inference)  │  │ (Artifacts)  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
```

## Acceptance Criteria

All tickets meet their specified acceptance criteria:

- [x] Relay runs on port 3334 with NIP support
- [x] Monitor logs heartbeats, artifacts, latency to SQLite
- [x] Client creates git commits every 5 minutes
- [x] MLX integration ready for local inference
- [x] Report generator creates daily markdown/JSON
- [x] Protocol documents group structure and dispatch commands

## File Structure

```
epic-work/
├── README.md                 # This file
├── relay/
│   ├── docker-compose.yml    # Relay deployment
│   └── strfry.conf          # Relay configuration
├── monitor/
│   └── timmy_monitor.py     # Metrics collection
├── client/
│   └── timmy_client.py      # Mac heartbeat client
├── mlx/
│   └── mlx_integration.py   # Local inference
├── reports/
│   └── generate_report.py   # Retrospective reports
└── protocol/
    └── DISPATCH_PROTOCOL.md # Communication spec
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `TIMMY_RELAY` | `ws://167.99.126.228:3334` | Nostr relay URL |
| `TIMMY_INTERVAL` | `300` | Heartbeat interval (seconds) |
| `TIMMY_ARTIFACTS` | `~/timmy-artifacts` | Git repository path |
| `TIMMY_DB` | `/root/allegro/timmy_metrics.db` | SQLite database |
| `MLX_MODEL` | `` | Path to MLX model |

## Dependencies

### Cloud (Relay + Monitor)
- Docker & docker-compose
- Python 3.10+
- websockets library

### Local (Mac Client)
- Python 3.10+
- websockets library
- Git
- MLX + mlx-lm (optional)

## Monitoring

Access metrics directly:

```bash
sqlite3 /root/allegro/timmy_metrics.db

# Recent heartbeats
SELECT * FROM heartbeats ORDER BY timestamp DESC LIMIT 10;

# Artifact count by type
SELECT artifact_type, COUNT(*) FROM artifacts GROUP BY artifact_type;
```

## Troubleshooting

### Relay won't start
```bash
docker-compose logs timmy-relay
# Check port 3334 not in use
ss -tlnp | grep 3334
```

### Client can't connect
```bash
# Test relay connectivity
websocat ws://167.99.126.228:3334

# Check firewall
nc -zv 167.99.126.228 3334
```

### No artifacts created
```bash
# Check git configuration
cd ~/timmy-artifacts
git status
git log --oneline -5
```

## Roadmap

- [ ] SSL termination (wss://)
- [ ] Multiple relay redundancy
- [ ] Encrypted group channels (NIP-44)
- [ ] File storage via Blossom (NIP-96)
- [ ] Automated PR creation from artifacts

## Contributors

- **Allegro** - Tempo-and-dispatch, infrastructure
- **Ezra** - Mac client deployment
- **Timmy** - Sovereign soul, local inference

## License

Sovereign software for sovereign individuals. Use freely, own completely.