# Familiar

**Self-hosted AI agent with Signal-grade encryption**

![Version](https://img.shields.io/badge/version-1.12.1-purple) ![Python](https://img.shields.io/badge/python-3.10+-green) ![License](https://img.shields.io/badge/license-MIT-orange)

---

## Quick Start

### Install from PyPI

```bash
pip install familiar-agent[llm]
export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY
python -m familiar
```

### Run from source

```bash
git clone https://github.com/omegcrash/familiar.git
cd familiar/familiar
./run.sh
```

`run.sh` auto-detects your setup. If you have Ollama installed, it uses local AI (free, private). If you set an API key, it uses Claude or GPT instead.

**That's it.** No Docker, no databases, no config files needed.

### Setup Wizard

For a guided setup experience, use the onboarding wizard:

```bash
python -m familiar --onboard          # CLI wizard (step-by-step)
python -m familiar --onboard-tui      # Rich terminal UI (keyboard-navigable)
python -m familiar --reconfigure      # Re-run setup to change settings
```

The wizard auto-detects your LLM providers (Anthropic, OpenAI, Gemini, Ollama), lets you configure channels (Telegram, Discord, Matrix, WhatsApp, Signal, iMessage, Teams, CLI), sets up encryption, and sends a test message — all in under 5 minutes. A web-based version is also available at `/onboard` on the dashboard.

See [docs/CHANNELS.md](familiar/docs/CHANNELS.md) for per-channel setup instructions.

To run the web wizard from another device on your LAN (e.g. setting up a Raspberry Pi from your laptop):

```bash
FAMILIAR_ONBOARD_LAN=1 python -m familiar --dashboard
# Then open http://<pi-ip>:5000/onboard from your laptop
```

---

## What Is Familiar?

A self-hosted AI agent that runs on your machine — from a Raspberry Pi to a workstation. Talk to it through CLI, Telegram, Discord, Matrix, Teams, or the web dashboard. It remembers context, executes tools, manages your calendar, reads your email, controls GPIO pins, and browses the web.

Everything is encrypted locally. Your conversations never leave your hardware unless you choose a cloud LLM provider.

### Features

- **Multi-provider LLM** — Claude, GPT, or local models via Ollama (llama3.2, deepseek-r1, qwen2.5, mistral, gemma3, phi3)
- **50+ skills** — email, calendar, browser, knowledge base, tasks, GPIO, voice, documents, Nextcloud, Gitea, Jellyfin, and more
- **Signal-grade encryption** — Double Ratchet secure transport, sessions and memory encrypted at rest
- **Multi-channel** — CLI, Telegram, Discord, Matrix, Teams, web dashboard, Signal, iMessage, WhatsApp, SMS
- **Raspberry Pi optimized** — runs on 4GB Pi with local Ollama models
- **Multi-device mesh** — connect multiple Familiar instances with encrypted peer-to-peer networking
- **HIPAA-ready** — compliance mode with audit logging and PHI detection
- **Task hints & eval metrics** — context-aware task suggestions, CI evaluation with cost tracking
- **Self-hosted email server** — built-in SMTP/IMAP server for fully self-hosted email

---

## Advanced Installation

For running as a system daemon, Pi optimization, or full dependency install:

```bash
# Full install with all extras
pip install familiar-agent[full]

# Pi-specific with Ollama optimization
./familiar/scripts/install-pi.sh --with-ollama

# Nonprofit preset (email, calendar, tasks)
./familiar/scripts/install-pi.sh --nonprofit
```

See [docs/INSTALL.md](familiar/docs/INSTALL.md) for detailed options.

---

## Configuration

Copy and edit the sample config:

```bash
cp config.sample.yaml ~/.familiar/config.yaml
```

Key settings:
```yaml
llm:
  default_provider: anthropic     # or openai, ollama
  anthropic_model: claude-sonnet-4-6
  ollama_model: llama3.2

agent:
  name: Familiar
  memory_enabled: true
  skills_enabled: true

security:
  encrypt_sessions: true
  encrypt_memory: true
```

---

## Project Structure

```
familiar/
├── pyproject.toml           # Package config (pip install -e .)
├── familiar/
│   ├── run.sh               # Quick start script
│   ├── __main__.py          # CLI entry point
│   ├── core/                # Agent, providers, memory, mesh, secure transport
│   ├── channels/            # CLI, Telegram, Discord, Matrix, Teams, etc.
│   ├── skills/              # 50+ built-in skills
│   ├── dashboard/           # Web dashboard
│   ├── admin/               # Admin panel
│   ├── onboard/             # Google Workspace setup wizard
│   ├── docs/                # Documentation
│   └── scripts/             # Install scripts + dev tools
```

---

## License

MIT — Copyright (c) 2026 George Scott Foley

See [LICENSE](LICENSE) for full text.
