sankarshan22/iterative-incredibles

Customer Support Ticket Triage - OpenEnv Environment

A production-ready OpenEnv environment for AI agents to learn automatic customer support ticket triage. This real-world task simulation mirrors the daily work of support teams: classifying issues, prioritizing requests, and routing to appropriate teams.

🎯 Motivation & Problem Statement

Why This Problem?

Real-world challenge: Support teams manually triage 100s-1000s of tickets daily:

• —Classification: Is it a bug, feature request, or question?
• —Prioritization: How urgent? What severity?
• —Routing: Which team handles this?
• —Actioning: What's the recommended first response?

Current pain points:

• —❌ Manual triage is slow and inconsistent
• —❌ Customer wait times increase
• —❌ Errors in routing waste team effort
• —❌ No machine learning applied to this workflow

Solution: Train AI agents to automate triage via OpenEnv, with:

• —Progressive difficulty (easy → medium → hard)
• —Deterministic grading for reproducibility
• —Context-aware rewards reflecting real business metrics
• —Baseline evaluation with GPT-4 Turbo

Success Criteria

• —Easy: ≥80% accuracy on category classification
• —Medium: ≥70% accuracy on priority & urgency decisions
• —Hard: ≥60% accuracy on full triage with recommendations

📋 Observation Space

Input data the agent receives for each ticket:

Observation(
    ticket_id: str,              # Unique identifier (e.g., "TKT-0042")
    customer_name: str,          # Customer name
    issue_text: str,             # Full ticket description  
    issue_type: str,             # Placeholder for classification
    sentiment_score: float,      # Sentiment analysis score [-1.0 to 1.0]
                                 # -1.0 = very angry, 0 = neutral, 1.0 = satisfied
    wait_time_hours: float,      # How long customer has been waiting
    is_escalated: bool,          # Whether ticket was escalated by customer
    step_count: int,             # Current step in episode
    task_difficulty: str,        # "easy", "medium", or "hard"
)

Example observation:

Observation(
    ticket_id="TKT-2847",
    customer_name="Alice Johnson", 
    issue_text="Can't login to my account. Getting 'Invalid credentials' error.",
    sentiment_score=-0.9,        # Very frustrated
    wait_time_hours=3.5,
    is_escalated=True,
    task_difficulty="medium"
)

🎬 Action Space

Decisions the agent must make:

Action(
    category: str,               # REQUIRED: "Bug" | "FeatureRequest" | "Question"
    priority: str,               # OPTIONAL: "Low" | "Medium" | "High" | "Critical"
    urgency_days: int,           # OPTIONAL: 1-7 days to respond
    department: str,             # OPTIONAL: "Engineering" | "Product" | "Support" | "Management"
    recommendation: str,         # OPTIONAL: Specific actionable suggestion
)

Example actions:

Easy task (classification only):

Action(category="Bug")

Medium task (add priority & urgency):

Action(
    category="Bug",
    priority="Critical",
    urgency_days=1
)

Hard task (full routing & recommendations):

Action(
    category="Bug",
    priority="Critical", 
    urgency_days=1,
    department="Engineering",
    recommendation="Check authentication service logs for failed login attempts"
)

📊 Task Descriptions & Expected Difficulty

Task 1: Category Classification (Easy)

Objective: Classify ticket into one of three categories Expected Difficulty: ⭐ (Low) Baseline Performance: 98% accuracy (GPT-4 Turbo)

What's required:

• —Just pick the correct category (Bug/FeatureRequest/Question)
• —Simple pattern matching on issue text
• —No need to consider other factors

Grading: 1.0 if correct, 0.0 if wrong

Real-world equivalent: First-pass triage where support buckets incoming tickets

Task 2: Priority & Urgency Assignment (Medium)

Objective: Assign priority level and response timeline Expected Difficulty: ⭐⭐ (Medium) Baseline Performance: 72% accuracy (GPT-4 Turbo)

What's required:

• —Correct category classification (from task 1)
• —Appropriate priority: Low/Medium/High/Critical
• —Response urgency: 1-7 days
• —Consider sentiment, wait time, escalation flags

Grading Logic:

• —Context-aware: Angry customer (-0.9 sentiment) → Critical priority is expected
• —Partial credit: High vs Critical priority = 0.5 points
• —Urgency scaling: Bug with -0.8 sentiment → 1 day expected

Real-world equivalent: Support agents routing by severity and customer impact

Task 3: Full Triage with Recommendations (Hard)

Objective: Complete ticket triage with actionable recommendations Expected Difficulty: ⭐⭐⭐ (Hard) Baseline Performance: 65% accuracy (GPT-4 Turbo)

What's required:

• —All fields from medium task (category, priority, urgency)
• —Department routing: Engineering/Product/Support/Management
• —Actionable recommendation text (specific, helpful)
• —Must match category-specific expectations

Grading Components:

1. 1.Category (25%): Correct classification
2. 2.Priority (25%): Contextually appropriate level
3. 3.Department (25%): Correct team assignment based on issue type
4. 4.Recommendation (25%): Quality of suggested action

Recommendation keywords (category-specific):

• —Bug: "investigate", "reproduce", "debug", "logs", "error"
• —FeatureRequest: "roadmap", "evaluate", "research", "prioritize"
• —Question: "guide", "documentation", "help", "walkthrough"

Real-world equivalent: Expert support team doing complex multi-factor analysis

📊 Baseline Scores

Model: GPT-4 Turbo Episodes: 5 per difficulty (15 total) Temperature: 0.3 (low randomness) Determinism: Seeded (reproducible)

Performance Summary

Breakdown by Component

Easy (Classification Only)

Category Accuracy: 100%
Reward: 1.0 if correct, 0.0 if wrong
Consistency: Very High

Medium (Priority & Urgency)

Category Accuracy: 100%
Priority Accuracy: 80%
Urgency Accuracy: 40%
Combined Score: 73%
Reward Range: 0.65-0.82

Hard (Full Triage)

Category Accuracy: 100%
Priority Accuracy: 80%
Department Accuracy: 60%
Recommendation Quality: 30%
Combined Score: 68%
Reward Range: 0.50-0.85

⚙️ Setup Instructions

Prerequisites

• —Python 3.8+
• —pip or conda
• —(Optional) OpenAI API key for baseline evaluation

Local Installation

# 1. Clone repository
cd scalar

# 2. Install dependencies
pip install -r requirements.txt

# 3. Validate installation
python validate.py
# Expected: ✅ OPENENV VALIDATION PASSED! (9/9 checks)

# 4. Run tests
python test_environment.py  
# Expected: ✅ ALL TESTS PASSED! (11/11 tests)

Docker Installation

# Build containerized environment
docker build -t customer-support-triage:latest .

# Validate in container
docker run --rm customer-support-triage:latest python validate.py

# Run tests in container
docker run --rm customer-support-triage:latest python test_environment.py

🚀 Usage Instructions

Quick Validation (30 seconds)

pip install -r requirements.txt
python validate.py

Output:

✅ OPENENV VALIDATION PASSED!
RESULTS: 9/9 checks passed

Run Unit Tests (10 seconds)

python test_environment.py

Output:

✅ ALL TESTS PASSED!
RESULTS: 11/11 tests passed

Run Baseline Evaluation (2-3 minutes)

export OPENAI_API_KEY="sk-your-api-key"
python baseline.py

Output:

EASY       | Avg Reward: 0.9800 | Success:   100.0% (5/5)
MEDIUM     | Avg Reward: 0.7240 | Success:    60.0% (3/5)
HARD       | Avg Reward: 0.6520 | Success:    40.0% (2/5)

Overall Average Reward: 0.7853
Results saved to baseline_results.json

Custom Usage in Python

from main import create_env, Action

# Create environment at desired difficulty
env = create_env(difficulty="medium")

# Reset to get a random ticket
obs, info = env.reset(seed=42)

print(f"Ticket: {obs.ticket_id}")
print(f"Customer: {obs.customer_name}")
print(f"Issue: {obs.issue_text}")
print(f"Sentiment: {obs.sentiment_score:.2f}")
print(f"Wait time: {obs.wait_time_hours:.1f} hours")
print(f"Escalated: {obs.is_escalated}")

# Submit your triage decision
action = Action(
    category="Bug",
    priority="High",
    urgency_days=1,
    department="Engineering",
    recommendation="Investigate authentication service for repeated login failures"
)

# Get feedback
obs, reward, done, truncated, info = env.step(action)

print(f"\nReward: {reward.value:.4f}")
print(f"Breakdown: {reward.breakdown}")
print(f"Episode done: {done}")

Iterate Over Multiple Episodes

from main import create_env, Action

env = create_env(difficulty="easy")

for episode in range(5):
    obs, info = env.reset(seed=episode)
    
    # Your agent's decision
    action = Action(category="Bug")
    
    # Step and collect reward
    obs, reward, done, truncated, info = env.step(action)
    
    print(f"Episode {episode + 1}: Reward = {reward.value:.4f}")

📋 File Overview

📚 Key Implementation Details

Reward Function

Total Reward = (Correctness × 0.7) + (Efficiency × 0.3)

Where:
- Correctness: How well decisions match optimal triage
- Efficiency: Task completion speed penalty factor

Deterministic Grading

Each component has programmatic graders:

• —grade_category() - Classification accuracy
• —grade_priority() - Priority appropriateness
• —grade_urgency() - Urgency timeline accuracy
• —grade_department() - Department routing accuracy
• —grade_recommendation() - Recommendation quality

Context-Aware Evaluation

Grading considers multiple factors:

• —Sentiment score: Negative sentiment → higher priority expected
• —Wait time: Longer wait → more urgent response needed
• —Escalation flag: Escalated → Management routing bonus
• —Issue type: Different expectations for Bug vs Feature

🐳 Docker & HuggingFace Spaces Deployment

Building and Running Locally

Build the Docker image:

docker build -t customer-support-triage:latest .

Run validation inside container:

docker run --rm customer-support-triage:latest python validate.py

Expected output: ✅ OPENENV VALIDATION PASSED! (9/9 checks)

Run tests inside container:

docker run --rm customer-support-triage:latest python test_environment.py

Run interactive baseline evaluation:

docker run --rm -e OPENAI_API_KEY=your-api-key customer-support-triage:latest python baseline.py

Deploying to HuggingFace Spaces

1. 1.Create a new Space on HuggingFace Spaces
2. 2.Select "Docker" as the runtime
3. 3.Clone your space repository

1. 1.Push repository with Dockerfile:

   git clone https://huggingface.co/spaces/username/your-space-name
   cd your-space-name
   cp Dockerfile .
   cp requirements.txt .
   cp main.py .
   cp baseline.py .
   cp validate.py .
   cp openenv.yaml .
   cp test_environment.py .
   cp .dockerignore .
   git add .
   git commit -m "Add OpenEnv environment"
   git push

1. 1.Space will automatically:
2. 2.Build the Docker image using the Dockerfile
3. 3.Start the environment with docker run
4. 4.Execute validation checks on startup
5. 5.Show logs in the Space interface

1. 1.Optional: Add API endpoint
2. 2.Replace CMD in Dockerfile with a simple Flask/FastAPI server
3. 3.Expose endpoint to interact with environment programmatically
4. 4.See comments in Dockerfile for customization options

Container Features

• —Multi-stage build: Optimized image size (builder + runtime stages)
• —Health checks: Verifies environment loads correctly every 30s
• —Non-root user: Security best practice (runs as appuser)
• —Metadata labels: Tagged for OpenEnv and HF Spaces integration
• —Deterministic execution: Seeds ensure reproducible results

✅ Compliance

• —✅ Full OpenEnv specification (Observation, Action, Reward typed models)
• —✅ Deterministic evaluation with reproducible seeds
• —✅ 3 progressive tasks with graders
• —✅ Meaningful reward function
• —✅ Docker containerization
• —✅ Baseline evaluation with GPT-4 Turbo
• —✅ 9/9 validation checks passing
• —✅ 11/11 unit tests passing

📄 License

This project is provided as-is for research and development purposes.