Upload folder using huggingface_hub

core/__init__.py

@@ -1,5 +1,6 @@
 """CI/CD Doctor environment subpackage."""
 
-from .grader import grade
+from .grading.grader import grade
+from .utils.packages import get_packages
 
-__all__ = [ "grade"]
+__all__ = [ "grade","get_packages"]

core/grading/grader.py

@@ -0,0 +1,143 @@
+"""
+Grader for the CI/CD Doctor environment.
+
+Reward shape:
+  fixes_applied_fraction * 0.35   proportional credit for each answer_key fix
+                                  that is present in the filesystem (emitted
+                                  incrementally as each fix lands, not all-or-
+                                  nothing — on a 2-fix task, each fix is worth
+                                  +0.175)
+  pipeline_passed       +0.50     pipeline_status == "passed" (terminal)
+
+Total positive: 0.85 from grade() + shaped bonuses from balance_score().
+
+Investigation milestones (investigated, logs_read, correct_file_located) are
+still tracked in state.milestones for the balance_score() logic but give no
+reward — reading a file is not progress, fixing it is.
+
+balance_score() applies per-step shaped adjustments on top of the tier delta:
+  +0.05  First read of each answer-key file (exploration bonus, max 2 files)
+  -0.05  cat on a file already read this episode (redundant read penalty)
+  -0.10  pipeline run with no filesystem changes since last run (idle run)
+  -0.01 * overage  each step taken beyond the task's ideal step count
+         (efficiency penalty scales linearly with how far past ideal — at
+         ideal+1 it's -0.01, at ideal+5 it's -0.05; cumulative cost on a
+         9-step overage tops out around -0.45)
+  -0.08  agent has read the correct file but runs pipeline again with no edit
+         (exploitation trap — knows the problem, not acting on it)
+"""
+
+from dataclasses import dataclass, field
+
+from models import PipelineState
+
+CORRECT_FILE_EDITED_TOTAL = 0.2
+
+TIER_REWARDS: dict[str, float] = {
+    "investigated": 0.0,
+    "logs_read": 0.0,
+    "correct_file_located": 0.01,
+    "pipeline_passed": 0.50,
+    "optimal_step":0.05
+}
+
+PENALTIES: dict[str, float] = {
+    "idle_pipeline_run": -0.10,
+    "redundant_read": -0.05,
+    "over_ideal_step": -0.01,
+    "exploitation_trap": -0.08,
+}
+
+@dataclass
+class StepContext:
+    cmd_type: str
+    filename: str | None = None
+    files_read: set[str] = field(default_factory=set)
+    fs_changed_since_last_run: bool = True
+    step_count: int = 0
+    max_steps: int = 15
+    ideal_steps: int = 6
+    pipeline_runs_since_last_edit: int = 0
+
+
+def _fixes_applied_fraction(state: PipelineState) -> float:
+    """
+    Fraction of answer_key fixes that are currently present in the filesystem.
+    Returns a value in [0.0, 1.0]. Each fix contributes incrementally the
+    moment its fragment appears in the target file, so a 2-fix task rewards
+    each correct edit as it happens rather than only when both are done.
+    """
+    fixes = state.answer_key.get("fixes", {})
+    if not fixes:
+        return 0.0
+    applied = sum(
+        1 for filename, fragment in fixes.items()
+        if fragment in state.filesystem.get(filename, "")
+    )
+    return applied / len(fixes)
+
+
+def grade(state: PipelineState) -> float:
+    """
+    Compute the total earned grade from state. Fractional credit for fixes
+    in the filesystem, plus the terminal bonus on pipeline pass. Investigation
+    milestones contribute 0 — reading a file is not progress, fixing it is.
+    """
+    score = CORRECT_FILE_EDITED_TOTAL * _fixes_applied_fraction(state)
+
+    unlocked = set(state.milestones)
+    if state.pipeline_status == "passed":
+        unlocked.add("pipeline_passed")
+    score += sum(TIER_REWARDS[tier] for tier in unlocked if tier in TIER_REWARDS)
+
+    return round(score, 2)
+
+
+def balance_score(state: PipelineState, ctx: StepContext) -> float:
+    """
+    Per-step shaped reward adjustment on top of the raw grade delta.
+
+    Returns a float (may be negative). The caller adds this to the grade
+    delta to produce the final step reward.
+
+    The two goals:
+      - Encourage exploration: small bonus the first time the agent reads a
+        file that needs fixing (up to 2 files per episode).
+      - Discourage waste: penalties for re-reading, idle pipeline runs,
+        burning the step budget, and knowing the fix but not applying it.
+    """
+    adjustment = 0.0
+    fix_files = set(state.answer_key.get("fixes", {}).keys())
+
+    if ctx.cmd_type == "cat" and ctx.filename:
+        if ctx.filename in fix_files and ctx.filename not in ctx.files_read:
+            # First read of a file that needs fixing — exploration bonus.
+            # Cap at 2 files total to avoid rewarding excessive exploration.
+            already_explored = sum(1 for f in ctx.files_read if f in fix_files)
+            if already_explored < 2:
+                adjustment += 0.05
+        elif ctx.filename in ctx.files_read:
+            # Already read this file — wasted step.
+            adjustment += PENALTIES["redundant_read"]
+
+    if ctx.cmd_type == "pipeline_run":
+        if not ctx.fs_changed_since_last_run:
+            # Nothing changed since the last run — this reveals no new info.
+            adjustment += PENALTIES["idle_pipeline_run"]
+
+        if (
+            "correct_file_located" in state.milestones
+            and ctx.pipeline_runs_since_last_edit >= 1
+        ):
+            # Agent has already read the right file and run the pipeline at
+            # least once since its last edit — it knows what to fix but is
+            # stalling instead of applying the fix.
+            adjustment += PENALTIES["exploitation_trap"]
+
+    if ctx.step_count > ctx.ideal_steps:
+        overage = ctx.step_count - ctx.ideal_steps
+        adjustment += PENALTIES["over_ideal_step"] * overage
+    else: 
+        adjustment += TIER_REWARDS["optimal_step"]
+
+    return round(adjustment, 2)

core/pipeline/stage_runner.py

@@ -0,0 +1,396 @@
+"""
+Simulated pipeline stage runner for the CI/CD Doctor environment.
+No real pip or subprocess — pure deterministic logic.
+
+Error message design principle: report WHICH stage failed and WHICH file to
+inspect, but NOT the exact value that is wrong. The agent must read the file
+and reason about the fix itself.
+"""
+
+import re
+
+from core.validation.validator import validate_ci_stages, parse_stages
+
+from core.utils.packages import get_packages_set
+
+CORRECT_PYTHON_VERSION = "3.11"
+REQUIRED_ENV_VARS = {"DATABASE_URL", "API_KEY", "SECRET_KEY"}
+
+def run_install_stage(filesystem: dict, task: str = "easy") -> dict:
+    """
+    Reads requirements.txt. Fails if any required package is missing, or
+    (hard task) if numpy is pinned to an incompatible version.
+
+    Version pins are stripped before comparing against the required set, so
+    `numpy==1.21` parses as `numpy` for the missing-package check.
+    """
+    required = get_packages_set(task)
+    content = filesystem.get("requirements.txt", "")
+    installed = {
+        re.split(r"[=<>!]", line, 1)[0].strip().lower()
+        for line in content.splitlines()
+        if line.strip()
+    }
+    missing = required - installed
+
+    if missing:
+        pkg = sorted(missing)[0]
+        logs = "Collecting dependencies...\n"
+        logs += f"  Collecting {pkg}\n"
+        logs += f"ERROR: Could not find a version that satisfies the requirement {pkg}\n"
+        logs += f"ERROR: No matching distribution found for {pkg}\n"
+        logs += "  Add the missing package to requirements.txt.\n"
+        return {"exit_code": 1, "logs": logs}
+
+    if task == "hard" and "numpy==1.21" in content:
+        logs = "Collecting dependencies...\n"
+        logs += "  Collecting numpy==1.21\n"
+        logs += "ERROR: ResolutionImpossible: dependency conflict detected.\n"
+        logs += "  requirements.txt pins numpy==1.21, but a transitive dependency\n"
+        logs += "  requires numpy>=1.26. Update the numpy pin in requirements.txt.\n"
+        return {"exit_code": 1, "logs": logs}
+
+    logs = "Collecting dependencies...\n"
+    logs += "Successfully installed " + " ".join(sorted(required)) + "\n"
+    return {"exit_code": 0, "logs": logs}
+
+
+def run_env_check_stage(filesystem: dict) -> dict:
+    """
+    Checks that .env.ci defines all required environment variables.
+    Error reports which variables are required so the agent can compare against the file.
+    """
+    content = filesystem.get(".env.ci", "")
+    defined = {
+        line.split("=")[0].strip()
+        for line in content.splitlines()
+        if "=" in line and line.strip()
+    }
+    missing = REQUIRED_ENV_VARS - defined
+
+    if not missing:
+        logs = "Environment check passed.\n"
+        logs += "All required variables present: " + ", ".join(sorted(REQUIRED_ENV_VARS)) + "\n"
+        return {"exit_code": 0, "logs": logs}
+    else:
+        logs = "Environment check failed.\n"
+        logs += f"  Required variables: {', '.join(sorted(REQUIRED_ENV_VARS))}\n"
+        logs += "  Not all required variables are defined in .env.ci.\n"
+        return {"exit_code": 1, "logs": logs}
+
+
+def run_docker_build_stage(filesystem: dict, strict_tag: bool = False) -> dict:
+    """
+    Checks that Dockerfile uses the correct Python base image.
+
+    In the default (medium) mode, any `python:3.11` tag is accepted. With
+    `strict_tag=True` (hard task), the full tag must be `python:3.11-slim` —
+    the alpine variant is rejected because it lacks the glibc-based system
+    libraries that the project's native-code dependencies need.
+    """
+    content = filesystem.get("Dockerfile", "")
+
+    if strict_tag:
+        if "python:3.11-slim" in content:
+            logs = "Step 1/5 : FROM python:3.11-slim\n"
+            logs += "Successfully built docker image\n"
+            return {"exit_code": 0, "logs": logs}
+        logs = "Step 1/5 : FROM ...\n"
+        logs += "ERROR: Docker build failed.\n"
+        logs += "  Base image rejected: the alpine variant lacks the system\n"
+        logs += "  libraries (glibc, build tools) required by the project's\n"
+        logs += "  native dependencies.\n"
+        logs += "  Expected base image: python:3.11-slim\n"
+        logs += "  Inspect your Dockerfile.\n"
+        return {"exit_code": 1, "logs": logs}
+
+    if f"python:{CORRECT_PYTHON_VERSION}" in content:
+        logs = f"Step 1/5 : FROM python:{CORRECT_PYTHON_VERSION}-slim\n"
+        logs += "Successfully built docker image\n"
+        return {"exit_code": 0, "logs": logs}
+    logs = "Step 1/5 : FROM ...\n"
+    logs += "ERROR: Docker build failed.\n"
+    logs += f"  Expected base image: python:{CORRECT_PYTHON_VERSION}-slim\n"
+    logs += "  Inspect your Dockerfile.\n"
+    return {"exit_code": 1, "logs": logs}
+
+
+def run_config_validate_stage(filesystem: dict) -> dict:
+    """
+    Checks that deploy_config.yml has deploy_enabled: true.
+    Error reports expected field value so the agent can compare against the file.
+    """
+    content = filesystem.get("deploy_config.yml", "")
+    if "deploy_enabled: true" in content:
+        logs = "Deployment configuration validated.\n"
+        logs += "All required settings are correct.\n"
+        return {"exit_code": 0, "logs": logs}
+    else:
+        logs = "ERROR: Deployment configuration is invalid.\n"
+        logs += "  deploy_enabled must be 'true' in deploy_config.yml.\n"
+        return {"exit_code": 1, "logs": logs}
+
+
+def run_smoke_test_stage(filesystem: dict) -> dict:
+    """Always passes — reached only when prior stages succeed."""
+    return {"exit_code": 0, "logs": "Smoke test passed. Application started successfully.\n"}
+
+
+def run_test_stage(filesystem: dict) -> dict:
+    """
+    Checks that the Makefile's test target runs pytest correctly.
+    Fails if the command is --collect-only, --dry-run, or uses unittest.
+    Error reports expected command so the agent can compare against the file.
+    """
+    content = filesystem.get("Makefile", "")
+    correct = (
+        "python -m pytest tests/" in content
+        and "--collect-only" not in content
+        and "--dry-run" not in content
+        and "unittest" not in content
+    )
+    if correct:
+        logs = "Running test suite...\n"
+        logs += "All tests passed.\n"
+        return {"exit_code": 0, "logs": logs}
+    else:
+        logs = "ERROR: Test runner failed.\n"
+        logs += "  Expected test command: python -m pytest tests/\n"
+        logs += "  Check the test command in your Makefile.\n"
+        return {"exit_code": 1, "logs": logs}
+
+
+def run_port_check_stage(filesystem: dict) -> dict:
+    """
+    Checks that service.yaml exposes port 8080.
+    Error reports expected port so the agent can compare against the file.
+    """
+    content = filesystem.get("service.yaml", "")
+    if "port: 8080" in content:
+        logs = "Service configuration validated.\n"
+        logs += "Port binding is correct.\n"
+        return {"exit_code": 0, "logs": logs}
+    else:
+        logs = "ERROR: Service configuration validation failed.\n"
+        logs += "  Expected port: 8080. Inspect service.yaml.\n"
+        return {"exit_code": 1, "logs": logs}
+
+def run_ci_validate_stage(filesystem: dict) -> dict:
+    """
+    Checks that ci.yml defines stages in the correct order: install (and
+    build, if present) must appear before test.
+
+    Expected format is a single comma-separated line like:
+        stages: install, build, test
+    """
+    content = filesystem.get("ci.yml", "")
+    try:
+        validate_ci_stages(content)
+    except ValueError as e:
+        return {"exit_code": 1, "logs": f"ERROR: {str(e)}\n"}
+
+    return {"exit_code": 0, "logs": "ci.yml validation passed. Stage order is correct.\n"}
+
+def _run_medium_type_a_pipeline(filesystem: dict) -> dict:
+    """install (always passes) → env_check → docker_build"""
+    combined_logs = ""
+
+    install = run_install_stage(filesystem, task="medium")
+    combined_logs += "=== Stage: install ===\n" + install["logs"]
+    if install["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    env = run_env_check_stage(filesystem)
+    combined_logs += "=== Stage: env_check ===\n" + env["logs"]
+    if env["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    docker = run_docker_build_stage(filesystem)
+    combined_logs += "=== Stage: docker_build ===\n" + docker["logs"]
+    return {"exit_code": docker["exit_code"], "logs": combined_logs}
+
+
+def _run_medium_type_b_pipeline(filesystem: dict) -> dict:
+    """install (missing pkg) → config_validate → smoke_test"""
+    combined_logs = ""
+
+    install = run_install_stage(filesystem, task="medium")
+    combined_logs += "=== Stage: install ===\n" + install["logs"]
+    if install["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    config = run_config_validate_stage(filesystem)
+    combined_logs += "=== Stage: config_validate ===\n" + config["logs"]
+    if config["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    smoke = run_smoke_test_stage(filesystem)
+    combined_logs += "=== Stage: smoke_test ===\n" + smoke["logs"]
+    return {"exit_code": smoke["exit_code"], "logs": combined_logs}
+
+
+def _run_medium_type_c_pipeline(filesystem: dict) -> dict:
+    """install (always passes) → env_check → test (Makefile)"""
+    combined_logs = ""
+
+    install = run_install_stage(filesystem, task="medium")
+    combined_logs += "=== Stage: install ===\n" + install["logs"]
+    if install["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    env = run_env_check_stage(filesystem)
+    combined_logs += "=== Stage: env_check ===\n" + env["logs"]
+    if env["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    test = run_test_stage(filesystem)
+    combined_logs += "=== Stage: test ===\n" + test["logs"]
+    return {"exit_code": test["exit_code"], "logs": combined_logs}
+
+
+def _run_medium_type_d_pipeline(filesystem: dict) -> dict:
+    """install (always passes) → port_check → docker_build"""
+    combined_logs = ""
+
+    install = run_install_stage(filesystem, task="medium")
+    combined_logs += "=== Stage: install ===\n" + install["logs"]
+    if install["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    port = run_port_check_stage(filesystem)
+    combined_logs += "=== Stage: port_check ===\n" + port["logs"]
+    if port["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    docker = run_docker_build_stage(filesystem)
+    combined_logs += "=== Stage: docker_build ===\n" + docker["logs"]
+    return {"exit_code": docker["exit_code"], "logs": combined_logs}
+
+
+def _run_medium_pipeline(filesystem: dict) -> dict:
+    """
+    Detects scenario type from the filesystem and dispatches to the right runner.
+    Each type has a unique distinguishing file:
+      Type B → deploy_config.yml
+      Type C → Makefile
+      Type D → service.yaml
+      Type A → fallback (Dockerfile + .env.ci)
+    """
+    if "Makefile" in filesystem:
+        return _run_medium_type_c_pipeline(filesystem)
+    elif "deploy_config.yml" in filesystem:
+        return _run_medium_type_b_pipeline(filesystem)
+    elif "service.yaml" in filesystem:
+        return _run_medium_type_d_pipeline(filesystem)
+    else:
+        return _run_medium_type_a_pipeline(filesystem)
+
+
+def _run_hard_type_a_pipeline(filesystem: dict) -> dict:
+    """ci_validate → docker_build(strict) → install(hard)."""
+    combined_logs = ""
+
+    ci = run_ci_validate_stage(filesystem)
+    combined_logs += "=== Stage: ci_validate ===\n" + ci["logs"]
+    if ci["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    docker = run_docker_build_stage(filesystem, strict_tag=True)
+    combined_logs += "=== Stage: docker_build ===\n" + docker["logs"]
+    if docker["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    install = run_install_stage(filesystem, task="hard")
+    combined_logs += "=== Stage: install ===\n" + install["logs"]
+    return {"exit_code": install["exit_code"], "logs": combined_logs}
+
+
+def _run_hard_type_b_pipeline(filesystem: dict) -> dict:
+    """ci_validate → env_check → test (Makefile)."""
+    combined_logs = ""
+
+    ci = run_ci_validate_stage(filesystem)
+    combined_logs += "=== Stage: ci_validate ===\n" + ci["logs"]
+    if ci["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    env = run_env_check_stage(filesystem)
+    combined_logs += "=== Stage: env_check ===\n" + env["logs"]
+    if env["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    test = run_test_stage(filesystem)
+    combined_logs += "=== Stage: test ===\n" + test["logs"]
+    return {"exit_code": test["exit_code"], "logs": combined_logs}
+
+
+def _run_hard_type_c_pipeline(filesystem: dict) -> dict:
+    """docker_build(strict) → config_validate → port_check."""
+    combined_logs = ""
+
+    docker = run_docker_build_stage(filesystem, strict_tag=True)
+    combined_logs += "=== Stage: docker_build ===\n" + docker["logs"]
+    if docker["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    config = run_config_validate_stage(filesystem)
+    combined_logs += "=== Stage: config_validate ===\n" + config["logs"]
+    if config["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    port = run_port_check_stage(filesystem)
+    combined_logs += "=== Stage: port_check ===\n" + port["logs"]
+    return {"exit_code": port["exit_code"], "logs": combined_logs}
+
+
+def _run_hard_type_d_pipeline(filesystem: dict) -> dict:
+    """install(hard, missing pkg) → env_check → docker_build(strict)."""
+    combined_logs = ""
+
+    install = run_install_stage(filesystem, task="hard")
+    combined_logs += "=== Stage: install ===\n" + install["logs"]
+    if install["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    env = run_env_check_stage(filesystem)
+    combined_logs += "=== Stage: env_check ===\n" + env["logs"]
+    if env["exit_code"] != 0:
+        return {"exit_code": 1, "logs": combined_logs}
+
+    docker = run_docker_build_stage(filesystem, strict_tag=True)
+    combined_logs += "=== Stage: docker_build ===\n" + docker["logs"]
+    return {"exit_code": docker["exit_code"], "logs": combined_logs}
+
+
+def _run_hard_pipeline(filesystem: dict) -> dict:
+    """
+    Detects hard scenario variant from the filesystem and dispatches.
+    Cascading failures: each stage is only reached after the previous
+    passes, so bugs surface one at a time as the agent fixes them.
+
+    Distinguishing markers:
+      Type B → ci.yml + Makefile
+      Type A → ci.yml alone
+      Type C → service.yaml (with deploy_config.yml)
+      Type D → fallback (Dockerfile + .env.ci, no ci.yml)
+    """
+    if "ci.yml" in filesystem and "Makefile" in filesystem:
+        return _run_hard_type_b_pipeline(filesystem)
+    if "ci.yml" in filesystem:
+        return _run_hard_type_a_pipeline(filesystem)
+    if "service.yaml" in filesystem:
+        return _run_hard_type_c_pipeline(filesystem)
+    return _run_hard_type_d_pipeline(filesystem)
+
+
+def run_pipeline(filesystem: dict, task: str = "easy") -> dict:
+    """
+    Top-level dispatcher. Call this from environment.py.
+    Returns {"exit_code": int, "logs": str}.
+    """
+    if task == "medium":
+        return _run_medium_pipeline(filesystem)
+    elif task == "hard":
+        return _run_hard_pipeline(filesystem)
+    else:
+        return run_install_stage(filesystem, task=task)

core/scenarios/generator.py

@@ -0,0 +1,433 @@
+"""
+Procedural scenario generator for the CI/CD Doctor environment.
+"""
+
+import random
+
+from core.utils.packages import get_packages
+
+PYTHON_VERSIONS = ["3.9", "3.10"]       # always wrong; correct is 3.11
+REQUIRED_ENV_VARS = ["DATABASE_URL", "API_KEY", "SECRET_KEY"]
+WRONG_PORTS = [3000, 5000, 9000]
+WRONG_TEST_COMMANDS = [
+    "python -m pytest tests/ --collect-only",   # collects but never runs
+    "python -m unittest discover tests/",        # wrong runner
+    "python -m pytest tests/ --dry-run",         # dry-run, no output
+]
+
+
+def generate_easy_scenario(seed: int) -> dict:
+    """
+    Returns a filesystem dict + answer_key.
+    The filesystem has requirements.txt missing one required package.
+    """
+    rng = random.Random(seed)
+    all_packages = get_packages("easy")
+    missing = rng.choice(all_packages)
+    present = [p for p in all_packages if p != missing]
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(present) + "\n",
+            "pipeline.yaml": "stages:\n  - install\n",
+            "logs/install.log": "",
+            "app.py": "import flask\nimport numpy\n# app code here\n",
+        },
+        "answer_key": {
+            "fixes": {
+                "requirements.txt": missing,
+            },
+        },
+    }
+
+def _medium_type_a(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type A: wrong Python version (Dockerfile) + missing env var (.env.ci).
+    Pipeline: install → env_check → docker_build
+    Both files must be fixed. install always passes.
+    """
+    wrong_version = rng.choice(PYTHON_VERSIONS)
+    missing_var = rng.choice(REQUIRED_ENV_VARS)
+    present_vars = {v: "placeholder" for v in REQUIRED_ENV_VARS if v != missing_var}
+    env_ci_content = "".join(f"{k}={v}\n" for k, v in sorted(present_vars.items()))
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(all_packages) + "\n",
+            "Dockerfile": (
+                f"FROM python:{wrong_version}-slim\n"
+                "WORKDIR /app\n"
+                "COPY requirements.txt .\n"
+                "RUN pip install -r requirements.txt\n"
+                "COPY . .\n"
+                'CMD ["python", "app.py"]\n'
+            ),
+            ".env.ci": env_ci_content,
+            "pipeline.yaml": "stages:\n  - install\n  - env_check\n  - docker_build\n",
+            "app.py": "import flask\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                "Dockerfile": "python:3.11",
+                ".env.ci": missing_var,
+            },
+        },
+    }
+
+
+def _medium_type_b(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type B: missing package (requirements.txt) + deployment flag off (deploy_config.yml).
+    Pipeline: install → config_validate → smoke_test
+    install fails first; after fixing, config_validate fails.
+    """
+    missing_pkg = rng.choice(all_packages)
+    present_pkgs = [p for p in all_packages if p != missing_pkg]
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(present_pkgs) + "\n",
+            "deploy_config.yml": (
+                "target_env: production\n"
+                "deploy_enabled: false\n"   # BUG: must be true
+                "replicas: 2\n"
+                "health_check_path: /health\n"
+                "timeout: 30\n"
+            ),
+            "pipeline.yaml": "stages:\n  - install\n  - config_validate\n  - smoke_test\n",
+            "app.py": "import flask\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                "requirements.txt": missing_pkg,
+                "deploy_config.yml": "deploy_enabled: true",
+            },
+        },
+    }
+
+
+def _medium_type_c(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type C: wrong test command (Makefile) + missing env var (.env.ci).
+    Pipeline: install → env_check → test
+    env_check fails first; after fixing, test fails due to bad Makefile.
+    """
+    wrong_cmd = rng.choice(WRONG_TEST_COMMANDS)
+    missing_var = rng.choice(REQUIRED_ENV_VARS)
+    present_vars = {v: "placeholder" for v in REQUIRED_ENV_VARS if v != missing_var}
+    env_ci_content = "".join(f"{k}={v}\n" for k, v in sorted(present_vars.items()))
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(all_packages) + "\n",
+            ".env.ci": env_ci_content,
+            "Makefile": (
+                ".PHONY: test\n"
+                "test:\n"
+                f"\t{wrong_cmd}\n"
+            ),
+            "pipeline.yaml": "stages:\n  - install\n  - env_check\n  - test\n",
+            "app.py": "import flask\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                ".env.ci": missing_var,
+                "Makefile": "python -m pytest tests/",
+            },
+        },
+    }
+
+
+def _medium_type_d(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type D: wrong port (service.yaml) + wrong Python version (Dockerfile).
+    Pipeline: install → port_check → docker_build
+    port_check fails first; after fixing, docker_build fails.
+    install always passes.
+    """
+    wrong_version = rng.choice(PYTHON_VERSIONS)
+    wrong_port = rng.choice(WRONG_PORTS)
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(all_packages) + "\n",
+            "Dockerfile": (
+                f"FROM python:{wrong_version}-slim\n"
+                "WORKDIR /app\n"
+                "COPY requirements.txt .\n"
+                "RUN pip install -r requirements.txt\n"
+                "COPY . .\n"
+                'CMD ["python", "app.py"]\n'
+            ),
+            "service.yaml": (
+                "apiVersion: v1\n"
+                "kind: Service\n"
+                "metadata:\n"
+                "  name: app\n"
+                "spec:\n"
+                f"  port: {wrong_port}\n"
+            ),
+            "pipeline.yaml": "stages:\n  - install\n  - port_check\n  - docker_build\n",
+            "app.py": "import flask\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                "service.yaml": "port: 8080",
+                "Dockerfile": "python:3.11",
+            },
+        },
+    }
+
+
+def generate_medium_scenario(seed: int) -> dict:
+    """
+    Randomly selects one of four structurally distinct medium scenario types,
+    then generates the specifics (which var, which version, etc.) from the
+    same seed. Same seed → same scenario every time.
+    """
+    rng = random.Random(seed)
+    all_packages = get_packages("medium")
+    scenario_type = rng.choice(["A", "B", "C", "D"])
+
+    if scenario_type == "A":
+        return _medium_type_a(rng, all_packages)
+    elif scenario_type == "B":
+        return _medium_type_b(rng, all_packages)
+    elif scenario_type == "C":
+        return _medium_type_c(rng, all_packages)
+    else:
+        return _medium_type_d(rng, all_packages)
+
+
+def _hard_type_a(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type A (Interdependent):
+    ci.yml ordering → Dockerfile alpine → numpy version pin.
+
+    Behavior:
+    - docker_build fails first due to alpine
+    - AFTER fixing Docker base, install fails due to numpy incompatibility
+    - Demonstrates interdependent failures (fixing one reveals another)
+
+    Pipeline: ci_validate → docker_build(strict) → install(hard).
+    """
+    _ = rng
+
+    # numpy version only breaks AFTER Docker base is fixed (alpine -> slim)
+    requirements_lines = [
+        "numpy==1.21" if pkg == "numpy" else pkg
+        for pkg in all_packages
+    ]
+
+    # Randomize ci.yml format (inline vs YAML list)
+    if rng.random() < 0.5:
+        ci_content = "stages: test, build, install\n"
+        ci_fix = "stages: install, build, test\n"
+    else:
+        ci_content = (
+            "stages:\n"
+            "  - test\n"
+            "  - build\n"
+            "  - install\n"
+        )
+        ci_fix = (
+            "stages:\n"
+            "  - install\n"
+            "  - build\n"
+            "  - test\n"
+        )
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(requirements_lines) + "\n",
+            "Dockerfile": (
+                "FROM python:3.11-alpine\n"  # BUG 1: causes build failure first
+                "WORKDIR /app\n"
+                "COPY requirements.txt .\n"
+                "RUN pip install -r requirements.txt\n"  # BUG 2 surfaces only after base fix
+                "COPY . .\n"
+                'CMD ["python", "app.py"]\n'
+            ),
+            "ci.yml": ci_content,
+            "pipeline.yaml": "stages:\n  - ci_validate\n  - docker_build\n  - install\n",
+            "app.py": "import flask\nimport numpy\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                "ci.yml": ci_fix,
+                "Dockerfile": "python:3.11-slim",
+                "requirements.txt": "numpy==1.26",
+            },
+        },
+    }
+
+
+def _hard_type_b(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type B (Interdependent):
+    ci.yml ordering → missing env var → wrong test command.
+
+    Behavior:
+    - env_check fails first
+    - AFTER fixing env, test stage fails due to bad command
+
+    Demonstrates dependency between runtime config and execution.
+
+    Pipeline: ci_validate → env_check → test.
+    """
+    wrong_cmd = rng.choice(WRONG_TEST_COMMANDS)
+    missing_var = rng.choice(REQUIRED_ENV_VARS)
+    present_vars = {v: "placeholder" for v in REQUIRED_ENV_VARS if v != missing_var}
+    env_ci_content = "".join(f"{k}={v}\n" for k, v in sorted(present_vars.items()))
+
+    if rng.random() < 0.5:
+        ci_content = "stages: test, build, install\n"
+        ci_fix = "stages: install, build, test\n"
+    else:
+        ci_content = (
+            "stages:\n"
+            "  - test\n"
+            "  - build\n"
+            "  - install\n"
+        )
+        ci_fix = (
+            "stages:\n"
+            "  - install\n"
+            "  - build\n"
+            "  - test\n"
+        )
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(all_packages) + "\n",
+            "ci.yml": ci_content,
+            ".env.ci": env_ci_content,
+            "Makefile": (
+                ".PHONY: test\n"
+                "test:\n"
+                f"\t{wrong_cmd}\n"  # BUG surfaces only after env is fixed
+            ),
+            "pipeline.yaml": "stages:\n  - ci_validate\n  - env_check\n  - test\n",
+            "app.py": "import flask\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                "ci.yml": ci_fix,
+                ".env.ci": missing_var,
+                "Makefile": "python -m pytest tests/",
+            },
+        },
+    }
+
+
+def _hard_type_c(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type C: Dockerfile alpine → deploy disabled → wrong service port.
+    Pipeline: docker_build(strict) → config_validate → port_check.
+    """
+    _ = rng  # reserved for future per-seed variation
+    wrong_port = rng.choice(WRONG_PORTS)
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(all_packages) + "\n",
+            "Dockerfile": (
+                "FROM python:3.11-alpine\n"
+                "WORKDIR /app\n"
+                "COPY requirements.txt .\n"
+                "RUN pip install -r requirements.txt\n"
+                "COPY . .\n"
+                'CMD ["python", "app.py"]\n'
+            ),
+            "deploy_config.yml": (
+                "target_env: production\n"
+                "deploy_enabled: false\n"
+                "replicas: 2\n"
+                "health_check_path: /health\n"
+                "timeout: 30\n"
+            ),
+            "service.yaml": (
+                "apiVersion: v1\n"
+                "kind: Service\n"
+                "metadata:\n"
+                "  name: app\n"
+                "spec:\n"
+                f"  port: {wrong_port}\n"
+            ),
+            "pipeline.yaml": "stages:\n  - docker_build\n  - config_validate\n  - port_check\n",
+            "app.py": "import flask\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                "Dockerfile": "python:3.11-slim",
+                "deploy_config.yml": "deploy_enabled: true",
+                "service.yaml": "port: 8080",
+            },
+        },
+    }
+
+
+def _hard_type_d(rng: random.Random, all_packages: list) -> dict:
+    """
+    Type D: missing package → missing env var → Dockerfile alpine.
+    Pipeline: install(hard) → env_check → docker_build(strict).
+    """
+    missing_pkg = rng.choice(all_packages)
+    present_pkgs = [p for p in all_packages if p != missing_pkg]
+    missing_var = rng.choice(REQUIRED_ENV_VARS)
+    present_vars = {v: "placeholder" for v in REQUIRED_ENV_VARS if v != missing_var}
+    env_ci_content = "".join(f"{k}={v}\n" for k, v in sorted(present_vars.items()))
+
+    return {
+        "filesystem": {
+            "requirements.txt": "\n".join(present_pkgs) + "\n",
+            ".env.ci": env_ci_content,
+            "Dockerfile": (
+                "FROM python:3.11-alpine\n"
+                "WORKDIR /app\n"
+                "COPY requirements.txt .\n"
+                "RUN pip install -r requirements.txt\n"
+                "COPY . .\n"
+                'CMD ["python", "app.py"]\n'
+            ),
+            "pipeline.yaml": "stages:\n  - install\n  - env_check\n  - docker_build\n",
+            "app.py": "import flask\n# app code here\n",
+            "logs/install.log": "",
+        },
+        "answer_key": {
+            "fixes": {
+                "requirements.txt": missing_pkg,
+                ".env.ci": missing_var,
+                "Dockerfile": "python:3.11-slim",
+            },
+        },
+    }
+
+
+def generate_hard_scenario(seed: int) -> dict:
+    """
+    Randomly selects one of four structurally distinct hard scenario types,
+    then generates the specifics from the same seed. Each variant is a
+    three-fix cascading failure — each pipeline run stops at the first
+    failing stage, so bugs surface one at a time as the agent fixes them.
+    Same seed → same scenario every time.
+    """
+    rng = random.Random(seed)
+    all_packages = get_packages("hard")
+    scenario_type = rng.choice(["A", "B", "C", "D"])
+
+    if scenario_type == "A":
+        return _hard_type_a(rng, all_packages)
+    elif scenario_type == "B":
+        return _hard_type_b(rng, all_packages)
+    elif scenario_type == "C":
+        return _hard_type_c(rng, all_packages)
+    else:
+        return _hard_type_d(rng, all_packages)

core/utils/packages.py

@@ -0,0 +1,23 @@
+"""
+Single source of truth for required packages across all task difficulties.
+
+Add new entries here when implementing medium and hard scenarios.
+"""
+
+PACKAGES: dict[str, list[str]] = {
+    "easy": ["flask", "numpy", "pandas", "requests", "pydantic"],
+    "medium": ["flask", "numpy", "pandas", "requests", "pydantic"],  # install always passes; failures are in Dockerfile + .env.ci
+    "hard": ["flask", "numpy", "pandas", "requests", "pydantic"],  # install failure is from a numpy version conflict, not a missing package
+}
+
+
+def get_packages(task: str) -> list[str]:
+    """Return the required package list for a given task difficulty."""
+    if task not in PACKAGES:
+        raise ValueError(f"Unknown task: {task!r}. Valid tasks: {list(PACKAGES)}")
+    return PACKAGES[task]
+
+
+def get_packages_set(task: str) -> set[str]:
+    """Return required packages as a set (used for O(1) lookup in stage_runner)."""
+    return set(get_packages(task))

core/validation/parser.py

@@ -0,0 +1,64 @@
+"""
+Free-form command parser for the CI/CD Doctor environment.
+Converts raw command strings into structured ParsedCommand objects.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ParsedCommand:
+    type: str  # "cat" | "echo_append" | "sed" | "pipeline_run" | "pipeline_logs" | "pipeline_status" | "unknown"
+    filename: Optional[str] = None
+    content: Optional[str] = None    # for echo >>
+    pattern: Optional[str] = None    # for sed: old value
+    replacement: Optional[str] = None  # for sed: new value
+    stage: Optional[str] = None
+
+
+def parse_command(command: str) -> ParsedCommand:
+    command = command.strip()
+
+    for sep in ["&&", ";"]:
+        if sep in command:
+            command = command.split(sep)[0].strip()
+            break
+
+    m = re.match(r"cat\s+(.+)", command)
+    if m:
+        return ParsedCommand(type="cat", filename=m.group(1).strip())
+
+    m = re.match(r'echo\s+([\'"])(.*?)\1\s*>>\s*(\S+)', command, re.DOTALL)
+    if m:
+        return ParsedCommand(
+            type="echo_append",
+            content=m.group(2),
+            filename=m.group(3),
+        )
+
+    # Example supported: sed -i 's/old/new/g' file OR sed -i "s|old|new|" file
+    m = re.match(
+        r"sed\s+-i\s+([\'\"]?)s(.)(.+?)\2(.*?)\2([g]*)\1\s+(\S+)",
+        command,
+    )
+    if m:
+        return ParsedCommand(
+            type="sed",
+            pattern=m.group(3),
+            replacement=m.group(4),
+            filename=m.group(6),
+        )
+
+    if re.fullmatch(r"pipeline\s+run", command):
+        return ParsedCommand(type="pipeline_run")
+
+    m = re.match(r"pipeline\s+logs(?:\s+(\S+))?\s*$", command)
+    if m:
+        return ParsedCommand(type="pipeline_logs", stage=m.group(1))
+
+    if re.fullmatch(r"pipeline\s+status", command):
+        return ParsedCommand(type="pipeline_status")
+
+    return ParsedCommand(type="unknown")

core/validation/validator.py

@@ -0,0 +1,43 @@
+import re
+
+def parse_stages(content: str) -> list:
+    # Try inline format: stages: a, b, c
+    match = re.search(r"^stages:\s*(.+)$", content, re.MULTILINE)
+    if match and "," in match.group(1) and "\n" not in match.group(1):
+        return [s.strip() for s in match.group(1).split(",")]
+
+    lines = content.splitlines()
+    stages = []
+    in_stages_block = False
+
+    for line in lines:
+        if line.strip().startswith("stages:"):
+            in_stages_block = True
+            continue
+
+        if in_stages_block:
+            if line.strip().startswith("-"):
+                stages.append(line.strip().lstrip("- ").strip())
+            elif line.strip() == "":
+                continue
+            else:
+                break
+
+    return stages
+
+def validate_ci_stages(ci_content: str):
+    stages = parse_stages(ci_content)
+
+    if not stages:
+        raise ValueError("ci.yml has no valid stages defined.")
+
+    if "install" not in stages or "test" not in stages:
+        raise ValueError("ci.yml must define both 'install' and 'test' stages.")
+
+    # Only check 'build' if it exists
+    if "build" in stages:
+        if stages.index("test") < stages.index("install") or stages.index("test") < stages.index("build"):
+            raise ValueError("ci.yml stage ordering is invalid.")
+    else:
+        if stages.index("test") < stages.index("install"):
+            raise ValueError("ci.yml stage ordering is invalid.")

models.py

@@ -3,7 +3,7 @@ Data models for the CI/CD Doctor RL environment.
 """
 
 from pydantic import BaseModel, Field
-from typing import Optional, Dict, Any, List
+from typing import Dict, Any, List
 
 
 class PipelineAction(BaseModel):

openenv.yaml

@@ -12,7 +12,7 @@ tasks:
     description: "Single-file failure: one required package is missing from requirements.txt. Inspect the install logs, identify the missing package, and add it."
     grader:
       type: programmatic
-      module: core.grader:grade
+      module: core.grading.grader:grade
       success_threshold: 0.70
       prompt_template: |
         Score the agent's CI/CD debugging session from 0.01 to 0.99
@@ -27,7 +27,7 @@ tasks:
     description: "Two-file cascading failure (one of four randomized variants). Each variant pairs two bugs across files such as Dockerfile (wrong Python version or port), .env.ci (missing required env var), requirements.txt (missing package), deploy_config.yml (deploy_enabled false), Makefile (wrong test command), or service.yaml (wrong port). Bugs surface one at a time across the pipeline stages — fix both to make it pass."
     grader:
       type: programmatic
-      module: core.grader:grade
+      module: core.grading.grader:grade
       success_threshold: 0.60
       prompt_template: |
         Score the agent's CI/CD debugging session from 0.01 to 0.99
@@ -45,7 +45,7 @@ tasks:
     description: "Three-file cascading failure (one of four randomized variants). Each variant chains three bugs across files such as ci.yml (wrong stage order), Dockerfile (alpine base incompatible with binary wheels), requirements.txt (missing package or wrong version pin like numpy==1.21), .env.ci (missing env var), Makefile (wrong test command), deploy_config.yml (deploy_enabled false), or service.yaml (wrong port). Each pipeline run stops at the first failing stage, so bugs reveal themselves one at a time — fix all three in sequence."
     grader:
       type: programmatic
-      module: core.grader:grade
+      module: core.grading.grader:grade
       success_threshold: 0.45
       prompt_template: |
         Score the agent's CI/CD debugging session from 0.01 to 0.99

openenv_CI_CD_Doctor.egg-info/SOURCES.txt

@@ -1,16 +1,19 @@
 LICENSE
 README.md
+__init__.py
+inference.py
 pyproject.toml
 ./__init__.py
+./client.py
 ./inference.py
-environment/__init__.py
-environment/client.py
-environment/generator.py
-environment/grader.py
-environment/models.py
-environment/packages.py
-environment/parser.py
-environment/stage_runner.py
+./models.py
+core/__init__.py
+core/generator.py
+core/grader.py
+core/packages.py
+core/parser.py
+core/stage_runner.py
+core/validator.py
 openenv_CI_CD_Doctor.egg-info/PKG-INFO
 openenv_CI_CD_Doctor.egg-info/SOURCES.txt
 openenv_CI_CD_Doctor.egg-info/dependency_links.txt
@@ -19,4 +22,5 @@ openenv_CI_CD_Doctor.egg-info/requires.txt
 openenv_CI_CD_Doctor.egg-info/top_level.txt
 server/__init__.py
 server/app.py
+server/app_2.py
 server/environment.py

server/environment.py

@@ -6,10 +6,10 @@ Ties together generator, stage_runner, and parser into a step/reset/state loop.
 import uuid
 
 from models import PipelineAction, PipelineObservation, PipelineState
-from core.generator import generate_easy_scenario, generate_medium_scenario, generate_hard_scenario
-from core.stage_runner import run_pipeline
-from core.parser import parse_command
-from core.grader import grade as grade_state, balance_score, StepContext
+from core.scenarios.generator import generate_easy_scenario, generate_medium_scenario, generate_hard_scenario
+from core.pipeline.stage_runner import run_pipeline
+from core.validation.parser import parse_command
+from core.grading.grader import grade as grade_state, balance_score, StepContext
 
 MAX_STEPS_BY_TASK = {"easy": 10, "medium": 15, "hard": 25}
 IDEAL_STEPS_BY_TASK = {"easy": 3, "medium": 6, "hard": 10}