Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY . /app
+RUN pip install --no-cache-dir --upgrade pip && pip install --no-cache-dir -r /app/requirements.txt
+
+EXPOSE 8000
+
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["python", "-m", "supportdesk_env.server.app"]

README.md

@@ -1,10 +1,254 @@
----
-title: HyperBrickCaseOps
-emoji: 🚀
-colorFrom: indigo
-colorTo: green
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: SupportDesk OpenEnv Environment
+sdk: docker
+app_port: 8000
+tags:
+  - openenv
+  - reinforcement-learning
+  - customer-support
+base_path: /web
+---
+
+# SupportDesk OpenEnv Environment
+
+SupportDesk is best thought of as an enterprise operations-desk environment, not a generic support classifier.
+
+SupportDesk is a real-world RL environment for enterprise support operations. The agent receives a realistic inbound ticket, a small internal knowledge base, and the live case state. It must route the case, set the right priority, decide whether to request more information, draft the customer response, add an internal note, and submit the case with the correct final status.
+
+This environment is intentionally built around work humans actually do every day in B2B SaaS support queues. It is not a toy chat task and it is not a game. The environment includes enterprise mechanics such as SLA countdowns, business-impact context, and distracting secondary concerns, so the agent has to prioritize the primary operational issue instead of just pattern-matching keywords.
+
+## Environment Description and Motivation
+
+The goal of this environment is to model a real operational gap in agent evaluation: many support benchmarks only test whether a model can produce a plausible reply, but real support work also requires correct routing, escalation, information gathering, and final disposition decisions. SupportDesk is designed to evaluate whether an agent can handle enterprise support operations end to end rather than just generate support-sounding text.
+
+This makes the environment useful for both:
+
+- training agents to improve multi-step support operations behavior
+- evaluating whether an agent can make safe and business-correct support decisions under pressure
+
+## Why this should score well
+
+- Real-world utility: customer support triage is a real production workflow with immediate evaluation value.
+- Deterministic grading: every task has an explicit gold queue, priority, issue type, required follow-up fields, reply markers, note markers, status, and resolution code.
+- Dense rewards: each step gets rewarded from the delta in the deterministic grader, which gives partial progress rather than only a binary terminal signal.
+- Reproducible baseline: `inference.py` runs all tasks in a fixed order and falls back to a deterministic heuristic policy if model credentials are unavailable.
+- Novel mechanics: observations expose SLA pressure, business impact, and secondary concerns, which makes the environment closer to an enterprise operations desk than a plain support classifier.
+
+## Why this is more novel than a standard support benchmark
+
+- It is not just routing or intent classification. The agent has to combine queueing, urgency, customer communication, internal notes, and final disposition in one trajectory.
+- It models primary-vs-secondary issue prioritization. The hardest task includes a tempting compliance side-question that should not override the live outage.
+- It encodes enterprise pressure directly in the observation through SLA countdowns, affected-user counts, and business-impact context.
+- It evaluates operational judgment, not just answer quality. A polished reply with the wrong queue, wrong escalation choice, or premature resolution still scores poorly.
+- It is built specifically for OpenEnv-style agent learning and evaluation, where the same environment can be used for baseline runs, external agents, and RL experiments.
+
+## Action Space
+
+Each `step()` takes a typed `SupportDeskAction` with:
+
+- `operation`: one of `classify`, `request_info`, `draft_reply`, `add_internal_note`, `submit`
+- `queue`
+- `priority`
+- `issue_type`
+- `status`
+- `resolution_code`
+- `requested_fields`
+- `reply`
+- `internal_note`
+
+The environment allows the agent to update multiple fields in one structured action, which keeps the workflow realistic and helps training.
+
+## Observation Space
+
+Each observation contains:
+
+- `task_id`, `difficulty`, and the agent objective
+- the inbound `ticket`
+- ticket-level urgency metadata such as `affected_users`, `sla_minutes_remaining`, `business_impact`, and `secondary_concerns`
+- `knowledge_base` policy snippets
+- allowed queues, priorities, statuses, and issue types
+- the mutable `case` snapshot
+- `action_history`
+- `feedback`
+- `remaining_steps`
+- the standard OpenEnv `reward` and `done`
+
+## OpenEnv Interface
+
+The environment implements the standard OpenEnv API:
+
+- `reset()` returns the initial typed observation for a new case
+- `step(action)` returns the next typed observation together with reward and done status
+- `state()` returns the current typed environment state
+- `openenv.yaml` provides environment metadata used by validators and deployment tooling
+
+The implementation uses typed Pydantic models for action, observation, and state.
+
+## Task Descriptions with Expected Difficulty
+
+1. `billing_refund_easy` — Expected difficulty: easy
+   Duplicate-charge billing ticket. The correct path is immediate billing routing, a refund confirmation, and case resolution.
+2. `account_takeover_medium` — Expected difficulty: medium
+   Suspicious-login security ticket. The agent must escalate to trust and safety, request verification details, and keep the case waiting on the customer.
+3. `api_incident_hard` — Expected difficulty: hard
+   Enterprise production API incident with a distracting compliance mention. The agent must escalate to platform engineering, request the right diagnostics, and open the incident instead of resolving it.
+
+What makes these tasks less generic than ordinary support-routing demos:
+
+- They mix queueing, priority, customer communication, internal note-taking, and close-vs-escalate decisions in one trajectory.
+- They include operational context like customer tier, affected-user count, SLA pressure, and business impact.
+- The harder tasks contain conflicting or distracting signals, so a frontier model has to identify the primary issue instead of treating every mention as equally important.
+
+## Deterministic Graders
+
+The final task score is a weighted total in `[0.0, 1.0]`:
+
+- Queue correctness: `0.15`
+- Priority correctness: `0.10`
+- Issue-type correctness: `0.10`
+- Requested-fields correctness: `0.15`
+- Reply coverage: `0.25`
+- Internal-note coverage: `0.10`
+- Final status: `0.10`
+- Resolution code: `0.05`
+
+The same grader also drives dense reward shaping during the episode by comparing the current score to the previous score and then subtracting small penalties for no-op or low-signal actions.
+
+## Project Layout
+
+```text
+.
+|-- inference.py
+|-- openenv.yaml
+|-- pyproject.toml
+|-- requirements.txt
+|-- supportdesk_env
+|   |-- __init__.py
+|   |-- client.py
+|   |-- graders.py
+|   |-- models.py
+|   |-- tasks.py
+|   `-- server
+|       |-- app.py
+|       `-- supportdesk_environment.py
+|-- tests
+|   `-- test_supportdesk.py
+`-- uv.lock
+```
+
+## Local Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+Or with uv:
+
+```bash
+uv sync
+```
+
+Optional environment variables for the baseline:
+
+```bash
+export API_BASE_URL="https://router.huggingface.co/v1"
+export MODEL_NAME="openai/gpt-oss-120b"
+export OPENAI_API_KEY="sk-..."  # Or use HF_TOKEN with a compatible router
+export HF_TOKEN="hf_..."
+```
+
+The baseline uses the OpenAI Python client and supports both `OPENAI_API_KEY` and `HF_TOKEN`.
+
+## Setup and Usage Instructions
+
+Typical local workflow:
+
+```bash
+pip install -r requirements.txt
+python -m openenv.cli validate .
+python inference.py
+python -m supportdesk_env.server.app
+```
+
+## Local RL Playground
+
+If you want to import the package directly and train against the local environment without going through the HTTP server, use the tabular Q-learning example:
+
+```bash
+python examples/rl/train_q_agent.py
+```
+
+This script imports the package, instantiates `SupportDeskEnvironment` directly, trains a tiny Q-learning agent over a compact discrete action library, and then prints greedy evaluation results for all three tasks. It is meant as a local experimentation playground, not as the official submission baseline.
+
+## Run the Server
+
+```bash
+python -m supportdesk_env.server.app
+```
+
+Or with the OpenEnv entrypoint:
+
+```bash
+server
+```
+
+## Run the Baseline
+
+```bash
+python inference.py
+```
+
+When model credentials are present, the script uses the OpenAI client against `API_BASE_URL` and `MODEL_NAME`. If credentials are missing or a request fails, it falls back to a deterministic heuristic policy so the script still completes and prints reproducible scores.
+
+## Docker
+
+```bash
+docker build -t supportdesk-env .
+docker run -p 8000:8000 supportdesk-env
+```
+
+## Hugging Face Space Deployment
+
+Deploy this repo as a Docker Space and keep it public for submission. The Space should include the `openenv` tag and the following environment configuration values:
+
+- `API_BASE_URL`
+- `MODEL_NAME`
+- `HF_TOKEN`
+
+If the OpenEnv CLI is installed, deployment can be done with:
+
+```bash
+openenv push --repo-id your-username/hyperbrick-support-ops-env
+```
+
+## Validation
+
+```bash
+openenv validate .
+```
+
+For a full pre-submission pass against a deployed Space:
+
+```bash
+./scripts/validate-submission.sh https://your-space.hf.space .
+```
+
+## Submission Checklist
+
+- Public GitHub repository with this codebase
+- Root `inference.py`
+- Working Docker build
+- Deployed Hugging Face Docker Space tagged `openenv`
+- Space secrets configured: `API_BASE_URL`, `MODEL_NAME`, `HF_TOKEN`
+- README present with environment overview, action/observation definitions, tasks, setup, and baseline scores
+
+## Baseline Scores
+
+Expected deterministic fallback baseline:
+
+- `billing_refund_easy`: `1.00`
+- `account_takeover_medium`: `1.00`
+- `api_incident_hard`: `1.00`
+- Average: `1.00`
+
+These scores are deliberately reproducible because the fallback policy follows the gold workflow exactly. A model-backed run will typically be lower unless the prompt or model is improved, which makes the environment useful for both training and evaluation.

__init__.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the real supportdesk_env package."""
+
+from supportdesk_env import *  # noqa: F401,F403

client.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the real supportdesk_env package."""
+
+from supportdesk_env.client import *  # noqa: F401,F403

examples/rl/train_q_agent.py

@@ -0,0 +1,278 @@
+"""Train a simple tabular Q-learning agent against the local SupportDesk env.
+
+This is an extra playground script for local experimentation. It is not part of
+the hackathon submission baseline and intentionally uses a compact, hand-built
+discrete action library so that plain Python Q-learning can train quickly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from supportdesk_env import (
+    SupportDeskAction,
+    get_task,
+    grade_case,
+    list_task_ids,
+)
+from supportdesk_env.policies import default_note, default_reply
+from supportdesk_env.server.supportdesk_environment import SupportDeskEnvironment
+
+
+@dataclass
+class EvalResult:
+    """Compact report for a greedy evaluation episode."""
+
+    task_id: str
+    score: float
+    reward: float
+    steps: int
+    actions: list[str]
+
+
+def build_action_library(task_id: str) -> list[SupportDeskAction]:
+    """Return a small discrete action set for a task."""
+
+    task = get_task(task_id)
+    wrong_queue = next(queue for queue in ("general_support", "billing_ops", "trust_and_safety", "platform_engineering") if queue != task.gold_queue)
+    wrong_priority = next(priority for priority in ("low", "normal", "high", "urgent") if priority != task.gold_priority)
+    wrong_issue = next(issue for issue in ("general_question", "duplicate_charge", "account_compromise", "production_incident") if issue != task.gold_issue_type)
+
+    partial_fields = list(task.required_requested_fields[:1])
+    if not partial_fields:
+        partial_fields = ["billing_email"]
+
+    if task.required_requested_fields:
+        good_request = SupportDeskAction(
+            operation="request_info",
+            requested_fields=list(task.required_requested_fields),
+            status=task.gold_status,
+            reply=default_reply(task_id),
+        )
+    else:
+        good_request = SupportDeskAction(
+            operation="request_info",
+            requested_fields=["billing_email"],
+            status="waiting_on_customer",
+            reply="Please confirm the billing email on the account so we can continue.",
+        )
+    partial_request = SupportDeskAction(
+        operation="request_info",
+        requested_fields=partial_fields,
+        status="waiting_on_customer",
+        reply="Please share more details so we can investigate.",
+    )
+
+    return [
+        SupportDeskAction(
+            operation="classify",
+            queue=task.gold_queue,
+            priority=task.gold_priority,
+            issue_type=task.gold_issue_type,
+        ),
+        SupportDeskAction(
+            operation="classify",
+            queue=wrong_queue,
+            priority=wrong_priority,
+            issue_type=wrong_issue,
+        ),
+        good_request,
+        partial_request,
+        SupportDeskAction(operation="draft_reply", reply=default_reply(task_id)),
+        SupportDeskAction(operation="draft_reply", reply="Thanks for reaching out. We are checking this now."),
+        SupportDeskAction(operation="add_internal_note", internal_note=default_note(task_id)),
+        SupportDeskAction(operation="add_internal_note", internal_note="Customer contacted support with a problem."),
+        SupportDeskAction(
+            operation="submit",
+            status=task.gold_status,
+            resolution_code=task.gold_resolution_code,
+        ),
+        SupportDeskAction(
+            operation="submit",
+            status="resolved",
+            resolution_code="closed_generic",
+        ),
+    ]
+
+
+def state_key(task_id: str, observation) -> tuple:
+    """Compress the observation into a tabular Q-learning state."""
+
+    case = observation.case
+    return (
+        task_id,
+        case.queue or "_",
+        case.priority or "_",
+        case.issue_type or "_",
+        case.status,
+        case.resolution_code or "_",
+        tuple(case.requested_fields),
+        bool(case.reply),
+        bool(case.internal_note),
+        observation.remaining_steps,
+    )
+
+
+def action_label(action: SupportDeskAction) -> str:
+    """Human-readable action label for debug output."""
+
+    parts = [action.operation]
+    if action.queue:
+        parts.append(action.queue)
+    if action.priority:
+        parts.append(action.priority)
+    if action.issue_type:
+        parts.append(action.issue_type)
+    if action.status:
+        parts.append(action.status)
+    if action.resolution_code:
+        parts.append(action.resolution_code)
+    if action.requested_fields:
+        parts.append(",".join(action.requested_fields))
+    if action.reply:
+        parts.append("reply")
+    if action.internal_note:
+        parts.append("note")
+    return " | ".join(parts)
+
+
+def choose_action(q_values: dict[tuple, list[float]], state: tuple, num_actions: int, epsilon: float) -> int:
+    """Epsilon-greedy action selection."""
+
+    if state not in q_values:
+        q_values[state] = [0.0] * num_actions
+
+    if random.random() < epsilon:
+        return random.randrange(num_actions)
+
+    best_value = max(q_values[state])
+    best_indices = [index for index, value in enumerate(q_values[state]) if value == best_value]
+    return random.choice(best_indices)
+
+
+def train_q_agent(
+    episodes_per_task: int,
+    alpha: float,
+    gamma: float,
+    epsilon: float,
+    epsilon_decay: float,
+    min_epsilon: float,
+    seed: int,
+) -> tuple[dict[tuple, list[float]], dict[str, list[SupportDeskAction]]]:
+    """Train a small tabular Q-learning agent over all tasks."""
+
+    random.seed(seed)
+    q_values: dict[tuple, list[float]] = {}
+    action_libraries = {task_id: build_action_library(task_id) for task_id in list_task_ids()}
+
+    for _ in range(episodes_per_task):
+        for task_id in list_task_ids():
+            env = SupportDeskEnvironment(task_id=task_id)
+            observation = env.reset()
+            actions = action_libraries[task_id]
+
+            try:
+                while not observation.done:
+                    state = state_key(task_id, observation)
+                    action_index = choose_action(q_values, state, len(actions), epsilon)
+                    next_observation = env.step(actions[action_index])
+
+                    next_state = state_key(task_id, next_observation)
+                    if next_state not in q_values:
+                        q_values[next_state] = [0.0] * len(actions)
+
+                    td_target = next_observation.reward + gamma * (0.0 if next_observation.done else max(q_values[next_state]))
+                    td_error = td_target - q_values[state][action_index]
+                    q_values[state][action_index] += alpha * td_error
+                    observation = next_observation
+            finally:
+                env.close()
+
+        epsilon = max(min_epsilon, epsilon * epsilon_decay)
+
+    return q_values, action_libraries
+
+
+def evaluate_policy(
+    q_values: dict[tuple, list[float]],
+    action_libraries: dict[str, list[SupportDeskAction]],
+) -> list[EvalResult]:
+    """Run a greedy evaluation episode for each task."""
+
+    results: list[EvalResult] = []
+
+    for task_id in list_task_ids():
+        env = SupportDeskEnvironment(task_id=task_id)
+        observation = env.reset()
+        actions = action_libraries[task_id]
+        chosen_actions: list[str] = []
+
+        try:
+            while not observation.done:
+                state = state_key(task_id, observation)
+                q_values.setdefault(state, [0.0] * len(actions))
+                action_index = max(range(len(actions)), key=lambda idx: q_values[state][idx])
+                action = actions[action_index]
+                chosen_actions.append(action_label(action))
+                observation = env.step(action)
+
+            results.append(
+                EvalResult(
+                    task_id=task_id,
+                    score=grade_case(get_task(task_id), env.state.case).total_score,
+                    reward=env.state.reward,
+                    steps=env.state.step_count,
+                    actions=chosen_actions,
+                )
+            )
+        finally:
+            env.close()
+
+    return results
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Train a simple tabular Q-learning agent on SupportDesk.")
+    parser.add_argument("--episodes-per-task", type=int, default=250)
+    parser.add_argument("--alpha", type=float, default=0.45)
+    parser.add_argument("--gamma", type=float, default=0.92)
+    parser.add_argument("--epsilon", type=float, default=0.35)
+    parser.add_argument("--epsilon-decay", type=float, default=0.99)
+    parser.add_argument("--min-epsilon", type=float, default=0.03)
+    parser.add_argument("--seed", type=int, default=7)
+    args = parser.parse_args()
+
+    q_values, action_libraries = train_q_agent(
+        episodes_per_task=args.episodes_per_task,
+        alpha=args.alpha,
+        gamma=args.gamma,
+        epsilon=args.epsilon,
+        epsilon_decay=args.epsilon_decay,
+        min_epsilon=args.min_epsilon,
+        seed=args.seed,
+    )
+
+    results = evaluate_policy(q_values, action_libraries)
+    average_score = sum(result.score for result in results) / len(results)
+
+    print("Tabular Q-learning evaluation")
+    print("============================")
+    for result in results:
+        print(
+            f"{result.task_id}: score={result.score:.2f} reward={result.reward:.2f} "
+            f"steps={result.steps}"
+        )
+        print(f"  actions: {' -> '.join(result.actions)}")
+    print(f"average_score={average_score:.3f}")
+
+
+if __name__ == "__main__":
+    main()

graders.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the real supportdesk_env package."""
+
+from supportdesk_env.graders import *  # noqa: F401,F403

inference.py

@@ -0,0 +1,151 @@
+"""Baseline inference script for the SupportDesk OpenEnv submission."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from statistics import mean
+
+try:
+    from openai import OpenAI
+except ImportError:  # pragma: no cover - local fallback mode
+    OpenAI = None  # type: ignore[assignment]
+
+from supportdesk_env.graders import grade_case
+from supportdesk_env.models import SupportDeskAction, SupportDeskObservation
+from supportdesk_env.policies import heuristic_action
+from supportdesk_env.server.supportdesk_environment import SupportDeskEnvironment
+from supportdesk_env.tasks import get_task, list_task_ids
+
+SYSTEM_PROMPT = """You are a support operations agent solving one triage ticket.
+Return exactly one JSON object with this schema:
+{
+  "operation": "classify|request_info|draft_reply|add_internal_note|submit",
+  "queue": string or null,
+  "priority": string or null,
+  "issue_type": string or null,
+  "status": string or null,
+  "resolution_code": string or null,
+  "requested_fields": [string],
+  "reply": string or null,
+  "internal_note": string or null
+}
+
+Use the policy snippets in the observation. Keep customer replies short, precise, and professional.
+"""
+
+MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4.1-mini")
+API_BASE_URL = os.getenv("API_BASE_URL")
+API_KEY = os.getenv("OPENAI_API_KEY") or os.getenv("HF_TOKEN") or "not-set"
+MAX_STEPS = int(os.getenv("MAX_STEPS", "6"))
+TEMPERATURE = float(os.getenv("TEMPERATURE", "0"))
+
+
+def _build_client() -> OpenAI | None:
+    if OpenAI is None:
+        return None
+    if API_KEY == "not-set":
+        return None
+    kwargs = {"api_key": API_KEY}
+    if API_BASE_URL:
+        kwargs["base_url"] = API_BASE_URL
+    return OpenAI(**kwargs)
+
+
+def _extract_json(text: str) -> dict:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+        if not match:
+            raise
+        return json.loads(match.group(0))
+
+
+def _observation_prompt(observation: SupportDeskObservation) -> str:
+    kb_lines = "\n".join(
+        f"- {snippet.article_id}: {snippet.title}: {snippet.content}" for snippet in observation.knowledge_base
+    )
+    history_lines = "\n".join(
+        f"- step {entry.step}: {entry.summary} ({entry.reward_delta:+.2f})"
+        for entry in observation.action_history
+    ) or "- none"
+
+    return f"""Task: {observation.task_id} ({observation.difficulty})
+Objective: {observation.objective}
+Ticket subject: {observation.ticket.subject}
+Ticket body: {observation.ticket.body}
+Customer tier: {observation.ticket.customer_tier}
+Region: {observation.ticket.region}
+Affected users: {observation.ticket.affected_users}
+SLA minutes remaining: {observation.ticket.sla_minutes_remaining}
+Business impact: {observation.ticket.business_impact}
+Secondary concerns: {observation.ticket.secondary_concerns}
+
+Knowledge base:
+{kb_lines}
+
+Current case state:
+- queue: {observation.case.queue}
+- priority: {observation.case.priority}
+- issue_type: {observation.case.issue_type}
+- status: {observation.case.status}
+- resolution_code: {observation.case.resolution_code}
+- requested_fields: {observation.case.requested_fields}
+- reply: {observation.case.reply}
+- internal_note: {observation.case.internal_note}
+
+Feedback: {observation.feedback}
+Remaining steps: {observation.remaining_steps}
+
+History:
+{history_lines}
+"""
+
+
+def _model_action(client: OpenAI | None, observation: SupportDeskObservation) -> SupportDeskAction:
+    if client is None:
+        return heuristic_action(observation)
+
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            temperature=TEMPERATURE,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": _observation_prompt(observation)},
+            ],
+        )
+        content = completion.choices[0].message.content or ""
+        payload = _extract_json(content)
+        return SupportDeskAction(**payload)
+    except Exception:
+        return heuristic_action(observation)
+
+
+def run_task(task_id: str, client: OpenAI | None) -> float:
+    env = SupportDeskEnvironment(task_id=task_id)
+    observation = env.reset()
+
+    try:
+        for _ in range(MAX_STEPS):
+            action = _model_action(client, observation)
+            observation = env.step(action)
+            if observation.done:
+                break
+        final_grade = grade_case(get_task(task_id), env.state.case)
+        print(f"{task_id}: score={final_grade.total_score:.2f} reward={env.state.reward:.2f}")
+        return final_grade.total_score
+    finally:
+        env.close()
+
+
+def main() -> None:
+    client = _build_client()
+    scores = [run_task(task_id, client) for task_id in list_task_ids()]
+    print(f"average_score={mean(scores):.3f}")
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the real supportdesk_env package."""
+
+from supportdesk_env.models import *  # noqa: F401,F403

openenv.yaml

@@ -0,0 +1,3 @@
+name: HyperBrickCaseOps
+env_name: supportdesk_env
+description: Enterprise support operations environment with SLA pressure, business-impact aware triage, and primary-vs-secondary issue prioritization.

pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "supportdesk-env"
+version = "0.1.0"
+description = "A real-world OpenEnv environment for customer support triage and escalation."
+authors = [{ name = "HyperBrick" }]
+dependencies = [
+  "fastapi>=0.115.0",
+  "openai>=1.54.0",
+  "openenv-core>=0.2.0",
+  "pydantic>=2.9.0",
+  "requests>=2.32.0",
+  "uvicorn>=0.30.0",
+]
+requires-python = ">=3.10"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0",
+]
+
+[project.scripts]
+server = "supportdesk_env.server.app:main"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["supportdesk_env", "supportdesk_env.server"]

pytest-cache-files-0ad_osqx/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

pytest-cache-files-0ad_osqx/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

pytest-cache-files-7cu1ajqk/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

pytest-cache-files-7cu1ajqk/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

pytest-cache-files-8nb5ix7f/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

pytest-cache-files-8nb5ix7f/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

pytest-cache-files-fy9fhtya/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

pytest-cache-files-fy9fhtya/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

pytest-cache-files-i3h6kocm/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

pytest-cache-files-i3h6kocm/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

pytest-cache-files-l0dcjql5/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

pytest-cache-files-l0dcjql5/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

pytest-cache-files-ofsx67d1/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

pytest-cache-files-ofsx67d1/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

requirements.txt

@@ -0,0 +1 @@
+-e .

scripts/validate-submission.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PING_URL="${1:-}"
+REPO_DIR="${2:-.}"
+IMAGE_TAG="supportdesk-env-validate"
+
+if [ -z "$PING_URL" ]; then
+  echo "Usage: ./scripts/validate-submission.sh <space_url> [repo_dir]"
+  exit 1
+fi
+
+echo "[1/4] Validating local OpenEnv project structure"
+(cd "$REPO_DIR" && openenv validate .)
+
+echo "[2/4] Building Docker image"
+(cd "$REPO_DIR" && docker build -t "$IMAGE_TAG" .)
+
+echo "[3/4] Checking public Space health"
+curl -fsSL "$PING_URL/health" >/dev/null
+curl -fsSL "$PING_URL/openapi.json" >/dev/null
+
+echo "[4/4] Checking public reset endpoint"
+curl -fsSL -X POST "$PING_URL/reset" \
+  -H "Content-Type: application/json" \
+  -d '{}' >/dev/null
+
+echo "Validation checks completed successfully."

server/__init__.py

@@ -0,0 +1 @@
+"""Server package for the SupportDesk OpenEnv environment."""

server/app.py

@@ -0,0 +1,33 @@
+"""FastAPI app entrypoint for the SupportDesk environment."""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except ImportError:  # pragma: no cover - package name differs across releases
+    from openenv_core.env_server.http_server import create_app
+
+from supportdesk_env.models import SupportDeskAction, SupportDeskObservation
+from supportdesk_env.server.supportdesk_environment import SupportDeskEnvironment
+
+app = create_app(
+    SupportDeskEnvironment,
+    action_cls=SupportDeskAction,
+    observation_cls=SupportDeskObservation,
+    env_name="supportdesk_env",
+)
+
+
+def main() -> None:
+    """Run the local HTTP server."""
+
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run("supportdesk_env.server.app:app", host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

server/supportdesk_environment.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the real supportdesk_env package."""
+
+from supportdesk_env.server.supportdesk_environment import *  # noqa: F401,F403

supportdesk_env/__init__.py

@@ -0,0 +1,46 @@
+"""SupportDesk OpenEnv environment package."""
+
+from supportdesk_env.graders import GradeBreakdown, grade_case, grade_task_id
+from supportdesk_env.models import (
+    ActionHistoryEntry,
+    KnowledgeSnippet,
+    SupportCaseProgress,
+    SupportDeskAction,
+    SupportDeskObservation,
+    SupportDeskState,
+    SupportTicket,
+)
+from supportdesk_env.policies import default_note, default_reply, heuristic_action
+from supportdesk_env.tasks import TASKS, SupportTaskSpec, get_task, list_task_ids
+
+try:
+    from supportdesk_env.client import SupportDeskEnv
+except ImportError:  # pragma: no cover - local unit tests can run without openenv-core
+    SupportDeskEnv = None  # type: ignore[assignment]
+
+try:
+    from supportdesk_env.server.supportdesk_environment import SupportDeskEnvironment
+except ImportError:  # pragma: no cover - guarded for partial local setups
+    SupportDeskEnvironment = None  # type: ignore[assignment]
+
+__all__ = [
+    "ActionHistoryEntry",
+    "GradeBreakdown",
+    "KnowledgeSnippet",
+    "SupportCaseProgress",
+    "SupportDeskAction",
+    "SupportDeskEnv",
+    "SupportDeskEnvironment",
+    "SupportDeskObservation",
+    "SupportDeskState",
+    "SupportTaskSpec",
+    "SupportTicket",
+    "TASKS",
+    "default_note",
+    "default_reply",
+    "get_task",
+    "grade_case",
+    "grade_task_id",
+    "heuristic_action",
+    "list_task_ids",
+]

supportdesk_env/client.py

@@ -0,0 +1,31 @@
+"""HTTP client for interacting with a deployed SupportDesk environment."""
+
+from __future__ import annotations
+
+from supportdesk_env.models import SupportDeskAction, SupportDeskObservation, SupportDeskState
+from supportdesk_env.openenv_compat import EnvClient, StepResult
+
+
+def _validate(model_cls, payload):
+    if hasattr(model_cls, "model_validate"):
+        return model_cls.model_validate(payload)
+    return model_cls(**payload)  # pragma: no cover - pydantic v1 fallback
+
+
+class SupportDeskEnv(EnvClient[SupportDeskAction, SupportDeskObservation, SupportDeskState]):
+    """Typed client for a locally running or deployed OpenEnv server."""
+
+    def _parse_state(self, payload) -> SupportDeskState:
+        return _validate(SupportDeskState, payload)
+
+    def _parse_reset(self, payload) -> SupportDeskObservation:
+        return _validate(SupportDeskObservation, payload)
+
+    def _parse_result(self, payload) -> StepResult[SupportDeskObservation]:
+        observation = _validate(SupportDeskObservation, payload["observation"])
+        return StepResult(
+            observation=observation,
+            reward=payload["reward"],
+            done=payload["done"],
+            info=payload.get("info", {}),
+        )

supportdesk_env/graders.py

@@ -0,0 +1,131 @@
+"""Deterministic graders and reward helpers for SupportDesk."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from supportdesk_env.models import SupportCaseProgress
+from supportdesk_env.tasks import SupportTaskSpec, get_task
+
+
+@dataclass(frozen=True)
+class GradeBreakdown:
+    """A scored view of how close a case is to the gold solution."""
+
+    total_score: float
+    queue_score: float
+    priority_score: float
+    issue_type_score: float
+    requested_fields_score: float
+    reply_score: float
+    note_score: float
+    status_score: float
+    resolution_score: float
+    completed_milestones: tuple[str, ...]
+
+
+def _normalize(text: str | None) -> str:
+    if not text:
+        return ""
+    normalized = text.lower().replace("-", " ")
+    return re.sub(r"[^a-z0-9\s]", " ", normalized)
+
+
+def _marker_group_score(text: str | None, marker_groups: tuple[tuple[str, ...], ...]) -> float:
+    if not marker_groups:
+        return 1.0
+
+    normalized = _normalize(text)
+    if not normalized:
+        return 0.0
+
+    matches = 0
+    for group in marker_groups:
+        if any(_normalize(marker) in normalized for marker in group):
+            matches += 1
+    return matches / len(marker_groups)
+
+
+def _requested_fields_score(case: SupportCaseProgress, task: SupportTaskSpec) -> float:
+    required = set(task.required_requested_fields)
+    requested = set(case.requested_fields)
+
+    if not required:
+        return 1.0 if not requested else 0.0
+    if not requested:
+        return 0.0
+
+    matched = len(required.intersection(requested))
+    extras = len(requested.difference(required))
+    raw = matched / len(required)
+    penalty = min(0.25, extras * 0.05)
+    return max(0.0, raw - penalty)
+
+
+def _reply_penalty(case: SupportCaseProgress, task: SupportTaskSpec) -> float:
+    text = _normalize(case.reply)
+    if not text:
+        return 0.0
+    return 0.0 if not any(_normalize(marker) in text for marker in task.forbidden_reply_markers) else 0.5
+
+
+def grade_case(task: SupportTaskSpec, case: SupportCaseProgress) -> GradeBreakdown:
+    """Score a case from 0.0 to 1.0 using deterministic task rules."""
+
+    queue_score = 1.0 if case.queue == task.gold_queue else 0.0
+    priority_score = 1.0 if case.priority == task.gold_priority else 0.0
+    issue_type_score = 1.0 if case.issue_type == task.gold_issue_type else 0.0
+    requested_fields_score = _requested_fields_score(case, task)
+    reply_score = max(0.0, _marker_group_score(case.reply, task.required_reply_markers) - _reply_penalty(case, task))
+    note_score = _marker_group_score(case.internal_note, task.required_note_markers)
+    status_score = 1.0 if case.status == task.gold_status else 0.0
+    resolution_score = 1.0 if case.resolution_code == task.gold_resolution_code else 0.0
+
+    weighted_total = (
+        queue_score * 0.15
+        + priority_score * 0.10
+        + issue_type_score * 0.10
+        + requested_fields_score * 0.15
+        + reply_score * 0.25
+        + note_score * 0.10
+        + status_score * 0.10
+        + resolution_score * 0.05
+    )
+
+    milestones: list[str] = []
+    if queue_score:
+        milestones.append("queue")
+    if priority_score:
+        milestones.append("priority")
+    if issue_type_score:
+        milestones.append("issue_type")
+    if requested_fields_score >= 0.99:
+        milestones.append("requested_fields")
+    if reply_score >= 0.99:
+        milestones.append("reply")
+    if note_score >= 0.99:
+        milestones.append("internal_note")
+    if status_score:
+        milestones.append("status")
+    if resolution_score:
+        milestones.append("resolution_code")
+
+    return GradeBreakdown(
+        total_score=round(weighted_total, 4),
+        queue_score=queue_score,
+        priority_score=priority_score,
+        issue_type_score=issue_type_score,
+        requested_fields_score=round(requested_fields_score, 4),
+        reply_score=round(reply_score, 4),
+        note_score=round(note_score, 4),
+        status_score=status_score,
+        resolution_score=resolution_score,
+        completed_milestones=tuple(milestones),
+    )
+
+
+def grade_task_id(task_id: str, case: SupportCaseProgress) -> GradeBreakdown:
+    """Convenience wrapper used by tests and evaluation scripts."""
+
+    return grade_case(get_task(task_id), case)

supportdesk_env/models.py

@@ -0,0 +1,103 @@
+"""Typed models for the SupportDesk OpenEnv environment."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from supportdesk_env.openenv_compat import Action, Observation, State
+
+
+class KnowledgeSnippet(BaseModel):
+    """A policy or runbook excerpt the agent can use during triage."""
+
+    article_id: str
+    title: str
+    content: str
+
+
+class SupportTicket(BaseModel):
+    """Static task input representing the inbound support ticket."""
+
+    customer_name: str
+    customer_tier: Literal["free", "pro", "enterprise"]
+    company: str
+    subject: str
+    body: str
+    region: str
+    affected_users: int | None = None
+    sla_minutes_remaining: int | None = None
+    business_impact: str | None = None
+    secondary_concerns: list[str] = Field(default_factory=list)
+    attachments: list[str] = Field(default_factory=list)
+
+
+class ActionHistoryEntry(BaseModel):
+    """A concise trace entry used in observations and state dumps."""
+
+    step: int
+    operation: str
+    summary: str
+    reward_delta: float = 0.0
+
+
+class SupportCaseProgress(BaseModel):
+    """Mutable case state that graders score against."""
+
+    queue: str | None = None
+    priority: str | None = None
+    issue_type: str | None = None
+    status: str = "new"
+    resolution_code: str | None = None
+    requested_fields: list[str] = Field(default_factory=list)
+    reply: str | None = None
+    internal_note: str | None = None
+
+
+class SupportDeskAction(Action):
+    """One structured action the agent can take at each step."""
+
+    operation: Literal["classify", "request_info", "draft_reply", "add_internal_note", "submit"]
+    queue: str | None = None
+    priority: str | None = None
+    issue_type: str | None = None
+    status: str | None = None
+    resolution_code: str | None = None
+    requested_fields: list[str] = Field(default_factory=list)
+    reply: str | None = None
+    internal_note: str | None = None
+
+
+class SupportDeskObservation(Observation):
+    """Observation emitted to the agent after reset and each step."""
+
+    task_id: str
+    difficulty: Literal["easy", "medium", "hard"]
+    objective: str
+    ticket: SupportTicket
+    knowledge_base: list[KnowledgeSnippet]
+    available_queues: list[str]
+    available_priorities: list[str]
+    available_statuses: list[str]
+    available_issue_types: list[str]
+    case: SupportCaseProgress
+    action_history: list[ActionHistoryEntry] = Field(default_factory=list)
+    feedback: str = ""
+    remaining_steps: int = 0
+
+
+class SupportDeskState(State):
+    """Current environment state returned by the OpenEnv state() API."""
+
+    task_id: str
+    difficulty: Literal["easy", "medium", "hard"]
+    step_count: int = 0
+    reward: float = 0.0
+    done: bool = False
+    current_score: float = 0.0
+    max_steps: int = 0
+    case: SupportCaseProgress
+    action_history: list[ActionHistoryEntry] = Field(default_factory=list)
+    completed_milestones: list[str] = Field(default_factory=list)
+    last_feedback: str = ""

supportdesk_env/openenv_compat.py

@@ -0,0 +1,76 @@
+"""Compatibility helpers for environments where openenv-core is not installed."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+A = TypeVar("A")
+O = TypeVar("O")
+S = TypeVar("S")
+
+
+OPENENV_AVAILABLE = True
+
+try:
+    from openenv.core.client_types import StepResult  # type: ignore
+    from openenv.core.env_client import EnvClient  # type: ignore
+    from openenv.core.env_server.interfaces import Environment  # type: ignore
+    from openenv.core.env_server.types import Action, Observation, State  # type: ignore
+    from openenv.core.env_server.types import EnvironmentMetadata  # type: ignore
+except ImportError:
+    try:
+        from openenv_core.client_types import StepResult  # type: ignore
+        from openenv_core.http_env_client import HTTPEnvClient as EnvClient  # type: ignore
+        from openenv_core.env_server.interfaces import Environment  # type: ignore
+        from openenv_core.env_server.types import Action, Observation, State  # type: ignore
+        from openenv_core.env_server.types import EnvironmentMetadata  # type: ignore
+    except ImportError:
+        OPENENV_AVAILABLE = False
+
+        class Action(BaseModel):
+            """Fallback Action base type for local import-only workflows."""
+
+        class Observation(BaseModel):
+            """Fallback Observation base type for local import-only workflows."""
+
+            reward: float = 0.0
+            done: bool = False
+
+        class State(BaseModel):
+            """Fallback State base type for local import-only workflows."""
+
+        class Environment(Generic[A, O, S]):
+            """Minimal base class used for local unit tests and import-based demos."""
+
+            def __init__(self) -> None:
+                super().__init__()
+
+        class EnvironmentMetadata(BaseModel):
+            """Fallback metadata model used when OpenEnv is absent."""
+
+            name: str
+            description: str
+            readme_content: str | None = None
+            version: str | None = None
+            author: str | None = None
+
+        @dataclass
+        class StepResult(Generic[O]):
+            """Fallback step result for local-only client compatibility."""
+
+            observation: O
+            reward: float
+            done: bool
+            info: dict[str, Any] = field(default_factory=dict)
+
+        class EnvClient(Generic[A, O, S]):
+            """Placeholder client that fails only when actually used."""
+
+            def __init__(self, *args, **kwargs) -> None:
+                raise ImportError(
+                    "SupportDeskEnv requires openenv-core to be installed. "
+                    "Run `py -3 -m pip install openenv-core` to use the HTTP client."
+                )

supportdesk_env/policies.py

@@ -0,0 +1,72 @@
+"""Reusable policy helpers for local baselines and training examples."""
+
+from __future__ import annotations
+
+from supportdesk_env.models import SupportDeskAction, SupportDeskObservation
+from supportdesk_env.tasks import get_task
+
+
+def default_reply(task_id: str) -> str:
+    """Return a task-specific high-signal customer reply."""
+
+    if task_id == "billing_refund_easy":
+        return (
+            "Thanks for flagging the duplicate charge. I have started the refund for the extra "
+            "charge, and the funds usually appear within 5-7 business days."
+        )
+    if task_id == "account_takeover_medium":
+        return (
+            "We have escalated this to our trust team. Please reset your password, scan your "
+            "device for malware, and reply with your workspace_id, last successful login time, "
+            "and billing email so we can verify the account safely."
+        )
+    return (
+        "We are treating this as an active incident and our on-call engineering team is engaged. "
+        "Please send the affected request IDs, UTC timestamps, and the impacted region so we can "
+        "speed up the investigation."
+    )
+
+
+def default_note(task_id: str) -> str:
+    """Return a task-specific internal note."""
+
+    if task_id == "billing_refund_easy":
+        return "Duplicate charge confirmed from attached invoice; refund approved."
+    if task_id == "account_takeover_medium":
+        return "Suspicious login alert reported and customer is locked out."
+    return "EU data residency rollout hit intermittent HTTP 500s and the customer launches tonight."
+
+
+def heuristic_action(observation: SupportDeskObservation) -> SupportDeskAction:
+    """Deterministic high-performing policy used by the baseline."""
+
+    task = get_task(observation.task_id)
+    case = observation.case
+
+    if case.queue is None or case.priority is None or case.issue_type is None:
+        return SupportDeskAction(
+            operation="classify",
+            queue=task.gold_queue,
+            priority=task.gold_priority,
+            issue_type=task.gold_issue_type,
+        )
+
+    if task.required_requested_fields and sorted(case.requested_fields) != sorted(task.required_requested_fields):
+        return SupportDeskAction(
+            operation="request_info",
+            requested_fields=list(task.required_requested_fields),
+            status=task.gold_status,
+            reply=default_reply(observation.task_id),
+        )
+
+    if not case.reply:
+        return SupportDeskAction(operation="draft_reply", reply=default_reply(observation.task_id))
+
+    if not case.internal_note:
+        return SupportDeskAction(operation="add_internal_note", internal_note=default_note(observation.task_id))
+
+    return SupportDeskAction(
+        operation="submit",
+        status=task.gold_status,
+        resolution_code=task.gold_resolution_code,
+    )

supportdesk_env/server/__init__.py

@@ -0,0 +1 @@
+"""SupportDesk server package."""

supportdesk_env/server/app.py

@@ -0,0 +1,33 @@
+"""FastAPI app entrypoint for the SupportDesk environment."""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except ImportError:  # pragma: no cover - package name differs across releases
+    from openenv_core.env_server.http_server import create_app
+
+from supportdesk_env.models import SupportDeskAction, SupportDeskObservation
+from supportdesk_env.server.supportdesk_environment import SupportDeskEnvironment
+
+app = create_app(
+    SupportDeskEnvironment,
+    action_cls=SupportDeskAction,
+    observation_cls=SupportDeskObservation,
+    env_name="supportdesk_env",
+)
+
+
+def main() -> None:
+    """Run the local HTTP server."""
+
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run("supportdesk_env.server.app:app", host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

supportdesk_env/server/supportdesk_environment.py

@@ -0,0 +1,241 @@
+"""SupportDesk environment implementation."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from supportdesk_env.graders import grade_case
+from supportdesk_env.models import (
+    ActionHistoryEntry,
+    SupportCaseProgress,
+    SupportDeskAction,
+    SupportDeskObservation,
+    SupportDeskState,
+)
+from supportdesk_env.openenv_compat import Environment, EnvironmentMetadata
+from supportdesk_env.tasks import (
+    ALL_ISSUE_TYPES,
+    ALL_PRIORITIES,
+    ALL_QUEUES,
+    ALL_STATUSES,
+    SupportTaskSpec,
+    get_task,
+    list_task_ids,
+)
+
+
+class SupportDeskEnvironment(
+    Environment[SupportDeskAction, SupportDeskObservation, SupportDeskState]
+):
+    """A realistic customer support triage environment with dense rewards."""
+
+    def __init__(self, task_id: str | None = None):
+        super().__init__()
+        requested_task = task_id or os.getenv("SUPPORTDESK_TASK_ID") or list_task_ids()[0]
+        self.task: SupportTaskSpec = get_task(requested_task)
+        self._max_steps = self.task.max_steps
+        self._step_count = 0
+        self._reward_total = 0.0
+        self._done = False
+        self._last_feedback = ""
+        self._history: list[ActionHistoryEntry] = []
+        self._case = SupportCaseProgress()
+        initial_grade = grade_case(self.task, self._case)
+        self._score = initial_grade.total_score
+        self._completed_milestones = list(initial_grade.completed_milestones)
+
+    @property
+    def state(self) -> SupportDeskState:
+        return SupportDeskState(
+            task_id=self.task.task_id,
+            difficulty=self.task.difficulty,
+            step_count=self._step_count,
+            reward=round(self._reward_total, 4),
+            done=self._done,
+            current_score=round(self._score, 4),
+            max_steps=self._max_steps,
+            case=self._case.model_copy(deep=True),
+            action_history=[entry.model_copy(deep=True) for entry in self._history],
+            completed_milestones=list(self._completed_milestones),
+            last_feedback=self._last_feedback,
+        )
+
+    def reset(
+        self,
+        seed: int | None = None,
+        episode_id: str | None = None,
+        **kwargs,
+    ) -> SupportDeskObservation:
+        self._step_count = 0
+        self._reward_total = 0.0
+        self._done = False
+        self._last_feedback = "New case loaded. Review the ticket and policy snippets before acting."
+        self._history = []
+        self._case = SupportCaseProgress()
+        initial_grade = grade_case(self.task, self._case)
+        self._score = initial_grade.total_score
+        self._completed_milestones = list(initial_grade.completed_milestones)
+        return self._build_observation(reward=0.0, done=False)
+
+    def step(
+        self,
+        action: SupportDeskAction,
+        timeout_s: float | None = None,
+        **kwargs,
+    ) -> SupportDeskObservation:
+        if self._done:
+            return self._build_observation(
+                reward=-0.05,
+                done=True,
+                feedback="Episode already finished. Call reset() before taking more actions.",
+            )
+
+        previous_grade = grade_case(self.task, self._case)
+        self._apply_action(action)
+        self._step_count += 1
+
+        current_grade = grade_case(self.task, self._case)
+        reward = current_grade.total_score - previous_grade.total_score
+        reward += self._action_penalty(action, current_grade.total_score, previous_grade.total_score)
+        reward = round(reward, 4)
+
+        self._score = current_grade.total_score
+        self._completed_milestones = list(current_grade.completed_milestones)
+
+        if action.operation == "submit":
+            self._done = True
+            self._last_feedback = (
+                "Case submitted. Final deterministic grade is "
+                f"{current_grade.total_score:.2f}."
+            )
+        elif self._step_count >= self._max_steps:
+            self._done = True
+            self._last_feedback = (
+                f"Reached max steps ({self._max_steps}). Final deterministic grade is "
+                f"{current_grade.total_score:.2f}."
+            )
+        else:
+            self._last_feedback = self._build_feedback(current_grade, reward)
+
+        self._reward_total = round(self._reward_total + reward, 4)
+        self._history.append(
+            ActionHistoryEntry(
+                step=self._step_count,
+                operation=action.operation,
+                summary=self._summarize_action(action),
+                reward_delta=reward,
+            )
+        )
+
+        return self._build_observation(reward=reward, done=self._done)
+
+    def close(self) -> None:
+        """No-op close hook for compatibility with local scripts."""
+
+    def get_metadata(self) -> EnvironmentMetadata:
+        """Return richer metadata for docs, validators, and HF Space UI."""
+
+        readme_path = Path(__file__).resolve().parents[2] / "README.md"
+        readme_content = readme_path.read_text(encoding="utf-8") if readme_path.exists() else None
+        return EnvironmentMetadata(
+            name="supportdesk_env",
+            description=(
+                "A policy-heavy enterprise support operations environment with deterministic "
+                "grading, dense rewards, SLA pressure, and escalating ticket difficulty."
+            ),
+            readme_content=readme_content,
+            version="0.1.0",
+            author="HyperBrick",
+        )
+
+    def _apply_action(self, action: SupportDeskAction) -> None:
+        if action.queue is not None:
+            self._case.queue = action.queue
+        if action.priority is not None:
+            self._case.priority = action.priority
+        if action.issue_type is not None:
+            self._case.issue_type = action.issue_type
+        if action.status is not None:
+            self._case.status = action.status
+        if action.resolution_code is not None:
+            self._case.resolution_code = action.resolution_code
+        if action.reply is not None:
+            self._case.reply = action.reply
+        if action.internal_note is not None:
+            self._case.internal_note = action.internal_note
+        if action.requested_fields:
+            merged = {item for item in self._case.requested_fields}
+            merged.update(action.requested_fields)
+            self._case.requested_fields = sorted(merged)
+
+    def _action_penalty(
+        self,
+        action: SupportDeskAction,
+        current_score: float,
+        previous_score: float,
+    ) -> float:
+        penalty = 0.0
+        if current_score <= previous_score:
+            penalty -= 0.03
+        if action.operation == "draft_reply" and not action.reply:
+            penalty -= 0.03
+        if action.operation == "request_info" and not action.requested_fields:
+            penalty -= 0.03
+        if action.operation == "add_internal_note" and not action.internal_note:
+            penalty -= 0.03
+        if action.operation == "classify" and not any(
+            [action.queue, action.priority, action.issue_type, action.status, action.resolution_code]
+        ):
+            penalty -= 0.03
+        return round(penalty, 4)
+
+    def _build_feedback(self, grade, reward: float) -> str:
+        return (
+            f"Reward delta {reward:+.2f}. Current score {grade.total_score:.2f}. "
+            f"Completed milestones: {', '.join(grade.completed_milestones) or 'none yet'}."
+        )
+
+    def _summarize_action(self, action: SupportDeskAction) -> str:
+        parts = [action.operation]
+        if action.queue:
+            parts.append(f"queue={action.queue}")
+        if action.priority:
+            parts.append(f"priority={action.priority}")
+        if action.issue_type:
+            parts.append(f"issue_type={action.issue_type}")
+        if action.status:
+            parts.append(f"status={action.status}")
+        if action.resolution_code:
+            parts.append(f"resolution={action.resolution_code}")
+        if action.requested_fields:
+            parts.append(f"requested={','.join(action.requested_fields)}")
+        if action.reply:
+            parts.append("reply=yes")
+        if action.internal_note:
+            parts.append("note=yes")
+        return " | ".join(parts)
+
+    def _build_observation(
+        self,
+        reward: float,
+        done: bool,
+        feedback: str | None = None,
+    ) -> SupportDeskObservation:
+        return SupportDeskObservation(
+            task_id=self.task.task_id,
+            difficulty=self.task.difficulty,
+            objective=self.task.objective,
+            ticket=self.task.ticket,
+            knowledge_base=list(self.task.knowledge_base),
+            available_queues=list(ALL_QUEUES),
+            available_priorities=list(ALL_PRIORITIES),
+            available_statuses=list(ALL_STATUSES),
+            available_issue_types=list(ALL_ISSUE_TYPES),
+            case=self._case.model_copy(deep=True),
+            action_history=[entry.model_copy(deep=True) for entry in self._history],
+            feedback=feedback or self._last_feedback,
+            remaining_steps=max(self._max_steps - self._step_count, 0),
+            reward=reward,
+            done=done,
+        )

supportdesk_env/tasks.py

@@ -0,0 +1,281 @@
+"""Task registry for the SupportDesk environment."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from supportdesk_env.models import KnowledgeSnippet, SupportTicket
+
+
+ALL_QUEUES = ["billing_ops", "trust_and_safety", "platform_engineering", "general_support"]
+ALL_PRIORITIES = ["low", "normal", "high", "urgent"]
+ALL_STATUSES = ["new", "waiting_on_customer", "resolved", "escalated"]
+ALL_ISSUE_TYPES = [
+    "duplicate_charge",
+    "account_compromise",
+    "production_incident",
+    "general_question",
+]
+
+
+@dataclass(frozen=True)
+class SupportTaskSpec:
+    """Immutable definition of a single support triage task."""
+
+    task_id: str
+    difficulty: Literal["easy", "medium", "hard"]
+    title: str
+    objective: str
+    ticket: SupportTicket
+    knowledge_base: tuple[KnowledgeSnippet, ...]
+    gold_queue: str
+    gold_priority: str
+    gold_issue_type: str
+    gold_status: str
+    gold_resolution_code: str
+    required_requested_fields: tuple[str, ...]
+    required_reply_markers: tuple[tuple[str, ...], ...]
+    required_note_markers: tuple[tuple[str, ...], ...]
+    forbidden_reply_markers: tuple[str, ...] = ()
+    max_steps: int = 6
+
+
+TASKS: dict[str, SupportTaskSpec] = {
+    "billing_refund_easy": SupportTaskSpec(
+        task_id="billing_refund_easy",
+        difficulty="easy",
+        title="Duplicate charge refund triage",
+        objective=(
+            "Triage a duplicate-charge billing ticket, send the correct customer response, "
+            "and close the case only if no further customer information is required."
+        ),
+        ticket=SupportTicket(
+            customer_name="Riya Shah",
+            customer_tier="pro",
+            company="PixelNorth Studio",
+            subject="Charged twice after I canceled",
+            body=(
+                "I canceled our Pro annual workspace yesterday, but my card was charged again "
+                "this morning and I still see the old invoice. We only had one workspace, "
+                "so this looks like a duplicate charge. Please fix it quickly."
+            ),
+            region="ap-south-1",
+            affected_users=12,
+            sla_minutes_remaining=240,
+            business_impact="Finance ops are blocked from closing the monthly books until the duplicate invoice is fixed.",
+            secondary_concerns=["The customer also wants confirmation that the canceled workspace will stay deactivated."],
+            attachments=["invoice_7741.pdf"],
+        ),
+        knowledge_base=(
+            KnowledgeSnippet(
+                article_id="KB-101",
+                title="Duplicate charges and same-day cancellations",
+                content=(
+                    "If a customer reports a duplicate charge and the subscription is already "
+                    "canceled, route the ticket to billing_ops with high priority. Billing can "
+                    "approve the refund immediately without requesting extra information when an "
+                    "invoice is attached."
+                ),
+            ),
+            KnowledgeSnippet(
+                article_id="KB-102",
+                title="Refund communication checklist",
+                content=(
+                    "Customer replies for approved duplicate-charge refunds must confirm that a "
+                    "refund is being processed, mention the duplicate charge, and set the "
+                    "expectation that funds typically appear within 5-7 business days."
+                ),
+            ),
+            KnowledgeSnippet(
+                article_id="KB-103",
+                title="When to close a billing case",
+                content=(
+                    "Close the case as resolved only after the refund path is clear and no more "
+                    "customer details are needed."
+                ),
+            ),
+        ),
+        gold_queue="billing_ops",
+        gold_priority="high",
+        gold_issue_type="duplicate_charge",
+        gold_status="resolved",
+        gold_resolution_code="refund_approved",
+        required_requested_fields=(),
+        required_reply_markers=(
+            ("refund", "refunded", "reimburse"),
+            ("duplicate charge", "charged twice", "double charge"),
+            ("5-7 business days", "5 to 7 business days", "within 7 business days"),
+        ),
+        required_note_markers=(
+            ("duplicate charge", "double charge"),
+            ("refund", "refund approved"),
+        ),
+        forbidden_reply_markers=("chargeback", "security team"),
+    ),
+    "account_takeover_medium": SupportTaskSpec(
+        task_id="account_takeover_medium",
+        difficulty="medium",
+        title="Suspicious login recovery triage",
+        objective=(
+            "Handle a potential account-compromise case, request the missing verification "
+            "details, communicate safe next steps, and keep the case open until the customer replies. "
+            "The agent must protect account safety without promising an unsafe immediate unlock."
+        ),
+        ticket=SupportTicket(
+            customer_name="Marcus Lee",
+            customer_tier="pro",
+            company="Northline Analytics",
+            subject="Locked out after strange login alert",
+            body=(
+                "Our workspace admin got a login alert from a country none of us have visited, "
+                "and now I can't get back into the account. Please unlock it ASAP. The billing "
+                "email is still ours, but I'm worried someone got in."
+            ),
+            region="us-east-1",
+            affected_users=34,
+            sla_minutes_remaining=90,
+            business_impact="The admin is locked out of the analytics workspace ahead of the Monday executive review.",
+            secondary_concerns=["The customer wants the account unlocked immediately, but the verification flow cannot be skipped."],
+            attachments=[],
+        ),
+        knowledge_base=(
+            KnowledgeSnippet(
+                article_id="SEC-201",
+                title="Account compromise routing",
+                content=(
+                    "Potential account-takeover reports route to trust_and_safety with urgent "
+                    "priority. Do not resolve the case immediately."
+                ),
+            ),
+            KnowledgeSnippet(
+                article_id="SEC-202",
+                title="Verification details before unlock",
+                content=(
+                    "Before access can be restored, ask the customer for the workspace_id, the "
+                    "last successful login time, and the billing email on file. Keep the status "
+                    "waiting_on_customer until the details arrive."
+                ),
+            ),
+            KnowledgeSnippet(
+                article_id="SEC-203",
+                title="Customer response checklist",
+                content=(
+                    "Security replies should tell the customer to reset their password, scan "
+                    "their device for malware, and explain that the trust team is reviewing the case."
+                ),
+            ),
+        ),
+        gold_queue="trust_and_safety",
+        gold_priority="urgent",
+        gold_issue_type="account_compromise",
+        gold_status="waiting_on_customer",
+        gold_resolution_code="verification_needed",
+        required_requested_fields=("workspace_id", "last_successful_login", "billing_email"),
+        required_reply_markers=(
+            ("reset your password", "change your password"),
+            ("scan", "malware", "device check"),
+            ("trust team", "security team", "trust and safety"),
+        ),
+        required_note_markers=(
+            ("suspicious login", "strange login"),
+            ("locked out", "can’t get back", "cannot get back"),
+        ),
+    ),
+    "api_incident_hard": SupportTaskSpec(
+        task_id="api_incident_hard",
+        difficulty="hard",
+        title="Production API incident escalation",
+        objective=(
+            "Triage a high-pressure enterprise incident, ask for the right diagnostics, notify "
+            "the customer that engineering is engaged, and escalate instead of resolving. "
+            "The agent must prioritize the outage over a tempting secondary compliance question."
+        ),
+        ticket=SupportTicket(
+            customer_name="Asha Verma",
+            customer_tier="enterprise",
+            company="Kairo Health",
+            subject="EU rollout blocked by intermittent 500s",
+            body=(
+                "We're launching our EU workspace tonight. Since enabling EU data residency we "
+                "see intermittent HTTP 500 responses from /v1/exports in production. Our "
+                "compliance lead is also asking whether this affects the audit trail, but the "
+                "main issue is the outage. We need help immediately."
+            ),
+            region="eu-west-1",
+            affected_users=1800,
+            sla_minutes_remaining=25,
+            business_impact="A production launch and a customer-facing compliance review are both at risk tonight if the outage persists.",
+            secondary_concerns=["The compliance lead is asking whether audit trails are affected, but the live outage is the primary incident."],
+            attachments=["error_screenshot.png"],
+        ),
+        knowledge_base=(
+            KnowledgeSnippet(
+                article_id="INC-301",
+                title="Production availability incidents",
+                content=(
+                    "Any active production 5xx incident for a paying customer routes to "
+                    "platform_engineering with urgent priority and should be escalated, not resolved."
+                ),
+            ),
+            KnowledgeSnippet(
+                article_id="INC-302",
+                title="Minimum diagnostics for API incidents",
+                content=(
+                    "Before engineering can investigate, request concrete examples including "
+                    "request_ids, UTC timestamps, and the affected region."
+                ),
+            ),
+            KnowledgeSnippet(
+                article_id="INC-303",
+                title="Customer communication during an incident",
+                content=(
+                    "The reply should acknowledge an incident, say the on-call engineering team "
+                    "is engaged, and ask for the diagnostics needed to speed investigation."
+                ),
+            ),
+            KnowledgeSnippet(
+                article_id="INC-304",
+                title="Primary issue triage rule",
+                content=(
+                    "When a production outage appears alongside a secondary compliance or audit "
+                    "question, resolve the live outage first and avoid treating the secondary "
+                    "question as the primary queue-driving issue."
+                ),
+            ),
+        ),
+        gold_queue="platform_engineering",
+        gold_priority="urgent",
+        gold_issue_type="production_incident",
+        gold_status="escalated",
+        gold_resolution_code="incident_opened",
+        required_requested_fields=("request_ids", "timestamp_utc", "region"),
+        required_reply_markers=(
+            ("incident", "outage", "investigating"),
+            ("on-call", "engineering team", "engineering is engaged"),
+            ("request id", "request_ids"),
+            ("utc", "timestamp"),
+        ),
+        required_note_markers=(
+            ("eu data residency", "eu rollout"),
+            ("500", "http 500"),
+            ("launch tonight", "tonight"),
+        ),
+    ),
+}
+
+
+def get_task(task_id: str) -> SupportTaskSpec:
+    """Return a task definition or raise a helpful error."""
+
+    try:
+        return TASKS[task_id]
+    except KeyError as exc:  # pragma: no cover - defensive
+        valid = ", ".join(sorted(TASKS))
+        raise ValueError(f"Unknown task_id '{task_id}'. Valid task ids: {valid}") from exc
+
+
+def list_task_ids() -> list[str]:
+    """List tasks in a stable evaluation order."""
+
+    return list(TASKS)

tasks.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the real supportdesk_env package."""
+
+from supportdesk_env.tasks import *  # noqa: F401,F403

tests/test_supportdesk.py

@@ -0,0 +1,58 @@
+"""Smoke tests for the SupportDesk environment."""
+
+from supportdesk_env.graders import grade_case
+from supportdesk_env.models import SupportDeskAction
+from supportdesk_env.server.supportdesk_environment import SupportDeskEnvironment
+from supportdesk_env.tasks import get_task, list_task_ids
+
+
+def test_all_tasks_are_registered():
+    assert list_task_ids() == [
+        "billing_refund_easy",
+        "account_takeover_medium",
+        "api_incident_hard",
+    ]
+
+
+def test_environment_reset_and_state():
+    env = SupportDeskEnvironment(task_id="billing_refund_easy")
+    observation = env.reset()
+    assert observation.task_id == "billing_refund_easy"
+    assert env.state.step_count == 0
+    assert env.state.current_score == 0.15
+
+
+def test_perfect_solution_grades_full_score():
+    task = get_task("billing_refund_easy")
+    env = SupportDeskEnvironment(task_id=task.task_id)
+    env.reset()
+    env.step(
+        SupportDeskAction(
+            operation="classify",
+            queue=task.gold_queue,
+            priority=task.gold_priority,
+            issue_type=task.gold_issue_type,
+        )
+    )
+    env.step(
+        SupportDeskAction(
+            operation="draft_reply",
+            reply="Refund approved for the duplicate charge and it should arrive within 5-7 business days.",
+        )
+    )
+    env.step(
+        SupportDeskAction(
+            operation="add_internal_note",
+            internal_note="Duplicate charge verified and refund approved.",
+        )
+    )
+    env.step(
+        SupportDeskAction(
+            operation="submit",
+            status=task.gold_status,
+            resolution_code=task.gold_resolution_code,
+        )
+    )
+
+    breakdown = grade_case(task, env.state.case)
+    assert breakdown.total_score == 1.0