Metadata-Version: 2.3
Name: mailpilot-crm
Version: 0.18.0
Summary: Agent-operated CRM with Gmail as the comms layer
Author: Konstantin Borovik
Author-email: Konstantin Borovik <github@lab5.ca>
Requires-Dist: click>=8.1.0,<8.4.0
Requires-Dist: google-api-python-client>=2.170.0,<3.0.0
Requires-Dist: google-auth>=2.40.0,<3.0.0
Requires-Dist: google-cloud-pubsub>=2.29.0,<3.0.0
Requires-Dist: httpx>=0.28.0,<1.0.0
Requires-Dist: logfire>=4.0.0,<5.0.0
Requires-Dist: mistune>=3.1.0,<4.0.0
Requires-Dist: psycopg[binary]>=3.2.0,<4.0.0
Requires-Dist: pydantic-ai-slim[anthropic]>=2.2.0,<3.0.0
Requires-Dist: pydantic-settings>=2.7.0,<3.0.0
Requires-Python: >=3.14
Project-URL: Homepage, https://lab5.ca
Project-URL: Repository, https://github.com/kborovik/mailpilot
Description-Content-Type: text/markdown

# MailPilot

Agent-operated CRM with Gmail as the communication layer.

**[See it in action](https://lab5.ca/mailpilot//)**

## Overview

MailPilot manages contacts, companies, and communication workflows through Gmail API. It is designed to be operated by AI agents -- Claude Code as the strategic orchestrator and an internal Pydantic AI agent for real-time reactive work.

### Two-Layer Intelligence

1. **Claude Code** -- strategic orchestrator. Creates workflows, assigns contacts, reviews outcomes, generates reports. Operates the system via CLI.
2. **Internal Pydantic AI agent** -- subordinate tactical executor. Handles inbound email classification, auto-replies, and follow-up scheduling within workflows.

### Key Capabilities

- **Contact and company management** -- track relationships, tag for segmentation, annotate with notes
- **Activity timeline** -- unified chronological log of all interactions per contact
- **Email workflows** -- inbound auto-reply and outbound campaigns via Gmail API with service account delegation
- **Task scheduling** -- deferred agent work with scheduled execution for long-running processes
- **Reporting** -- Claude Code queries the database and generates activity summaries, relationship health, and campaign effectiveness reports

## Architecture

- **CLI-first** -- JSON output, meaningful exit codes, actionable errors. Designed for LLM agent consumption.
- **PostgreSQL** -- contacts, companies, workflows, emails, activities, tags, notes. Raw SQL via psycopg, no ORM.
- **Gmail API** -- service account domain-wide delegation. Pub/Sub for real-time notifications. History API for incremental sync.
- **Pydantic AI** -- stateless agent invocations with tool access. Per-contact advisory locks for concurrency.
- **Observability** -- Pydantic Logfire (OpenTelemetry-based) for tracing and logging.

## Tech Stack

- Python 3.14
- PostgreSQL 18
- Gmail API (`google-api-python-client`)
- Pydantic AI (agent framework)
- Pydantic Logfire (observability)
- Click (CLI)
- basedpyright (strict type checking)
- ruff (formatting and linting)
- pytest (testing)

## Quick Start

```bash
# Install dependencies
uv sync

# Configure
mailpilot config set database_url postgresql://localhost/mailpilot
mailpilot config set google_application_credentials /path/to/service-account.json
mailpilot config set anthropic_api_key sk-ant-...

# Create an account
mailpilot account create --email user@example.com --display-name "User Name"

# Sync emails
mailpilot account sync

# Start the sync loop
mailpilot run
```

## Development

```bash
make check    # lint + tests
make lint     # ruff format + ruff check + basedpyright
make py-test  # pytest -x
```

## Documentation

- [SPEC.md](SPEC.md) -- single source of truth (goals, constraints, invariants, tasks, bugs).
- [CLAUDE.md](CLAUDE.md) -- operator/agent guide.

## License

Private.
