🎫 AI Support Ticket Analyzer

An AI-powered backend service that analyzes customer support tickets in real time. Send raw ticket text through the API and receive structured JSON with category classification, priority assignment, order ID extraction, sentiment analysis, and a concise summary — all powered by OpenAI's GPT-4.1 Mini.

Built with FastAPI, Pydantic, and the OpenAI Responses API.

---

🧠 Why This Project?

Customer support teams handle hundreds of tickets daily. Manually reading, categorizing, and prioritizing each one is slow, inconsistent, and expensive.

AI Support Ticket Analyzer solves this by:

• Classifying tickets into 8 business categories automatically
• Assigning priority based on deterministic rules — no hallucinated urgency
• Extracting structured data (order IDs, summaries) from unstructured text
• Detecting sentiment to flag frustrated customers early
• Integrating with Slack for real-time team notifications

This is the kind of service that plugs directly into helpdesk pipelines (Zendesk, Freshdesk, Intercom) or custom CRM backends.

---

Live Demo

After starting the server you can explore the interactive API documentation:

http://localhost:8000/docs

This Swagger interface allows you to test the AI ticket analyzer directly from the browser.

---

🏗️ Architecture

Client → POST /analyze-ticket { "text": "..." }
  → FastAPI router
    → Analyzer (loads prompt, calls LLM, maps priority)
      → OpenAI Responses API
    ← Validated TicketAnalysis
  ← JSON response

Layer	Responsibility
app/main.py	FastAPI app, endpoints, CORS, lifespan
app/config.py	Environment variable management via pydantic-settings
app/schemas.py	Pydantic models, enums, validation
app/analyzer.py	Orchestration: prompt → LLM → parse → priority mapping
app/llm_client.py	Async OpenAI Responses API client (httpx)
app/integrations/slack.py	Decoupled Slack webhook sender
prompts/analyze_ticket.txt	Externalized LLM system prompt

Key design decisions:

• Priority is derived deterministically from category — not by the LLM
• Slack integration is fully decoupled from the analysis endpoint and can be used independently
• The prompt is stored as a plain text file for easy iteration without code changes

---

AI Processing Pipeline

1. Ticket text is submitted through the API
2. The prompt template is loaded from prompts/analyze_ticket.txt
3. The ticket content is sent to the OpenAI Responses API
4. The LLM extracts structured fields
5. Priority is deterministically derived from category
6. The validated result is returned via Pydantic schema

---

🚀 Quick Start

1. Clone the repository

git clone https://github.com/andrei-ameliugin/ai-support-ticket-analyzer.git
cd ai-support-ticket-analyzer

2. Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

cp .env.example .env

Edit .env and add your OpenAI API key:

OPENAI_API_KEY=sk-your-actual-key
OPENAI_API_URL=https://api.openai.com/v1/responses
OPENAI_MODEL=gpt-4.1-mini
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url

5. Run the server

uvicorn app.main:app --reload

6. Open Swagger UI

Navigate to http://localhost:8000/docs in your browser.

---

📡 API Endpoints

POST /analyze-ticket

Analyze a customer support ticket.

Request:

{
  "text": "Hello, my order #45123 hasn't arrived yet. Can you check the delivery status?"
}

Response:

{
  "category": "delivery_issue",
  "priority": "medium",
  "order_id": "45123",
  "summary": "Customer reports missing delivery.",
  "customer_sentiment": "neutral"
}

POST /send-to-slack

Forward an analyzed ticket to Slack (requires SLACK_WEBHOOK_URL).

Request: A full TicketAnalysis JSON object.

GET /health

Health check — returns {"status": "ok"}.

---

🏷️ Categories & Priority Mapping

Category	Priority
billing_issue	🔴 High
payment_failed	🔴 High
account_access	🔴 High
delivery_issue	🟡 Medium
refund_request	🟡 Medium
technical_problem	🟡 Medium
product_question	🟢 Low
general_inquiry	🟢 Low

---

😊 Sentiment Detection

Every ticket is classified as:

• positive — grateful, satisfied, complimentary tone
• neutral — factual, informational, no strong emotion
• negative — frustrated, angry, disappointed tone

---

📂 Project Structure

ai-support-ticket-analyzer/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI application & endpoints
│   ├── config.py             # Settings from environment variables
│   ├── schemas.py            # Pydantic models & enums
│   ├── analyzer.py           # Core analysis orchestrator
│   ├── llm_client.py         # OpenAI Responses API client
│   └── integrations/
│       ├── __init__.py
│       └── slack.py          # Slack webhook integration
├── prompts/
│   └── analyze_ticket.txt    # LLM system prompt
├── examples/                 # Sample tickets for every category
├── .env.example              # Environment variable template
├── .gitignore
├── requirements.txt
├── LICENSE
└── README.md

---

📧 Example Tickets

The examples/ folder contains realistic sample tickets for every category:

File	Category
billing_issue.txt	Incorrect charges
payment_failed.txt	Declined payments
delivery_issue.txt	Missing packages
refund_request.txt	Return & refund
account_access.txt	Locked accounts
product_question.txt	Pre-purchase questions
technical_problem.txt	App bugs & crashes
general_inquiry.txt	Store hours & general info

Use any of these in the Swagger UI to test the API.

---

🔌 Real-World Integration Ideas

This service is designed to plug into larger support workflows:

• Gmail / Outlook → Incoming email webhook triggers /analyze-ticket
• Zendesk / Freshdesk → Auto-tag and prioritize new tickets
• Intercom / HubSpot → Enrich conversation metadata with AI analysis
• Slack → Push high-priority tickets to #urgent-support channels
• PagerDuty → Auto-escalate account_access or payment_failed tickets
• Internal dashboards → Aggregate sentiment trends and category distributions

---

🛠️ Tech Stack

Technology	Purpose
Python 3.11+	Runtime
FastAPI	Web framework & Swagger UI
Pydantic v2	Data validation & serialization
pydantic-settings	Environment configuration
httpx	Async HTTP client
OpenAI Responses API	LLM inference

---

Possible Improvements

• Streaming responses for large ticket analysis
• Batch ticket processing endpoint
• Queue-based processing (Redis / Celery)
• Observability with OpenTelemetry
• Unit and integration tests
• Rate limiting and API key authentication

---

👨‍💻 About This Project

This project demonstrates:

• Clean Python backend architecture with clear module boundaries
• AI/LLM integration in a production-style API
• Prompt engineering for structured JSON extraction
• Pydantic-first data modeling and validation
• Async programming with FastAPI and httpx
• Decoupled third-party integrations (Slack)
• Professional documentation and project structure

Ideal for: AI/ML engineer portfolios, backend developer showcases, Upwork client proposals, and recruiter demonstrations.

---

Use Cases

This service can be used by companies that receive high volumes of customer support emails and want to automate:

• ticket triage
• priority routing
• CRM enrichment
• sentiment monitoring
• support team notifications

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.