customeragent

SentinelQMS - AI-Powered Customer Complaint Management System MVP

An end-to-end MVP for a Pharmaceutical Manufacturing Quality Management System (QMS). This tool automates customer complaint intake by extracting 11 structured fields from unstructured complaint text or uploaded documents (PDF, DOCX, TXT, EML) using a LangGraph state graph powered by Groq API, and assigns an initial GMP risk severity & priority rating.

---

🏛️ System Architecture

                               ┌─────────────────────────────────────────┐
                               │           React + Redux Store           │
                               │           (Vite + Inter Font)           │
                               └────────────────────┬────────────────────┘
                                                    │
                                           POST /api/extract
                                           POST /api/parse-and-extract
                                                    │
                                                    ▼
                               ┌─────────────────────────────────────────┐
                               │             FastAPI Backend             │
                               └────────────────────┬────────────────────┘
                                                    │
                                                    ▼
                               ┌─────────────────────────────────────────┐
                               │         LangGraph State Pipeline        │
                               └────────────────────┬────────────────────┘
                                                    │
           ┌────────────────────────────────────────┼────────────────────────────────────────┐
           │                                        │                                        │
           ▼                                        ▼                                        ▼
┌──────────────────────┐                ┌──────────────────────┐                ┌──────────────────────┐
│  1. extract_fields   │                │ 2. assess_severity   │                │ 3. generate_summary  │
│                      ├───────────────►│      _priority       ├───────────────►│      (Bonus)         │
│ Model: llama-3.1-8b-instant │                │ Model: llama-3.3-70b │                │ Model: llama-3.1-8b-instant │
└──────────────────────┘                └──────────────────────┘                └──────────────────────┘

LangGraph Nodes & Model Strategy

1. extract_fields (llama-3.1-8b-instant): Extracts 11 key QMS metadata fields: complaint_source, customer_name, product_name, product_strength_grade, batch_lot_number, manufacturing_date, expiry_date, quantity_affected, complaint_type, complaint_date, detailed_description.
2. assess_severity_priority (llama-3.3-70b-versatile): Evaluates initial severity (Critical, Major, Minor) and priority (High, Medium, Low) based on GMP risk, patient health impact, and sterility/potency risks. Includes detailed technical rationale.
3. generate_exec_summary [Bonus Node] (llama-3.1-8b-instant): Produces a 2-3 line executive summary and immediate QA action items (e.g. batch quarantine, sample returns).

---

📁 Repository Structure

.
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── core/
│   │   │   └── config.py              # Environment & Groq configuration
│   │   ├── graph/
│   │   │   ├── nodes.py               # LangGraph node definitions
│   │   │   └── workflow.py            # LangGraph StateGraph setup
│   │   ├── schemas/
│   │   │   └── complaint.py           # Pydantic schemas
│   │   ├── services/
│   │   │   └── groq_client.py         # Groq API client with JSON mode
│   │   ├── utils/
│   │   │   └── doc_parser.py          # PDF/DOCX/TXT/EML parser
│   │   └── main.py                    # FastAPI server & routes
│   ├── tests/
│   │   └── sample_fixtures.py         # 3 realistic pharma complaint fixtures
│   ├── .env.example
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Header.jsx
│   │   │   ├── LeftPanelForm.jsx      # Log Customer Complaint Form
│   │   │   ├── RightPanelAssistant.jsx # AI Intake & Chat Assistant
│   │   │   └── ProgressBar.jsx        # LangGraph stage indicator
│   │   ├── store/
│   │   │   ├── complaintSlice.js      # Redux Toolkit state
│   │   │   └── store.js
│   │   ├── App.jsx
│   │   ├── main.jsx
│   │   └── index.css                  # Modern dark theme styles
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
└── README.md

---

🚀 Quickstart Guide

Prerequisites

• Python 3.9+
• Node.js 18+ & npm
• Groq API Key (Sign up free at console.groq.com)

---

1. Running Backend (FastAPI)

1. Open terminal and navigate to /backend:

   cd backend
   

2. Create a virtual environment & activate it:

   python -m venv venv
   # On Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   # On Mac/Linux:
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure your .env file:

   cp .env.example .env
   

   Open .env and set your Groq API Key:

   GROQ_API_KEY=gsk_your_actual_groq_api_key_here
   GROQ_MODEL_FAST=llama-3.1-8b-instant
   GROQ_MODEL_REASONING=llama-3.3-70b-versatile
   PORT=8000
   

5. Launch FastAPI development server:

   python -m app.main
   

   The backend runs on http://localhost:8000. You can test API endpoints interactively at http://localhost:8000/docs.

---

2. Running Frontend (React + Vite)

1. Open a second terminal window and navigate to /frontend:

   cd frontend
   

2. Install dependencies:

   npm install
   

3. Start Vite dev server:

   npm run dev
   

4. Open http://localhost:5173 in your browser.

---

🧪 Testing the MVP

1. Preset Test Fixtures: On the top right panel, click one of the preset buttons:
   • Sterility / Particulate Contamination (Critical)
   • Sub-potency / Efficacy Failure (Major)
   • Packaging / Labeling Defect (Minor)
2. Text / Document Upload:
   • Paste raw text into the text area OR drop a PDF / DOCX file into the upload zone.
   • Click "Extract & Assess AI".
3. Inspect Extraction:
   • Watch the Extraction Progress Bar move through LangGraph stages (Node 1 $\rightarrow$ Node 2 $\rightarrow$ Node 3).
   • Observe auto-populated form fields on the Left Panel.
   • Review Executive Summary & Recommended Steps on the Right Panel.
4. Follow-Up Interactive Chat:
   • Use the chat box at the bottom right to ask questions like:
     • "What risk does this issue pose to patient health?"
     • "What root cause analysis steps should we take?"

---

🛡️ Robustness & Error Handling

• JSON Mode & Pydantic Validation: Every LLM node enforces structured JSON responses via Pydantic model validation.
• Graceful Fallbacks: API key errors, network issues, or malformed LLM outputs are caught and handled gracefully in the state graph without crashing the UI.
• Database Abstraction: Built with an in-memory dictionary layer that can be swapped for PostgreSQL by updating a single repository module.