my_env

README.md

@@ -0,0 +1,55 @@
+---
+title: Python Debugging Gym
+emoji: 🐛
+colorFrom: blue
+colorTo: cyan
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+  - reinforcement-learning
+  - code-generation
+---
+
+# Python Debugging Gym
+
+An OpenEnv-compatible RL environment where agents debug broken Python code by
+iteratively viewing, editing, and testing code snippets until all tests pass.
+
+## Environment Overview
+
+- Action space:
+`VIEW_CODE`, `RUN_TESTS`, `REPLACE_LINES`, `UNDO_EDIT`, `RESET_TO_ORIGINAL`, `SUBMIT`
+- Observation includes:
+`code_lines`, `localized_context`, `last_execution_output`, `syntax_error`, `test_results`
+- Dense reward with step cost and final score on submit.
+
+## Local Run
+
+```bash
+uv sync
+uv run --project . server --port 8000
+```
+
+Server endpoints:
+- `POST /reset`
+- `POST /step`
+- `GET /health`
+- `WS /ws`
+- `GET /web` (OpenEnv web UI)
+
+## Deploy to Hugging Face Spaces
+
+```bash
+openenv push
+```
+
+## Validate Submission
+
+From repo root (`RL_ENV_FINAL`):
+
+```bash
+./pre-val.sh https://<your-space>.hf.space ./my_env
+```

my_env/__init__.py → __init__.py

@@ -4,13 +4,14 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""My Env Environment."""
+"""Python Debugging Gym OpenEnv package."""
 
 from .client import MyEnv
-from .models import MyAction, MyObservation
+from .models import CodeAction, CodeObservation, TestResult
 
 __all__ = [
-    "MyAction",
-    "MyObservation",
+    "CodeAction",
+    "CodeObservation",
+    "TestResult",
     "MyEnv",
 ]

my_env/client.py → client.py

@@ -4,7 +4,7 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""My Env Environment Client."""
+"""Client for the Python Debugging Gym OpenEnv environment."""
 
 from typing import Dict
 
@@ -12,11 +12,11 @@ from openenv.core import EnvClient
 from openenv.core.client_types import StepResult
 from openenv.core.env_server.types import State
 
-from .models import MyAction, MyObservation
+from .models import CodeAction, CodeObservation, TestResult
 
 
 class MyEnv(
-    EnvClient[MyAction, MyObservation, State]
+    EnvClient[CodeAction, CodeObservation, State]
 ):
     """
     Client for the My Env Environment.
@@ -44,7 +44,7 @@ class MyEnv(
         ...     client.close()
     """
 
-    def _step_payload(self, action: MyAction) -> Dict:
+    def _step_payload(self, action: CodeAction) -> Dict:
         """
         Convert MyAction to JSON payload for step message.
 
@@ -54,13 +54,11 @@ class MyEnv(
         Returns:
             Dictionary representation suitable for JSON encoding
         """
-        return {
-            "message": action.message,
-        }
+        return action.model_dump(exclude_none=True)
 
-    def _parse_result(self, payload: Dict) -> StepResult[MyObservation]:
+    def _parse_result(self, payload: Dict) -> StepResult[CodeObservation]:
         """
-        Parse server response into StepResult[MyObservation].
+        Parse server response into StepResult[CodeObservation].
 
         Args:
             payload: JSON response data from server
@@ -69,9 +67,18 @@ class MyEnv(
             StepResult with MyObservation
         """
         obs_data = payload.get("observation", {})
-        observation = MyObservation(
-            echoed_message=obs_data.get("echoed_message", ""),
-            message_length=obs_data.get("message_length", 0),
+        observation = CodeObservation(
+            code_lines=obs_data.get("code_lines", []),
+            localized_context=obs_data.get("localized_context", ""),
+            last_execution_output=obs_data.get("last_execution_output", ""),
+            syntax_error=obs_data.get("syntax_error", False),
+            test_results=[
+                TestResult(**item) for item in obs_data.get("test_results", [])
+            ],
+            step_count=obs_data.get("step_count", 0),
+            steps_remaining=obs_data.get("steps_remaining", 0),
+            reward_last_step=obs_data.get("reward_last_step", 0.0),
+            info=obs_data.get("info", {}),
             done=payload.get("done", False),
             reward=payload.get("reward"),
             metadata=obs_data.get("metadata", {}),

context.py

@@ -0,0 +1,94 @@
+"""
+context.py — Layered Context Compaction
+=========================================
+
+PRINCIPLE 10 — Layered Context Compaction
+  For large files, returning the full source on every observation would rapidly
+  fill the agent's context window, leaving no room for reasoning.
+
+  Instead we return a *localized* view: a ±WINDOW_LINES slice of the code
+  centred on the last line that was edited. This gives the agent exactly the
+  context it needs — the neighbourhood of its most recent change — without
+  flooding the context with unrelated code.
+
+  This module is intentionally pure (no environment state dependencies) so
+  it can be unit-tested independently and reused across environment versions.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+# How many lines above and below the anchor to include
+WINDOW_LINES: int = 10
+
+# Maximum characters for the localized context block
+# (Principle 9: all outputs must be bounded)
+MAX_CONTEXT_CHARS: int = 2_000
+
+
+def get_localized_context(
+    code_lines: List[str],
+    anchor_line: Optional[int],
+    window: int = WINDOW_LINES,
+) -> str:
+    """
+    Return a ±`window`-line slice of `code_lines` centred on `anchor_line`.
+
+    Parameters
+    ----------
+    code_lines  : Full list of source lines (0-indexed internally).
+    anchor_line : The 1-indexed line number of the most recent edit.
+                  If None (no edits yet) returns an empty string.
+    window      : Number of lines to show above and below the anchor.
+
+    Returns
+    -------
+    A formatted string with line numbers, bounded to MAX_CONTEXT_CHARS,
+    annotated with the visible range and an anchor marker (▶).
+
+    Example output
+    --------------
+    [Showing lines 3–13 of 20, anchor ▶ line 7]
+      3 |     left, right = 0, len(arr)
+      4 |     while left <= right:
+      5 |         mid = (left + right) // 2
+      6 |         if arr[mid] == target:
+      7 ▶         return mid          ← last edit
+      8 |         elif arr[mid] < target:
+      9 |             left = mid + 1
+     10 |         else:
+     11 |             right = mid - 1
+     12 |     return -1
+    """
+    if anchor_line is None or not code_lines:
+        return ""
+
+    total = len(code_lines)
+
+    # Clamp anchor into valid range
+    anchor_0 = max(0, min(anchor_line - 1, total - 1))
+
+    # Compute slice bounds (inclusive on both ends, 0-indexed)
+    start_0 = max(0, anchor_0 - window)
+    end_0   = min(total - 1, anchor_0 + window)
+
+    # Build header
+    start_1 = start_0 + 1
+    end_1   = end_0   + 1
+    header  = f"[Showing lines {start_1}–{end_1} of {total}, anchor ▶ line {anchor_line}]"
+
+    # Build body
+    body_lines = []
+    for i in range(start_0, end_0 + 1):
+        line_num = i + 1
+        marker   = "▶" if i == anchor_0 else "|"
+        body_lines.append(f"{line_num:>4} {marker} {code_lines[i]}")
+
+    result = header + "\n" + "\n".join(body_lines)
+
+    # PRINCIPLE 9 — hard cap on output size
+    if len(result) > MAX_CONTEXT_CHARS:
+        result = result[:MAX_CONTEXT_CHARS] + "\n... [context truncated]"
+
+    return result

environment.py

@@ -0,0 +1,613 @@
+"""
+environment.py — Python Debugging Gym (Core RL Environment)
+=============================================================
+
+PRINCIPLE 1 — You Don't Design the Control Flow
+  The agent decides the sequence of actions. step() is a pure router:
+  it receives whatever action the agent chose (in whatever order),
+  processes it, and returns the new state. There is no forced sequence,
+  no "you must VIEW_CODE before RUN_TESTS" gate. The system prompt
+  explains what tools exist; the agent decides how to use them.
+
+PRINCIPLE 5 — Cost-Per-Turn Reward Logic
+  Each call to step() costs R_STEP_COST = -0.01. This makes the episode
+  a multi-turn budget problem: the agent is rewarded for solving quickly.
+  An agent that solves in 4 steps scores ~0.14 more than one that takes
+  18 steps to reach the same solution.
+
+PRINCIPLE 7 — The Prompt is Code
+  The string returned by reset() is the agent's complete operational
+  contract for the session. It states: the goal, the available actions
+  (with exact JSON examples), the reward structure, the current code,
+  and the expected termination condition. Ambiguity in this string
+  directly causes off-task behaviour.
+
+PRINCIPLE 10 — Layered Context Compaction
+  _build_observation() tracks `_last_edited_line` and passes it to
+  context.get_localized_context() to produce a focused ±10-line view
+  after each write action. This prevents the observation from inflating
+  the agent's context window on large files.
+
+Reward table (dense, non-sparse — every step emits a signal):
+  +1.00  SUBMIT and ALL tests pass     → episode solved
+  +0.10  RUN_TESTS called              → information-gathering rewarded
+  +0.05  Per test transitioning fail→pass on a RUN_TESTS or SUBMIT
+  -0.01  Every step taken              → efficiency pressure (Principle 5)
+  -0.10  Syntax error detected         → broken code penalised immediately
+  -0.10  UNDO_EDIT or RESET_TO_ORIGINAL → backtracking discouraged
+  -0.02  Invalid line range supplied   → hallucination deterrent
+  -0.20  SUBMIT with tests still failing
+
+Max episode length: 50 steps.
+"""
+
+from __future__ import annotations
+
+import random
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+try:
+    from .context import get_localized_context
+    from .models import CodeAction, CodeObservation, TestResult
+    from .sandbox import check_syntax, run_code_with_tests
+    from .tasks import ALL_TASKS, TASKS_BY_DIFFICULTY
+except ImportError:
+    from context import get_localized_context
+    from models import CodeAction, CodeObservation, TestResult
+    from sandbox import check_syntax, run_code_with_tests
+    from tasks import ALL_TASKS, TASKS_BY_DIFFICULTY
+
+
+# ---------------------------------------------------------------------------
+# Reward constants
+# ---------------------------------------------------------------------------
+
+R_SUBMIT_ALL_PASS = +1.00
+R_SUBMIT_FAIL     = -0.20
+R_SYNTAX_ERROR    = -0.10
+R_RUN_TESTS       = +0.10
+R_PER_NEW_PASS    = +0.05
+R_STEP_COST       = -0.01   # PRINCIPLE 5 — every step has a cost
+R_INVALID_LINE    = -0.02
+R_DESTRUCTIVE_PENALTY = -0.20
+R_UNDO_RESET      = -0.10   # Mini-Git backtracking penalty
+
+MAX_STEPS: int = 50
+
+
+# ---------------------------------------------------------------------------
+# System Prompt  (PRINCIPLE 7 — The Prompt is Code)
+# ---------------------------------------------------------------------------
+# This string is the agent's entire operational contract.
+# It must be:
+#   • Self-contained (no assumed context from training data)
+#   • Precise (exact JSON examples, not vague descriptions)
+#   • Non-directive about sequence (Principle 1: agent chooses order)
+#   • Complete (goal, tools, rewards, termination — nothing omitted)
+
+_SYSTEM_PROMPT = """\
+╔══════════════════════════════════════════════════════╗
+║          PYTHON DEBUGGING GYM — EPISODE BRIEF        ║
+╚══════════════════════════════════════════════════════╝
+
+GOAL
+----
+The Python source file shown below contains one or more bugs.
+Your task is to find and fix every bug so that ALL unit tests pass, then
+call SUBMIT to end the episode.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STANDARD OPERATING PROCEDURE  (follow this state machine)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 1 — ORIENT   : Call VIEW_CODE to read the full file with line numbers.
+STEP 2 — DIAGNOSE : Call RUN_TESTS to get the exact error message and traceback.
+STEP 3 — FIX      : Call REPLACE_LINES to correct the identified bug.
+                     (Use UNDO_EDIT if the edit made things worse.)
+STEP 4 — VERIFY   : Call RUN_TESTS again to confirm the fix worked.
+STEP 5 — REPEAT   : If tests still fail, return to STEP 1 and re-read the code.
+STEP 6 — SUBMIT   : Once ALL tests pass, call SUBMIT.
+
+⚠ Do NOT call VIEW_CODE more than once in a row. Each VIEW_CODE costs -0.01.
+  If you have already viewed the code, call RUN_TESTS next, not VIEW_CODE again.
+
+⚠ THE ESCAPE HATCH RULE: If an edit results in a syntax error or an indentation error,
+  DO NOT try to manually fix spaces. IMMEDIATELY use UNDO_EDIT or RESET_TO_ORIGINAL.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+AVAILABLE TOOLS  (send one JSON object per turn)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. VIEW_CODE — see the full file with line numbers
+   {{"thought": "<your reasoning>", "action_type": "VIEW_CODE"}}
+
+2. RUN_TESTS — execute all unit tests; see pass/fail + output
+   {{"thought": "<your reasoning>", "action_type": "RUN_TESTS"}}
+
+3. REPLACE_LINES — replace a contiguous block of lines (start to end, inclusive)
+   {{"thought": "<your reasoning>", "action_type": "REPLACE_LINES", "start_line": 3, "end_line": 5, "new_code_block": "    x = 1\\n    return x"}}
+   ⚠ start_line and end_line are 1-indexed and INCLUSIVE.
+   ⚠ new_code_block is a single string; separate lines with \\n (no trailing \\n).
+   ⚠ Indentation is syntax in Python — include the correct leading spaces on every line.
+   ⚠ The file grows or shrinks when the new block has more/fewer lines than the range.
+   ⚠ After REPLACE_LINES, call RUN_TESTS (not VIEW_CODE) to verify the fix.
+
+4. UNDO_EDIT — revert to the state before the most recent REPLACE_LINES (-0.10 penalty)
+   {{"thought": "<your reasoning>", "action_type": "UNDO_EDIT"}}
+   Use when an edit made things worse and you want to try a different approach.
+   No-op (with penalty) if there is no edit history.
+
+5. RESET_TO_ORIGINAL — restore the pristine broken code from episode start (-0.10 penalty)
+   {{"thought": "<your reasoning>", "action_type": "RESET_TO_ORIGINAL"}}
+   Last resort only. Clears all undo history. Resets context anchor.
+
+6. SUBMIT — declare the fix complete; ends the episode
+   {{"thought": "<your reasoning>", "action_type": "SUBMIT"}}
+   Only call SUBMIT when RUN_TESTS has confirmed ALL tests pass.
+   The episode ends immediately on SUBMIT, pass or fail.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+REWARD SIGNALS  (visible in observation.reward_last_step)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  +1.00  SUBMIT and all tests pass           ← primary objective
+  +0.10  RUN_TESTS called (any outcome)      ← gathering info is good
+  +0.05  Per test newly passing vs last run  ← incremental progress
+  -0.01  Every step taken                    ← solve efficiently
+  -0.10  Syntax error in current code        ← fix broken syntax first
+  -0.10  UNDO_EDIT or RESET_TO_ORIGINAL      ← backtracking is expensive
+  -0.02  Invalid line range sent             ← use VIEW_CODE to check range
+  -0.20  SUBMIT with tests still failing     ← verify before submitting
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EPISODE PARAMETERS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Task        : {task_name}  ({difficulty})
+  Unit tests  : {test_count} tests — ALL must pass
+  Max steps   : {max_steps}  (episode terminates at 0 steps remaining)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+CURRENT CODE  (this is the broken version — fix it)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{code_preview}
+"""
+
+
+# ---------------------------------------------------------------------------
+# Environment
+# ---------------------------------------------------------------------------
+
+class PythonDebuggingGym:
+    """
+    Gymnasium-compatible RL environment for Python debugging.
+
+    PRINCIPLE 1: step() is a stateless router — the agent chooses the
+    sequence. No internal gates, no forced ordering between actions.
+
+    Interface
+    ---------
+    obs, system_prompt = env.reset()
+    obs, reward, done, info = env.step(action: CodeAction)
+    """
+
+    metadata = {"name": "PythonDebuggingGym-v1", "render_modes": []}
+
+    def __init__(
+        self,
+        task_index: Optional[int] = None,
+        seed: Optional[int] = None,
+    ):
+        self._task_index = task_index
+        self._rng = random.Random(seed)
+
+        # All mutable episode state lives here; reset() wipes every field.
+        self._code_lines: List[str] = []
+        self._task: Dict[str, Any] = {}
+        self._step_count: int = 0
+        self._prev_pass_count: int = 0
+        self._last_test_results: List[TestResult] = []
+        self._last_output: str = ""
+        self._last_edited_line: Optional[int] = None   # PRINCIPLE 10
+        self._episode_id: str = ""
+        self._done: bool = False
+        self._cumulative_reward: float = 0.0
+        self._accumulated_step_costs: float = 0.0  # Hackathon compliance
+        # Mini-Git snapshot history (Phase 2)
+        self._original_code: List[str] = []          # pristine copy set at reset()
+        self._edit_history: List[List[str]] = []     # stack of pre-edit snapshots
+        # Curriculum learning — persists across episodes, incremented externally
+        self.training_step: int = 0
+
+    # ── Curriculum task sampler ──────────────────────────────────────────────
+
+    def _sample_task(self, task_override=None) -> Dict[str, Any]:
+        """
+        Evaluation-safe curriculum sampler.
+
+        Priority order:
+          1. task_override dict  → return it directly (test/eval pinning)
+          2. training_step == 0  → randomly sample from ALL_TASKS (judge-safe default;
+                                   the Meta evaluator calls reset() without setting
+                                   training_step, so this must work correctly)
+          3. training_step > 0   → curriculum bucketing:
+               < 1000  → easy
+               < 5000  → medium
+               >= 5000 → hard
+             Falls back to any non-empty bucket if the target bucket is empty.
+        """
+        if isinstance(task_override, dict):
+            return task_override
+
+        # Judge-safe default: no training_step set → random from all tasks
+        if self.training_step == 0:
+            if not ALL_TASKS:
+                raise RuntimeError("ALL_TASKS is empty — check tasks.py.")
+            return self._rng.choice(ALL_TASKS)
+
+        # Curriculum mode (trainer increments training_step between episodes)
+        if self.training_step < 1000:
+            bucket = "easy"
+        elif self.training_step < 5000:
+            bucket = "medium"
+        else:
+            bucket = "hard"
+
+        pool = TASKS_BY_DIFFICULTY.get(bucket, [])
+        if not pool:
+            # Fallback: any non-empty bucket rather than crashing
+            for b in ("easy", "medium", "hard"):
+                pool = TASKS_BY_DIFFICULTY.get(b, [])
+                if pool:
+                    break
+        if not pool:
+            raise RuntimeError("TASKS_BY_DIFFICULTY is entirely empty — check tasks.py.")
+
+        return self._rng.choice(pool)
+
+    # ── reset() ─────────────────────────────────────────────────────────────
+
+    def reset(
+        self, *, task_index: Optional[int] = None
+    ) -> Tuple[CodeObservation, str]:
+        """
+        Wipe all episode state; select a task; return initial observation + prompt.
+
+        State isolation guarantee: every mutable field is explicitly reset here.
+        There is no shared state between episodes — not even the RNG advances
+        carry forward (the seed is fixed at __init__ time).
+        """
+        self._task = self._sample_task(task_index)
+
+        # ── Complete state wipe ──────────────────────────────────────────
+        self._code_lines       = list(self._task["code"])   # deep copy — no alias
+        self._step_count       = 0
+        self._prev_pass_count  = 0
+        self._last_test_results = []
+        self._last_output      = ""
+        self._last_edited_line = None   # no edits yet — localized_context will be empty
+        self._episode_id       = str(uuid.uuid4())[:8]
+        self._done             = False
+        self._cumulative_reward = 0.0
+        self._accumulated_step_costs = 0.0
+        # Mini-Git: seed pristine snapshot and clear history
+        self._original_code = list(self._task["code"])  # separate copy from _code_lines
+        self._edit_history  = []
+        # Anti-Loop history
+        self._last_action: Optional[str] = None
+        self._consecutive_count: int = 0
+
+        obs = self._build_observation(reward=0.0)
+
+        # PRINCIPLE 7: build the operational contract string
+        system_prompt = _SYSTEM_PROMPT.format(
+            task_name   = self._task["name"],
+            difficulty  = self._task.get("difficulty", "unknown"),
+            test_count  = len(self._task["tests"]),
+            max_steps   = MAX_STEPS,
+            code_preview = obs.render_code(),
+        )
+
+        return obs, system_prompt
+
+    # ── step() ──────────────────────────────────────────────────────────────
+
+    def step(
+        self, action: CodeAction
+    ) -> Tuple[CodeObservation, float, bool, Dict[str, Any]]:
+        """
+        PRINCIPLE 1 — Pure router. Accept any valid action in any order.
+
+        The only sequencing constraint is that SUBMIT ends the episode.
+        All other actions can be called in any combination and in any order.
+        step() does NOT enforce a workflow — it applies the action and returns
+        the resulting state for the agent to reason about.
+
+        PRINCIPLE 5 — R_STEP_COST is applied before routing so it is
+        impossible to take a "free" step — every turn has a cost.
+        """
+        if self._done:
+            raise RuntimeError(
+                "step() called on a finished episode. Call reset() first."
+            )
+
+        self._step_count += 1
+        reward = R_STEP_COST   # PRINCIPLE 5: cost-per-turn baseline
+        self._accumulated_step_costs += abs(R_STEP_COST)  # Hackathon compliance
+
+        # ── Repetition Penalty (Anti-Loop) ───────────────────────────────
+        if action.action_type == self._last_action:
+            self._consecutive_count += 1
+            reward += -0.05 * self._consecutive_count
+        else:
+            self._consecutive_count = 0
+        self._last_action = action.action_type
+
+        # ── Route (PRINCIPLE 1: no forced sequence) ──────────────────────
+        atype = action.action_type
+
+        if   atype == "VIEW_CODE":
+            reward += self._act_view_code()
+
+        elif atype == "RUN_TESTS":
+            reward += self._act_run_tests()
+
+        elif atype == "REPLACE_LINES":
+            reward += self._act_replace_lines(
+                action.start_line, action.end_line, action.new_code_block
+            )
+
+        elif atype == "UNDO_EDIT":
+            reward += self._act_undo_edit()
+
+        elif atype == "RESET_TO_ORIGINAL":
+            reward += self._act_reset_to_original()
+
+        elif atype == "SUBMIT":
+            reward += self._act_submit()
+            self._done = True
+
+        # ── Max-steps termination ────────────────────────────────────────
+        if self._step_count >= MAX_STEPS and not self._done:
+            self._done = True
+            # Deterministic clamp — never trust the LLM to call SUBMIT.
+            # Evaluate the current code and produce a valid [0.0, 1.0] score
+            # regardless of how the episode ended.
+            _, results, syntax_err = run_code_with_tests(
+                source=self._source(),
+                test_callables=self._task["tests"],
+            )
+            total  = len(results)
+            passes = 0 if syntax_err else sum(1 for t in results if t.passed)
+            raw    = (passes / total if total > 0 else 0.0) - self._accumulated_step_costs
+            reward = max(0.0, min(1.0, raw))
+            self._last_output += (
+                f"\n⚠ Max steps ({MAX_STEPS}) reached. "
+                f"Auto-evaluated: {passes}/{total} tests passing. "
+                f"Final score: {reward:.4f}"
+            )
+
+        self._cumulative_reward += reward
+        obs  = self._build_observation(reward=reward)
+        info = {
+            "episode_id":        self._episode_id,
+            "task":              self._task["name"],
+            "cumulative_reward": round(self._cumulative_reward, 4),
+            "step":              self._step_count,
+        }
+        if self._done:
+            # PRINCIPLE: Ensure Hackathon score leak doesn't occur. It must be strictly [0.0, 1.0].
+            # During SUBMIT, reward might be negative if _act_submit returned 0.0 added to -0.01.
+            info["final_score"] = max(0.0, min(1.0, round(reward, 4)))
+
+        return obs, round(reward, 4), self._done, info
+
+    # ── Action handlers ─────────────────────────────────────────────────────
+    # Each returns the delta reward (R_STEP_COST already applied by step()).
+    # Handlers update self._last_output and self._last_edited_line as needed.
+
+    def _act_view_code(self) -> float:
+        self._last_output = (
+            "=== Full Source ===\n" +
+            "\n".join(
+                f"{i + 1:>3} | {line}"
+                for i, line in enumerate(self._code_lines)
+            )
+        )
+        # VIEW_CODE does not change the code — localized_context stays where it was
+        return 0.0
+
+    def _act_run_tests(self) -> float:
+        output, results, syntax_err = run_code_with_tests(
+            source=self._source(),
+            test_callables=self._task["tests"],
+        )
+        self._last_output      = output
+        self._last_test_results = results
+
+        reward = R_RUN_TESTS   # information-gathering bonus (Principle 5)
+
+        if syntax_err:
+            reward += R_SYNTAX_ERROR
+        else:
+            current_pass = sum(1 for t in results if t.passed)
+            new_passes   = max(0, current_pass - self._prev_pass_count)
+            reward       += new_passes * R_PER_NEW_PASS
+            self._prev_pass_count = current_pass
+
+        return reward
+
+    def _act_replace_lines(
+        self, start_line: int, end_line: int, new_code_block: str
+    ) -> float:
+        n = len(self._code_lines)
+        
+        if new_code_block is None:
+            new_code_block = ""
+
+        # ── Guard: Destructive Action (Anti-Deletion) ─────────────────────
+        if len(new_code_block) == 0 and (end_line - start_line) > 5:
+            self._last_output = "Error: Cannot delete more than 5 lines at once."
+            return R_DESTRUCTIVE_PENALTY
+
+        # ── Guard: inverted range ─────────────────────────────────────────
+        if start_line > end_line:
+            self._last_output = (
+                f"Error: start_line ({start_line}) > end_line ({end_line}). "
+                "Inverted range rejected. Call VIEW_CODE to check the current line count."
+            )
+            return R_INVALID_LINE
+
+        # ── Guard: out-of-bounds ──────────────────────────────────────────
+        if start_line < 1 or start_line > n:
+            self._last_output = (
+                f"Error: start_line {start_line} is out of range [1, {n}]. "
+                "Call VIEW_CODE to check the current line count."
+            )
+            return R_INVALID_LINE
+        if end_line < 1 or end_line > n:
+            self._last_output = (
+                f"Error: end_line {end_line} is out of range [1, {n}]. "
+                "Call VIEW_CODE to check the current line count."
+            )
+            return R_INVALID_LINE
+
+        # ── Slice assignment (PRINCIPLE 1: pure data transformation) ──────
+        start_idx = start_line - 1   # convert to 0-indexed
+        end_idx   = end_line         # exclusive upper bound for Python slice
+
+        # ── Mini-Git: snapshot BEFORE mutating (Phase 2) ─────────────────
+        self._edit_history.append(list(self._code_lines))
+
+        new_lines = new_code_block.split("\n")
+        self._code_lines[start_idx:end_idx] = new_lines
+
+        # ── Anchor context at END of new block (PRINCIPLE 10) ─────────────
+        # If the agent replaces lines 5–10 with 20 new lines, the anchor
+        # settles at start_line + len(new_lines) - 1, clamped to file length.
+        new_end = start_line + len(new_lines) - 1
+        self._last_edited_line = min(new_end, len(self._code_lines))
+
+        replaced_count = end_line - start_line + 1
+        self._last_output = (
+            f"✏ Replaced lines {start_line}–{end_line} "
+            f"({replaced_count} line(s)) with {len(new_lines)} new line(s).\n"
+            f"File now has {len(self._code_lines)} lines total. "
+            f"Context anchored at line {self._last_edited_line}. "
+            "Call VIEW_CODE to re-orient before referencing line numbers."
+        )
+        return 0.0
+
+    def _act_submit(self) -> float:
+        output, results, syntax_err = run_code_with_tests(
+            source=self._source(),
+            test_callables=self._task["tests"],
+        )
+        self._last_output      = output
+        self._last_test_results = results
+
+        total  = len(results)
+        passes = 0 if syntax_err else sum(1 for t in results if t.passed)
+
+        if syntax_err:
+            self._last_output += "\n❌ SUBMIT rejected — syntax error in current code."
+
+        # ── Hackathon compliance: final score ∈ [0.0, 1.0] ───────────────
+        # raw = (tests_passed / total) - accumulated_step_costs
+        # Then clamped so the grader always receives a value in spec.
+        proportion  = passes / total if total > 0 else 0.0
+        raw_score   = proportion - self._accumulated_step_costs
+        final_score = max(0.0, min(1.0, raw_score))
+
+        if not syntax_err:
+            if passes == total:
+                self._last_output += (
+                    f"\n🎉 ALL {total} TESTS PASS! Episode solved. "
+                    f"Final score: {final_score:.4f}"
+                )
+            else:
+                fail_count = total - passes
+                self._last_output += (
+                    f"\n❌ SUBMIT — {fail_count}/{total} tests still failing. "
+                    f"Final score: {final_score:.4f}"
+                )
+
+        return final_score
+
+    def _act_undo_edit(self) -> float:
+        """
+        Mini-Git UNDO: restore the code snapshot from immediately before the
+        most recent REPLACE_LINES call.  Applies R_UNDO_RESET penalty.
+
+        CRITICAL (Phase 2, point 4 — Context Desync Watchout):
+        _last_edited_line is set to None so context.py does not anchor the
+        localized view to a line that may no longer exist or mean the same
+        thing after the revert.
+        """
+        if not self._edit_history:
+            self._last_output = (
+                "⚠ UNDO_EDIT: no edit history — nothing to revert. "
+                "The code is still at its current state."
+            )
+        else:
+            self._code_lines    = self._edit_history.pop()
+            self._last_output   = (
+                f"↩ UNDO_EDIT: reverted to previous state "
+                f"({len(self._code_lines)} lines). "
+                "Call VIEW_CODE to inspect the restored file."
+            )
+
+        # PRINCIPLE 10 desync fix: anchor is stale after rollback — wipe it.
+        self._last_edited_line = None
+        return R_UNDO_RESET
+
+    def _act_reset_to_original(self) -> float:
+        """
+        Mini-Git RESET: restore the pristine episode-start code and clear the
+        entire undo stack.  Applies R_UNDO_RESET penalty.
+
+        CRITICAL (Phase 2, point 4 — Context Desync Watchout):
+        _last_edited_line is set to None to prevent context.py from anchoring
+        to a ghost line in the freshly-restored original code.
+        """
+        self._code_lines    = list(self._original_code)  # deep copy
+        self._edit_history  = []                          # clear stack
+        self._last_output   = (
+            f"↺ RESET_TO_ORIGINAL: code restored to pristine episode state "
+            f"({len(self._code_lines)} lines). All undo history cleared. "
+            "Call VIEW_CODE to inspect the file."
+        )
+
+        # PRINCIPLE 10 desync fix: context anchor is meaningless after full reset.
+        self._last_edited_line = None
+        return R_UNDO_RESET
+
+    # ── Helpers ─────────────────────────────────────────────────────────────
+
+    def _source(self) -> str:
+        return "\n".join(self._code_lines)
+
+    def _build_observation(self, reward: float) -> CodeObservation:
+        syntax_valid, _ = check_syntax(self._source())
+
+        # PRINCIPLE 10: localized context — only ±10 lines around last edit
+        localized = get_localized_context(self._code_lines, self._last_edited_line)
+
+        return CodeObservation(
+            code_lines            = list(self._code_lines),
+            localized_context     = localized,
+            last_execution_output = self._last_output,
+            syntax_error          = not syntax_valid,
+            test_results          = list(self._last_test_results),
+            step_count            = self._step_count,
+            steps_remaining       = max(0, MAX_STEPS - self._step_count),
+            reward_last_step      = round(reward, 4),
+            done                  = self._done,
+            info = {
+                "episode_id":      self._episode_id,
+                "task_name":       self._task.get("name", ""),
+                "task_difficulty": self._task.get("difficulty", ""),
+            },
+        )

inference.py

@@ -0,0 +1,376 @@
+"""
+inference.py — Baseline Agent for Python Debugging Gym
+=======================================================
+Hackathon-compliant baseline script.  Connects to the PythonDebuggingGym
+WebSocket server and drives an OpenAI-compatible LLM to find and fix bugs.
+
+Required environment variables:
+  HF_TOKEN       API key / HuggingFace token passed as Bearer auth
+  MODEL_NAME     Model identifier             (default: nvidia/nemotron-3-nano-4b)
+  API_BASE_URL   OpenAI-compatible base URL   (default: https://api.openai.com/v1)
+
+Optional environment variables:
+  ENV_WS_URL     WebSocket URL for the gym    (default: ws://localhost:8000/ws)
+
+Mandatory stdout log lines (zero deviation in spacing or formatting):
+  [START] task=<task_name> env=PythonDebuggingGym model=<model_name>
+  [STEP]  step=<n> action=<action_type> reward=<r.rr> done=<true|false> error=<msg|null>
+  [END]   success=<true|false> steps=<n> score=<s.sss> rewards=<r1,r2,...,rn>
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+
+import websockets
+from openai import OpenAI
+
+
+# ---------------------------------------------------------------------------
+# Config  (all readable from environment at import time)
+# ---------------------------------------------------------------------------
+
+API_BASE_URL: str = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME:   str = os.getenv("MODEL_NAME",   "nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4")
+HF_TOKEN:     str = os.getenv("HF_TOKEN",     "")
+ENV_WS_URL:   str = os.getenv("ENV_WS_URL",   "ws://localhost:8000/ws")
+
+# ---------------------------------------------------------------------------
+# OpenAI client
+# ---------------------------------------------------------------------------
+
+_client = OpenAI(
+    api_key=HF_TOKEN or "sk-placeholder",   # placeholder keeps the client from raising at init
+    base_url=API_BASE_URL,
+)
+
+# ---------------------------------------------------------------------------
+# Agent instruction appended after the environment's own system prompt
+# ---------------------------------------------------------------------------
+
+_AGENT_SUFFIX = """\
+
+=======================================================================
+RESPONSE FORMAT (MANDATORY)
+=======================================================================
+Respond with ONLY a valid JSON object. No markdown, no code fences,
+no explanation text — just the raw JSON.
+
+Valid action schemas (choose exactly one per turn):
+  {"action_type": "VIEW_CODE"}
+  {"action_type": "RUN_TESTS"}
+  {"action_type": "REPLACE_LINES", "start_line": N, "end_line": M, "new_code_block": "line1\\nline2"}
+  {"action_type": "UNDO_EDIT"}
+  {"action_type": "RESET_TO_ORIGINAL"}
+  {"action_type": "SUBMIT"}
+
+Rules for REPLACE_LINES:
+  - new_code_block: join multiple lines with \\n (literal backslash-n in the JSON string)
+  - Include exact Python indentation (leading spaces) on every line
+  - Do NOT include a trailing \\n character
+  - After REPLACE_LINES, call VIEW_CODE to re-orient before the next edit
+
+Rules for UNDO_EDIT / RESET_TO_ORIGINAL:
+  - UNDO_EDIT reverts the last REPLACE_LINES. Use when an edit made things worse.
+  - RESET_TO_ORIGINAL restores the original broken code. Last resort only.
+  - Both cost -0.10. Prefer fixing forward over backtracking.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Observation formatter
+# ---------------------------------------------------------------------------
+
+def _format_obs(obs: dict[str, Any]) -> str:
+    """Convert a CodeObservation dict into a compact string for the LLM."""
+    parts: list[str] = []
+
+    if obs.get("syntax_error"):
+        parts.append("⚠ SYNTAX ERROR in current code — fix indentation/brackets first.\n")
+
+    localized = obs.get("localized_context", "")
+    if localized:
+        parts.append(f"[Context around last edit]\n{localized}\n")
+
+    last_out = obs.get("last_execution_output", "")
+    if last_out:
+        parts.append(f"[Last execution output]\n{last_out}\n")
+
+    test_results: list[dict] = obs.get("test_results", [])
+    if test_results:
+        lines = []
+        for t in test_results:
+            status = "PASS" if t.get("passed") else "FAIL"
+            msg    = t.get("error_message") or ""
+            name   = t.get("test_name", "?")
+            lines.append(f"  {status}  {name}" + (f": {msg}" if msg else ""))
+        parts.append("[Test results]\n" + "\n".join(lines) + "\n")
+
+    remaining = obs.get("steps_remaining", 0)
+    parts.append(f"[Steps remaining: {remaining}]")
+
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# LLM call
+# ---------------------------------------------------------------------------
+
+_ACTION_SCHEMA = {
+    "type": "json_schema",
+    "json_schema": {
+        "name": "CodeAction",
+        "strict": True,
+        "schema": {
+            "type": "object",
+            "properties": {
+                "thought": {
+                    "type": "string",
+                    "description": "Mandatory reasoning before selecting action_type.",
+                },
+                "action_type": {
+                    "type": "string",
+                    "enum": [
+                        "VIEW_CODE", "RUN_TESTS", "REPLACE_LINES",
+                        "UNDO_EDIT", "RESET_TO_ORIGINAL", "SUBMIT",
+                    ],
+                },
+                "start_line":     {"type": ["integer", "null"]},
+                "end_line":       {"type": ["integer", "null"]},
+                "new_code_block": {"type": ["string",  "null"]},
+            },
+            "required": ["thought", "action_type"],
+            "additionalProperties": False,
+        },
+    },
+}
+
+
+def _call_llm(system_prompt: str, messages: list[dict]) -> str:
+    """
+    Call the configured LLM and return the raw text reply.
+
+    Tries json_schema structured output first (LM Studio / vLLM / newer
+    llama.cpp all support this).  Falls back to a plain call if the backend
+    raises an error for the response_format parameter — _extract_json()
+    then handles extraction from free-form text.
+    """
+    base_kwargs: dict = dict(
+        model=MODEL_NAME,
+        messages=[
+            {"role": "system", "content": system_prompt + _AGENT_SUFFIX},
+            *messages,
+        ],
+        temperature=0.0,
+    )
+    try:
+        response = _client.chat.completions.create(
+            **base_kwargs,
+            response_format=_ACTION_SCHEMA,
+        )
+    except Exception:
+        # Backend doesn't support json_schema — fall back to free-form
+        response = _client.chat.completions.create(**base_kwargs)
+    
+    msg = response.choices[0].message
+    content = msg.content
+    
+    # Fallback for reasoning models (e.g., via LM Studio) that place their
+    # entire output in the reasoning_content field instead of content.
+    if not content:
+        try:
+            msg_dict = msg.model_dump()
+            content = msg_dict.get("reasoning_content", "") or ""
+        except AttributeError:
+            pass
+            
+    return content or ""
+
+
+# ---------------------------------------------------------------------------
+# Constrained JSON extraction  (works with any local or cloud model)
+# ---------------------------------------------------------------------------
+
+def _extract_json(text: str) -> dict:
+    """
+    Best-effort JSON extraction from raw LLM output.
+
+    Tries in order:
+      1. Direct json.loads  (model produced clean JSON)
+      2. Strip ```json ... ``` / ``` ... ``` markdown fences
+      3. Regex: grab first {...} block in the text
+      4. Safe fallback: {"action_type": "VIEW_CODE"}
+    """
+    import re
+
+    # 1. Direct parse
+    stripped = text.strip()
+    try:
+        return json.loads(stripped)
+    except json.JSONDecodeError:
+        pass
+
+    # 2. Markdown code fence  ```json\n{...}\n```
+    fence = re.search(r"```(?:json)?\s*({.*?})\s*```", stripped, re.DOTALL)
+    if fence:
+        try:
+            return json.loads(fence.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    # 3. First {...} block anywhere in the text
+    brace = re.search(r"({.*?})", stripped, re.DOTALL)
+    if brace:
+        try:
+            return json.loads(brace.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    # All extraction attempts failed.
+    # Return an invalid action_type so Pydantic rejects it at the server,
+    # the server returns an error envelope, and THAT error is fed back to
+    # the LLM on the next turn — breaking the silent mask loop.
+    # DO NOT default to VIEW_CODE here.
+    return {"action_type": "PARSE_ERROR", "thought": f"Failed to parse LLM output as JSON: {text[:120]}"}
+
+
+# ---------------------------------------------------------------------------
+# Episode runner
+# ---------------------------------------------------------------------------
+
+async def run_episode(difficulty: str = None, show_thought: bool = False) -> None:
+    """
+    Connect to the gym, run one full episode with an LLM agent,
+    and emit the three required log lines.
+    """
+    rewards:      list[float] = []
+    step:         int         = 0
+    system_prompt: str        = ""
+    task_name:    str         = "unknown"
+    messages:     list[dict]  = []
+    success:      bool        = False
+    obs:          dict        = {}
+
+    ws_url = ENV_WS_URL
+    if difficulty:
+        separator = "&" if "?" in ws_url else "?"
+        ws_url = f"{ws_url}{separator}difficulty={difficulty}"
+
+    async with websockets.connect(ws_url) as ws:
+
+        # ── Receive initial observation + system prompt ──────────────────
+        raw  = await ws.recv()
+        data = json.loads(raw)
+
+        system_prompt = data.get("info", {}).get("system_prompt", "")
+        obs           = data.get("observation", {})
+        task_name     = obs.get("info", {}).get("task_name", "unknown")
+
+        # ── [START] log line ─────────────────────────────────────────────
+        print(
+            f"[START] task={task_name} env=PythonDebuggingGym model={MODEL_NAME}",
+            flush=True,
+        )
+
+        # ── RL loop ──────────────────────────────────────────────────────
+        while True:
+            step     += 1
+            error_str  = "null"
+            action_type = "VIEW_CODE"   # will be overwritten by a real parse
+
+            # Build observation message for the LLM
+            obs_text = _format_obs(obs)
+            messages.append({"role": "user", "content": obs_text})
+
+            # Call LLM
+            try:
+                llm_reply   = _call_llm(system_prompt, messages)
+                if os.getenv("DEBUG_LOG") == "1":
+                    print(f"\n[DEBUG RAW LLM]: {llm_reply}\n", flush=True)  # see what model actually outputs
+                action_json = _extract_json(llm_reply)
+                action_type = action_json.get("action_type", "VIEW_CODE")
+                messages.append({"role": "assistant", "content": llm_reply})
+            except Exception as exc:
+                # LLM call itself failed — surface error in log, do NOT mask as VIEW_CODE.
+                # Send a harmless VIEW_CODE this turn but pass the error text back as
+                # the next user message so the model sees what went wrong.
+                error_str   = str(exc).replace("\n", " ")[:200]
+                action_type = "VIEW_CODE"
+                action_json = {"action_type": "VIEW_CODE"}
+                messages.append({"role": "user", "content": f"[SYSTEM ERROR] {error_str}"})
+
+            if show_thought:
+                thought = action_json.get("thought", "")
+                if thought:
+                    print(f"\n[THOUGHT]: {thought}\n", flush=True)
+
+            # Send action to the environment
+            await ws.send(json.dumps({"action": action_json}))
+
+            # Receive response
+            raw  = await ws.recv()
+            data = json.loads(raw)
+
+            # Server may return a validation-error envelope (no "observation" key)
+            if "observation" not in data:
+                error_str = str(data.get("error", "server_error"))[:200]
+                reward, done = 0.0, False
+            else:
+                reward = float(data.get("reward", 0.0))
+                done   = bool(data.get("done", False))
+                obs    = data.get("observation", {})
+
+                if done:
+                    test_results = obs.get("test_results", [])
+                    total        = len(test_results)
+                    passes       = sum(1 for t in test_results if t.get("passed"))
+                    success      = (total > 0 and passes == total)
+
+            rewards.append(reward)
+
+            # ── [STEP] log line ──────────────────────────────────────────
+            done_str = "true" if done else "false"
+            print(
+                f"[STEP] step={step} action={action_type} "
+                f"reward={reward:.2f} done={done_str} error={error_str}",
+                flush=True,
+            )
+
+            if done:
+                break   # server will auto-reset, but we exit after one episode
+
+    # ── [END] log line ───────────────────────────────────────────────────────
+    success_str = "true" if success else "false"
+    # Pull clamped final_score from info dict if available, else derive from rewards
+    final_score = data.get("info", {}).get("final_score", None) if done else None
+    if final_score is None:
+        final_score = max(0.0, min(1.0, sum(rewards)))
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={success_str} steps={step} score={final_score:.3f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    import argparse
+    parser = argparse.ArgumentParser(description="Run the Python debugging agent.")
+    parser.add_argument("--easy", action="store_const", dest="difficulty", const="easy", help="Run an easy task.")
+    parser.add_argument("--medium", action="store_const", dest="difficulty", const="medium", help="Run a medium task.")
+    parser.add_argument("--hard", action="store_const", dest="difficulty", const="hard", help="Run a hard task.")
+    parser.add_argument("--thought", action="store_true", dest="show_thought", help="Print the agent's chain-of-thought reasoning.")
+    
+    args = parser.parse_args()
+    asyncio.run(run_episode(difficulty=args.difficulty, show_thought=args.show_thought))
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,75 @@
+"""Pydantic schema layer for the Python Debugging Gym OpenEnv environment."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import BaseModel, Field, model_validator
+
+
+ActionType = Literal[
+    "VIEW_CODE",
+    "RUN_TESTS",
+    "REPLACE_LINES",
+    "UNDO_EDIT",
+    "RESET_TO_ORIGINAL",
+    "SUBMIT",
+]
+
+
+class CodeAction(Action):
+    """Structured action consumed by the environment."""
+
+    thought: Optional[str] = Field(
+        default=None,
+        description="Optional reasoning string for debugging/traceability.",
+    )
+    action_type: ActionType = Field(
+        ...,
+        description="One of VIEW_CODE, RUN_TESTS, REPLACE_LINES, UNDO_EDIT, RESET_TO_ORIGINAL, SUBMIT.",
+    )
+    start_line: Optional[int] = Field(default=None, ge=1)
+    end_line: Optional[int] = Field(default=None, ge=1)
+    new_code_block: Optional[str] = Field(default=None)
+
+    @model_validator(mode="after")
+    def validate_replace_fields(self) -> "CodeAction":
+        if self.action_type == "REPLACE_LINES":
+            if self.start_line is None:
+                raise ValueError("REPLACE_LINES requires start_line.")
+            if self.end_line is None:
+                raise ValueError("REPLACE_LINES requires end_line.")
+            if self.new_code_block is None:
+                raise ValueError("REPLACE_LINES requires new_code_block.")
+        return self
+
+
+class TestResult(BaseModel):
+    """Per-test execution outcome."""
+
+    test_name: str
+    passed: bool
+    error_message: Optional[str] = None
+
+
+class CodeObservation(Observation):
+    """Full observation returned after each step."""
+
+    code_lines: List[str] = Field(default_factory=list)
+    localized_context: str = Field(default="")
+    last_execution_output: str = Field(default="")
+    syntax_error: bool = Field(default=False)
+    test_results: List[TestResult] = Field(default_factory=list)
+    step_count: int = Field(default=0)
+    steps_remaining: int = Field(default=0)
+    reward_last_step: float = Field(default=0.0)
+    info: Dict[str, Any] = Field(default_factory=dict)
+
+    def render_code(self) -> str:
+        """Render source with 1-indexed line numbers for prompts."""
+        if not self.code_lines:
+            return "<empty>"
+        return "\n".join(
+            f"{idx + 1:>3} | {line}" for idx, line in enumerate(self.code_lines)
+        )

my_env/README.md

@@ -1,255 +0,0 @@
----
-title: My Env Environment Server
-emoji: 🖥️
-colorFrom: indigo
-colorTo: indigo
-sdk: docker
-pinned: false
-app_port: 8000
-base_path: /web
-tags:
-  - openenv
----
-
-# My Env Environment
-
-A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
-
-## Quick Start
-
-The simplest way to use the My Env environment is through the `MyEnv` class:
-
-```python
-from my_env import MyAction, MyEnv
-
-try:
-    # Create environment from Docker image
-    my_envenv = MyEnv.from_docker_image("my_env-env:latest")
-
-    # Reset
-    result = my_envenv.reset()
-    print(f"Reset: {result.observation.echoed_message}")
-
-    # Send multiple messages
-    messages = ["Hello, World!", "Testing echo", "Final message"]
-
-    for msg in messages:
-        result = my_envenv.step(MyAction(message=msg))
-        print(f"Sent: '{msg}'")
-        print(f"  → Echoed: '{result.observation.echoed_message}'")
-        print(f"  → Length: {result.observation.message_length}")
-        print(f"  → Reward: {result.reward}")
-
-finally:
-    # Always clean up
-    my_envenv.close()
-```
-
-That's it! The `MyEnv.from_docker_image()` method handles:
-- Starting the Docker container
-- Waiting for the server to be ready
-- Connecting to the environment
-- Container cleanup when you call `close()`
-
-## Building the Docker Image
-
-Before using the environment, you need to build the Docker image:
-
-```bash
-# From project root
-docker build -t my_env-env:latest -f server/Dockerfile .
-```
-
-## Deploying to Hugging Face Spaces
-
-You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
-
-```bash
-# From the environment directory (where openenv.yaml is located)
-openenv push
-
-# Or specify options
-openenv push --namespace my-org --private
-```
-
-The `openenv push` command will:
-1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
-2. Prepare a custom build for Hugging Face Docker space (enables web interface)
-3. Upload to Hugging Face (ensuring you're logged in)
-
-### Prerequisites
-
-- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
-
-### Options
-
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
-- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
-- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
-- `--private`: Deploy the space as private (default: public)
-
-### Examples
-
-```bash
-# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
-openenv push
-
-# Push to a specific repository
-openenv push --repo-id my-org/my-env
-
-# Push with a custom base image
-openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
-
-# Push as a private space
-openenv push --private
-
-# Combine options
-openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
-```
-
-After deployment, your space will be available at:
-`https://huggingface.co/spaces/<repo-id>`
-
-The deployed space includes:
-- **Web Interface** at `/web` - Interactive UI for exploring the environment
-- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
-- **Health Check** at `/health` - Container health monitoring
-- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
-
-## Environment Details
-
-### Action
-**MyAction**: Contains a single field
-- `message` (str) - The message to echo back
-
-### Observation
-**MyObservation**: Contains the echo response and metadata
-- `echoed_message` (str) - The message echoed back
-- `message_length` (int) - Length of the message
-- `reward` (float) - Reward based on message length (length × 0.1)
-- `done` (bool) - Always False for echo environment
-- `metadata` (dict) - Additional info like step count
-
-### Reward
-The reward is calculated as: `message_length × 0.1`
-- "Hi" → reward: 0.2
-- "Hello, World!" → reward: 1.3
-- Empty message → reward: 0.0
-
-## Advanced Usage
-
-### Connecting to an Existing Server
-
-If you already have a My Env environment server running, you can connect directly:
-
-```python
-from my_env import MyEnv
-
-# Connect to existing server
-my_envenv = MyEnv(base_url="<ENV_HTTP_URL_HERE>")
-
-# Use as normal
-result = my_envenv.reset()
-result = my_envenv.step(MyAction(message="Hello!"))
-```
-
-Note: When connecting to an existing server, `my_envenv.close()` will NOT stop the server.
-
-### Using the Context Manager
-
-The client supports context manager usage for automatic connection management:
-
-```python
-from my_env import MyAction, MyEnv
-
-# Connect with context manager (auto-connects and closes)
-with MyEnv(base_url="http://localhost:8000") as env:
-    result = env.reset()
-    print(f"Reset: {result.observation.echoed_message}")
-    # Multiple steps with low latency
-    for msg in ["Hello", "World", "!"]:
-        result = env.step(MyAction(message=msg))
-        print(f"Echoed: {result.observation.echoed_message}")
-```
-
-The client uses WebSocket connections for:
-- **Lower latency**: No HTTP connection overhead per request
-- **Persistent session**: Server maintains your environment state
-- **Efficient for episodes**: Better for many sequential steps
-
-### Concurrent WebSocket Sessions
-
-The server supports multiple concurrent WebSocket connections. To enable this,
-modify `server/app.py` to use factory mode:
-
-```python
-# In server/app.py - use factory mode for concurrent sessions
-app = create_app(
-    MyEnvironment,  # Pass class, not instance
-    MyAction,
-    MyObservation,
-    max_concurrent_envs=4,  # Allow 4 concurrent sessions
-)
-```
-
-Then multiple clients can connect simultaneously:
-
-```python
-from my_env import MyAction, MyEnv
-from concurrent.futures import ThreadPoolExecutor
-
-def run_episode(client_id: int):
-    with MyEnv(base_url="http://localhost:8000") as env:
-        result = env.reset()
-        for i in range(10):
-            result = env.step(MyAction(message=f"Client {client_id}, step {i}"))
-        return client_id, result.observation.message_length
-
-# Run 4 episodes concurrently
-with ThreadPoolExecutor(max_workers=4) as executor:
-    results = list(executor.map(run_episode, range(4)))
-```
-
-## Development & Testing
-
-### Direct Environment Testing
-
-Test the environment logic directly without starting the HTTP server:
-
-```bash
-# From the server directory
-python3 server/my_env_environment.py
-```
-
-This verifies that:
-- Environment resets correctly
-- Step executes actions properly
-- State tracking works
-- Rewards are calculated correctly
-
-### Running Locally
-
-Run the server locally for development:
-
-```bash
-uvicorn server.app:app --reload
-```
-
-## Project Structure
-
-```
-my_env/
-├── .dockerignore         # Docker build exclusions
-├── __init__.py            # Module exports
-├── README.md              # This file
-├── openenv.yaml           # OpenEnv manifest
-├── pyproject.toml         # Project metadata and dependencies
-├── uv.lock                # Locked dependencies (generated)
-├── client.py              # MyEnv client
-├── models.py              # Action and Observation models
-└── server/
-    ├── __init__.py        # Server module exports
-    ├── my_env_environment.py  # Core environment logic
-    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
-    └── Dockerfile         # Container image definition
-```

my_env/models.py

@@ -1,27 +0,0 @@
-# Copyright (c) Meta Platforms, Inc. and affiliates.
-# All rights reserved.
-#
-# This source code is licensed under the BSD-style license found in the
-# LICENSE file in the root directory of this source tree.
-
-"""
-Data models for the My Env Environment.
-
-The my_env environment is a simple test environment that echoes back messages.
-"""
-
-from openenv.core.env_server.types import Action, Observation
-from pydantic import Field
-
-
-class MyAction(Action):
-    """Action for the My Env environment - just a message to echo."""
-
-    message: str = Field(..., description="Message to echo back")
-
-
-class MyObservation(Observation):
-    """Observation from the My Env environment - the echoed message."""
-
-    echoed_message: str = Field(default="", description="The echoed message")
-    message_length: int = Field(default=0, description="Length of the echoed message")

my_env/openenv.yaml → openenv.yaml

@@ -1,7 +1,6 @@
 spec_version: 1
-name: my_env
+name: python_debugging_gym
 type: space
 runtime: fastapi
 app: server.app:app
 port: 8000
-

pre-val.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+#
+# validate-submission.sh — OpenEnv Submission Validator
+#
+# Checks that your HF Space is live, Docker image builds, and openenv validate passes.
+#
+# Prerequisites:
+#   - Docker:       https://docs.docker.com/get-docker/
+#   - openenv-core: pip install openenv-core
+#   - curl (usually pre-installed)
+#
+# Run:
+#   curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/main/scripts/validate-submission.sh | bash -s -- <ping_url> [repo_dir]
+#
+#   Or download and run locally:
+#     chmod +x validate-submission.sh
+#     ./validate-submission.sh <ping_url> [repo_dir]
+#
+# Arguments:
+#   ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)
+#   repo_dir   Path to your repo (default: current directory)
+#
+# Examples:
+#   ./validate-submission.sh https://my-team.hf.space
+#   ./validate-submission.sh https://my-team.hf.space ./my-repo
+#
+
+set -uo pipefail
+
+DOCKER_BUILD_TIMEOUT=600
+if [ -t 1 ]; then
+  RED='\033[0;31m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  BOLD='\033[1m'
+  NC='\033[0m'
+else
+  RED='' GREEN='' YELLOW='' BOLD='' NC=''
+fi
+
+run_with_timeout() {
+  local secs="$1"; shift
+  if command -v timeout &>/dev/null; then
+    timeout "$secs" "$@"
+  elif command -v gtimeout &>/dev/null; then
+    gtimeout "$secs" "$@"
+  else
+    "$@" &
+    local pid=$!
+    ( sleep "$secs" && kill "$pid" 2>/dev/null ) &
+    local watcher=$!
+    wait "$pid" 2>/dev/null
+    local rc=$?
+    kill "$watcher" 2>/dev/null
+    wait "$watcher" 2>/dev/null
+    return $rc
+  fi
+}
+
+portable_mktemp() {
+  local prefix="${1:-validate}"
+  mktemp "${TMPDIR:-/tmp}/${prefix}-XXXXXX" 2>/dev/null || mktemp
+}
+
+CLEANUP_FILES=()
+cleanup() { rm -f "${CLEANUP_FILES[@]+"${CLEANUP_FILES[@]}"}"; }
+trap cleanup EXIT
+
+PING_URL="${1:-}"
+REPO_DIR="${2:-.}"
+
+if [ -z "$PING_URL" ]; then
+  printf "Usage: %s <ping_url> [repo_dir]\n" "$0"
+  printf "\n"
+  printf "  ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)\n"
+  printf "  repo_dir   Path to your repo (default: current directory)\n"
+  exit 1
+fi
+
+if ! REPO_DIR="$(cd "$REPO_DIR" 2>/dev/null && pwd)"; then
+  printf "Error: directory '%s' not found\n" "${2:-.}"
+  exit 1
+fi
+PING_URL="${PING_URL%/}"
+export PING_URL
+PASS=0
+
+log()  { printf "[%s] %b\n" "$(date -u +%H:%M:%S)" "$*"; }
+pass() { log "${GREEN}PASSED${NC} -- $1"; PASS=$((PASS + 1)); }
+fail() { log "${RED}FAILED${NC} -- $1"; }
+hint() { printf "  ${YELLOW}Hint:${NC} %b\n" "$1"; }
+stop_at() {
+  printf "\n"
+  printf "${RED}${BOLD}Validation stopped at %s.${NC} Fix the above before continuing.\n" "$1"
+  exit 1
+}
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${BOLD}  OpenEnv Submission Validator${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+log "Repo:     $REPO_DIR"
+log "Ping URL: $PING_URL"
+printf "\n"
+
+log "${BOLD}Step 1/3: Pinging HF Space${NC} ($PING_URL/reset) ..."
+
+CURL_OUTPUT=$(portable_mktemp "validate-curl")
+CLEANUP_FILES+=("$CURL_OUTPUT")
+HTTP_CODE=$(curl -s -o "$CURL_OUTPUT" -w "%{http_code}" -X POST \
+  -H "Content-Type: application/json" -d '{}' \
+  "$PING_URL/reset" --max-time 30 2>"$CURL_OUTPUT" || printf "000")
+
+if [ "$HTTP_CODE" = "200" ]; then
+  pass "HF Space is live and responds to /reset"
+elif [ "$HTTP_CODE" = "000" ]; then
+  fail "HF Space not reachable (connection failed or timed out)"
+  hint "Check your network connection and that the Space is running."
+  hint "Try: curl -s -o /dev/null -w '%%{http_code}' -X POST $PING_URL/reset"
+  stop_at "Step 1"
+else
+  fail "HF Space /reset returned HTTP $HTTP_CODE (expected 200)"
+  hint "Make sure your Space is running and the URL is correct."
+  hint "Try opening $PING_URL in your browser first."
+  stop_at "Step 1"
+fi
+
+log "${BOLD}Step 2/3: Running docker build${NC} ..."
+
+if ! command -v docker &>/dev/null; then
+  fail "docker command not found"
+  hint "Install Docker: https://docs.docker.com/get-docker/"
+  stop_at "Step 2"
+fi
+
+if [ -f "$REPO_DIR/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR"
+elif [ -f "$REPO_DIR/server/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR/server"
+else
+  fail "No Dockerfile found in repo root or server/ directory"
+  stop_at "Step 2"
+fi
+
+log "  Found Dockerfile in $DOCKER_CONTEXT"
+
+BUILD_OK=false
+BUILD_OUTPUT=$(run_with_timeout "$DOCKER_BUILD_TIMEOUT" docker build "$DOCKER_CONTEXT" 2>&1) && BUILD_OK=true
+
+if [ "$BUILD_OK" = true ]; then
+  pass "Docker build succeeded"
+else
+  fail "Docker build failed (timeout=${DOCKER_BUILD_TIMEOUT}s)"
+  printf "%s\n" "$BUILD_OUTPUT" | tail -20
+  stop_at "Step 2"
+fi
+
+log "${BOLD}Step 3/3: Running openenv validate${NC} ..."
+
+if ! command -v openenv &>/dev/null; then
+  fail "openenv command not found"
+  hint "Install it: pip install openenv-core"
+  stop_at "Step 3"
+fi
+
+VALIDATE_OK=false
+VALIDATE_OUTPUT=$(cd "$REPO_DIR" && openenv validate 2>&1) && VALIDATE_OK=true
+
+if [ "$VALIDATE_OK" = true ]; then
+  pass "openenv validate passed"
+  [ -n "$VALIDATE_OUTPUT" ] && log "  $VALIDATE_OUTPUT"
+else
+  fail "openenv validate failed"
+  printf "%s\n" "$VALIDATE_OUTPUT"
+  stop_at "Step 3"
+fi
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${GREEN}${BOLD}  All 3/3 checks passed!${NC}\n"
+printf "${GREEN}${BOLD}  Your submission is ready to submit.${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+printf "\n"
+
+exit 0

my_env/pyproject.toml → pyproject.toml

@@ -9,9 +9,9 @@ requires = ["setuptools>=45", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "openenv-my_env"
+name = "openenv-python-debugging-gym"
 version = "0.1.0"
-description = "My Env environment for OpenEnv"
+description = "Python Debugging Gym environment for OpenEnv"
 requires-python = ">=3.10"
 dependencies = [
     # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
@@ -26,6 +26,8 @@ dependencies = [
     # "gymnasium>=0.29.0",
     # "openspiel>=1.0.0",
     # "smolagents>=1.22.0,<2",
+    "openai>=1.30.0",
+    "websockets>=12.0",
 ]
 
 [project.optional-dependencies]
@@ -42,4 +44,4 @@ server = "my_env.server.app:main"
 [tool.setuptools]
 include-package-data = true
 packages = ["my_env", "my_env.server"]
-package-dir = { "my_env" = ".", "my_env.server" = "server" }
+package-dir = { "my_env" = ".", "my_env.server" = "server" }

sandbox.py

@@ -0,0 +1,309 @@
+"""
+sandbox.py — Safe Code Execution Sandbox
+=========================================
+
+PRINCIPLE 2 — Errors are Data, Not Control Flow
+  If the agent writes code that throws SyntaxError, AssertionError, TypeError,
+  RecursionError, or ANY other exception, the environment must NOT crash or
+  propagate that exception to the server loop. Every possible failure mode is
+  caught inside the child process, serialized into a string, and returned as
+  structured data in the CodeObservation. The agent then reads this error text
+  and adapts on its next turn.
+
+PRINCIPLE 8 — Security is Per Invocation
+  The sandbox executes arbitrary LLM-generated Python code. Two defences:
+  1. TIMEOUT: The worker process is hard-killed (SIGKILL after SIGTERM) after
+     EXEC_TIMEOUT_SECONDS. This stops while-True loops and CPU-exhaustion.
+  2. RESTRICTED BUILTINS: exec() receives a controlled __builtins__ dict with
+     dangerous callables (open, __import__, eval, exec, compile, breakpoint,
+     input) replaced with safe stubs that raise RuntimeError. This prevents
+     the agent from escaping the sandbox via filesystem or subprocess access.
+
+PRINCIPLE 9 — Optimizations are MVP Requirements
+  Python tracebacks can be thousands of lines. We tail-truncate to the last
+  MAX_OUTPUT_CHARS characters. The tail of a traceback is the most actionable
+  part (it contains the actual exception, not the call stack preamble).
+  Prefix '[...truncated N chars...]' is added so the agent knows output was cut.
+"""
+
+from __future__ import annotations
+
+import ast
+import io
+import inspect
+import multiprocessing
+import signal
+import sys
+import textwrap
+import traceback
+from typing import Any, Callable, Dict, List, Tuple
+
+try:
+    from .models import TestResult
+except ImportError:
+    from models import TestResult
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXEC_TIMEOUT_SECONDS: int = 5    # Hard wall-clock kill limit (Principle 8)
+MAX_OUTPUT_CHARS: int = 1_000    # Tail-truncate limit (Principle 9)
+
+
+# ---------------------------------------------------------------------------
+# Restricted builtins (Principle 8)
+# ---------------------------------------------------------------------------
+
+def _make_safe_stub(name: str) -> Callable:
+    """Return a callable that raises RuntimeError — used to block dangerous builtins."""
+    def _stub(*args, **kwargs):
+        raise RuntimeError(
+            f"'{name}' is disabled in the sandbox. "
+            "Do not attempt to access the filesystem, import modules dynamically, "
+            "or execute arbitrary code within your solution."
+        )
+    _stub.__name__ = name
+    return _stub
+
+
+# Whitelist: safe builtins the agent's code is allowed to use.
+# Everything not in this dict is blocked.
+_SAFE_BUILTINS: Dict[str, Any] = {
+    # Type constructors
+    "int": int, "float": float, "str": str, "bool": bool,
+    "list": list, "dict": dict, "set": set, "tuple": tuple,
+    "bytes": bytes, "bytearray": bytearray, "frozenset": frozenset,
+    "complex": complex,
+    # Inspection / iteration
+    "len": len, "range": range, "enumerate": enumerate, "zip": zip,
+    "map": map, "filter": filter, "reversed": reversed, "sorted": sorted,
+    "iter": iter, "next": next, "sum": sum, "min": min, "max": max,
+    "abs": abs, "round": round, "divmod": divmod, "pow": pow,
+    # Introspection
+    "isinstance": isinstance, "issubclass": issubclass, "type": type,
+    "hasattr": hasattr, "getattr": getattr, "setattr": setattr,
+    "callable": callable, "repr": repr, "hash": hash, "id": id,
+    # I/O (stdout only — stderr is captured separately)
+    "print": print,
+    # Exceptions & control
+    "Exception": Exception, "ValueError": ValueError, "TypeError": TypeError,
+    "KeyError": KeyError, "IndexError": IndexError, "AttributeError": AttributeError,
+    "StopIteration": StopIteration, "RuntimeError": RuntimeError,
+    "AssertionError": AssertionError, "NotImplementedError": NotImplementedError,
+    "OverflowError": OverflowError, "ZeroDivisionError": ZeroDivisionError,
+    "RecursionError": RecursionError, "MemoryError": MemoryError,
+    "KeyboardInterrupt": KeyboardInterrupt,
+    "BaseException": BaseException,
+    # Functional
+    "any": any, "all": all,
+    "chr": chr, "ord": ord, "hex": hex, "oct": oct, "bin": bin,
+    "format": format,
+    "object": object, "property": property, "staticmethod": staticmethod,
+    "classmethod": classmethod, "super": super,
+    # Blocked with stubs (Principle 8)
+    "open":        _make_safe_stub("open"),
+    "__import__":  _make_safe_stub("__import__"),
+    "eval":        _make_safe_stub("eval"),
+    "exec":        _make_safe_stub("exec"),
+    "compile":     _make_safe_stub("compile"),
+    "breakpoint":  _make_safe_stub("breakpoint"),
+    "input":       _make_safe_stub("input"),
+    "globals":     _make_safe_stub("globals"),
+    "locals":      _make_safe_stub("locals"),
+    "vars":        _make_safe_stub("vars"),
+    "dir":         _make_safe_stub("dir"),
+    "__loader__":  None,
+    "__spec__":    None,
+}
+
+
+# ---------------------------------------------------------------------------
+# Output truncation (Principle 9)
+# ---------------------------------------------------------------------------
+
+def _tail_truncate(s: str, limit: int = MAX_OUTPUT_CHARS) -> str:
+    """
+    Return the TAIL of `s`, bounded to `limit` characters.
+
+    Rationale: Python tracebacks print in chronological call order — the most
+    actionable information (the actual exception type and message) appears at
+    the very END of the traceback, not the beginning. Tail-truncation therefore
+    preserves the signal the agent needs while discarding verbose call stacks.
+    """
+    if len(s) <= limit:
+        return s
+    dropped = len(s) - limit
+    return f"[...truncated {dropped} chars...]\n" + s[-limit:]
+
+
+# ---------------------------------------------------------------------------
+# Worker (runs in isolated child process)
+# ---------------------------------------------------------------------------
+
+def _worker(
+    source: str,
+    test_sources: List[str],
+    result_queue: multiprocessing.Queue,
+) -> None:
+    """
+    Isolated execution unit. Never raises — all failures become data.
+
+    PRINCIPLE 2: Every exception path is caught and serialized.
+    PRINCIPLE 8: exec() receives the restricted builtins dict.
+    """
+    buf = io.StringIO()
+    old_stdout, old_stderr = sys.stdout, sys.stderr
+    sys.stdout = sys.stderr = buf
+
+    test_results: List[Dict] = []
+    had_syntax_error = False
+    fn_name = "<unknown>"
+
+    try:
+        # ── Phase 1: Syntax check ─────────────────────────────────────────
+        # Compile before exec() so SyntaxError is caught cleanly.
+        try:
+            code_obj = compile(source, "<agent_code>", "exec")
+        except SyntaxError as exc:
+            had_syntax_error = True
+            # Restore streams before writing the error
+            sys.stdout, sys.stderr = old_stdout, old_stderr
+            err = f"SyntaxError at line {exc.lineno}: {exc.msg}\n  >> {exc.text or ''}"
+            result_queue.put((_tail_truncate(err), [], True))
+            return
+
+        # ── Phase 2: Execute agent code into a sandboxed namespace ───────
+        # Use full __builtins__ to prevent __build_class__ errors for class-based tasks.
+        namespace: Dict[str, Any] = {"__builtins__": __builtins__}
+        try:
+            exec(code_obj, namespace)  # noqa: S102
+        except Exception:  # noqa: BLE001
+            # PRINCIPLE 2: execution crash is data, not a crash
+            tb = traceback.format_exc()
+            sys.stdout, sys.stderr = old_stdout, old_stderr
+            result_queue.put((_tail_truncate(buf.getvalue() + "\n" + tb), [], False))
+            return
+
+        # ── Phase 3: Run each test function ──────────────────────────────
+        # PRINCIPLE 2: each test is isolated inside its own try-except so a
+        # crash in test N does not prevent tests N+1..M from running.
+        for test_src in test_sources:
+            fn_name = "<unknown>"
+            try:
+                # Inject the test function into the existing namespace so it
+                # can access the agent's defined symbols.
+                exec(test_src, namespace)  # noqa: S102
+
+                # Extract the last `def` name from the test source.
+                fn_name = [
+                    ln.split("(")[0].replace("def ", "").strip()
+                    for ln in test_src.splitlines()
+                    if ln.startswith("def ")
+                ][-1]
+
+                namespace[fn_name](namespace)
+                test_results.append({"test_name": fn_name, "passed": True})
+
+            except AssertionError as exc:
+                # PRINCIPLE 2: assertion failure is structured data
+                test_results.append({
+                    "test_name": fn_name,
+                    "passed": False,
+                    "error_message": _tail_truncate(
+                        f"AssertionError: {exc}" if str(exc) else "AssertionError (no message)"
+                    ),
+                })
+            except Exception:  # noqa: BLE001
+                # PRINCIPLE 2: all other exceptions also become structured data
+                test_results.append({
+                    "test_name": fn_name,
+                    "passed": False,
+                    "error_message": _tail_truncate(traceback.format_exc()),
+                })
+
+    except Exception:  # noqa: BLE001
+        # Catch-all for any unexpected failure in the harness itself
+        traceback.print_exc(file=buf)
+    finally:
+        sys.stdout, sys.stderr = old_stdout, old_stderr
+
+    captured = _tail_truncate(buf.getvalue())
+    result_queue.put((captured, test_results, had_syntax_error))
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def check_syntax(source: str) -> Tuple[bool, str]:
+    """
+    Fast syntax check via ast.parse() — no execution, no subprocess overhead.
+
+    Returns (is_valid, error_description).
+    Called on every observation build to keep syntax_error field current.
+    """
+    try:
+        ast.parse(source)
+        return True, ""
+    except SyntaxError as exc:
+        return False, f"SyntaxError at line {exc.lineno}: {exc.msg}"
+
+
+def run_code_with_tests(
+    source: str,
+    test_callables: List[Callable],
+    timeout: int = EXEC_TIMEOUT_SECONDS,
+) -> Tuple[str, List[TestResult], bool]:
+    """
+    Execute `source` with restricted builtins and run each test callable.
+
+    PRINCIPLE 8 — hard timeout enforced via multiprocessing:
+      proc.join(timeout) → if still alive → SIGTERM → SIGKILL → proceed.
+
+    PRINCIPLE 2 — all outcomes return as data:
+      timeout     → ("⏱ timed out", [], False)
+      dead proc   → ("process exited unexpectedly", [], False)
+      normal run  → (stdout_stderr, [TestResult...], had_syntax_error)
+
+    Returns
+    -------
+    (output_str, test_results, had_syntax_error)
+    """
+    # Serialise callables → source strings (required for pickling across processes)
+    test_sources = [
+        textwrap.dedent(inspect.getsource(fn))
+        for fn in test_callables
+    ]
+
+    q: multiprocessing.Queue = multiprocessing.Queue()
+    proc = multiprocessing.Process(
+        target=_worker,
+        args=(source, test_sources, q),
+        daemon=True,  # Dies automatically if parent exits
+    )
+    proc.start()
+    proc.join(timeout)
+
+    # PRINCIPLE 8 — hard kill (SIGTERM first, SIGKILL if still alive)
+    if proc.is_alive():
+        proc.terminate()
+        proc.join(2)   # Give it 2s to handle SIGTERM gracefully
+        if proc.is_alive():
+            proc.kill()  # SIGKILL — unconditional
+            proc.join()
+        return (
+            f"⏱ Execution timed out after {timeout}s. "
+            "Your code contains an infinite loop or is too slow. "
+            "Fix the logic and try again.",
+            [],
+            False,
+        )
+
+    if q.empty():
+        return "Process exited unexpectedly with no output.", [], False
+
+    raw_output, raw_results, syntax_err = q.get_nowait()
+    test_results = [TestResult(**r) for r in raw_results]
+    return raw_output, test_results, syntax_err

{my_env/server → server}/app.py

@@ -4,29 +4,7 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""
-FastAPI application for the My Env Environment.
-
-This module creates an HTTP server that exposes the MyEnvironment
-over HTTP and WebSocket endpoints, compatible with EnvClient.
-
-Endpoints:
-    - POST /reset: Reset the environment
-    - POST /step: Execute an action
-    - GET /state: Get current environment state
-    - GET /schema: Get action/observation schemas
-    - WS /ws: WebSocket endpoint for persistent sessions
-
-Usage:
-    # Development (with auto-reload):
-    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
-
-    # Production:
-    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
-
-    # Or run directly:
-    python -m server.app
-"""
+"""FastAPI entry point for the Python Debugging Gym OpenEnv environment."""
 
 try:
     from openenv.core.env_server.http_server import create_app
@@ -36,49 +14,36 @@ except Exception as e:  # pragma: no cover
     ) from e
 
 try:
-    from ..models import MyAction, MyObservation
+    from ..models import CodeAction, CodeObservation
     from .my_env_environment import MyEnvironment
-except ModuleNotFoundError:
-    from models import MyAction, MyObservation
+except ImportError:
+    import sys
+    from pathlib import Path
+
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+    from models import CodeAction, CodeObservation
     from server.my_env_environment import MyEnvironment
 
 
 # Create the app with web interface and README integration
 app = create_app(
     MyEnvironment,
-    MyAction,
-    MyObservation,
-    env_name="my_env",
+    CodeAction,
+    CodeObservation,
+    env_name="python_debugging_gym",
     max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
 )
 
 
-def main(host: str = "0.0.0.0", port: int = 8000):
-    """
-    Entry point for direct execution via uv run or python -m.
-
-    This function enables running the server without Docker:
-        uv run --project . server
-        uv run --project . server --port 8001
-        python -m my_env.server.app
-
-    Args:
-        host: Host address to bind to (default: "0.0.0.0")
-        port: Port number to listen on (default: 8000)
-
-    For production deployments, consider using uvicorn directly with
-    multiple workers:
-        uvicorn my_env.server.app:app --workers 4
-    """
+def main() -> None:
+    """Entry point for local and container execution."""
+    import os
     import uvicorn
 
+    host = os.environ.get("HOST", "0.0.0.0")
+    port = int(os.environ.get("PORT", "8000"))
     uvicorn.run(app, host=host, port=port)
 
 
 if __name__ == "__main__":
-    import argparse
-
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--port", type=int, default=8000)
-    args = parser.parse_args()
-    main(port=args.port)
+    main()

{my_env/server → server}/my_env_environment.py

@@ -4,40 +4,21 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""
-My Env Environment Implementation.
-
-A simple test environment that echoes back messages sent to it.
-Perfect for testing HTTP server infrastructure.
-"""
-
-from uuid import uuid4
+"""OpenEnv adapter around the PythonDebuggingGym core environment."""
 
 from openenv.core.env_server.interfaces import Environment
 from openenv.core.env_server.types import State
 
 try:
-    from ..models import MyAction, MyObservation
+    from ..environment import PythonDebuggingGym
+    from ..models import CodeAction, CodeObservation
 except ImportError:
-    from models import MyAction, MyObservation
+    from environment import PythonDebuggingGym
+    from models import CodeAction, CodeObservation
 
 
 class MyEnvironment(Environment):
-    """
-    A simple echo environment that echoes back messages.
-
-    This environment is designed for testing the HTTP server infrastructure.
-    It maintains minimal state and simply echoes back whatever message it receives.
-
-    Example:
-        >>> env = MyEnvironment()
-        >>> obs = env.reset()
-        >>> print(obs.echoed_message)  # "My Env environment ready!"
-        >>>
-        >>> obs = env.step(MyAction(message="Hello"))
-        >>> print(obs.echoed_message)  # "Hello"
-        >>> print(obs.message_length)  # 5
-    """
+    """Environment implementation compatible with OpenEnv's server interface."""
 
     # Enable concurrent WebSocket sessions.
     # Set to True if your environment isolates state between instances.
@@ -46,52 +27,32 @@ class MyEnvironment(Environment):
     SUPPORTS_CONCURRENT_SESSIONS: bool = True
 
     def __init__(self):
-        """Initialize the my_env environment."""
-        self._state = State(episode_id=str(uuid4()), step_count=0)
-        self._reset_count = 0
-
-    def reset(self) -> MyObservation:
-        """
-        Reset the environment.
-
-        Returns:
-            MyObservation with a ready message
-        """
-        self._state = State(episode_id=str(uuid4()), step_count=0)
-        self._reset_count += 1
-
-        return MyObservation(
-            echoed_message="My Env environment ready!",
-            message_length=0,
-            done=False,
-            reward=0.0,
+        self._gym = PythonDebuggingGym()
+        self._state = State(episode_id="", step_count=0)
+
+    def reset(self) -> CodeObservation:
+        obs, system_prompt = self._gym.reset()
+        self._state = State(
+            episode_id=obs.info.get("episode_id", ""),
+            step_count=obs.step_count,
         )
-
-    def step(self, action: MyAction) -> MyObservation:  # type: ignore[override]
-        """
-        Execute a step in the environment by echoing the message.
-
-        Args:
-            action: MyAction containing the message to echo
-
-        Returns:
-            MyObservation with the echoed message and its length
-        """
-        self._state.step_count += 1
-
-        message = action.message
-        length = len(message)
-
-        # Simple reward: longer messages get higher rewards
-        reward = length * 0.1
-
-        return MyObservation(
-            echoed_message=message,
-            message_length=length,
-            done=False,
-            reward=reward,
-            metadata={"original_message": message, "step": self._state.step_count},
+        metadata = dict(obs.metadata or {})
+        metadata["system_prompt"] = system_prompt
+        obs.metadata = metadata
+        return obs
+
+    def step(self, action: CodeAction) -> CodeObservation:  # type: ignore[override]
+        obs, reward, done, info = self._gym.step(action)
+        obs.reward = reward
+        obs.done = done
+        metadata = dict(obs.metadata or {})
+        metadata.update(info)
+        obs.metadata = metadata
+        self._state = State(
+            episode_id=obs.info.get("episode_id", ""),
+            step_count=obs.step_count,
         )
+        return obs
 
     @property
     def state(self) -> State:

{my_env/server → server}/requirements.txt

@@ -1,6 +1,7 @@
 openenv[core]>=0.2.0
 fastapi>=0.115.0
 uvicorn>=0.24.0
-
+openai>=1.30.0
+websockets>=12.0
 
 

tasks.py

@@ -0,0 +1,683 @@
+"""
+tasks.py — Static Task Registry
+================================
+This is a "dumb" registry. Tasks are hardcoded dicts representing
+curated buggy programs generated offline via MutationEngine.
+
+Exported symbols:
+  TASKS_BY_DIFFICULTY   Dict[str, List[Dict]] — tasks grouped by tier
+  ALL_TASKS             List[Dict]             — flat list for random sampling
+
+Run mutation_engine.py + dataset_generator.py locally (offline) to
+generate new candidates, curate the best ones, and add them here.
+"""
+
+from __future__ import annotations
+from typing import Any, Callable, Dict, List
+
+
+# ---------------------------------------------------------------------------
+# Test helpers (module-level; accept namespace dict, raise AssertionError)
+# ---------------------------------------------------------------------------
+
+# ── sum_even_numbers ────────────────────────────────────────────────────────
+
+def _tse_1(ns):
+    res = ns["sum_even_numbers"]([1, 2, 3, 4])
+    assert res == 6, f"Test failed: input=[1, 2, 3, 4], expected=6, got={res}"
+def _tse_2(ns):
+    res = ns["sum_even_numbers"]([])
+    assert res == 0, f"Test failed: input=[], expected=0, got={res}"
+def _tse_3(ns):
+    res = ns["sum_even_numbers"]([1, 3, 5])
+    assert res == 0, f"Test failed: input=[1, 3, 5], expected=0, got={res}"
+def _tse_4(ns):
+    res = ns["sum_even_numbers"]([2, 2, 2])
+    assert res == 6, f"Test failed: input=[2, 2, 2], expected=6, got={res}"
+
+# ── reverse_string ──────────────────────────────────────────────────────────
+
+def _trs_1(ns):
+    res = ns["reverse_string"]("abc")
+    assert res == "cba", f"Test failed: input='abc', expected='cba', got={res!r}"
+def _trs_2(ns):
+    res = ns["reverse_string"]("")
+    assert res == "", f"Test failed: input='', expected='', got={res!r}"
+def _trs_3(ns):
+    res = ns["reverse_string"]("a")
+    assert res == "a", f"Test failed: input='a', expected='a', got={res!r}"
+def _trs_4(ns):
+    res = ns["reverse_string"]("abcd")
+    assert res == "dcba", f"Test failed: input='abcd', expected='dcba', got={res!r}"
+
+# ── binary_search ───────────────────────────────────────────────────────────
+
+def _tbs_1(ns):
+    res = ns["binary_search"]([1, 2, 3, 4, 5], 3)
+    assert res == 2, f"Test failed: input=([1, 2, 3, 4, 5], 3), expected=2, got={res}"
+def _tbs_2(ns):
+    res = ns["binary_search"]([1, 2, 3, 4, 5], 6)
+    assert res == -1, f"Test failed: input=([1, 2, 3, 4, 5], 6), expected=-1, got={res}"
+def _tbs_3(ns):
+    res = ns["binary_search"]([], 1)
+    assert res == -1, f"Test failed: input=([], 1), expected=-1, got={res}"
+def _tbs_4(ns):
+    res = ns["binary_search"]([7], 7)
+    assert res == 0, f"Test failed: input=([7], 7), expected=0, got={res}"
+
+# ── flatten ─────────────────────────────────────────────────────────────────
+
+def _tfl_1(ns):
+    res = ns["flatten"]([1, [2, 3]])
+    assert res == [1, 2, 3], f"Test failed: input=[1, [2, 3]], expected=[1, 2, 3], got={res}"
+def _tfl_2(ns):
+    res = ns["flatten"]([])
+    assert res == [], f"Test failed: input=[], expected=[], got={res}"
+def _tfl_3(ns):
+    res = ns["flatten"]([1, [2, [3]]])
+    assert res == [1, 2, 3], f"Test failed: input=[1, [2, [3]]], expected=[1, 2, 3], got={res}"
+def _tfl_4(ns):
+    res = ns["flatten"]([[1], [2, 3], [4]])
+    assert res == [1, 2, 3, 4], f"Test failed: input=[[1], [2, 3], [4]], expected=[1, 2, 3, 4], got={res}"
+
+# ── word_count ──────────────────────────────────────────────────────────────
+
+def _twc_1(ns):
+    res = ns["word_count"]("hello world hello")
+    assert res == {"hello": 2, "world": 1}, f"Test failed: input='hello world hello', expected={{'hello': 2, 'world': 1}}, got={res}"
+def _twc_2(ns):
+    res = ns["word_count"]("Hi, hi!")
+    assert res == {"hi": 2}, f"Test failed: input='Hi, hi!', expected={{'hi': 2}}, got={res}"
+def _twc_3(ns):
+    res = ns["word_count"]("")
+    assert res == {}, f"Test failed: input='', expected={{}}, got={res}"
+def _twc_4(ns):
+    res = ns["word_count"]("Hello HELLO hello")
+    assert res == {"hello": 3}, f"Test failed: input='Hello HELLO hello', expected={{'hello': 3}}, got={res}"
+
+# ── lru_cache ───────────────────────────────────────────────────────────────
+
+def _tlru_1(ns):
+    C = ns["LRUCache"]
+    c = C(2); c.put(1, 1); c.put(2, 2)
+    res = c.get(1)
+    assert res == 1, f"Test failed: Capacity 2. Added (1,1), then (2,2). Expected get(1) to be 1, got {res}"
+
+def _tlru_2(ns):
+    C = ns["LRUCache"]
+    c = C(1); c.put(1, 1); c.put(2, 2)
+    res = c.get(1)
+    assert res == -1, f"Test failed: Capacity 1. Added (1,1), then (2,2). Expected key 1 to be evicted (return -1), got {res}"
+
+def _tlru_3(ns):
+    C = ns["LRUCache"]
+    c = C(2); c.put(1, 1); c.put(2, 2); c.get(1); c.put(3, 3)
+    res = c.get(2)
+    assert res == -1, f"Test failed: Capacity 2. Added (1,1), then (2,2), got(1), added (3,3). Expected key 2 to be evicted (return -1) since 1 was promoted during get(1), got {res}. Did you promote key 1 during get()?"
+
+# ── valid_parentheses ────────────────────────────────────────────────────────
+
+def _tvp_1(ns):
+    res = ns["is_valid"]("()")
+    assert res == True, f"Test failed: input='()', expected=True, got={res}"
+def _tvp_2(ns):
+    res = ns["is_valid"]("(]")
+    assert res == False, f"Test failed: input='(]', expected=False, got={res}"
+def _tvp_3(ns):
+    res = ns["is_valid"]("([{}])")
+    assert res == True, f"Test failed: input='([{{}}])', expected=True, got={res}"
+def _tvp_4(ns):
+    res = ns["is_valid"]("")
+    assert res == True, f"Test failed: input='', expected=True, got={res}"
+
+# ── merge_intervals ──────────────────────────────────────────────────────────
+
+def _tmi_1(ns):
+    res = ns["merge_intervals"]([[1, 3], [2, 6]])
+    assert res == [[1, 6]], f"Test failed: input=[[1, 3], [2, 6]], expected=[[1, 6]], got={res}"
+def _tmi_2(ns):
+    res = ns["merge_intervals"]([[1, 4], [4, 5]])
+    assert res == [[1, 5]], f"Test failed: input=[[1, 4], [4, 5]], expected=[[1, 5]], got={res}"
+def _tmi_3(ns):
+    res = ns["merge_intervals"]([[1, 2], [3, 4]])
+    assert res == [[1, 2], [3, 4]], f"Test failed: input=[[1, 2], [3, 4]], expected=[[1, 2], [3, 4]], got={res}"
+
+
+# ---------------------------------------------------------------------------
+# Static task registry
+# ---------------------------------------------------------------------------
+
+def _t(name, description, code, solution, tests, difficulty, bug_type):
+    return dict(
+        name=name, description=description,
+        code=code, solution=solution,
+        tests=tests, difficulty=difficulty, bug_type=bug_type,
+    )
+
+
+# ── EASY ──────────────────────────────────────────────────────────────────
+
+TASK_SUM_EVEN_WRONG_OP = _t(
+    name="sum_even_wrong_condition",
+    description="Debug the sum_even_numbers function so it passes all tests.",
+    difficulty="easy",
+    bug_type="wrong_operator",
+    code=[
+        "def sum_even_numbers(nums):",
+        "    total = 0",
+        "    for n in nums:",
+        "        if n % 2 != 0:",
+        "            total += n",
+        "    return total",
+    ],
+    solution=[
+        "def sum_even_numbers(nums):",
+        "    total = 0",
+        "    for n in nums:",
+        "        if n % 2 == 0:",
+        "            total += n",
+        "    return total",
+    ],
+    tests=[_tse_1, _tse_2, _tse_3, _tse_4],
+)
+
+TASK_SUM_EVEN_MISSING_INIT = _t(
+    name="sum_even_missing_accumulator",
+    description="Debug the sum_even_numbers function so it passes all tests.",
+    difficulty="easy",
+    bug_type="wrong_operator",
+    code=[
+        "def sum_even_numbers(nums):",
+        "    total = 0",
+        "    for n in nums:",
+        "        if n % 2 == 0:",
+        "            total -= n",
+        "    return total",
+    ],
+    solution=[
+        "def sum_even_numbers(nums):",
+        "    total = 0",
+        "    for n in nums:",
+        "        if n % 2 == 0:",
+        "            total += n",
+        "    return total",
+    ],
+    tests=[_tse_1, _tse_2, _tse_3, _tse_4],
+)
+
+TASK_REVERSE_WRONG_STEP = _t(
+    name="reverse_string_wrong_step",
+    description="Debug the reverse_string function so it passes all tests.",
+    difficulty="easy",
+    bug_type="off_by_one",
+    code=[
+        "def reverse_string(s):",
+        "    return s[::-2]",
+    ],
+    solution=[
+        "def reverse_string(s):",
+        "    return s[::-1]",
+    ],
+    tests=[_trs_1, _trs_2, _trs_3, _trs_4],
+)
+
+TASK_REVERSE_NO_REVERSE = _t(
+    name="reverse_string_returns_original",
+    description="Debug the reverse_string function so it passes all tests.",
+    difficulty="easy",
+    bug_type="wrong_operator",
+    code=[
+        "def reverse_string(s):",
+        "    return s[::1]",
+    ],
+    solution=[
+        "def reverse_string(s):",
+        "    return s[::-1]",
+    ],
+    tests=[_trs_1, _trs_2, _trs_3, _trs_4],
+)
+
+
+# ── MEDIUM ─────────────────────��──────────────────────────────────────────
+
+TASK_BS_OFF_BY_ONE = _t(
+    name="binary_search_off_by_one",
+    description="Debug the binary_search function so it passes all tests.",
+    difficulty="medium",
+    bug_type="off_by_one",
+    code=[
+        "def binary_search(arr, target):",
+        "    left, right = 0, len(arr)",
+        "    while left <= right:",
+        "        mid = (left + right) // 2",
+        "        if arr[mid] == target:",
+        "            return mid",
+        "        elif arr[mid] < target:",
+        "            left = mid + 1",
+        "        else:",
+        "            right = mid - 1",
+        "    return -1",
+    ],
+    solution=[
+        "def binary_search(arr, target):",
+        "    left, right = 0, len(arr) - 1",
+        "    while left <= right:",
+        "        mid = (left + right) // 2",
+        "        if arr[mid] == target:",
+        "            return mid",
+        "        elif arr[mid] < target:",
+        "            left = mid + 1",
+        "        else:",
+        "            right = mid - 1",
+        "    return -1",
+    ],
+    tests=[_tbs_1, _tbs_2, _tbs_3, _tbs_4],
+)
+
+TASK_BS_WRONG_MID = _t(
+    name="binary_search_wrong_mid",
+    description="Debug the binary_search function so it passes all tests.",
+    difficulty="medium",
+    bug_type="wrong_operator",
+    code=[
+        "def binary_search(arr, target):",
+        "    left, right = 0, len(arr) - 1",
+        "    while left <= right:",
+        "        mid = left + right",
+        "        if mid >= len(arr):",
+        "            return -1",
+        "        if arr[mid] == target:",
+        "            return mid",
+        "        elif arr[mid] < target:",
+        "            left = mid + 1",
+        "        else:",
+        "            right = mid - 1",
+        "    return -1",
+    ],
+    solution=[
+        "def binary_search(arr, target):",
+        "    left, right = 0, len(arr) - 1",
+        "    while left <= right:",
+        "        mid = (left + right) // 2",
+        "        if arr[mid] == target:",
+        "            return mid",
+        "        elif arr[mid] < target:",
+        "            left = mid + 1",
+        "        else:",
+        "            right = mid - 1",
+        "    return -1",
+    ],
+    tests=[_tbs_1, _tbs_2, _tbs_3, _tbs_4],
+)
+
+TASK_FLATTEN_APPEND = _t(
+    name="flatten_missing_recursion",
+    description="Debug the flatten function so it passes all tests.",
+    difficulty="medium",
+    bug_type="wrong_function_call",
+    code=[
+        "def flatten(lst):",
+        "    result = []",
+        "    for item in lst:",
+        "        if isinstance(item, list):",
+        "            result.append(item)",
+        "        else:",
+        "            result.append(item)",
+        "    return result",
+    ],
+    solution=[
+        "def flatten(lst):",
+        "    result = []",
+        "    for item in lst:",
+        "        if isinstance(item, list):",
+        "            result.extend(flatten(item))",
+        "        else:",
+        "            result.append(item)",
+        "    return result",
+    ],
+    tests=[_tfl_1, _tfl_2, _tfl_3, _tfl_4],
+)
+
+TASK_FLATTEN_LOGIC_INVERT = _t(
+    name="flatten_inverted_branch",
+    description="Debug the flatten function so it passes all tests.",
+    difficulty="medium",
+    bug_type="logic_inversion",
+    code=[
+        "def flatten(lst):",
+        "    result = []",
+        "    for item in lst:",
+        "        if not isinstance(item, list):",
+        "            result.extend(flatten(item))",
+        "        else:",
+        "            result.append(item)",
+        "    return result",
+    ],
+    solution=[
+        "def flatten(lst):",
+        "    result = []",
+        "    for item in lst:",
+        "        if isinstance(item, list):",
+        "            result.extend(flatten(item))",
+        "        else:",
+        "            result.append(item)",
+        "    return result",
+    ],
+    tests=[_tfl_1, _tfl_2, _tfl_3, _tfl_4],
+)
+
+TASK_WC_NO_LOWER = _t(
+    name="word_count_no_lower",
+    description="Debug the word_count function so it passes all tests.",
+    difficulty="medium",
+    bug_type="missing_return",
+    code=[
+        "import string",
+        "def word_count(text):",
+        "    for p in string.punctuation:",
+        "        text = text.replace(p, '')",
+        "    words = text.split()",
+        "    counts = {}",
+        "    for w in words:",
+        "        counts[w] = counts.get(w, 0) + 1",
+        "    return counts",
+    ],
+    solution=[
+        "import string",
+        "def word_count(text):",
+        "    text = text.lower()",
+        "    for p in string.punctuation:",
+        "        text = text.replace(p, '')",
+        "    words = text.split()",
+        "    counts = {}",
+        "    for w in words:",
+        "        counts[w] = counts.get(w, 0) + 1",
+        "    return counts",
+    ],
+    tests=[_twc_1, _twc_2, _twc_3, _twc_4],
+)
+
+TASK_WC_NO_PUNCT = _t(
+    name="word_count_no_punct_strip",
+    description="Debug the word_count function so it passes all tests.",
+    difficulty="medium",
+    bug_type="missing_return",
+    code=[
+        "def word_count(text):",
+        "    text = text.lower()",
+        "    words = text.split()",
+        "    counts = {}",
+        "    for w in words:",
+        "        counts[w] = counts.get(w, 0) + 1",
+        "    return counts",
+    ],
+    solution=[
+        "import string",
+        "def word_count(text):",
+        "    text = text.lower()",
+        "    for p in string.punctuation:",
+        "        text = text.replace(p, '')",
+        "    words = text.split()",
+        "    counts = {}",
+        "    for w in words:",
+        "        counts[w] = counts.get(w, 0) + 1",
+        "    return counts",
+    ],
+    tests=[_twc_1, _twc_2, _twc_3, _twc_4],
+)
+
+
+# ── HARD ──────────────────────────────────────────────────────────────────
+
+TASK_LRU_WRONG_EVICT = _t(
+    name="lru_cache_wrong_eviction",
+    description="Debug the LRUCache function so it passes all tests.",
+    difficulty="hard",
+    bug_type="off_by_one",
+    code=[
+        "class LRUCache:",
+        "    def __init__(self, capacity):",
+        "        self.capacity = capacity",
+        "        self.cache = []",
+        "    def get(self, key):",
+        "        for i, (k, v) in enumerate(self.cache):",
+        "            if k == key:",
+        "                self.cache.append(self.cache.pop(i))",
+        "                return v",
+        "        return -1",
+        "    def put(self, key, value):",
+        "        for i, (k, _) in enumerate(self.cache):",
+        "            if k == key:",
+        "                self.cache.pop(i)",
+        "                break",
+        "        if len(self.cache) >= self.capacity:",
+        "            self.cache.pop(0)",
+        "        self.cache.append((key, value))",
+    ],
+    solution=[
+        "class LRUCache:",
+        "    def __init__(self, capacity):",
+        "        self.capacity = capacity",
+        "        self.cache = []",
+        "    def get(self, key):",
+        "        for i, (k, v) in enumerate(self.cache):",
+        "            if k == key:",
+        "                self.cache.append(self.cache.pop(i))",
+        "                return v",
+        "        return -1",
+        "    def put(self, key, value):",
+        "        for i, (k, _) in enumerate(self.cache):",
+        "            if k == key:",
+        "                self.cache.pop(i)",
+        "                break",
+        "        if len(self.cache) >= self.capacity:",
+        "            self.cache.pop(0)",
+        "        self.cache.append((key, value))",
+    ],
+    tests=[_tlru_1, _tlru_2, _tlru_3],
+)
+
+TASK_LRU_NO_PROMOTE = _t(
+    name="lru_cache_no_promotion",
+    description="Debug the LRUCache function so it passes all tests.",
+    difficulty="hard",
+    bug_type="missing_return",
+    code=[
+        "class LRUCache:",
+        "    def __init__(self, capacity):",
+        "        self.capacity = capacity",
+        "        self.cache = []",
+        "    def get(self, key):",
+        "        for i, (k, v) in enumerate(self.cache):",
+        "            if k == key:",
+        "                return v",
+        "        return -1",
+        "    def put(self, key, value):",
+        "        for i, (k, _) in enumerate(self.cache):",
+        "            if k == key:",
+        "                self.cache.pop(i)",
+        "                break",
+        "        if len(self.cache) >= self.capacity:",
+        "            self.cache.pop(0)",
+        "        self.cache.append((key, value))",
+    ],
+    solution=[
+        "class LRUCache:",
+        "    def __init__(self, capacity):",
+        "        self.capacity = capacity",
+        "        self.cache = []",
+        "    def get(self, key):",
+        "        for i, (k, v) in enumerate(self.cache):",
+        "            if k == key:",
+        "                self.cache.append(self.cache.pop(i))",
+        "                return v",
+        "        return -1",
+        "    def put(self, key, value):",
+        "        for i, (k, _) in enumerate(self.cache):",
+        "            if k == key:",
+        "                self.cache.pop(i)",
+        "                break",
+        "        if len(self.cache) >= self.capacity:",
+        "            self.cache.pop(0)",
+        "        self.cache.append((key, value))",
+    ],
+    tests=[_tlru_1, _tlru_2, _tlru_3],
+)
+
+TASK_VP_WRONG_MAPPING = _t(
+    name="valid_parentheses_wrong_mapping",
+    description="Debug the is_valid function so it passes all tests.",
+    difficulty="hard",
+    bug_type="wrong_operator",
+    code=[
+        "def is_valid(s):",
+        "    stack = []",
+        "    mapping = {')': '[', ']': '{', '}': '('}",
+        "    for c in s:",
+        "        if c in mapping.values():",
+        "            stack.append(c)",
+        "        elif c in mapping:",
+        "            if not stack or stack.pop() != mapping[c]:",
+        "                return False",
+        "    return len(stack) == 0",
+    ],
+    solution=[
+        "def is_valid(s):",
+        "    stack = []",
+        "    mapping = {')': '(', ']': '[', '}': '{'}",
+        "    for c in s:",
+        "        if c in mapping.values():",
+        "            stack.append(c)",
+        "        elif c in mapping:",
+        "            if not stack or stack.pop() != mapping[c]:",
+        "                return False",
+        "    return len(stack) == 0",
+    ],
+    tests=[_tvp_1, _tvp_2, _tvp_3, _tvp_4],
+)
+
+TASK_VP_MISSING_EMPTY_CHECK = _t(
+    name="valid_parentheses_no_empty_check",
+    description="Debug the is_valid function so it passes all tests.",
+    difficulty="hard",
+    bug_type="logic_inversion",
+    code=[
+        "def is_valid(s):",
+        "    stack = []",
+        "    mapping = {')': '(', ']': '[', '}': '{'}",
+        "    for c in s:",
+        "        if c in mapping.values():",
+        "            stack.append(c)",
+        "        elif c in mapping:",
+        "            if stack.pop() != mapping[c]:",
+        "                return False",
+        "    return len(stack) == 0",
+    ],
+    solution=[
+        "def is_valid(s):",
+        "    stack = []",
+        "    mapping = {')': '(', ']': '[', '}': '{'}",
+        "    for c in s:",
+        "        if c in mapping.values():",
+        "            stack.append(c)",
+        "        elif c in mapping:",
+        "            if not stack or stack.pop() != mapping[c]:",
+        "                return False",
+        "    return len(stack) == 0",
+    ],
+    tests=[_tvp_1, _tvp_2, _tvp_3, _tvp_4],
+)
+
+TASK_MI_STRICT_OVERLAP = _t(
+    name="merge_intervals_strict_overlap",
+    description="Debug the merge_intervals function so it passes all tests.",
+    difficulty="hard",
+    bug_type="wrong_operator",
+    code=[
+        "def merge_intervals(intervals):",
+        "    intervals.sort()",
+        "    merged = []",
+        "    for interval in intervals:",
+        "        if not merged or merged[-1][1] < interval[0]:",
+        "            merged.append(list(interval))",
+        "        else:",
+        "            merged[-1][1] = max(merged[-1][1], interval[1])",
+        "    return merged",
+    ],
+    solution=[
+        "def merge_intervals(intervals):",
+        "    intervals.sort()",
+        "    merged = []",
+        "    for interval in intervals:",
+        "        if not merged or merged[-1][1] <= interval[0]:",
+        "            merged.append(list(interval))",
+        "        else:",
+        "            merged[-1][1] = min(merged[-1][1], interval[1])",
+        "    return merged",
+    ],
+    tests=[_tmi_1, _tmi_2, _tmi_3],
+)
+
+TASK_MI_NO_SORT = _t(
+    name="merge_intervals_missing_sort",
+    description="Debug the merge_intervals function so it passes all tests.",
+    difficulty="hard",
+    bug_type="missing_return",
+    code=[
+        "def merge_intervals(intervals):",
+        "    merged = []",
+        "    for interval in intervals:",
+        "        if not merged or merged[-1][1] < interval[0]:",
+        "            merged.append(list(interval))",
+        "        else:",
+        "            merged[-1][1] = max(merged[-1][1], interval[1])",
+        "    return merged",
+    ],
+    solution=[
+        "def merge_intervals(intervals):",
+        "    intervals.sort()",
+        "    merged = []",
+        "    for interval in intervals:",
+        "        if not merged or merged[-1][1] < interval[0]:",
+        "            merged.append(list(interval))",
+        "        else:",
+        "            merged[-1][1] = max(merged[-1][1], interval[1])",
+        "    return merged",
+    ],
+    tests=[_tmi_1, _tmi_2, _tmi_3],
+)
+
+
+# ---------------------------------------------------------------------------
+# Registries
+# ---------------------------------------------------------------------------
+
+TASKS_BY_DIFFICULTY: Dict[str, List[Dict]] = {
+    "easy": [
+        TASK_SUM_EVEN_WRONG_OP,
+        TASK_SUM_EVEN_MISSING_INIT,
+        TASK_REVERSE_WRONG_STEP,
+        TASK_REVERSE_NO_REVERSE,
+    ],
+    "medium": [
+        TASK_BS_OFF_BY_ONE,
+        TASK_BS_WRONG_MID,
+        TASK_FLATTEN_APPEND,
+        TASK_FLATTEN_LOGIC_INVERT,
+        TASK_WC_NO_LOWER,
+        TASK_WC_NO_PUNCT,
+    ],
+    "hard": [
+        TASK_LRU_WRONG_EVICT,
+        TASK_LRU_NO_PROMOTE,
+        TASK_VP_WRONG_MAPPING,
+        TASK_VP_MISSING_EMPTY_CHECK,
+        TASK_MI_STRICT_OVERLAP,
+        TASK_MI_NO_SORT,
+    ],
+}
+
+# Flat list — used for random sampling when training_step is not set
+ALL_TASKS: List[Dict] = [
+    t for bucket in TASKS_BY_DIFFICULTY.values() for t in bucket
+]