An intelligent, terminal-based support ticket triage system with RAG (Retrieval-Augmented Generation), risk-based escalation, and multi-domain routing.
ARGUS is an AI agent that autonomously triages customer support tickets using a local-first, privacy-focused architecture. Unlike purely LLM-based solutions, it combines deterministic keyword routing with semantic search to ensure accurate, grounded responses while safely escalating high-risk tickets.
- 🔒 Privacy-First: Runs locally with offline embeddings (
all-MiniLM-L6-v2) and ChromaDB vector store - 🎯 Grounded Responses: All answers are extracted from the provided documentation corpus—no hallucinations
- ⚡ Smart Escalation: Risk keywords and confidence thresholds trigger automatic escalation to human agents
- 🧩 Modular Design: Clean separation of concerns across routing, retrieval, triage, and generation
- 📊 Transparent: Every decision includes a detailed justification explaining the routing logic
- 🔌 Optional LLM: Works without API keys; add Gemini/Claude/GPT for more natural language responses
The system is built with six modular components:
code/
├── main.py # CLI orchestrator and pipeline coordinator
├── config.py # Central configuration (thresholds, paths, risk keywords)
├── loader.py # CSV I/O with strict schema validation
├── router.py # Domain classifier for multi-domain routing
├── retriever.py # Vector search with heading-aware chunking
├── triage.py # Risk assessment and escalation logic
└── generator.py # Response generation (template or LLM-based)
Shows the complete data flow from input CSV through all processing stages to output generation.
Illustrates the optional LLM integration with fallback mechanisms and validation pipeline.
Details the RAG engine, embedding model, ChromaDB integration, and chunking strategy.
Complete system overview showing all components, data flows, and integration points.
- Load → Parse support tickets from CSV
- Route → Classify ticket domain using keyword analysis
- Retrieve → Semantic search across documentation corpus
- Triage → Assess risk and determine escalation vs. reply
- Generate → Create grounded response with justification
- Output → Write results to CSV with full traceability
- Python 3.9 or higher
- pip package manager
- Clone the repository
git clone https://github.com/yourusername/ARGUS.git
cd ARGUS- Create virtual environment
# Windows
python -m venv venv
venv\Scripts\activate
# macOS/Linux
python -m venv venv
source venv/bin/activate- Install dependencies
pip install -r code/requirements.txt- Optional: Configure API keys (for enhanced responses)
cp code/.env.example code/.env
# Edit code/.env and add your API key (Gemini recommended)Process support tickets:
python code/main.pyTest with sample data:
python code/main.py --sampleManual ticket testing:
python code/main.py --query "How do I reset my password?" --subject "Password Reset"Rebuild vector index (after updating documentation):
python code/main.py --rebuildThe agent works without API keys using template-based extraction. For more natural responses, add one of:
-
Google Gemini 2.5 Flash (Recommended - fastest & cheapest)
- Get key: https://aistudio.google.com/apikey
- Add to
code/.env:GEMINI_API_KEY=your-key-here
-
Anthropic Claude:
ANTHROPIC_API_KEY=sk-ant-... -
OpenAI GPT:
OPENAI_API_KEY=sk-proj-...
The agent automatically escalates tickets when:
- High-risk keywords detected: fraud, stolen, lawsuit, GDPR, security breach, account ban
- Service outages mentioned: "site down", "500 error", system failures
- Low retrieval confidence: Similarity score below 0.30 threshold
- Domain ambiguity: Cross-domain or insufficient context
All escalated tickets receive a safe, standardized handoff message.
| Column | Description |
|---|---|
Status |
replied or escalated |
Product Area |
Inferred from documentation path (e.g., settings, privacy) |
Response |
User-facing message grounded in corpus |
Justification |
Transparent decision log with routing details |
Request Type |
product_issue, feature_request, bug, or invalid |
The system includes validation scripts to ensure quality:
- Relevance Check: Validates responses match ticket context
- Quality Check: Ensures professional, complete responses
- Accuracy Report: Compares against expected outputs
ARGUS/
├── code/ # Main application code
│ ├── main.py # Entry point
│ ├── config.py # Configuration
│ ├── loader.py # CSV I/O
│ ├── router.py # Domain routing
│ ├── retriever.py # Vector search
│ ├── triage.py # Risk assessment
│ ├── generator.py # Response generation
│ ├── requirements.txt # Python dependencies
│ └── .env.example # API key template
├── data/ # Documentation corpus
│ └── [your documentation files]
└── README.md # This file
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
Questions or issues? Open an issue on GitHub or reach out to the maintainers.