Communication Agent (MVP1)

A Production-Grade, Stateful Triage and Response System

The Communication Agent (MVP1) is the fully engineered successor to the initial SMS (Sales Mail Support) concept. The original vision was to automate the triage and response process for customer emails in a solar panel enterprise. It is a backend-first MVP that connects securely to Gmail, uses a swappable LLM adapter for triage and drafting, and manages the entire support lifecycle via a robust state machine and API.
The architecture emphasizes security, auditability, and operational maturity, leveraging modern asynchronous Python frameworks to handle mission-critical communication workflows.

The Architectural Problem

Moving from a conceptual agent flow to a production system requires solving non-trivial engineering problems: secure authentication (OAuth), reliable state persistence (tickets), and providing a usable interface (reporting boards).

The Solution's Core Value

Delivered a complete, stateful agent that provides full lifecycle management for customer emails, from secure ingestion to state-based routing and final human-approved response, all while leveraging FastAPI and SQLAlchemy for stability.

Technical Architecture and Production Features

The system is built on a high-integrity technical stack designed for scalability and operational transparency.

Agent Core & Reasoning

Pillars of Intelligence

The abstraction layer for pluggable LLM services.

  • Pluggable LLM Adapter: Uses an abstract adapter model, defaulting to the Architect LLM service, allowing the core business logic to remain independent of the specific model endpoint (OpenAI-chat-like JSON structure).
  • Draft & Triage: The model provides initial triage, suggested replies, and a structured plan via the /tickets/{id}/draft endpoint.
  • Activity Logging: Tracks every action (draft, assign, send) using structlog for auditability.

System Integrity & State Management

FastAPI + SQLAlchemy Core

Ensuring data persistence and state consistency.

  • Stateful Tickets: Implements a clear ticket status flow: NEW $\rightarrow$ NEEDS_ACTION $\rightarrow$ WAITING_OTHERS $\rightarrow$ DONE. This state management is essential for auditable workflows.
  • Asynchronous ORM: Uses SQLAlchemy (async) and FastAPI for high-performance, non-blocking I/O across database operations (SQLite/Postgres).
  • Security: Configured to handle Gmail OAuth2 client credentials and tokens securely via environment variables (.env), explicitly ignoring secrets from version control.

Operational UX & MLOps

Reporting and Control

Tools for operators and MLOps monitoring.

  • Server-Rendered Boards: Provides four key operational boards (/boards/*) using Jinja2 for real-time ticket status viewing (e.g., Needs My Action, Waiting on Others).
  • Full API Control: The entire workflow—from POST /sync/run (to pull emails) to POST /tickets/{id}/approve_send—is exposed via the FastAPI REST API, making it fully scriptable and ready for MLOps monitoring.
  • Optional Background Sync: Features a configurable background polling system for continuous email ingestion.
Communication Agent (MVP1): Central Hub Architecture

Repository Layout: An Architecture of Clarity

The repository layout itself demonstrates a strong commitment to systems architecture, ensuring separation of concerns:
app/
api/            # FastAPI app + routers (The exposed surface)
adapters/       # External dependencies: Gmail, LLM (The pluggable connectors)
services/       # Triage, drafting, sync (The business logic)
models/         # SQLAlchemy entities + Pydantic schemas (The data contracts)
core/           # Config, db, logging (The system foundation)
ui/templates/   # Jinja pages (The simple UX layer)
This clear organization is fundamental to building scalable and auditable AI systems.
Discuss Production AI Systems
View on Github
Back to Featured Projects