Scan a repo, let AI write the README, review it.

# ai-inbox-agent

An AI agent that triages an inbox, summarises each email, drafts replies from your past answers and waits for your approval before sending.

## Features

- Email triage pipeline (`inbox_agent/pipeline.py`) that fetches mail and summarises each message.
- Reply drafting via configurable LLM providers (Anthropic, OpenAI, Google).
- Human-in-the-loop approval before any reply is sent.
- Digest generation for high-priority open items, awaiting replies, and follow-ups due.
- Task extraction with optional webhook dispatch and Google Sheets export.
- Web UI (FastAPI + Jinja2 + HTMX) with views for inbox, email, sent, digest, follow-ups, stats, tasks and settings.
- CLI with `serve`, `triage`, `run`, `demo-reset` and `digest` subcommands.
- Demo mode with a seeded mailbox (`inbox_agent/demo/emails.json`).
- n8n integration workflow (`integrations/n8n/inbox-agent-tasks.json`).
- Docker and Docker Compose deployment, including a Traefik compose variant.

## Requirements

- Python 3.12 (>=3.12,<3.13)
- [uv](https://github.com/astral-sh/uv) for dependency management (lockfile: `uv.lock`)
- An API key for at least one supported LLM provider (or run in demo mode)

## Getting started

1. Copy `.env.example` to `.env` and fill in the values you need.
2. Install dependencies:

```
uv sync
```

3. Run the pipeline once or start the web UI:

```
uv run inbox-agent triage
uv run inbox-agent serve
```

## Configuration

Environment variables (see `.env.example`):

| Variable | Purpose |
| --- | --- |
| `DEMO_MODE` | Enables demo mode with the seeded mailbox. |
| `DEMO_RESET_MINUTES` | Interval for resetting demo data. |
| `AI_PROVIDER` | LLM provider selection (`auto` by default). |
| `AI_MODEL` | Model name override. |
| `ANTHROPIC_API_KEY` | Anthropic API key. |
| `OPENAI_API_KEY` | OpenAI API key. |
| `GEMINI_API_KEY` | Google Gemini API key. |
| `DEEPSEEK_API_KEY` | DeepSeek API key. |
| `GMAIL_CREDENTIALS_PATH` | Path to Gmail OAuth credentials file. |
| `GMAIL_TOKEN_PATH` | Path to stored Gmail OAuth token. |
| `MAX_EMAILS_PER_RUN` | Upper bound on emails processed per run. |
| `POLL_INTERVAL_SECONDS` | Polling interval for the `run` subcommand. |
| `GOOGLE_SHEETS_ID` | Target Google Sheets document for task export. |
| `TASK_WEBHOOK_URL` | Webhook endpoint for task dispatch. |
| `TASK_WEBHOOK_SECRET` | Shared secret used to sign webhook calls. |
| `WEB_PASSWORD` | Password protecting the web UI. |
| `ROOT_PATH` | Root path prefix when serving behind a proxy. |
| `OWNER_NAME` | Name used in generated signatures. |
| `OWNER_SIGNATURE` | Signature block appended to drafts. |
| `DATABASE_PATH` | SQLite database location. |
| `MINUTES_SAVED_TRIAGE` | Estimated minutes saved per triaged email. |
| `MINUTES_SAVED_REPLY` | Estimated minutes saved per drafted reply. |

## Commands

| Command | Description |
| --- | --- |
| `uv run inbox-agent serve [--host HOST] [--port PORT]` | Run the web UI (defaults `127.0.0.1:8000`). |
| `uv run inbox-agent triage` | Fetch and triage new mail once. |
| `uv run inbox-agent run` | Fetch and triage on a loop at `POLL_INTERVAL_SECONDS`. |
| `uv run inbox-agent digest` | Print today's digest. |
| `uv run inbox-agent demo-reset` | Wipe the database and reseed the demo mailbox. |

## Project structure

```
inbox_agent/        # agents, pipeline, LLM client, mailbox, retrieval, store, web UI
inbox_agent/demo/   # seeded demo data (emails.json, recordings.json, seed.py)
inbox_agent/web/    # FastAPI app and Jinja2 templates/static assets
deploy/             # compose.traefik.yaml
integrations/n8n/   # n8n workflow definition
docs/               # ARCHITECTURE.md and screenshots
tests/              # pytest suite
```

## Testing

Run the test suite with pytest:

```
uv run pytest
```

Tests live in `tests/` (`test_pipeline.py`, `test_web.py`, `test_root_path.py`). `httpx` is a dev dependency used for web tests.

## Docker

Build and run with compose:

```
docker compose up --build
```

The image exposes port `8000` and runs `inbox-agent serve --host 0.0.0.0 --port 8000`. A Traefik-fronted variant is provided in `deploy/compose.traefik.yaml`.

## License

MIT License. See `LICENSE`.