Email Receiver Agent

An in-progress Personal Action Agent / Inbox Operations Agent. The project turns communication evidence into durable, automatically maintained Actions: what needs the user, what is waiting on another party, and how an ongoing process evolves over time.

Why this exists

Important work is often buried in email threads. A useful assistant must preserve evidence, understand the surrounding Conversation, and maintain an operational state over time instead of producing a one-off label or summary. This repository explores that boundary with provider-neutral models, explicit persistence, deterministic policy, and offline evaluation.

Current capabilities

• Gmail ingestion, parsing, normalization, and connector-level authentication boundaries.
• Provider-neutral NormalizedEmail evidence with inbound/outbound direction, RFC reply metadata, and internal Conversation grouping.
• Selective full-thread hydration and persistent Conversation tracking.
• SQLite migrations and schema evolution for durable inbox, Conversation, Action, and ActionEvent state.
• Durable Action projections with append-only ActionEvent provenance.
• Deterministic Action transition policy between semantic interpretation and database mutation.
• Structured LLM adapters for OpenAI, Kimi, and Gemini with strict response validation and safe failure behavior.
• A Personal Agent / WeChat interaction surface using a mockable provider boundary; live transport remains explicitly opt-in.
• Offline regression, synthetic evaluation, local dogfood export, deterministic alignment, and private-data-safe evaluation tooling.

Architecture

Email Provider
    ↓
Provider-Neutral Normalization
    ↓
Conversation Evidence
    ↓
Selective Conversation Hydration
    ↓
Structured LLM Semantic Interpretation
    ↓
Deterministic Policy
    ↓
Durable Action + ActionEvent State
    ↓
Personal Agent / Action Views

The core safety boundary is intentional:

LLM recommendation
≠
authorized database mutation

Model output is advisory. Deterministic policy checks scope, evidence, lifecycle rules, hydration, terminal safeguards, and user authority before the repository can write an Action or ActionEvent.

Example Action lifecycle

Recruiter asks for availability
→ needs_user_action

User replies
→ waiting_for_other_party

Recruiter proposes a time
→ needs_user_action

Process resolves
→ completed

Action is the mutable current projection; ActionEvent preserves append-only mutation provenance. The current lifecycle vocabulary is needs_user_action, waiting_for_other_party, completed, and cancelled.

Engineering highlights

The repository has been built incrementally through tested H4 contracts: normalized evidence and Conversations, hydration and tracking, SQLite migration/repository layers, structured provider adapters, a pure transition-policy boundary, a runtime lifecycle service, Personal Action projections, and reusable offline evaluation infrastructure. The evaluation tooling is designed to support realistic methodology without committing private Gmail bodies or private dogfood snapshots.

Current status / In Progress

The committed repository is a substantial working research/prototype system, not a finished product. H4/D3 Action-semantics work is actively evolving and is intentionally marked In Progress. The next semantic iteration is exploring structural Conversation activation, 0..N process discovery, separate Action identity matching, ownership-based lifecycle derivation, and stricter provider contracts. Those contracts are not presented here as finalized product behavior.

Running locally

Create a virtual environment, install requirements.txt, and copy .env.example to a local .env only when connector or model credentials are needed. The default sample path is offline and safe:

python -m pip install -r requirements.txt
python backend/app/run_mvp.py --connector sample --delivery console

Gmail, model providers, webhook delivery, and live WeChat transport require explicit local configuration and are not invoked by the offline tests.

Tests

Run the full offline suite from the repository root:

python -m unittest discover -s backend/tests -q

The test suite uses synthetic fixtures, fake provider clients, temporary SQLite databases, and deterministic policy checks. It does not require Gmail access or live model calls.

Roadmap

• Complete and validate the H4/D3 semantic pipeline behind an explicit rollout boundary.
• Improve long-running replay, evaluation, and decision-provenance diagnostics.
• Continue testing provider-neutral Conversation and Action behavior against synthetic and carefully controlled local fixtures.
• Explore additional communication sources only after their privacy and evidence contracts are clear.

This project does not currently claim production-ready RAG/vector retrieval, Canvas/Slack/Calendar ingestion, autonomous email sending, production-scale multi-user deployment, finalized D3 semantic quality, or strong product-market validation.

Privacy / safety note

Never commit API keys, OAuth tokens, credentials, local .env files, personal WeChat/iLink authentication state, canonical SQLite data, real Gmail messages, or private evaluation snapshots. Local private dogfood output belongs outside tracked source paths. The repository includes synthetic examples and public-safe engineering documentation only; inspect git diff and staged files before publishing changes.

H4 milestone closeout record: see docs/h4_closeout_record.md.