{"id":50936056,"url":"https://github.com/prodev717/support-pilot","last_synced_at":"2026-06-17T09:02:23.200Z","repository":{"id":361668481,"uuid":"1208513063","full_name":"prodev717/support-pilot","owner":"prodev717","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-31T17:49:50.000Z","size":7,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T19:23:00.740Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prodev717.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T11:43:07.000Z","updated_at":"2026-05-31T17:49:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/prodev717/support-pilot","commit_stats":null,"previous_names":["prodev717/support-pilot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/prodev717/support-pilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodev717%2Fsupport-pilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodev717%2Fsupport-pilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodev717%2Fsupport-pilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodev717%2Fsupport-pilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prodev717","download_url":"https://codeload.github.com/prodev717/support-pilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodev717%2Fsupport-pilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34441285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-17T09:02:22.138Z","updated_at":"2026-06-17T09:02:23.193Z","avatar_url":"https://github.com/prodev717.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Support-Pilot ✈️\n\nSupport-Pilot is a premium, AI-powered customer support inbox management and triage workspace. It automates ticket classification, provides retrieval-augmented generation (RAG) capabilities to resolve queries using your custom knowledge base, and offers an admin dashboard for human-in-the-loop review and management.\n\nBuilt with **FastAPI**, **Google Gemini 2.5 Flash**, **Pinecone**, and **SQLAlchemy**, it streamlines customer support by bridging the gap between automated AI replies and human agent review.\n\n---\n\n## 🌟 Key Features\n\n1. **AI Decision Engine**: Automatically classifies incoming emails using Gemini 2.5 Flash. It identifies:\n   - **Issue Category**: (e.g., *refund, billing, technical, cancellation, complaint, account, etc.*)\n   - **Severity**: (*low, medium, high*)\n   - **Customer Sentiment**: (*positive, neutral, negative, mixed*)\n   - **Underlying Emotion**: (*frustrated, angry, concerned, happy, etc.*)\n   - **Actionable Decision**: \n     - `auto_resolve`: Generates a draft using context from the Knowledge Base and automatically replies/closes the ticket.\n     - `review_required`: Generates an AI draft reply but holds it in the dashboard for human review and approval.\n     - `escalate`: Automatically forwards the query to the designated department email and notifies the customer.\n2. **Retrieval-Augmented Generation (RAG)**: Integrates with Pinecone's serverless vector store to chunk, store, and query knowledge documents (supporting `.pdf`, `.docx`, and `.txt` files).\n3. **Email Integration**: Monitors an IMAP inbox (such as Gmail) for incoming support requests, resolves threading (detecting replies via `Message-ID`, `References`, or thread IDs), and sends outbound replies or forwards via SMTP.\n4. **Admin Dashboard**: A sleek, dark-themed responsive admin panel:\n   - **Tickets Workspace**: Tracks open, pending, and escalated tickets. Displays conversation history, sentiment badges, and offers a draft editor where agents can modify and send AI-suggested responses.\n   - **Knowledge Base Tab**: Upload documents, adjust chunk/overlap sizes, search the index directly, and manage ingested files.\n   - **Email Routing Tab**: Set up and customize routing rules to map issue types to specific departments (e.g., Billing, Tech Support).\n5. **Dual-Process Architecture**: A lightweight background poller checks for emails asynchronously, while the web server handles API requests and serves the dashboard.\n\n---\n\n## 📂 Project Structure\n\n```text\nsupport-pilot/\n├── main.py              # Entry point for the background email listener (polls IMAP inbox)\n├── server.py            # FastAPI server implementing REST API endpoints \u0026 HTML template rendering\n├── config.py            # Loads and manages env configuration and similarity thresholds\n├── database.py          # SQLAlchemy models (DocumentMetadata, Email, Ticket) \u0026 database connection\n├── schemas.py           # Pydantic validation schemas for API requests\n├── services.py          # Core helper functions for text extraction, chunking, and Pinecone vector ops\n├── ai_service.py        # Gemini API client wrapper for triage analysis \u0026 draft generation\n├── email_service.py     # IMAP inbox fetcher, parser, SMTP reply/forward sender, and thread resolver\n├── policy.txt           # Standard customer support policy rules used in system prompt contexts\n├── templates/\n│   └── upload.html      # Monolithic glassmorphic frontend UI dashboard (Outfit font, CSS variables)\n├── pyproject.toml       # Python dependencies configuration (managed by uv)\n├── start-service.bat    # Windows batch script to launch the listener and server concurrently\n└── .env                 # Environment variables configuration file (Credentials \u0026 API keys)\n```\n\n---\n\n## 🛠️ Prerequisites\n\n- **Python**: version `3.11` or higher is required.\n- **Package Manager**: [uv](https://github.com/astral-sh/uv) is highly recommended for dependency and environment management (as used in the start scripts). Alternatively, standard `pip` can be used.\n\n---\n\n## 🚀 Getting Started\n\n### 1. Clone \u0026 Set Up Environment\n\nCreate a `.env` file in the root directory and specify the following variables:\n\n```env\nEMAIL_USER = your-support-email@gmail.com\nEMAIL_PASS = your-gmail-app-password\nGEMINI_API_KEY = your-google-gemini-api-key\nPINECONE_API_KEY = your-pinecone-api-key\nPINECONE_INDEX_NAME = your-pinecone-index-name\nDATABASE_URL = postgresql://username:password@hostname/database?sslmode=require\nSERVER_URL = http://localhost:8000\nSIMILARITY_THRESHOLD = 0.40\n```\n\n\u003e [!IMPORTANT]\n\u003e - **Gmail Setup**: If using Gmail, you must enable **2-Step Verification** on your Google Account and generate an **App Password** for `EMAIL_PASS`. Standard passwords will be rejected by Google's SMTP/IMAP servers.\n\u003e - **Pinecone Index**: Ensure your Pinecone index supports Integrated Embeddings or is configured to match the indexing structure in `services.py`.\n\n### 2. Install Dependencies\n\nInstall `uv`:\n```bash\npip install uv\n```\n\nThen install dependencies:\n```bash\nuv sync\n```\n\n### 3. Running the System\n\nYou can run both processes together or launch them separately.\n\n#### Option A: Run concurrently (Windows Batch script)\nRun the convenience script:\n```bash\nstart-service.bat\n```\nThis script opens two separate command line windows running:\n1. `uv run main.py` (Email Poller)\n2. `uv run uvicorn server:app --reload` (FastAPI Server)\n\n#### Option B: Launch manually\n**Start the FastAPI server:**\n```bash\nuv run uvicorn server:app --reload --port 8000\n```\n\n**Start the background email listener:**\n```bash\nuv run main.py\n```\n\nOpen your browser and navigate to `http://localhost:8000` to access the Admin Dashboard.\n\n---\n\n## 📊 Database Schema Details\n\nThe system uses SQLAlchemy to manage three tables:\n- **`tickets`**: Stores the logical thread groupings (`ticket_id`), customer contact details, subject, body, and the full history of messages. It also records triage results (`severity`, `sentiment`, `emotion`, `issue`) and AI metadata like `ai_decision`, `ai_draft_reply`, and `forwarded_to`.\n- **`emails`**: Contains the department rules configuration used to map issues to specialists.\n- **`document_metadata`**: Tracks chunk IDs, filenames, and Pinecone vector IDs to coordinate knowledge document deletion and references.\n\n---\n\n## ⚙️ AI Classification \u0026 Triage Flow\n\nWhen an email lands in the inbox:\n1. **Fetch \u0026 Clean**: The poller extracts the plaintext body, sender address, and thread headers.\n2. **Context Retrieval**: The email content is queried against the Pinecone index to retrieve up to 5 matching chunks from the ingested documents above the `SIMILARITY_THRESHOLD`.\n3. **Triage Analysis**: Gemini is prompted with the incoming email, knowledge base context, and department rules to output a structured JSON response.\n4. **Action Execution**:\n   - **`auto_resolve`**: A reply is dispatched immediately using SMTP in-thread reference headers, and the ticket status is saved as `Closed`.\n   - **`escalate`**: The ticket is forwarded to the matching department email (e.g., billing inquiries go to Billing), a notice is sent to the customer, and the ticket is set to `Escalated`.\n   - **`review_required`**: No email is sent. The generated reply draft and reasoning are stored. The ticket is marked `Pending` and highlights itself in the Admin Dashboard for review.\n\n---\n\n## 🎨 UI Dashboard Showcase\n\nThe dashboard features:\n- **Real-time Stat Cards**: Total Open, Pending Review, Escalated, High Severity, and Closed metrics.\n- **Active Thread Viewer**: Allows agents to inspect the exact chat layout of email exchanges (with distinct visual styles for inbound vs outbound messages).\n- **Interactive Draft Console**: Agents can review AI-drafted replies, modify them directly in a textarea, and hit **Approve \u0026 Send** to transmit the email instantly via SMTP.\n- **Document Management**: Drag-and-drop file uploader with configurable chunk settings, coupled with an active document list highlighting source files.\n- **Department Routing**: Intuitive table listing current rules, complete with a creation form to add or edit existing departments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprodev717%2Fsupport-pilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprodev717%2Fsupport-pilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprodev717%2Fsupport-pilot/lists"}