How bobbyflow/ron-inbox-intelligence works
1. Project shape
This is a single Python CLI application centered on gmail_intel.py, not a service or web app. The rest of the repo is supporting material: safety documentation, example output, tests, and CI.
2. Primary runtime
The tool runs locally on Python 3.11+ and is intended to be executed from the command line in either demo, dry-run calibration, or live monitor mode. The command-line entry point is the main orchestration layer for the whole pipeline.
3. External integrations
The system depends on Google Workspace APIs for Gmail and optionally Calendar. The README notes a required local adapter, google_api.build_service, which supplies authenticated service clients. That adapter is an important boundary: the repo assumes Gmail/Calendar connectivity but does not vendor the auth stack.
4. Message ingestion boundary
The first subsystem is Gmail retrieval. It supports:
- targeted candidate queries,
- broader calibration sweeps,
- custom Gmail search strings.
This is the source of all message data flowing into the decision pipeline.
5. Normalization layer
Retrieved messages are normalized into a consistent internal representation containing:
- headers,
- body text,
- snippets,
- attachments,
- ICS payloads.
This layer is important because later classification is driven by evidence aggregation across all of these fields, not just the subject line.
6. Decision engine
The core logic is a deterministic rule engine that classifies each message into one of four actions:
- ignore
- notify_user
- needs_review
- auto_create_calendar
The README emphasizes conservative behavior: only strong evidence allows automatic calendar writes. This makes the decision engine the main architectural boundary between “parsing” and “action.”
7. Parser and safety subsystems
The repo uses provider-aware parsers for recurring event sources plus a conservative generic parser. Safety checks include:
- confirmation/approval language,
- parseable future date/time,
- blocking waitlists/cancellations/tentative items,
- inspecting ICS attachments,
- preventing action on urgent-but-non-calendar categories such as financial or medical notices.
These checks are not cosmetic; they directly gate whether a message becomes actionable.
8. Calendar action path
Only high-confidence events can reach the live Google Calendar write path. Before creation, the system performs:
- idempotency key checks,
- duplicate event scans in the surrounding time window.
For parseable-but-not-approved events, it can create clearly labeled placeholders such as [PENDING APPROVAL], marked tentative/free. This is a distinct branch from full auto-creation.
9. Persistence and audit trail
The application writes a local SQLite audit trail for messages, decisions, runs, and calendar actions. This is the main durability layer and supports traceability, reproducibility, and post-run review. The repo also emits compact JSON reports for downstream automation or dashboards.
10. Demo and test harness
The repo includes a zero-credential synthetic demo (--demo) and an example output file under examples/. Tests focus on demo classification behavior, which suggests the public test surface is centered on the deterministic rule engine rather than external API calls.
11. Documentation and safety model
docs/safety-model.md is a key design document: it defines the conservative decision rules and the kinds of messages that must never auto-act. reports/README.md likely documents report artifacts and usage, reinforcing that outputs are meant to be inspected and archived.
12. CI and packaging posture
The .github/workflows/ci.yml workflow and pyproject.toml/requirements.txt indicate standard Python package hygiene: lint/test/compile checks rather than deployment orchestration. The repo is organized as an automation prototype with a strong emphasis on safety, auditability, and local-first operation.
Main entry points: gmail_intel.py gmail_intel.py · safety-model.md Safety gates · pyproject.toml Packaging · test_demo_classification.py tests/test_demo_classification.py
Components 20
Runtime
Local CLI execution and core processing pipeline
- gmail_intel.py · Main command-line entry point and pipeline coordinator
gmail_intel.py - Demo mode · Zero-credential demo path used for local simulation
gmail_intel.py - Query ingest · Candidate queries, calibration sweeps, and custom Gmail search strings
gmail_intel.py - Normalize mail · Normalizes headers, body, snippets, attachments, and ICS payloads
gmail_intel.py - Rule engine · Maps each message to ignore, notify_user, needs_review, or auto_create_calendar
gmail_intel.py
Integrations
External Google Workspace boundaries and write path
- Approval branch · Creates labeled tentative placeholders when an event is parseable but not approved
gmail_intel.py - Calendar write · Live Google Calendar creation path for high-confidence events
gmail_intel.py - Dedupe checks · Uses idempotency keys and duplicate scans in the surrounding time window
gmail_intel.py - Service adapter · Local authenticated build_service boundary for Gmail and optional Calendar clients
gmail_intel.py
Safety
Conservative decision rules, audits, and documentation
- Safety gates · Confirmation language, future date checks, waitlist/cancellation blocking, and non-calendar category rejection
docs/safety-model.md - Parser stack · Provider-aware recurring-event parsing plus conservative generic parsing
gmail_intel.py - ICS inspect · Examines calendar payloads embedded in message attachments
gmail_intel.py - Audit SQLite · Stores messages, decisions, runs, and calendar actions
gmail_intel.py - JSON reports · Emits machine-readable reports for downstream automation or review
gmail_intel.py - docs/safety-model.md · Defines conservative action rules and never-auto-act categories
docs/safety-model.md
Project
Packaging, tests, and supporting repo files
- examples/demo_output.json · Example output artifact for the demo and report format
examples/demo_output.json - tests/test_demo_classification.py · Validates deterministic demo classification behavior
tests/test_demo_classification.py - CI workflow · Automated lint, test, and compile checks
.github/workflows/ci.yml - Packaging · Project metadata and dependency configuration
pyproject.toml - Deps · Pinned runtime dependency list
requirements.txt
Connections 22
- gmail_intel.py → Demo mode: demo · Runs synthetic local simulation mode
- gmail_intel.py → Query ingest: ingest · Fetches Gmail messages for analysis
- Query ingest → Service adapter: auth client · Uses service adapter to obtain Gmail/Calendar clients
- Query ingest → Normalize mail: messages · Passes retrieved messages into normalization
- Normalize mail → Parser stack: parse · Feeds structured text and metadata to parsers
- Normalize mail → ICS inspect: attachments · Surfaces ICS evidence for inspection
- Parser stack → Safety gates: candidate event · Parser output is checked by safety gates
- ICS inspect → Safety gates: calendar evidence · ICS payloads are evaluated conservatively
- Safety gates → Rule engine: allow/deny · Gates whether a message can become actionable
- Rule engine → Approval branch: pending · Routes parseable but unapproved items to placeholders
- Rule engine → Calendar write: auto create · Sends only high-confidence events to Calendar writes
- Calendar write → Dedupe checks: before write · Runs idempotency and duplicate detection first
- Dedupe checks → Service adapter: calendar client · Uses authenticated Calendar service for writes
- Rule engine → Audit SQLite: audit · Stores classifications and run metadata
- Calendar write → Audit SQLite: action log · Persists calendar actions for traceability
- gmail_intel.py → JSON reports: report · Emits compact JSON summaries
- JSON reports → examples/demo_output.json: example · Example output demonstrates report shape
- gmail_intel.py → docs/safety-model.md: policy · Implements the documented safety model
- gmail_intel.py → tests/test_demo_classification.py: verified by · Demo classification behavior is tested directly
- CI workflow → tests/test_demo_classification.py: runs · CI executes the test suite
- Packaging → gmail_intel.py: packages · Defines the Python application build and metadata
- Packaging → Deps: depends on · Declares runtime dependencies