Initial commit for CodeForge GRPO training

Dockerfile

@@ -0,0 +1,25 @@
+FROM pytorch/pytorch:2.5.1-cuda12.4-cudnn9-devel
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+# Upgrade pip and install unsloth properly
+RUN pip install --no-cache-dir --upgrade pip
+RUN pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Copy all the code
+COPY --chown=user . /app
+
+# Ensure correct permissions for checkpoint saving
+USER root
+RUN chown -R user:user /app
+USER user
+
+# Hugging Face spaces expect the app to run on 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

app.py

@@ -0,0 +1,60 @@
+from fastapi import FastAPI, BackgroundTasks
+import subprocess
+import threading
+import os
+from fastapi.responses import PlainTextResponse
+
+app = FastAPI()
+
+# Global state to track training
+training_status = {
+    "status": "idle",
+    "log": ""
+}
+
+def run_training():
+    global training_status
+    training_status["status"] = "running"
+    training_status["log"] = "Started training...\n"
+    
+    # Run the trainer script and capture output
+    process = subprocess.Popen(
+        ["python", "-m", "trainer.train", "--steps", "300"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+        universal_newlines=True
+    )
+    
+    for line in process.stdout:
+        training_status["log"] += line
+        
+    process.wait()
+    training_status["status"] = f"finished with code {process.returncode}"
+    training_status["log"] += f"\nTraining finished with exit code: {process.returncode}\n"
+
+@app.get("/")
+def read_root():
+    return {
+        "message": "CodeForge GRPO Training Node Active",
+        "status": training_status["status"],
+        "endpoints": {
+            "/start": "Start training (runs in background)",
+            "/logs": "View live training logs"
+        }
+    }
+
+@app.post("/start")
+def start_training(background_tasks: BackgroundTasks):
+    if training_status["status"] == "running":
+        return {"message": "Training is already running!"}
+        
+    # Run in a separate thread so it doesn't block the API
+    thread = threading.Thread(target=run_training)
+    thread.start()
+    return {"message": "Training started! Go to /logs to monitor."}
+
+@app.get("/logs", response_class=PlainTextResponse)
+def get_logs():
+    return training_status["log"]

codeforge/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

codeforge/app.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import logging
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+import shutil
+import threading
+import time
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from fastapi import FastAPI, Response
+from openenv.core.env_server.http_server import create_app
+
+from codeforge.environment import CodeForgeEnvironment
+from codeforge.models import CodeForgeAction, CodeForgeObservation
+from codeforge.tasks import TASKS
+
+_log = logging.getLogger(__name__)
+
+_corpus_path_str = os.environ.get("GROUNDLOOP_CORPUS_PATH")
+_corpus_path = Path(_corpus_path_str) if _corpus_path_str else None
+
+# ---------------------------------------------------------------------------
+# Session-keyed environment pool (SYSTEM_DESIGN §15)
+# ---------------------------------------------------------------------------
+_lock = threading.Lock()
+_sessions: dict[str, CodeForgeEnvironment] = {}
+_session_access: dict[str, float] = {}  # session_id → last access timestamp
+_MAX_SESSIONS = int(os.environ.get("CODEFORGE_MAX_SESSIONS", "10"))
+_SESSION_TTL_S = int(os.environ.get("CODEFORGE_SESSION_TTL", "3600"))
+
+
+def _get_or_create_env() -> CodeForgeEnvironment:
+    """For OpenEnv compliance — creates a single-session env.
+
+    The session pool below is used by the MCP server layer.
+    """
+    return CodeForgeEnvironment(corpus_path=_corpus_path)
+
+
+def _expire_stale_sessions() -> None:
+    """Remove sessions older than TTL. Must hold _lock."""
+    now = time.monotonic()
+    expired = [
+        sid for sid, ts in _session_access.items()
+        if now - ts > _SESSION_TTL_S
+    ]
+    for sid in expired:
+        _sessions.pop(sid, None)
+        _session_access.pop(sid, None)
+
+
+def get_session(session_id: str) -> CodeForgeEnvironment | None:
+    """Retrieve an existing session by ID. Returns None if expired or missing."""
+    with _lock:
+        _expire_stale_sessions()
+        env = _sessions.get(session_id)
+        if env is not None:
+            _session_access[session_id] = time.monotonic()
+        return env
+
+
+def create_session() -> tuple[str, CodeForgeEnvironment]:
+    """Create a new session. Evicts LRU session if at capacity."""
+    sid = uuid4().hex[:16]
+    env = CodeForgeEnvironment(corpus_path=_corpus_path)
+    now = time.monotonic()
+    with _lock:
+        _expire_stale_sessions()
+        if len(_sessions) >= _MAX_SESSIONS:
+            # Evict least-recently-used session
+            lru_sid = min(_session_access, key=_session_access.get)  # type: ignore[arg-type]
+            _sessions.pop(lru_sid, None)
+            _session_access.pop(lru_sid, None)
+        _sessions[sid] = env
+        _session_access[sid] = now
+    return sid, env
+
+
+# ---------------------------------------------------------------------------
+# OpenEnv compliance app
+# ---------------------------------------------------------------------------
+app: FastAPI = create_app(_get_or_create_env, CodeForgeAction, CodeForgeObservation)
+
+
+@app.get("/", summary="Health check")
+def root() -> dict[str, str]:
+    return {"name": "code-forge", "version": "0.2.0", "status": "ok", "docs": "/docs"}
+
+
+@app.get("/favicon.ico", include_in_schema=False)
+def favicon() -> Response:
+    return Response(status_code=204)
+
+
+@app.get("/tasks", summary="List tasks + action schema")
+def list_tasks() -> dict[str, Any]:
+    return {
+        "tasks": [
+            {
+                "id": t.task_id,
+                "difficulty": t.task_level,
+                "brief": t.brief,
+                "target_score": t.target_score,
+                "max_budget": t.max_budget,
+                "tools": list(t.tools),
+            }
+            for t in TASKS
+        ],
+        "action_schema": {
+            "action_types": [
+                "query_kb",
+                "query_cluster",
+                "interrogate",
+                "run_ralph",
+                "submit",
+                "get_audit",
+            ],
+        },
+    }
+
+
+@app.get("/health/deep", summary="Deep health check")
+def health_check() -> dict[str, Any]:
+    """Check all dependencies: corpus file, tools."""
+    checks: dict[str, bool] = {
+        "ruff": shutil.which("ruff") is not None,
+        "mypy": shutil.which("mypy") is not None,
+        "pytest": shutil.which("pytest") is not None,
+    }
+    corpus_ok = _corpus_path is not None and Path(_corpus_path).is_file()
+    checks["corpus"] = corpus_ok
+    all_ok = all(checks.values())
+    return {"status": "ok" if all_ok else "degraded", "checks": checks}

codeforge/audit/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from codeforge.audit.ledger import AuditLedger
+from codeforge.audit.models import AuditReport
+from codeforge.audit.reporter import AuditReporter
+
+__all__ = ["AuditLedger", "AuditReport", "AuditReporter"]

codeforge/audit/ledger.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import asdict
+
+from codeforge.models import AuditEntry
+
+
+class AuditLedger:
+    """Per-episode, per-step append-only audit log."""
+
+    def __init__(self) -> None:
+        self._entries: list[AuditEntry] = []
+
+    def append(self, entry: AuditEntry) -> None:
+        self._entries.append(entry)
+
+    def entries(self) -> tuple[AuditEntry, ...]:
+        return tuple(self._entries)
+
+    def total_reward(self) -> float:
+        return sum(e.reward for e in self._entries)
+
+    def citation_count(self) -> dict[str, int]:
+        counts: Counter[str] = Counter()
+        for entry in self._entries:
+            counts.update(entry.cited_skill_ids)
+        return dict(counts)
+
+    def step_count(self) -> int:
+        return len(self._entries)
+
+    def serialize(self) -> dict[str, object]:
+        return {
+            "entries": [asdict(e) for e in self._entries],
+            "total_reward": self.total_reward(),
+            "step_count": self.step_count(),
+            "citation_count": self.citation_count(),
+        }

codeforge/audit/models.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AuditReport(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    run_id: str
+    summary: str
+    iterations_total: int
+    iterations_kept: int
+    iterations_regressed: int
+    iterations_plateau: int
+    skill_citations: tuple[tuple[str, int], ...]
+    score_trajectory: tuple[float, ...]
+    final_score: float
+    terminated_by: str
+    hallucination_rate: float

codeforge/audit/reporter.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import TYPE_CHECKING
+
+from codeforge.audit.models import AuditReport
+
+if TYPE_CHECKING:
+    from codeforge.ralph.models import RunResult
+
+
+class AuditReporter:
+    """Builds an AuditReport from a Ralph RunResult."""
+
+    @staticmethod
+    def build(run: RunResult, hallucination_rate: float = 0.0) -> AuditReport:
+        cites: Counter[str] = Counter()
+        kept = 0
+        regressed = 0
+        plateau = 0
+        trajectory: list[float] = []
+
+        for it in run.iterations:
+            cites.update(it.cited_node_ids)
+            trajectory.append(it.sandbox_score_after)
+            if it.reason == "score_improved":
+                kept += 1
+            elif it.reason == "score_regressed":
+                regressed += 1
+            elif it.reason == "score_plateau":
+                plateau += 1
+
+        summary = (
+            f"run={run.run_id} iters={len(run.iterations)} "
+            f"final={run.final_score:.3f} terminated_by={run.terminated_by}"
+        )
+        skill_citations = tuple(
+            sorted(cites.items(), key=lambda kv: (-kv[1], kv[0]))
+        )
+
+        return AuditReport(
+            run_id=run.run_id,
+            summary=summary,
+            iterations_total=len(run.iterations),
+            iterations_kept=kept,
+            iterations_regressed=regressed,
+            iterations_plateau=plateau,
+            skill_citations=skill_citations,
+            score_trajectory=tuple(trajectory),
+            final_score=run.final_score,
+            terminated_by=run.terminated_by,
+            hallucination_rate=hallucination_rate,
+        )

codeforge/environment.py

@@ -0,0 +1,515 @@
+from __future__ import annotations
+
+import logging
+import re
+import uuid
+from pathlib import Path
+from typing import Any
+
+from openenv.core.env_server.interfaces import Environment
+
+from codeforge.audit.ledger import AuditLedger
+from codeforge.grader import compute_reward
+from codeforge.grounder import ground
+from codeforge.interrogator.interrogator import Interrogator
+from codeforge.kb.cluster import build_clusters
+from codeforge.kb.indexer import SkillsIndex
+from codeforge.models import AuditEntry, CodeForgeAction, CodeForgeActionType, CodeForgeObservation
+from codeforge.observation import build_observation
+from codeforge.ralph.loop import run_loop
+from codeforge.ralph.models import LoopConfig
+from codeforge.ralph.synthesizer import StubSynthesizer, Synthesizer
+from codeforge.sandbox.sandbox import run_sandbox
+from codeforge.shaping import citation_shaping_bonus
+from codeforge.tasks import Task, get_task
+
+_log = logging.getLogger(__name__)
+_DEFAULT_CORPUS = Path(__file__).resolve().parent / "kb" / "skills_corpus.jsonl"
+
+# ---------------------------------------------------------------------------
+# Filename validation (SYSTEM_DESIGN §14.2, §14.3)
+# ---------------------------------------------------------------------------
+_FILENAME_RE = re.compile(r"^[a-z][a-z0-9_]*\.py$")
+_FORBIDDEN_FILENAMES = frozenset({
+    "conftest.py", "pytest.ini", "setup.cfg", "pyproject.toml", "tox.ini",
+})
+_MAX_FILES = 10
+_MAX_FILE_SIZE = 50 * 1024  # 50 KB
+_MAX_TOTAL_SIZE = 200 * 1024  # 200 KB
+
+
+def _validate_files(files: dict[str, str]) -> str | None:
+    """Return an error message if *files* violates submission constraints, else None."""
+    if not files:
+        return "files dict is empty"
+    if len(files) > _MAX_FILES:
+        return f"too many files ({len(files)} > {_MAX_FILES})"
+    total_size = 0
+    for name, content in files.items():
+        if name in _FORBIDDEN_FILENAMES:
+            return f"filename '{name}' is not allowed"
+        if not _FILENAME_RE.match(name):
+            return f"filename '{name}' must match [a-z][a-z0-9_]*.py"
+        size = len(content.encode("utf-8"))
+        if size > _MAX_FILE_SIZE:
+            return f"file '{name}' exceeds {_MAX_FILE_SIZE} bytes"
+        total_size += size
+    if total_size > _MAX_TOTAL_SIZE:
+        return f"total size ({total_size}) exceeds {_MAX_TOTAL_SIZE} bytes"
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Valid action types (for fast membership check)
+# ---------------------------------------------------------------------------
+_VALID_ACTION_TYPES = frozenset(member.value for member in CodeForgeActionType)
+
+
+# ---------------------------------------------------------------------------
+# Environment
+# ---------------------------------------------------------------------------
+
+
+class CodeForgeEnvironment(Environment):  # type: ignore[type-arg]
+    """OpenEnv-compliant RL environment with all 6 CodeForge actions.
+
+    Implements SYSTEM_DESIGN §4.9, §5.2, §17.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(
+        self,
+        *,
+        corpus_path: Path | None = None,
+        synthesizer: Synthesizer | None = None,
+    ) -> None:
+        super().__init__()
+        self._corpus_path = corpus_path or _DEFAULT_CORPUS
+        self._synthesizer = synthesizer
+        self._index: SkillsIndex | None = None
+        self._task: Task | None = None
+        self._episode_id: str = ""
+        self._budget_remaining: int = 0
+        self._current_files: dict[str, str] = {}
+        self._previous_score: float = 0.0
+        self._is_done: bool = False
+
+        # Per-step state
+        self._last_citations: tuple[dict[str, object], ...] = ()
+        self._last_grounding: dict[str, object] | None = None
+        self._last_reward: float = 0.0
+        self._last_cluster_hits: tuple[str, ...] = ()
+        self._last_interrogation_questions: tuple[str, ...] = ()
+        self._last_ralph_run_id: str | None = None
+        self._last_ralph_iterations: tuple[dict[str, object], ...] = ()
+
+        # Brier/quality tracking for audit entries
+        self._last_brier_penalty: float | None = None
+        self._last_quality: float = 0.0
+
+        # Episode-level accumulators
+        self._all_episode_citations: list[dict[str, object]] = []
+        self._all_episode_cluster_hits: list[str] = []
+        self._ledger: AuditLedger | None = None
+        self._step_index: int = 0
+
+    # ------------------------------------------------------------------
+    # Index management
+    # ------------------------------------------------------------------
+
+    def _ensure_index(self) -> SkillsIndex:
+        if self._index is None:
+            if not self._corpus_path.is_file():
+                msg = (
+                    f"corpus not found: {self._corpus_path}. "
+                    f"Run the skills scraper first."
+                )
+                raise FileNotFoundError(msg)
+            idx = SkillsIndex(corpus_path=self._corpus_path)
+            idx.build()
+            # Build and attach clusters
+            import json
+            nodes: list[dict[str, Any]] = []
+            with self._corpus_path.open(encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        nodes.append(json.loads(line))
+            manifest = build_clusters(nodes)
+            idx.attach_cluster_manifest(manifest)
+            self._index = idx
+        return self._index
+
+    # ------------------------------------------------------------------
+    # OpenEnv interface
+    # ------------------------------------------------------------------
+
+    def reset(
+        self,
+        seed: int | None = None,
+        episode_id: str | None = None,
+        **kwargs: Any,
+    ) -> CodeForgeObservation:
+        task_level: str = kwargs.get("task_level", "easy")
+        task = get_task(task_level)
+        self._task = task
+        self._episode_id = episode_id or uuid.uuid4().hex[:12]
+        self._budget_remaining = task.max_budget
+        self._current_files = dict(task.initial_files)
+        self._previous_score = 0.0
+        self._is_done = False
+
+        # Reset per-step
+        self._last_citations = ()
+        self._last_grounding = None
+        self._last_reward = 0.0
+        self._last_cluster_hits = ()
+        self._last_interrogation_questions = ()
+        self._last_ralph_run_id = None
+        self._last_ralph_iterations = ()
+
+        # Reset episode accumulators
+        self._all_episode_citations = []
+        self._all_episode_cluster_hits = []
+        self._ledger = AuditLedger()
+        self._step_index = 0
+
+        _log.info(
+            "reset id=%s task=%s budget=%s",
+            self._episode_id, task.task_id, task.max_budget,
+        )
+        return self._build_obs()
+
+    def step(
+        self,
+        action: CodeForgeAction,
+        timeout_s: float | None = None,
+        **kwargs: Any,
+    ) -> CodeForgeObservation:
+        # --- Pre-check: no active episode --------------------------------
+        if self._task is None:
+            return self._error_obs("No active episode — call reset() first")
+
+        # --- Pre-check: episode already done -----------------------------
+        if self._is_done:
+            return self._build_obs()
+
+        # --- Pre-check: valid action_type --------------------------------
+        action_type_str = str(action.action_type)
+        if action_type_str not in _VALID_ACTION_TYPES:
+            return self._error_obs(f"Unknown action_type: {action_type_str!r}")
+
+        # --- Budget check (variable cost) --------------------------------
+        cost = self._action_cost(action)
+        if cost > self._budget_remaining:
+            return self._error_obs(
+                f"Insufficient budget: need {cost}, have {self._budget_remaining}"
+            )
+        self._budget_remaining -= cost
+
+        # --- Clear per-step state ----------------------------------------
+        self._last_reward = 0.0
+        self._last_citations = ()
+        self._last_grounding = None
+        self._last_cluster_hits = ()
+        self._last_interrogation_questions = ()
+        self._last_ralph_run_id = None
+        self._last_ralph_iterations = ()
+        error: str | None = None
+
+        # --- Route to handler --------------------------------------------
+        try:
+            if action_type_str == CodeForgeActionType.QUERY_KB:
+                error = self._handle_query_kb(action)
+            elif action_type_str == CodeForgeActionType.QUERY_CLUSTER:
+                error = self._handle_query_cluster(action)
+            elif action_type_str == CodeForgeActionType.INTERROGATE:
+                error = self._handle_interrogate(action)
+            elif action_type_str == CodeForgeActionType.SUBMIT:
+                error = self._handle_submit(action)
+            elif action_type_str == CodeForgeActionType.RUN_RALPH:
+                error = self._handle_run_ralph(action)
+            elif action_type_str == CodeForgeActionType.GET_AUDIT:
+                error = self._handle_get_audit(action)
+        except Exception as exc:
+            _log.exception("handler error: %s", exc)
+            error = f"Internal error: {exc}"
+
+        # --- Append audit entry ------------------------------------------
+        assert self._ledger is not None
+        _cited: list[str] = []
+        _cite: dict[str, object]
+        for _cite in self._last_citations:
+            _cited.append(str(_cite.get("node_id", "")))
+        cited_ids: tuple[str, ...] = tuple(_cited)
+        self._ledger.append(
+            AuditEntry(
+                step_index=self._step_index,
+                action_type=action_type_str,
+                cited_skill_ids=cited_ids,
+                cited_clusters=self._last_cluster_hits,
+                grounding_report=(
+                    self._last_grounding if self._last_grounding else None
+                ),
+                reward=self._last_reward,
+                brier_penalty=(
+                    self._last_brier_penalty
+                    if action_type_str == CodeForgeActionType.SUBMIT
+                    else None
+                ),
+                confidence_declared=(
+                    action.confidence
+                    if action_type_str == CodeForgeActionType.SUBMIT
+                    else None
+                ),
+                quality=(
+                    self._last_quality
+                    if action_type_str == CodeForgeActionType.SUBMIT
+                    else self._previous_score
+                ),
+            ),
+        )
+        self._step_index += 1
+
+        # --- Check budget exhaustion -------------------------------------
+        if self._budget_remaining <= 0:
+            self._is_done = True
+
+        return self._build_obs(error=error)
+
+    @property
+    def state(self) -> CodeForgeObservation:
+        if self._task is None:
+            return self._error_obs("No active episode — call reset() first")
+        return self._build_obs()
+
+    # ------------------------------------------------------------------
+    # Cost computation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _action_cost(action: CodeForgeAction) -> int:
+        """Variable-cost budget accounting (SYSTEM_DESIGN §17.2)."""
+        if str(action.action_type) == CodeForgeActionType.GET_AUDIT:
+            return 0
+        if str(action.action_type) == CodeForgeActionType.RUN_RALPH:
+            return action.max_iters
+        return 1
+
+    # ------------------------------------------------------------------
+    # Action handlers (each returns an error string or None)
+    # ------------------------------------------------------------------
+
+    def _handle_query_kb(self, action: CodeForgeAction) -> str | None:
+        try:
+            idx = self._ensure_index()
+        except FileNotFoundError as e:
+            _log.warning("query_kb: no corpus: %s", e)
+            self._last_citations = ()
+            return None
+        tags = set(action.required_tags) if action.required_tags else None
+        results = idx.search(
+            action.claim or "", top_k=action.top_k, required_tags=tags,
+        )
+        self._last_citations = tuple(
+            {
+                "node_id": r.node_id,
+                "skill_name": r.skill_name,
+                "section_path": list(r.section_path),
+                "section_body": r.section_body,
+                "score": r.score,
+                "rank": r.rank,
+            }
+            for r in results
+        )
+        self._all_episode_citations.extend(self._last_citations)
+        return None
+
+    def _handle_query_cluster(self, action: CodeForgeAction) -> str | None:
+        try:
+            idx = self._ensure_index()
+        except FileNotFoundError as e:
+            _log.warning("query_cluster: no corpus: %s", e)
+            self._last_cluster_hits = ()
+            return None
+        label = action.cluster_label or ""
+        results = idx.nodes_in_cluster(label)
+        if not results:
+            self._last_cluster_hits = ()
+            return None
+        self._last_cluster_hits = tuple(r.node_id for r in results)
+        self._all_episode_cluster_hits.extend(self._last_cluster_hits)
+        return None
+
+    def _handle_interrogate(self, action: CodeForgeAction) -> str | None:
+        idx: SkillsIndex | None
+        try:
+            idx = self._ensure_index()
+        except FileNotFoundError:
+            idx = None
+        interrogator = Interrogator(idx)
+        assert self._task is not None
+        result = interrogator.generate(self._task.brief)
+        self._last_interrogation_questions = result.questions
+        return None
+
+    def _handle_submit(self, action: CodeForgeAction) -> str | None:
+        if action.files is None:
+            return "files required for submit"
+        file_err = _validate_files(action.files)
+        if file_err is not None:
+            return file_err
+
+        self._current_files = dict(action.files)
+        assert self._task is not None
+
+        # Merge hidden correctness tests into sandbox files (agent cannot see these)
+        sandbox_files = dict(action.files)
+        if self._task.hidden_tests:
+            sandbox_files.update(self._task.hidden_tests)
+
+        # Run sandbox
+        try:
+            sandbox_result = run_sandbox(
+                files=sandbox_files,
+                tools=self._task.tools,
+                timeout_per_tool=30.0,
+            )
+            sandbox_score = sandbox_result.composite_score
+        except Exception as e:
+            _log.exception("sandbox error: %s", e)
+            sandbox_score = 0.0
+
+        # Run grounder (pass local module names so they're not penalized)
+        local_modules = frozenset(
+            f.removesuffix(".py") for f in action.files if f.endswith(".py")
+        )
+        concatenated = "\n".join(action.files.values())
+        grounding_report = ground(concatenated, local_modules=local_modules)
+        self._last_grounding = grounding_report.model_dump()
+
+        # Compute reward with Brier calibration
+        quality = 0.6 * sandbox_score + 0.4 * grounding_report.groundedness
+        effective_conf = action.confidence if action.confidence is not None else 0.5
+        brier_penalty: float | None = min((effective_conf - quality) ** 2, 0.5)
+        self._last_brier_penalty = brier_penalty
+        self._last_quality = quality
+
+        reward = compute_reward(
+            sandbox_score=sandbox_score,
+            groundedness=grounding_report.groundedness,
+            confidence=action.confidence,
+        )
+
+        # Apply citation shaping bonus only on successful submits (§4.8.4)
+        if reward > 0:
+            shaping = citation_shaping_bonus(
+                submit_files=action.files,
+                prior_citations=self._all_episode_citations,
+                prior_cluster_hits=self._all_episode_cluster_hits,
+            )
+            reward = round(min(1.0, reward + shaping), 3)
+
+        self._last_reward = reward
+        self._previous_score = reward
+
+        # Check target score
+        if reward >= self._task.target_score:
+            self._is_done = True
+
+        return None
+
+    def _handle_run_ralph(self, action: CodeForgeAction) -> str | None:
+        assert self._task is not None
+        try:
+            idx = self._ensure_index()
+        except FileNotFoundError as e:
+            return f"corpus not available: {e}"
+
+        config = LoopConfig(
+            max_iters=action.max_iters,
+            target_score=self._task.target_score,
+            tools=self._task.tools,
+        )
+        synthesizer = self._synthesizer or StubSynthesizer()
+        result = run_loop(
+            spec=self._task.brief,
+            initial_files=self._current_files,
+            index=idx,
+            synthesizer=synthesizer,
+            config=config,
+        )
+
+        self._last_ralph_run_id = result.run_id
+        self._last_ralph_iterations = tuple(
+            it.model_dump() for it in result.iterations
+        )
+        self._current_files = dict(result.final_files)
+
+        # Compute ralph reward (SYSTEM_DESIGN §4.8.5)
+        concatenated = "\n".join(result.final_files.values())
+        grounding_report = ground(concatenated)
+        self._last_grounding = grounding_report.model_dump()
+
+        wasted = sum(
+            1 for it in result.iterations if it.reason in ("score_regressed", "score_plateau")
+        )
+        base = compute_reward(
+            sandbox_score=result.final_score,
+            groundedness=grounding_report.groundedness,
+            confidence=0.75,
+        )
+        waste_penalty = wasted * 0.05
+        ralph_reward = round(max(0.0, min(1.0, base - waste_penalty)), 3)
+
+        self._last_reward = ralph_reward
+        self._previous_score = ralph_reward
+        return None
+
+    def _handle_get_audit(self, action: CodeForgeAction) -> str | None:
+        # Audit data is populated in _build_obs via cumulative_audit_summary
+        return None
+
+    # ------------------------------------------------------------------
+    # Observation helpers
+    # ------------------------------------------------------------------
+
+    def _build_obs(self, *, error: str | None = None) -> CodeForgeObservation:
+        assert self._task is not None
+        audit_summary: dict[str, object] | None = None
+        if self._ledger is not None:
+            audit_summary = self._ledger.serialize()
+        return build_observation(
+            episode_id=self._episode_id,
+            task=self._task,
+            current_files=self._current_files,
+            budget_remaining=self._budget_remaining,
+            previous_score=self._previous_score,
+            last_citations=self._last_citations,
+            last_grounding=self._last_grounding,
+            is_done=self._is_done,
+            last_reward=self._last_reward,
+            last_cluster_hits=self._last_cluster_hits,
+            last_interrogation_questions=self._last_interrogation_questions,
+            last_ralph_run_id=self._last_ralph_run_id,
+            last_ralph_iterations=self._last_ralph_iterations,
+            cumulative_audit_summary=audit_summary,
+            error=error,
+        )
+
+    def _error_obs(self, msg: str) -> CodeForgeObservation:
+        """Return an error observation without modifying episode state."""
+        if self._task is None:
+            # No task set — use a dummy task for the observation structure
+            dummy = get_task("easy")
+            return build_observation(
+                episode_id=self._episode_id or "none",
+                task=dummy,
+                current_files=self._current_files,
+                budget_remaining=self._budget_remaining,
+                previous_score=self._previous_score,
+                is_done=self._is_done,
+                error=msg,
+            )
+        return self._build_obs(error=msg)

codeforge/grader.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+_SANDBOX_WEIGHT = 0.6
+_GROUNDING_WEIGHT = 0.4
+_BRIER_CAP = 0.5
+_UNCERTAIN_CONFIDENCE_THRESHOLD = 0.3
+_UNCERTAIN_QUALITY_THRESHOLD = 0.5
+_UNCERTAIN_FLOOR = 0.50
+
+
+def compute_reward(
+    *,
+    sandbox_score: float,
+    groundedness: float,
+    confidence: float | None = None,
+) -> float:
+    """Compute the final reward for a submit action.
+
+    quality   = weighted combination of sandbox and grounding signals
+    brier     = calibration penalty (overconfidence on bad code is punished)
+    uncertain = floor reward for honest uncertainty (below all task targets)
+    """
+    quality = _SANDBOX_WEIGHT * sandbox_score + _GROUNDING_WEIGHT * groundedness
+
+    # Brier calibration: confidence=None treated as 0.5 (mediocre calibration)
+    # so agents cannot bypass Brier entirely by omitting confidence.
+    effective_confidence = confidence if confidence is not None else 0.5
+    brier_penalty = min((effective_confidence - quality) ** 2, _BRIER_CAP)
+
+    reward = quality * (1.0 - brier_penalty)
+
+    if (
+        confidence is not None
+        and confidence < _UNCERTAIN_CONFIDENCE_THRESHOLD
+        and quality < _UNCERTAIN_QUALITY_THRESHOLD
+    ):
+        reward = max(reward, _UNCERTAIN_FLOOR)
+
+    return round(max(0.0, min(1.0, reward)), 3)

codeforge/grounder.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import ast
+import importlib
+import importlib.util
+import logging
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+_log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+
+class Symbol(BaseModel):
+    """A single symbol extracted from source code by AST walking."""
+
+    model_config = ConfigDict(frozen=True)
+    module: str
+    attr: str | None
+    kind: Literal["import", "attribute"]
+    resolved: bool
+    line: int
+
+
+class GroundingReport(BaseModel):
+    """Result of grounding analysis on source code."""
+
+    model_config = ConfigDict(frozen=True)
+    total_symbols: int
+    grounded: tuple[Symbol, ...]
+    ungrounded: tuple[Symbol, ...]
+    groundedness: float
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _module_spec(name: str) -> bool:
+    """Return True if the module can be found by the import system."""
+    try:
+        return importlib.util.find_spec(name) is not None
+    except (ImportError, ValueError, ModuleNotFoundError):
+        return False
+
+
+def _has_attr(module_name: str, attr: str) -> bool:
+    """Check if *module_name* exposes *attr*.
+
+    Uses the FULL module path (e.g. ``os.path``) — not just
+    the top-level package.  This is the fix for SYSTEM_DESIGN §4.8.3
+    bug #3.
+    """
+    try:
+        mod = importlib.import_module(module_name)
+    except Exception:
+        return False
+    return hasattr(mod, attr)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def ground(
+    source: str,
+    *,
+    local_modules: frozenset[str] = frozenset(),
+) -> GroundingReport:
+    """AST-parse *source*, check every import and attribute access resolves.
+
+    Three fixes baked in from day one (SYSTEM_DESIGN §4.8.3):
+    1. SyntaxError → groundedness=0.0  (was 1.0)
+    2. Zero symbols → groundedness=0.5 (was 1.0)
+    3. Attribute resolution against full module path (was top-level only)
+
+    *local_modules*: set of module names (e.g. ``{"core", "main"}``) that are
+    local to the agent's project and should be treated as grounded even though
+    ``importlib.util.find_spec`` cannot resolve them from the grader process.
+    """
+    # ----- parse --------------------------------------------------------
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        # FIX 1: unparseable code → 0.0, not 1.0
+        return GroundingReport(
+            total_symbols=0,
+            grounded=(),
+            ungrounded=(),
+            groundedness=0.0,
+        )
+
+    symbols: list[Symbol] = []
+    import_to_module: dict[str, str] = {}
+
+    # ----- walk imports -------------------------------------------------
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                pkg = alias.name.split(".")[0]
+                # Local modules are always treated as grounded
+                resolved = (
+                    pkg in local_modules or _module_spec(alias.name)
+                )
+                symbols.append(
+                    Symbol(
+                        module=alias.name,
+                        attr=None,
+                        kind="import",
+                        resolved=resolved,
+                        line=node.lineno,
+                    )
+                )
+                import_to_module[alias.asname or pkg] = alias.name
+
+        elif isinstance(node, ast.ImportFrom):
+            if node.level != 0 or node.module is None:
+                continue
+            mod_top = node.module.split(".")[0]
+            is_local = mod_top in local_modules
+            resolved_mod = is_local or _module_spec(node.module)
+            for alias in (node.names or []):
+                attr_resolved = resolved_mod if is_local else (
+                    resolved_mod and _has_attr(node.module, alias.name)
+                )
+                symbols.append(
+                    Symbol(
+                        module=node.module,
+                        attr=alias.name,
+                        kind="import",
+                        resolved=attr_resolved,
+                        line=node.lineno,
+                    )
+                )
+
+    # ----- walk attribute accesses --------------------------------------
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Attribute):
+            continue
+
+        # Resolve the chain: e.g. os.path.join → base="os", chain=["path"], attr="join"
+        chain: list[str] = []
+        cursor: ast.expr = node.value
+        while isinstance(cursor, ast.Attribute):
+            chain.append(cursor.attr)
+            cursor = cursor.value
+        if not isinstance(cursor, ast.Name):
+            continue
+
+        base = cursor.id
+        mod_name = import_to_module.get(base)
+        if mod_name is None:
+            continue
+
+        # Build the full module path for chained access:
+        # import os.path → import_to_module["os"] = "os.path"
+        # os.path.join → chain=["path"], we need to resolve "join" against "os.path"
+        # The chain intermediates are sub-module parts already covered by mod_name.
+        # We check the final attr against the deepest resolvable module.
+        if chain:
+            # chain was built bottom-up, reverse to get top-down order
+            chain.reverse()
+            # Build candidate module: mod_name + chain parts
+            full_mod = mod_name + "." + ".".join(chain)
+            # Try the full module first; fall back to mod_name if it doesn't exist
+            check_mod = full_mod if _module_spec(full_mod) else mod_name
+        else:
+            check_mod = mod_name
+
+        # FIX 3: resolve against full module path, not just top-level
+        resolved = _has_attr(check_mod, node.attr)
+        symbols.append(
+            Symbol(
+                module=check_mod,
+                attr=node.attr,
+                kind="attribute",
+                resolved=resolved,
+                line=node.lineno,
+            )
+        )
+
+    # ----- compute groundedness -----------------------------------------
+    grounded = tuple(s for s in symbols if s.resolved)
+    ungrounded = tuple(s for s in symbols if not s.resolved)
+    total = len(symbols)
+
+    # FIX 2: zero symbols → 0.5 (neutral), not 1.0
+    groundedness = 0.5 if total == 0 else len(grounded) / total
+
+    return GroundingReport(
+        total_symbols=total,
+        grounded=grounded,
+        ungrounded=ungrounded,
+        groundedness=groundedness,
+    )

codeforge/interrogator/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from codeforge.interrogator.interrogator import Interrogator
+from codeforge.interrogator.models import InterrogationResult
+
+__all__ = ["InterrogationResult", "Interrogator"]

codeforge/interrogator/interrogator.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from codeforge.interrogator.models import InterrogationResult
+
+if TYPE_CHECKING:
+    from codeforge.kb.indexer import SkillsIndex
+
+_TEMPLATES = (
+    "What is the exact success criterion for '{brief_head}'?",
+    "Have you considered the guidance from {skill_name}: '{section_title}'?",
+    "Which of these assumptions is most load-bearing: success metric, inputs, failure modes?",
+    "What is the single hardest edge case for '{brief_head}'?",
+    "Have you consulted {skill_name2} for the patterns it recommends?",
+)
+
+
+class Interrogator:
+    """Generates Socratic questions that cite real skill corpus nodes."""
+
+    def __init__(self, index: SkillsIndex | None) -> None:
+        self._index = index
+
+    def generate(self, brief: str, *, top_k: int = 5) -> InterrogationResult:
+        brief_head = brief.strip()[:80] or "the task"
+        results = (
+            self._index.search(brief, top_k=top_k)
+            if self._index is not None
+            else []
+        )
+        cited_ids = tuple(r.node_id for r in results[:2])
+        first = results[0] if results else None
+        second = results[1] if len(results) > 1 else first
+
+        skill_name = first.skill_name if first else "the skill library"
+        section_title = (
+            "/".join(first.section_path) if first else "the relevant section"
+        )
+        skill_name2 = second.skill_name if second else skill_name
+
+        questions = tuple(
+            t.format(
+                brief_head=brief_head,
+                skill_name=skill_name,
+                section_title=section_title,
+                skill_name2=skill_name2,
+            )
+            for t in _TEMPLATES
+        )
+        return InterrogationResult(questions=questions, cited_node_ids=cited_ids)

codeforge/interrogator/models.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class InterrogationResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    questions: tuple[str, ...]
+    cited_node_ids: tuple[str, ...]

codeforge/kb/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from codeforge.kb.cluster import build_clusters
+from codeforge.kb.indexer import SkillsIndex
+from codeforge.kb.models import (
+    Cluster,
+    ClusterManifest,
+    SearchResult,
+)
+
+__all__ = [
+    "Cluster",
+    "ClusterManifest",
+    "SearchResult",
+    "SkillsIndex",
+    "build_clusters",
+]

codeforge/kb/cluster.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import hashlib
+from collections import Counter
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from typing import Any
+
+from codeforge.kb.models import Cluster, ClusterManifest
+from codeforge.kb.tokenizer import tokenize
+
+_STOPWORDS: frozenset[str] = frozenset({
+    "the", "and", "for", "with", "this", "that", "are", "was",
+    "not", "but", "use", "can", "all", "one", "from", "when",
+    "which", "have", "any", "should", "would", "must", "will",
+    "your", "you", "our", "its", "their", "them", "they",
+})
+
+
+def _filter_tokens(tokens: list[str], min_length: int = 3) -> list[str]:
+    return [t for t in tokens if len(t) >= min_length and t not in _STOPWORDS]
+
+
+def _jaccard(a: set[str], b: set[str]) -> float:
+    if not a and not b:
+        return 0.0
+    union = a | b
+    inter = a & b
+    return len(inter) / len(union)
+
+
+def _connected_components(
+    node_ids: list[str], adj: dict[str, set[str]],
+) -> list[set[str]]:
+    seen: set[str] = set()
+    comps: list[set[str]] = []
+    for start in node_ids:
+        if start in seen:
+            continue
+        comp: set[str] = set()
+        stack = [start]
+        while stack:
+            nid = stack.pop()
+            if nid in comp:
+                continue
+            comp.add(nid)
+            seen.add(nid)
+            for nbr in adj.get(nid, ()):
+                if nbr not in comp:
+                    stack.append(nbr)
+        comps.append(comp)
+    return comps
+
+
+def _dominant_domain(tags_list: Iterable[tuple[str, ...]]) -> str:
+    counts: Counter[str] = Counter()
+    for tags in tags_list:
+        for t in tags:
+            if t.startswith("domain:"):
+                counts[t.split(":", 1)[1]] += 1
+    if not counts:
+        return "general"
+    return counts.most_common(1)[0][0]
+
+
+def _label_cluster(
+    nodes_data: list[dict[str, Any]],
+) -> tuple[str, tuple[str, ...], str]:
+    all_tokens: Counter[str] = Counter()
+    tag_lists: list[tuple[str, ...]] = []
+    for nd in nodes_data:
+        all_tokens.update(nd["tokens"])
+        tag_lists.append(tuple(nd.get("tags", ())))
+    top3 = [t for t, _ in all_tokens.most_common(3)]
+    dominant = _dominant_domain(tag_lists)
+    label = f"{dominant}_" + "_".join(top3) if top3 else dominant
+    return label, tuple(top3), dominant
+
+
+def build_clusters(
+    nodes: list[dict[str, Any]],
+    *,
+    jaccard_threshold: float = 0.15,
+    min_token_length: int = 3,
+    corpus_sha256: str = "",
+    generated_at: str | None = None,
+) -> ClusterManifest:
+    if not nodes:
+        stamp = (
+            generated_at
+            if generated_at is not None
+            else datetime.now(UTC).isoformat(timespec="seconds")
+        )
+        return ClusterManifest(
+            generated_at=stamp,
+            corpus_sha256=corpus_sha256,
+            jaccard_threshold=jaccard_threshold,
+            total_clusters=0,
+            total_nodes_clustered=0,
+            singletons=0,
+            clusters=(),
+        )
+
+    node_ids = [str(n["id"]) for n in nodes]
+    token_sets: dict[str, set[str]] = {
+        str(n["id"]): set(
+            _filter_tokens(
+                tokenize(str(n.get("section_body", ""))), min_token_length,
+            ),
+        )
+        for n in nodes
+    }
+    adj: dict[str, set[str]] = {nid: set() for nid in node_ids}
+    for i, a in enumerate(node_ids):
+        for b in node_ids[i + 1 :]:
+            sim = _jaccard(token_sets[a], token_sets[b])
+            if sim >= jaccard_threshold:
+                adj[a].add(b)
+                adj[b].add(a)
+
+    components = _connected_components(node_ids, adj)
+    node_by_id = {str(n["id"]): n for n in nodes}
+
+    clusters: list[Cluster] = []
+    singletons = 0
+    for comp in components:
+        member_ids = sorted(comp)
+        nodes_data = [
+            {
+                "tokens": _filter_tokens(
+                    tokenize(str(node_by_id[nid].get("section_body", ""))),
+                    min_token_length,
+                ),
+                "tags": tuple(node_by_id[nid].get("tags", ())),
+            }
+            for nid in member_ids
+        ]
+        label, top_tokens, dominant = _label_cluster(nodes_data)
+        cluster_id = hashlib.sha256(
+            "|".join(member_ids).encode(),
+        ).hexdigest()[:12]
+        if len(member_ids) == 1:
+            singletons += 1
+        clusters.append(
+            Cluster(
+                cluster_id=cluster_id,
+                label=label,
+                dominant_domain=dominant,
+                top_tokens=top_tokens,
+                node_count=len(member_ids),
+                member_node_ids=tuple(member_ids),
+            ),
+        )
+    clusters.sort(key=lambda c: (-c.node_count, c.cluster_id))
+
+    stamp = (
+        generated_at
+        if generated_at is not None
+        else datetime.now(UTC).isoformat(timespec="seconds")
+    )
+    return ClusterManifest(
+        generated_at=stamp,
+        corpus_sha256=corpus_sha256,
+        jaccard_threshold=jaccard_threshold,
+        total_clusters=len(clusters),
+        total_nodes_clustered=len(node_ids),
+        singletons=singletons,
+        clusters=tuple(clusters),
+    )

codeforge/kb/code_graph.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+import networkx as nx  # type: ignore[import-untyped]
+
+
+def build_code_graph(files: dict[str, str]) -> nx.DiGraph:
+    """Build a structural graph from Python source files.
+
+    Nodes: modules, functions, classes
+    Edges: imports, calls, inheritance, exports
+    """
+    g: nx.DiGraph = nx.DiGraph()
+    for filename, source in files.items():
+        module = filename.removesuffix(".py")
+        g.add_node(module, kind="module")
+        try:
+            tree = ast.parse(source, filename=filename)
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                fqn = f"{module}.{node.name}"
+                g.add_node(fqn, kind="function", line=node.lineno)
+                g.add_edge(module, fqn, relation="exports")
+            elif isinstance(node, ast.ClassDef):
+                fqn = f"{module}.{node.name}"
+                g.add_node(fqn, kind="class", line=node.lineno)
+                g.add_edge(module, fqn, relation="exports")
+                for base in node.bases:
+                    if isinstance(base, ast.Name):
+                        g.add_edge(fqn, base.id, relation="inherits")
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                g.add_edge(module, node.module, relation="imports")
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    g.add_edge(module, alias.name, relation="imports")
+    return g
+
+
+def query_graph(g: nx.DiGraph, question: str) -> list[dict[str, Any]]:
+    """Structural queries on the code graph.
+
+    Supported question prefixes:
+    - "exports_of <module>" -- functions/classes exported by module
+    - "imports_of <module>" -- modules imported by module
+    - "dependents_of <module>" -- modules that import this module
+    - "all_modules" -- list all module nodes
+    - "all_functions" -- list all function nodes
+    - "all_classes" -- list all class nodes
+    """
+    parts = question.strip().split(maxsplit=1)
+    if len(parts) < 1 or not parts[0]:
+        return []
+
+    cmd = parts[0].lower()
+    target = parts[1] if len(parts) > 1 else ""
+
+    if cmd == "exports_of":
+        if target not in g:
+            return []
+        return [
+            {"node": n, **g.nodes[n]}
+            for n in g.successors(target)
+            if g.edges[target, n].get("relation") == "exports"
+        ]
+
+    if cmd == "imports_of":
+        if target not in g:
+            return []
+        return [
+            {"node": n}
+            for n in g.successors(target)
+            if g.edges[target, n].get("relation") == "imports"
+        ]
+
+    if cmd == "dependents_of":
+        if target not in g:
+            return []
+        return [
+            {"node": n}
+            for n in g.predecessors(target)
+            if g.edges[n, target].get("relation") == "imports"
+        ]
+
+    if cmd == "all_modules":
+        return [
+            {"node": n, **d}
+            for n, d in g.nodes(data=True)
+            if d.get("kind") == "module"
+        ]
+
+    if cmd == "all_functions":
+        return [
+            {"node": n, **d}
+            for n, d in g.nodes(data=True)
+            if d.get("kind") == "function"
+        ]
+
+    if cmd == "all_classes":
+        return [
+            {"node": n, **d}
+            for n, d in g.nodes(data=True)
+            if d.get("kind") == "class"
+        ]
+
+    return []

codeforge/kb/corpus_manager.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from codeforge.scraper.discovery import SourceRoot, walk_sources
+from codeforge.scraper.parser import ParseError, parse_skill
+from codeforge.scraper.pipeline import _dedupe, scrape_single_skill
+
+_log = logging.getLogger(__name__)
+
+
+class SkillCorpusManager:
+    """Manages the skill corpus: add, remove, refresh, save/load JSONL."""
+
+    def __init__(self, *, corpus_path: Path) -> None:
+        self._corpus_path = corpus_path
+        self._nodes: list[dict[str, Any]] = []
+
+    @property
+    def nodes(self) -> list[dict[str, Any]]:
+        """Read-only access to the current node list."""
+        return list(self._nodes)
+
+    def load(self) -> None:
+        """Load existing corpus from JSONL file."""
+        if not self._corpus_path.is_file():
+            self._nodes = []
+            return
+        nodes: list[dict[str, Any]] = []
+        with self._corpus_path.open(encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                nodes.append(json.loads(line))
+        self._nodes = nodes
+
+    def add_skill(self, path: Path) -> int:
+        """Scrape a single SKILL.md, append nodes to corpus. Returns count added."""
+        new_nodes = scrape_single_skill(path)
+        if not new_nodes:
+            return 0
+        combined = list(self._nodes) + new_nodes
+        deduped = _dedupe(combined)
+        added = len(deduped) - len(self._nodes)
+        self._nodes = deduped
+        return max(added, 0)
+
+    def remove_skill(self, skill_name: str) -> int:
+        """Remove all nodes for skill_name. Returns count removed."""
+        before = len(self._nodes)
+        self._nodes = [n for n in self._nodes if n["skill_name"] != skill_name]
+        return before - len(self._nodes)
+
+    def refresh(
+        self, *, sources: list[SourceRoot] | None = None
+    ) -> dict[str, int]:
+        """Diff disk sources vs corpus by mtime/body_hash.
+
+        Returns {added, removed, unchanged}.
+        """
+        if sources is None:
+            sources = []
+
+        # Build a map of current corpus keyed by source_path
+        existing_by_path: dict[str, list[dict[str, Any]]] = {}
+        for node in self._nodes:
+            sp = node.get("source_path", "")
+            existing_by_path.setdefault(sp, []).append(node)
+
+        # Discover what's on disk
+        disk_paths: set[str] = set()
+        disk_nodes: list[dict[str, Any]] = []
+        for path, root in walk_sources(sources):
+            disk_paths.add(str(path))
+            try:
+                parse_skill(path)
+            except ParseError:
+                continue
+            file_nodes = scrape_single_skill(path)
+            for n in file_nodes:
+                n["source_root"] = root.label
+            disk_nodes.extend(file_nodes)
+
+        # Nodes from sources not on disk anymore -> removed
+        removed_count = 0
+        kept: list[dict[str, Any]] = []
+        for node in self._nodes:
+            sp = node.get("source_path", "")
+            if sp in disk_paths:
+                # Check if body_hash or mtime changed
+                pass  # handled below
+            elif sources:
+                # source_path no longer on disk via any source root
+                removed_count += 1
+                continue
+            kept.append(node)
+
+        # Determine unchanged vs changed via body_hash comparison
+        existing_hashes: set[tuple[str, str]] = set()
+        for node in kept:
+            existing_hashes.add(
+                (node.get("source_path", ""), node.get("body_hash", ""))
+            )
+
+        # Add new/changed nodes from disk
+        added_count = 0
+        for dn in disk_nodes:
+            key = (dn.get("source_path", ""), dn.get("body_hash", ""))
+            if key not in existing_hashes:
+                added_count += 1
+
+        # Replace nodes from disk-paths with fresh scraped versions
+        non_disk = [n for n in kept if n.get("source_path", "") not in disk_paths]
+        combined = non_disk + disk_nodes
+        deduped = _dedupe(combined)
+        unchanged = len(self._nodes) - removed_count - added_count
+        if unchanged < 0:
+            unchanged = 0
+
+        self._nodes = deduped
+        return {"added": added_count, "removed": removed_count, "unchanged": unchanged}
+
+    def save(self) -> None:
+        """Write corpus back to JSONL."""
+        self._corpus_path.parent.mkdir(parents=True, exist_ok=True)
+        sorted_nodes = sorted(self._nodes, key=lambda n: str(n["id"]))
+        with self._corpus_path.open("w", encoding="utf-8") as f:
+            for node in sorted_nodes:
+                f.write(json.dumps(node, default=str))
+                f.write("\n")
+
+    def node_count(self) -> int:
+        """Return current number of nodes in the corpus."""
+        return len(self._nodes)

codeforge/kb/indexer.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from rank_bm25 import BM25Okapi  # type: ignore[import-untyped]
+
+from codeforge.kb.models import Cluster, ClusterManifest, SearchResult
+from codeforge.kb.tokenizer import tokenize
+
+
+class SkillsIndex:
+    """BM25-backed full-text search over the skill documentation corpus."""
+
+    def __init__(self, *, corpus_path: Path) -> None:
+        self._corpus_path = corpus_path
+        self._nodes: list[dict[str, Any]] = []
+        self._tokenized: list[list[str]] = []
+        self._bm25: BM25Okapi | None = None
+        self._corpus_sha256: str = ""
+        self._cluster_manifest: ClusterManifest | None = None
+        self._node_to_cluster: dict[str, Cluster] = {}
+
+    def build(self) -> None:
+        """Load JSONL corpus and build BM25 index."""
+        if not self._corpus_path.is_file():
+            msg = f"corpus missing: {self._corpus_path}"
+            raise FileNotFoundError(msg)
+        self._corpus_sha256 = hashlib.sha256(
+            self._corpus_path.read_bytes(),
+        ).hexdigest()
+        self._nodes = []
+        self._tokenized = []
+        with self._corpus_path.open(encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                node: dict[str, Any] = json.loads(line)
+                self._nodes.append(node)
+                self._tokenized.append(
+                    tokenize(str(node.get("section_body", ""))),
+                )
+        if self._tokenized:
+            self._bm25 = BM25Okapi(self._tokenized)
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        required_tags: set[str] | None = None,
+    ) -> list[SearchResult]:
+        """BM25 search over corpus, optionally filtered by tags."""
+        q_tokens = tokenize(query)
+        if not q_tokens or self._bm25 is None or not self._nodes:
+            return []
+        candidates: list[int] = list(range(len(self._nodes)))
+        if required_tags:
+            candidates = [
+                i
+                for i in candidates
+                if required_tags.issubset(set(self._nodes[i].get("tags", [])))
+            ]
+            if not candidates:
+                return []
+        all_scores = self._bm25.get_scores(q_tokens)
+        scored = [(i, float(all_scores[i])) for i in candidates]
+        scored.sort(key=lambda pair: (-pair[1], self._nodes[pair[0]]["id"]))
+        top = scored[:top_k]
+        results: list[SearchResult] = []
+        for rank, (i, score) in enumerate(top, start=1):
+            node = self._nodes[i]
+            cluster = self._node_to_cluster.get(node["id"])
+            results.append(
+                SearchResult(
+                    node_id=node["id"],
+                    skill_name=node["skill_name"],
+                    section_path=tuple(node["section_path"]),
+                    section_body=node["section_body"],
+                    tags=tuple(node["tags"]),
+                    source_path=node["source_path"],
+                    score=score,
+                    rank=rank,
+                    cluster_id=cluster.cluster_id if cluster else None,
+                ),
+            )
+        return results
+
+    def attach_cluster_manifest(self, manifest: ClusterManifest) -> None:
+        """Wire cluster assignments to nodes for search enrichment."""
+        self._cluster_manifest = manifest
+        self._node_to_cluster = {
+            nid: cluster
+            for cluster in manifest.clusters
+            for nid in cluster.member_node_ids
+        }
+
+    def cluster_by_label(self, label: str) -> Cluster | None:
+        """Look up a cluster by its label string."""
+        if self._cluster_manifest is None:
+            return None
+        for c in self._cluster_manifest.clusters:
+            if c.label == label:
+                return c
+        return None
+
+    def nodes_in_cluster(
+        self,
+        cluster_label: str,
+        top_k: int = 50,
+    ) -> list[SearchResult]:
+        """Return corpus nodes belonging to the named cluster."""
+        cluster = self.cluster_by_label(cluster_label)
+        if cluster is None:
+            return []
+        member_ids = set(cluster.member_node_ids)
+        results: list[SearchResult] = []
+        for node in self._nodes:
+            if node["id"] not in member_ids:
+                continue
+            results.append(
+                SearchResult(
+                    node_id=node["id"],
+                    skill_name=node["skill_name"],
+                    section_path=tuple(node["section_path"]),
+                    section_body=node["section_body"],
+                    tags=tuple(node["tags"]),
+                    source_path=node["source_path"],
+                    score=0.0,
+                    rank=len(results) + 1,
+                    cluster_id=cluster.cluster_id,
+                ),
+            )
+            if len(results) >= top_k:
+                break
+        return results
+
+    def stats(self) -> dict[str, int | float]:
+        """Return index statistics: node_count, vocab_size, avg_doc_len."""
+        if not self._tokenized:
+            return {"node_count": 0, "vocab_size": 0, "avg_doc_len": 0.0}
+        vocab: set[str] = set()
+        total_len = 0
+        for toks in self._tokenized:
+            vocab.update(toks)
+            total_len += len(toks)
+        return {
+            "node_count": len(self._nodes),
+            "vocab_size": len(vocab),
+            "avg_doc_len": total_len / len(self._tokenized),
+        }
+
+    def all_cluster_labels(self) -> list[str]:
+        """Return all cluster labels (for MCP discovery tool)."""
+        if self._cluster_manifest is None:
+            return []
+        return [c.label for c in self._cluster_manifest.clusters]
+
+    def all_tags(self) -> set[str]:
+        """Return all unique tags across the corpus (for MCP discovery tool)."""
+        tags: set[str] = set()
+        for node in self._nodes:
+            for t in node.get("tags", []):
+                tags.add(str(t))
+        return tags

codeforge/kb/models.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class SearchResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    node_id: str
+    skill_name: str
+    section_path: tuple[str, ...]
+    section_body: str
+    tags: tuple[str, ...]
+    source_path: str
+    score: float
+    rank: int
+    cluster_id: str | None = None
+
+
+class Cluster(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    cluster_id: str
+    label: str
+    dominant_domain: str
+    top_tokens: tuple[str, ...]
+    node_count: int
+    member_node_ids: tuple[str, ...]
+
+
+class ClusterManifest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    generated_at: str
+    corpus_sha256: str
+    jaccard_threshold: float
+    total_clusters: int
+    total_nodes_clustered: int
+    singletons: int
+    clusters: tuple[Cluster, ...]

codeforge/kb/skills_corpus.manifest.json

@@ -0,0 +1,14 @@
+{
+  "generated_at": "2026-04-18T10:23:57+00:00",
+  "sources": [
+    {
+      "label": "ecc",
+      "glob": "CODEFORGE/everything-claude-code/skills/*/SKILL.md"
+    }
+  ],
+  "scraped_files": 183,
+  "skipped_files": 0,
+  "total_nodes": 2212,
+  "errors": [],
+  "corpus_sha256": "7cbc3be718ad4365b2061ee253e15d9f6de7e0e52c43198ffd021754c02029d3"
+}

codeforge/kb/tokenizer.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import re
+
+_SPLIT_RE = re.compile(r"[^\w]+", re.UNICODE)
+
+
+def tokenize(text: str) -> list[str]:
+    return [t for t in _SPLIT_RE.split(text.lower()) if t]

codeforge/mcp_server.py

@@ -0,0 +1,848 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from codeforge.environment import CodeForgeEnvironment
+from codeforge.models import CodeForgeAction, CodeForgeActionType
+from codeforge.ralph.synthesizer import Synthesizer
+from codeforge.tasks import TASKS
+
+_log = logging.getLogger(__name__)
+_VERSION = "0.2.0"
+
+_Handler = Callable[
+    ["CodeForgeMCPServer", "dict[str, Any]"],
+    "dict[str, Any]",
+]
+
+_SID_DESC = "Session ID from codeforge_reset."
+_SID_PROP: dict[str, str] = {
+    "type": "string",
+    "description": _SID_DESC,
+}
+
+# -------------------------------------------------------------------
+# Tool schema definitions (SYSTEM_DESIGN §9.1)
+# -------------------------------------------------------------------
+
+_TOOL_DEFS: tuple[dict[str, Any], ...] = (
+    {
+        "name": "codeforge_reset",
+        "description": (
+            "Start a new CodeForge episode. You will receive a task "
+            "brief and initial files. Your goal is to produce working "
+            "Python code that passes sandbox verification. Budget is "
+            "limited — plan your actions carefully."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "task_level": {
+                    "type": "string",
+                    "enum": ["easy", "medium", "hard"],
+                    "description": (
+                        "Difficulty level. Easy: single file, budget "
+                        "4. Medium: multi-file with tests, budget 6. "
+                        "Hard: three-file module, budget 10."
+                    ),
+                },
+            },
+            "required": ["task_level"],
+        },
+    },
+    {
+        "name": "codeforge_query_kb",
+        "description": (
+            "Search the coding skills knowledge base. Returns real "
+            "documentation from 1006 skill nodes. Use this to find "
+            "patterns, best practices, and guidance BEFORE writing "
+            "code. Costs 1 budget unit. DO NOT guess library APIs — "
+            "search for them here or verify via documentation first."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "session_id": _SID_PROP,
+                "claim": {
+                    "type": "string",
+                    "description": (
+                        "What you want to find guidance on. Be "
+                        "specific. Example: 'pytest fixture patterns "
+                        "for testing greet functions'"
+                    ),
+                },
+                "top_k": {
+                    "type": "integer",
+                    "default": 5,
+                    "minimum": 1,
+                    "maximum": 20,
+                    "description": "Number of results to return",
+                },
+                "required_tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "default": [],
+                    "description": (
+                        "Only return nodes that have ALL of these "
+                        "tags"
+                    ),
+                },
+            },
+            "required": ["session_id", "claim"],
+        },
+    },
+    {
+        "name": "codeforge_query_cluster",
+        "description": (
+            "Browse a skill cluster by label. Clusters are communities "
+            "of related skill nodes grouped by Jaccard similarity. Use "
+            "this to explore a topic area deeply. Costs 1 budget unit."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "session_id": _SID_PROP,
+                "cluster_label": {
+                    "type": "string",
+                    "description": (
+                        "The cluster label to look up. Example: "
+                        "'python_testing_pytest_fixtures'"
+                    ),
+                },
+                "top_k": {
+                    "type": "integer",
+                    "default": 10,
+                    "minimum": 1,
+                    "maximum": 50,
+                },
+            },
+            "required": ["session_id", "cluster_label"],
+        },
+    },
+    {
+        "name": "codeforge_interrogate",
+        "description": (
+            "Get Socratic questions about the task that cite real skill "
+            "corpus nodes. Use this BEFORE writing code to identify "
+            "edge cases, success criteria, and assumptions you might be "
+            "wrong about. Costs 1 budget unit."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "session_id": _SID_PROP,
+                "brief_override": {
+                    "type": "string",
+                    "description": (
+                        "Optional override for the task brief. "
+                        "If omitted, uses the current task brief."
+                    ),
+                },
+            },
+            "required": ["session_id"],
+        },
+    },
+    {
+        "name": "codeforge_run_ralph",
+        "description": (
+            "Run autonomous improvement iterations on your current "
+            "code. Each iteration: synthesize improvement → "
+            "sandbox-score → keep if better. Costs max_iters budget "
+            "units. Wasted iterations (no improvement) cost 0.05 "
+            "penalty each. Use when you want the environment to "
+            "iteratively improve your code."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "session_id": _SID_PROP,
+                "max_iters": {
+                    "type": "integer",
+                    "default": 3,
+                    "minimum": 1,
+                    "maximum": 10,
+                    "description": (
+                        "Maximum iterations. Each costs 1 budget. "
+                        "Choose carefully."
+                    ),
+                },
+            },
+            "required": ["session_id", "max_iters"],
+        },
+    },
+    {
+        "name": "codeforge_submit",
+        "description": (
+            "Submit Python files for grading. Your code will be: "
+            "(1) written to a sandbox and checked by ruff, mypy "
+            "--strict, pytest, and import resolution — these are REAL "
+            "tools, not mocks; (2) AST-grounded to verify every "
+            "import and attribute access resolves to a real Python "
+            "module/attribute; (3) scored via quality = 0.6*sandbox + "
+            "0.4*groundedness; (4) if you provide confidence, "
+            "Brier-penalized: reward = quality * (1 - "
+            "min((confidence-quality)^2, 0.5)). DO NOT fabricate "
+            "library names or API signatures — the grounder WILL "
+            "catch them and your score WILL drop."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "session_id": _SID_PROP,
+                "files": {
+                    "type": "object",
+                    "additionalProperties": {"type": "string"},
+                    "description": (
+                        "Map of filename to file content. Example: "
+                        '{"main.py": "def greet(name: str) -> str:'
+                        "\\n    return f'Hello, {name}!'\\n\"}"
+                    ),
+                },
+                "confidence": {
+                    "type": "number",
+                    "minimum": 0.0,
+                    "maximum": 1.0,
+                    "description": (
+                        "Your confidence that this submission is "
+                        "correct (0.0 = no idea, 1.0 = certain). "
+                        "Overconfidence on bad code is PENALIZED. "
+                        "Honest uncertainty is treated more "
+                        "favorably. If you are unsure, say so."
+                    ),
+                },
+            },
+            "required": ["session_id", "files"],
+        },
+    },
+    {
+        "name": "codeforge_get_audit",
+        "description": (
+            "Read the audit trail for the current episode (or a "
+            "specific run). Returns every action taken, every citation "
+            "made, every reward earned, and the evidence behind each. "
+            "Costs 0 budget. Use this to review your progress and "
+            "understand what worked."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "session_id": _SID_PROP,
+                "target_run_id": {
+                    "type": "string",
+                    "description": (
+                        "Optional run ID to audit. "
+                        "Defaults to current episode."
+                    ),
+                },
+            },
+            "required": ["session_id"],
+        },
+    },
+    {
+        "name": "codeforge_state",
+        "description": (
+            "Get current episode state without taking an action. Shows "
+            "task brief, current files, budget remaining, last reward, "
+            "and whether the episode is done. Costs 0 budget."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"session_id": _SID_PROP},
+            "required": ["session_id"],
+        },
+    },
+    {
+        "name": "codeforge_list_clusters",
+        "description": (
+            "List all available cluster labels and their node counts. "
+            "Use this to discover what topic areas exist before "
+            "calling codeforge_query_cluster. Costs 0 budget."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"session_id": _SID_PROP},
+        },
+    },
+    {
+        "name": "codeforge_list_tags",
+        "description": (
+            "List all available tags in the skill corpus. Use this to "
+            "discover valid values for the required_tags parameter. "
+            "Costs 0 budget."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"session_id": _SID_PROP},
+        },
+    },
+)
+
+# -------------------------------------------------------------------
+# Resource definitions
+# -------------------------------------------------------------------
+
+_RESOURCE_DEFS: tuple[dict[str, str], ...] = (
+    {
+        "uri": "codeforge://corpus/stats",
+        "name": "Corpus Statistics",
+        "description": (
+            "Corpus statistics (node count, vocab size, cluster count)"
+        ),
+        "mimeType": "application/json",
+    },
+    {
+        "uri": "codeforge://corpus/node/{node_id}",
+        "name": "Skill Node",
+        "description": (
+            "Full content of a specific skill node (free, no budget)"
+        ),
+        "mimeType": "application/json",
+    },
+    {
+        "uri": "codeforge://tasks",
+        "name": "Task Definitions",
+        "description": (
+            "Task definitions with briefs, budgets, targets, tools"
+        ),
+        "mimeType": "application/json",
+    },
+    {
+        "uri": "codeforge://audit/{episode_id}",
+        "name": "Audit Ledger",
+        "description": (
+            "Serialized audit ledger for a completed episode"
+        ),
+        "mimeType": "application/json",
+    },
+)
+
+# -------------------------------------------------------------------
+# Prompt text
+# -------------------------------------------------------------------
+
+_SYSTEM_PROMPT_TEXT = (
+    "You are solving a CodeForge episode. Your code is graded by "
+    "REAL tools (ruff, mypy --strict, pytest, import resolution) in "
+    "a sandbox. Every import and attribute access is AST-grounded "
+    "against the real Python runtime. Overconfidence is penalized "
+    "via Brier scoring. Honest uncertainty about genuinely uncertain "
+    "results is rewarded.\n\n"
+    "Rules:\n"
+    "- DO NOT fabricate library names or API signatures — "
+    "the grounder catches them.\n"
+    "- DO NOT submit stubs (pass, ..., NotImplementedError) — "
+    "they score zero.\n"
+    "- Use codeforge_query_kb to find patterns BEFORE writing code.\n"
+    "- Use codeforge_interrogate to identify edge cases.\n"
+    "- Budget is limited. Plan actions carefully.\n"
+    "- If unsure of your confidence, set it low — "
+    "the grader rewards honesty.\n"
+)
+
+_SESSION_ERR = "Invalid session_id: {sid!r}. Call codeforge_reset first."
+
+
+# -------------------------------------------------------------------
+# Helpers
+# -------------------------------------------------------------------
+
+
+def _obs_to_dict(obs: Any) -> dict[str, Any]:
+    """Convert a CodeForgeObservation to a serializable dict."""
+    result: dict[str, Any] = json.loads(obs.model_dump_json())
+    return result
+
+
+def _make_response(
+    obs: Any,
+    *,
+    session_id: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a versioned response dict from an observation."""
+    result: dict[str, Any] = {"_codeforge_version": _VERSION}
+    if session_id is not None:
+        result["session_id"] = session_id
+    result["observation"] = _obs_to_dict(obs)
+    if extra:
+        result.update(extra)
+    budget = result["observation"].get("budget_remaining", 0)
+    if isinstance(budget, int) and 0 < budget <= 2:
+        result["budget_warning"] = (
+            f"WARNING: {budget} budget remaining — plan carefully."
+        )
+    return result
+
+
+def _session_error(sid: str) -> dict[str, Any]:
+    """Return an isError response for a missing session."""
+    return {
+        "isError": True,
+        "error": _SESSION_ERR.format(sid=sid),
+        "_codeforge_version": _VERSION,
+    }
+
+
+def _require_session(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> tuple[str, CodeForgeEnvironment | None]:
+    """Extract session_id and look up the environment."""
+    sid: str = arguments.get("session_id", "")
+    return sid, server._get_session(sid)
+
+
+# -------------------------------------------------------------------
+# CodeForgeMCPServer — embedded mode
+# -------------------------------------------------------------------
+
+
+class CodeForgeMCPServer:
+    """MCP server wrapping CodeForgeEnvironment (SYSTEM_DESIGN §9).
+
+    Embedded mode: imports CodeForgeEnvironment directly.
+    Each tool call is routed to a session-keyed environment.
+
+    **Universal LLM support:** The Ralph loop's synthesizer is configurable.
+    Whichever LLM connects to this MCP server can provide its own config::
+
+        # Ollama (local, free)
+        server = CodeForgeMCPServer(llm_provider="ollama", llm_model="llama3")
+
+        # OpenAI
+        server = CodeForgeMCPServer(llm_provider="openai", llm_model="gpt-4o")
+
+        # Anthropic
+        server = CodeForgeMCPServer(llm_provider="anthropic", llm_model="claude-sonnet-4-20250514")
+
+        # Any OpenAI-compatible (vLLM, LM Studio, Together, Groq)
+        server = CodeForgeMCPServer(
+            llm_provider="openai",
+            llm_base_url="http://localhost:8000/v1",
+            llm_model="my-model",
+        )
+
+    When no LLM config is provided, Ralph uses the deterministic
+    StubSynthesizer (no API calls needed).
+    """
+
+    def __init__(
+        self,
+        *,
+        corpus_path: Path | None = None,
+        max_sessions: int = 10,
+        llm_provider: str | None = None,
+        llm_api_key: str | None = None,
+        llm_base_url: str | None = None,
+        llm_model: str | None = None,
+    ) -> None:
+        self._corpus_path = corpus_path
+        self._sessions: dict[str, CodeForgeEnvironment] = {}
+        self._max_sessions = max_sessions
+        self._llm_provider = llm_provider
+        self._llm_api_key = llm_api_key
+        self._llm_base_url = llm_base_url
+        self._llm_model = llm_model
+
+    # -- Session management ------------------------------------------
+
+    def _get_session(
+        self,
+        session_id: str,
+    ) -> CodeForgeEnvironment | None:
+        return self._sessions.get(session_id)
+
+    def _create_session(
+        self,
+    ) -> tuple[str, CodeForgeEnvironment]:
+        sid = uuid4().hex[:16]
+        # Build synthesizer from LLM config (if provided)
+        synth: Synthesizer | None = None
+        if self._llm_provider:
+            from codeforge.ralph.synthesizer import LLMSynthesizer
+
+            synth = LLMSynthesizer(
+                provider=self._llm_provider,
+                api_key=self._llm_api_key,
+                base_url=self._llm_base_url,
+                model=self._llm_model,
+            )
+
+        env = CodeForgeEnvironment(
+            corpus_path=self._corpus_path,
+            synthesizer=synth,
+        )
+        if len(self._sessions) >= self._max_sessions:
+            oldest = next(iter(self._sessions))
+            del self._sessions[oldest]
+        self._sessions[sid] = env
+        return sid, env
+
+    # -- Public: definitions -----------------------------------------
+
+    def tool_definitions(self) -> list[dict[str, Any]]:
+        """Return tool schemas matching SYSTEM_DESIGN §9.1."""
+        return [dict(d) for d in _TOOL_DEFS]
+
+    def resource_definitions(self) -> list[dict[str, str]]:
+        """Return MCP resource definitions."""
+        return [dict(r) for r in _RESOURCE_DEFS]
+
+    def prompt_definitions(self) -> list[dict[str, Any]]:
+        """Return MCP prompt definitions."""
+        return [
+            {
+                "name": "codeforge_system",
+                "description": (
+                    "System prompt injected at session start. "
+                    "Contains task rules, budget constraints, "
+                    "grading explanation."
+                ),
+                "arguments": [],
+            },
+            {
+                "name": "codeforge_task_brief",
+                "description": (
+                    "Dynamic prompt populated with the current "
+                    "task's brief, initial files, budget, target "
+                    "score, and tool config."
+                ),
+                "arguments": [
+                    {
+                        "name": "session_id",
+                        "description": _SID_DESC,
+                        "required": True,
+                    },
+                ],
+            },
+        ]
+
+    # -- Public: handle_tool -----------------------------------------
+
+    def handle_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Route tool call to handler, return result dict."""
+        handler = _HANDLERS.get(tool_name)
+        if handler is None:
+            return {
+                "isError": True,
+                "error": f"Unknown tool: {tool_name!r}",
+                "_codeforge_version": _VERSION,
+            }
+        return handler(self, arguments)
+
+    # -- Public: resources -------------------------------------------
+
+    def read_resource(
+        self,
+        uri: str,
+        *,
+        session_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Read an MCP resource by URI."""
+        if uri == "codeforge://corpus/stats":
+            if session_id is None:
+                return {
+                    "_codeforge_version": _VERSION,
+                    "error": "session_id required for corpus stats",
+                }
+            env = self._get_session(session_id)
+            if env is None:
+                return {"_codeforge_version": _VERSION, "error": "Invalid session_id"}
+            idx = env._ensure_index()
+            stats = idx.stats()
+            cluster_count = len(idx.all_cluster_labels())
+            return {
+                "node_count": stats["node_count"],
+                "vocab_size": stats["vocab_size"],
+                "avg_doc_len": stats["avg_doc_len"],
+                "cluster_count": cluster_count,
+            }
+        if uri.startswith("codeforge://corpus/node/"):
+            node_id = uri.removeprefix("codeforge://corpus/node/")
+            if session_id is None:
+                return {
+                    "_codeforge_version": _VERSION,
+                    "error": "session_id required for node lookup",
+                }
+            env = self._get_session(session_id)
+            if env is None:
+                return {"_codeforge_version": _VERSION, "error": "Invalid session_id"}
+            idx = env._ensure_index()
+            for node in idx._nodes:
+                if node.get("id") == node_id:
+                    return {"_codeforge_version": _VERSION, "node": node}
+            return {"_codeforge_version": _VERSION, "error": f"Node {node_id!r} not found"}
+        if uri == "codeforge://tasks":
+            return {
+                "_codeforge_version": _VERSION,
+                "tasks": [
+                    {
+                        "id": t.task_id,
+                        "difficulty": t.task_level,
+                        "brief": t.brief,
+                        "target_score": t.target_score,
+                        "max_budget": t.max_budget,
+                        "tools": list(t.tools),
+                    }
+                    for t in TASKS
+                ],
+            }
+        if uri.startswith("codeforge://audit/"):
+            episode_id = uri.removeprefix("codeforge://audit/")
+            if session_id is None:
+                return {
+                    "_codeforge_version": _VERSION,
+                    "error": "session_id required for audit lookup",
+                }
+            env = self._get_session(session_id)
+            if env is None:
+                return {"_codeforge_version": _VERSION, "error": "Invalid session_id"}
+            if env._ledger is not None:
+                return {
+                    "_codeforge_version": _VERSION,
+                    "episode_id": episode_id,
+                    "audit": env._ledger.serialize(),
+                }
+            return {
+                "_codeforge_version": _VERSION,
+                "error": "No audit data for this session",
+            }
+        return {"_codeforge_version": _VERSION, "error": f"Unknown resource URI: {uri!r}"}
+
+    # -- Public: prompts ---------------------------------------------
+
+    def get_prompt(
+        self,
+        name: str,
+        *,
+        session_id: str | None = None,
+    ) -> list[dict[str, str]]:
+        """Return prompt messages for the given prompt name."""
+        if name == "codeforge_system":
+            return [
+                {"role": "system", "content": _SYSTEM_PROMPT_TEXT},
+            ]
+        if name == "codeforge_task_brief":
+            if session_id is None:
+                return [
+                    {
+                        "role": "system",
+                        "content": (
+                            "Error: session_id required for "
+                            "task_brief prompt."
+                        ),
+                    },
+                ]
+            env = self._get_session(session_id)
+            if env is None:
+                return [
+                    {
+                        "role": "system",
+                        "content": "Error: invalid session_id.",
+                    },
+                ]
+            obs = env.state
+            task = env._task
+            target = task.target_score if task is not None else 0.0
+            content = (
+                f"## Task: {obs.task_id}\n"
+                f"**Level:** {obs.task_level}\n"
+                f"**Brief:** {obs.task_brief}\n"
+                f"**Budget:** {obs.budget_remaining}\n"
+                f"**Target score:** {target}\n\n"
+                "### Initial files\n"
+            )
+            for fname, body in obs.initial_files.items():
+                content += (
+                    f"\n**{fname}:**\n```python\n{body}\n```\n"
+                )
+            return [{"role": "system", "content": content}]
+        return [
+            {
+                "role": "system",
+                "content": f"Unknown prompt: {name!r}",
+            },
+        ]
+
+
+# -------------------------------------------------------------------
+# Tool handlers (private, keyed by tool name)
+# -------------------------------------------------------------------
+
+
+def _handle_reset(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    task_level = arguments.get("task_level", "easy")
+    sid, env = server._create_session()
+    obs = env.reset(task_level=task_level)
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_query_kb(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    sid, env = _require_session(server, arguments)
+    if env is None:
+        return _session_error(sid)
+    action = CodeForgeAction(
+        action_type=CodeForgeActionType.QUERY_KB,
+        claim=arguments.get("claim"),
+        top_k=arguments.get("top_k", 5),
+        required_tags=tuple(arguments.get("required_tags", ())),
+    )
+    obs = env.step(action)
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_query_cluster(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    sid, env = _require_session(server, arguments)
+    if env is None:
+        return _session_error(sid)
+    action = CodeForgeAction(
+        action_type=CodeForgeActionType.QUERY_CLUSTER,
+        cluster_label=arguments.get("cluster_label"),
+        top_k=arguments.get("top_k", 10),
+    )
+    obs = env.step(action)
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_interrogate(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    sid, env = _require_session(server, arguments)
+    if env is None:
+        return _session_error(sid)
+    action = CodeForgeAction(
+        action_type=CodeForgeActionType.INTERROGATE,
+    )
+    obs = env.step(action)
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_run_ralph(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    sid, env = _require_session(server, arguments)
+    if env is None:
+        return _session_error(sid)
+    action = CodeForgeAction(
+        action_type=CodeForgeActionType.RUN_RALPH,
+        max_iters=arguments.get("max_iters", 3),
+    )
+    obs = env.step(action)
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_submit(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    sid, env = _require_session(server, arguments)
+    if env is None:
+        return _session_error(sid)
+    action = CodeForgeAction(
+        action_type=CodeForgeActionType.SUBMIT,
+        files=arguments.get("files"),
+        confidence=arguments.get("confidence"),
+    )
+    obs = env.step(action)
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_get_audit(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    sid, env = _require_session(server, arguments)
+    if env is None:
+        return _session_error(sid)
+    action = CodeForgeAction(
+        action_type=CodeForgeActionType.GET_AUDIT,
+        target_run_id=arguments.get("target_run_id"),
+    )
+    obs = env.step(action)
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_state(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    sid, env = _require_session(server, arguments)
+    if env is None:
+        return _session_error(sid)
+    obs = env.state
+    return _make_response(obs, session_id=sid)
+
+
+def _handle_list_clusters(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    _sid, env = _require_session(server, arguments)
+    if env is None:
+        return {"_codeforge_version": _VERSION, "clusters": []}
+    try:
+        idx = env._ensure_index()
+    except FileNotFoundError:
+        return {"_codeforge_version": _VERSION, "clusters": []}
+    labels = idx.all_cluster_labels()
+    cluster_info: list[dict[str, Any]] = []
+    for label in labels:
+        cluster = idx.cluster_by_label(label)
+        if cluster is not None:
+            cluster_info.append({
+                "label": cluster.label,
+                "node_count": cluster.node_count,
+            })
+    return {"_codeforge_version": _VERSION, "clusters": cluster_info}
+
+
+def _handle_list_tags(
+    server: CodeForgeMCPServer,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    _sid, env = _require_session(server, arguments)
+    if env is None:
+        return {"_codeforge_version": _VERSION, "tags": []}
+    try:
+        idx = env._ensure_index()
+    except FileNotFoundError:
+        return {"_codeforge_version": _VERSION, "tags": []}
+    return {
+        "_codeforge_version": _VERSION,
+        "tags": sorted(idx.all_tags()),
+    }
+
+
+# Handler dispatch table
+_HANDLERS: dict[str, _Handler] = {
+    "codeforge_reset": _handle_reset,
+    "codeforge_query_kb": _handle_query_kb,
+    "codeforge_query_cluster": _handle_query_cluster,
+    "codeforge_interrogate": _handle_interrogate,
+    "codeforge_run_ralph": _handle_run_ralph,
+    "codeforge_submit": _handle_submit,
+    "codeforge_get_audit": _handle_get_audit,
+    "codeforge_state": _handle_state,
+    "codeforge_list_clusters": _handle_list_clusters,
+    "codeforge_list_tags": _handle_list_tags,
+}

codeforge/models.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field
+
+
+class CodeForgeActionType(StrEnum):
+    QUERY_KB = "query_kb"
+    QUERY_CLUSTER = "query_cluster"
+    INTERROGATE = "interrogate"
+    RUN_RALPH = "run_ralph"
+    SUBMIT = "submit"
+    GET_AUDIT = "get_audit"
+
+
+class CodeForgeAction(Action):
+    action_type: CodeForgeActionType
+    # query_kb fields
+    claim: str | None = None
+    top_k: int = 5
+    required_tags: tuple[str, ...] = ()
+    # submit fields
+    files: dict[str, str] | None = None
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+    # query_cluster fields
+    cluster_label: str | None = None
+    # run_ralph fields
+    max_iters: int = Field(default=3, ge=1, le=10)
+    # get_audit fields
+    target_run_id: str | None = None
+
+
+class CodeForgeObservation(Observation):
+    episode_id: str
+    task_id: str
+    task_level: str
+    task_brief: str
+    initial_files: dict[str, str]
+    current_files: dict[str, str]
+    budget_remaining: int
+    previous_score: float
+    last_reward: float
+    is_done: bool
+    # KB results
+    last_citations: tuple[dict[str, object], ...] = ()
+    last_grounding: dict[str, object] | None = None
+    # Cluster results
+    last_cluster_hits: tuple[str, ...] = ()
+    # Interrogation results
+    last_interrogation_questions: tuple[str, ...] = ()
+    # Ralph results
+    last_ralph_run_id: str | None = None
+    last_ralph_iterations: tuple[dict[str, object], ...] = ()
+    # Audit summary
+    cumulative_audit_summary: dict[str, object] = Field(default_factory=dict)
+    # Error field
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    step_index: int
+    action_type: str
+    cited_skill_ids: tuple[str, ...]
+    cited_clusters: tuple[str, ...]
+    grounding_report: dict[str, object] | None
+    reward: float
+    brier_penalty: float | None
+    confidence_declared: float | None
+    quality: float

codeforge/observation.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from codeforge.models import CodeForgeObservation
+
+if TYPE_CHECKING:
+    from codeforge.tasks import Task
+
+
+def build_observation(
+    *,
+    episode_id: str,
+    task: Task,
+    current_files: dict[str, str],
+    budget_remaining: int,
+    previous_score: float,
+    last_citations: tuple[dict[str, object], ...] = (),
+    last_grounding: dict[str, object] | None = None,
+    is_done: bool = False,
+    last_reward: float = 0.0,
+    last_cluster_hits: tuple[str, ...] = (),
+    last_interrogation_questions: tuple[str, ...] = (),
+    last_ralph_run_id: str | None = None,
+    last_ralph_iterations: tuple[dict[str, object], ...] = (),
+    cumulative_audit_summary: dict[str, object] | None = None,
+    error: str | None = None,
+) -> CodeForgeObservation:
+    return CodeForgeObservation(
+        episode_id=episode_id,
+        task_id=task.task_id,
+        task_level=task.task_level,
+        task_brief=task.brief,
+        initial_files=dict(task.initial_files),
+        current_files=dict(current_files),
+        budget_remaining=budget_remaining,
+        previous_score=previous_score,
+        last_citations=last_citations,
+        last_grounding=last_grounding,
+        is_done=is_done,
+        last_reward=last_reward,
+        last_cluster_hits=last_cluster_hits,
+        last_interrogation_questions=last_interrogation_questions,
+        last_ralph_run_id=last_ralph_run_id,
+        last_ralph_iterations=last_ralph_iterations,
+        cumulative_audit_summary=cumulative_audit_summary or {},
+        error=error,
+        reward=last_reward,
+        done=is_done,
+    )

codeforge/ralph/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from codeforge.ralph.loop import run_loop
+from codeforge.ralph.models import LoopConfig, RunResult
+from codeforge.ralph.planner import Planner, Subtask
+from codeforge.ralph.synthesizer import LLMSynthesizer, StubSynthesizer, Synthesizer
+
+__all__ = [
+    "LLMSynthesizer",
+    "LoopConfig",
+    "Planner",
+    "RunResult",
+    "StubSynthesizer",
+    "Subtask",
+    "Synthesizer",
+    "run_loop",
+]

codeforge/ralph/checkpoint.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from codeforge.ralph.models import RunResult
+
+
+def save_checkpoint(run: RunResult, checkpoint_dir: Path) -> Path:
+    """Atomically write a RunResult to ``checkpoint_dir/run_{run_id}.json``."""
+    checkpoint_dir.mkdir(parents=True, exist_ok=True)
+    final = checkpoint_dir / f"run_{run.run_id}.json"
+    tmp = final.with_suffix(".json.tmp")
+    tmp.write_text(run.model_dump_json(indent=2), encoding="utf-8")
+    os.replace(tmp, final)
+    return final
+
+
+def load_checkpoint(checkpoint_path: Path) -> RunResult:
+    """Load a RunResult from a checkpoint JSON file."""
+    return RunResult.model_validate_json(
+        checkpoint_path.read_text(encoding="utf-8"),
+    )

codeforge/ralph/loop.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from codeforge.ralph.checkpoint import save_checkpoint
+from codeforge.ralph.models import (
+    Iteration,
+    IterationReason,
+    LoopConfig,
+    RunResult,
+    TerminationReason,
+)
+from codeforge.sandbox.sandbox import run_sandbox
+
+if TYPE_CHECKING:
+    from codeforge.kb.indexer import SkillsIndex
+    from codeforge.ralph.synthesizer import Synthesizer
+
+_log = logging.getLogger(__name__)
+_STUCK_THRESHOLD = 3
+
+
+def _score_files(files: Mapping[str, str], config: LoopConfig) -> float:
+    """Score files via the real sandbox. Returns 0.0 on any error."""
+    try:
+        result = run_sandbox(
+            files=dict(files),
+            tools=config.tools,
+            timeout_per_tool=config.timeout_per_tool,
+        )
+    except Exception as e:
+        _log.exception("sandbox error: %s", e)
+        return 0.0
+    return result.composite_score
+
+
+def run_loop(
+    *,
+    spec: str,
+    initial_files: Mapping[str, str],
+    index: SkillsIndex,
+    synthesizer: Synthesizer,
+    config: LoopConfig | None = None,
+    checkpoint_dir: Path | None = None,
+) -> RunResult:
+    """Run the score-gated retry loop.
+
+    Each iteration: score current → synthesize → score proposed → keep if better.
+    Terminates on target_hit, max_iters, or stuck (3 consecutive regressions).
+    """
+    cfg = config or LoopConfig()
+    run_id = f"ralph_{uuid.uuid4().hex[:12]}"
+    started_at = datetime.now(UTC).isoformat(timespec="seconds")
+
+    current: dict[str, str] = dict(initial_files)
+    iterations: list[Iteration] = []
+    consecutive_regressions = 0
+    terminated_by: TerminationReason = "max_iters"
+
+    for i in range(cfg.max_iters):
+        score_before = _score_files(current, cfg)
+        if score_before >= cfg.target_score:
+            terminated_by = "target_hit"
+            break
+
+        citations = index.search(spec, top_k=cfg.top_k_citations)
+
+        synth_reason: IterationReason | None = None
+        try:
+            synth = synthesizer.synthesize(
+                spec=spec,
+                current_files=current,
+                citations=citations,
+                iteration=i,
+            )
+        except Exception as e:
+            _log.exception("synthesizer error: %s", e)
+            synth = None
+            synth_reason = "synthesizer_error"
+
+        if synth is None:
+            iterations.append(
+                Iteration(
+                    index=i,
+                    cited_node_ids=(),
+                    rationale="synth_error",
+                    proposed_files=current,
+                    sandbox_score_before=score_before,
+                    sandbox_score_after=score_before,
+                    kept=False,
+                    reason=synth_reason or "synthesizer_error",
+                ),
+            )
+            consecutive_regressions += 1
+        else:
+            score_after = _score_files(synth.proposed_files, cfg)
+            reason: IterationReason
+            if score_after > score_before:
+                kept = True
+                reason = "score_improved"
+                consecutive_regressions = 0
+                current = dict(synth.proposed_files)
+            elif score_after < score_before:
+                kept = False
+                reason = "score_regressed"
+                consecutive_regressions += 1
+            else:
+                kept = False
+                reason = "score_plateau"
+                consecutive_regressions = 0
+            iterations.append(
+                Iteration(
+                    index=i,
+                    cited_node_ids=synth.cited_node_ids,
+                    rationale=synth.rationale,
+                    proposed_files=synth.proposed_files,
+                    sandbox_score_before=score_before,
+                    sandbox_score_after=score_after,
+                    kept=kept,
+                    reason=reason,
+                ),
+            )
+
+        if checkpoint_dir is not None:
+            try:
+                save_checkpoint(
+                    RunResult(
+                        run_id=run_id,
+                        spec=spec,
+                        started_at=started_at,
+                        ended_at=datetime.now(UTC).isoformat(timespec="seconds"),
+                        final_score=iterations[-1].sandbox_score_after,
+                        final_files=current,
+                        iterations=tuple(iterations),
+                        terminated_by="in_progress",
+                    ),
+                    checkpoint_dir,
+                )
+            except OSError as e:
+                _log.warning("checkpoint write failed: %s", e)
+
+        if consecutive_regressions >= _STUCK_THRESHOLD:
+            terminated_by = "stuck"
+            break
+
+    final_score = _score_files(current, cfg)
+    result = RunResult(
+        run_id=run_id,
+        spec=spec,
+        started_at=started_at,
+        ended_at=datetime.now(UTC).isoformat(timespec="seconds"),
+        final_score=final_score,
+        final_files=current,
+        iterations=tuple(iterations),
+        terminated_by=terminated_by,
+    )
+    if checkpoint_dir is not None:
+        try:
+            save_checkpoint(result, checkpoint_dir)
+        except OSError as e:
+            _log.warning("final checkpoint write failed: %s", e)
+    return result

codeforge/ralph/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+TerminationReason = Literal["target_hit", "max_iters", "stuck", "in_progress"]
+IterationReason = Literal[
+    "score_improved",
+    "score_regressed",
+    "score_plateau",
+    "target_hit",
+    "sandbox_error",
+    "synthesizer_error",
+]
+
+
+class LoopConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    max_iters: int = Field(default=5, gt=0, le=100)
+    target_score: float = Field(default=0.95, gt=0.0, le=2.0)
+    tools: tuple[str, ...] = ("ruff", "imports")
+    timeout_per_tool: float = 60.0
+    top_k_citations: int = Field(default=5, gt=0, le=50)
+
+
+class SynthesisResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    proposed_files: dict[str, str]
+    rationale: str
+    cited_node_ids: tuple[str, ...]
+
+
+class Iteration(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    index: int
+    cited_node_ids: tuple[str, ...]
+    rationale: str
+    proposed_files: dict[str, str]
+    sandbox_score_before: float
+    sandbox_score_after: float
+    kept: bool
+    reason: IterationReason
+
+
+class RunResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    run_id: str
+    spec: str
+    started_at: str
+    ended_at: str
+    final_score: float
+    final_files: dict[str, str]
+    iterations: tuple[Iteration, ...]
+    terminated_by: TerminationReason

codeforge/ralph/planner.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Subtask:
+    """A single step in a decomposed task plan."""
+
+    description: str
+    target_files: tuple[str, ...]
+    acceptance: str
+    tools: tuple[str, ...]
+
+
+class Planner:
+    """Decomposes a task spec into ordered subtasks.
+
+    The planner analyzes the spec and initial files to determine:
+    1. Which files need to be created/modified
+    2. In what order (dependency-based)
+    3. Which tools are relevant for scoring each subtask
+
+    This enables incremental scoring: implement core.py with ruff+mypy only,
+    then add tests with ruff+mypy+pytest.
+    """
+
+    def plan(
+        self,
+        spec: str,
+        initial_files: dict[str, str],
+    ) -> list[Subtask]:
+        """Decompose spec into ordered subtasks.
+
+        Strategy:
+        1. Identify empty files (need implementation)
+        2. Identify test files (depends on implementation files)
+        3. Order: implementation files first, then test files
+        4. Implementation files get ruff+mypy+imports tools
+        5. Test files get ruff+mypy+imports+pytest tools
+        """
+        empty_files = [f for f, content in initial_files.items() if not content.strip()]
+
+        # Separate test files from implementation files
+        test_files = [f for f in empty_files if f.startswith("test_")]
+        impl_files = [f for f in empty_files if not f.startswith("test_")]
+
+        subtasks: list[Subtask] = []
+
+        # Phase 1: Implement empty non-test files
+        for f in impl_files:
+            subtasks.append(
+                Subtask(
+                    description=f"Implement {f}",
+                    target_files=(f,),
+                    acceptance=f"{f} passes ruff, mypy --strict, and imports check",
+                    tools=("ruff", "imports", "mypy"),
+                )
+            )
+
+        # Phase 2: Write tests
+        for f in test_files:
+            subtasks.append(
+                Subtask(
+                    description=f"Write tests in {f}",
+                    target_files=(f,),
+                    acceptance=f"{f} passes all tools including pytest",
+                    tools=("ruff", "imports", "mypy", "pytest"),
+                )
+            )
+
+        # If no subtasks were generated, create one for everything
+        if not subtasks:
+            all_files = tuple(initial_files.keys())
+            has_tests = any(f.startswith("test_") for f in initial_files)
+            tools = (
+                ("ruff", "imports", "mypy", "pytest")
+                if has_tests
+                else ("ruff", "imports", "mypy")
+            )
+            subtasks.append(
+                Subtask(
+                    description="Implement the complete task",
+                    target_files=all_files,
+                    acceptance="All tools pass",
+                    tools=tools,
+                )
+            )
+
+        return subtasks

codeforge/ralph/synthesizer.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Protocol
+
+from codeforge.ralph.models import SynthesisResult
+
+if TYPE_CHECKING:
+    from codeforge.kb.models import SearchResult
+
+_FENCED_PY_RE = re.compile(r"```python\n(.*?)\n```", re.DOTALL)
+
+# Matches '# filename: foo.py' or '## foo.py' immediately before a fenced block
+_FILENAME_HEADER_RE = re.compile(
+    r"(?:^#{1,2}\s+(?:filename:\s*)?(\S+\.py)\s*$)",
+    re.MULTILINE,
+)
+
+
+class Synthesizer(Protocol):
+    """Abstract synthesizer interface for Ralph loop."""
+
+    def synthesize(
+        self,
+        *,
+        spec: str,
+        current_files: Mapping[str, str],
+        citations: Sequence[SearchResult],
+        iteration: int,
+    ) -> SynthesisResult: ...
+
+
+class StubSynthesizer:
+    """Deterministic, KB-grounded stub. No LLM. Used in tests and as default."""
+
+    def synthesize(
+        self,
+        *,
+        spec: str,
+        current_files: Mapping[str, str],
+        citations: Sequence[SearchResult],
+        iteration: int,
+    ) -> SynthesisResult:
+        del spec, iteration  # inputs retained for protocol; stub ignores
+
+        if not citations:
+            return SynthesisResult(
+                proposed_files=dict(current_files),
+                rationale="no_citations",
+                cited_node_ids=(),
+            )
+
+        top = citations[0]
+        main = current_files.get("main.py", "")
+        blocks = _FENCED_PY_RE.findall(top.section_body)
+
+        wrapper_name = f"_from_{top.skill_name.replace('-', '_')}_{top.rank}"
+        if blocks and wrapper_name not in main:
+            body = "\n".join(
+                f"    {ln}" if ln.strip() else "" for ln in blocks[0].splitlines()
+            )
+            snippet = f"\n\ndef {wrapper_name}() -> None:\n{body}\n"
+            new_main = main + snippet
+            rationale = (
+                f"Applied suggestion from "
+                f"{top.skill_name}/{'/'.join(top.section_path)}"
+            )
+        elif blocks:
+            new_main = main
+            rationale = (
+                f"Already applied "
+                f"{top.skill_name}/{'/'.join(top.section_path)}"
+            )
+        else:
+            comment = f"# consulted: {top.skill_name}/{'/'.join(top.section_path)}\n"
+            new_main = main + (comment if comment not in main else "")
+            rationale = (
+                f"Consulted "
+                f"{top.skill_name}/{'/'.join(top.section_path)} (no code block)"
+            )
+
+        new_files = {**current_files, "main.py": new_main}
+        return SynthesisResult(
+            proposed_files=new_files,
+            rationale=rationale,
+            cited_node_ids=(top.node_id,),
+        )
+
+
+class LLMSynthesizer:
+    """Calls any LLM to produce improved code given spec + current files + citations.
+
+    Provider-agnostic: works with Ollama, OpenAI, Anthropic, or any
+    OpenAI-compatible API. Set *provider* to choose the backend:
+
+    - ``"openai"`` — OpenAI / OpenAI-compatible (default). Works with Ollama,
+      LM Studio, vLLM, Together, Groq, etc. Set *base_url* for local models.
+    - ``"anthropic"`` — Anthropic Claude API.
+    - ``"ollama"`` — Shortcut for Ollama (sets base_url to localhost:11434).
+
+    Examples::
+
+        # Ollama (local, no API key needed)
+        LLMSynthesizer(provider="ollama", model="llama3")
+
+        # OpenAI
+        LLMSynthesizer(provider="openai", model="gpt-4o")
+
+        # Anthropic
+        LLMSynthesizer(provider="anthropic", model="claude-sonnet-4-20250514")
+
+        # Any OpenAI-compatible endpoint (vLLM, LM Studio, Together, etc.)
+        LLMSynthesizer(
+            provider="openai",
+            base_url="http://localhost:8000/v1",
+            model="my-local-model",
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        provider: str = "openai",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+    ) -> None:
+        self._provider: str = provider.lower()
+        self._max_tokens: int = max_tokens
+
+        if self._provider == "ollama":
+            self._base_url = base_url or "http://localhost:11434/v1"
+            self._api_key = api_key or "ollama"  # Ollama ignores this
+            self._model = model or "llama3"
+        elif self._provider == "anthropic":
+            self._base_url = base_url or "https://api.anthropic.com"
+            self._api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+            self._model = model or "claude-sonnet-4-20250514"
+        else:  # openai or any compatible
+            self._base_url = base_url or "https://api.openai.com/v1"
+            self._api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
+            self._model = model or "gpt-4o"
+
+    # ------------------------------------------------------------------
+    # Public API (satisfies Synthesizer protocol)
+    # ------------------------------------------------------------------
+
+    def synthesize(
+        self,
+        *,
+        spec: str,
+        current_files: Mapping[str, str],
+        citations: Sequence[SearchResult],
+        iteration: int,
+    ) -> SynthesisResult:
+        """Build prompt, call LLM, parse response into *SynthesisResult*."""
+        prompt = self._build_prompt(spec, current_files, citations, iteration)
+        response_text = self._call_llm(prompt)
+        result = self._parse_response(response_text, citations)
+
+        # If no code blocks were parsed, fall back to current files unchanged.
+        if not result.proposed_files:
+            return SynthesisResult(
+                proposed_files=dict(current_files),
+                rationale=result.rationale or "No parseable code blocks in LLM response",
+                cited_node_ids=result.cited_node_ids,
+            )
+        return result
+
+    # ------------------------------------------------------------------
+    # Prompt construction
+    # ------------------------------------------------------------------
+
+    def _build_prompt(
+        self,
+        spec: str,
+        current_files: Mapping[str, str],
+        citations: Sequence[SearchResult],
+        iteration: int,
+    ) -> str:
+        """Build the synthesis prompt with spec, files, citations, and iteration."""
+        parts: list[str] = [
+            "You are a Python code synthesis assistant.",
+            f"Iteration: {iteration}",
+            "",
+            "## Task Specification",
+            spec,
+        ]
+
+        if current_files:
+            parts.append("")
+            parts.append("## Current Files")
+            for fname, content in current_files.items():
+                parts.append(f"\n### {fname}")
+                parts.append(f"```python\n{content}\n```")
+
+        if citations:
+            parts.append("")
+            parts.append("## Skill Corpus Citations")
+            for cit in citations:
+                parts.append(
+                    f"\n### {cit.skill_name} / {'/'.join(cit.section_path)}"
+                    f" (score={cit.score:.1f})"
+                )
+                parts.append(cit.section_body)
+
+        parts.append("")
+        parts.append("## Instructions")
+        parts.append(
+            "Produce improved Python files. For EACH file, emit a header "
+            "`# filename: <name>.py` followed by a fenced python code block. "
+            "After all files, write a short rationale explaining your changes."
+        )
+
+        return "\n".join(parts)
+
+    # ------------------------------------------------------------------
+    # LLM API call (provider-agnostic)
+    # ------------------------------------------------------------------
+
+    def _call_llm(self, prompt: str) -> str:
+        """Call the configured LLM provider.
+
+        Supports three backends:
+        - **openai / ollama**: OpenAI-compatible ``/chat/completions`` endpoint.
+          Works with Ollama, LM Studio, vLLM, Together, Groq, OpenAI, etc.
+        - **anthropic**: Anthropic ``/v1/messages`` endpoint.
+        """
+        if self._provider == "anthropic":
+            return self._call_anthropic(prompt)
+        return self._call_openai_compatible(prompt)
+
+    def _call_openai_compatible(self, prompt: str) -> str:
+        """OpenAI-compatible API (works with Ollama, LM Studio, vLLM, etc.)."""
+        import httpx
+
+        url = f"{self._base_url.rstrip('/')}/chat/completions"
+        headers: dict[str, str] = {"content-type": "application/json"}
+        if self._api_key and self._api_key != "ollama":
+            headers["Authorization"] = f"Bearer {self._api_key}"
+
+        resp = httpx.post(
+            url,
+            headers=headers,
+            json={
+                "model": self._model,
+                "max_tokens": self._max_tokens,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+            timeout=120.0,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return str(data["choices"][0]["message"]["content"])
+
+    def _call_anthropic(self, prompt: str) -> str:
+        """Anthropic Claude API."""
+        if not self._api_key:
+            msg = (
+                "ANTHROPIC_API_KEY not set. For local models, use "
+                "provider='ollama' or provider='openai' with base_url."
+            )
+            raise ValueError(msg)
+
+        try:
+            import anthropic
+
+            client = anthropic.Anthropic(api_key=self._api_key)
+            message = client.messages.create(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            block = message.content[0]
+            return str(getattr(block, "text", ""))
+        except ImportError:
+            import httpx
+
+            resp = httpx.post(
+                f"{self._base_url.rstrip('/')}/v1/messages",
+                headers={
+                    "x-api-key": self._api_key,
+                    "anthropic-version": "2023-06-01",
+                    "content-type": "application/json",
+                },
+                json={
+                    "model": self._model,
+                    "max_tokens": self._max_tokens,
+                    "messages": [{"role": "user", "content": prompt}],
+                },
+                timeout=120.0,
+            )
+            resp.raise_for_status()
+            data: dict[str, object] = resp.json()
+            content = data["content"]
+            assert isinstance(content, list)
+            first = content[0]
+            assert isinstance(first, dict)
+            return str(first["text"])
+
+    # ------------------------------------------------------------------
+    # Response parsing
+    # ------------------------------------------------------------------
+
+    def _parse_response(
+        self,
+        text: str,
+        citations: Sequence[SearchResult],
+    ) -> SynthesisResult:
+        """Parse LLM response: extract fenced code blocks with filename headers."""
+        proposed_files: dict[str, str] = {}
+
+        # Strategy: find all filename headers and pair each with the next
+        # fenced python block.
+        header_positions: list[tuple[int, str]] = [
+            (m.start(), m.group(1))
+            for m in _FILENAME_HEADER_RE.finditer(text)
+        ]
+
+        code_blocks: list[tuple[int, str]] = [
+            (m.start(), m.group(1))
+            for m in _FENCED_PY_RE.finditer(text)
+        ]
+
+        if header_positions and code_blocks:
+            for hdr_pos, filename in header_positions:
+                # Find the first code block that follows this header
+                for blk_pos, code in code_blocks:
+                    if blk_pos > hdr_pos:
+                        proposed_files[filename] = code
+                        break
+
+        # Extract rationale from non-code, non-header text
+        rationale_text = text
+        for _, code in code_blocks:
+            rationale_text = rationale_text.replace(f"```python\n{code}\n```", "")
+        for m in _FILENAME_HEADER_RE.finditer(rationale_text):
+            rationale_text = rationale_text.replace(m.group(0), "")
+        rationale = rationale_text.strip()
+        # Collapse to a single line for storage
+        rationale = " ".join(rationale.split())
+
+        if not proposed_files:
+            rationale = rationale or "No parseable code blocks in LLM response"
+
+        cited_node_ids = tuple(c.node_id for c in citations)
+
+        return SynthesisResult(
+            proposed_files=proposed_files,
+            rationale=rationale,
+            cited_node_ids=cited_node_ids,
+        )

codeforge/sandbox/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from codeforge.sandbox.models import (
+    ImportReport,
+    ParsedResult,
+    SandboxResult,
+    ToolResult,
+)
+from codeforge.sandbox.sandbox import run_sandbox
+
+__all__ = [
+    "ImportReport",
+    "ParsedResult",
+    "SandboxResult",
+    "ToolResult",
+    "run_sandbox",
+]

codeforge/sandbox/imports.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import ast
+import importlib.util
+import logging
+from typing import TYPE_CHECKING
+
+from codeforge.sandbox.models import ImportReport
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_log = logging.getLogger(__name__)
+
+
+def _top_level(name: str) -> str:
+    return name.split(".", maxsplit=1)[0]
+
+
+def _extract_imports(tree: ast.AST) -> set[str]:
+    out: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                out.add(_top_level(alias.name))
+        elif isinstance(node, ast.ImportFrom):
+            if node.level != 0 or node.module is None:
+                continue
+            out.add(_top_level(node.module))
+    return out
+
+
+def _local_modules(project_dir: Path) -> set[str]:
+    local: set[str] = set()
+    for py in project_dir.rglob("*.py"):
+        if py.name == "__init__.py":
+            local.add(py.parent.name)
+        else:
+            local.add(py.stem)
+    return local
+
+
+def scan_imports(project_dir: Path) -> ImportReport:
+    by_file: dict[str, tuple[str, ...]] = {}
+    all_pkgs: set[str] = set()
+    total = 0
+
+    for py in sorted(project_dir.rglob("*.py")):
+        try:
+            tree = ast.parse(py.read_text(encoding="utf-8"))
+        except (SyntaxError, UnicodeDecodeError) as e:
+            _log.warning("imports: parse error %s: %s", py, e)
+            by_file[str(py.relative_to(project_dir))] = ("__parse_error__",)
+            continue
+        pkgs = _extract_imports(tree)
+        total += len(pkgs)
+        by_file[str(py.relative_to(project_dir))] = tuple(sorted(pkgs))
+        all_pkgs.update(pkgs)
+
+    local = _local_modules(project_dir)
+    unresolved = tuple(
+        sorted(
+            p for p in all_pkgs
+            if p not in local and importlib.util.find_spec(p) is None
+        )
+    )
+    return ImportReport(total=total, unresolved=unresolved, by_file=by_file)

codeforge/sandbox/metric.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codeforge.sandbox.models import SandboxResult
+
+
+def composite_score(
+    result: SandboxResult,
+    *,
+    tools: tuple[str, ...] | None = None,
+) -> float:
+    """Compute composite score from sandbox results.
+
+    When tools is None, score all tools that were run (full-project scoring).
+    When tools is provided, score only those tools (subtask scoring).
+    This lets the planner score 'implement core.py' with only ruff+mypy+imports,
+    without pytest destroying the score because tests aren't written yet.
+    """
+    parsed = result.parsed
+    if tools is not None:
+        parsed = {k: v for k, v in parsed.items() if k in tools}
+    if not parsed:
+        return 0.0
+
+    # Penalty-only scoring (no double-counting with pass_rate)
+    imports_penalty = min(1.0, len(result.imports.unresolved) * 0.1)
+
+    ruff = parsed.get("ruff")
+    mypy = parsed.get("mypy")
+    pytest_result = parsed.get("pytest")
+
+    ruff_penalty = min(ruff.count, 20) / 40 if ruff else 0.0
+    mypy_penalty = min(mypy.count, 20) / 40 if mypy else 0.0
+    pytest_penalty = 0.5 if pytest_result and not pytest_result.ok else 0.0
+
+    # Start at 1.0, subtract penalties. No pass_rate to avoid double-counting.
+    raw = 1.0 - imports_penalty - ruff_penalty - mypy_penalty - pytest_penalty
+    return max(0.0, min(1.0, raw))

codeforge/sandbox/models.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ToolResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    name: str
+    argv: tuple[str, ...]
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_ms: int
+    timed_out: bool
+
+
+class ParsedResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    ok: bool
+    count: int
+    details: dict[str, Any]
+
+
+class ImportReport(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    total: int
+    unresolved: tuple[str, ...]
+    by_file: dict[str, tuple[str, ...]]
+
+
+class SandboxResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    project_dir: str
+    tools_run: tuple[str, ...]
+    tool_results: dict[str, ToolResult]
+    parsed: dict[str, ParsedResult]
+    imports: ImportReport
+    composite_score: float
+    generated_at: str

codeforge/sandbox/runner.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from typing import TYPE_CHECKING
+
+from codeforge.sandbox.models import ToolResult
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def run_tool(
+    name: str,
+    argv: list[str],
+    *,
+    cwd: Path,
+    timeout: float = 60.0,
+    env_overrides: dict[str, str] | None = None,
+) -> ToolResult:
+    t0 = time.monotonic()
+    timed_out = False
+    stdout = ""
+    stderr = ""
+    exit_code = -1
+
+    try:
+        proc = subprocess.run(
+            argv,
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+            env=None if env_overrides is None else {**_os_env(), **env_overrides},
+        )
+        exit_code = proc.returncode
+        stdout = proc.stdout
+        stderr = proc.stderr
+    except subprocess.TimeoutExpired as e:
+        timed_out = True
+        stdout = e.stdout.decode() if isinstance(e.stdout, bytes) else (e.stdout or "")
+        stderr = e.stderr.decode() if isinstance(e.stderr, bytes) else (e.stderr or "")
+    except (FileNotFoundError, OSError) as e:
+        stderr = f"binary not found: {e}"
+
+    duration_ms = int((time.monotonic() - t0) * 1000)
+    return ToolResult(
+        name=name,
+        argv=tuple(argv),
+        exit_code=exit_code,
+        stdout=stdout,
+        stderr=stderr,
+        duration_ms=duration_ms,
+        timed_out=timed_out,
+    )
+
+
+def _os_env() -> dict[str, str]:
+    return dict(os.environ)

codeforge/sandbox/sandbox.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from codeforge.sandbox.imports import scan_imports
+from codeforge.sandbox.metric import composite_score
+from codeforge.sandbox.models import (
+    ImportReport,
+    ParsedResult,
+    SandboxResult,
+    ToolResult,
+)
+from codeforge.sandbox.runner import run_tool
+from codeforge.sandbox.tools import (
+    DEFAULT_TOOLS,
+    argv_for,
+    is_available,
+    parse,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+def run_sandbox(
+    *,
+    project_dir: Path | None = None,
+    files: dict[str, str] | None = None,
+    tools: Iterable[str] = DEFAULT_TOOLS,
+    timeout_per_tool: float = 60.0,
+) -> SandboxResult:
+    if (project_dir is None) == (files is None):
+        msg = "exactly one of project_dir / files must be set"
+        raise ValueError(msg)
+
+    tmp_root: Path | None = None
+    try:
+        if files is not None:
+            tmp_root = Path(tempfile.mkdtemp(prefix="codeforge_sandbox_"))
+            tmp_root_resolved = tmp_root.resolve()
+            for name, content in files.items():
+                target = (tmp_root / name).resolve()
+                if not target.is_relative_to(tmp_root_resolved):
+                    msg = f"path escapes sandbox root: {name!r}"
+                    raise ValueError(msg)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(content, encoding="utf-8")
+            project_dir = tmp_root
+
+        assert project_dir is not None
+        tool_list = tuple(tools)
+        tool_results: dict[str, ToolResult] = {}
+        parsed_results: dict[str, ParsedResult] = {}
+        imports_report: ImportReport | None = None
+
+        for name in tool_list:
+            if name == "imports":
+                imports_report = scan_imports(project_dir)
+                parsed_results[name] = ParsedResult(
+                    ok=len(imports_report.unresolved) == 0,
+                    count=len(imports_report.unresolved),
+                    details={"unresolved": list(imports_report.unresolved)},
+                )
+                continue
+            if not is_available(name):
+                tool_results[name] = ToolResult(
+                    name=name, argv=(name,), exit_code=-1,
+                    stdout="", stderr="binary not found",
+                    duration_ms=0, timed_out=False,
+                )
+                parsed_results[name] = ParsedResult(
+                    ok=False, count=0, details={"unavailable": True},
+                )
+                continue
+            argv = argv_for(name, project_dir)
+            tr = run_tool(name, argv, cwd=project_dir, timeout=timeout_per_tool)
+            tool_results[name] = tr
+            parsed_results[name] = parse(name, tr)
+
+        if imports_report is None:
+            imports_report = ImportReport(total=0, unresolved=(), by_file={})
+
+        result = SandboxResult(
+            project_dir=str(project_dir),
+            tools_run=tool_list,
+            tool_results=tool_results,
+            parsed=parsed_results,
+            imports=imports_report,
+            composite_score=0.0,
+            generated_at=datetime.now(UTC).isoformat(timespec="seconds"),
+        )
+        score = composite_score(result)
+        return result.model_copy(update={"composite_score": score})
+    finally:
+        if tmp_root is not None and tmp_root.exists():
+            shutil.rmtree(tmp_root, ignore_errors=True)

codeforge/sandbox/tools.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from typing import TYPE_CHECKING
+
+from codeforge.sandbox.models import ParsedResult, ToolResult
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+DEFAULT_TOOLS: tuple[str, ...] = ("ruff", "mypy", "pytest", "imports")
+
+_MYPY_ERROR_RE = re.compile(r"Found (\d+) errors?")
+
+
+def argv_for(name: str, project_dir: Path) -> list[str]:
+    """Return the argv for running a tool. Runner sets cwd=project_dir."""
+    del project_dir
+    if name == "ruff":
+        return ["ruff", "check", "--output-format", "json", "."]
+    if name == "mypy":
+        return ["mypy", "--no-incremental", "--strict", "."]
+    if name == "pytest":
+        return ["pytest", "-q", "--tb=line", "--no-header"]
+    if name == "pip-audit":
+        return ["pip-audit", "--format", "json"]
+    msg = f"unknown tool: {name}"
+    raise ValueError(msg)
+
+
+def parse(name: str, tool_result: ToolResult) -> ParsedResult:
+    if name == "ruff":
+        return _parse_ruff(tool_result)
+    if name == "mypy":
+        return _parse_mypy(tool_result)
+    if name == "pytest":
+        return _parse_pytest(tool_result)
+    if name == "pip-audit":
+        return _parse_pip_audit(tool_result)
+    return ParsedResult(ok=tool_result.exit_code == 0, count=0, details={})
+
+
+def _parse_ruff(tr: ToolResult) -> ParsedResult:
+    try:
+        items = json.loads(tr.stdout or "[]")
+    except json.JSONDecodeError:
+        return ParsedResult(ok=False, count=0, details={"parse_error": tr.stdout[:500]})
+    count = len(items) if isinstance(items, list) else 0
+    return ParsedResult(
+        ok=count == 0 and tr.exit_code == 0,
+        count=count,
+        details={"violations": items[:20]},
+    )
+
+
+def _parse_mypy(tr: ToolResult) -> ParsedResult:
+    if tr.exit_code == 0 and "Success" in tr.stdout:
+        return ParsedResult(ok=True, count=0, details={})
+    m = _MYPY_ERROR_RE.search(tr.stdout)
+    count = int(m.group(1)) if m else 0
+    return ParsedResult(ok=False, count=count, details={"tail": tr.stdout[-500:]})
+
+
+def _parse_pytest(tr: ToolResult) -> ParsedResult:
+    ok = tr.exit_code == 0
+    return ParsedResult(ok=ok, count=0 if ok else 1, details={"tail": tr.stdout[-500:]})
+
+
+def _parse_pip_audit(tr: ToolResult) -> ParsedResult:
+    if tr.exit_code == 0:
+        return ParsedResult(ok=True, count=0, details={})
+    try:
+        data = json.loads(tr.stdout or "{}")
+    except json.JSONDecodeError:
+        data = {}
+    count = len(data.get("vulnerabilities", []))
+    return ParsedResult(ok=count == 0, count=count, details={"tail": tr.stdout[-500:]})
+
+
+def is_available(name: str) -> bool:
+    if name == "imports":
+        return True
+    return shutil.which(name) is not None

codeforge/scraper/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from codeforge.scraper.discovery import SourceRoot, walk_sources
+from codeforge.scraper.parser import ParsedSkill, ParseError, parse_skill
+from codeforge.scraper.pipeline import ScrapeResult, run_scraper, scrape_single_skill
+
+__all__ = [
+    "ParseError",
+    "ParsedSkill",
+    "ScrapeResult",
+    "SourceRoot",
+    "parse_skill",
+    "run_scraper",
+    "scrape_single_skill",
+    "walk_sources",
+]

codeforge/scraper/chunker.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from markdown_it import MarkdownIt
+from markdown_it.token import Token
+from pydantic import BaseModel, ConfigDict
+
+MIN_CHUNK_CHARS = 80
+MAX_HEADING_LEVEL = 3
+
+_md = MarkdownIt()
+
+
+class SectionChunk(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    section_path: tuple[str, ...]
+    section_body: str
+
+
+def _segment_tokens(
+    tokens: list[Token],
+) -> list[tuple[int, str, list[str]]]:
+    """Walk token stream, returning heading-delimited segments.
+
+    Each segment is (heading_level, heading_text, body_texts).
+    Level 0 is a sentinel for content before the first H1-H3.
+    """
+    segments: list[tuple[int, str, list[str]]] = []
+    current: tuple[int, str, list[str]] | None = None
+
+    for i, tok in enumerate(tokens):
+        if tok.type == "heading_open":
+            level = int(tok.tag[1])  # "h2" -> 2
+            heading_text = tokens[i + 1].content.strip()
+            if level <= MAX_HEADING_LEVEL:
+                if current is not None:
+                    segments.append(current)
+                current = (level, heading_text, [])
+            else:
+                if current is None:
+                    current = (0, "", [])
+                current[2].append(heading_text)
+        elif tok.type.endswith("_open"):
+            continue
+        elif tok.type == "inline":
+            if current is None:
+                current = (0, "", [])
+            current[2].append(tok.content)
+
+    if current is not None:
+        segments.append(current)
+    return segments
+
+
+def chunk_body(body: str) -> list[SectionChunk]:
+    """Split markdown body into section chunks by H1-H3 headings."""
+    tokens = _md.parse(body)
+    segments = _segment_tokens(tokens)
+
+    if not segments:
+        text = body.strip()
+        if text:
+            return [SectionChunk(section_path=(), section_body=text)]
+        return []
+
+    stack: list[str] = []
+    chunks: list[SectionChunk] = []
+    for level, title, body_parts in segments:
+        if level == 0:
+            chunks.append(
+                SectionChunk(
+                    section_path=(),
+                    section_body="\n\n".join(body_parts).strip(),
+                )
+            )
+            continue
+        while len(stack) >= level:
+            stack.pop()
+        stack.append(title)
+        chunks.append(
+            SectionChunk(
+                section_path=tuple(stack),
+                section_body="\n\n".join(body_parts).strip(),
+            )
+        )
+
+    return _merge_small(chunks)
+
+
+def _merge_small(chunks: list[SectionChunk]) -> list[SectionChunk]:
+    """Merge chunks smaller than MIN_CHUNK_CHARS into their successor."""
+    if not chunks:
+        return chunks
+    merged: list[SectionChunk] = []
+    carry: str = ""
+    for c in chunks:
+        body = (carry + "\n\n" + c.section_body).strip() if carry else c.section_body
+        if len(body) < MIN_CHUNK_CHARS and c is not chunks[-1]:
+            carry = body
+            continue
+        merged.append(SectionChunk(section_path=c.section_path, section_body=body))
+        carry = ""
+    if carry and merged:
+        last = merged[-1]
+        merged[-1] = SectionChunk(
+            section_path=last.section_path,
+            section_body=(last.section_body + "\n\n" + carry).strip(),
+        )
+    return merged

codeforge/scraper/discovery.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import glob as glob_mod
+import logging
+import os
+from collections.abc import Iterator
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+_log = logging.getLogger(__name__)
+
+
+class SourceRoot(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    label: str
+    glob: str
+
+
+def walk_sources(sources: list[SourceRoot]) -> Iterator[tuple[Path, SourceRoot]]:
+    """Yield (path, source_root) for every readable SKILL.md matched by a glob."""
+    for root in sources:
+        pattern = os.path.expanduser(root.glob)
+        for match in glob_mod.glob(pattern, recursive=True):
+            path = Path(match)
+            if not path.is_file():
+                _log.warning("discovery: skipping non-file %s", path)
+                continue
+            try:
+                path.stat()
+            except OSError as e:
+                _log.warning("discovery: unreadable %s: %s", path, e)
+                continue
+            yield path, root

codeforge/scraper/parser.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import frontmatter  # type: ignore[import-untyped]
+import yaml
+from pydantic import BaseModel, ConfigDict
+
+
+class ParsedSkill(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    frontmatter: dict[str, object]
+    body: str
+    mtime: float
+
+
+class ParseError(Exception):
+    """Raised when a SKILL.md cannot be parsed."""
+
+
+def parse_skill(path: Path) -> ParsedSkill:
+    """Parse a SKILL.md file: extract YAML frontmatter and markdown body."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise ParseError(f"unreadable: {path}: {e}") from e
+    try:
+        post = frontmatter.loads(raw)
+    except yaml.YAMLError as e:
+        raise ParseError(f"malformed yaml in {path}: {e}") from e
+    mtime = path.stat().st_mtime
+    return ParsedSkill(frontmatter=dict(post.metadata), body=post.content, mtime=mtime)

codeforge/scraper/pipeline.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from codeforge.scraper.chunker import chunk_body
+from codeforge.scraper.discovery import SourceRoot, walk_sources
+from codeforge.scraper.parser import ParseError, parse_skill
+from codeforge.scraper.tagger import infer_tags
+from codeforge.scraper.writer import write_corpus, write_manifest
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ScrapeResult:
+    scraped_files: int
+    skipped_files: int
+    total_nodes: int
+    errors: list[dict[str, str]]
+    corpus_path: Path
+    manifest_path: Path
+
+
+def _node_id(source_path: str, section_path: tuple[str, ...]) -> str:
+    raw = source_path + "#" + "/".join(section_path)
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def _body_hash(body: str) -> str:
+    return hashlib.sha256(body.encode()).hexdigest()
+
+
+def scrape_single_skill(path: Path) -> list[dict[str, Any]]:
+    """Scrape a single SKILL.md file and return a list of node dicts."""
+    parsed = parse_skill(path)
+    body = parsed.body.strip()
+    if not body:
+        return []
+
+    fm = parsed.frontmatter
+    name_val = fm.get("name")
+    skill_name = str(name_val) if name_val else path.parent.name
+    desc_val = fm.get("description", "")
+    skill_desc = str(desc_val) if desc_val else ""
+    type_val = fm.get("type")
+    skill_type: str | None = (
+        str(type_val) if type_val in ("flexible", "rigid") else None
+    )
+    triggers = skill_desc
+
+    raw_chunks = chunk_body(body)
+    if not raw_chunks:
+        return []
+
+    chunks = [
+        c.model_copy(update={"section_path": (skill_name,)})
+        if c.section_path == ()
+        else c
+        for c in raw_chunks
+    ]
+
+    nodes: list[dict[str, Any]] = []
+    for chunk in chunks:
+        tags = list(
+            infer_tags(
+                skill_name,
+                chunk.section_path[-1] if chunk.section_path else "",
+                chunk.section_body,
+            )
+        )
+        node: dict[str, Any] = {
+            "id": _node_id(str(path), chunk.section_path),
+            "skill_name": skill_name,
+            "skill_description": skill_desc,
+            "skill_type": skill_type,
+            "section_path": list(chunk.section_path),
+            "section_title": chunk.section_path[-1] if chunk.section_path else "",
+            "section_body": chunk.section_body,
+            "source_path": str(path),
+            "source_root": "",
+            "tags": tags,
+            "trigger_hints": triggers,
+            "mtime": parsed.mtime,
+            "body_hash": _body_hash(chunk.section_body),
+            "alias_sources": [],
+        }
+        nodes.append(node)
+    return nodes
+
+
+def _dedupe(nodes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Deduplicate nodes by (skill_name, section_path, body_hash)."""
+    index: dict[tuple[str, tuple[str, ...], str], dict[str, Any]] = {}
+    for n in nodes:
+        key = (n["skill_name"], tuple(n["section_path"]), n["body_hash"])
+        existing = index.get(key)
+        if existing is None:
+            index[key] = n
+        else:
+            aliases = list(existing.get("alias_sources", []))
+            aliases.append(n["source_path"])
+            existing["alias_sources"] = aliases
+    return list(index.values())
+
+
+def run_scraper(
+    *, sources: list[SourceRoot], output: Path
+) -> ScrapeResult:
+    """Full pipeline: discover -> parse -> chunk -> tag -> deduplicate -> write."""
+    nodes: list[dict[str, Any]] = []
+    errors: list[dict[str, str]] = []
+    scraped = 0
+    skipped = 0
+
+    for path, root in walk_sources(sources):
+        try:
+            file_nodes = scrape_single_skill(path)
+        except ParseError as e:
+            errors.append({"path": str(path), "stage": "parse", "reason": str(e)})
+            skipped += 1
+            continue
+
+        if not file_nodes:
+            skipped += 1
+            continue
+
+        for n in file_nodes:
+            n["source_root"] = root.label
+        nodes.extend(file_nodes)
+        scraped += 1
+
+    deduped = _dedupe(nodes)
+    corpus_path = write_corpus(deduped, output)
+    manifest_path = write_manifest(
+        corpus_path=corpus_path,
+        sources=[{"label": s.label, "glob": s.glob} for s in sources],
+        scraped_files=scraped,
+        skipped_files=skipped,
+        total_nodes=len(deduped),
+        errors=errors,
+    )
+
+    return ScrapeResult(
+        scraped_files=scraped,
+        skipped_files=skipped,
+        total_nodes=len(deduped),
+        errors=errors,
+        corpus_path=corpus_path,
+        manifest_path=manifest_path,
+    )

codeforge/scraper/tagger.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import re
+
+DOMAIN_RULES: list[tuple[str, list[str]]] = [
+    ("python", ["python", "pytest", "pip", "pydantic"]),
+    ("javascript", ["javascript", "typescript", "react", "next.js", "node"]),
+    ("go", ["golang", "go"]),
+    ("kotlin", ["kotlin", "gradle"]),
+    ("security", ["security", "auth", "secret", "owasp", "injection"]),
+    ("frontend", ["frontend", "ui", "ux", "tailwind", "css"]),
+    ("api", ["api", "endpoint", "rest", "graphql", "openapi"]),
+    ("backend", ["backend", "fastapi", "django", "spring"]),
+    ("data", ["pandas", "numpy", "clickhouse", "postgres", "sql"]),
+    ("mcp", ["mcp", "model context protocol"]),
+    ("devops", ["docker", "kubernetes", "ci/cd", "deploy"]),
+]
+
+PHASE_RULES: list[tuple[str, list[str]]] = [
+    ("plan", ["plan", "design", "architecture", "brainstorm"]),
+    ("build", ["build", "implement", "feature", "write"]),
+    ("test", ["test", "pytest", "coverage", "tdd"]),
+    ("review", ["review", "critic", "checklist", "audit"]),
+    ("deploy", ["deploy", "release", "ship", "publish"]),
+    ("debug", ["debug", "fix", "troubleshoot", "bug"]),
+    ("docs", ["docs", "documentation", "readme"]),
+]
+
+_TOKEN_RE = re.compile(r"[a-z0-9]+(?:\.[a-z0-9]+)*")
+
+
+def _tokenize(text: str) -> frozenset[str]:
+    """Split lowercased text into alphanumeric tokens."""
+    return frozenset(_TOKEN_RE.findall(text.lower()))
+
+
+def _matches(keyword: str, tokens: frozenset[str], joined_lower: str) -> bool:
+    if " " in keyword:
+        return keyword in joined_lower
+    return keyword in tokens
+
+
+def infer_tags(skill_name: str, section_title: str, body: str) -> list[str]:
+    """Infer domain and phase tags from skill name, section title, and body."""
+    joined_lower = " ".join(
+        p.lower() for p in (skill_name, section_title, body) if p
+    )
+    tokens = _tokenize(joined_lower)
+    tags: list[str] = []
+
+    domain = "general"
+    for name, keywords in DOMAIN_RULES:
+        if any(_matches(k, tokens, joined_lower) for k in keywords):
+            domain = name
+            break
+    tags.append(f"domain:{domain}")
+
+    for name, keywords in PHASE_RULES:
+        if any(_matches(k, tokens, joined_lower) for k in keywords):
+            tags.append(f"phase:{name}")
+
+    return tags

codeforge/scraper/writer.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+
+def write_corpus(nodes: Iterable[dict[str, Any]], out_path: Path) -> Path:
+    """Write nodes as sorted JSONL."""
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    sorted_nodes = sorted(nodes, key=lambda n: str(n["id"]))
+    with out_path.open("w", encoding="utf-8") as f:
+        for node in sorted_nodes:
+            f.write(json.dumps(node, default=str))
+            f.write("\n")
+    return out_path
+
+
+def compute_corpus_sha256(corpus_path: Path) -> str:
+    """SHA256 hex digest of the corpus file."""
+    return hashlib.sha256(corpus_path.read_bytes()).hexdigest()
+
+
+def write_manifest(
+    *,
+    corpus_path: Path,
+    sources: list[dict[str, str]],
+    scraped_files: int,
+    skipped_files: int,
+    total_nodes: int,
+    errors: list[dict[str, str]],
+) -> Path:
+    """Write a manifest JSON alongside the corpus."""
+    digest = compute_corpus_sha256(corpus_path)
+    manifest = {
+        "generated_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        "sources": sources,
+        "scraped_files": scraped_files,
+        "skipped_files": skipped_files,
+        "total_nodes": total_nodes,
+        "errors": errors,
+        "corpus_sha256": digest,
+    }
+    manifest_path = corpus_path.with_suffix(".manifest.json")
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(
+        json.dumps(manifest, indent=2), encoding="utf-8"
+    )
+    return manifest_path

codeforge/shaping.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import re
+
+# Match explicit citation comments: # cited: skill-name or # ref: skill-name
+_CITATION_RE = re.compile(r"#\s*(?:cited|ref|source|from):\s*(\S+)", re.IGNORECASE)
+
+
+def citation_shaping_bonus(
+    *,
+    submit_files: dict[str, str],
+    prior_citations: list[dict[str, object]],
+    prior_cluster_hits: list[str],
+) -> float:
+    """Retroactive shaping bonus for prior queries whose cited skills appear in submitted code.
+
+    +0.01 per cited skill name found as an explicit citation comment in the code,
+    max 0.05.  Only fires on submit with reward > 0.  See SYSTEM_DESIGN §4.8.4.
+
+    Uses explicit comment matching (``# cited: skill-name``) instead of substring
+    matching to prevent common-word skill names from trivially matching any code.
+    """
+    if not prior_citations:
+        return 0.0
+
+    cited_skills: set[str] = set()
+    for c in prior_citations:
+        sn = c.get("skill_name")
+        if isinstance(sn, str):
+            cited_skills.add(sn.lower())
+
+    code_text = "\n".join(submit_files.values())
+    code_citations = {m.group(1).lower() for m in _CITATION_RE.finditer(code_text)}
+
+    overlap = len(cited_skills & code_citations)
+    return min(overlap * 0.01, 0.05)

codeforge/tasks.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Task:
+    task_id: str
+    task_level: str
+    brief: str
+    initial_files: dict[str, str]
+    target_score: float
+    max_budget: int
+    tools: tuple[str, ...]
+    hidden_tests: dict[str, str] = ()  # type: ignore[assignment]
+    """Hidden correctness tests injected by the environment during grading.
+
+    The agent never sees these. They are written into the sandbox temp dir
+    alongside the agent's submitted files so pytest runs them automatically.
+    This prevents "clean garbage" exploits where syntactically valid but
+    semantically wrong code scores perfectly.
+    """
+
+
+# -- Hidden test suites (agent never sees these) ----------------------------
+
+_HIDDEN_EASY = {
+    "test_hidden_greet.py": (
+        "from __future__ import annotations\n"
+        "from main import greet\n\n"
+        "def test_greet_alice() -> None:\n"
+        '    assert greet("Alice") == "Hello, Alice!"\n\n'
+        "def test_greet_bob() -> None:\n"
+        '    assert greet("Bob") == "Hello, Bob!"\n\n'
+        "def test_greet_empty() -> None:\n"
+        '    assert greet("") == "Hello, !"\n'
+    ),
+}
+
+_HIDDEN_MEDIUM = {
+    "test_hidden_greet.py": (
+        "from __future__ import annotations\n"
+        "import pytest\n"
+        "from main import greet\n\n"
+        "def test_greet_alice() -> None:\n"
+        '    assert greet("Alice") == "Hello, Alice!"\n\n'
+        "def test_greet_none_raises() -> None:\n"
+        "    with pytest.raises(ValueError):\n"
+        "        greet(None)  # type: ignore[arg-type]\n\n"
+        "def test_greet_returns_str() -> None:\n"
+        '    assert isinstance(greet("X"), str)\n'
+    ),
+}
+
+_HIDDEN_HARD = {
+    "test_hidden_core.py": (
+        "from __future__ import annotations\n"
+        "import pytest\n"
+        "from core import greet\n\n"
+        "def test_greet_alice() -> None:\n"
+        '    assert greet("Alice") == "Hello, Alice!"\n\n'
+        "def test_greet_bob() -> None:\n"
+        '    assert greet("Bob") == "Hello, Bob!"\n\n'
+        "def test_greet_returns_str() -> None:\n"
+        '    assert isinstance(greet("X"), str)\n\n'
+        "def test_greet_empty() -> None:\n"
+        '    assert greet("") == "Hello, !"\n'
+    ),
+}
+
+
+TASKS: tuple[Task, ...] = (
+    Task(
+        task_id="greet_single_file",
+        task_level="easy",
+        brief=(
+            "Implement `greet(name)` in `main.py` so that `greet(\"Alice\")` returns "
+            '`"Hello, Alice!"`. Use type hints. Keep the module under 15 lines.'
+        ),
+        initial_files={"main.py": "def greet(name):\n    pass\n"},
+        target_score=0.90,
+        max_budget=4,
+        tools=("ruff", "imports", "mypy", "pytest"),
+        hidden_tests=_HIDDEN_EASY,
+    ),
+    Task(
+        task_id="greet_with_tests",
+        task_level="medium",
+        brief=(
+            "Extend `main.py` so that `greet(None)` raises `ValueError`, "
+            "and add a `test_main.py` with pytest assertions. Keep `ruff` and "
+            "`mypy --strict` clean."
+        ),
+        initial_files={
+            "main.py": (
+                "from __future__ import annotations\n\n\n"
+                "def greet(name: str) -> str:\n"
+                '    return f"Hello, {name}!"\n'
+            ),
+            "test_main.py": "",
+        },
+        target_score=0.80,
+        max_budget=6,
+        tools=("ruff", "imports", "mypy", "pytest"),
+        hidden_tests=_HIDDEN_MEDIUM,
+    ),
+    Task(
+        task_id="multi_file_module",
+        task_level="hard",
+        brief=(
+            "Split into three files: `main.py` (entry), `core.py` (the greet "
+            "function), `test_core.py` (tests). Every function must be type-hinted. "
+            "All tests pass. `mypy --strict` clean."
+        ),
+        initial_files={
+            "main.py": (
+                "from __future__ import annotations\n\nfrom core import greet\n\n\n"
+                'if __name__ == "__main__":\n'
+                '    print(greet("World"))\n'
+            ),
+            "core.py": "",
+            "test_core.py": "",
+        },
+        target_score=0.70,
+        max_budget=10,
+        tools=("ruff", "imports", "mypy", "pytest"),
+        hidden_tests=_HIDDEN_HARD,
+    ),
+)
+
+
+def get_task(task_level: str) -> Task:
+    for t in TASKS:
+        if t.task_level == task_level:
+            return t
+    msg = f"unknown task_level: {task_level!r} (expected easy|medium|hard)"
+    raise ValueError(msg)

requirements.txt

@@ -0,0 +1,11 @@
+fastapi
+uvicorn[standard]
+unsloth
+trl>=0.14.0
+datasets
+peft
+transformers
+accelerate
+pytest
+ruff
+mypy