FastAPI OpenEnv server

Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+EXPOSE 7860
+CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "7860"]

api.py

@@ -0,0 +1,110 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from environment import CustomerSupportEnv
+
+app = FastAPI(title="Customer Support AI OpenEnv")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+_env = None
+
+
+class ResetRequest(BaseModel):
+    task: str = "easy"
+
+
+class StepRequest(BaseModel):
+    action: str
+
+
+def obs_to_dict(obs) -> dict:
+    step = obs.current_step
+    return {
+        "task_id": obs.task_id,
+        "task_description": obs.task_description,
+        "current_customer_message": obs.current_customer_message,
+        "current_step": {
+            "step_id": str(step.step_id),
+            "label": str(step.label),
+            "description": str(step.description),
+        },
+        "progress": obs.progress,
+        "step_number": int(obs.step_number),
+        "total_steps": int(obs.total_steps),
+        "max_steps": int(obs.max_steps),
+        "metadata": obs.metadata,
+        "conversation_history": obs.conversation_history,
+        "context_memory": obs.context_memory,
+        "steps_completed": list(obs.steps_completed),
+        "consecutive_failures": int(obs.consecutive_failures),
+        "episode_status": str(obs.episode_status),
+        "fail_conditions": list(obs.fail_conditions),
+    }
+
+
+@app.get("/")
+def root():
+    return {"status": "ok", "message": "Customer Support AI OpenEnv API"}
+
+
+@app.post("/reset")
+def reset_env(body: ResetRequest = None):
+    global _env
+    task = (body.task if body else "easy").lower()
+    if task not in ["easy", "medium", "hard"]:
+        task = "easy"
+    _env = CustomerSupportEnv(task=task)
+    obs = _env.reset()
+    return {"observation": obs_to_dict(obs)}
+
+
+@app.post("/step")
+def step_env(body: StepRequest):
+    global _env
+    if _env is None:
+        return {"error": "Call /reset first"}
+    result = _env.step(body.action)
+    info = result.info.copy()
+    return {
+        "observation": obs_to_dict(result.observation),
+        "reward": float(result.reward),
+        "done": bool(result.done),
+        "info": info,
+    }
+
+
+@app.get("/state")
+def get_state():
+    global _env
+    if _env is None:
+        return {"error": "Call /reset first"}
+    return _env.state()
+
+
+@app.get("/observation_space")
+def observation_space():
+    return {
+        "type": "Dict",
+        "fields": {
+            "task_id": "str",
+            "current_customer_message": "str",
+            "current_step": "StepInfo",
+            "progress": "str",
+            "episode_status": "str",
+        }
+    }
+
+
+@app.get("/action_space")
+def action_space():
+    return {
+        "type": "Text",
+        "description": "Agent free-text reply",
+        "min_words": 6,
+    }

environment.py

@@ -0,0 +1,239 @@
+"""
+environment.py — Strict RL-style Customer Support Environment
+Handles: step enforcement, repeat detection, fail conditions, reward calculation
+"""
+
+from __future__ import annotations
+import re
+from typing import List, Tuple, Optional
+
+from models import (
+    Episode, EpisodeStatus, StepName, StepResult,
+    DifficultyLevel, Task
+)
+from graders.base_grader import BaseGrader
+
+
+# ── Step order ────────────────────────────────────────────────────────────────
+STEP_ORDER = [
+    StepName.EMPATHY,
+    StepName.COLLECT_INFO,
+    StepName.INVESTIGATE,
+    StepName.RESOLUTION,
+]
+
+# ── Reward constants ───────────────────────────────────────────────────────────
+BASE_SCORE_CORRECT   = 1.0
+BASE_SCORE_INCORRECT = 0.2
+STEP_BONUS           = 0.2          # bonus when step is correct
+WRONG_STEP_PENALTY   = 0.3          # wrong action in correct step position
+REPEAT_PENALTY       = 0.2          # repeated question / response
+SKIP_STEP_PENALTY    = 0.3          # jumped ahead
+EARLY_SOLUTION_PENALTY = 0.25       # gave resolution before investigation
+EMOTION_IGNORE_PENALTY = 0.25       # angry customer → neutral / cold reply
+GENERIC_RESPONSE_PENALTY = 0.15     # "ok", "done", vague one-liners
+WRONG_ASSUMPTION_PENALTY = 0.2      # stated wrong facts
+LOOP_PENALTY         = 0.35         # agent stuck in loop (same step repeated 2+)
+
+# ── Overlap threshold for repeat detection ─────────────────────────────────────
+REPEAT_WORD_OVERLAP_MIN = 10        # words in common → flagged as repeat
+
+
+class CustomerSupportEnv:
+    """
+    Strict step-based RL environment for customer support training.
+    """
+
+    def __init__(self, task: Task, grader: BaseGrader):
+        self.task    = task
+        self.grader  = grader
+        self.episode = Episode(
+            task_id    = task.task_id,
+            difficulty = task.difficulty,
+        )
+        self._response_history: List[str] = []
+        self._step_index = 0           # which step we expect next
+        self._consecutive_wrong = 0    # wrong attempts at current step
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    def step(self, agent_response: str) -> Tuple[StepResult, bool]:
+        """
+        Process one agent response.
+        Returns (StepResult, done:bool).
+        """
+        if self.episode.status != EpisodeStatus.RUNNING:
+            raise RuntimeError("Episode is already finished.")
+
+        expected_step = STEP_ORDER[self._step_index]
+        result = self._evaluate(agent_response, expected_step)
+        self.episode.add_step(result)
+        self._response_history.append(agent_response.lower().strip())
+
+        done = False
+        if result.correct:
+            self._step_index        += 1
+            self._consecutive_wrong  = 0
+        else:
+            self._consecutive_wrong += 1
+
+        # Loop fail: 3 consecutive wrong attempts at the same step
+        if self._consecutive_wrong >= 3 and self.episode.status == EpisodeStatus.RUNNING:
+            self.episode.status    = EpisodeStatus.FAIL
+            self.episode.fail_reason = (
+                f"Agent stuck in loop at step '{expected_step.value}' "
+                f"({self._consecutive_wrong} consecutive failures)"
+            )
+
+        if self.episode.status != EpisodeStatus.RUNNING:
+            done = True
+        elif self._step_index >= len(STEP_ORDER):
+            done = True   # episode.add_step() already set SUCCESS/FAIL
+
+        return result, done
+
+    def reset(self) -> None:
+        self.episode = Episode(
+            task_id    = self.task.task_id,
+            difficulty = self.task.difficulty,
+        )
+        self._response_history  = []
+        self._step_index        = 0
+        self._consecutive_wrong = 0
+
+    def summary(self):
+        return self.episode.summary()
+
+    # ── Internal evaluation ────────────────────────────────────────────────────
+
+    def _evaluate(self, response: str, expected_step: StepName) -> StepResult:
+        penalties: List[str] = []
+        total_penalty        = 0.0
+
+        # 1. Grade the response against expected step
+        grader_result = self.grader.grade(
+            response      = response,
+            expected_step = expected_step,
+            task          = self.task,
+        )
+        correct        = grader_result["correct"]
+        base_score     = BASE_SCORE_CORRECT if correct else BASE_SCORE_INCORRECT
+        detected_action = grader_result.get("detected_action", "unknown")
+
+        # 2. Step bonus
+        step_bonus = STEP_BONUS if correct else 0.0
+
+        # 3. Wrong-step penalty
+        if not correct:
+            total_penalty += WRONG_STEP_PENALTY
+            penalties.append(
+                f"Wrong action detected ('{detected_action}' "
+                f"≠ '{expected_step.value}'): -{WRONG_STEP_PENALTY}"
+            )
+
+        # 4. Repeat detection
+        if self._is_repeated_response(response):
+            total_penalty += REPEAT_PENALTY
+            penalties.append(f"Repeated/duplicate response: -{REPEAT_PENALTY}")
+
+        # 5. Early solution penalty
+        if self._is_early_solution(response, expected_step):
+            total_penalty += EARLY_SOLUTION_PENALTY
+            penalties.append(f"Solution given too early: -{EARLY_SOLUTION_PENALTY}")
+
+        # 6. Emotion mismatch penalty
+        if self._is_emotion_mismatch(response):
+            total_penalty += EMOTION_IGNORE_PENALTY
+            penalties.append(
+                f"Angry customer ignored (no empathy/de-escalation): "
+                f"-{EMOTION_IGNORE_PENALTY}"
+            )
+
+        # 7. Generic / too-short response
+        if self._is_generic_response(response):
+            total_penalty += GENERIC_RESPONSE_PENALTY
+            penalties.append(f"Generic/too-short response: -{GENERIC_RESPONSE_PENALTY}")
+
+        # 8. Wrong assumption detection
+        wrong_assumption = grader_result.get("wrong_assumption", False)
+        if wrong_assumption:
+            total_penalty += WRONG_ASSUMPTION_PENALTY
+            penalties.append(f"Incorrect assumption stated: -{WRONG_ASSUMPTION_PENALTY}")
+
+        # 9. Skip-step penalty (grader signals this)
+        if grader_result.get("skipped_step", False):
+            total_penalty += SKIP_STEP_PENALTY
+            penalties.append(f"Step skipped: -{SKIP_STEP_PENALTY}")
+
+        # ── Reward formula ─────────────────────────────────────────────────────
+        reward = max(0.0, base_score + step_bonus - total_penalty)
+
+        # ── Fail trigger (individual step) ────────────────────────────────────
+        fail_triggered = False
+        fail_reason    = ""
+        if total_penalty >= 0.8:
+            fail_triggered = True
+            fail_reason    = f"Single step penalty exceeded threshold ({total_penalty:.2f})"
+
+        return StepResult(
+            step            = expected_step,
+            agent_response  = response,
+            detected_action = detected_action,
+            expected_action = expected_step.value,
+            correct         = correct,
+            base_score      = base_score,
+            step_bonus      = step_bonus,
+            penalty         = total_penalty,
+            penalty_reasons = penalties,
+            reward          = reward,
+            fail_triggered  = fail_triggered,
+            fail_reason     = fail_reason,
+        )
+
+    # ── Helper detectors ───────────────────────────────────────────────────────
+
+    def _is_repeated_response(self, response: str) -> bool:
+        if not self._response_history:
+            return False
+        words_new = set(response.lower().split())
+        for prev in self._response_history:
+            words_prev = set(prev.split())
+            overlap = len(words_new & words_prev)
+            if overlap >= REPEAT_WORD_OVERLAP_MIN:
+                return True
+        return False
+
+    def _is_early_solution(self, response: str, step: StepName) -> bool:
+        """Penalise giving resolution keywords before the resolution step."""
+        if step in (StepName.EMPATHY, StepName.COLLECT_INFO):
+            resolution_signals = [
+                "refund", "replacement", "we will fix", "we will credit",
+                "here is the solution", "the fix is", "escalate your",
+            ]
+            r = response.lower()
+            return any(sig in r for sig in resolution_signals)
+        return False
+
+    def _is_emotion_mismatch(self, response: str) -> bool:
+        """Flag cold/neutral replies when customer is angry/frustrated."""
+        if self.task.customer_emotion not in ("angry", "frustrated"):
+            return False
+        empathy_signals = [
+            "sorry", "apologize", "apology", "understand your frustration",
+            "i hear you", "i completely understand", "that must be",
+            "deeply sorry", "sincerely apologize",
+        ]
+        r = response.lower()
+        return not any(sig in r for sig in empathy_signals)
+
+    def _is_generic_response(self, response: str) -> bool:
+        stripped = response.strip().lower()
+        # Very short replies
+        if len(stripped.split()) <= 4:
+            return True
+        # Generic filler phrases
+        generic_phrases = [
+            "ok", "okay", "done", "sure", "got it",
+            "no problem", "understood", "alright",
+        ]
+        return stripped in generic_phrases

graders/__init__.py

@@ -0,0 +1,3 @@
+from graders.base_grader import BaseGrader, HardTaskGrader
+
+__all__ = ["BaseGrader", "HardTaskGrader"]

graders/base_grader.py

@@ -0,0 +1,238 @@
+"""
+graders/base_grader.py — Deterministic, rule-based grader
+Handles: step detection, edge cases, emotion mismatch, wrong assumptions
+"""
+
+from __future__ import annotations
+import re
+from typing import Dict, Any, List
+
+from models import StepName, Task
+
+
+# ── Keyword banks ──────────────────────────────────────────────────────────────
+
+EMPATHY_KEYWORDS = [
+    "sorry", "apologize", "apology", "understand", "frustrat",
+    "hear you", "feel", "concern", "inconvenien", "deeply sorry",
+    "sincerely", "personally sorry", "personally and deeply sorry",
+    "i take full", "full responsibility",
+]
+
+COLLECT_INFO_KEYWORDS = [
+    "order number", "order id", "account number", "could you provide",
+    "can you share", "what is your", "please confirm", "transaction id",
+    "booking reference", "invoice", "date of purchase", "when did",
+    "which product", "what happened", "could you tell me", "may i have",
+    "can i have your", "full name", "email address", "phone number",
+    # Additional strong collect-info signals
+    "could you please provide", "please provide", "provide me with",
+    "associated with your account", "your account", "look into this",
+    "look into further", "assist you further", "help me locate",
+    "need a few details", "need some information", "need your",
+    "retrieve your", "verify your", "pull up your", "access your",
+    "your email", "your order", "your reference", "your details",
+    "please share your", "share your", "to look into", "to assist you",
+    "to help you", "can you provide", "can you confirm", "can you give",
+    "i would need", "i will need", "so i can", "in order to",
+]
+
+INVESTIGATE_KEYWORDS = [
+    "checking", "looking into", "pulling up", "reviewing",
+    "investigating", "let me check", "i can see", "our records show",
+    "according to our system", "i have found", "i found", "found that",
+    "it appears", "it seems", "the issue", "root cause",
+]
+
+RESOLUTION_KEYWORDS = [
+    "refund", "replacement", "credit", "we will", "i will",
+    "here is what", "the solution", "fix this", "resolved",
+    "compensation", "escalate", "expedite", "waive", "reimburse",
+    "send a new", "process a", "arrange for", "free of charge",
+]
+
+# De-escalation signals required for hard tasks
+DEESCALATION_KEYWORDS = [
+    "i completely understand", "that is unacceptable", "i take full responsibility",
+    "this should not have happened", "you have every right",
+    "personally ensure", "highest priority", "immediate attention",
+    "personally and deeply sorry", "sincerely apologize",
+    "i hear your frustration", "deeply sorry for the experience",
+]
+
+# Wrong-assumption triggers (generic bad guesses)
+WRONG_ASSUMPTION_PHRASES = [
+    "you probably forgot", "you must have", "it is your fault",
+    "you should have", "clearly you", "obviously you",
+]
+
+# Generic / non-answer phrases
+GENERIC_FILLERS = [
+    "ok", "okay", "done", "sure", "got it", "understood",
+    "no problem", "alright", "i see", "noted",
+]
+
+
+class BaseGrader:
+    """
+    Deterministic grader.  Returns a dict with:
+      correct, detected_action, wrong_assumption, skipped_step, notes
+    """
+
+    def grade(
+        self,
+        response: str,
+        expected_step: StepName,
+        task: Task,
+    ) -> Dict[str, Any]:
+
+        r = response.lower().strip()
+        result: Dict[str, Any] = {
+            "correct":          False,
+            "detected_action":  "unknown",
+            "wrong_assumption": False,
+            "skipped_step":     False,
+            "notes":            [],
+        }
+
+        # ── Edge-case guard ────────────────────────────────────────────────────
+        if self._is_irrelevant(r):
+            result["detected_action"] = "irrelevant"
+            result["notes"].append("Response is irrelevant / generic filler.")
+            return result
+
+        # ── Detect what the agent actually did ─────────────────────────────────
+        detected = self._detect_action(r, task)
+        result["detected_action"] = detected
+
+        # ── Correctness check ──────────────────────────────────────────────────
+        result["correct"] = (detected == expected_step.value)
+
+        # ── Skip-step check ────────────────────────────────────────────────────
+        # e.g. agent jumps straight to RESOLUTION while expected EMPATHY
+        step_rank = {
+            StepName.EMPATHY:      0,
+            StepName.COLLECT_INFO: 1,
+            StepName.INVESTIGATE:  2,
+            StepName.RESOLUTION:   3,
+        }
+        detected_rank = self._action_to_rank(detected)
+        expected_rank = step_rank[expected_step]
+        if detected_rank > expected_rank + 0:
+            result["skipped_step"] = True
+            result["notes"].append(
+                f"Skipped step: expected '{expected_step.value}', "
+                f"agent jumped to '{detected}'."
+            )
+
+        # ── Wrong-assumption check ─────────────────────────────────────────────
+        if any(phrase in r for phrase in WRONG_ASSUMPTION_PHRASES):
+            result["wrong_assumption"] = True
+            result["notes"].append("Agent made a wrong assumption about the customer.")
+
+        # ── Hard-task: de-escalation required ─────────────────────────────────
+        if task.escalation_risk and expected_step == StepName.EMPATHY:
+            if not any(kw in r for kw in DEESCALATION_KEYWORDS):
+                result["correct"] = False
+                result["notes"].append(
+                    "Hard task requires de-escalation language; none detected."
+                )
+
+        return result
+
+    # ── Helpers ────────────────────────────────────────────────────────────────
+
+    def _detect_action(self, r: str, task: Task) -> str:
+        """Return the name of the step the response most resembles."""
+        scores = {
+            "empathy":      self._score_keywords(r, EMPATHY_KEYWORDS),
+            "collect_info": self._score_keywords(r, COLLECT_INFO_KEYWORDS),
+            "investigate":  self._score_keywords(r, INVESTIGATE_KEYWORDS),
+            "resolution":   self._score_keywords(r, RESOLUTION_KEYWORDS),
+        }
+        best = max(scores, key=scores.get)
+        if scores[best] == 0:
+            return "unknown"
+        return best
+
+    def _score_keywords(self, text: str, keywords: List[str]) -> int:
+        return sum(1 for kw in keywords if kw in text)
+
+    def _is_irrelevant(self, r: str) -> bool:
+        # Very short
+        if len(r.split()) <= 3:
+            return True
+        # Pure filler
+        if r in GENERIC_FILLERS:
+            return True
+        # No customer-support vocabulary at all
+        all_keywords = (
+            EMPATHY_KEYWORDS + COLLECT_INFO_KEYWORDS
+            + INVESTIGATE_KEYWORDS + RESOLUTION_KEYWORDS
+        )
+        return not any(kw in r for kw in all_keywords)
+
+    def _action_to_rank(self, action: str) -> int:
+        mapping = {
+            "empathy":      0,
+            "collect_info": 1,
+            "investigate":  2,
+            "resolution":   3,
+            "unknown":      -1,
+            "irrelevant":   -1,
+        }
+        return mapping.get(action, -1)
+
+
+# ── Hard-task specific grader ──────────────────────────────────────────────────
+
+class HardTaskGrader(BaseGrader):
+    """
+    Extended grader for the hard escalation scenario.
+    Adds: emotional control score, conflict handling, professional tone.
+    """
+
+    PROFESSIONAL_PHRASES = [
+        "i assure you", "rest assured", "our team will",
+        "i will personally", "i will escalate", "within 24 hours",
+        "we take this very seriously", "top priority",
+    ]
+
+    UNPROFESSIONAL_PHRASES = [
+        "calm down", "you need to", "stop complaining",
+        "it is not our fault", "nothing we can do", "policy says",
+    ]
+
+    def grade(
+        self,
+        response: str,
+        expected_step: StepName,
+        task: Task,
+    ) -> Dict[str, Any]:
+        result = super().grade(response, expected_step, task)
+        r      = response.lower()
+
+        notes = result["notes"]
+
+        # Emotional-control bonus / penalty
+        if any(kw in r for kw in self.PROFESSIONAL_PHRASES):
+            notes.append("✅ Professional / reassuring language detected.")
+        if any(kw in r for kw in self.UNPROFESSIONAL_PHRASES):
+            result["correct"]   = False
+            result["wrong_assumption"] = True
+            notes.append("❌ Unprofessional language detected (e.g. 'calm down').")
+
+        # Resolution accuracy: must offer concrete action on resolution step
+        if expected_step == StepName.RESOLUTION:
+            concrete = [
+                "refund", "replacement", "credit", "waive", "free",
+                "expedite", "send", "process", "arrange",
+            ]
+            if not any(c in r for c in concrete):
+                result["correct"] = False
+                notes.append(
+                    "❌ Resolution step requires a concrete action (refund/replacement/credit)."
+                )
+
+        result["notes"] = notes
+        return result

graders/easy_grader.py

@@ -0,0 +1,84 @@
+"""
+Easy Grader — Scores FAQ responses based on keyword coverage and tone.
+"""
+
+from typing import Tuple
+
+
+class EasyGrader:
+    """
+    Scoring logic for Easy (FAQ) Task.
+
+    Formula:
+        score = (keyword_matches / total_keywords) * tone_multiplier
+
+    Breakdown:
+        keyword_matches:  How many expected keywords appear in the agent's reply.
+        total_keywords:   Total number of expected keywords in the scenario.
+        tone_multiplier:  0.8 if tone is bad (rude/dismissive), 1.0 if neutral, 1.1 if polite.
+    """
+
+    # Polite/professional phrases boost score slightly
+    POLITE_PHRASES = [
+        "happy to help", "great question", "certainly", "of course",
+        "please", "thank you", "let me", "i'd be happy", "absolutely",
+        "sure", "glad", "assist", "help you",
+    ]
+
+    # Dismissive/rude phrases reduce score
+    BAD_PHRASES = [
+        "i don't know", "not sure", "no idea", "can't help",
+        "figure it out", "read the manual", "obvious",
+    ]
+
+    def grade(self, action: str, scenario: dict, history: list) -> Tuple[float, dict]:
+        """
+        Grade the agent's FAQ response.
+
+        Returns:
+            (score: float [0.0–1.0], grader_info: dict)
+        """
+        action_lower = action.lower()
+        keywords = scenario.get("correct_answer_keywords", [])
+
+        # 1. Keyword Coverage
+        matched = [kw for kw in keywords if kw.lower() in action_lower]
+        keyword_score = len(matched) / len(keywords) if keywords else 0.5
+
+        # 2. Tone Multiplier
+        has_polite = any(p in action_lower for p in self.POLITE_PHRASES)
+        has_bad = any(p in action_lower for p in self.BAD_PHRASES)
+
+        if has_bad:
+            tone_multiplier = 0.7
+            tone_label = "unprofessional"
+        elif has_polite:
+            tone_multiplier = 1.1
+            tone_label = "polite"
+        else:
+            tone_multiplier = 1.0
+            tone_label = "neutral"
+
+        # 3. Length check — too short = incomplete
+        word_count = len(action.split())
+        if word_count < 5:
+            length_penalty = 0.4   # very short answers likely incomplete
+        elif word_count < 10:
+            length_penalty = 0.85
+        else:
+            length_penalty = 1.0
+
+        # Final score (capped at 1.0)
+        score = min(1.0, keyword_score * tone_multiplier * length_penalty)
+
+        grader_info = {
+            "matched_keywords": matched,
+            "missing_keywords": [kw for kw in keywords if kw.lower() not in action_lower],
+            "keyword_score": round(keyword_score, 3),
+            "tone": tone_label,
+            "tone_multiplier": tone_multiplier,
+            "word_count": word_count,
+            "final_score": round(score, 3),
+        }
+
+        return round(score, 3), grader_info

graders/hard_grader.py

@@ -0,0 +1,156 @@
+"""
+Hard Grader - Scores emotional complaint handling.
+"""
+
+from typing import Tuple, Optional
+
+
+class HardGrader:
+
+    BEHAVIOR_KEYWORDS = {
+        "genuine_empathy": [
+            "i understand how", "i can only imagine", "that must be incredibly",
+            "i truly understand", "how frustrating", "how upsetting", "i hear you",
+            "i completely understand", "your feelings are valid", "that's terrible",
+            "i'm so sorry you're going through", "that sounds incredibly",
+        ],
+        "personal_apology": [
+            "i personally apologize", "i am deeply sorry", "i sincerely apologize",
+            "i'm truly sorry", "you deserve better", "this is unacceptable",
+            "we have failed you", "i take full responsibility",
+        ],
+        "take_ownership": [
+            "i will personally", "i'm taking ownership", "i'll make sure",
+            "i'll see this through", "let me personally", "i'll handle this myself",
+            "i'm going to fix", "i'll escalate this myself",
+        ],
+        "offer_compensation": [
+            "credit", "discount", "refund", "compensat", "free month",
+            "extend your subscription", "make this right", "as a gesture",
+            "offer you", "we'd like to offer",
+        ],
+        "provide_resolution": [
+            "fixed", "resolved", "escalated to", "engineering team",
+            "senior team", "within 24 hours", "immediately", "priority",
+            "restore", "recovery", "our team is working",
+        ],
+        "express_concern_for_health": [
+            "please see a doctor", "seek medical attention", "your health",
+            "medical professional", "health comes first", "please get checked",
+            "are you okay", "how are you feeling", "go to a doctor",
+        ],
+        "collect_product_info": [
+            "batch number", "product name", "order number", "lot number",
+            "when did you purchase", "which product", "can you provide",
+        ],
+        "escalate_to_safety_team": [
+            "safety team", "quality team", "investigating", "immediate investigation",
+            "food safety", "health and safety", "escalate to our", "report this",
+            "regulatory", "quality control",
+        ],
+        "investigate_data_loss": [
+            "engineering team", "data recovery", "backup logs", "investigate",
+            "technical team", "escalate immediately", "attempt to recover",
+            "our engineers", "priority investigation",
+        ],
+    }
+
+    VIOLATION_KEYWORDS = {
+        "robotic_response": [
+            "we apologize for the inconvenience",
+            "your feedback is important to us",
+            "we strive to provide",
+            "as per our policy",
+            "please note that",
+            "kindly be advised",
+        ],
+        "dismiss_emotion": [
+            "calm down", "theres no need to", "youre overreacting",
+            "this is normal", "happens to everyone",
+        ],
+        "blame_customer": [
+            "you should have", "if you had", "user error",
+            "thats your fault", "you didnt follow",
+        ],
+        "deny_fault": [
+            "not our fault", "we cant be held responsible",
+            "no evidence", "impossible that our product",
+        ],
+        "minimize_health_concern": [
+            "just a mild reaction", "probably not related",
+            "unlikely to be our product", "youre probably fine",
+        ],
+        "offer_no_compensation": [],
+        "downplay_data_loss": [
+            "just data", "its only files", "you should have backed up",
+            "not our responsibility for backups",
+        ],
+    }
+
+    GENERIC_INDICATORS = [
+        "dear valued customer",
+        "we take all complaints seriously",
+        "please contact us at",
+        "for further assistance",
+        "thank you for contacting",
+    ]
+
+    def grade(
+        self,
+        action: str,
+        scenario: dict,
+        history: list,
+        behaviors_demonstrated: list,
+        avoid_violations: list,
+    ) -> Tuple[float, dict, Optional[str], Optional[str]]:
+
+        action_lower = action.lower()
+        required_behaviors = scenario.get("required_behaviors", [])
+        avoid_behaviors = scenario.get("avoid_behaviors", [])
+
+        behavior_found = None
+        best_behavior_score = 0.0
+
+        for behavior in required_behaviors:
+            if behavior in behaviors_demonstrated:
+                continue
+            kw_list = self.BEHAVIOR_KEYWORDS.get(behavior, [])
+            matches = sum(1 for kw in kw_list if kw in action_lower)
+            if matches > 0:
+                ratio = matches / len(kw_list) if kw_list else 0
+                if ratio > best_behavior_score:
+                    best_behavior_score = ratio
+                    behavior_found = behavior
+
+        all_empathy_keywords = self.BEHAVIOR_KEYWORDS.get("genuine_empathy", [])
+        empathy_matches = sum(1 for kw in all_empathy_keywords if kw in action_lower)
+        empathy_score = min(1.3, 1.0 + (empathy_matches * 0.1))
+
+        is_generic = any(gi in action_lower for gi in self.GENERIC_INDICATORS)
+        personalization_mult = 0.7 if is_generic else 1.0
+
+        violation_found = None
+        for avoidance in avoid_behaviors:
+            if avoidance in avoid_violations:
+                continue
+            kw_list = self.VIOLATION_KEYWORDS.get(avoidance, [])
+            matches = sum(1 for kw in kw_list if kw in action_lower)
+            if matches > 0:
+                violation_found = avoidance
+                break
+
+        if behavior_found:
+            base = min(1.0, best_behavior_score * 1.5)
+            score = min(1.0, base * empathy_score * personalization_mult)
+        else:
+            score = 0.15 * empathy_score if empathy_matches > 0 else 0.05
+
+        grader_info = {
+            "behavior_found": behavior_found,
+            "behavior_match_score": round(best_behavior_score, 3),
+            "empathy_score": round(empathy_score, 3),
+            "personalization": "generic" if is_generic else "personalized",
+            "violation_found": violation_found,
+        }
+
+        return round(score, 3), grader_info, behavior_found, violation_found

graders/hard_grader.py

@@ -0,0 +1,161 @@
+"""
+Hard Grader — Scores emotional complaint handling.
+"""
+
+from typing import Tuple, Optional
+
+
+class HardGrader:
+
+    BEHAVIOR_KEYWORDS = {
+        "genuine_empathy": [
+            "i understand how", "i can only imagine", "that must be incredibly",
+            "i truly understand", "how frustrating", "how upsetting", "i hear you",
+            "i completely understand", "your feelings are valid", "that's terrible",
+            "i'm so sorry you're going through", "that sounds incredibly",
+        ],
+        "personal_apology": [
+            "i personally apologize", "i am deeply sorry", "i sincerely apologize",
+            "i'm truly sorry", "you deserve better", "this is unacceptable",
+            "we have failed you", "i take full responsibility",
+        ],
+        "take_ownership": [
+            "i will personally", "i'm taking ownership", "i'll make sure",
+            "i'll see this through", "let me personally", "i'll handle this myself",
+            "i'm going to fix", "i'll escalate this myself",
+        ],
+        "offer_compensation": [
+            "credit", "discount", "refund", "compensat", "free month",
+            "extend your subscription", "make this right", "as a gesture",
+            "offer you", "we'd like to offer",
+        ],
+        "provide_resolution": [
+            "fixed", "resolved", "escalated to", "engineering team",
+            "senior team", "within 24 hours", "immediately", "priority",
+            "restore", "recovery", "our team is working",
+        ],
+        "express_concern_for_health": [
+            "please see a doctor", "seek medical attention", "your health",
+            "medical professional", "health comes first", "please get checked",
+            "are you okay", "how are you feeling", "go to a doctor",
+        ],
+        "collect_product_info": [
+            "batch number", "product name", "order number", "lot number",
+            "when did you purchase", "which product", "can you provide",
+        ],
+        "escalate_to_safety_team": [
+            "safety team", "quality team", "investigating", "immediate investigation",
+            "food safety", "health and safety", "escalate to our", "report this",
+            "regulatory", "quality control",
+        ],
+        "investigate_data_loss": [
+            "engineering team", "data recovery", "backup logs", "investigate",
+            "technical team", "escalate immediately", "attempt to recover",
+            "our engineers", "priority investigation",
+        ],
+    }
+
+    VIOLATION_KEYWORDS = {
+        "robotic_response": [
+            "we apologize for the inconvenience",
+            "your feedback is important to us",
+            "we strive to provide",
+            "as per our policy",
+            "please note that",
+            "kindly be advised",
+        ],
+        "dismiss_emotion": [
+            "calm down", "there's no need to", "you're overreacting",
+            "this is normal", "happens to everyone",
+        ],
+        "blame_customer": [
+            "you should have", "if you had", "user error",
+            "that's your fault", "you didn't follow",
+        ],
+        "deny_fault": [
+            "not our fault", "we can't be held responsible",
+            "no evidence", "impossible that our product",
+        ],
+        "minimize_health_concern": [
+            "just a mild reaction", "probably not related",
+            "unlikely to be our product", "you're probably fine",
+        ],
+        "offer_no_compensation": [],
+        "downplay_data_loss": [
+            "just data", "it's only files", "you should have backed up",
+            "not our responsibility for backups",
+        ],
+    }
+
+    GENERIC_INDICATORS = [
+        "dear valued customer",
+        "we take all complaints seriously",
+        "please contact us at",
+        "for further assistance",
+        "thank you for contacting",
+    ]
+
+    def grade(
+        self,
+        action: str,
+        scenario: dict,
+        history: list,
+        behaviors_demonstrated: list,
+        avoid_violations: list,
+    ) -> Tuple[float, dict, Optional[str], Optional[str]]:
+
+        action_lower = action.lower()
+        required_behaviors = scenario.get("required_behaviors", [])
+        avoid_behaviors = scenario.get("avoid_behaviors", [])
+
+        # 1. Behavior Detection
+        behavior_found = None
+        best_behavior_score = 0.0
+
+        for behavior in required_behaviors:
+            if behavior in behaviors_demonstrated:
+                continue
+            kw_list = self.BEHAVIOR_KEYWORDS.get(behavior, [])
+            matches = sum(1 for kw in kw_list if kw in action_lower)
+            if matches > 0:
+                ratio = matches / len(kw_list) if kw_list else 0
+                if ratio > best_behavior_score:
+                    best_behavior_score = ratio
+                    behavior_found = behavior
+
+        # 2. Empathy Multiplier
+        all_empathy_keywords = self.BEHAVIOR_KEYWORDS.get("genuine_empathy", [])
+        empathy_matches = sum(1 for kw in all_empathy_keywords if kw in action_lower)
+        empathy_score = min(1.3, 1.0 + (empathy_matches * 0.1))
+
+        # 3. Personalization
+        is_generic = any(gi in action_lower for gi in self.GENERIC_INDICATORS)
+        personalization_mult = 0.7 if is_generic else 1.0
+
+        # 4. Violation Detection
+        violation_found = None
+        for avoidance in avoid_behaviors:
+            if avoidance in avoid_violations:
+                continue
+            kw_list = self.VIOLATION_KEYWORDS.get(avoidance, [])
+            matches = sum(1 for kw in kw_list if kw in action_lower)
+            if matches > 0:
+                violation_found = avoidance
+                break
+
+        # 5. Final Score
+        if behavior_found:
+            base = min(1.0, best_behavior_score * 1.5)
+            score = min(1.0, base * empathy_score * personalization_mult)
+        else:
+            score = 0.15 * empathy_score if empathy_matches > 0 else 0.05
+
+        grader_info = {
+            "behavior_found": behavior_found,
+            "behavior_match_score": round(best_behavior_score, 3),
+            "empathy_score": round(empathy_score, 3),
+            "personalization": "generic" if is_generic else "personalized",
+            "violation_found": violation_found,
+        }
+
+        return round(score, 3), grader_info, behavior_found, violation_found

graders/medium_grader.py

@@ -0,0 +1,118 @@
+"""
+Medium Grader — Scores multi-step issue resolution responses.
+"""
+
+from typing import Tuple, Optional
+
+
+class MediumGrader:
+    """
+    Scoring logic for Medium (Multi-Step) Task.
+
+    Formula:
+        score = step_detection_score * completeness_multiplier * tone_multiplier
+
+    Step Detection:
+        Each required step has associated keywords.
+        If the agent's reply matches those keywords → step is identified.
+
+    Completeness:
+        Partial answers (missing some required info for the step) get partial credit.
+
+    Tone:
+        Professional, empathetic tone adds a small bonus.
+    """
+
+    # Keywords that signal each step type
+    STEP_KEYWORDS = {
+        # Medium scenario step types → what words trigger them
+        "acknowledge_frustration":  ["understand", "frustrat", "sorry to hear", "apologize", "that must", "i can see"],
+        "acknowledge_issue":        ["understand", "sorry", "i can see", "must be", "apologize", "frustrat"],
+        "collect_account_info":     ["email", "account", "order number", "name", "id", "could you provide", "can i get", "please share"],
+        "collect_order_info":       ["order number", "order id", "reference", "can i get", "could you share"],
+        "investigate":              ["look into", "check", "investigate", "pull up", "look at", "review your account"],
+        "check_basic_steps":        ["browser", "cache", "clear", "try", "incognito", "different browser", "cookies"],
+        "offer_password_reset":     ["reset", "password", "link", "send you", "email you", "forgot password"],
+        "confirm_resolution":       ["resolved", "able to log", "working now", "fixed", "sorted", "everything ok", "is that working"],
+        "resolve_or_escalate":      ["refund", "credit", "resolve", "fix", "escalate", "team will", "processed"],
+        "apologize_sincerely":      ["sorry", "apologize", "sincerely apologize", "deeply sorry", "truly sorry"],
+        "confirm_item_details":     ["ordered", "confirm", "blue jacket", "correct item", "you ordered", "size"],
+        "arrange_replacement":      ["replacement", "send the correct", "return", "new", "reship", "express", "free return"],
+    }
+
+    POLITE_PHRASES = [
+        "happy to help", "certainly", "of course", "absolutely",
+        "please", "thank you", "glad", "i understand", "i appreciate",
+        "let me help", "my pleasure",
+    ]
+
+    BAD_PHRASES = [
+        "not my problem", "policy says", "can't do anything", "nothing i can do",
+        "you should have", "your fault", "read the faq",
+    ]
+
+    def grade(
+        self,
+        action: str,
+        scenario: dict,
+        history: list,
+        steps_completed: list,
+    ) -> Tuple[float, dict, Optional[str]]:
+        """
+        Grade the agent's response for a medium-task step.
+
+        Returns:
+            (score: float, grader_info: dict, step_identified: str or None)
+        """
+        action_lower = action.lower()
+        required_steps = scenario.get("required_steps", [])
+
+        # 1. Detect which step the agent is performing
+        step_identified = None
+        step_match_score = 0.0
+
+        for step in required_steps:
+            if step in steps_completed:
+                continue  # Already done, skip
+            step_keywords = self.STEP_KEYWORDS.get(step, [])
+            if not step_keywords:
+                continue
+            matches = sum(1 for kw in step_keywords if kw in action_lower)
+            match_ratio = matches / len(step_keywords)
+            if match_ratio > step_match_score and matches >= 1:
+                step_match_score = match_ratio
+                step_identified = step
+
+        # 2. Completeness score (how thoroughly the step is addressed)
+        completeness = min(1.0, step_match_score * 1.5) if step_identified else 0.3
+
+        # 3. Tone multiplier
+        has_polite = any(p in action_lower for p in self.POLITE_PHRASES)
+        has_bad = any(p in action_lower for p in self.BAD_PHRASES)
+
+        if has_bad:
+            tone_mult = 0.6
+            tone = "bad"
+        elif has_polite:
+            tone_mult = 1.1
+            tone = "polite"
+        else:
+            tone_mult = 1.0
+            tone = "neutral"
+
+        # Final score
+        if step_identified:
+            score = min(1.0, completeness * tone_mult)
+        else:
+            # No useful step found — partial score for being polite
+            score = 0.2 * tone_mult if has_polite else 0.1
+
+        grader_info = {
+            "step_identified": step_identified,
+            "step_match_score": round(step_match_score, 3),
+            "completeness": round(completeness, 3),
+            "tone": tone,
+            "already_done": steps_completed,
+        }
+
+        return round(score, 3), grader_info, step_identified

inference.py

@@ -0,0 +1,183 @@
+"""
+inference.py — Rule-based agent + CLI test runner
+Usage:
+    python inference.py --task easy   --agent rule
+    python inference.py --task medium --agent rule
+    python inference.py --task hard   --agent rule
+    python inference.py --task all    --agent rule
+"""
+
+import argparse
+import json
+from typing import List
+
+from models import StepName, DifficultyLevel
+from environment import CustomerSupportEnv
+from graders.base_grader import BaseGrader, HardTaskGrader
+from tasks import TASK_REGISTRY
+
+
+# ── Rule-based agent responses ─────────────────────────────────────────────────
+
+RULE_BASED_RESPONSES = {
+    "easy": [
+        # Step 1: Empathy
+        (
+            "I am truly sorry to hear that your laptop has not arrived yet. "
+            "I completely understand how frustrating and urgent this must be for you, "
+            "especially when you need it for work. Please allow me to help resolve this immediately."
+        ),
+        # Step 2: Collect Info
+        (
+            "To assist you as quickly as possible, could you please provide me with "
+            "your order number or order ID? Additionally, may I have your full name "
+            "and the email address associated with the order?"
+        ),
+        # Step 3: Investigate
+        (
+            "Thank you for that information. I am checking our system right now. "
+            "I found that order #ORD-8821 is currently tracked and it appears the package "
+            "is stuck at a sorting facility. Our records show the delay is due to a "
+            "logistical hold-up that we are actively investigating."
+        ),
+        # Step 4: Resolution
+        (
+            "I sincerely apologize for this unacceptable delay. I will personally "
+            "expedite your delivery and escalate this to our logistics partner immediately. "
+            "You will receive your laptop within 2 business days. As compensation, "
+            "I will also credit ₹500 to your account for the inconvenience caused."
+        ),
+    ],
+
+    "medium": [
+        # Step 1: Empathy
+        (
+            "I sincerely apologize for the double charge on your account. "
+            "I completely understand how upsetting and inconvenient this is. "
+            "This should never have happened and I take full responsibility. "
+            "I am going to resolve this for you right away."
+        ),
+        # Step 2: Collect Info
+        (
+            "To look into this immediately, may I please have your account number "
+            "or the email address linked to your subscription? "
+            "Could you also confirm the transaction dates and the card used for billing?"
+        ),
+        # Step 3: Investigate
+        (
+            "Thank you. I am reviewing your billing history right now. "
+            "I can see in our billing system that there was indeed a duplicate charge "
+            "on both the 1st and the 15th. It appears this was caused by a payment "
+            "gateway retry issue on our end. I found the duplicate transaction clearly."
+        ),
+        # Step 4: Resolution
+        (
+            "I sincerely apologize for this error. I will process a full refund of "
+            "$49.99 immediately. You should see this credited back to your card "
+            "within 3 to 5 business days. I am also escalating this to our billing "
+            "team to ensure this does not happen again. Thank you for your patience."
+        ),
+    ],
+
+    "hard": [
+        # Step 1: Empathy (de-escalation required)
+        (
+            "Mr. Mehta, I am personally and deeply sorry for what you have experienced. "
+            "This is completely unacceptable and you have every right to be angry. "
+            "I take full responsibility for the failure of our team to respond properly "
+            "over the past three weeks. This should not have happened, especially for a "
+            "valued VIP customer like yourself. I hear your frustration and I assure you "
+            "that I will personally ensure this is resolved today."
+        ),
+        # Step 2: Collect Info
+        (
+            "To immediately escalate this as our top priority, could you please confirm "
+            "your order number and VIP account details? I also need your email and "
+            "contact number so I can personally follow up with you today."
+        ),
+        # Step 3: Investigate
+        (
+            "Thank you, Mr. Mehta. I am reviewing your tickets right now. "
+            "I can see five tickets — all marked pending — with no technician dispatched. "
+            "I found that this is unacceptable internally. I have already escalated "
+            "this to our senior operations manager and our VIP support head. "
+            "Our records show the replacement unit is available and ready to ship."
+        ),
+        # Step 4: Resolution
+        (
+            "Mr. Mehta, here is what I am doing right now: "
+            "1) A replacement Premium Standing Desk Pro will be dispatched today with "
+            "priority delivery — you will receive it within 24 hours. "
+            "2) As per our VIP policy, I am authorizing a compensation of ₹9,000 "
+            "(20% of your order value) credited to your account immediately. "
+            "3) I will personally ensure a senior technician contacts you within 2 hours. "
+            "4) I am waiving your next month's subscription fee as an additional apology. "
+            "I personally guarantee this will be resolved to your satisfaction today."
+        ),
+    ],
+}
+
+
+# ── Runner ─────────────────────────────────────────────────────────────────────
+
+def run_task(task_name: str) -> dict:
+    task    = TASK_REGISTRY[task_name]
+    grader  = HardTaskGrader() if task_name == "hard" else BaseGrader()
+    env     = CustomerSupportEnv(task=task, grader=grader)
+    responses = RULE_BASED_RESPONSES[task_name]
+
+    print(f"\n{'='*60}")
+    print(f"  TASK: {task_name.upper()}  |  {task.task_id}")
+    print(f"  Customer emotion: {task.customer_emotion}")
+    print(f"{'='*60}")
+    print(f"  Customer: {task.customer_message[:120]}...")
+    print(f"{'='*60}\n")
+
+    for i, response in enumerate(responses):
+        step_name = list(StepName)[i]
+        result, done = env.step(response)
+
+        status = "✅ CORRECT" if result.correct else "❌ WRONG"
+        print(f"[Step {i+1}/4] {step_name.value.upper()} — {status}")
+        print(f"  Detected : {result.detected_action}")
+        print(f"  Reward   : {result.reward:.3f}  "
+              f"(base={result.base_score:.2f}, bonus={result.step_bonus:.2f}, "
+              f"penalty={result.penalty:.2f})")
+        if result.penalty_reasons:
+            for pr in result.penalty_reasons:
+                print(f"  ⚠ {pr}")
+        print()
+
+        if done:
+            break
+
+    summary = env.summary()
+    print(f"\n{'='*60}")
+    print(f"  EPISODE STATUS  : {summary['status'].upper()}")
+    print(f"  TOTAL REWARD    : {summary['total_reward']:.3f} / 4.8 max")
+    print(f"  WRONG STEPS     : {summary['wrong_steps']}")
+    if summary["fail_reason"]:
+        print(f"  FAIL REASON     : {summary['fail_reason']}")
+    print(f"{'='*60}\n")
+
+    return summary
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--task",  choices=["easy", "medium", "hard", "all"],
+                        default="all")
+    parser.add_argument("--agent", choices=["rule"], default="rule")
+    args = parser.parse_args()
+
+    tasks = ["easy", "medium", "hard"] if args.task == "all" else [args.task]
+    results = {}
+    for t in tasks:
+        results[t] = run_task(t)
+
+    print("\n📊 FINAL SUMMARY")
+    print(json.dumps(results, indent=2))
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,125 @@
+"""
+models.py — Core data models for AI Customer Support Simulator
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+from enum import Enum
+
+
+class StepName(str, Enum):
+    EMPATHY       = "empathy"
+    COLLECT_INFO  = "collect_info"
+    INVESTIGATE   = "investigate"
+    RESOLUTION    = "resolution"
+
+
+class DifficultyLevel(str, Enum):
+    EASY   = "easy"
+    MEDIUM = "medium"
+    HARD   = "hard"
+
+
+class EpisodeStatus(str, Enum):
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAIL    = "fail"
+
+
+@dataclass
+class StepResult:
+    step: StepName
+    agent_response: str
+    detected_action: str          # what grader detected
+    expected_action: str          # what was required
+    correct: bool
+    base_score: float             # 0.0 – 1.0
+    step_bonus: float             # 0.0 – 0.2
+    penalty: float                # 0.0+ (subtracted)
+    penalty_reasons: List[str]
+    reward: float                 # base_score + step_bonus - penalty
+    fail_triggered: bool = False
+    fail_reason: str = ""
+
+
+@dataclass
+class Episode:
+    task_id: str
+    difficulty: DifficultyLevel
+    steps: List[StepResult] = field(default_factory=list)
+    total_reward: float = 0.0
+    wrong_step_count: int = 0
+    status: EpisodeStatus = EpisodeStatus.RUNNING
+    fail_reason: str = ""
+
+    # Thresholds
+    MAX_WRONG_STEPS: int = 3
+    MIN_TOTAL_REWARD: float = 1.5   # out of 4.0 max
+
+    def add_step(self, result: StepResult) -> None:
+        self.steps.append(result)
+        self.total_reward += result.reward
+        if not result.correct:
+            self.wrong_step_count += 1
+        self._check_fail_conditions(result)
+
+    def _check_fail_conditions(self, result: StepResult) -> None:
+        if self.status != EpisodeStatus.RUNNING:
+            return
+
+        # Too many wrong steps
+        if self.wrong_step_count >= self.MAX_WRONG_STEPS:
+            self.status    = EpisodeStatus.FAIL
+            self.fail_reason = f"Too many wrong steps ({self.wrong_step_count}/{self.MAX_WRONG_STEPS})"
+            return
+
+        # Step-level fail
+        if result.fail_triggered:
+            self.status    = EpisodeStatus.FAIL
+            self.fail_reason = result.fail_reason
+            return
+
+        # All 4 steps done — check total score
+        if len(self.steps) == 4:
+            if self.total_reward < self.MIN_TOTAL_REWARD:
+                self.status    = EpisodeStatus.FAIL
+                self.fail_reason = (
+                    f"Total reward {self.total_reward:.2f} below threshold "
+                    f"{self.MIN_TOTAL_REWARD}"
+                )
+            else:
+                self.status = EpisodeStatus.SUCCESS
+
+    def summary(self) -> Dict[str, Any]:
+        return {
+            "task_id":         self.task_id,
+            "difficulty":      self.difficulty.value,
+            "status":          self.status.value,
+            "total_reward":    round(self.total_reward, 3),
+            "wrong_steps":     self.wrong_step_count,
+            "fail_reason":     self.fail_reason,
+            "steps": [
+                {
+                    "step":            s.step.value,
+                    "correct":         s.correct,
+                    "base_score":      round(s.base_score, 3),
+                    "step_bonus":      round(s.step_bonus, 3),
+                    "penalty":         round(s.penalty, 3),
+                    "reward":          round(s.reward, 3),
+                    "penalty_reasons": s.penalty_reasons,
+                }
+                for s in self.steps
+            ],
+        }
+
+
+@dataclass
+class Task:
+    task_id: str
+    difficulty: DifficultyLevel
+    customer_message: str
+    scenario_context: str
+    required_steps: List[StepName]
+    step_keywords: Dict[StepName, List[str]]   # keywords that prove step done
+    escalation_risk: bool = False               # hard tasks only
+    customer_emotion: str = "neutral"          # neutral | frustrated | angry

requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.100.0
+uvicorn>=0.23.0
+groq>=0.4.0
+pyyaml>=6.0
+pydantic>=2.0.0

tasks/ medium_task.py

@@ -0,0 +1,160 @@
+"""
+MEDIUM TASK — Multi-Step Issue Resolution
+Goal: Agent guides a customer through a multi-turn troubleshooting process.
+"""
+
+import random
+from graders.medium_grader import MediumGrader
+
+
+class MediumTask:
+    """
+    Task: Resolve a customer's technical/account issue over multiple turns.
+
+    - 3–5 turn conversations.
+    - Agent must ask clarifying questions, diagnose the problem, and resolve it.
+    - Resolution requires following a correct sequence of steps.
+    - Rewarded for each correct step, penalized for skipping or wrong order.
+    """
+
+    description = (
+        "Help the customer resolve their issue step-by-step. "
+        "Ask clarifying questions, diagnose the problem, and guide them to a resolution. "
+        "Complete all required steps in a logical order."
+    )
+    max_steps = 6
+
+    SCENARIOS = [
+        {
+            "id": "med_001",
+            "topic": "billing_issue",
+            "opening_message": "I was charged twice for my subscription this month. This is really frustrating!",
+            "required_steps": [
+                "acknowledge_frustration",   # "I understand, I'm sorry to hear that..."
+                "collect_account_info",      # "Could I get your account email/ID?"
+                "investigate",               # "Let me look into this for you..."
+                "resolve_or_escalate",       # "I've initiated a refund..." or "escalating..."
+            ],
+            "resolution": "Issue a full refund for the duplicate charge and confirm via email.",
+            "metadata": {
+                "product": "Subscription Service",
+                "account_id": "ACC-88321",
+                "charge_amount": "$29.99",
+                "charge_date": "March 28, 2026",
+            },
+            # Simulated customer replies for each agent step
+            "customer_replies": {
+                "acknowledge_frustration": "Thank you for understanding. Yes, I need this fixed.",
+                "collect_account_info": "Sure, my email is user@example.com.",
+                "investigate": "Okay, please check it. I can see two charges on my bank statement.",
+                "resolve_or_escalate": "Great, thank you! When will the refund appear?",
+            },
+        },
+        {
+            "id": "med_002",
+            "topic": "login_problem",
+            "opening_message": "I can't log into my account. It keeps saying my password is wrong but I haven't changed it.",
+            "required_steps": [
+                "acknowledge_issue",
+                "check_basic_steps",     # "Have you tried clearing your browser cache?"
+                "offer_password_reset",  # "Let me send you a password reset link."
+                "confirm_resolution",    # "Were you able to log in successfully?"
+            ],
+            "resolution": "Send password reset link and confirm the customer successfully logged in.",
+            "metadata": {
+                "product": "SaaS App",
+                "account_status": "Active",
+                "last_login": "3 days ago",
+            },
+            "customer_replies": {
+                "acknowledge_issue": "Yes, I've been trying for an hour!",
+                "check_basic_steps": "I tried that, it didn't work.",
+                "offer_password_reset": "Okay, I got the email. Let me try.",
+                "confirm_resolution": "Yes! I'm in now. Thank you so much!",
+            },
+        },
+        {
+            "id": "med_003",
+            "topic": "wrong_item_shipped",
+            "opening_message": "I ordered a blue jacket (size M) but received a red one in size L. What do I do?",
+            "required_steps": [
+                "apologize_sincerely",
+                "collect_order_info",     # "Could I get your order number?"
+                "confirm_item_details",   # "Let me confirm what you ordered..."
+                "arrange_replacement",    # "I'll arrange a free return and send the correct item."
+            ],
+            "resolution": "Arrange free return and ship correct item with express delivery.",
+            "metadata": {
+                "product": "Online Clothing Store",
+                "order_id": "ORD-44512",
+                "ordered_item": "Blue Jacket Size M",
+                "received_item": "Red Jacket Size L",
+            },
+            "customer_replies": {
+                "apologize_sincerely": "Thank you, I hope you can fix this.",
+                "collect_order_info": "My order number is ORD-44512.",
+                "confirm_item_details": "Yes, that's correct, I ordered the blue one.",
+                "arrange_replacement": "That's great, when will the correct one arrive?",
+            },
+        },
+    ]
+
+    def __init__(self):
+        self._grader = MediumGrader()
+        self._current_scenario = None
+        self._steps_completed = []
+
+    def reset(self) -> dict:
+        self._steps_completed = []
+        self._current_scenario = random.choice(self.SCENARIOS).copy()
+        return self._current_scenario
+
+    def step(self, action: str, scenario: dict, history: list, step_number: int) -> dict:
+        score, grader_info, step_identified = self._grader.grade(
+            action=action,
+            scenario=scenario,
+            history=history,
+            steps_completed=self._steps_completed,
+        )
+
+        # Track completed steps
+        if step_identified and step_identified not in self._steps_completed:
+            self._steps_completed.append(step_identified)
+
+        required = scenario["required_steps"]
+        completed_count = len(self._steps_completed)
+        total_required = len(required)
+
+        # Reward formula:
+        # Each correctly completed step earns proportional reward.
+        # Final step earns a bonus. Missing steps or wrong answers penalize.
+        if step_identified in required and step_identified not in grader_info.get("already_done", []):
+            step_reward = (1.0 / total_required) * score    # partial step reward
+        else:
+            step_reward = -0.1 * (1 - score)                # small penalty for non-progress
+
+        # Check if all required steps are done
+        all_done = all(s in self._steps_completed for s in required)
+        done = all_done or step_number >= self.max_steps
+
+        if all_done:
+            step_reward += 0.2   # bonus for completing all steps
+
+        # Generate next customer message based on what step was just done
+        next_msg = ""
+        if not done:
+            replies = scenario.get("customer_replies", {})
+            next_msg = replies.get(step_identified, "Okay, what should I do next?")
+
+        return {
+            "reward": max(-1.0, min(1.0, step_reward)),
+            "done": done,
+            "next_customer_message": next_msg,
+            "grader_info": {
+                **grader_info,
+                "score": score,
+                "step_identified": step_identified,
+                "steps_completed": list(self._steps_completed),
+                "progress": f"{completed_count}/{total_required}",
+            },
+        }

tasks/__init__.py

@@ -0,0 +1,12 @@
+from tasks.easy_task   import EASY_TASK
+from tasks.medium_task import MEDIUM_TASK
+from tasks.hard_task   import HARD_TASK, evaluate_hard_response
+
+TASK_REGISTRY = {
+    "easy":   EASY_TASK,
+    "medium": MEDIUM_TASK,
+    "hard":   HARD_TASK,
+}
+
+__all__ = ["EASY_TASK", "MEDIUM_TASK", "HARD_TASK",
+           "TASK_REGISTRY", "evaluate_hard_response"]

tasks/easy_task.py

@@ -0,0 +1,36 @@
+"""
+tasks/easy_task.py — Easy scenario: delayed delivery complaint
+"""
+
+from models import Task, StepName, DifficultyLevel
+
+EASY_TASK = Task(
+    task_id           = "EASY_001",
+    difficulty        = DifficultyLevel.EASY,
+    customer_emotion  = "frustrated",
+    escalation_risk   = False,
+    customer_message  = (
+        "Hello, I ordered a laptop 10 days ago and it still hasn't arrived. "
+        "I need it urgently for work. Can you help me?"
+    ),
+    scenario_context  = (
+        "Customer placed order #ORD-8821 on 25 March. "
+        "Standard delivery is 5–7 business days. "
+        "Tracking shows package is stuck at a sorting facility."
+    ),
+    required_steps    = [
+        StepName.EMPATHY,
+        StepName.COLLECT_INFO,
+        StepName.INVESTIGATE,
+        StepName.RESOLUTION,
+    ],
+    step_keywords     = {
+        StepName.EMPATHY:      ["sorry", "apologize", "understand", "frustrat"],
+        StepName.COLLECT_INFO: ["order number", "order id", "could you provide",
+                                "may i have", "can i have"],
+        StepName.INVESTIGATE:  ["checking", "looking into", "tracking", "found",
+                                "our records", "it appears"],
+        StepName.RESOLUTION:   ["refund", "replacement", "expedite", "credit",
+                                "we will", "i will"],
+    },
+)

tasks/hard_task.py

@@ -0,0 +1,120 @@
+"""
+tasks/hard_task.py — Hard scenario: angry VIP customer threatening legal action
+                      after a 3-week unresolved product failure
+
+Grader used: HardTaskGrader (requires de-escalation + concrete resolution)
+"""
+
+from models import Task, StepName, DifficultyLevel
+
+HARD_TASK = Task(
+    task_id           = "HARD_001",
+    difficulty        = DifficultyLevel.HARD,
+    customer_emotion  = "angry",
+    escalation_risk   = True,
+    customer_message  = (
+        "I am ABSOLUTELY FURIOUS. I purchased your premium standing desk "
+        "(₹45,000) three weeks ago and it arrived broken. I've called five times, "
+        "sent four emails, and NOBODY has fixed this. I'm a VIP member and this "
+        "is how you treat me?! I am going to post this on every review site, "
+        "contact consumer court, and make sure everyone knows how pathetic your "
+        "company's service is. I want this resolved TODAY or I'm cancelling my "
+        "entire ₹2 lakh annual contract!"
+    ),
+    scenario_context  = (
+        "Customer: Rajesh Mehta | VIP Tier | Annual contract: ₹2,00,000. "
+        "Order #ORD-VIP-2241 — Premium Standing Desk Pro (₹45,000) delivered "
+        "on 12 March with a broken motorised lift mechanism. "
+        "5 prior support tickets (TKT-001 to TKT-005) — all marked 'pending'. "
+        "No technician dispatched yet. Replacement stock available (3–5 days). "
+        "Policy: VIP customers get same-day escalation + compensation up to 20% "
+        "of order value for delays > 7 days."
+    ),
+    required_steps    = [
+        StepName.EMPATHY,
+        StepName.COLLECT_INFO,
+        StepName.INVESTIGATE,
+        StepName.RESOLUTION,
+    ],
+    step_keywords     = {
+        StepName.EMPATHY: [
+            "i am personally and deeply sorry",
+            "deeply sorry",
+            "sincerely apologize",
+            "i completely understand",
+            "that is completely unacceptable",
+            "you have every right",
+            "i take full responsibility",
+            "this should not have happened",
+            "i hear your frustration",
+        ],
+        StepName.COLLECT_INFO: [
+            "order number", "ticket number", "vip", "account",
+            "could you confirm", "full name", "email", "contact",
+        ],
+        StepName.INVESTIGATE: [
+            "reviewing your tickets", "i can see", "five tickets",
+            "all marked pending", "this is unacceptable internally",
+            "i have escalated", "our records show", "found that",
+            "i found", "looking into",
+        ],
+        StepName.RESOLUTION: [
+            "replacement", "technician today", "within 24 hours",
+            "₹9,000", "9000", "20%", "compensation",
+            "personally ensure", "i will personally",
+            "waive", "free of charge", "priority",
+        ],
+    },
+)
+
+
+# ── Hard-task specific scoring weights ────────────────────────────────────────
+HARD_TASK_SCORING = {
+    "emotional_control":   0.30,   # calm + empathetic tone
+    "conflict_handling":   0.25,   # de-escalation phrases
+    "professional_tone":   0.20,   # no blame, no dismissal
+    "resolution_accuracy": 0.25,   # correct refund % + timeline
+}
+
+
+def evaluate_hard_response(response: str, step: StepName) -> dict:
+    """
+    Returns a breakdown dict for hard-task evaluation display.
+    Used by the UI to show per-dimension scores.
+    """
+    r      = response.lower()
+    scores = {}
+
+    if step == StepName.EMPATHY:
+        emotional_hits = sum(1 for kw in HARD_TASK.step_keywords[StepName.EMPATHY]
+                             if kw in r)
+        scores["emotional_control"] = min(1.0, emotional_hits / 3)
+
+        deesc = ["completely understand", "every right", "full responsibility",
+                 "should not have happened", "hear your frustration"]
+        deesc_hits = sum(1 for kw in deesc if kw in r)
+        scores["conflict_handling"] = min(1.0, deesc_hits / 2)
+
+        bad = ["calm down", "your fault", "nothing we can do", "policy says"]
+        scores["professional_tone"] = 0.0 if any(b in r for b in bad) else 1.0
+
+        scores["resolution_accuracy"] = 0.0   # N/A at empathy step
+
+    elif step == StepName.RESOLUTION:
+        scores["emotional_control"]   = 1.0 if "personally ensure" in r else 0.5
+        scores["conflict_handling"]   = 1.0 if "priority" in r else 0.5
+        scores["professional_tone"]   = 1.0 if "i will personally" in r else 0.5
+
+        # Check resolution accuracy: compensation + timeline
+        has_comp     = any(c in r for c in ["9,000", "9000", "20%", "compensation"])
+        has_timeline = any(t in r for t in ["24 hours", "today", "tomorrow", "3 days"])
+        scores["resolution_accuracy"] = (0.5 * int(has_comp)) + (0.5 * int(has_timeline))
+
+    else:
+        # Default neutral for mid steps
+        scores = {k: 0.5 for k in HARD_TASK_SCORING}
+
+    weighted = sum(HARD_TASK_SCORING[k] * scores.get(k, 0.0)
+                   for k in HARD_TASK_SCORING)
+    scores["weighted_total"] = round(weighted, 3)
+    return scores

tasks/medium_task.py

@@ -0,0 +1,39 @@
+"""
+tasks/medium_task.py — Medium scenario: billing error + overcharge
+"""
+
+from models import Task, StepName, DifficultyLevel
+
+MEDIUM_TASK = Task(
+    task_id           = "MEDIUM_001",
+    difficulty        = DifficultyLevel.MEDIUM,
+    customer_emotion  = "frustrated",
+    escalation_risk   = False,
+    customer_message  = (
+        "I've been charged twice for my subscription this month — "
+        "$49.99 appeared on my card on both the 1st and the 15th. "
+        "This is completely unacceptable. I want my money back!"
+    ),
+    scenario_context  = (
+        "Customer account: ACC-4492. "
+        "Subscription plan: Pro Monthly ($49.99/month). "
+        "Billing system shows a duplicate charge due to a payment gateway retry bug on the 15th. "
+        "Policy: full refund issued within 3–5 business days for duplicate charges."
+    ),
+    required_steps    = [
+        StepName.EMPATHY,
+        StepName.COLLECT_INFO,
+        StepName.INVESTIGATE,
+        StepName.RESOLUTION,
+    ],
+    step_keywords     = {
+        StepName.EMPATHY:      ["sorry", "apologize", "understand", "frustrat",
+                                "unacceptable", "inconvenien"],
+        StepName.COLLECT_INFO: ["account number", "email", "could you confirm",
+                                "transaction", "billing date", "card", "may i"],
+        StepName.INVESTIGATE:  ["checking", "i can see", "our records", "duplicate",
+                                "found", "it appears", "billing system"],
+        StepName.RESOLUTION:   ["refund", "credit", "3 to 5", "3-5", "business days",
+                                "we will process", "i will process", "reimburse"],
+    },
+)