AI Support Ticket Analyzer

A small Python command-line tool that analyzes a technical support ticket and returns structured triage guidance for Support Engineers.

The primary analysis path uses the OpenAI Responses API through the official Python SDK to generate structured triage. The dependency-free heuristic analyzer is retained as a credential-free alternative for reviewing the submission; the default auto provider uses it only when OPENAI_API_KEY is unavailable or an API request fails.

OpenAI API setup

Create and activate a virtual environment:

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

Install dependencies:

python3 -m pip install -r requirements.txt

Create a local .env file:

cp .env.example .env

Edit .env and set your key:

OPENAI_API_KEY=your_real_api_key_here
OPENAI_MODEL=gpt-5-mini

Do not commit .env; it is intentionally ignored by .gitignore.

Run with the OpenAI API:

python3 ticket_analyzer.py --provider openai --file ticket.txt

You can also omit --provider openai; the default auto mode uses OpenAI when OPENAI_API_KEY is available and otherwise uses the local heuristic analyzer.

Usage

Analyze inline text:

python3 ticket_analyzer.py --ticket "Customer cannot submit assessments and receives an Unexpected error."

Analyze a text file:

python3 ticket_analyzer.py --file ticket.txt

Analyze from stdin:

cat ticket.txt | python3 ticket_analyzer.py

Return JSON:

python3 ticket_analyzer.py --file ticket.txt --json

Run with the OpenAI API (recommended):

python3 ticket_analyzer.py --file ticket.txt --provider openai

Use the credential-free heuristic alternative:

python3 ticket_analyzer.py --file ticket.txt --provider heuristic

Verify which provider ran:

python3 ticket_analyzer.py --file ticket.txt --provider openai --verbose

--verbose writes execution metadata to standard error. A successful OpenAI call prints provider=openai request=completed, along with the response ID, model, duration, and (when returned by the API) token usage. It never prints ticket text or API keys. With --provider openai, an API failure ends with an error; it does not fall back to heuristic analysis. Only --provider auto can fall back, and it prints a fallback message to standard error when that happens.

Output

The analysis includes:

• Concise issue summary
• Classification: Bug, Configuration issue, User question, Service request, or Insufficient information
• Recommended priority: Low, Medium, High, or Critical
• Explanation of classification and priority
• Missing information or customer questions
• Recommended troubleshooting steps
• Draft customer response
• Escalation recommendation for Development

Deliverables

1. Source code

The implementation is in ticket_analyzer.py. It is a single-file Python CLI. Local heuristic mode has no third-party dependency, while OpenAI mode uses the official openai Python SDK listed in requirements.txt.

Main design points:

• OpenAI mode for LLM-generated analysis when OPENAI_API_KEY is available in the environment or local .env file.
• Offline heuristic mode as a credential-free local review alternative.
• Markdown output for better readability and subsequent human review and JSON output for downstream automation.
• Explicit classification and priority enums to keep output structured.
• Structured Outputs keep every OpenAI response aligned to the expected triage fields and allowed classification and priority values.

2. README

This README explains how to run and review the solution.

Run with the OpenAI API (primary path):

python3 ticket_analyzer.py --provider openai --file ticket.txt --verbose

This requires OPENAI_API_KEY and runs the OpenAI Responses API. The verbose trace confirms the completed request, response ID, model, duration, and token usage.

Credential-free review alternative:

python3 ticket_analyzer.py --provider heuristic --file ticket.txt

Use heuristic mode only when API credentials are unavailable or when you need to review the command-line flow without making an API call.

3. Prompts

The OpenAI-backed mode uses the Responses API with Structured Outputs and these key instructions:

System instruction:

You are a senior technical support triage assistant. Return only structured JSON matching the provided schema. Be concise, practical, and customer-centric. Only set escalate_to_development to true when Support has already been unable to identify a fix or workaround. For initial triage, recommend that Support tries reproduction, log review, configuration checks, and workaround discovery first.

User instruction template:

Analyze this technical support ticket for a Support Engineer.

The analysis must include:
- A concise summary of the issue.
- Classification: Bug, Configuration issue, User question, Service request, or Insufficient information.
- Priority: Low, Medium, High, or Critical.
- Missing information or questions for the customer.
- Recommended troubleshooting steps.
- A polished draft customer response that follows these rules:
  - The selected priority is the sole authority for urgency wording. State its exact value (Low, Medium, High, or Critical) and do not use a stronger or weaker label anywhere else. In particular, for High priority, never use "urgent", "urgently", or "critical".
  - Write as a direct, customer-facing email: acknowledge the specific business impact in the ticket and use clear, warm, professional language.
  - Start with `**Priority: <selected priority>**`, then `Hello,` on its own line and a short acknowledgement paragraph. Do not add an "Acknowledgement" heading or label.
  - Use `## Information requested` with 3–5 concise bullets only for details the customer needs to provide.
  - Follow with `## What happens next` and one short paragraph explaining the Support investigation in customer-friendly language. Avoid internal jargon, speculative causes, and unsupported promises about resolution times or workarounds.
  - End with a courteous, concise closing using `Thank you,` and `Support Team` on separate lines.
  - Keep the response under 180 words and include only information supported by the ticket or this analysis.
- Whether to escalate to Development, only after Support cannot identify a fix or workaround.

If the ticket describes a browser-based submission or save failure, consider asking for a sanitized HAR file.

Ticket:
{ticket}

The JSON schema requires:

• summary
• classification
• priority
• explanation
• missing_information
• troubleshooting_steps
• draft_response
• escalate_to_development
• escalation_reason

4. Example OpenAI API output

Input ticket:

Since this morning, our users receive an 'Unexpected error' message when submitting supplier assessments.
Viewing and editing assessments still works. We tried logging out and using another browser, but the issue remains.
This is preventing our compliance team from completing assessments due today. We have not made any
configuration changes recently.
Please treat this as urgent

This is the exact structured output returned by the OpenAI-backed command below for the input above. It was generated with gpt-5-mini-2025-08-07 (response ID req_87379145cd174fb097e25c193ebf066d), not by the local heuristic provider.

.venv/bin/python ticket_analyzer.py --provider openai --file ticket.txt --json

{
  "summary": "Users receive an 'Unexpected error' when submitting supplier assessments; viewing and editing still work. Logout and different browsers did not help. This blocks the compliance team from completing assessments due today.",
  "classification": "Bug",
  "priority": "High",
  "explanation": "Submission is failing with an unexpected error while other UI actions succeed, and multiple browsers/users are affected. The issue impacts a time-sensitive business workflow (assessments due today), so priority is High. Initial triage should treat this as a server-side fault or validation path rather than a local browser issue.",
  "missing_information": [
    "Exact timestamp (with timezone) when the problem first occurred",
    "Whether all users and all supplier assessments are affected or only certain users/assessments (tenant/org and user IDs if possible)",
    "Exact reproduction steps (click-by-click) and whether specific fields, attachments, or sizes are included",
    "Screenshot of the 'Unexpected error' and any error/correlation ID shown",
    "Sanitized HAR file of a failing submission attempt and browser console logs"
  ],
  "troubleshooting_steps": [
    "Attempt to reproduce the error in the customer's account at the reported time and with the same steps/data.",
    "Collect a sanitized HAR of the failing submission and browser console logs; request screenshot and any error/correlation IDs.",
    "Search application and error-monitoring logs (by timestamp, user, correlation ID) for stack traces or backend error messages.",
    "Verify recent deployments, configuration changes, feature flags, and service health (API, DB, auth) around the incident time.",
    "Test submitting a minimal assessment (no attachments, minimal fields) to check for data/validation-related failures and identify possible workarounds (API or admin submission)."
  ],
  "draft_response": "**Priority: High**\nHello,\n\nThank you — I understand your compliance team cannot complete supplier assessments due today because submissions return an \"Unexpected error.\" We will investigate this with High priority.\n\n## Information requested\n- Exact timestamp (with timezone) when you first saw the error\n- Is every user and every assessment affected? Please include tenant/org and a sample user ID\n- Step-by-step actions you take to submit (including attachments or large fields)\n- Screenshot of the error and any error/correlation ID shown\n- A sanitized HAR of a failing submission and browser console logs\n\n## What happens next\nWe will try to reproduce the failure in your environment, review logs and recent deployments, and check backend service health; we’ll update you with findings and next steps as soon as we have them.\n\nThank you,\nSupport Team",
  "escalate_to_development": false,
  "escalation_reason": ""
}

5. AI usage summary

Tools used:

• Codex was used to design and implement the Python CLI, README, and verification commands.
• The sample output above was generated by the OpenAI Responses API. The local heuristic provider remains available as a credential-free alternative for reviewing the submission.

How AI helped:

• Structured the ticket analysis categories.
• Drafted practical troubleshooting and customer-response language.
• Added execution tracing so API usage can be verified through the selected provider, response ID, latency, and token usage without logging ticket text or credentials.

One output changed, corrected, or rejected:

• An early draft automatically escalated the issue to Development. This was corrected to keep escalation evidence-based: Support first reproduces and investigates the problem, gathers the relevant context, and looks for a fix or workaround; Development is recommended only when that triage cannot resolve the likely defect.

6. Reflection

Independent decision:

• The solution is designed around the OpenAI API, which is the intended provider for live, LLM-generated ticket triage. I included a small dependency-free heuristic path solely so the submitted work can be run and reviewed when API credentials are unavailable and it also prevents unnecessary API calls during initial stages; it is not intended to replace the OpenAI workflow.

Key assumptions:

• A support engineer needs a fast triage aid, not an authoritative root-cause diagnosis.
• Priority can be estimated from business impact, urgency, and outage/security/data-loss signals.
• Development escalation should be recommended only after Support cannot identify a fix or workaround through triage.

Remaining work:

• Add unit tests for more ticket types and edge cases.
• Add richer policy controls for customer data handling and HAR-file requests.
• Add configuration so teams can tune classification, priority, and escalation rules to their support process.
• Add additional benchmarking to test others models as the one used here (gpt-5-mini), even though very cost effective might not be the best option for a production environment.
• An agent isn't just producing an answer—it is taking actions over time, often across multiple tools, models, systems, and decision steps which is why observability should be added as a control layer. Without it agents would run as a black box.

What I would improve:

• The next meaningful step would be to evaluate the OpenAI workflow against representative, anonymized support tickets and have Support engineers review its recommendations. That feedback would guide refinements to the prompt, output schema, and escalation criteria before the workflow is integrated into a ticketing system.