README.md

---
title: Customer Support AI API
emoji: 🤖
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---

# 🎮 AI Customer Support Simulator

A strict, deterministic RL-style environment for training and evaluating AI agents on customer support tasks.

## 🏗️ Architecture

```
├── models.py              # Core data models (Episode, StepResult, Task)
├── environment.py         # Strict step enforcement + fail logic
├── inference.py           # Rule-based agent + CLI runner
├── app.py                 # Gradio UI
├── tasks/
│   ├── easy_task.py       # Delayed delivery complaint
│   ├── medium_task.py     # Billing double-charge
│   └── hard_task.py       # Angry VIP threatening legal action
├── graders/
│   └── base_grader.py     # BaseGrader + HardTaskGrader
└── tests/
    └── test_cases.py      # 4 mandatory test scenarios
```

## 🎯 Step Flow

**Empathy → Collect Info → Investigate → Resolution**

Each step must be completed correctly before advancing.

## 📊 Reward Formula

```
reward = base_score + step_bonus − penalty
```

| Component     | Value  |
|---------------|--------|
| Base (correct)| 1.00   |
| Base (wrong)  | 0.20   |
| Step bonus    | 0.20   |
| Max per step  | **1.20** |
| Episode max   | **4.80** |

## ⚠️ Penalties

| Trigger                        | Penalty |
|-------------------------------|---------|
| Wrong action in step           | −0.30   |
| Repeated response              | −0.20   |
| Early solution                 | −0.25   |
| Angry customer ignored         | −0.25   |
| Generic / too-short response   | −0.15   |
| Wrong assumption               | −0.20   |
| Skipped step                   | −0.30   |

## 💥 Fail Conditions

- More than **3 wrong steps** across episode
- Total reward below **1.5**
- Agent stuck in loop: **3 consecutive failures** at same step
- Single-step penalty ≥ 0.80

## 🚀 Local Setup

```bash
pip install -r requirements.txt
python inference.py --task all --agent rule   # CLI test
python app.py                                  # Gradio UI
python tests/test_cases.py                    # Run tests
```