Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,23 @@
+# Dockerfile — builds from openenv-base, MUST use this base image
+ARG BASE_IMAGE=openenv-base:latest
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY server/requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt && rm /tmp/requirements.txt
+
+# Copy environment code
+COPY . /app/code_debug_env/
+
+# Health check (required by hackathon validator)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Expose port
+EXPOSE 8000
+
+# Start server
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["uvicorn", "code_debug_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,131 @@
 ---
 title: Code Debug Env
-emoji: 🚀
-colorFrom: indigo
-colorTo: yellow
+emoji: 🐞
+colorFrom: blue
+colorTo: indigo
 sdk: docker
-pinned: false
+app_port: 8000
+base_path: /web
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# code-debug-env
+
+An OpenEnv environment for training AI agents to repair buggy Python code.
+The agent receives a broken function and must iteratively submit patches until
+all unit tests pass.
+
+## Quick Start
+
+```python
+from code_debug_env import CodeDebugEnv, Action
+
+async with CodeDebugEnv(base_url="https://luciferai-devil-code-debug-env.hf.space") as env:
+    obs = await env.reset(task_id="task_easy")
+    print(obs.buggy_code)          # The broken function
+    
+    result = await env.step(Action(
+        patch="def find_max_subarray_sum(nums):\n    ...",
+        task_id="task_easy",
+        think="The off-by-one error is in range(1, len(nums)-1)"
+    ))
+    print(result.observation.score)  # 0.0–1.0
+```
+
+## Action Space
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `patch` | str | Yes | Full Python source replacement for the function |
+| `task_id` | str | Yes | Which task to target |
+| `think` | str | No | Chain-of-thought reasoning (earns +0.2 reward bonus) |
+
+## Observation Space
+
+| Field | Type | Description |
+|---|---|---|
+| `buggy_code` | str | Current version of the code |
+| `test_results` | list | Per-test pass/fail with error messages |
+| `passed` / `total` | int | Tests passing out of total |
+| `score` | float | Composite reward for this step (0.0–1.0) |
+| `done` | bool | True when all tests pass or max_steps reached |
+
+## Reward Function
+
+```
+r = 0.5 × (tests_passed / tests_total)   # correctness
+  + 0.2 × (1 if valid syntax else 0)     # format
+  + 0.2 × (1 if <think> provided else 0) # chain-of-thought bonus
+  + 0.1 × (steps_remaining / max_steps)  # efficiency
+  − 0.3 × (1 if timeout/crash else 0)    # penalty
+```
+
+## Tasks
+
+| ID | Difficulty | Description | Variants |
+|---|---|---|---|
+| `task_easy` | Easy | Single off-by-one error | 6+ |
+| `task_medium` | Medium | Two independent bugs | 6+ |
+| `task_hard` | Hard | 3+ subtle bugs in recursive function | 7+ |
+
+*Total: 19 procedurally generated tasks via `task_generator.py`.*
+
+## Setup
+
+```bash
+pip install openenv-core
+pip install git+https://huggingface.co/spaces/luciferai-devil/code-debug-env
+```
+
+## Docker
+
+```bash
+docker pull luciferai-devil/code-debug-env:latest
+docker run -p 8000:8000 luciferai-devil/code-debug-env
+```
+
+## Baseline Results (via OpenAI API)
+
+Evaluated using `gpt-4o-mini` / `gpt-oss-120b` reasoning models.
+
+| Task | Agent | Score | Notes |
+|---|---|---|---|
+| task_easy | LLM | 0.99 | One-shot fix with CoT |
+| task_medium | LLM | 0.74 | Iterative refinement |
+| task_hard | LLM | 0.59 | Struggles with complex recursion depth |
+
+*Average Score: 0.77*
+
+## Training with GRPO
+
+See `baseline/run_baseline.py` for the inference client.
+Compatible with TRL's `GRPOTrainer` — pass `reward_fn` that calls `/grader`.
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/health` | GET | Health check |
+| `/reset` | POST | Start a new episode |
+| `/step` | POST | Submit action, get observation |
+| `/state` | GET | Get current episode state |
+| `/tasks` | GET | List all available tasks |
+| `/grader` | GET | Grade a submission directly |
+| `/baseline` | GET | Run baseline agent on all tasks |
+
+## Local Development
+
+```bash
+# Run server locally
+uvicorn code_debug_env.server.app:app --reload --port 8000
+
+# Build Docker
+docker build -t code-debug-env -f server/Dockerfile .
+
+# Run Docker
+docker run -p 8000:8000 code-debug-env
+
+# Smoke test
+curl http://localhost:8000/health
+curl -X POST http://localhost:8000/reset -H "Content-Type: application/json" -d '{}'
+curl http://localhost:8000/tasks
+```

__init__.py

@@ -0,0 +1,5 @@
+# __init__.py — export the public API
+from .models import Action, Observation, State
+from .client import CodeDebugEnv
+
+__all__ = ["Action", "Observation", "State", "CodeDebugEnv"]

baseline/run_baseline.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+Baseline inference script.
+Runs an LLM agent on all 3 tasks using OpenAI API.
+Usage: python baseline/run_baseline.py [--output json]
+Requires: OPENAI_API_KEY environment variable.
+"""
+import asyncio
+import sys
+import json
+import os
+from pathlib import Path
+
+# Add parent to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from code_debug_env.client import CodeDebugEnv
+from code_debug_env.models import Action
+
+try:
+    from openai import AsyncOpenAI
+except ImportError:
+    print("Please install openai: pip install openai")
+    sys.exit(1)
+
+BASE_URL = os.getenv("OPENENV_URL", "http://127.0.0.1:8000")
+API_BASE_URL = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME = os.getenv("OPENENV_MODEL", "gpt-4o-mini")
+
+client = AsyncOpenAI(
+    api_key=os.getenv("OPENAI_API_KEY"),
+    base_url=API_BASE_URL
+)
+
+async def openai_agent(observation) -> Action:
+    """Uses LLM to suggest a code fix."""
+    prompt = f"""You are an expert Python debugger. Your task is to fix the buggy code below.
+Task Description: {observation.task_description}
+
+Buggy Code:
+```python
+{observation.buggy_code}
+```
+
+Test Results so far:
+{[[t.name, t.passed, t.error] for t in observation.test_results]}
+Passed {observation.passed} out of {observation.total} tests.
+
+Provide ONLY a valid JSON object matching this schema:
+{{
+  "patch": "The FULL python function as a string, with the bugs fixed",
+  "task_id": "{observation.task_id}",
+  "think": "Your chain-of-thought reasoning before patching (important!)"
+}}
+"""
+    try:
+        response = await client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[{"role": "user", "content": prompt}],
+            response_format={"type": "json_object"} if "gpt-4" in MODEL_NAME or "gpt-oss" in MODEL_NAME else None,
+            temperature=0.2,
+        )
+        content = response.choices[0].message.content
+        data = json.loads(content)
+        return Action(
+            patch=data["patch"],
+            task_id=observation.task_id,
+            think=data.get("think", "Applied fix based on test errors."),
+        )
+    except Exception as e:
+        print(f"LLM Error: {e}", file=sys.stderr)
+        # fallback to returning original code to avoid crashing the loop
+        return Action(
+            patch=observation.buggy_code,
+            task_id=observation.task_id,
+            think="Failed to generate patch.",
+        )
+
+async def evaluate_task(env, task_id: str) -> dict:
+    result = await env.reset(task_id=task_id)
+    obs = result.observation
+    best_score = 0.0
+    for step in range(10):
+        action = await openai_agent(obs)
+        result = await env.step(action)
+        best_score = max(best_score, result.observation.score)
+        obs = result.observation
+        if obs.done:
+            break
+    return {"task_id": task_id, "best_score": round(best_score, 4), "steps": step + 1}
+
+async def main(output_format: str = "table"):
+    if not os.getenv("OPENAI_API_KEY"):
+        print("Warning: OPENAI_API_KEY not set. LLM calls will fail.", file=sys.stderr)
+        
+    results = []
+    async with CodeDebugEnv(base_url=BASE_URL) as env:
+        for task_id in ["task_easy", "task_medium", "task_hard"]:
+            res = await evaluate_task(env, task_id)
+            results.append(res)
+
+    if output_format == "json":
+        print(json.dumps({"baseline_results": results, "agent": "openai_api"}))
+    else:
+        print("\n=== Baseline Results ===")
+        for r in results:
+            print(f"  {r['task_id']:15s}  score={r['best_score']:.3f}  steps={r['steps']}")
+        print(f"\n  avg score: {sum(r['best_score'] for r in results) / len(results):.3f}")
+
+if __name__ == "__main__":
+    output = "json" if "--output json" in sys.argv else "table"
+    asyncio.run(main(output))

baseline/train_grpo_120b.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+GRPO Training Script for gpt-oss-120b using OpenEnv and TRL.
+Adapted from the openenv-course repository architecture.
+
+Requirements:
+pip install "trl>=0.17.0" openenv-core transformers datasets accelerate vllm
+"""
+import os
+import sys
+import json
+import torch
+from datasets import Dataset
+from transformers import AutoTokenizer
+
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from code_debug_env.client import CodeDebugEnv
+from code_debug_env.models import Action
+
+# TRL imports
+from trl import GRPOConfig, GRPOTrainer
+from trl.experimental.openenv import generate_rollout_completions
+
+# 1. Configuration
+MODEL_NAME = "openai/gpt-oss-120b"
+OUTPUT_DIR = "code-debug-grpo-120b"
+ENV_URL = os.getenv("OPENENV_URL", "http://127.0.0.1:8000")
+
+# 2. Setup Persistent Environment Connection
+print(f"Connecting to env: {ENV_URL}")
+env = CodeDebugEnv(base_url=ENV_URL)
+sync_env = env.sync()
+sync_env.connect()
+
+# 3. Setup Tokenizer
+print(f"Loading tokenizer for {MODEL_NAME}")
+tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
+if tokenizer.pad_token is None:
+    tokenizer.pad_token = tokenizer.eos_token
+
+# 4. System Prompt Definition
+SYSTEM_PROMPT = """You are an expert Python debugger and RL agent.
+Your task is to fix the buggy code provided to you.
+
+Provide ONLY a valid JSON object matching this schema:
+{
+  "patch": "The FULL python function as a string, with the bugs fixed",
+  "task_id": "the task requested",
+  "think": "Your chain-of-thought reasoning before patching (important for rewards!)"
+}
+"""
+
+def make_user_prompt(observation):
+    return (
+        f"Task Description: {observation.task_description}\n\n"
+        f"Buggy Code:\n```python\n{observation.buggy_code}\n```\n\n"
+        f"Passed {observation.passed} out of {observation.total} tests."
+    )
+
+# 5. Rollout Function
+def rollout_once(trainer, sync_env, tokenizer, dataset_prompt, system_prompt, max_turns):
+    """Execute one full episode to gather trajectory formatting for GRPO."""
+    result = sync_env.reset()
+    observation = result.observation
+
+    prompt_ids = []
+    completion_ids = []
+    logprobs = []
+    composite_rewards = []
+
+    for _turn in range(max_turns):
+        if result.done:
+            break
+
+        user_prompt = make_user_prompt(observation)
+        messages = [
+            {'role': 'system', 'content': system_prompt},
+            {'role': 'user', 'content': user_prompt},
+        ]
+        
+        prompt_text = tokenizer.apply_chat_template(
+            messages,
+            add_generation_prompt=True,
+            tokenize=False,
+            enable_thinking=False,
+        )
+
+        rollout_outputs = generate_rollout_completions(trainer, [prompt_text])[0]
+        prompt_ids.append(rollout_outputs['prompt_ids'])
+        completion_ids.append(rollout_outputs['completion_ids'])
+        logprobs.append(rollout_outputs['logprobs'])
+        
+        completion_text = rollout_outputs.get('text') or tokenizer.decode(
+            rollout_outputs['completion_ids'], skip_special_tokens=True
+        )
+
+        # Parse JSON output from the model
+        try:
+            # simple extraction since prompt dictates JSON
+            start = completion_text.find("{")
+            end = completion_text.rfind("}") + 1
+            if start != -1 and end != -1:
+                data = json.loads(completion_text[start:end])
+                action = Action(patch=data["patch"], task_id=observation.task_id, think=data.get("think", ""))
+            else:
+                raise ValueError("No JSON found")
+        except:
+            # Fallback action if parsing fails
+            action = Action(patch=observation.buggy_code, task_id=observation.task_id, think="")
+
+        # Step the environment
+        result = sync_env.step(action)
+        observation = result.observation
+        
+        # The environment already calculates the composite reward (0.0 to 1.0)
+        # correctness, format, CoT bonus, and efficiency are all baked in.
+        composite_rewards.append(observation.score)
+
+    return {
+        'prompt_ids': [pid for sub in prompt_ids for pid in sub], # flatten
+        'completion_ids': [cid for sub in completion_ids for cid in sub],
+        'logprobs': [lp for sub in logprobs for lp in sub],
+        'env_reward': composite_rewards[-1] if composite_rewards else 0.0,
+    }
+
+
+def rollout_func(prompts, trainer=None):
+    """Rollout function called by GRPOTrainer."""
+    episode_prompt_ids = []
+    episode_completion_ids = []
+    episode_logprobs = []
+    rewards = []
+
+    for prompt_text in prompts:
+        episode = rollout_once(
+            trainer=trainer,
+            sync_env=sync_env,
+            tokenizer=tokenizer,
+            dataset_prompt=prompt_text,
+            system_prompt=SYSTEM_PROMPT,
+            max_turns=3, # Keep turns low for heavy models like 120B
+        )
+        episode_prompt_ids.append(episode['prompt_ids'])
+        episode_completion_ids.append(episode['completion_ids'])
+        episode_logprobs.append(episode['logprobs'])
+        rewards.append(episode['env_reward'])
+
+    return {
+        'prompt_ids': episode_prompt_ids,
+        'completion_ids': episode_completion_ids,
+        'logprobs': episode_logprobs,
+        'env_reward': rewards,
+    }
+
+# 6. Reward Functions (Mapped from rollout_func keys)
+def composite_env_reward(completions, **kwargs):
+    rewards = kwargs.get("env_reward")
+    return [float(r) for r in rewards] if rewards else [0.0] * len(completions)
+
+
+# 7. Create Dataset & Config
+def main():
+    print("Preparing dataset...")
+    # Dummy prompts to kick off the rollout loop (the actual env state overrides this)
+    dataset = Dataset.from_dict({"prompt": ["Fix the buggy Python code."] * 500})
+    
+    # Using specific optimizations for 120B model (like MXFP4, tensor parallelism if available)
+    grpo_config = GRPOConfig(
+        num_train_epochs=1,
+        learning_rate=1e-6, # lower LR for 120B
+        gradient_accumulation_steps=128,
+        per_device_train_batch_size=1,
+        warmup_steps=10,
+        num_generations=2,
+        max_completion_length=512,
+        max_prompt_length=1500,
+        use_vllm=True,
+        vllm_mode="colocate",
+        vllm_gpu_memory_utilization=0.9, # maximize for 120B
+        output_dir=OUTPUT_DIR,
+        logging_steps=1,
+        save_steps=50,
+        gradient_checkpointing=True,
+        gradient_checkpointing_kwargs={"use_reentrant": False},
+        push_to_hub=False,
+    )
+
+    print(f"Initializing GRPOTrainer for {MODEL_NAME}...")
+    trainer = GRPOTrainer(
+        model=MODEL_NAME,
+        processing_class=tokenizer,
+        reward_funcs=[composite_env_reward],
+        train_dataset=dataset,
+        args=grpo_config,
+        rollout_func=rollout_func,
+    )
+
+    print("Starting training...")
+    trainer.train()
+    
+    sync_env.close()
+    trainer.save_model(OUTPUT_DIR)
+    print("Training complete! Model saved.")
+
+if __name__ == "__main__":
+    main()

client.py

@@ -0,0 +1,29 @@
+# client.py — used in training code / run_baseline.py
+from typing import Any
+from openenv.core.env_client import EnvClient
+from openenv.core.client_types import StepResult
+from .models import Action, Observation, State
+
+
+class CodeDebugEnv(EnvClient[Action, Observation, State]):
+    """
+    Client for the CodeDebug environment.
+    Usage:
+        async with CodeDebugEnv(base_url="https://your-space.hf.space") as env:
+            result = await env.reset(task_id="task_easy")
+            result = await env.step(Action(patch="...", task_id="task_easy"))
+    """
+
+    def _step_payload(self, action: Action) -> dict[str, Any]:
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: dict[str, Any]) -> StepResult[Observation]:
+        obs = Observation(**payload.get("observation", payload))
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward", obs.reward),
+            done=payload.get("done", obs.done)
+        )
+
+    def _parse_state(self, payload: dict[str, Any]) -> State:
+        return State(**payload)

models.py

@@ -0,0 +1,57 @@
+# models.py
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import Optional
+import uuid
+
+
+class Action(BaseModel):
+    """Agent's action: submit a code patch to fix the buggy function."""
+    patch: str = Field(
+        description="Full replacement of the function body (valid Python source code)."
+    )
+    task_id: str = Field(
+        description="Which task this patch targets. Must match a task from /tasks."
+    )
+    think: Optional[str] = Field(
+        default=None,
+        description="Optional chain-of-thought reasoning. Providing this earns r_cot bonus."
+    )
+
+
+class TestResult(BaseModel):
+    name: str
+    passed: bool
+    error: Optional[str] = None
+
+
+class Observation(BaseModel):
+    """What the agent sees after reset() or step()."""
+    task_id: str
+    buggy_code: str = Field(description="Current version of the code (may be patched).")
+    task_description: str
+    test_results: list[TestResult] = Field(default_factory=list)
+    passed: int = 0
+    total: int = 0
+    score: float = 0.0
+    done: bool = False
+    reward: float = Field(default=0.0, exclude=True) # Required by openenv 0.2 serialization
+    error: Optional[str] = None
+
+
+class State(BaseModel):
+    """Episode metadata — returned by state() endpoint."""
+    episode_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    task_id: str = ""
+    step_count: int = 0
+    max_steps: int = 10
+    current_score: float = 0.0
+    best_score: float = 0.0
+
+
+class TaskInfo(BaseModel):
+    """Returned by /tasks endpoint."""
+    task_id: str
+    difficulty: str          # "easy" | "medium" | "hard"
+    description: str
+    action_schema: dict      # JSON schema of Action for this task

openenv.yaml

@@ -0,0 +1,70 @@
+# openenv.yaml — validated by `openenv validate`
+name: code-debug-env
+version: "1.0.0"
+description: >
+  A real-world RL environment where an AI agent repairs buggy Python functions.
+  The agent receives broken code and must iteratively submit patches until all
+  unit tests pass. Designed for training LLMs on code repair via GRPO/RLVR.
+
+author: "luciferai-devil"
+license: MIT
+
+# Hackathon domain tag
+domain: software-engineering
+
+tasks:
+  - id: task_easy
+    difficulty: easy
+    description: "Fix a single off-by-one error in a Kadane's algorithm implementation."
+  - id: task_medium
+    difficulty: medium
+    description: "Fix two independent bugs in a string parsing utility."
+  - id: task_hard
+    difficulty: hard
+    description: "Fix 3+ subtle bugs in a recursive tree function with missing edge cases."
+
+action:
+  type: object
+  properties:
+    patch:
+      type: string
+      description: "Full replacement Python source for the function body."
+    task_id:
+      type: string
+      description: "Which task this patch targets."
+    think:
+      type: string
+      description: "Optional chain-of-thought reasoning (earns bonus reward)."
+  required: [patch, task_id]
+
+observation:
+  type: object
+  properties:
+    task_id:        { type: string }
+    buggy_code:     { type: string }
+    task_description: { type: string }
+    test_results:   { type: array }
+    passed:         { type: integer }
+    total:          { type: integer }
+    score:          { type: number, minimum: 0.0, maximum: 1.0 }
+    done:           { type: boolean }
+    error:          { type: string, nullable: true }
+
+reward:
+  description: >
+    Composite reward: 0.5×correctness + 0.2×valid_syntax + 0.2×chain_of_thought
+    + 0.1×step_efficiency − 0.3×timeout_penalty. Range: [0.0, 1.0].
+  type: number
+  minimum: 0.0
+  maximum: 1.0
+
+episode:
+  max_steps: 10
+  termination: "All tests pass (score=1.0) OR max_steps reached."
+
+server:
+  port: 8000
+  transport: websocket   # openenv uses WebSocket for persistent sessions
+
+huggingface:
+  space_id: "luciferai-devil/code-debug-env"

pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "code-debug-env"
+version = "1.0.0"
+description = "OpenEnv environment for AI-powered code repair via GRPO training"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core>=0.1.0",
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.27.0",
+    "pydantic>=2.0.0",
+    "pytest>=8.0.0",
+    "pytest-timeout>=2.3.0",
+    "pytest-json-report>=1.5.0",
+]
+
+[project.optional-dependencies]
+baseline = [
+    "transformers>=4.40.0",
+    "torch>=2.2.0",
+    "trl>=0.8.6",
+    "accelerate>=0.28.0",
+    "openai>=1.0.0",
+]
+
+[project.scripts]
+code-debug-env = "code_debug_env.server.app:main"
+server = "code_debug_env.server.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["code_debug_env"]

server/__init__.py

@@ -0,0 +1 @@
+# server/__init__.py

server/app.py

@@ -0,0 +1,72 @@
+# server/app.py
+from fastapi import FastAPI, HTTPException
+from openenv.core.env_server import create_fastapi_app
+from ..models import Action, Observation, TaskInfo
+from .environment import CodeDebugEnvironment
+from .tasks import TASK_REGISTRY
+from .grader import grade
+
+# Core OpenEnv app (provides /reset, /step, /state, /ws, /health)
+app = create_fastapi_app(CodeDebugEnvironment, Action, Observation)
+
+
+# ── Additional required hackathon endpoints ────────────────────────────
+
+@app.get("/tasks")
+def list_tasks() -> list[TaskInfo]:
+    """Return all tasks with their action schema."""
+    return [
+        TaskInfo(
+            task_id=tid,
+            difficulty=task["difficulty"],
+            description=task["description"],
+            action_schema=Action.model_json_schema(),
+        )
+        for tid, task in TASK_REGISTRY.items()
+    ]
+
+
+@app.get("/grader")
+def get_grader_score(task_id: str, submitted_code: str) -> dict:
+    """
+    Grade a submission directly (for testing / evaluation).
+    Returns: { score: float, passed: int, total: int, test_results: list }
+    """
+    if task_id not in TASK_REGISTRY:
+        raise HTTPException(status_code=404, detail=f"Unknown task_id: {task_id}")
+    task = TASK_REGISTRY[task_id]
+    result = grade(submitted_code, task_id, task["test_suite"])
+    return {
+        "task_id": task_id,
+        "score": result["score"],
+        "passed": result["passed"],
+        "total": result["total"],
+        "test_results": [r.model_dump() for r in result["test_results"]],
+    }
+
+
+@app.get("/baseline")
+def run_baseline() -> dict:
+    """
+    Run the baseline agent on all tasks and return scores.
+    This endpoint triggers the baseline inference script.
+    """
+    import subprocess, sys, json
+    try:
+        result = subprocess.run(
+            [sys.executable, "baseline/run_baseline.py", "--output", "json"],
+            capture_output=True, text=True, timeout=120,
+        )
+        return json.loads(result.stdout)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+def main():
+    """Entry point for the server."""
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

server/environment.py

@@ -0,0 +1,114 @@
+# server/environment.py
+from __future__ import annotations
+import uuid
+from openenv.core.env_server import Environment
+from ..models import Action, Observation, State
+from .grader import grade
+from .tasks import TASK_REGISTRY
+
+
+class CodeDebugEnvironment(Environment):
+    """
+    Real-world environment: AI agent must fix buggy Python functions.
+    Episodes are multi-turn: agent iterates until all tests pass or max_steps reached.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._state = State()
+        self._current_task = None
+
+    def reset(
+        self,
+        seed: int | None = None,
+        episode_id: str | None = None,
+        task_id: str | None = None,
+        **kwargs,
+    ) -> Observation:
+        """
+        Start a new episode.
+        - If task_id is None, sample a random task from the registry.
+        - Always returns a clean Observation with the buggy code.
+        """
+        if task_id is None:
+            import random
+            task_id = random.choice(list(TASK_REGISTRY.keys()))
+
+        task = TASK_REGISTRY[task_id]
+        self._current_task = task
+        self._state = State(
+            episode_id=str(uuid.uuid4()),
+            task_id=task_id,
+            step_count=0,
+            max_steps=10,
+            current_score=0.0,
+            best_score=0.0,
+        )
+
+        return Observation(
+            task_id=task_id,
+            buggy_code=task["buggy_code"],
+            task_description=task["description"],
+            passed=0,
+            total=task["num_tests"],
+            score=0.0,
+            done=False,
+        )
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: float | None = None,
+        **kwargs,
+    ) -> Observation:
+        """
+        Execute the agent's patch.
+        Returns observation with test results and composite reward.
+        """
+        if self._current_task is None:
+            raise RuntimeError("Call reset() before step()")
+
+        self._state.step_count += 1
+        task = self._current_task
+
+        # Grade the submission
+        grade_result = grade(
+            submitted_code=action.patch,
+            task_id=action.task_id,
+            test_suite=task["test_suite"],
+        )
+
+        # Composite reward:
+        # 0.5 * correctness + 0.2 * format + 0.2 * cot_bonus + 0.1 * efficiency
+        r_correct = grade_result["score"]          # 0.0–1.0
+        r_format  = 1.0 if grade_result["valid_syntax"] else 0.0
+        r_cot     = 0.2 if (action.think and len(action.think) > 20) else 0.0
+        r_eff     = max(0.0, (10 - self._state.step_count) / 10) * 0.1
+
+        reward = 0.5 * r_correct + 0.2 * r_format + r_cot + r_eff
+        reward = max(0.0, min(1.0, reward))
+
+        # Penalty for timeout/crash
+        if grade_result.get("timed_out"):
+            reward = max(0.0, reward - 0.3)
+
+        done = (r_correct == 1.0) or (self._state.step_count >= self._state.max_steps)
+
+        self._state.current_score = reward
+        self._state.best_score = max(self._state.best_score, reward)
+
+        return Observation(
+            task_id=action.task_id,
+            buggy_code=action.patch,
+            task_description=task["description"],
+            test_results=grade_result["test_results"],
+            passed=grade_result["passed"],
+            total=grade_result["total"],
+            score=reward,
+            done=done,
+            error=grade_result.get("error"),
+        )
+
+    @property
+    def state(self) -> State:
+        return self._state

server/grader.py

@@ -0,0 +1,118 @@
+# server/grader.py
+"""
+Deterministic, sandboxed grader. Runs submitted code against a hidden pytest suite.
+Returns score = passed / total (float 0.0–1.0).
+
+SECURITY: runs in a subprocess with:
+- 10 second wall-clock timeout
+- No network access (subprocess inherits restricted env)
+- Restricted builtins (no open, no os, no sys import)
+"""
+from __future__ import annotations
+import subprocess
+import sys
+import textwrap
+import tempfile
+import os
+import json
+from pathlib import Path
+from ..models import TestResult
+
+
+def grade(
+    submitted_code: str,
+    task_id: str,
+    test_suite: str,
+    timeout: int = 10,
+) -> dict:
+    """
+    Grade submitted_code against test_suite.
+    Returns dict with: score, passed, total, valid_syntax, timed_out, test_results, error.
+    """
+    # Step 1: syntax check (fast, no subprocess needed)
+    try:
+        compile(submitted_code, "<submission>", "exec")
+        valid_syntax = True
+    except SyntaxError as e:
+        return {
+            "score": 0.0, "passed": 0, "total": 1,
+            "valid_syntax": False, "timed_out": False,
+            "test_results": [TestResult(name="syntax", passed=False, error=str(e))],
+            "error": f"SyntaxError: {e}",
+        }
+
+    # Step 2: build test module in a temp dir
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # Write submission
+        sub_path = Path(tmpdir) / "submission.py"
+        sub_path.write_text(submitted_code)
+
+        # Write test file (imports submission)
+        test_content = f"""
+import sys
+sys.path.insert(0, "{tmpdir}")
+from submission import *
+{test_suite}
+"""
+        test_path = Path(tmpdir) / "test_submission.py"
+        test_path.write_text(textwrap.dedent(test_content))
+
+        # Step 3: run pytest with JSON output
+        result_path = Path(tmpdir) / "results.json"
+        cmd = [
+            sys.executable, "-m", "pytest",
+            str(test_path),
+            "--tb=short",
+            "-q",
+            f"--json-report",
+            f"--json-report-file={result_path}",
+            "--timeout=8",
+        ]
+
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=tmpdir,
+                env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"},
+            )
+            timed_out = False
+        except subprocess.TimeoutExpired:
+            return {
+                "score": 0.0, "passed": 0, "total": 1,
+                "valid_syntax": True, "timed_out": True,
+                "test_results": [TestResult(name="timeout", passed=False, error="Timed out")],
+                "error": "TimeoutExpired",
+            }
+
+        # Step 4: parse results
+        if result_path.exists():
+            data = json.loads(result_path.read_text())
+            passed = data["summary"].get("passed", 0)
+            total  = data["summary"].get("total", 1)
+            test_results = [
+                TestResult(
+                    name=t["nodeid"],
+                    passed=(t["outcome"] == "passed"),
+                    error=t.get("call", {}).get("longrepr"),
+                )
+                for t in data.get("tests", [])
+            ]
+        else:
+            # Fallback: parse stdout
+            passed = proc.stdout.count(" passed")
+            total  = max(1, passed + proc.stdout.count(" failed") + proc.stdout.count(" error"))
+            test_results = []
+
+        score = passed / total if total > 0 else 0.0
+        return {
+            "score": round(score, 4),
+            "passed": passed,
+            "total": total,
+            "valid_syntax": True,
+            "timed_out": False,
+            "test_results": test_results,
+            "error": None,
+        }

server/requirements.txt

@@ -0,0 +1,8 @@
+fastapi>=0.110.0
+uvicorn[standard]>=0.27.0
+pydantic>=2.0.0
+pytest>=8.0.0
+pytest-timeout>=2.3.0
+pytest-json-report>=1.5.0
+accelerate>=0.28.0
+bitsandbytes>=0.43.0

server/task_generator.py

@@ -0,0 +1,52 @@
+# task_generator.py — generate task variants programmatically
+"""
+Generates variants of each task by injecting different bug patterns.
+Used to build a larger task pool for robust RL training.
+"""
+import random
+from typing import Iterator
+
+BUG_PATTERNS = [
+    # General Logic Bugs
+    ("off_by_one_minus", "len(arr)",        "len(arr) - 1"),
+    ("off_by_one_plus",  "range(n)",         "range(n + 1)"),
+    ("wrong_operator",   "current + nums[i]","current - nums[i]"),
+    ("wrong_init",       "max_sum = arr[0]", "max_sum = 0"),
+    ("wrong_comparison", "if a > b",         "if a >= b"),
+    ("wrong_return",     "return result",    "return result - 1"),
+    ("wrong_boolean",    "if not ",          "if "),
+
+    # String Parsing Bugs (targets task_medium)
+    ("wrong_split",      "split(';')",       "split(',')"),
+    ("missing_strip_1",  "key.strip()",      "key"),
+    ("missing_strip_2",  "value.strip()",    "value"),
+
+    # Dictionary/List Bugs (targets task_hard)
+    ("wrong_enumerate",  "enumerate(v)",     "enumerate(v, start=1)"),
+    ("wrong_recursion",  "new_key, sep)",    "new_key, '/')"),
+    ("missing_str_cast", "str_k = str(k)",   "str_k = k"),
+    ("wrong_list_index", "str(i)",           "str(i+1)"),
+    ("wrong_dict_check", "if not v:",        "if v:"),
+]
+
+
+def inject_bug(code: str, pattern: tuple) -> str:
+    _, find, replace = pattern
+    if find in code:
+        return code.replace(find, replace, 1)
+    return code  # pattern not applicable to this code
+
+
+def generate_task_variants(base_task: dict, n: int = 20) -> Iterator[dict]:
+    """Yield n variants of base_task with randomly injected bugs."""
+    for i in range(n):
+        pattern = random.choice(BUG_PATTERNS)
+        buggy = inject_bug(base_task["clean_code"], pattern)
+        if buggy == base_task["clean_code"]:
+            continue  # pattern not applicable
+        yield {
+            **base_task,
+            "task_id": f"{base_task['task_id']}_v{i:03d}",
+            "buggy_code": buggy,
+            "bug_pattern": pattern[0],
+        }

server/tasks/__init__.py

@@ -0,0 +1,17 @@
+# server/tasks/__init__.py
+from .task_easy   import TASK_EASY
+from .task_medium import TASK_MEDIUM
+from .task_hard   import TASK_HARD
+from ..task_generator import generate_task_variants
+
+TASK_REGISTRY: dict[str, dict] = {
+    "task_easy":   TASK_EASY,
+    "task_medium": TASK_MEDIUM,
+    "task_hard":   TASK_HARD,
+}
+
+# Generate 100 variants per task for the hackathon differentiator
+for base_task in [TASK_EASY, TASK_MEDIUM, TASK_HARD]:
+    # ensure base_task has a clean_code field if task_generator requires it, or just use buggy_code as base
+    for variant in generate_task_variants(base_task, n=100):
+        TASK_REGISTRY[variant["task_id"]] = variant

server/tasks/task_easy.py

@@ -0,0 +1,48 @@
+# server/tasks/task_easy.py
+TASK_EASY = {
+    "task_id": "task_easy",
+    "difficulty": "easy",
+    "num_tests": 4,
+    "description": (
+        "Fix the off-by-one error in the `find_max_subarray_sum` function. "
+        "It should return the maximum contiguous subarray sum (Kadane's algorithm). "
+        "Currently it misses the last element."
+    ),
+    # The broken version the agent sees
+    "buggy_code": """\
+def find_max_subarray_sum(nums: list[int]) -> int:
+    if not nums:
+        return 0
+    max_sum = current_sum = nums[0]
+    # BUG: range stops one short
+    for i in range(1, len(nums) - 1):
+        current_sum = max(nums[i], current_sum + nums[i])
+        max_sum = max(max_sum, current_sum)
+    return max_sum
+""",
+    # The correct solution (used by task_generator)
+    "clean_code": """\
+def find_max_subarray_sum(nums: list[int]) -> int:
+    if not nums:
+        return 0
+    max_sum = current_sum = nums[0]
+    for i in range(1, len(nums)):
+        current_sum = max(nums[i], current_sum + nums[i])
+        max_sum = max(max_sum, current_sum)
+    return max_sum
+""",
+    # Hidden test suite — agent never sees this directly
+    "test_suite": """\
+def test_basic():
+    assert find_max_subarray_sum([-2, 1, -3, 4, -1, 2, 1, -5, 4]) == 6
+
+def test_all_negative():
+    assert find_max_subarray_sum([-3, -1, -2]) == -1
+
+def test_single():
+    assert find_max_subarray_sum([42]) == 42
+
+def test_empty():
+    assert find_max_subarray_sum([]) == 0
+""",
+}

server/tasks/task_hard.py

@@ -0,0 +1,104 @@
+# server/tasks/task_hard.py
+TASK_HARD = {
+    "task_id": "task_hard",
+    "difficulty": "hard",
+    "num_tests": 10,
+    "description": (
+        "Fix 3+ subtle bugs in the `flatten_nested_dict` function. "
+        "It should recursively flatten a nested dictionary using dot-notation keys. "
+        "Example: {'a': {'b': 1}} → {'a.b': 1}. "
+        "Bug 1: wrong separator used in recursive calls. "
+        "Bug 2: lists are not handled correctly (should be indexed like 'a.0', 'a.1'). "
+        "Bug 3: empty dict values should produce the parent key with empty dict, not be skipped. "
+        "Bug 4: non-string keys are not converted to strings."
+    ),
+    # The broken version the agent sees
+    "buggy_code": """\
+def flatten_nested_dict(d: dict, parent_key: str = '', sep: str = '.') -> dict:
+    \"\"\"Flatten a nested dict into a single-level dict with dot-notation keys.
+    Lists should be expanded with numeric indices: {'a': [1,2]} → {'a.0': 1, 'a.1': 2}
+    Empty dicts should map to {}: {'a': {}} → {'a': {}}
+    Non-string keys should be converted to strings.\"\"\"
+    items = []
+    for k, v in d.items():
+        # BUG 4: k not converted to str
+        new_key = parent_key + sep + k if parent_key else k
+        if isinstance(v, dict):
+            # BUG 3: empty dict case not handled — this skips it entirely
+            # BUG 1: passes '/' instead of sep in recursive call
+            items.extend(flatten_nested_dict(v, new_key, '/').items())
+        elif isinstance(v, list):
+            # BUG 2: uses 1-based indexing instead of 0-based
+            for i, item in enumerate(v, start=1):
+                list_key = new_key + sep + str(i)
+                if isinstance(item, dict):
+                    items.extend(flatten_nested_dict(item, list_key, sep).items())
+                else:
+                    items.append((list_key, item))
+        else:
+            items.append((new_key, v))
+    return dict(items)
+""",
+    "clean_code": """\
+def flatten_nested_dict(d: dict, parent_key: str = '', sep: str = '.') -> dict:
+    \"\"\"Flatten a nested dict into a single-level dict with dot-notation keys.
+    Lists should be expanded with numeric indices: {'a': [1,2]} → {'a.0': 1, 'a.1': 2}
+    Empty dicts should map to {}: {'a': {}} → {'a': {}}
+    Non-string keys should be converted to strings.\"\"\"
+    items = []
+    for k, v in d.items():
+        str_k = str(k)
+        new_key = parent_key + sep + str_k if parent_key else str_k
+        if isinstance(v, dict):
+            if not v:
+                items.append((new_key, {}))
+            else:
+                items.extend(flatten_nested_dict(v, new_key, sep).items())
+        elif isinstance(v, list):
+            for i, item in enumerate(v):
+                list_key = new_key + sep + str(i)
+                if isinstance(item, dict):
+                    items.extend(flatten_nested_dict(item, list_key, sep).items())
+                else:
+                    items.append((list_key, item))
+        else:
+            items.append((new_key, v))
+    return dict(items)
+""",
+    "test_suite": """\
+def test_simple_flat():
+    assert flatten_nested_dict({"a": 1, "b": 2}) == {"a": 1, "b": 2}
+
+def test_one_level_nesting():
+    assert flatten_nested_dict({"a": {"b": 1}}) == {"a.b": 1}
+
+def test_deep_nesting():
+    assert flatten_nested_dict({"a": {"b": {"c": 3}}}) == {"a.b.c": 3}
+
+def test_mixed_nesting():
+    result = flatten_nested_dict({"a": 1, "b": {"c": 2, "d": {"e": 3}}})
+    assert result == {"a": 1, "b.c": 2, "b.d.e": 3}
+
+def test_list_values():
+    assert flatten_nested_dict({"a": [10, 20, 30]}) == {"a.0": 10, "a.1": 20, "a.2": 30}
+
+def test_nested_list_of_dicts():
+    inp = {"users": [{"name": "Alice"}, {"name": "Bob"}]}
+    expected = {"users.0.name": "Alice", "users.1.name": "Bob"}
+    assert flatten_nested_dict(inp) == expected
+
+def test_empty_dict_value():
+    assert flatten_nested_dict({"a": {}, "b": 1}) == {"a": {}, "b": 1}
+
+def test_empty_input():
+    assert flatten_nested_dict({}) == {}
+
+def test_numeric_keys():
+    assert flatten_nested_dict({1: "a", 2: {"3": "b"}}) == {"1": "a", "2.3": "b"}
+
+def test_complex_mixed():
+    inp = {"x": [{"y": [1, 2]}, {"z": 3}], "w": 4}
+    expected = {"x.0.y.0": 1, "x.0.y.1": 2, "x.1.z": 3, "w": 4}
+    assert flatten_nested_dict(inp) == expected
+""",
+}

server/tasks/task_medium.py

@@ -0,0 +1,64 @@
+# server/tasks/task_medium.py
+TASK_MEDIUM = {
+    "task_id": "task_medium",
+    "difficulty": "medium",
+    "num_tests": 6,
+    "description": (
+        "Fix two independent bugs in the `parse_key_value` function. "
+        "It should parse a string of 'key=value' pairs separated by semicolons "
+        "into a dictionary. Bug 1: it splits on the wrong delimiter for pairs. "
+        "Bug 2: it doesn't strip whitespace from keys and values."
+    ),
+    # The broken version the agent sees
+    "buggy_code": """\
+def parse_key_value(s: str) -> dict[str, str]:
+    \"\"\"Parse 'key1=val1;key2=val2' into {'key1': 'val1', 'key2': 'val2'}.
+    Handles whitespace around keys/values. Returns empty dict for empty string.\"\"\"
+    if not s or not s.strip():
+        return {}
+    result = {}
+    # BUG 1: splits on ',' instead of ';'
+    pairs = s.split(',')
+    for pair in pairs:
+        if '=' not in pair:
+            continue
+        key, value = pair.split('=', 1)
+        # BUG 2: missing .strip() on key and value
+        result[key] = value
+    return result
+""",
+    "clean_code": """\
+def parse_key_value(s: str) -> dict[str, str]:
+    \"\"\"Parse 'key1=val1;key2=val2' into {'key1': 'val1', 'key2': 'val2'}.
+    Handles whitespace around keys/values. Returns empty dict for empty string.\"\"\"
+    if not s or not s.strip():
+        return {}
+    result = {}
+    pairs = s.split(';')
+    for pair in pairs:
+        if '=' not in pair:
+            continue
+        key, value = pair.split('=', 1)
+        result[key.strip()] = value.strip()
+    return result
+""",
+    "test_suite": """\
+def test_basic():
+    assert parse_key_value("name=Alice;age=30") == {"name": "Alice", "age": "30"}
+
+def test_whitespace():
+    assert parse_key_value(" name = Alice ; age = 30 ") == {"name": "Alice", "age": "30"}
+
+def test_empty():
+    assert parse_key_value("") == {}
+
+def test_single_pair():
+    assert parse_key_value("key=value") == {"key": "value"}
+
+def test_value_with_equals():
+    assert parse_key_value("expr=a=b;other=c") == {"expr": "a=b", "other": "c"}
+
+def test_whitespace_only():
+    assert parse_key_value("   ") == {}
+""",
+}

test_client.py

@@ -0,0 +1,17 @@
+import asyncio
+from code_debug_env.client import CodeDebugEnv
+from code_debug_env.models import Action
+
+async def test():
+    async with CodeDebugEnv(base_url="http://127.0.0.1:8000") as env:
+        obs = await env.reset(task_id="task_easy")
+        print("Reset OK:", obs.observation.buggy_code[:20])
+        action = Action(patch="def foo(): pass", task_id="task_easy")
+        print("Sending step...")
+        try:
+            res = await env.step(action)
+            print("Step OK", res)
+        except Exception as e:
+            print("Exception during step:", repr(e))
+
+asyncio.run(test())