# Familiar on Raspberry Pi

> **Your AI runs at home. Your data stays at home.**

Familiar is a self-hosted AI agent that runs on a Raspberry Pi in your closet. Your memories, conversations, and automation rules never leave your network—only API calls go to the cloud (and even those are optional with local LLMs).

---

## Why Run AI on a Pi?

| Aspect | Cloud-Hosted | Pi-Hosted |
|--------|-------------|-----------|
| **Monthly cost** | $6-24/month | $0 (after Pi) |
| **Your data** | On someone else's server | In your house |
| **Latency to smart home** | 50-200ms | <1ms |
| **Works offline** | ❌ | ✅ (with Ollama) |
| **GPIO/hardware access** | ❌ | ✅ Native |
| **Power consumption** | N/A | ~5W |

---

## Quick Start (5 minutes)

### Prerequisites

- Raspberry Pi 4 (4GB+) or Pi 5
- Raspberry Pi OS (64-bit recommended)
- Internet connection
- An API key from [Anthropic](https://console.anthropic.com/) or [OpenAI](https://platform.openai.com/)

### One-Line Install

```bash
curl -fsSL https://raw.githubusercontent.com/you/familiar/main/install-pi.sh | sudo bash
```

### Or with Local LLM (No Cloud Required)

```bash
curl -fsSL https://raw.githubusercontent.com/you/familiar/main/install-pi.sh | sudo bash -s -- --with-ollama
```

---

## Post-Install Setup

### 1. Add Your API Key

```bash
sudo nano /opt/familiar/.familiar/.env
```

Add your key:
```
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
```

### 2. Start Familiar

```bash
sudo systemctl start familiar
sudo systemctl enable familiar  # Start on boot
```

### 3. Test It

```bash
# Interactive CLI
sudo -u familiar /opt/familiar/venv/bin/python -m familiar.channels.cli

# Or check status
sudo systemctl status familiar
```

---

## Hardware Recommendations

### Minimum: Pi 4 (4GB) — $55

- ✅ Runs Familiar with cloud LLM backend
- ✅ Multiple chat channels (Telegram, Discord, etc.)
- ⚠️ Local LLM will be slow (~2 tokens/sec)

### Recommended: Pi 5 (8GB) — $80

- ✅ Everything above
- ✅ Local LLM at usable speed (~8-10 tokens/sec)
- ✅ Can run Llama 3.2 8B quantized

### Optimal: Pi 5 (8GB) + NVMe — $120

- ✅ Everything above
- ✅ Fast model loading from NVMe
- ✅ More storage for larger models

---

## Local LLM Options

With `--with-ollama`, Familiar can run entirely offline:

| Model | Size | Speed on Pi 5 | Good For |
|-------|------|---------------|----------|
| `phi3:mini` | 1.5GB | ~12 tok/s | Quick queries |
| `llama3.2:3b` | 2GB | ~8 tok/s | General use |
| `llama3.2:8b-q4` | 4GB | ~4 tok/s | Complex tasks |

Switch models anytime:
```bash
ollama pull llama3.2:3b
# Then edit /opt/familiar/.familiar/config.yaml
```

---

## Connecting Chat Channels

### Telegram

1. Create a bot via [@BotFather](https://t.me/BotFather)
2. Add token to `.env`:
   ```
   TELEGRAM_BOT_TOKEN=123456:ABC-xxx
   ```
3. Enable in config:
   ```yaml
   channels:
     telegram_enabled: true
   ```
4. Restart: `sudo systemctl restart familiar`

### Discord

1. Create app at [Discord Developer Portal](https://discord.com/developers/applications)
2. Add token to `.env`:
   ```
   DISCORD_BOT_TOKEN=xxx
   ```
3. Enable in config and restart

### Signal (via signal-cli)

Requires additional setup—see `docs/SIGNAL_SETUP.md`

---

## Security Model

Familiar uses **progressive trust**—users earn capabilities over time:

| Trust Level | After | Can Do |
|-------------|-------|--------|
| STRANGER | Immediately | Read time, weather |
| KNOWN | 10 interactions | Reminders, notes, calendar |
| TRUSTED | 50 interactions | Email, files (with confirmation) |
| OWNER | Manual grant | Everything (still logged) |

This prevents a compromised channel from immediately accessing sensitive operations.

---

## Monitoring

### Check Logs
```bash
tail -f /var/log/familiar/familiar.log
```

### Check CPU Temperature
```bash
vcgencmd measure_temp
# Or via Familiar:
# "Hey Familiar, what's my Pi's temperature?"
```

### Resource Usage
```bash
systemctl status familiar
htop  # Filter by 'familiar'
```

---

## GPIO & Home Automation

Familiar can control GPIO pins directly:

```python
# In skills/gpio/skill.py
# Already included - just wire up your hardware

# Example: "Turn on the living room light"
# → Triggers GPIO pin 17 HIGH
```

Integration ideas:
- Smart relay control
- Temperature/humidity sensors (DHT22)
- Motion detection alerts
- Garage door status

---

## Backup & Recovery

### Backup Your Data
```bash
sudo tar -czf familiar-backup-$(date +%Y%m%d).tar.gz \
  /opt/familiar/.familiar \
  /var/lib/familiar
```

### Restore
```bash
sudo systemctl stop familiar
sudo tar -xzf familiar-backup-YYYYMMDD.tar.gz -C /
sudo systemctl start familiar
```

---

## Troubleshooting

### "Cannot connect to Anthropic API"
- Check your API key in `/opt/familiar/.familiar/.env`
- Verify internet: `curl -I https://api.anthropic.com`

### "Out of memory" errors
- Reduce `max_tokens` in config.yaml
- If using Ollama, switch to smaller model
- Add swap: `sudo dphys-swapfile setup && sudo dphys-swapfile swapon`

### Slow responses
- Check CPU throttling: `vcgencmd get_throttled`
- Improve cooling (heatsink, fan)
- Use cloud LLM instead of local

### Service won't start
```bash
sudo journalctl -u familiar -n 50 --no-pager
```

---

## Updating

```bash
cd /opt/familiar/familiar
sudo -u familiar git pull
sudo -u familiar /opt/familiar/venv/bin/pip install -r requirements.txt
sudo systemctl restart familiar
```

---

## Uninstall

```bash
sudo systemctl stop familiar
sudo systemctl disable familiar
sudo rm /etc/systemd/system/familiar.service
sudo userdel -r familiar
sudo rm -rf /opt/familiar /var/lib/familiar /var/log/familiar
```

---

## Community

- GitHub Issues: Report bugs and request features
- Discussions: Share your Pi setups and automations

---

## License

MIT - See [LICENSE](LICENSE)

---

*Built for people who care where their data lives.*
