mailpilot-crm 0.18.0__tar.gz

mailpilot_crm-0.18.0/PKG-INFO

@@ -0,0 +1,101 @@
+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.

mailpilot_crm-0.18.0/README.md

@@ -0,0 +1,80 @@
+# 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.

mailpilot_crm-0.18.0/pyproject.toml

@@ -0,0 +1,130 @@
+[project]
+# PyPI distribution name; "mailpilot" is owned by an unrelated PyPI project.
+# The import package and CLI command stay "mailpilot" (module-name below).
+name = "mailpilot-crm"
+version = "0.18.0"
+description = "Agent-operated CRM with Gmail as the comms layer"
+readme = "README.md"
+authors = [
+    { name = "Konstantin Borovik", email = "github@lab5.ca" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "click>=8.1.0,<8.4.0",
+    "google-api-python-client>=2.170.0,<3.0.0",
+    "google-auth>=2.40.0,<3.0.0",
+    "google-cloud-pubsub>=2.29.0,<3.0.0",
+    "httpx>=0.28.0,<1.0.0",
+    "logfire>=4.0.0,<5.0.0",
+    "mistune>=3.1.0,<4.0.0",
+    "psycopg[binary]>=3.2.0,<4.0.0",
+    "pydantic-ai-slim[anthropic]>=2.2.0,<3.0.0",
+    "pydantic-settings>=2.7.0,<3.0.0",
+]
+
+[project.urls]
+Homepage = "https://lab5.ca"
+Repository = "https://github.com/kborovik/mailpilot"
+
+[project.scripts]
+mailpilot = "mailpilot.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mailpilot"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.37.0",
+    "pytest>=8.4.0,<9.0.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.13.0",
+    "uv>=0.8.17",
+]
+
+[tool.basedpyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.14"
+include = ["src/mailpilot/", "tests/"]
+reportMissingTypeStubs = false
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownParameterType = false
+reportUnknownLambdaType = false
+reportUnusedFunction = "warning"
+
+[tool.ruff]
+target-version = "py314"
+src = ["src", "tests"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+select = [
+    "B",     # flake8-bugbear
+    "C4",    # flake8-comprehensions
+    "C90",   # mccabe
+    "COM",   # flake8-commas
+    "D",     # pydocstyle
+    "E",     # pycodestyle
+    "F",     # pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "PL",    # Pylint
+    "PT",    # flake8-pytest-style
+    "RUF",   # Ruff-specific rules
+    "SIM",   # flake8-simplify
+    "TID",   # flake8-tidy-imports
+    "UP",    # pyupgrade
+    "W",     # pycodestyle warnings
+]
+ignore = [
+    "PLR2004",  # magic values in comparisons
+    "PLC0415",  # import not at top-level (lazy imports)
+    "D100",     # Missing docstring in public module
+    "D104",     # Missing docstring in public package
+    "D105",     # Missing docstring in magic method
+    "D107",     # Missing docstring in __init__
+    "COM812",   # trailing commas
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["mailpilot"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/mailpilot/cli.py" = [
+    "PLR0913", # Click commands have many parameters by design
+]
+"src/mailpilot/database.py" = [
+    "PLR0913", # Create functions map to table columns
+]
+"src/mailpilot/gmail.py" = [
+    "PLR0913", # Gmail API functions have many parameters
+]
+"tests/**/*.py" = [
+    "D",       # No docstrings required in tests
+    "PLR2004", # Magic values OK in tests
+    "PLR0913", # Too many arguments OK in tests
+    "E501",    # Line too long
+]
+".claude/**/*.py" = [
+    "D",       # No docstrings required in operator skill scripts
+    "E501",    # Line too long
+    "PLR2004", # Magic values OK in scripts
+]
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+    "ignore::logfire._internal.config.LogfireNotConfiguredWarning",
+]

mailpilot_crm-0.18.0/src/mailpilot/SKILL.md

@@ -0,0 +1,265 @@
+# mailpilot CLI skill
+
+External LLM-agent reference for the `mailpilot` CLI. Audience: agents that
+have `mailpilot` installed as a dependency and need to drive it from a shell.
+Scope: command grammar, JSON envelope shape, exit codes, common task recipes,
+settings. Out of scope: database schema, internal agent / template wiring.
+
+## Grammar
+
+```
+mailpilot <noun> <verb> [args]
+mailpilot run | status | config get|set
+mailpilot --version | --help | --completion <shell> | --skill | --debug
+```
+
+Nouns: `account`, `company`, `contact`, `workflow`, `enrollment`, `task`,
+`email`, `activity`, `tag`, `note`, `template`, `db`.
+
+Verbs: `list`, `search`, `view`, `create`, `update`, `disable`, `enable`,
+`add`, `remove`, `reply`, `send`, `start`, `stop`, `cancel`, `retry`, `run`,
+`sync`, `export`, `import`, `init`, `migrate`, `check`. Not every verb applies
+to every noun -- use
+`mailpilot <noun> --help` to enumerate. `config` exposes the `get` and `set`
+subverbs for reading and writing persistent configuration.
+
+## JSON envelope
+
+Every noun-verb command writes a single JSON document to stdout. Operator
+diagnostics go to stderr and never to stdout.
+
+- `list`, `search`, `sync`, `export`, `import`:
+  `{"<plural>": [...], "record_count": <int>, "ok": true}`
+- `view`, `create`, `update`, `disable`, `enable`, `add`, `remove`,
+  `reply`, `send`, `start`, `stop`, `cancel`, `retry`, `init`, `migrate`,
+  `check`:
+  `{"<singular>": {...}, "record_count": 1, "ok": true}`
+- error: `{"error": "<code>", "message": "<text>", "ok": false}`
+
+Every `ok: true` envelope carries a top-level integer `record_count`: the
+array length for array payloads, `1` for single-object payloads. Error
+envelopes omit it.
+
+Plural keys mirror the noun (`accounts`, `companies`, `contacts`,
+`workflows`, `enrollments`, `tasks`, `emails`, `activities`, `tags`, `notes`,
+`templates`). Singular keys are the noun itself (`account`, `company`, ...).
+
+Soft-disable verbs such as `contact disable`, `enrollment disable`, and
+`tag disable` return the full updated entity under the singular envelope
+since the row is retained.
+
+## Exit codes
+
+- `0` -- success. `ok: true` payload on stdout.
+- `1` -- failure. `ok: false` envelope on stderr; stdout stays empty.
+
+The top-level `--skill`, `--version`, `--help`, `--completion` flags emit
+plain text (not JSON) and exit `0`.
+
+## Settings
+
+Persistent config lives in `~/.mailpilot/config.json`. Read and write with:
+
+```
+mailpilot config get [KEY]
+mailpilot config set KEY VALUE
+```
+
+`config get` with no key returns `{"config": {...}, "ok": true}`. With a key
+it returns `{"key": ..., "value": ..., "ok": true}` or an `invalid_key`
+error envelope.
+
+Every key may also be overridden via an environment variable of the form
+`MAILPILOT_<UPPERCASE_KEY>` (for example, `MAILPILOT_DATABASE_URL`,
+`MAILPILOT_ANTHROPIC_API_KEY`, `MAILPILOT_RUN_INTERVAL`). Priority is
+constructor kwargs (tests only), then `MAILPILOT_*` env vars, then the
+config file, then field defaults.
+
+Keys:
+
+- `database_url` -- PostgreSQL DSN. Default `postgresql://localhost/mailpilot`.
+- `anthropic_api_key` -- required for agent invocations.
+- `anthropic_model` -- e.g. `claude-sonnet-4-6`.
+- `anthropic_base_url` -- Anthropic-compatible API endpoint. Default
+  `https://api.anthropic.com`; point it at e.g. `https://api.novita.ai/anthropic`
+  to route the same call to another vendor.
+- `anthropic_thinking` -- workflow-agent extended thinking. Default `adaptive`
+  (on); set to empty to turn it off. Classifier never reads this key.
+- `anthropic_effort` -- workflow-agent reasoning effort. Default `high`; one of
+  `low`, `medium`, `high`, `xhigh`, `max`, or empty to send no effort key.
+  `xhigh` needs Opus 4.7 or newer. Classifier never reads this key.
+- `anthropic_max_tokens` -- workflow-agent output-token budget. Default `16384`;
+  always sent so default-active thinking cannot exhaust the provider-default
+  budget before any reply text. Classifier never reads this key.
+- `google_application_credentials` -- path to service-account JSON. Optional
+  when running on a platform that exposes Application Default Credentials (GCE
+  attached service account, GKE Workload Identity, Cloud Run identity); leave
+  unset to use ADC. Set explicitly otherwise. Domain-wide delegation works in
+  both modes; ADC mode signs JWTs via the IAM Credentials API and requires the
+  active service account to hold `roles/iam.serviceAccountTokenCreator` on
+  itself.
+- `google_pubsub_topic` -- default `mailpilot-topic-dev`.
+- `google_pubsub_subscription` -- default `mailpilot-sub-dev`.
+- `logfire_token` -- optional. Enables cloud telemetry.
+- `logfire_environment` -- `development` or `production`.
+- `run_interval` -- fallback poll interval for the sync loop, in seconds.
+  Default `60`.
+- `max_concurrent_tasks` -- bound on the worker pool that drains the task
+  queue. Default `10`.
+
+## Recipes
+
+### Inspect state
+
+```
+mailpilot status
+mailpilot account list
+mailpilot workflow list --account-email <ACCOUNT_REF>
+mailpilot enrollment list --workflow-id <ID>
+mailpilot task list --status pending
+mailpilot email list --account-email <ACCOUNT_REF> --limit 50
+```
+
+### Provision and migrate the schema
+
+```
+mailpilot db init
+mailpilot db migrate
+mailpilot db check
+```
+
+`db init` provisions an empty database from the bundled schema; it refuses a
+populated database (no destructive re-init) and is an idempotent no-op once
+current. `db migrate` applies pending forward migrations, one transaction each.
+`db check` reports the schema verdict and exits non-zero on `pending`/`drift`,
+so it doubles as a deploy gate.
+
+### Onboard an account
+
+```
+mailpilot account create --email outbound@example.com --display-name "Outbound"
+mailpilot account sync --account-email <ACCOUNT_REF>
+```
+
+`account sync` performs a one-shot Gmail sync; omit `--account-email` to sync
+every account. The long-running `mailpilot run` loop handles ongoing
+Pub/Sub deltas.
+
+### Create a contact and company
+
+```
+mailpilot company create --domain example.com --name "Example Co"
+mailpilot contact create --email lead@example.com \
+    --first-name "Ada" --last-name "Lovelace" --company-domain <COMPANY_REF>
+```
+
+Soft-disable a contact (preserves audit history) with:
+
+```
+mailpilot contact disable <CONTACT_REF> --reason "left company"
+```
+
+### Define a workflow declaratively
+
+Workflow definitions are one TOML file per workflow. Export/import is TOML-only
+and idempotent; round-trip is keyed on the globally unique `name`.
+
+```
+mailpilot workflow export --account-email <ACCOUNT_REF> --out-dir workflows/
+mailpilot workflow import --account-email <ACCOUNT_REF> --file workflows/
+```
+
+`workflow export` writes one `*.toml` per workflow into `--out-dir` and prints a
+JSON status envelope of the paths written (TOML never goes to stdout). `workflow
+import` takes a single `.toml` file or a directory of them (`*.toml` glob). Each
+file carries `name`, `template`, `goal`, `instructions`, `theme`, with
+`instructions` as a TOML multi-line literal string. Available templates:
+
+```
+mailpilot template list
+mailpilot template view <NAME>
+```
+
+`template` is immutable on update -- changing it requires deleting and
+recreating the workflow. Import reports a per-row `template_immutable` error
+when the value differs and continues with the rest of the batch.
+
+Every import envelope carries top-level integer `applied` and `rejected`
+counts beside the `workflows` rows. An import that applies zero rows (every
+row rejected, or no `*.toml` found) fails loudly: `import_failed` error
+envelope on stderr with the per-row rows inlined, exit 1. A partial import
+stays `ok: true` (exit 0) with per-row errors inline, so check `rejected`
+before trusting a batch.
+
+### Enroll a contact
+
+`enrollment add` constructs the binding from `--workflow-id` + `--contact-email`
+and returns the freshly-minted scalar `id`; every other verb takes that id
+as a single positional argument.
+
+```
+mailpilot enrollment add --workflow-id <WID> --contact-email <CONTACT_REF>
+mailpilot enrollment run <ENROLLMENT_ID>                            # manual kick
+mailpilot enrollment view <ENROLLMENT_ID>
+mailpilot enrollment disable <ENROLLMENT_ID> --reason "left company"
+mailpilot enrollment enable <ENROLLMENT_ID>
+```
+
+Pass `--scheduled-at <ISO>` on `enrollment add` against an outbound workflow
+to queue a first-touch send for that time; the run loop dispatches it when
+due.
+
+Enrollment status is `active` or `disabled`. `disabled` is the operator halt
+(set via `enrollment disable`, reversed via `enrollment enable`); the agent
+never re-enables an enrollment. Terminal outcomes (`completed`, `failed`) are
+recorded as activity-log entries by the agent, not as enrollment status
+changes.
+
+### Send and reply by hand
+
+```
+mailpilot email send --account-email <ADDR> --to lead@example.com \
+    --subject "Hello" --body "..."
+mailpilot email reply --account-email <ADDR> --email-id <EMAIL_ID> --body "..."
+```
+
+### Tag, note, and audit
+
+```
+mailpilot tag create vip
+mailpilot tag add --tag vip --contact-email <ADDR>
+mailpilot tag remove --tag vip --contact-email <ADDR>
+mailpilot tag disable vip --reason "<text>"
+mailpilot note add --contact-email <ADDR> --body "Met at conf 2026."
+mailpilot activity list --contact-email <ADDR>
+```
+
+Tags are a controlled vocabulary: `tag create` defines a name, `tag add`
+links it to a contact or company, `tag remove` unlinks, and `tag disable`
+retires the name. A note attaches to exactly one of `contact_id` or
+`company_id`. Activities may attach to either, both, or neither.
+
+### Task queue
+
+```
+mailpilot task list --status pending
+mailpilot task view <TID>
+mailpilot task cancel <TID>
+mailpilot task retry <TID>     # only on failed or cancelled rows
+```
+
+### Run the sync loop
+
+```
+mailpilot run
+```
+
+Foreground process. Drives Gmail Pub/Sub delivery, runs queued tasks,
+invokes the agent on routed inbound mail. Stderr emits one
+`HH:MM:SS event=<name> ...` line per operator event. `Ctrl-C` stops cleanly.
+
+## Discovery
+
+Every command supports `--help`. The top-level `--help` lists noun groups;
+`mailpilot <noun> --help` lists verbs; `mailpilot <noun> <verb> --help`
+lists flags. When uncertain, prefer `--help` over guessing.

mailpilot_crm-0.18.0/src/mailpilot/__init__.py

@@ -0,0 +1 @@
+"""MailPilot -- CRM application for cold email outreach via Gmail."""

mailpilot_crm-0.18.0/src/mailpilot/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m mailpilot`."""
+
+from mailpilot.cli import main
+
+main()