Metadata-Version: 2.4
Name: aegis-mail-companion
Version: 1.0.18
Summary: Autonomous AI Mail Companion & Tiered L1/L2 Support Bot for Outlook, Gmail, Zoho & IMAP with 5-stage multi-agent triage, Jira root-cause analysis, and installable PWA.
Author-email: Sachin Bose Pulikkathara <sachin.bose.p@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://aegis-mail-companion.vercel.app
Project-URL: Documentation & Setup Portal, https://aegis-mail-companion.vercel.app/download
Project-URL: Aegis Official Portal, https://aegis-help.nilswa.com
Project-URL: Author PyPI Profile, https://pypi.org/user/sachinbosep/
Project-URL: Author LinkedIn, https://www.linkedin.com/in/sachin-bose-p/
Keywords: aegis,aegis-ai,aegis-ai-suite,aegis-mail,aegis-mail-companion,aegiscore,ai,genai,future-of-ai,agentic-ai,autonomous-agents,ai-agents,multi-agent-systems,llm-orchestration,ai-email-assistant,email-automation,email-bot,email-agent,mail-companion,smart-inbox,inbox-zero,email-triage,auto-reply,email-responder,customer-support-ai,customer-service-bot,helpdesk-automation,it-helpdesk,service-desk,l1-support,l2-support,ticket-triage,sla-monitoring,sentiment-analysis,root-cause-analysis,outlook,microsoft-graph,office-365,gmail,gmail-api,zoho-mail,imap,smtp,jira-connector,issue-tracker,rag,knowledge-base,openai,claude,gemini,ollama,local-llm,self-hosted-ai,pwa,crm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Customer Service
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Communications :: Email :: Email Clients (MUA)
Classifier: Topic :: Communications :: Email :: Filters
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: eval-type-backport>=0.2.0; python_version < "3.10"
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: email-validator>=2.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: bcrypt>=4.1.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: markdown>=3.5.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: truststore>=0.9.0; python_version >= "3.10"
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: langchain==0.3.0
Requires-Dist: langchain-community==0.3.0
Requires-Dist: langchain-core==0.3.0
Requires-Dist: langchain-text-splitters<0.3.1,>=0.3.0; python_version < "3.10"
Requires-Dist: langchain-openai<0.2.2,>=0.2.0; python_version < "3.10"
Requires-Dist: langchain-openai<0.3.0,>=0.2.0; python_version >= "3.10"
Requires-Dist: langchain-anthropic<0.2.1,>=0.2.0; python_version < "3.10"
Requires-Dist: langchain-anthropic<0.3.0,>=0.2.0; python_version >= "3.10"
Requires-Dist: langchain-google-genai<2.0.2,>=2.0.0; python_version < "3.10"
Requires-Dist: langchain-google-genai<2.1.0,>=2.0.0; python_version >= "3.10"
Requires-Dist: langchain-groq<0.2.1,>=0.2.0; python_version < "3.10"
Requires-Dist: langchain-groq<0.3.0,>=0.2.0; python_version >= "3.10"
Requires-Dist: langchain-ollama<0.2.1,>=0.2.0; python_version < "3.10"
Requires-Dist: langchain-ollama<0.3.0,>=0.2.0; python_version >= "3.10"
Requires-Dist: pypdf>=4.0.0
Requires-Dist: openapi-spec-validator>=0.7.0
Requires-Dist: openpyxl
Requires-Dist: python-docx
Requires-Dist: python-pptx
Requires-Dist: Pillow>=10.0.0
Requires-Dist: APScheduler
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: feedparser>=6.0.10
Requires-Dist: feedparser-sgmllib==2.1.0; python_version >= "3.10"
Requires-Dist: SQLAlchemy<2.1,>=2.0
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: psycopg[binary]>=3.2.0
Requires-Dist: psycopg-pool>=3.2.0
Requires-Dist: pgvector>=0.3.0
Requires-Dist: pyotp
Requires-Dist: qrcode[pil]
Requires-Dist: radon>=6.0.1
Requires-Dist: lizard>=1.24.0
Requires-Dist: openai>=1.20.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: google-genai>=0.1.0; python_version >= "3.10"
Requires-Dist: langgraph<0.2.41,>=0.2.35; python_version < "3.10"
Requires-Dist: langgraph<0.3.0,>=0.2.0; python_version >= "3.10"
Requires-Dist: sqlglot>=25.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: psutil>=5.9.0

<div align="center">

<img src="https://raw.githubusercontent.com/sachin-bose-p/sachin-bose-p/main/assets/aegis-mail-companion/hero.png" alt="Aegis Mail Companion — Autonomous AI Mail Companion & Tiered L1/L2 Support Bot" width="100%" />

<br />
<br />

[![PyPI Version](https://img.shields.io/badge/pypi-v1.0.18-232E7A?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/aegis-mail-companion/)
[![Wheel](https://img.shields.io/badge/wheel-universal%20py3--none--any-059669?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/aegis-mail-companion/#files)
[![Download Analytics](https://img.shields.io/badge/analytics-ClickPy%20%7C%20PePy-D97706?style=for-the-badge&logo=clickhouse&logoColor=white)](https://clickpy.clickhouse.com/dashboard/aegis-mail-companion)
[![PWA Ready](https://img.shields.io/badge/PWA-Installable%20Desktop%20%26%20Mobile-2563EB?style=for-the-badge&logo=pwa&logoColor=white)](https://aegis-mail-companion.vercel.app)
[![Python](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/aegis-mail-companion/)
[![Platform](https://img.shields.io/badge/OS-macOS%20%7C%20Windows%20%7C%20Linux-4F46E5?style=for-the-badge)](https://pypi.org/project/aegis-mail-companion/)
[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://pypi.org/project/aegis-mail-companion/)
[![React](https://img.shields.io/badge/React-18%20PWA-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://pypi.org/project/aegis-mail-companion/)
[![Local LLMs](https://img.shields.io/badge/Local%20LLMs-Ollama%20%7C%20vLLM-000000?style=for-the-badge&logo=ollama&logoColor=white)](https://pypi.org/project/aegis-mail-companion/)

### **aegis Mail Companion (`aegis-mail-companion`) — Autonomous AI Email & Tiered L1/L2 Support Bot**
*Part of the [aegis-ai-suite](https://pypi.org/project/aegis-ai-suite/) Ecosystem — Multi-Agent · Multi-Provider (Outlook, Gmail, Zoho, IMAP) · Human-Governed · Jira-Correlated · Installable PWA*

</div>

---

**Aegis Mail Companion** is an autonomous, self-hosted AI Email Companion and Tiered L1/L2 Customer & Engineering Support Bot. Connect **Microsoft Outlook / Office 365**, **Google Gmail**, **Zoho Mail**, or **any Standard IMAP/SMTP server**, configure **Cloud or 100% Local LLMs (Ollama, vLLM, OpenAI, Anthropic, Gemini, Groq)**, and orchestrate **7 specialized Email AI Agents** and **6 Email Skills** in a single self-contained Python package.

---

## ⚡ 30-Second Quick Install & Immediate Browser Launch (macOS · Windows · Linux)

Installing `aegis-mail-companion` installs **all required backend dependencies, the pre-built React + PWA web interface, the 7 Email Agents, and the 6 Email Skills** in a single command. Run `aegis-mail` and it immediately launches in your browser:

```bash
# 1. Install the universal Python package from PyPI
pip install aegis-mail-companion

# 2. Configure your PostgreSQL + pgvector database URL (auto-creates database, extensions & all tables on startup)
export EXPORT_AEGIS_EMAIL_COMPANION_DB="postgresql://postgres:password@localhost:5432/aegis_mail_companion"

# 3. Launch the server & immediately open Mail Companion in your browser (http://localhost:8020)
aegis-mail
# (or `python3 -m aegis_mail_companion`)
```

> **Automatic Database & Vector RAG Provisioning:** When `EXPORT_AEGIS_EMAIL_COMPANION_DB` (or `--db-url`) is set, the first service startup automatically creates the target database (if missing), enables `vector` (`pgvector`) + `pg_trgm` + `pgcrypto` extensions, applies all database tables/functions/indexes (`kb_files`, `kb_parents`, `kb_chunks`, `projects`, `connectors`, `email_accounts`, etc.), and saves the connection URL to `~/.aegis-mail-companion/settings.json`.

### Default Sign-In Credentials (Local Workspace)
- **URL:** `http://localhost:8020` (opens automatically in your default browser; click **Install App** in the top bar to install as a standalone Desktop/Mobile PWA)
- **Email:** `admin@example.com`
- **Password:** `admin1234`

### CLI Options (`aegis-mail` / `aegis-mail-companion`)

```bash
aegis-mail                                 # Start Mail Companion (:8020) & open browser immediately
aegis-mail --port 8080                     # Run on a custom port (e.g. http://localhost:8080)
aegis-mail --host 0.0.0.0 --port 8020      # Expose on LAN for team access
aegis-mail --no-browser                    # Run server headlessly without opening a browser tab
aegis-mail --update                        # Self-update to the latest release from PyPI via pip
```

---

## ✨ Key Features & Architecture

### 1. 📬 Multi-Provider Email Connectivity (With Built-in Step-by-Step Visual Setup Guides)
Every provider card includes an interactive **? Help** button that opens a right-side step-by-step setup drawer with annotated screenshots and 1-click server presets:
- **Microsoft Outlook / Office 365:** OAuth 2.0 Web Redirect, Device Code flow, and Sovereign Cloud support (`graph.microsoft.com`, US Gov, 21Vianet) via Microsoft Graph API.
- **Google Gmail:** Google Workspace & personal Gmail via **16-digit App Password** (`imap.gmail.com:993` / `smtp.gmail.com:587`) or Google Cloud OAuth 2.0.
- **Zoho Mail:** Zoho OAuth 2.0 or Application-Specific Password across all regional data centers (`imap.zoho.com`, `imappro.zoho.com`, `.eu`, `.in`, `.com.au`, `.jp`).
- **Standard Mail (IMAP/SMTP):** 1-click presets and visual guides for **cPanel / Corporate Mail**, **Apple iCloud Mail**, **Yahoo Mail**, **Fastmail**, **Namecheap PrivateEmail**, **Rackspace**, and **GoDaddy / Titan Mail**.
- **AES-256 / Fernet Encrypted Token Vault:** All OAuth refresh tokens and IMAP/SMTP App Passwords are encrypted at rest.

### 2. 🤖 7 Specialized Email AI Agents (`AI Agents` Screen)
| Stage | Agent ID | Agent Name | Role & Capabilities |
| :---: | :--- | :--- | :--- |
| **★** | `email_ticket_analysis_agent` | **Ticket Analysis Agent** | Extracts issue keys (`SCRUM-21`), fetches live Jira/Project context, performs root-cause analysis, and drafts or auto-sends replies. |
| **⚡** | `email_tiered_pipeline_agent` | **Tiered L1/L2 Support Pipeline Agent** | End-to-end 5-stage orchestrator (`Stage 1 → Stage 2 → Stage 3/4 → Stage 5`). |
| **1** | `email_thread_parser_agent` | **Thread Parser & Digest Agent** | Strips signatures/disclaimers, orders replies chronologically, and separates `historical_context` from the `immediate_ask`. |
| **2** | `email_sentiment_triage_agent` | **Sentiment & Triage Router Agent** | Detects customer frustration, urgency, SLA risk, and churn risk; routes to `L1`, `L2`, or `HUMAN_ESCALATION`. |
| **3** | `email_l1_support_agent` | **L1 Support Agent (General Support)** | Resolves standard inquiries, billing, and FAQs via Knowledge Base RAG; supports high-confidence (`>90%`) auto-send. |
| **4** | `email_l2_support_agent` | **L2 Support Agent (Deep Technical)** | Parses stack traces, HTTP errors, and logs; cross-references issue trackers to construct technical troubleshooting replies. |
| **5** | `email_response_qa_agent` | **Response Drafting & QA Agent** | Enforces empathy, corporate tone, policy guardrails, and completeness before 1-Click Send. |

### 3. 🧠 6 Specialized Email Skills (`Skills Library` Screen)
1. **Email Thread Digest & Delta Extraction** (`email_thread_digest`)
2. **Customer Sentiment, Urgency & L1/L2 Triage Routing** (`email_sentiment_triage`)
3. **L1 General Customer Support & FAQ Resolution** (`email_l1_faq_resolution`)
4. **L2 Technical Support, Log & Stack-Trace Diagnostics** (`email_l2_technical_diagnostics`)
5. **Jira & Project Ticket Correlation for Incoming Emails** (`email_jira_ticket_correlation`)
6. **Support Response QA, Tone Alignment & Policy Guardrails** (`email_response_qa_guardrails`)

### 4. 🖥️ Installable Progressive Web App (PWA)
- Includes a Web App Manifest (`manifest.webmanifest`) and offline-capable Service Worker (`sw.js`).
- Click **Install App** in the top navigation bar on Chrome, Edge, Brave, or Safari (`Add to Dock` / `Add to Home Screen`) to run **Mail Companion** in its own standalone desktop or mobile window with quick-launch shortcuts to **Email Config**, **AI Models**, **AI Agents**, and **Skills Library**.

---

## 🔗 Ecosystem & Links

- **Official Documentation & Setup Portal:** [https://aegis-mail-companion.vercel.app](https://aegis-mail-companion.vercel.app)
- **PyPI Author Profile:** [https://pypi.org/user/sachinbosep/](https://pypi.org/user/sachinbosep/)
- **Full Enterprise Suite (`aegis-ai-suite`):** [https://pypi.org/project/aegis-ai-suite/](https://pypi.org/project/aegis-ai-suite/)
- **Official Aegis Portal:** [https://aegis-help.nilswa.com](https://aegis-help.nilswa.com)
