Upload folder using huggingface_hub

DEMO_SCRIPT.md

@@ -0,0 +1,12 @@
+# TorchReview Copilot Demo Script
+
+## 60-90 Second Walkthrough
+
+1. Open the Hugging Face Space and introduce TorchReview Copilot as an AI-powered code review and improvement system built with PyTorch.
+2. Point to the problem statement: manual code review is slow, inconsistent, and hard to scale.
+3. Select the `Fix the invoice total syntax regression` example to show the app loading a broken code sample together with the context window.
+4. Highlight the **Live Triage Radar**, the ML quality score, and the RL-ready reward score.
+5. Explain that the PyTorch layer uses CodeBERTa embeddings to compare the input against known code-quality patterns from the OpenEnv task catalog.
+6. Scroll to the three-step improvement plan and call out the progression: syntax and bug fixes, edge cases, then scalability.
+7. Switch to the performance example to show the confidence profile and reward changing for a different class of issue.
+8. Close by noting that OpenEnv still powers deterministic validation under the hood, so the demo remains grounded in measurable task outcomes.

Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY pyproject.toml README.md DEMO_SCRIPT.md openenv.yaml __init__.py client.py compat.py openenv_models.py inference.py triage.py triage_catalog.py triage_models.py launch.py /app/
+COPY api /app/api
+COPY app /app/app
+COPY analyzers /app/analyzers
+COPY models /app/models
+COPY schemas /app/schemas
+COPY server /app/server
+COPY services /app/services
+COPY tasks /app/tasks
+COPY utils /app/utils
+COPY graders /app/graders
+
+RUN python -m pip install --upgrade pip && \
+    pip install .
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000', timeout=3).read()"
+
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["python", "launch.py"]

README.md

@@ -1,10 +1,62 @@
----
-title: Python Code Review Env
-emoji: 😻
-colorFrom: pink
-colorTo: green
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: TorchReview Copilot
+colorFrom: yellow
+colorTo: red
+sdk: docker
+pinned: false
+app_port: 8000
+tags:
+  - pytorch
+  - gradio
+  - fastapi
+  - openenv
+  - code-review
+base_path: /web
+---
+
+# TorchReview Copilot
+
+TorchReview Copilot is an **AI-powered code review and improvement system using PyTorch** to analyze Python code, predict quality, generate structured improvement suggestions, and compute an RL-ready reward score.
+
+It upgrades the original OpenEnv hackathon environment into a judge-friendly product demo: a polished Hugging Face Space on top, with the deterministic OpenEnv validation engine still preserved underneath.
+
+**Live demo:** https://huggingface.co/spaces/uvpatel7271/final-python-env  
+**Repository:** https://github.com/uvpatel/final-python-env
+
+## Problem Statement
+
+Engineering teams lose time during incident response and code review because broken Python snippets often arrive with noisy traces, partial test output, and unclear ownership. Before fixing anything, someone still has to answer:
+
+- Is this a syntax issue, a logic bug, or a performance regression?
+- How risky is the repair?
+- What should be checked first?
+
+That triage step is repetitive, error-prone, and often slows down the actual fix.
+
+## Solution
+
+TorchReview Copilot turns code, traceback text, and a short context window into a practical code-review report:
+
+- **Issue classification:** syntax, logic, or performance
+- **ML quality score:** predicted code quality from PyTorch embeddings
+- **Reward score:** RL-ready score from model quality, lint quality, and complexity penalty
+- **Live Triage Radar:** confidence visualization for all issue classes
+- **Nearest known pattern:** the closest OpenEnv task match
+- **Improvement plan:** step 1 syntax/bug fixes, step 2 edge cases, step 3 scalability
+
+## Why PyTorch Matters
+
+This project uses **PyTorch for real inference**, not placeholder branching:
+
+- `transformers` + `torch` load `huggingface/CodeBERTa-small-v1`
+- embeddings compare code with OpenEnv issue prototypes
+- combines ML + static analysis signals
+
+## How It Works
+
+`Input → static checks → PyTorch embeddings → prediction → suggestions → reward`
+
+## Reward Formula
+
+```text
+reward = (0.5 x ML_quality_score) + (0.3 x lint_score) - (0.2 x complexity_penalty)

__init__.py

@@ -0,0 +1,36 @@
+"""Public package exports for python_code_review_env."""
+
+from .client import PythonCodeReviewEnv, PythonEnv
+from .models import PyTorchCodeAnalyzerModel
+from .Models import (
+    PythonAction,
+    PythonCodeReviewAction,
+    PythonCodeReviewObservation,
+    PythonCodeReviewState,
+    PythonObservation,
+    PythonState,
+)
+from .schemas import AnalyzeCodeRequest, AnalyzeCodeResponse
+from .services import AnalysisService
+from .triage import CodeTriageEngine, HashingEmbeddingBackend, TransformersEmbeddingBackend, get_default_engine
+from .triage_models import TriageResult
+
+__all__ = [
+    "PythonAction",
+    "PythonObservation",
+    "PythonState",
+    "PythonCodeReviewAction",
+    "PythonCodeReviewObservation",
+    "PythonCodeReviewState",
+    "PythonCodeReviewEnv",
+    "PythonEnv",
+    "AnalyzeCodeRequest",
+    "AnalyzeCodeResponse",
+    "AnalysisService",
+    "CodeTriageEngine",
+    "HashingEmbeddingBackend",
+    "PyTorchCodeAnalyzerModel",
+    "TransformersEmbeddingBackend",
+    "TriageResult",
+    "get_default_engine",
+]

analyzers/__init__.py

@@ -0,0 +1,13 @@
+"""Domain-specific analyzers for multi-domain code understanding."""
+
+from .dsa_analyzer import analyze_dsa_code
+from .ds_analyzer import analyze_data_science_code
+from .ml_analyzer import analyze_ml_code
+from .web_analyzer import analyze_web_code
+
+__all__ = [
+    "analyze_dsa_code",
+    "analyze_data_science_code",
+    "analyze_ml_code",
+    "analyze_web_code",
+]

analyzers/ds_analyzer.py

@@ -0,0 +1,56 @@
+"""Analyzer for data-science oriented Python code."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from schemas.response import AnalysisIssue, DomainAnalysis
+
+
+def analyze_data_science_code(code: str, parsed: Dict[str, Any], complexity: Dict[str, Any]) -> DomainAnalysis:
+    """Inspect pandas and numpy code for vectorization and leakage concerns."""
+
+    issues = []
+    suggestions = []
+    score = 0.72
+
+    if "iterrows(" in code or "itertuples(" in code:
+        issues.append(
+            AnalysisIssue(
+                title="Row-wise dataframe iteration detected",
+                severity="medium",
+                description="Looping through dataframe rows is usually slower and less scalable than vectorized operations.",
+            )
+        )
+        suggestions.append("Use vectorized pandas or numpy expressions instead of row-wise iteration.")
+        score -= 0.18
+
+    if "inplace=True" in code:
+        suggestions.append("Avoid inplace mutation to keep data pipelines easier to reason about and test.")
+        score -= 0.05
+
+    if "fit_transform(" in code and "train_test_split" not in code:
+        issues.append(
+            AnalysisIssue(
+                title="Potential data leakage risk",
+                severity="high",
+                description="Feature transforms appear before an explicit train/test split.",
+            )
+        )
+        suggestions.append("Split train and validation data before fitting stateful preprocessing steps.")
+        score -= 0.2
+
+    if not suggestions:
+        suggestions.append("Add schema assumptions and null-handling checks for production data quality.")
+
+    return DomainAnalysis(
+        domain="data_science",
+        domain_score=max(0.05, round(score, 4)),
+        issues=issues,
+        suggestions=suggestions,
+        highlights={
+            "vectorization_risk": float("iterrows(" in code or "itertuples(" in code),
+            "time_complexity": complexity["time_complexity"],
+            "uses_pandas": float(parsed.get("uses_pandas", False)),
+        },
+    )

analyzers/dsa_analyzer.py

@@ -0,0 +1,48 @@
+"""Analyzer for DSA and competitive-programming style Python code."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from schemas.response import AnalysisIssue, DomainAnalysis
+
+
+def analyze_dsa_code(code: str, parsed: Dict[str, Any], complexity: Dict[str, Any]) -> DomainAnalysis:
+    """Inspect algorithmic code for brute-force patterns and efficiency risks."""
+
+    issues = []
+    suggestions = []
+    score = 0.7
+
+    if parsed.get("max_loop_depth", 0) >= 2:
+        issues.append(
+            AnalysisIssue(
+                title="Nested loops suggest brute-force behavior",
+                severity="medium",
+                description="The implementation scans the input multiple times, which is often avoidable in DSA problems.",
+            )
+        )
+        suggestions.append("Consider replacing nested scans with a hashmap, prefix table, or sorted search strategy.")
+        score -= 0.15
+
+    if parsed.get("uses_recursion"):
+        suggestions.append("Verify recursion depth and add memoization or iterative conversion if the input size can grow.")
+        score -= 0.05
+
+    if "sorted(" in code or ".sort(" in code:
+        suggestions.append("Sorting is acceptable here, but validate whether a direct O(n) pass can remove the sort.")
+
+    if not suggestions:
+        suggestions.append("Document the intended time complexity and add edge-case checks for empty input and duplicates.")
+
+    return DomainAnalysis(
+        domain="dsa",
+        domain_score=max(0.05, round(score, 4)),
+        issues=issues,
+        suggestions=suggestions,
+        highlights={
+            "time_complexity": complexity["time_complexity"],
+            "space_complexity": complexity["space_complexity"],
+            "max_loop_depth": float(parsed.get("max_loop_depth", 0)),
+        },
+    )

analyzers/ml_analyzer.py

@@ -0,0 +1,61 @@
+"""Analyzer for machine-learning and deep-learning code."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from schemas.response import AnalysisIssue, DomainAnalysis
+
+
+def analyze_ml_code(code: str, parsed: Dict[str, Any], complexity: Dict[str, Any]) -> DomainAnalysis:
+    """Inspect training and inference logic for common ML / DL mistakes."""
+
+    issues = []
+    suggestions = []
+    score = 0.74
+
+    if "torch" in code and "model.eval()" not in code and "predict" in code.lower():
+        issues.append(
+            AnalysisIssue(
+                title="Inference path may be missing eval mode",
+                severity="high",
+                description="Inference code should place the model in eval mode before prediction.",
+            )
+        )
+        suggestions.append("Call model.eval() before inference to disable training-time behavior such as dropout.")
+        score -= 0.18
+
+    if "torch" in code and "no_grad" not in code and "predict" in code.lower():
+        suggestions.append("Wrap inference in torch.no_grad() to reduce memory usage and avoid unnecessary gradient tracking.")
+        score -= 0.12
+
+    if parsed.get("calls_backward") and not parsed.get("calls_optimizer_step"):
+        issues.append(
+            AnalysisIssue(
+                title="Backward pass without optimizer step",
+                severity="medium",
+                description="Gradients are computed, but the optimizer step is not obvious in the snippet.",
+            )
+        )
+        suggestions.append("Ensure optimizer.step() and optimizer.zero_grad() are placed correctly in the training loop.")
+        score -= 0.12
+
+    if "CrossEntropyLoss" in code and "softmax(" in code:
+        suggestions.append("CrossEntropyLoss expects raw logits; remove the explicit softmax before the loss when possible.")
+        score -= 0.05
+
+    if not suggestions:
+        suggestions.append("Add explicit train/eval mode transitions and log validation metrics during training.")
+
+    return DomainAnalysis(
+        domain="ml_dl",
+        domain_score=max(0.05, round(score, 4)),
+        issues=issues,
+        suggestions=suggestions,
+        highlights={
+            "uses_torch": float(parsed.get("uses_torch", False)),
+            "has_eval_mode": float("model.eval()" in code),
+            "has_no_grad": float("no_grad" in code),
+            "time_complexity": complexity["time_complexity"],
+        },
+    )

analyzers/web_analyzer.py

@@ -0,0 +1,50 @@
+"""Analyzer for FastAPI and backend web-service code."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from schemas.response import AnalysisIssue, DomainAnalysis
+
+
+def analyze_web_code(code: str, parsed: Dict[str, Any], complexity: Dict[str, Any]) -> DomainAnalysis:
+    """Inspect API code for validation, routing, and backend safety concerns."""
+
+    issues = []
+    suggestions = []
+    score = 0.76
+
+    route_decorators = set(parsed.get("route_decorators", []))
+    if route_decorators and not parsed.get("uses_pydantic"):
+        issues.append(
+            AnalysisIssue(
+                title="Request validation model is missing",
+                severity="high",
+                description="Route handlers appear present, but no obvious Pydantic validation layer was detected.",
+            )
+        )
+        suggestions.append("Add Pydantic request and response models for strict validation and type-safe contracts.")
+        score -= 0.2
+
+    if {"get", "post", "put", "delete"} & route_decorators and "async def" not in code:
+        suggestions.append("Prefer async FastAPI endpoints when the route performs I/O or awaits downstream services.")
+        score -= 0.08
+
+    if "request.json()" in code or "request.body()" in code:
+        suggestions.append("Validate raw request payloads before use; avoid trusting unchecked JSON input.")
+        score -= 0.08
+
+    if not suggestions:
+        suggestions.append("Add domain-specific response models and centralize dependency injection for cleaner API structure.")
+
+    return DomainAnalysis(
+        domain="web",
+        domain_score=max(0.05, round(score, 4)),
+        issues=issues,
+        suggestions=suggestions,
+        highlights={
+            "route_count": float(len(route_decorators)),
+            "uses_validation": float(parsed.get("uses_pydantic", False)),
+            "time_complexity": complexity["time_complexity"],
+        },
+    )

api/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI backend package for the multi-domain analyzer."""
+
+from .main import app
+
+__all__ = ["app"]

api/main.py

@@ -0,0 +1,27 @@
+"""FastAPI backend for the multi-domain AI code analyzer."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from schemas.request import AnalyzeCodeRequest
+from schemas.response import AnalyzeCodeResponse
+from services.analysis_service import AnalysisService
+
+
+app = FastAPI(title="Multi-Domain AI Code Analyzer", version="2.0.0")
+analysis_service = AnalysisService()
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    """Return a simple health payload for deployments and smoke tests."""
+
+    return {"status": "ok"}
+
+
+@app.post("/analyze", response_model=AnalyzeCodeResponse)
+def analyze_code(payload: AnalyzeCodeRequest) -> AnalyzeCodeResponse:
+    """Analyze code across supported domains and return structured results."""
+
+    return analysis_service.analyze(payload)

app/__init__.py

@@ -0,0 +1 @@
+"""Streamlit UI package for the multi-domain analyzer."""

app/examples.py

@@ -0,0 +1,31 @@
+"""Example snippets for each supported analysis domain."""
+
+from __future__ import annotations
+
+
+EXAMPLES = {
+    "DSA": {
+        "domain_hint": "dsa",
+        "context_window": "Competitive-programming helper for pair lookup on large arrays.",
+        "traceback_text": "",
+        "code": """def two_sum(nums, target):\n    for i in range(len(nums)):\n        for j in range(i + 1, len(nums)):\n            if nums[i] + nums[j] == target:\n                return [i, j]\n    return []\n""",
+    },
+    "Data Science": {
+        "domain_hint": "data_science",
+        "context_window": "Feature engineering step in a churn-prediction notebook.",
+        "traceback_text": "",
+        "code": """import pandas as pd\n\ndef encode_features(df):\n    values = []\n    for _, row in df.iterrows():\n        values.append(row['age'] * row['sessions'])\n    df['score'] = values\n    return df\n""",
+    },
+    "ML / DL": {
+        "domain_hint": "ml_dl",
+        "context_window": "Inference utility for a PyTorch classifier used in a batch review job.",
+        "traceback_text": "",
+        "code": """import torch\n\nclass Predictor:\n    def __init__(self, model):\n        self.model = model\n\n    def predict(self, batch):\n        outputs = self.model(batch)\n        return outputs.argmax(dim=1)\n""",
+    },
+    "Web / FastAPI": {
+        "domain_hint": "web",
+        "context_window": "Backend endpoint for creating review tasks from user-submitted payloads.",
+        "traceback_text": "",
+        "code": """from fastapi import FastAPI, Request\n\napp = FastAPI()\n\n@app.post('/tasks')\ndef create_task(request: Request):\n    payload = request.json()\n    return {'task': payload}\n""",
+    },
+}

app/streamlit_app.py

@@ -0,0 +1,100 @@
+"""Streamlit frontend for the multi-domain analyzer platform."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from app.examples import EXAMPLES
+from schemas.request import AnalyzeCodeRequest
+from services.analysis_service import AnalysisService
+
+
+analysis_service = AnalysisService()
+
+
+def _analyze(code: str, context_window: str, traceback_text: str, domain_hint: str):
+    """Run the analysis service with validated request payloads."""
+
+    request = AnalyzeCodeRequest(
+        code=code,
+        context_window=context_window,
+        traceback_text=traceback_text,
+        domain_hint=domain_hint,  # type: ignore[arg-type]
+    )
+    return analysis_service.analyze(request)
+
+
+def main() -> None:
+    """Render the Streamlit UI."""
+
+    st.set_page_config(page_title="Multi-Domain AI Code Analyzer", layout="wide")
+    st.title("Multi-Domain AI Code Analyzer & Improvement System")
+    st.caption("PyTorch-powered code review across DSA, Data Science, ML/DL, and Web backend code.")
+
+    example_name = st.selectbox("Example input", list(EXAMPLES.keys()))
+    example = EXAMPLES[example_name]
+    auto_analyze = st.toggle("Real-time scoring", value=True)
+
+    left, right = st.columns([1.2, 1.0])
+    with left:
+        code = st.text_area("Code input", value=example["code"], height=420)
+        context_window = st.text_area("Context window", value=example["context_window"], height=100)
+        traceback_text = st.text_area("Optional traceback / runtime hint", value=example["traceback_text"], height=100)
+        domain_hint = st.selectbox("Domain hint", ["auto", "dsa", "data_science", "ml_dl", "web"], index=["auto", "dsa", "data_science", "ml_dl", "web"].index(example["domain_hint"]))
+        analyze_clicked = st.button("Analyze Code", type="primary")
+
+    result = None
+    if code and (analyze_clicked or auto_analyze):
+        result = _analyze(code, context_window, traceback_text, domain_hint)
+
+    with right:
+        if result is None:
+            st.info("Paste code or load an example to start analysis.")
+        else:
+            metric_cols = st.columns(4)
+            metric_cols[0].metric("Detected domain", result.detected_domain)
+            metric_cols[1].metric("ML score", f"{result.score_breakdown.ml_score:.0%}")
+            metric_cols[2].metric("Domain score", f"{result.score_breakdown.domain_score:.0%}")
+            metric_cols[3].metric("Reward", f"{result.score_breakdown.reward:.0%}")
+            st.bar_chart(result.domain_confidences)
+            st.caption(result.summary)
+
+    if result is not None:
+        overview_tab, suggestions_tab, domain_tab, static_tab = st.tabs(
+            ["Overview", "Suggestions", "Domain Detail", "Static Analysis"]
+        )
+
+        with overview_tab:
+            st.subheader("Improvement Plan")
+            for step in result.improvement_plan:
+                st.write(f"- {step}")
+            st.subheader("Complexity")
+            st.write(
+                {
+                    "time_complexity": result.static_analysis.time_complexity,
+                    "space_complexity": result.static_analysis.space_complexity,
+                    "cyclomatic_complexity": result.static_analysis.cyclomatic_complexity,
+                }
+            )
+
+        with suggestions_tab:
+            st.subheader("Suggestions")
+            for suggestion in result.domain_analysis.suggestions:
+                st.write(f"- {suggestion}")
+            if result.domain_analysis.issues:
+                st.subheader("Issues")
+                for issue in result.domain_analysis.issues:
+                    st.write(f"- [{issue.severity}] {issue.title}: {issue.description}")
+
+        with domain_tab:
+            st.subheader("Domain Highlights")
+            st.json(result.domain_analysis.highlights)
+            st.write(f"Domain score: {result.domain_analysis.domain_score:.0%}")
+
+        with static_tab:
+            st.subheader("Static Analysis")
+            st.json(result.static_analysis.model_dump())
+
+
+if __name__ == "__main__":
+    main()

client.py

@@ -0,0 +1,37 @@
+"""Client helpers for python_code_review_env."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+
+from .Models import (
+    PythonCodeReviewAction,
+    PythonCodeReviewObservation,
+    PythonCodeReviewState,
+)
+
+
+class PythonCodeReviewEnv(
+    EnvClient[PythonCodeReviewAction, PythonCodeReviewObservation, PythonCodeReviewState]
+):
+    """Typed client for the code review environment."""
+
+    def _step_payload(self, action: PythonCodeReviewAction) -> Dict:
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: Dict) -> StepResult[PythonCodeReviewObservation]:
+        observation = PythonCodeReviewObservation.model_validate(payload.get("observation", {}))
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", observation.done),
+        )
+
+    def _parse_state(self, payload: Dict) -> PythonCodeReviewState:
+        return PythonCodeReviewState.model_validate(payload)
+
+
+PythonEnv = PythonCodeReviewEnv

compat.py

@@ -0,0 +1,13 @@
+"""Compatibility helpers expected by validator-oriented scripts."""
+
+from __future__ import annotations
+
+
+def install_openenv_fastmcp_compat() -> None:
+    """Install runtime shims when needed.
+
+    The current environment does not require any monkey-patching, so this is a
+    deliberate no-op kept for validator compatibility.
+    """
+
+    return None

graders/__init__.py

@@ -0,0 +1,5 @@
+"""Deterministic graders for python_code_review_env."""
+
+from .dispatch import grade_task
+
+__all__ = ["grade_task"]

graders/bug_fix.py

@@ -0,0 +1,102 @@
+"""Bug-fix task grader."""
+
+from __future__ import annotations
+
+try:
+    from ..Models import TaskGrade
+    from ..tasks.catalog import ReviewTask
+except ImportError:
+    from Models import TaskGrade
+    from tasks.catalog import ReviewTask
+
+from .shared import (
+    base_grade,
+    compile_code,
+    component_score,
+    execute_cases,
+    quality_metrics,
+    shaped_score,
+    similarity_score,
+    summarize_results,
+)
+
+
+def grade_bug_fix_task(
+    task: ReviewTask,
+    code: str,
+    *,
+    include_hidden: bool,
+    timeout_s: float = 2.0,
+) -> TaskGrade:
+    """Grade a bug-fix task against public or full test suites."""
+
+    compiled, compile_error = compile_code(code)
+    quality = quality_metrics(code, task.function_name)
+    details = {
+        "compile_error": compile_error,
+        "quality_notes": quality["quality_notes"],
+        "style_score": quality["style_score"],
+        "visibility": "full" if include_hidden else "public",
+    }
+
+    if not compiled:
+        progress = 0.02 + 0.12 * similarity_score(code, task.reference_code)
+        details["test_results"] = []
+        details["test_summary"] = "Code does not compile."
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.01),
+            tests_passed=0,
+            tests_total=len(task.public_cases) + (len(task.hidden_cases) if include_hidden else 0),
+            quality_score=component_score(0.01),
+            runtime_score=component_score(0.01),
+            timed_out=False,
+            details=details,
+        )
+
+    cases = task.public_cases + (task.hidden_cases if include_hidden else [])
+    result = execute_cases(code, task.function_name, cases, timeout_s=timeout_s)
+    if result.get("timed_out"):
+        details["test_results"] = []
+        details["test_summary"] = result["error"]
+        progress = 0.12 + 0.18 * quality["score"]
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.95),
+            tests_passed=0,
+            tests_total=len(cases),
+            quality_score=quality["score"],
+            runtime_score=component_score(0.01),
+            timed_out=True,
+            details=details,
+        )
+    if "error" in result:
+        details["test_results"] = []
+        details["test_summary"] = result["error"]
+        progress = 0.1 + 0.2 * quality["score"]
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.95),
+            tests_passed=0,
+            tests_total=len(cases),
+            quality_score=quality["score"],
+            runtime_score=component_score(0.01),
+            timed_out=False,
+            details=details,
+        )
+
+    data = result["data"]
+    pass_rate = data["passed"] / max(data["total"], 1)
+    details["test_results"] = data["results"]
+    details["test_summary"] = summarize_results("Test results", data["results"])
+    progress = min(1.0, 0.05 + 0.8 * pass_rate + 0.15 * quality["score"])
+    return base_grade(
+        score=shaped_score(progress),
+        syntax_score=component_score(0.95),
+        tests_passed=data["passed"],
+        tests_total=data["total"],
+        quality_score=quality["score"],
+        runtime_score=component_score(0.01),
+        timed_out=False,
+        details=details,
+    )

graders/dispatch.py

@@ -0,0 +1,32 @@
+"""Task grader dispatch."""
+
+from __future__ import annotations
+
+try:
+    from ..Models import TaskGrade
+    from ..tasks.catalog import ReviewTask
+except ImportError:
+    from Models import TaskGrade
+    from tasks.catalog import ReviewTask
+
+from .bug_fix import grade_bug_fix_task
+from .optimization import grade_optimization_task
+from .syntax import grade_syntax_task
+
+
+def grade_task(
+    task: ReviewTask,
+    code: str,
+    *,
+    include_hidden: bool,
+    timeout_s: float = 3.0,
+) -> TaskGrade:
+    """Dispatch to the correct deterministic grader."""
+
+    if task.task_kind == "syntax_fix":
+        return grade_syntax_task(task, code, timeout_s=timeout_s)
+    if task.task_kind == "bug_fix":
+        return grade_bug_fix_task(task, code, include_hidden=include_hidden, timeout_s=timeout_s)
+    if task.task_kind == "optimization":
+        return grade_optimization_task(task, code, include_hidden=include_hidden, timeout_s=timeout_s)
+    raise ValueError(f"Unsupported task kind: {task.task_kind}")

graders/optimization.py

@@ -0,0 +1,122 @@
+"""Optimization task grader."""
+
+from __future__ import annotations
+
+try:
+    from ..Models import TaskGrade
+    from ..tasks.catalog import ReviewTask
+except ImportError:
+    from Models import TaskGrade
+    from tasks.catalog import ReviewTask
+
+from .shared import (
+    base_grade,
+    benchmark_candidate,
+    compile_code,
+    component_score,
+    execute_cases,
+    quality_metrics,
+    shaped_score,
+    similarity_score,
+    summarize_results,
+)
+
+
+def grade_optimization_task(
+    task: ReviewTask,
+    code: str,
+    *,
+    include_hidden: bool,
+    timeout_s: float = 3.0,
+) -> TaskGrade:
+    """Grade an optimization/refactor task with correctness, quality, and runtime."""
+
+    compiled, compile_error = compile_code(code)
+    quality = quality_metrics(code, task.function_name)
+    details = {
+        "compile_error": compile_error,
+        "quality_notes": quality["quality_notes"],
+        "style_score": quality["style_score"],
+        "visibility": "full" if include_hidden else "public",
+    }
+
+    if not compiled:
+        progress = 0.02 + 0.1 * similarity_score(code, task.reference_code)
+        details["test_results"] = []
+        details["test_summary"] = "Code does not compile."
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.01),
+            tests_passed=0,
+            tests_total=len(task.public_cases) + (len(task.hidden_cases) if include_hidden else 0),
+            quality_score=component_score(0.01),
+            runtime_score=component_score(0.01),
+            timed_out=False,
+            details=details,
+        )
+
+    cases = task.public_cases + (task.hidden_cases if include_hidden else [])
+    result = execute_cases(code, task.function_name, cases, timeout_s=timeout_s)
+    if result.get("timed_out"):
+        details["test_results"] = []
+        details["test_summary"] = result["error"]
+        progress = 0.1 + 0.18 * quality["score"]
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.95),
+            tests_passed=0,
+            tests_total=len(cases),
+            quality_score=quality["score"],
+            runtime_score=component_score(0.01),
+            timed_out=True,
+            details=details,
+        )
+    if "error" in result:
+        details["test_results"] = []
+        details["test_summary"] = result["error"]
+        progress = 0.1 + 0.2 * quality["score"]
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.95),
+            tests_passed=0,
+            tests_total=len(cases),
+            quality_score=quality["score"],
+            runtime_score=component_score(0.01),
+            timed_out=False,
+            details=details,
+        )
+
+    data = result["data"]
+    pass_rate = data["passed"] / max(data["total"], 1)
+    runtime_score = component_score(0.01)
+    benchmark_summary = "Benchmark deferred until hidden evaluation."
+    timed_out = False
+
+    if include_hidden and pass_rate == 1.0:
+        benchmark = benchmark_candidate(task, code, timeout_s=timeout_s)
+        runtime_score = benchmark["runtime_score"]
+        timed_out = benchmark.get("timed_out", False)
+        benchmark_summary = benchmark["details"]
+        if timed_out:
+            runtime_score = component_score(0.01)
+
+    details["test_results"] = data["results"]
+    details["test_summary"] = summarize_results("Test results", data["results"])
+    details["benchmark"] = benchmark_summary
+
+    runtime_progress = 0.0 if benchmark_summary == "Benchmark deferred until hidden evaluation." else runtime_score
+    if include_hidden:
+        progress = min(1.0, 0.05 + 0.6 * pass_rate + 0.2 * quality["score"] + 0.15 * runtime_progress)
+    else:
+        progress = min(1.0, 0.05 + 0.7 * pass_rate + 0.25 * quality["score"])
+
+    return base_grade(
+        score=shaped_score(progress),
+        syntax_score=component_score(0.95),
+        tests_passed=data["passed"],
+        tests_total=data["total"],
+        quality_score=quality["score"],
+        runtime_score=runtime_score,
+        timed_out=timed_out,
+        details=details,
+    )

graders/shared.py

@@ -0,0 +1,431 @@
+"""Shared deterministic grading helpers."""
+
+from __future__ import annotations
+
+import ast
+import difflib
+import math
+import multiprocessing as mp
+import time
+import traceback
+from typing import Any, Callable, Dict, List
+
+try:
+    from ..Models import TaskGrade
+    from ..tasks.catalog import CallCase, ReviewTask
+except ImportError:
+    from Models import TaskGrade
+    from tasks.catalog import CallCase, ReviewTask
+
+
+STRICT_SCORE_MIN = 0.01
+STRICT_SCORE_MAX = 0.99
+POOR_SCORE = 0.1
+NEAR_PERFECT_SCORE = 0.95
+
+
+def finite_float(value: Any, fallback: float = STRICT_SCORE_MIN) -> float:
+    """Convert a value into a finite float with a deterministic fallback."""
+
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        return fallback
+    if math.isnan(numeric) or math.isinf(numeric):
+        return fallback
+    return numeric
+
+
+def clamp(value: float, lower: float = 0.0, upper: float = 1.0) -> float:
+    """Clamp a floating-point value to a closed interval."""
+
+    numeric = finite_float(value, fallback=lower)
+    return max(lower, min(upper, numeric))
+
+
+def strict_score(value: Any, lower: float = STRICT_SCORE_MIN, upper: float = STRICT_SCORE_MAX) -> float:
+    """Clamp a score to the OpenEnv-safe open interval (0, 1)."""
+
+    score = max(lower, min(upper, finite_float(value, fallback=lower)))
+    score = round(score, 3)
+    assert 0 < score < 1, f"Invalid score: {score}"
+    return score
+
+
+def shaped_score(progress: Any, floor: float = POOR_SCORE, ceiling: float = NEAR_PERFECT_SCORE) -> float:
+    """Map progress in [0, 1] to a shaped score band within (0, 1)."""
+
+    bounded_progress = clamp(finite_float(progress, fallback=0.0))
+    score = floor + (ceiling - floor) * bounded_progress
+    score = max(STRICT_SCORE_MIN, min(score, STRICT_SCORE_MAX))
+    score = round(score, 3)
+    assert 0 < score < 1, f"Invalid score: {score}"
+    return score
+
+
+def score_from_checks(passed: int, total: int, floor: float = POOR_SCORE, ceiling: float = NEAR_PERFECT_SCORE) -> float:
+    """Convert discrete checks into a smoothly shaped score."""
+
+    return shaped_score(safe_ratio(passed, total), floor=floor, ceiling=ceiling)
+
+
+def safe_ratio(numerator: Any, denominator: Any) -> float:
+    """Return a stable ratio in [0, 1] that never raises or produces NaN."""
+
+    denom = int(finite_float(denominator, fallback=0.0))
+    if denom <= 0:
+        return 0.0
+    numer = finite_float(numerator, fallback=0.0)
+    return clamp(numer / denom)
+
+
+def component_score(value: Any) -> float:
+    """Normalize component scores such as syntax, quality, and runtime."""
+
+    return strict_score(value)
+
+
+def compile_code(code: str) -> tuple[bool, str]:
+    """Return whether code compiles and the syntax error, if any."""
+
+    try:
+        compile(code, "<candidate>", "exec")
+    except SyntaxError as exc:
+        return False, f"SyntaxError: {exc.msg} (line {exc.lineno}, column {exc.offset})"
+    except Exception as exc:  # pragma: no cover
+        return False, f"{type(exc).__name__}: {exc}"
+    return True, ""
+
+
+def similarity_score(candidate: str, reference: str) -> float:
+    """Compute a stable text similarity score in [0, 1]."""
+
+    return difflib.SequenceMatcher(a=candidate.strip(), b=reference.strip()).ratio()
+
+
+def _queue_worker(
+    worker: Callable[[Dict[str, Any]], Dict[str, Any]],
+    payload: Dict[str, Any],
+    queue: Any,
+) -> None:
+    try:
+        queue.put({"ok": True, "data": worker(payload)})
+    except Exception as exc:  # pragma: no cover
+        queue.put(
+            {
+                "ok": False,
+                "error": f"{type(exc).__name__}: {exc}",
+                "traceback": traceback.format_exc(limit=5),
+            }
+        )
+
+
+def run_with_timeout(
+    worker: Callable[[Dict[str, Any]], Dict[str, Any]],
+    payload: Dict[str, Any],
+    timeout_s: float,
+) -> Dict[str, Any]:
+    """Execute a worker in a subprocess and terminate on timeout."""
+
+    ctx = mp.get_context("spawn")
+    queue = ctx.Queue()
+    process = ctx.Process(target=_queue_worker, args=(worker, payload, queue))
+    process.start()
+    process.join(timeout_s)
+
+    if process.is_alive():
+        process.terminate()
+        process.join()
+        return {"timed_out": True, "error": f"Execution exceeded {timeout_s:.1f}s timeout."}
+
+    if queue.empty():
+        return {"timed_out": False, "error": "Worker exited without returning a result."}
+
+    message = queue.get()
+    if not message["ok"]:
+        return {
+            "timed_out": False,
+            "error": f"{message['error']}\n{message['traceback']}",
+        }
+    return {"timed_out": False, "data": message["data"]}
+
+
+def _execute_cases_worker(payload: Dict[str, Any]) -> Dict[str, Any]:
+    namespace: Dict[str, Any] = {}
+    exec(payload["code"], namespace)
+    func = namespace[payload["function_name"]]
+    results: List[Dict[str, Any]] = []
+
+    for case in payload["cases"]:
+        try:
+            actual = func(*case["args"], **case["kwargs"])
+            passed = actual == case["expected"]
+            actual_repr = repr(actual)
+        except Exception as exc:
+            passed = False
+            actual_repr = f"{type(exc).__name__}: {exc}"
+
+        results.append(
+            {
+                "label": case["label"],
+                "passed": passed,
+                "expected": repr(case["expected"]),
+                "actual": actual_repr,
+            }
+        )
+
+    passed_total = sum(1 for item in results if item["passed"])
+    return {"passed": passed_total, "total": len(results), "results": results}
+
+
+def execute_cases(code: str, function_name: str, cases: List[CallCase], timeout_s: float) -> Dict[str, Any]:
+    """Run function test cases in a subprocess."""
+
+    payload = {
+        "code": code,
+        "function_name": function_name,
+        "cases": [
+            {"label": case.label, "args": case.args, "kwargs": case.kwargs, "expected": case.expected}
+            for case in cases
+        ],
+    }
+    return run_with_timeout(_execute_cases_worker, payload, timeout_s=timeout_s)
+
+
+class _LoopDepthVisitor(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.depth = 0
+        self.max_depth = 0
+
+    def _visit_loop(self, node: ast.AST) -> None:
+        self.depth += 1
+        self.max_depth = max(self.max_depth, self.depth)
+        self.generic_visit(node)
+        self.depth -= 1
+
+    def visit_For(self, node: ast.For) -> None:  # noqa: N802
+        self._visit_loop(node)
+
+    def visit_While(self, node: ast.While) -> None:  # noqa: N802
+        self._visit_loop(node)
+
+    def visit_comprehension(self, node: ast.comprehension) -> None:  # noqa: N802
+        self._visit_loop(node)
+
+
+def quality_metrics(code: str, function_name: str) -> Dict[str, Any]:
+    """Compute deterministic AST/style quality metrics."""
+
+    compiled, error = compile_code(code)
+    if not compiled:
+        return {
+            "score": component_score(STRICT_SCORE_MIN),
+            "style_score": component_score(STRICT_SCORE_MIN),
+            "quality_notes": [error],
+            "max_loop_depth": 99,
+        }
+
+    tree = ast.parse(code)
+    function_node = next(
+        (
+            node
+            for node in tree.body
+            if isinstance(node, ast.FunctionDef) and node.name == function_name
+        ),
+        None,
+    )
+
+    notes: List[str] = []
+    score = 0.0
+
+    if function_node is not None:
+        score += 0.2
+    else:
+        notes.append(f"Expected function {function_name!r} is missing.")
+
+    lines = [line.rstrip("\n") for line in code.splitlines()]
+    long_lines = [index + 1 for index, line in enumerate(lines) if len(line) > 88]
+    trailing_whitespace = [index + 1 for index, line in enumerate(lines) if line.rstrip() != line]
+    uses_tabs = any("\t" in line for line in lines)
+
+    style_score = 0.0
+    if not long_lines:
+        score += 0.15
+        style_score += 0.5
+    else:
+        notes.append(f"Lines longer than 88 characters: {long_lines[:3]}")
+
+    if not trailing_whitespace and not uses_tabs:
+        score += 0.15
+        style_score += 0.5
+    else:
+        notes.append("Remove tabs or trailing whitespace for cleaner style.")
+
+    if function_node is not None:
+        if ast.get_docstring(function_node):
+            score += 0.1
+        else:
+            notes.append("Add a short docstring to explain the function contract.")
+
+        visitor = _LoopDepthVisitor()
+        visitor.visit(function_node)
+        if visitor.max_depth <= 1:
+            score += 0.15
+        elif visitor.max_depth == 2:
+            score += 0.08
+            notes.append("Loop nesting is still higher than necessary.")
+        else:
+            notes.append("Refactor nested loops to improve readability and runtime.")
+
+        names = [node.id for node in ast.walk(function_node) if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store)]
+        meaningful_names = [name for name in names if len(name) >= 3]
+        if names:
+            score += 0.1 * (len(meaningful_names) / len(names))
+
+        function_length = (function_node.end_lineno or function_node.lineno) - function_node.lineno + 1
+        if function_length <= 25:
+            score += 0.1
+        elif function_length <= 40:
+            score += 0.05
+            notes.append("The function can be shortened or decomposed further.")
+        else:
+            notes.append("The function is long enough to justify refactoring.")
+
+        max_loop_depth = visitor.max_depth
+    else:
+        max_loop_depth = 0
+
+    source_hints = ("Counter(", "defaultdict(", "set(", "dict(", "sorted(", "sum(", " any(", " all(", " for ")
+    if any(hint in code for hint in source_hints):
+        score += 0.15
+
+    return {
+        "score": component_score(clamp(score)),
+        "style_score": component_score(clamp(style_score)),
+        "quality_notes": notes,
+        "max_loop_depth": max_loop_depth,
+    }
+
+
+def build_benchmark_events(config: Dict[str, int]) -> List[Dict[str, Any]]:
+    """Generate deterministic benchmark data without randomness."""
+
+    user_pool = config["user_pool"]
+    events_per_user = config["events_per_user"]
+    events: List[Dict[str, Any]] = []
+
+    for user_index in range(user_pool):
+        user_id = f"user-{user_index:03d}"
+        for event_index in range(events_per_user):
+            status = "active" if (user_index + event_index) % 3 != 0 else "inactive"
+            events.append({"user_id": user_id, "status": status, "minute": event_index})
+            if event_index % 6 == 0:
+                events.append({"user_id": user_id, "status": status, "minute": event_index})
+
+    return events
+
+
+def _benchmark_worker(payload: Dict[str, Any]) -> Dict[str, Any]:
+    candidate_ns: Dict[str, Any] = {}
+    baseline_ns: Dict[str, Any] = {}
+    exec(payload["candidate_code"], candidate_ns)
+    exec(payload["baseline_code"], baseline_ns)
+
+    candidate = candidate_ns[payload["function_name"]]
+    baseline = baseline_ns[payload["function_name"]]
+    benchmark_events = payload["events"]
+    iterations = payload["iterations"]
+
+    baseline_output = baseline(benchmark_events)
+    candidate_output = candidate(benchmark_events)
+    if candidate_output != baseline_output:
+        raise AssertionError("Candidate output diverges from baseline on benchmark data.")
+
+    def _timed(fn: Callable[[Any], Any]) -> float:
+        start = time.perf_counter()
+        for _ in range(iterations):
+            fn(benchmark_events)
+        return time.perf_counter() - start
+
+    baseline_seconds = _timed(baseline)
+    candidate_seconds = _timed(candidate)
+    return {"baseline_seconds": baseline_seconds, "candidate_seconds": candidate_seconds}
+
+
+def benchmark_candidate(task: ReviewTask, code: str, timeout_s: float) -> Dict[str, Any]:
+    """Benchmark a candidate solution against the starter implementation."""
+
+    if not task.benchmark_config:
+        return {"runtime_score": component_score(STRICT_SCORE_MIN), "details": "No benchmark configured."}
+
+    events = build_benchmark_events(task.benchmark_config)
+    payload = {
+        "candidate_code": code,
+        "baseline_code": task.starter_code,
+        "function_name": task.function_name,
+        "events": events,
+        "iterations": task.benchmark_config.get("iterations", 5),
+    }
+    result = run_with_timeout(_benchmark_worker, payload, timeout_s=timeout_s)
+    if result.get("timed_out"):
+        return {"runtime_score": component_score(STRICT_SCORE_MIN), "timed_out": True, "details": result["error"]}
+    if "error" in result:
+        return {"runtime_score": component_score(STRICT_SCORE_MIN), "timed_out": False, "details": result["error"]}
+
+    data = result["data"]
+    baseline_seconds = float(data["baseline_seconds"])
+    candidate_seconds = float(data["candidate_seconds"])
+    improvement_ratio = baseline_seconds / max(candidate_seconds, 1e-9)
+    runtime_score = component_score(clamp((improvement_ratio - 1.0) / 1.5))
+    return {
+        "runtime_score": runtime_score,
+        "timed_out": False,
+        "details": {
+            "baseline_seconds": round(baseline_seconds, 6),
+            "candidate_seconds": round(candidate_seconds, 6),
+            "improvement_ratio": round(improvement_ratio, 3),
+        },
+    }
+
+
+def summarize_results(prefix: str, results: List[Dict[str, Any]]) -> str:
+    """Render concise test output."""
+
+    if not results:
+        return f"{prefix}: no tests were executed."
+
+    lines = [prefix]
+    for item in results:
+        marker = "PASS" if item["passed"] else "FAIL"
+        lines.append(f"- {marker} {item['label']}: expected {item['expected']}, got {item['actual']}")
+    return "\n".join(lines)
+
+
+def base_grade(
+    *,
+    score: float,
+    syntax_score: float,
+    tests_passed: int,
+    tests_total: int,
+    quality_score: float,
+    runtime_score: float,
+    timed_out: bool,
+    details: Dict[str, Any],
+) -> TaskGrade:
+    """Create a normalized TaskGrade payload."""
+
+    safe_score = strict_score(score)
+    safe_syntax_score = component_score(syntax_score)
+    safe_quality_score = component_score(quality_score)
+    safe_runtime_score = component_score(runtime_score)
+
+    return TaskGrade(
+        score=safe_score,
+        syntax_score=safe_syntax_score,
+        tests_passed=tests_passed,
+        tests_total=tests_total,
+        quality_score=safe_quality_score,
+        runtime_score=safe_runtime_score,
+        timed_out=timed_out,
+        details=details,
+    )

graders/syntax.py

@@ -0,0 +1,95 @@
+"""Syntax task grader."""
+
+from __future__ import annotations
+
+try:
+    from ..Models import TaskGrade
+    from ..tasks.catalog import ReviewTask
+except ImportError:
+    from Models import TaskGrade
+    from tasks.catalog import ReviewTask
+
+from .shared import (
+    base_grade,
+    compile_code,
+    component_score,
+    execute_cases,
+    quality_metrics,
+    shaped_score,
+    similarity_score,
+    summarize_results,
+)
+
+
+def grade_syntax_task(task: ReviewTask, code: str, timeout_s: float = 2.0) -> TaskGrade:
+    """Grade a syntax-fix task deterministically."""
+
+    compiled, compile_error = compile_code(code)
+    quality = quality_metrics(code, task.function_name)
+    details = {
+        "compile_error": compile_error,
+        "quality_notes": quality["quality_notes"],
+        "style_score": quality["style_score"],
+    }
+
+    if not compiled:
+        progress = 0.05 + 0.2 * similarity_score(code, task.reference_code)
+        details["test_results"] = []
+        details["test_summary"] = "Code does not compile yet."
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.01),
+            tests_passed=0,
+            tests_total=len(task.public_cases) + len(task.hidden_cases),
+            quality_score=component_score(0.01),
+            runtime_score=component_score(0.01),
+            timed_out=False,
+            details=details,
+        )
+
+    cases = task.public_cases + task.hidden_cases
+    result = execute_cases(code, task.function_name, cases, timeout_s=timeout_s)
+    if result.get("timed_out"):
+        details["test_results"] = []
+        details["test_summary"] = result["error"]
+        progress = 0.2 + 0.25 * quality["score"]
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.95),
+            tests_passed=0,
+            tests_total=len(cases),
+            quality_score=quality["score"],
+            runtime_score=component_score(0.01),
+            timed_out=True,
+            details=details,
+        )
+    if "error" in result:
+        details["test_results"] = []
+        details["test_summary"] = result["error"]
+        progress = 0.18 + 0.2 * quality["score"]
+        return base_grade(
+            score=shaped_score(progress),
+            syntax_score=component_score(0.95),
+            tests_passed=0,
+            tests_total=len(cases),
+            quality_score=quality["score"],
+            runtime_score=component_score(0.01),
+            timed_out=False,
+            details=details,
+        )
+
+    data = result["data"]
+    details["test_results"] = data["results"]
+    details["test_summary"] = summarize_results("Validation checks", data["results"])
+    pass_rate = data["passed"] / max(data["total"], 1)
+    progress = min(1.0, 0.15 + 0.75 * pass_rate + 0.1 * quality["score"])
+    return base_grade(
+        score=shaped_score(progress),
+        syntax_score=component_score(0.95),
+        tests_passed=data["passed"],
+        tests_total=data["total"],
+        quality_score=quality["score"],
+        runtime_score=component_score(0.01),
+        timed_out=False,
+        details=details,
+    )

inference.py

@@ -0,0 +1,383 @@
+#!/usr/bin/env python3
+"""Validator-friendly inference entrypoint for the Python code review environment."""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import time
+from collections.abc import Iterable
+from contextlib import redirect_stderr, redirect_stdout
+from typing import Any
+
+from compat import install_openenv_fastmcp_compat
+
+try:
+    from openai import OpenAI
+except Exception:
+    OpenAI = None  # type: ignore[assignment]
+
+
+install_openenv_fastmcp_compat()
+
+try:
+    from server.env import PythonCodeReviewEnvironment
+except Exception:
+    PythonCodeReviewEnvironment = None  # type: ignore[assignment]
+
+try:
+    from Models import PythonCodeReviewAction
+except Exception:
+    PythonCodeReviewAction = None  # type: ignore[assignment]
+
+try:
+    from tasks import get_task, task_ids
+except Exception:
+    get_task = None  # type: ignore[assignment]
+    task_ids = None  # type: ignore[assignment]
+
+
+ALLOWED_ACTIONS = {
+    "analyze_code",
+    "edit_code",
+    "run_tests",
+    "submit_solution",
+}
+DEFAULT_MODEL_NAME = "mock-model"
+API_TIMEOUT_SECONDS = 3.0
+API_RETRIES = 1
+API_RETRY_DELAY_SECONDS = 0.2
+MIN_SCORE = 0.01
+POOR_SCORE = 0.1
+MAX_SCORE = 0.99
+
+
+def safe_env(name: str, default: str = "") -> str:
+    """Read a string environment variable without raising."""
+    try:
+        value = os.getenv(name)
+        return default if value is None else str(value)
+    except Exception:
+        return default
+
+
+def clamp_score(value: Any) -> float:
+    """Clamp numeric scores to the required open interval (0, 1)."""
+    try:
+        numeric = float(value)
+    except Exception:
+        return MIN_SCORE
+    if numeric != numeric or numeric in (float("inf"), float("-inf")):
+        return MIN_SCORE
+    numeric = max(MIN_SCORE, min(MAX_SCORE, numeric))
+    assert 0 < numeric < 1, f"Invalid score: {numeric}"
+    return numeric
+
+
+def safe_float(value: Any, default: float = POOR_SCORE) -> float:
+    """Convert a value to float without raising."""
+    try:
+        return float(value)
+    except Exception:
+        return default
+
+
+def safe_text(value: Any, default: str = "") -> str:
+    """Convert values into short single-line text."""
+    try:
+        text = str(value)
+    except Exception:
+        return default
+    text = " ".join(text.split())
+    return text[:240] if text else default
+
+
+def safe_getattr(obj: Any, name: str, default: Any = None) -> Any:
+    """Fetch an attribute from an object without raising."""
+    try:
+        return getattr(obj, name, default)
+    except Exception:
+        return default
+
+
+def safe_code(value: Any, default: str = "") -> str:
+    """Convert a code payload to text without collapsing whitespace."""
+    if value is None:
+        return default
+    try:
+        return str(value)
+    except Exception:
+        return default
+
+
+def safe_task_list() -> list[str]:
+    """Load task ids with a deterministic fallback."""
+    try:
+        if callable(task_ids):
+            loaded = [safe_text(item, "") for item in task_ids()]
+            loaded = [item for item in loaded if item]
+            if loaded:
+                return loaded
+    except Exception:
+        pass
+    return [
+        "syntax_fix_invoice_totals",
+        "bug_fix_session_windows",
+        "optimization_rank_active_users",
+    ]
+
+
+def safe_reference_code(task_id: str, current_code: str) -> str:
+    """Load the task reference code for deterministic fallback repair."""
+    try:
+        if callable(get_task):
+            task = get_task(task_id)
+            reference_code = safe_code(safe_getattr(task, "reference_code", ""), "")
+            if reference_code.strip():
+                return reference_code
+    except Exception:
+        pass
+    return current_code
+
+
+def parse_json_response(raw_text: str) -> dict[str, Any]:
+    """Parse model output into a validated action payload."""
+    try:
+        text = raw_text or ""
+        start = text.find("{")
+        end = text.rfind("}") + 1
+        if start >= 0 and end > start:
+            payload = json.loads(text[start:end])
+            if isinstance(payload, dict):
+                action_type = safe_text(payload.get("action_type", "analyze_code"), "analyze_code")
+                code = payload.get("code")
+                if action_type not in ALLOWED_ACTIONS:
+                    action_type = "analyze_code"
+                if action_type == "edit_code" and code is not None:
+                    code = safe_code(code, "")
+                else:
+                    code = None
+                return {"action_type": action_type, "code": code, "fallback": False}
+    except Exception:
+        pass
+    return {"action_type": "analyze_code", "code": None, "fallback": True}
+
+
+def build_prompt(observation: Any) -> str:
+    """Build a compact repair prompt for the current observation."""
+    try:
+        task_description = safe_text(safe_getattr(observation, "task_description", ""), "No task description.")
+        errors = safe_text(safe_getattr(observation, "errors", ""), "none")
+        tests = safe_text(safe_getattr(observation, "test_results", ""), "not available")
+        score = clamp_score(safe_getattr(observation, "score", POOR_SCORE))
+        current_code = safe_code(safe_getattr(observation, "current_code", ""), "")
+        visible_tests = safe_getattr(observation, "visible_tests", [])
+        if not isinstance(visible_tests, Iterable) or isinstance(visible_tests, (str, bytes)):
+            visible_tests = []
+        visible_block = "\n".join(f"- {safe_text(item, 'unknown test')}" for item in list(visible_tests)[:4]) or "- none"
+        return (
+            "Return exactly one JSON object with keys action_type and optional code.\n"
+            "Allowed action_type values: analyze_code, edit_code, run_tests, submit_solution.\n"
+            "Prefer one safe next action only.\n"
+            f"Task: {task_description}\n"
+            f"Score: {score:.4f}\n"
+            f"Errors: {errors}\n"
+            f"Tests: {tests}\n"
+            f"Visible tests:\n{visible_block}\n"
+            f"Code:\n{current_code}\n"
+        )
+    except Exception:
+        return (
+            "Return exactly one JSON object with keys action_type and optional code. "
+            "Use analyze_code if unsure."
+        )
+
+
+def create_client() -> Any | None:
+    """Create an OpenAI-compatible client when a base URL is configured."""
+    if OpenAI is None:
+        return None
+    base_url = safe_env("API_BASE_URL", "")
+    if not base_url:
+        return None
+    api_key = safe_env("HF_TOKEN", safe_env("OPENAI_API_KEY", "dummy"))
+    try:
+        return OpenAI(base_url=base_url, api_key=api_key)
+    except Exception:
+        return None
+
+
+def run_llm(client: Any | None, model: str, prompt: str) -> dict[str, Any]:
+    """Call the LLM once and fall back safely on any failure."""
+    if client is None:
+        return {"action_type": "analyze_code", "code": None, "fallback": True}
+
+    for attempt in range(API_RETRIES + 1):
+        try:
+            with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+                response = client.with_options(timeout=API_TIMEOUT_SECONDS).chat.completions.create(
+                    model=model,
+                    messages=[{"role": "user", "content": prompt}],
+                    temperature=0,
+                    max_tokens=300,
+                )
+            message = safe_getattr(response.choices[0].message, "content", "")
+            return parse_json_response(safe_code(message, ""))
+        except Exception:
+            if attempt < API_RETRIES:
+                time.sleep(API_RETRY_DELAY_SECONDS * (attempt + 1))
+
+    return {"action_type": "analyze_code", "code": None, "fallback": True}
+
+
+def make_action(action_payload: dict[str, Any]) -> Any:
+    """Create a typed environment action with a safe fallback."""
+    action_type = safe_text(action_payload.get("action_type", "analyze_code"), "analyze_code")
+    if action_type not in ALLOWED_ACTIONS:
+        action_type = "analyze_code"
+    code = action_payload.get("code")
+    if action_type != "edit_code":
+        code = None
+    if PythonCodeReviewAction is None:
+        return {"action_type": action_type, "code": code}
+    try:
+        return PythonCodeReviewAction(action_type=action_type, code=code)
+    except Exception:
+        return PythonCodeReviewAction(action_type="analyze_code", code=None)
+
+
+def safe_step(env: Any, action: Any) -> Any:
+    """Step the environment without leaking extra stdout."""
+    try:
+        with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+            return env.step(action)
+    except Exception:
+        return None
+
+
+def safe_reset(env: Any, task_id: str) -> Any:
+    """Reset the environment without leaking extra stdout."""
+    try:
+        with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+            return env.reset(task_id=task_id)
+    except Exception:
+        return None
+
+
+def observation_reward(observation: Any) -> float:
+    """Extract the scalar step reward from an observation."""
+    reward = safe_getattr(observation, "reward", None)
+    if reward is not None:
+        return clamp_score(safe_float(reward, POOR_SCORE))
+    reward_details = safe_getattr(observation, "reward_details", None)
+    reward_value = safe_getattr(reward_details, "value", POOR_SCORE)
+    return clamp_score(safe_float(reward_value, POOR_SCORE))
+
+
+def fallback_first_action(task_id: str) -> dict[str, Any]:
+    """Choose a deterministic first action when the model is unavailable."""
+    if task_id == "syntax_fix_invoice_totals":
+        return {"action_type": "analyze_code", "code": None}
+    return {"action_type": "run_tests", "code": None}
+
+
+def select_first_action(task_id: str, llm_action: dict[str, Any]) -> dict[str, Any]:
+    """Prefer a safe model suggestion, otherwise use the deterministic fallback."""
+    action_type = safe_text(llm_action.get("action_type", ""), "")
+    code = llm_action.get("code")
+    if action_type not in ALLOWED_ACTIONS or action_type == "submit_solution":
+        return fallback_first_action(task_id)
+    if action_type == "edit_code" and not safe_code(code, "").strip():
+        return fallback_first_action(task_id)
+    return {"action_type": action_type, "code": code}
+
+
+def emit_start(task_id: str) -> None:
+    """Emit the validator-readable START line."""
+    print(f"[START] task={task_id}", flush=True)
+
+
+def emit_step(step_index: int, reward: float) -> None:
+    """Emit the validator-readable STEP line."""
+    print(f"[STEP] step={step_index} reward={reward:.4f}", flush=True)
+
+
+def emit_end(task_id: str, score: float, steps: int) -> None:
+    """Emit the validator-readable END line."""
+    print(f"[END] task={task_id} score={clamp_score(score):.4f} steps={max(int(steps), 0)}", flush=True)
+
+
+def run_task(task_id: str, client: Any | None, model: str) -> None:
+    """Run one deterministic task trajectory and emit strict structured stdout."""
+    emit_start(task_id)
+
+    if PythonCodeReviewEnvironment is None:
+        emit_step(1, POOR_SCORE)
+        emit_end(task_id, POOR_SCORE, 1)
+        return
+
+    try:
+        with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+            env = PythonCodeReviewEnvironment(verbose=False)
+    except Exception:
+        emit_step(1, POOR_SCORE)
+        emit_end(task_id, POOR_SCORE, 1)
+        return
+
+    observation = safe_reset(env, task_id)
+    if observation is None:
+        emit_step(1, POOR_SCORE)
+        emit_end(task_id, POOR_SCORE, 1)
+        return
+
+    step_count = 0
+    llm_action = run_llm(client, model, build_prompt(observation))
+    reference_code = safe_reference_code(task_id, safe_code(safe_getattr(observation, "current_code", ""), ""))
+    planned_actions = [
+        select_first_action(task_id, llm_action),
+        {"action_type": "edit_code", "code": reference_code},
+        {"action_type": "submit_solution", "code": None},
+    ]
+
+    final_observation = observation
+    for action_payload in planned_actions:
+        if step_count > 0 and bool(safe_getattr(final_observation, "done", False)):
+            break
+        if action_payload["action_type"] == "edit_code":
+            current_code = safe_code(safe_getattr(final_observation, "current_code", ""), "")
+            if not safe_code(action_payload.get("code"), "").strip():
+                continue
+            if current_code.strip() == safe_code(action_payload.get("code"), "").strip():
+                continue
+
+        next_observation = safe_step(env, make_action(action_payload))
+        step_count += 1
+        if next_observation is None:
+            emit_step(step_count, POOR_SCORE)
+            emit_end(task_id, clamp_score(safe_getattr(final_observation, "score", POOR_SCORE)), step_count)
+            return
+
+        final_observation = next_observation
+        emit_step(step_count, observation_reward(final_observation))
+
+    emit_end(task_id, clamp_score(safe_getattr(final_observation, "score", POOR_SCORE)), step_count)
+
+
+def main() -> int:
+    """Run every benchmark task and emit strict structured stdout."""
+    model_name = safe_env("MODEL_NAME", DEFAULT_MODEL_NAME) or DEFAULT_MODEL_NAME
+    client = create_client()
+    for task_id in safe_task_list():
+        try:
+            run_task(task_id, client, model_name)
+        except Exception:
+            emit_start(task_id)
+            emit_step(1, POOR_SCORE)
+            emit_end(task_id, POOR_SCORE, 1)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

launch.py

@@ -0,0 +1,35 @@
+"""Launch the FastAPI backend and Streamlit UI in one Docker container."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def main() -> int:
+    """Start the API backend in the background and keep Streamlit in the foreground."""
+
+    api_process = subprocess.Popen(
+        ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8001"],
+    )
+    try:
+        return subprocess.call(
+            [
+                "streamlit",
+                "run",
+                "app/streamlit_app.py",
+                "--server.port",
+                "8000",
+                "--server.address",
+                "0.0.0.0",
+                "--server.headless",
+                "true",
+            ]
+        )
+    finally:
+        api_process.terminate()
+        api_process.wait(timeout=10)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

models.py

@@ -0,0 +1,140 @@
+"""Typed models for the python_code_review_env environment."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from openenv.core.env_server.types import Action, Observation, State
+
+
+Difficulty = Literal["easy", "medium", "hard"]
+TaskKind = Literal["syntax_fix", "bug_fix", "optimization"]
+ActionType = Literal["analyze_code", "edit_code", "run_tests", "submit_solution"]
+
+
+class HistoryEntry(BaseModel):
+    """One environment transition recorded for the agent."""
+
+    step: int = Field(..., ge=0)
+    action_type: ActionType
+    status: str = Field(..., description="Short outcome summary.")
+    reward: float = Field(..., gt=0.0, lt=1.0, description="Reward returned for the step.")
+
+
+class RewardDetails(BaseModel):
+    """Transparent reward decomposition for debugging and training."""
+
+    value: float = Field(..., gt=0.0, lt=1.0, description="Clamped net reward in (0.0, 1.0).")
+    syntax_reward: float = Field(default=0.0)
+    test_reward: float = Field(default=0.0)
+    correctness_bonus: float = Field(default=0.0)
+    quality_bonus: float = Field(default=0.0)
+    progress_delta: float = Field(default=0.0)
+    invalid_action_penalty: float = Field(default=0.0)
+    timeout_penalty: float = Field(default=0.0)
+    regression_penalty: float = Field(default=0.0)
+    stagnation_penalty: float = Field(default=0.0)
+    reason: str = Field(..., description="Human-readable reward explanation.")
+    prev_score: float = Field(default=0.01, gt=0.0, lt=1.0)
+    curr_score: float = Field(default=0.01, gt=0.0, lt=1.0)
+    code_changed: bool = Field(default=False)
+
+
+class PythonCodeReviewAction(Action):
+    """Action schema exposed to the agent."""
+
+    action_type: ActionType = Field(..., description="Environment action to take.")
+    code: Optional[str] = Field(
+        default=None,
+        description="Updated Python source for edit_code or submit_solution actions.",
+    )
+
+
+class PythonCodeReviewObservation(Observation):
+    """Observation returned by reset and step."""
+
+    task_id: str = Field(..., description="Stable task identifier.")
+    title: str = Field(..., description="Human-readable task title.")
+    difficulty: Difficulty
+    task_kind: TaskKind
+    task_description: str = Field(..., description="Task instructions shown to the agent.")
+    current_code: str = Field(..., description="Latest code under review.")
+    errors: str = Field(default="", description="Syntax or execution errors.")
+    test_results: str = Field(default="", description="Public test and benchmark feedback.")
+    visible_tests: List[str] = Field(default_factory=list)
+    history: List[HistoryEntry] = Field(default_factory=list)
+    attempts_remaining: int = Field(..., ge=0)
+    last_action_status: str = Field(default="")
+    score: float = Field(..., gt=0.0, lt=1.0)
+    reward_details: RewardDetails = Field(
+        default_factory=lambda: RewardDetails(value=0.1, reason="Environment reset.")
+    )
+
+
+class PythonCodeReviewState(State):
+    """Internal environment state exposed through /state."""
+
+    task_id: Optional[str] = Field(default=None)
+    difficulty: Optional[Difficulty] = Field(default=None)
+    task_kind: Optional[TaskKind] = Field(default=None)
+    attempts_remaining: int = Field(default=0, ge=0)
+    current_code: str = Field(default="")
+    errors: str = Field(default="")
+    test_results: str = Field(default="")
+    history: List[HistoryEntry] = Field(default_factory=list)
+    score: float = Field(default=0.01, gt=0.0, lt=1.0)
+    done: bool = Field(default=False)
+
+
+class TaskDescriptor(BaseModel):
+    """Static task metadata."""
+
+    task_id: str
+    title: str
+    difficulty: Difficulty
+    task_kind: TaskKind
+    task_description: str
+    starter_code: str
+    visible_tests: List[str] = Field(default_factory=list)
+    repo_summary: str = Field(default="")
+    changed_files: List[str] = Field(default_factory=list)
+    available_files: List[str] = Field(default_factory=list)
+    goal: str = Field(default="")
+    max_steps: int = Field(..., ge=1)
+
+
+class TaskSummary(BaseModel):
+    """Compact task listing entry."""
+
+    task_id: str
+    difficulty: Difficulty
+    title: str
+    goal: str = Field(default="")
+
+
+class TaskGrade(BaseModel):
+    """Deterministic grader output."""
+
+    score: float = Field(..., gt=0.0, lt=1.0)
+    syntax_score: float = Field(default=0.01, gt=0.0, lt=1.0)
+    tests_passed: int = Field(default=0, ge=0)
+    tests_total: int = Field(default=0, ge=0)
+    quality_score: float = Field(default=0.01, gt=0.0, lt=1.0)
+    runtime_score: float = Field(default=0.01, gt=0.0, lt=1.0)
+    timed_out: bool = Field(default=False)
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+
+class HealthResponse(BaseModel):
+    """Health payload for smoke tests."""
+
+    status: Literal["ok"] = "ok"
+    environment: str = "python_code_review_env"
+    task_count: int = Field(default=0, ge=0)
+
+
+PythonAction = PythonCodeReviewAction
+PythonObservation = PythonCodeReviewObservation
+PythonState = PythonCodeReviewState

models/__init__.py

@@ -0,0 +1,5 @@
+"""PyTorch-backed model wrappers for the analyzer platform."""
+
+from .pytorch_model import PyTorchCodeAnalyzerModel
+
+__all__ = ["PyTorchCodeAnalyzerModel"]

models/pytorch_model.py

@@ -0,0 +1,149 @@
+"""PyTorch + transformers model wrapper for multi-domain code scoring."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Dict, List, Sequence
+
+import torch
+import torch.nn.functional as F
+
+try:
+    from transformers import AutoModel, AutoTokenizer
+except Exception:
+    AutoModel = None  # type: ignore[assignment]
+    AutoTokenizer = None  # type: ignore[assignment]
+
+
+DOMAIN_PROTOTYPES: Dict[str, List[str]] = {
+    "dsa": [
+        "Binary search, hashmap optimization, recursion, dynamic programming, arrays, trees, graphs, stack, queue, complexity.",
+        "Competitive programming algorithm with loops, memoization, prefix sums, and asymptotic analysis.",
+    ],
+    "data_science": [
+        "Pandas dataframe transformation, numpy vectorization, feature leakage, train test split, iterrows misuse.",
+        "Data cleaning pipeline using pandas, numpy, aggregation, joins, and vectorized operations.",
+    ],
+    "ml_dl": [
+        "PyTorch model, training loop, optimizer, backward pass, eval mode, no_grad, loss function, dataloader.",
+        "Machine learning inference and training code with torch, sklearn, tensors, gradients, and model checkpoints.",
+    ],
+    "web": [
+        "FastAPI endpoint, request validation, Pydantic models, async routes, API security, backend service design.",
+        "REST API backend with routers, dependency injection, input validation, serialization, and error handling.",
+    ],
+    "general": [
+        "General Python utility code with readable structure, typing, tests, and maintainable abstractions.",
+    ],
+}
+
+QUALITY_ANCHORS: Dict[str, List[str]] = {
+    "high": [
+        "Readable typed Python code with validation, efficient algorithms, vectorized operations, safe inference, and clean API boundaries.",
+        "Production-ready code with small functions, docstrings, low complexity, and clear error handling.",
+    ],
+    "low": [
+        "Brute-force nested loops, missing validation, unsafe input handling, missing eval mode, missing no_grad, and code smells.",
+        "Hard to maintain code with high complexity, repeated scans, mutable side effects, and unclear structure.",
+    ],
+}
+
+
+class _HashEmbeddingBackend:
+    """Torch-native fallback when pretrained weights cannot be loaded."""
+
+    def __init__(self, dimensions: int = 128) -> None:
+        self.dimensions = dimensions
+        self.model_id = "hashed-token-fallback"
+        self.backend_name = "hashed-token-fallback"
+        self.notes = ["Using hashed embeddings because pretrained transformer weights are unavailable."]
+
+    def embed_texts(self, texts: Sequence[str]) -> torch.Tensor:
+        matrix = torch.zeros((len(texts), self.dimensions), dtype=torch.float32)
+        for row_index, text in enumerate(texts):
+            tokens = text.lower().split()[:512]
+            if not tokens:
+                matrix[row_index, 0] = 1.0
+                continue
+            for token in tokens:
+                digest = hashlib.md5(token.encode("utf-8")).hexdigest()
+                bucket = int(digest[:8], 16) % self.dimensions
+                sign = -1.0 if int(digest[8:10], 16) % 2 else 1.0
+                matrix[row_index, bucket] += sign
+        return F.normalize(matrix + 1e-6, dim=1)
+
+
+class PyTorchCodeAnalyzerModel:
+    """Score code using pretrained transformer embeddings plus prototype similarity."""
+
+    def __init__(self, model_id: str = "huggingface/CodeBERTa-small-v1") -> None:
+        self.model_id = model_id
+        self.backend_name = model_id
+        self.notes: List[str] = []
+        self._tokenizer = None
+        self._model = None
+        self._fallback = _HashEmbeddingBackend()
+        self._prototype_cache: Dict[str, torch.Tensor] = {}
+
+    def _ensure_loaded(self) -> None:
+        if self._model is not None or self.notes:
+            return
+        if AutoTokenizer is None or AutoModel is None:
+            self.backend_name = self._fallback.backend_name
+            self.notes = list(self._fallback.notes)
+            return
+        try:
+            self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
+            self._model = AutoModel.from_pretrained(self.model_id)
+            self._model.eval()
+            self.notes.append(f"Loaded pretrained encoder `{self.model_id}`.")
+        except Exception as exc:
+            self.backend_name = self._fallback.backend_name
+            self.notes = list(self._fallback.notes) + [f"Pretrained load failed: {type(exc).__name__}: {exc}"]
+
+    def _embed_texts(self, texts: Sequence[str]) -> torch.Tensor:
+        self._ensure_loaded()
+        if self._model is None or self._tokenizer is None:
+            return self._fallback.embed_texts(texts)
+        encoded = self._tokenizer(list(texts), padding=True, truncation=True, max_length=256, return_tensors="pt")
+        with torch.no_grad():
+            outputs = self._model(**encoded)
+            hidden = outputs.last_hidden_state
+            mask = encoded["attention_mask"].unsqueeze(-1)
+            pooled = (hidden * mask).sum(dim=1) / mask.sum(dim=1).clamp(min=1)
+        return F.normalize(pooled, dim=1)
+
+    def _prototype_matrix(self, bucket: str, texts: Sequence[str]) -> torch.Tensor:
+        if bucket not in self._prototype_cache:
+            self._prototype_cache[bucket] = self._embed_texts(texts)
+        return self._prototype_cache[bucket]
+
+    def predict(self, code: str, context_window: str, static_summary: Dict[str, object]) -> Dict[str, object]:
+        """Predict domain probabilities and a model quality score."""
+
+        document = (
+            f"Code:\n{code.strip()[:4000]}\n\n"
+            f"Context:\n{context_window.strip()[:1000]}\n\n"
+            f"Static hints:\n{static_summary}\n"
+        )
+        candidate = self._embed_texts([document])
+
+        domain_scores: Dict[str, float] = {}
+        for domain, texts in DOMAIN_PROTOTYPES.items():
+            matrix = self._prototype_matrix(f"domain:{domain}", texts)
+            similarity = torch.matmul(candidate, matrix.T).max().item()
+            domain_scores[domain] = round((similarity + 1.0) / 2.0, 4)
+
+        high_matrix = self._prototype_matrix("quality:high", QUALITY_ANCHORS["high"])
+        low_matrix = self._prototype_matrix("quality:low", QUALITY_ANCHORS["low"])
+        high_similarity = torch.matmul(candidate, high_matrix.T).max().item()
+        low_similarity = torch.matmul(candidate, low_matrix.T).max().item()
+        ml_quality_score = torch.sigmoid(torch.tensor((high_similarity - low_similarity) * 4.0)).item()
+
+        return {
+            "domain_scores": domain_scores,
+            "ml_quality_score": round(float(ml_quality_score), 4),
+            "backend_name": self.backend_name,
+            "model_id": self.model_id,
+            "notes": list(self.notes),
+        }

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: python_code_review_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-python-code-review-env"
+version = "1.0.0"
+description = "TorchReview Copilot: AI-powered Python code triage with PyTorch and OpenEnv validation."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.111.0",
+    "gradio>=5.26.0",
+    "openai>=1.76.0",
+    "openenv-core[core]>=0.2.2",
+    "pytest>=8.0.0",
+    "streamlit>=1.44.0",
+    "torch>=2.2.0",
+    "transformers>=4.45.0",
+    "uvicorn>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+server = "python_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = [
+    "python_env",
+    "python_env.server",
+    "python_env.tasks",
+    "python_env.graders",
+    "python_env.api",
+    "python_env.app",
+    "python_env.analyzers",
+    "python_env.models",
+    "python_env.schemas",
+    "python_env.services",
+    "python_env.utils",
+]
+package-dir = { "python_env" = ".", "python_env.server" = "server", "python_env.tasks" = "tasks", "python_env.graders" = "graders", "python_env.api" = "api", "python_env.app" = "app", "python_env.analyzers" = "analyzers", "python_env.models" = "models", "python_env.schemas" = "schemas", "python_env.services" = "services", "python_env.utils" = "utils" }

schemas/__init__.py

@@ -0,0 +1,13 @@
+"""Public schemas for the multi-domain analysis platform."""
+
+from .request import AnalyzeCodeRequest
+from .response import AnalyzeCodeResponse, AnalysisIssue, DomainAnalysis, ScoreBreakdown, StaticAnalysisSummary
+
+__all__ = [
+    "AnalyzeCodeRequest",
+    "AnalyzeCodeResponse",
+    "AnalysisIssue",
+    "DomainAnalysis",
+    "ScoreBreakdown",
+    "StaticAnalysisSummary",
+]

schemas/request.py

@@ -0,0 +1,19 @@
+"""Request schemas for code analysis endpoints and UI."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+DomainHint = Literal["auto", "dsa", "data_science", "ml_dl", "web"]
+
+
+class AnalyzeCodeRequest(BaseModel):
+    """Validated input payload for multi-domain code analysis."""
+
+    code: str = Field(..., min_length=1, description="Source code to analyze.")
+    context_window: str = Field(default="", max_length=2000, description="Optional repository or task context.")
+    traceback_text: str = Field(default="", max_length=2000, description="Optional runtime or test failure output.")
+    domain_hint: DomainHint = Field(default="auto", description="Optional domain override when auto detection is not desired.")

schemas/response.py

@@ -0,0 +1,70 @@
+"""Response schemas for the multi-domain analysis platform."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Literal
+
+from pydantic import BaseModel, Field
+
+
+DomainType = Literal["dsa", "data_science", "ml_dl", "web", "general"]
+Severity = Literal["low", "medium", "high"]
+
+
+class AnalysisIssue(BaseModel):
+    """One detected issue or risk in the code snippet."""
+
+    title: str
+    severity: Severity
+    description: str
+    line_hint: int | None = None
+
+
+class StaticAnalysisSummary(BaseModel):
+    """Language-agnostic static-analysis signals."""
+
+    syntax_valid: bool
+    syntax_error: str = ""
+    cyclomatic_complexity: int = Field(..., ge=1)
+    line_count: int = Field(..., ge=0)
+    max_loop_depth: int = Field(..., ge=0)
+    time_complexity: str = "Unknown"
+    space_complexity: str = "Unknown"
+    detected_imports: List[str] = Field(default_factory=list)
+    code_smells: List[str] = Field(default_factory=list)
+
+
+class DomainAnalysis(BaseModel):
+    """Domain-specific analysis payload returned by an analyzer."""
+
+    domain: DomainType
+    domain_score: float = Field(..., ge=0.0, le=1.0)
+    issues: List[AnalysisIssue] = Field(default_factory=list)
+    suggestions: List[str] = Field(default_factory=list)
+    highlights: Dict[str, float | str] = Field(default_factory=dict)
+
+
+class ScoreBreakdown(BaseModel):
+    """Reward inputs and final normalized score."""
+
+    ml_score: float = Field(..., ge=0.0, le=1.0)
+    domain_score: float = Field(..., ge=0.0, le=1.0)
+    lint_score: float = Field(..., ge=0.0, le=1.0)
+    complexity_penalty: float = Field(..., ge=0.0, le=1.0)
+    reward: float = Field(..., ge=0.0, le=1.0)
+
+
+class AnalyzeCodeResponse(BaseModel):
+    """Top-level structured output for API and UI consumers."""
+
+    detected_domain: DomainType
+    domain_confidences: Dict[str, float]
+    score_breakdown: ScoreBreakdown
+    static_analysis: StaticAnalysisSummary
+    domain_analysis: DomainAnalysis
+    improvement_plan: List[str] = Field(default_factory=list)
+    model_backend: str
+    model_id: str
+    summary: str
+    context_window: str = ""
+    analysis_time_ms: float = Field(..., ge=0.0)

server/__init__.py

@@ -0,0 +1,6 @@
+"""Server exports for python_code_review_env."""
+
+from .app import app
+from .env import PythonCodeReviewEnvironment
+
+__all__ = ["app", "PythonCodeReviewEnvironment"]

server/app.py

@@ -0,0 +1,52 @@
+"""FastAPI + Gradio entrypoint for TorchReview Copilot."""
+
+from __future__ import annotations
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as exc:  # pragma: no cover
+    raise ImportError(
+        "openenv-core is required to run the API server. Install project dependencies first."
+    ) from exc
+
+try:
+    import gradio as gr
+except Exception:
+    gr = None  # type: ignore[assignment]
+
+try:
+    from ..Models import PythonCodeReviewAction, PythonCodeReviewObservation
+    from .env import PythonCodeReviewEnvironment
+    from .demo import build_demo
+except ImportError:
+    from Models import PythonCodeReviewAction, PythonCodeReviewObservation
+    from server.env import PythonCodeReviewEnvironment
+    from server.demo import build_demo
+
+
+def build_application():
+    """Compose the OpenEnv API with the Gradio demo frontend."""
+
+    api_app = create_app(
+        PythonCodeReviewEnvironment,
+        PythonCodeReviewAction,
+        PythonCodeReviewObservation,
+        env_name="python_code_review_env",
+        max_concurrent_envs=4,
+    )
+    if gr is None:
+        return api_app
+    return gr.mount_gradio_app(api_app, build_demo(), path="/")
+
+
+app = build_application()
+
+
+def main(host: str = "0.0.0.0", port: int = 8000) -> None:
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/demo.py

@@ -0,0 +1,441 @@
+"""Gradio UI for TorchReview Copilot."""
+
+from __future__ import annotations
+
+from html import escape
+
+import gradio as gr
+
+try:
+    from ..triage import get_default_engine
+except ImportError:
+    from triage import get_default_engine
+
+
+CSS = """
+:root {
+  --paper: #f6f1e8;
+  --ink: #162521;
+  --accent: #d95d39;
+  --panel: #fffdf8;
+  --border: #d6c4b8;
+  --muted: #5f6f67;
+  --good: #2d7d62;
+  --warn: #b76516;
+  --high: #b23a48;
+}
+
+body, .gradio-container {
+  background:
+    radial-gradient(circle at top left, rgba(247, 197, 159, 0.35), transparent 35%),
+    linear-gradient(135deg, #f9f6ef 0%, #efe5d3 100%);
+  color: var(--ink);
+  font-family: Georgia, "Times New Roman", serif;
+}
+
+.gradio-container {
+  max-width: 1260px !important;
+}
+
+.hero-card,
+.metric-card,
+.subtle-card {
+  background: rgba(255, 253, 248, 0.95);
+  border: 1px solid var(--border);
+  border-radius: 20px;
+  box-shadow: 0 16px 40px rgba(22, 37, 33, 0.08);
+}
+
+.hero-card {
+  padding: 28px 30px;
+  margin-bottom: 12px;
+}
+
+.metric-card,
+.subtle-card {
+  padding: 20px 22px;
+}
+
+.eyebrow {
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  font-size: 12px;
+  color: var(--accent);
+  margin-bottom: 10px;
+}
+
+.hero-title {
+  font-size: 44px;
+  line-height: 1.05;
+  margin: 0 0 10px;
+}
+
+.hero-copy {
+  margin: 0;
+  font-size: 18px;
+  line-height: 1.55;
+  color: var(--muted);
+}
+
+.summary-title {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  align-items: center;
+  margin-bottom: 14px;
+}
+
+.pill {
+  display: inline-block;
+  padding: 6px 12px;
+  border-radius: 999px;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  background: #efe5d3;
+}
+
+.pill.low { color: var(--good); }
+.pill.medium { color: var(--warn); }
+.pill.high { color: var(--high); }
+
+.summary-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+  margin-top: 16px;
+}
+
+.summary-stat {
+  background: #fff7ef;
+  border-radius: 14px;
+  padding: 12px 14px;
+  border: 1px solid rgba(214, 196, 184, 0.8);
+}
+
+.summary-stat strong {
+  display: block;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--muted);
+  margin-bottom: 6px;
+}
+
+.radar-wrap {
+  display: grid;
+  gap: 12px;
+}
+
+.bar {
+  display: grid;
+  gap: 6px;
+}
+
+.bar-head {
+  display: flex;
+  justify-content: space-between;
+  font-size: 13px;
+  color: var(--muted);
+}
+
+.bar-track {
+  width: 100%;
+  height: 12px;
+  background: #f2e5d6;
+  border-radius: 999px;
+  overflow: hidden;
+}
+
+.bar-fill {
+  height: 100%;
+  border-radius: 999px;
+}
+
+.matched-box {
+  background: #fff7ef;
+  border: 1px solid rgba(214, 196, 184, 0.8);
+  border-radius: 16px;
+  padding: 14px;
+}
+
+.how-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.how-step {
+  background: rgba(255, 253, 248, 0.9);
+  border: 1px solid var(--border);
+  border-radius: 18px;
+  padding: 16px;
+}
+
+@media (max-width: 900px) {
+  .hero-title {
+    font-size: 34px;
+  }
+
+  .summary-grid,
+  .how-grid {
+    grid-template-columns: 1fr;
+  }
+}
+"""
+
+
+def _default_outputs() -> tuple[str, str, str, str, str]:
+    return (
+        "<div class='metric-card'><div class='eyebrow'>Awaiting Analysis</div><p class='hero-copy'>Paste Python code, add an optional traceback, or load one of the built-in examples.</p></div>",
+        "<div class='metric-card'><div class='eyebrow'>Live Triage Radar</div><p class='hero-copy'>Confidence bars will appear after the first analysis run.</p></div>",
+        "### Improvement Plan\nAnalyze a sample to generate syntax, edge-case, and scalability recommendations.",
+        "### Known Pattern Match\nThe nearest OpenEnv task will be highlighted here after inference runs.",
+        "### Model Notes\nBackend and extracted signal details will appear here.",
+    )
+
+
+def _summary_html(result) -> str:
+    issue = escape(result.issue_label.title())
+    summary = escape(result.summary)
+    next_action = escape(result.suggested_next_action)
+    return f"""
+    <div class="metric-card">
+      <div class="summary-title">
+        <div>
+          <div class="eyebrow">TorchReview Verdict</div>
+          <h3 style="margin:0;font-size:30px;">{issue} Issue</h3>
+        </div>
+        <span class="pill {escape(result.repair_risk)}">{escape(result.repair_risk)} repair risk</span>
+      </div>
+      <p class="hero-copy">{summary}</p>
+        <div class="summary-grid">
+        <div class="summary-stat">
+          <strong>Reward Score</strong>
+          {result.reward_score:.0%}
+        </div>
+        <div class="summary-stat">
+          <strong>ML Quality</strong>
+          {result.ml_quality_score:.0%}
+        </div>
+        <div class="summary-stat">
+          <strong>Matched Pattern</strong>
+          {escape(result.matched_pattern.title)}
+        </div>
+        <div class="summary-stat">
+          <strong>Inference Backend</strong>
+          {escape(result.model_backend)}
+        </div>
+        <div class="summary-stat">
+          <strong>Lint Score</strong>
+          {result.lint_score:.0%}
+        </div>
+        <div class="summary-stat">
+          <strong>Complexity Penalty</strong>
+          {result.complexity_penalty:.0%}
+        </div>
+        <div class="summary-stat">
+          <strong>Next Action</strong>
+          {next_action}
+        </div>
+      </div>
+    </div>
+    """
+
+
+def _radar_html(result) -> str:
+    colors = {
+        "syntax": "#d95d39",
+        "logic": "#4f772d",
+        "performance": "#355070",
+    }
+    bars = []
+    for label, score in result.confidence_scores.items():
+        bars.append(
+            f"""
+            <div class="bar">
+              <div class="bar-head"><span>{escape(label.title())}</span><span>{score:.0%}</span></div>
+              <div class="bar-track">
+                <div class="bar-fill" style="width:{score * 100:.1f}%; background:{colors.get(label, '#d95d39')};"></div>
+              </div>
+            </div>
+            """
+        )
+    return f"""
+    <div class="metric-card radar-wrap">
+      <div class="eyebrow">Live Triage Radar</div>
+      {''.join(bars)}
+      <div class="matched-box">
+        <strong>Nearest Known Pattern:</strong> {escape(result.matched_pattern.title)}<br>
+        <span style="color:#5f6f67;">{escape(result.matched_pattern.summary)}</span>
+      </div>
+    </div>
+    """
+
+
+def _plan_markdown(result) -> str:
+    plan_lines = "\n".join(f"{index + 1}. {step}" for index, step in enumerate(result.repair_plan))
+    return (
+        "### Improvement Plan\n"
+        f"**Primary issue:** `{result.issue_label}`\n\n"
+        f"{plan_lines}\n\n"
+        f"**Suggested next action:** {result.suggested_next_action}"
+    )
+
+
+def _match_markdown(result) -> str:
+    return (
+        "### Known Pattern Match\n"
+        f"**Task:** `{result.matched_pattern.task_id}`  \n"
+        f"**Title:** {result.matched_pattern.title}  \n"
+        f"**Why it matched:** {result.matched_pattern.rationale}  \n"
+        f"**Similarity:** {result.matched_pattern.similarity:.0%}"
+    )
+
+
+def _model_markdown(result) -> str:
+    signal_lines = "\n".join(
+        f"- `{signal.name}` -> {signal.value} ({signal.impact}, weight {signal.weight:.2f}): {signal.evidence}"
+        for signal in result.extracted_signals
+    ) or "- No strong static signals were extracted."
+    notes = "\n".join(f"- {item}" for item in result.inference_notes) or "- No additional backend notes."
+    return (
+        "### Model Notes\n"
+        f"- **Model backend:** `{result.model_backend}`\n"
+        f"- **Model id:** `{result.model_id}`\n"
+        f"- **Analysis time:** `{result.analysis_time_ms:.2f} ms`\n\n"
+        "### Reward Formula\n"
+        f"- `reward = (0.5 x {result.ml_quality_score:.2f}) + (0.3 x {result.lint_score:.2f}) - (0.2 x {result.complexity_penalty:.2f})`\n"
+        f"- **Final reward:** `{result.reward_score:.2f}`\n\n"
+        "### Extracted Signals\n"
+        f"{signal_lines}\n\n"
+        "### Backend Notes\n"
+        f"{notes}"
+    )
+
+
+def analyze_inputs(code: str, traceback_text: str, context_window: str) -> tuple[str, str, str, str, str]:
+    """Run the triage engine and format outputs for the Gradio UI."""
+
+    result = get_default_engine().triage(code or "", traceback_text or "", context_window or "")
+    return (
+        _summary_html(result),
+        _radar_html(result),
+        _plan_markdown(result),
+        _match_markdown(result),
+        _model_markdown(result),
+    )
+
+
+def load_example(example_key: str) -> tuple[str, str, str, str, str, str, str, str, str]:
+    """Populate the UI from a built-in example and immediately analyze it."""
+
+    example = get_default_engine().example_map()[example_key]
+    outputs = analyze_inputs(example.code, example.traceback_text, example.context_window)
+    header = (
+        f"### Example Scenario\n"
+        f"**{example.title}**  \n"
+        f"{example.summary}  \n"
+        f"Label target: `{example.label}`"
+    )
+    return (example.code, example.traceback_text, example.context_window, header, *outputs)
+
+
+def build_demo() -> gr.Blocks:
+    """Create the TorchReview Copilot Gradio application."""
+
+    examples = get_default_engine().example_map()
+    first_example = next(iter(examples.values()))
+
+    with gr.Blocks(theme=gr.themes.Soft(primary_hue="orange", secondary_hue="amber"), css=CSS, title="TorchReview Copilot") as demo:
+        gr.HTML(
+            """
+            <div class="hero-card">
+              <div class="eyebrow">Meta PyTorch OpenEnv Hackathon Demo</div>
+              <h1 class="hero-title">TorchReview Copilot</h1>
+              <p class="hero-copy">
+                AI-powered code review and improvement system using PyTorch to score code quality, surface bugs,
+                and generate a three-step improvement plan. OpenEnv stays underneath as the deterministic validation engine.
+              </p>
+            </div>
+            """
+        )
+
+        with gr.Row():
+            with gr.Column(scale=6):
+                example_choice = gr.Radio(
+                    choices=[(item.title, item.key) for item in examples.values()],
+                    value=first_example.key,
+                    label="Try a built-in failure scenario",
+                    info="Switching examples updates the Live Triage Radar immediately.",
+                )
+                example_header = gr.Markdown()
+                code_input = gr.Code(
+                    value=first_example.code,
+                    language="python",
+                    lines=18,
+                    label="Python code under review",
+                )
+                traceback_input = gr.Textbox(
+                    value=first_example.traceback_text,
+                    lines=7,
+                    label="Optional traceback / failing test output",
+                    placeholder="Paste stack traces, assertion failures, or benchmark notes here.",
+                )
+                context_input = gr.Textbox(
+                    value=first_example.context_window,
+                    lines=4,
+                    label="Context window",
+                    placeholder="Describe expected behavior, constraints, or repository context.",
+                )
+                with gr.Row():
+                    analyze_button = gr.Button("Analyze & Score Code", variant="primary")
+                    clear_button = gr.Button("Clear Inputs", variant="secondary")
+
+            with gr.Column(scale=5):
+                summary_html = gr.HTML()
+                radar_html = gr.HTML()
+                plan_markdown = gr.Markdown()
+                match_markdown = gr.Markdown()
+                model_markdown = gr.Markdown()
+
+        gr.HTML(
+            """
+            <div class="subtle-card" style="margin-top: 12px;">
+              <div class="eyebrow">How It Works</div>
+              <div class="how-grid">
+                <div class="how-step"><strong>Input</strong><br>Code plus optional traceback or benchmark signal.</div>
+                <div class="how-step"><strong>Processing</strong><br>Static checks extract parser, lint, complexity, and runtime clues.</div>
+                <div class="how-step"><strong>Model</strong><br>CodeBERTa embeddings run through PyTorch and score code quality against known OpenEnv patterns.</div>
+                <div class="how-step"><strong>Output</strong><br>Confidence radar, reward score, and a three-step improvement plan.</div>
+              </div>
+            </div>
+            """
+        )
+
+        example_choice.change(
+            fn=load_example,
+            inputs=example_choice,
+            outputs=[code_input, traceback_input, context_input, example_header, summary_html, radar_html, plan_markdown, match_markdown, model_markdown],
+            show_progress="hidden",
+        )
+        analyze_button.click(
+            fn=analyze_inputs,
+            inputs=[code_input, traceback_input, context_input],
+            outputs=[summary_html, radar_html, plan_markdown, match_markdown, model_markdown],
+            show_progress="minimal",
+        )
+        clear_button.click(
+            fn=lambda: ("", "", "", "### Example Scenario\nChoose a built-in example or paste custom code.", *_default_outputs()),
+            inputs=None,
+            outputs=[code_input, traceback_input, context_input, example_header, summary_html, radar_html, plan_markdown, match_markdown, model_markdown],
+            show_progress="hidden",
+        )
+        demo.load(
+            fn=load_example,
+            inputs=example_choice,
+            outputs=[code_input, traceback_input, context_input, example_header, summary_html, radar_html, plan_markdown, match_markdown, model_markdown],
+            show_progress="hidden",
+        )
+
+    return demo

server/env.py

@@ -0,0 +1,396 @@
+"""OpenEnv environment implementation for Python code review tasks."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import EnvironmentMetadata
+
+try:
+    from ..graders import grade_task
+    from ..graders.shared import component_score, safe_ratio, strict_score
+    from ..Models import (
+        HistoryEntry,
+        PythonCodeReviewAction,
+        PythonCodeReviewObservation,
+        PythonCodeReviewState,
+        RewardDetails,
+        TaskGrade,
+    )
+    from ..tasks import ReviewTask, list_tasks, select_task
+except ImportError:
+    from graders import grade_task
+    from graders.shared import component_score, safe_ratio, strict_score
+    from Models import (
+        HistoryEntry,
+        PythonCodeReviewAction,
+        PythonCodeReviewObservation,
+        PythonCodeReviewState,
+        RewardDetails,
+        TaskGrade,
+    )
+    from tasks import ReviewTask, list_tasks, select_task
+
+
+def _empty_grade() -> TaskGrade:
+    return TaskGrade(
+        score=component_score(0.01),
+        syntax_score=component_score(0.01),
+        tests_passed=0,
+        tests_total=0,
+        quality_score=component_score(0.01),
+        runtime_score=component_score(0.01),
+    )
+
+
+def _reward_value(value: float) -> float:
+    return strict_score(value)
+
+
+class PythonCodeReviewEnvironment(
+    Environment[PythonCodeReviewAction, PythonCodeReviewObservation, PythonCodeReviewState]
+):
+    """Structured environment for deterministic Python code review workflows."""
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self, verbose: bool = False, **_: Any) -> None:
+        super().__init__()
+        self.verbose = verbose
+        self._task: ReviewTask = list_tasks()[0]
+        self._current_code: str = self._task.starter_code
+        self._history: list[HistoryEntry] = []
+        self._last_reward = RewardDetails(value=0.1, reason="Environment initialized.")
+        self._current_grade = _empty_grade()
+        self._state = PythonCodeReviewState(episode_id=str(uuid4()), step_count=0)
+        self.reset()
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> PythonCodeReviewObservation:
+        task_id = kwargs.get("task_id")
+        self._task = select_task(seed=seed, task_id=task_id)
+        self._current_code = self._task.starter_code
+        self._history = []
+        self._last_reward = RewardDetails(value=0.1, reason="Environment reset.")
+        self._current_grade = grade_task(self._task, self._current_code, include_hidden=False)
+
+        self._state = PythonCodeReviewState(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+            task_id=self._task.task_id,
+            difficulty=self._task.difficulty,
+            task_kind=self._task.task_kind,
+            attempts_remaining=self._task.max_steps,
+            current_code=self._current_code,
+            errors=self._format_errors(self._current_grade),
+            test_results=self._format_test_results(self._current_grade),
+            history=[],
+            score=self._current_grade.score,
+            done=False,
+        )
+        return self._build_observation(
+            grade=self._current_grade,
+            status=f"Loaded task {self._task.task_id}.",
+            reward_details=self._last_reward,
+        )
+
+    def step(
+        self,
+        action: PythonCodeReviewAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> PythonCodeReviewObservation:
+        observation, _, _, _ = self._step_transition(action, timeout_s=timeout_s, **kwargs)
+        return observation
+
+    def step_result(
+        self,
+        action: PythonCodeReviewAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Tuple[PythonCodeReviewObservation, float, bool, Dict[str, Any]]:
+        """Gym-style helper used by local scripts and tests."""
+
+        return self._step_transition(action, timeout_s=timeout_s, **kwargs)
+
+    def _step_transition(
+        self,
+        action: PythonCodeReviewAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Tuple[PythonCodeReviewObservation, float, bool, Dict[str, Any]]:
+        if self._state.done:
+            reward = RewardDetails(
+                value=_reward_value(0.05 + 0.25 * self._current_grade.score),
+                reason="Episode already finished. Call reset() to continue.",
+            )
+            observation = self._build_observation(
+                grade=self._current_grade,
+                status="Episode already finished.",
+                reward_details=reward,
+            )
+            return observation, reward.value, observation.done, {"task_id": observation.task_id, "score": observation.score}
+
+        previous_grade = self._current_grade
+        status = ""
+        invalid_action = False
+        code_changed = False
+        use_hidden_grading = False
+
+        if action.action_type == "edit_code":
+            if not action.code or not action.code.strip():
+                invalid_action = True
+                status = "edit_code requires a non-empty code payload."
+            else:
+                code_changed = action.code != self._current_code
+                self._current_code = action.code
+                status = "Updated working copy from agent patch."
+        elif action.action_type == "submit_solution":
+            if action.code is not None and action.code.strip():
+                code_changed = action.code != self._current_code
+                self._current_code = action.code
+            use_hidden_grading = True
+            status = "Submission received for final grading."
+        elif action.action_type == "run_tests":
+            status = "Executed public validation suite."
+        elif action.action_type == "analyze_code":
+            status = "Generated static review summary."
+        else:  # pragma: no cover
+            invalid_action = True
+            status = f"Unsupported action_type: {action.action_type}"
+
+        self._state.step_count += 1
+
+        if invalid_action:
+            current_grade = previous_grade
+        else:
+            current_grade = grade_task(
+                self._task,
+                self._current_code,
+                include_hidden=use_hidden_grading,
+                timeout_s=timeout_s or 3.0,
+            )
+            if action.action_type == "analyze_code":
+                status = self._analysis_status(current_grade)
+            elif action.action_type == "run_tests":
+                status = self._run_tests_status(current_grade, use_hidden_grading)
+            elif action.action_type == "submit_solution":
+                status = self._submission_status(current_grade)
+
+        done = use_hidden_grading or self._state.step_count >= self._task.max_steps
+        if self._state.step_count >= self._task.max_steps and not use_hidden_grading:
+            status = f"{status} Step budget exhausted."
+
+        reward_details = self._compute_reward(
+            previous_grade=previous_grade,
+            current_grade=current_grade,
+            action=action,
+            invalid_action=invalid_action,
+            timed_out=current_grade.timed_out,
+            code_changed=code_changed,
+            final_submission=use_hidden_grading,
+        )
+
+        self._history.append(
+            HistoryEntry(
+                step=self._state.step_count,
+                action_type=action.action_type,
+                status=status,
+                reward=reward_details.value,
+            )
+        )
+
+        self._current_grade = current_grade
+        self._last_reward = reward_details
+        attempts_remaining = max(self._task.max_steps - self._state.step_count, 0)
+
+        self._state.task_id = self._task.task_id
+        self._state.difficulty = self._task.difficulty
+        self._state.task_kind = self._task.task_kind
+        self._state.attempts_remaining = attempts_remaining
+        self._state.current_code = self._current_code
+        self._state.errors = self._format_errors(current_grade)
+        self._state.test_results = self._format_test_results(current_grade)
+        self._state.history = list(self._history)
+        self._state.score = current_grade.score
+        self._state.done = done
+
+        observation = self._build_observation(
+            grade=current_grade,
+            status=status,
+            reward_details=reward_details,
+        )
+        return observation, reward_details.value, observation.done, {"task_id": observation.task_id, "score": observation.score}
+
+    @property
+    def state(self) -> PythonCodeReviewState:
+        return self._state
+
+    def _build_observation(
+        self,
+        *,
+        grade: TaskGrade,
+        status: str,
+        reward_details: RewardDetails,
+    ) -> PythonCodeReviewObservation:
+        return PythonCodeReviewObservation(
+            task_id=self._task.task_id,
+            title=self._task.title,
+            difficulty=self._task.difficulty,
+            task_kind=self._task.task_kind,
+            task_description=self._task.task_description,
+            current_code=self._current_code,
+            errors=self._format_errors(grade),
+            test_results=self._format_test_results(grade),
+            visible_tests=list(self._task.visible_tests),
+            history=list(self._history),
+            attempts_remaining=self._state.attempts_remaining,
+            last_action_status=status,
+            score=grade.score,
+            reward=reward_details.value,
+            done=self._state.done,
+            reward_details=reward_details,
+            metadata={
+                "goal": self._task.goal,
+                "repo_summary": self._task.repo_summary,
+                "changed_files": self._task.changed_files,
+                "available_files": self._task.available_files,
+                "grade_details": grade.details,
+            },
+        )
+
+    def _compute_reward(
+        self,
+        *,
+        previous_grade: TaskGrade,
+        current_grade: TaskGrade,
+        action: PythonCodeReviewAction,
+        invalid_action: bool,
+        timed_out: bool,
+        code_changed: bool,
+        final_submission: bool,
+    ) -> RewardDetails:
+        prev_score = previous_grade.score
+        curr_score = current_grade.score
+        prev_rate = safe_ratio(previous_grade.tests_passed, previous_grade.tests_total)
+        curr_rate = safe_ratio(current_grade.tests_passed, current_grade.tests_total)
+
+        syntax_reward = 0.14 if previous_grade.syntax_score < 0.9 and current_grade.syntax_score >= 0.9 else 0.0
+        test_reward = round(max(curr_rate - prev_rate, 0.0) * 0.22, 3)
+        progress_delta = round(max(curr_score - prev_score, 0.0) * 0.35, 3)
+        quality_bonus = round(max(current_grade.quality_score - previous_grade.quality_score, 0.0) * 0.08, 3)
+        correctness_bonus = 0.12 if final_submission and curr_score >= 0.94 and prev_score < 0.94 else 0.0
+
+        invalid_action_penalty = 0.12 if invalid_action else 0.0
+        timeout_penalty = 0.14 if timed_out else 0.0
+        regression_penalty = round(max(prev_score - curr_score, 0.0) * 0.2, 3)
+        stagnation_penalty = 0.06 if action.action_type == "edit_code" and not code_changed else 0.0
+
+        raw_value = (
+            0.1
+            + 0.45 * curr_score
+            + syntax_reward
+            + test_reward
+            + progress_delta
+            + quality_bonus
+            + correctness_bonus
+            - invalid_action_penalty
+            - timeout_penalty
+            - regression_penalty
+            - stagnation_penalty
+        )
+        value = _reward_value(raw_value)
+
+        reason_parts = []
+        if syntax_reward:
+            reason_parts.append("syntax fixed")
+        if test_reward:
+            reason_parts.append("public test progress")
+        if progress_delta:
+            reason_parts.append("overall score improved")
+        if quality_bonus:
+            reason_parts.append("code quality improved")
+        if correctness_bonus:
+            reason_parts.append("full correctness bonus")
+        if invalid_action_penalty:
+            reason_parts.append("invalid action penalty")
+        if timeout_penalty:
+            reason_parts.append("timeout penalty")
+        if regression_penalty:
+            reason_parts.append("regression penalty")
+        if stagnation_penalty:
+            reason_parts.append("unchanged patch penalty")
+        if not reason_parts:
+            reason_parts.append("no meaningful state change")
+
+        return RewardDetails(
+            value=value,
+            syntax_reward=syntax_reward,
+            test_reward=test_reward,
+            correctness_bonus=correctness_bonus,
+            quality_bonus=quality_bonus,
+            progress_delta=progress_delta,
+            invalid_action_penalty=invalid_action_penalty,
+            timeout_penalty=timeout_penalty,
+            regression_penalty=regression_penalty,
+            stagnation_penalty=stagnation_penalty,
+            reason=", ".join(reason_parts),
+            prev_score=prev_score,
+            curr_score=curr_score,
+            code_changed=code_changed,
+        )
+
+    def _format_errors(self, grade: TaskGrade) -> str:
+        compile_error = str(grade.details.get("compile_error", "")).strip()
+        if compile_error:
+            return compile_error
+        return "Code parses successfully."
+
+    def _format_test_results(self, grade: TaskGrade) -> str:
+        parts = [grade.details.get("test_summary", "No test feedback available.")]
+        benchmark = grade.details.get("benchmark")
+        if isinstance(benchmark, dict):
+            parts.append(
+                "Benchmark: "
+                f"candidate {benchmark['candidate_seconds']}s vs baseline {benchmark['baseline_seconds']}s "
+                f"(x{benchmark['improvement_ratio']})."
+            )
+        elif isinstance(benchmark, str) and benchmark:
+            parts.append(f"Benchmark: {benchmark}")
+        return "\n".join(part for part in parts if part)
+
+    def _analysis_status(self, grade: TaskGrade) -> str:
+        notes = grade.details.get("quality_notes", [])
+        quality_note = notes[0] if notes else "No major static quality issues detected."
+        return (
+            f"Syntax score {grade.syntax_score:.2f}; "
+            f"public tests {grade.tests_passed}/{grade.tests_total}; "
+            f"quality {grade.quality_score:.2f}. {quality_note}"
+        )
+
+    def _run_tests_status(self, grade: TaskGrade, include_hidden: bool) -> str:
+        visibility = "full" if include_hidden else "public"
+        return f"Ran {visibility} tests: {grade.tests_passed}/{grade.tests_total} passed."
+
+    def _submission_status(self, grade: TaskGrade) -> str:
+        runtime_text = ""
+        if isinstance(grade.details.get("benchmark"), dict):
+            runtime_text = f" runtime {grade.runtime_score:.2f};"
+        return (
+            f"Submission graded with score {grade.score:.2f}; "
+            f"tests {grade.tests_passed}/{grade.tests_total};"
+            f"{runtime_text} quality {grade.quality_score:.2f}."
+        )
+
+    def get_metadata(self) -> EnvironmentMetadata:
+        return EnvironmentMetadata(
+            name="python_code_review_env",
+            description="Production-style Python code review environment with deterministic grading.",
+            version="1.0.0",
+        )

server/python_env_environment.py

@@ -0,0 +1,3 @@
+"""Backward-compatible import shim for the environment class."""
+
+from .env import PythonCodeReviewEnvironment, PythonCodeReviewEnvironment as PythonEnvironment

server/requirements.txt

@@ -0,0 +1,9 @@
+openenv-core[core]>=0.2.2
+fastapi>=0.111.0
+gradio>=5.26.0
+uvicorn>=0.30.0
+pytest>=8.0.0
+openai>=1.76.0
+streamlit>=1.44.0
+torch>=2.2.0
+transformers>=4.45.0

services/__init__.py

@@ -0,0 +1,7 @@
+"""Service layer for orchestrating analysis, suggestions, and rewards."""
+
+from .analysis_service import AnalysisService
+from .reward_service import RewardService
+from .suggestion_service import SuggestionService
+
+__all__ = ["AnalysisService", "RewardService", "SuggestionService"]

services/analysis_service.py

@@ -0,0 +1,133 @@
+"""Orchestration layer for multi-domain code analysis."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict
+
+from analyzers import analyze_data_science_code, analyze_dsa_code, analyze_ml_code, analyze_web_code
+from models import PyTorchCodeAnalyzerModel
+from schemas.request import AnalyzeCodeRequest
+from schemas.response import AnalyzeCodeResponse, DomainAnalysis, StaticAnalysisSummary
+from services.reward_service import RewardService
+from services.suggestion_service import SuggestionService
+from utils import estimate_complexity, parse_code_structure
+
+
+def _lint_score(parsed: Dict[str, Any]) -> float:
+    """Convert structural smells into a normalized lint-style score."""
+
+    score = 1.0
+    if not parsed.get("syntax_valid", True):
+        score -= 0.45
+    score -= min(parsed.get("long_lines", 0), 5) * 0.03
+    if parsed.get("tabs_used"):
+        score -= 0.1
+    if parsed.get("trailing_whitespace_lines"):
+        score -= 0.05
+    if parsed.get("docstring_ratio", 0.0) == 0.0 and parsed.get("function_names"):
+        score -= 0.08
+    return round(max(0.0, min(1.0, score)), 4)
+
+
+class AnalysisService:
+    """End-to-end analysis pipeline shared by API and UI."""
+
+    def __init__(self) -> None:
+        self.model = PyTorchCodeAnalyzerModel()
+        self.reward_service = RewardService()
+        self.suggestion_service = SuggestionService()
+        self._analyzers: Dict[str, Callable[[str, Dict[str, Any], Dict[str, Any]], DomainAnalysis]] = {
+            "dsa": analyze_dsa_code,
+            "data_science": analyze_data_science_code,
+            "ml_dl": analyze_ml_code,
+            "web": analyze_web_code,
+        }
+
+    def _heuristic_domain_scores(self, parsed: Dict[str, Any], code: str) -> Dict[str, float]:
+        """Derive domain priors from imports and syntax-level hints."""
+
+        scores = {
+            "dsa": 0.2 + (0.15 if parsed.get("uses_recursion") else 0.0) + (0.15 if parsed.get("max_loop_depth", 0) >= 1 else 0.0),
+            "data_science": 0.2 + (0.35 if parsed.get("uses_pandas") or parsed.get("uses_numpy") else 0.0),
+            "ml_dl": 0.2 + (0.35 if parsed.get("uses_torch") or parsed.get("uses_sklearn") else 0.0),
+            "web": 0.2 + (0.35 if parsed.get("uses_fastapi") or parsed.get("uses_flask") else 0.0) + (0.1 if parsed.get("route_decorators") else 0.0),
+            "general": 0.2,
+        }
+        if "fastapi" in code.lower():
+            scores["web"] += 0.1
+        if "pandas" in code.lower() or "numpy" in code.lower():
+            scores["data_science"] += 0.1
+        if "torch" in code.lower():
+            scores["ml_dl"] += 0.1
+        if "while" in code or "for" in code:
+            scores["dsa"] += 0.05
+        return {key: round(min(value, 0.99), 4) for key, value in scores.items()}
+
+    def analyze(self, request: AnalyzeCodeRequest) -> AnalyzeCodeResponse:
+        """Run the complete multi-domain analysis pipeline."""
+
+        started = time.perf_counter()
+        parsed = parse_code_structure(request.code)
+        complexity = estimate_complexity(parsed, request.code)
+        model_prediction = self.model.predict(request.code, request.context_window, parsed)
+        heuristic_scores = self._heuristic_domain_scores(parsed, request.code)
+
+        combined_scores = {}
+        for domain, heuristic_score in heuristic_scores.items():
+            model_score = float(model_prediction["domain_scores"].get(domain, 0.2))
+            combined_scores[domain] = round((0.6 * model_score) + (0.4 * heuristic_score), 4)
+
+        detected_domain = request.domain_hint if request.domain_hint != "auto" else max(combined_scores, key=combined_scores.get)
+        analyzer = self._analyzers.get(detected_domain)
+        domain_analysis = (
+            analyzer(request.code, parsed, complexity)
+            if analyzer is not None
+            else DomainAnalysis(
+                domain="general",
+                domain_score=0.6,
+                issues=[],
+                suggestions=["Add stronger domain-specific context for deeper analysis."],
+                highlights={},
+            )
+        )
+
+        lint_score = _lint_score(parsed)
+        score_breakdown = self.reward_service.compute(
+            ml_score=float(model_prediction["ml_quality_score"]),
+            domain_score=domain_analysis.domain_score,
+            lint_score=lint_score,
+            complexity_penalty=float(complexity["complexity_penalty"]),
+        )
+        static_analysis = StaticAnalysisSummary(
+            syntax_valid=bool(parsed["syntax_valid"]),
+            syntax_error=str(parsed["syntax_error"]),
+            cyclomatic_complexity=int(complexity["cyclomatic_complexity"]),
+            line_count=int(parsed["line_count"]),
+            max_loop_depth=int(parsed["max_loop_depth"]),
+            time_complexity=str(complexity["time_complexity"]),
+            space_complexity=str(complexity["space_complexity"]),
+            detected_imports=list(parsed["imports"]),
+            code_smells=list(parsed["code_smells"]),
+        )
+        improvement_plan = self.suggestion_service.build_improvement_plan(
+            domain_analysis=domain_analysis,
+            static_analysis=static_analysis,
+        )
+        summary = (
+            f"Detected `{detected_domain}` code with a model score of {score_breakdown.ml_score:.0%}, "
+            f"domain score {score_breakdown.domain_score:.0%}, and final reward {score_breakdown.reward:.0%}."
+        )
+        return AnalyzeCodeResponse(
+            detected_domain=detected_domain,  # type: ignore[arg-type]
+            domain_confidences=combined_scores,
+            score_breakdown=score_breakdown,
+            static_analysis=static_analysis,
+            domain_analysis=domain_analysis,
+            improvement_plan=improvement_plan,
+            model_backend=str(model_prediction["backend_name"]),
+            model_id=str(model_prediction["model_id"]),
+            summary=summary,
+            context_window=request.context_window,
+            analysis_time_ms=round((time.perf_counter() - started) * 1000.0, 2),
+        )

services/reward_service.py

@@ -0,0 +1,27 @@
+"""Reward shaping logic for RL-ready code analysis scores."""
+
+from __future__ import annotations
+
+from schemas.response import ScoreBreakdown
+
+
+class RewardService:
+    """Compute reward scores from model, domain, lint, and complexity signals."""
+
+    def compute(self, *, ml_score: float, domain_score: float, lint_score: float, complexity_penalty: float) -> ScoreBreakdown:
+        """Apply the weighted reward formula and clamp the result."""
+
+        reward = max(
+            0.0,
+            min(
+                1.0,
+                (0.4 * ml_score) + (0.2 * domain_score) + (0.2 * lint_score) - (0.2 * complexity_penalty),
+            ),
+        )
+        return ScoreBreakdown(
+            ml_score=round(ml_score, 4),
+            domain_score=round(domain_score, 4),
+            lint_score=round(lint_score, 4),
+            complexity_penalty=round(complexity_penalty, 4),
+            reward=round(reward, 4),
+        )

services/suggestion_service.py

@@ -0,0 +1,28 @@
+"""Suggestion and improvement-plan generation for analyzed code."""
+
+from __future__ import annotations
+
+from schemas.response import DomainAnalysis, StaticAnalysisSummary
+
+
+class SuggestionService:
+    """Build high-signal improvement steps from analysis output."""
+
+    def build_improvement_plan(self, *, domain_analysis: DomainAnalysis, static_analysis: StaticAnalysisSummary) -> list[str]:
+        """Return a compact three-step plan optimized for developer action."""
+
+        primary_issue = (
+            domain_analysis.issues[0].description
+            if domain_analysis.issues
+            else "Stabilize correctness first and keep the public behavior explicit."
+        )
+
+        step_one = f"Step 1 - Correctness and safety: {primary_issue}"
+        step_two = "Step 2 - Edge cases: test empty inputs, boundary values, malformed payloads, and failure-mode behavior explicitly."
+        step_three = "Step 3 - Scalability: reduce repeated scans, lower cyclomatic complexity, and benchmark the path on realistic input sizes."
+
+        if domain_analysis.suggestions:
+            step_three = f"{step_three} Priority hint: {domain_analysis.suggestions[0]}"
+        if not static_analysis.syntax_valid:
+            step_one = f"Step 1 - Correctness and safety: fix the syntax error first ({static_analysis.syntax_error})."
+        return [step_one, step_two, step_three]

tasks/__init__.py

@@ -0,0 +1,12 @@
+"""Task catalog for python_code_review_env."""
+
+from .catalog import ReviewTask, get_task, list_tasks, select_task
+
+
+def task_ids() -> list[str]:
+    """Return stable task identifiers for validators."""
+
+    return [task.task_id for task in list_tasks()]
+
+
+__all__ = ["ReviewTask", "get_task", "list_tasks", "select_task", "task_ids"]

tasks/catalog.py

@@ -0,0 +1,324 @@
+"""Deterministic task definitions for the code review environment."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from textwrap import dedent
+from typing import Any, Dict, List, Optional
+
+
+def _code(value: str) -> str:
+    return dedent(value).strip() + "\n"
+
+
+@dataclass(frozen=True)
+class CallCase:
+    """One executable function call used by graders."""
+
+    label: str
+    args: tuple[Any, ...] = ()
+    kwargs: Dict[str, Any] = field(default_factory=dict)
+    expected: Any = None
+
+
+@dataclass(frozen=True)
+class ReviewTask:
+    """Static task definition."""
+
+    task_id: str
+    title: str
+    difficulty: str
+    task_kind: str
+    task_description: str
+    starter_code: str
+    reference_code: str
+    function_name: str
+    visible_tests: List[str]
+    public_cases: List[CallCase]
+    hidden_cases: List[CallCase]
+    repo_summary: str
+    changed_files: List[str]
+    available_files: List[str]
+    goal: str
+    max_steps: int
+    benchmark_config: Optional[Dict[str, int]] = None
+
+
+TASKS: List[ReviewTask] = [
+    ReviewTask(
+        task_id="syntax_fix_invoice_totals",
+        title="Fix the invoice total syntax regression",
+        difficulty="easy",
+        task_kind="syntax_fix",
+        task_description=(
+            "A recent refactor broke the helper that normalizes invoice totals before "
+            "daily reconciliation. Repair the Python syntax so the function compiles "
+            "and returns the correct total for mixed integer and string inputs."
+        ),
+        starter_code=_code(
+            """
+            def normalize_invoice_totals(records):
+                cleaned = []
+                for record in records
+                    if "total" not in record:
+                        continue
+                    value = int(record["total"])
+                    cleaned.append(value)
+                return sum(cleaned
+            """
+        ),
+        reference_code=_code(
+            '''
+            def normalize_invoice_totals(records):
+                """Return the sum of invoice totals that are present in the payload."""
+                cleaned = []
+                for record in records:
+                    if "total" not in record:
+                        continue
+                    cleaned.append(int(record["total"]))
+                return sum(cleaned)
+            '''
+        ),
+        function_name="normalize_invoice_totals",
+        visible_tests=[
+            "normalize_invoice_totals([{'total': '4'}, {'total': 5}, {}]) == 9",
+            "normalize_invoice_totals([]) == 0",
+        ],
+        public_cases=[
+            CallCase(
+                label="mixed string and int totals",
+                args=([{"total": "4"}, {"total": 5}, {}],),
+                expected=9,
+            ),
+            CallCase(label="empty input", args=([],), expected=0),
+        ],
+        hidden_cases=[
+            CallCase(
+                label="skip missing totals",
+                args=([{}, {"total": "2"}, {"total": "8"}],),
+                expected=10,
+            ),
+            CallCase(
+                label="handle negative adjustments",
+                args=([{"total": "11"}, {"total": -3}],),
+                expected=8,
+            ),
+        ],
+        repo_summary=(
+            "services/billing/reconciliation.py computes end-of-day invoice totals for "
+            "a CPU-only batch job."
+        ),
+        changed_files=["services/billing/reconciliation.py"],
+        available_files=["services/billing/reconciliation.py", "tests/test_reconciliation.py"],
+        goal="Restore a compiling implementation for invoice total normalization.",
+        max_steps=6,
+    ),
+    ReviewTask(
+        task_id="bug_fix_session_windows",
+        title="Repair session window collapsing logic",
+        difficulty="medium",
+        task_kind="bug_fix",
+        task_description=(
+            "The session aggregator regressed after a cleanup pass. Public tests expose "
+            "incorrect boundary handling and the final session is missing. Fix the logic "
+            "without changing the function contract."
+        ),
+        starter_code=_code(
+            """
+            def collapse_sessions(events, idle_timeout_minutes):
+                if not events:
+                    return []
+
+                sessions = []
+                current_start = events[0]["minute"]
+                current_end = current_start
+
+                for event in events[1:]:
+                    minute = event["minute"]
+                    if minute - current_end > idle_timeout_minutes:
+                        sessions.append((current_start, current_end))
+                        current_start = minute
+                    current_end = minute
+
+                return sessions
+            """
+        ),
+        reference_code=_code(
+            '''
+            def collapse_sessions(events, idle_timeout_minutes):
+                """Collapse activity events into inclusive session windows."""
+                if not events:
+                    return []
+
+                sessions = []
+                current_start = events[0]["minute"]
+                current_end = current_start
+
+                for event in events[1:]:
+                    minute = event["minute"]
+                    if minute - current_end >= idle_timeout_minutes:
+                        sessions.append((current_start, current_end))
+                        current_start = minute
+                    current_end = minute
+
+                sessions.append((current_start, current_end))
+                return sessions
+            '''
+        ),
+        function_name="collapse_sessions",
+        visible_tests=[
+            "collapse_sessions([{'minute': 1}, {'minute': 3}, {'minute': 8}], 4) == [(1, 3), (8, 8)]",
+            "collapse_sessions([{'minute': 5}, {'minute': 9}], 4) == [(5, 5), (9, 9)]",
+        ],
+        public_cases=[
+            CallCase(
+                label="split when idle timeout is exceeded",
+                args=([{"minute": 1}, {"minute": 3}, {"minute": 8}], 4),
+                expected=[(1, 3), (8, 8)],
+            ),
+            CallCase(
+                label="boundary is inclusive",
+                args=([{"minute": 5}, {"minute": 9}], 4),
+                expected=[(5, 5), (9, 9)],
+            ),
+        ],
+        hidden_cases=[
+            CallCase(
+                label="single continuous session",
+                args=([{"minute": 2}, {"minute": 4}, {"minute": 5}], 4),
+                expected=[(2, 5)],
+            ),
+            CallCase(label="empty input", args=([], 10), expected=[]),
+            CallCase(
+                label="multiple boundaries",
+                args=([{"minute": 1}, {"minute": 5}, {"minute": 9}, {"minute": 14}], 4),
+                expected=[(1, 1), (5, 5), (9, 9), (14, 14)],
+            ),
+        ],
+        repo_summary=(
+            "analytics/sessionizer.py condenses sorted clickstream events into user "
+            "sessions for downstream retention reports."
+        ),
+        changed_files=["analytics/sessionizer.py"],
+        available_files=["analytics/sessionizer.py", "tests/test_sessionizer.py"],
+        goal="Make session collapsing match the expected timeout semantics.",
+        max_steps=8,
+    ),
+    ReviewTask(
+        task_id="optimization_rank_active_users",
+        title="Optimize the active-user ranking pipeline",
+        difficulty="hard",
+        task_kind="optimization",
+        task_description=(
+            "The reporting job is correct enough for small fixtures but too slow for the "
+            "daily production export. Preserve the API, keep the output deterministic, "
+            "and refactor the implementation for speed and readability."
+        ),
+        starter_code=_code(
+            """
+            def rank_active_users(events):
+                users = []
+                for event in events:
+                    if event["status"] == "active":
+                        found = False
+                        for existing in users:
+                            if existing == event["user_id"]:
+                                found = True
+                        if not found:
+                            users.append(event["user_id"])
+
+                totals = []
+                for user in users:
+                    count = 0
+                    for event in events:
+                        if event["status"] == "active" and event["user_id"] == user:
+                            count = count + 1
+                    totals.append((user, count))
+
+                totals.sort(key=lambda item: (-item[1], item[0]))
+                return totals
+            """
+        ),
+        reference_code=_code(
+            '''
+            from collections import Counter
+
+
+            def rank_active_users(events):
+                """Return users ranked by number of active events."""
+                counts = Counter(
+                    event["user_id"]
+                    for event in events
+                    if event["status"] == "active"
+                )
+                return sorted(counts.items(), key=lambda item: (-item[1], item[0]))
+            '''
+        ),
+        function_name="rank_active_users",
+        visible_tests=[
+            "rank_active_users([{'user_id': 'b', 'status': 'active'}, {'user_id': 'a', 'status': 'active'}, {'user_id': 'b', 'status': 'inactive'}]) == [('a', 1), ('b', 1)]",
+            "rank_active_users([{'user_id': 'u1', 'status': 'active'}, {'user_id': 'u1', 'status': 'active'}, {'user_id': 'u2', 'status': 'active'}]) == [('u1', 2), ('u2', 1)]",
+        ],
+        public_cases=[
+            CallCase(
+                label="inactive events are ignored",
+                args=([{"user_id": "b", "status": "active"}, {"user_id": "a", "status": "active"}, {"user_id": "b", "status": "inactive"}],),
+                expected=[("a", 1), ("b", 1)],
+            ),
+            CallCase(
+                label="counts repeated active users",
+                args=([{"user_id": "u1", "status": "active"}, {"user_id": "u1", "status": "active"}, {"user_id": "u2", "status": "active"}],),
+                expected=[("u1", 2), ("u2", 1)],
+            ),
+        ],
+        hidden_cases=[
+            CallCase(
+                label="stable alphabetical tie-break",
+                args=([{"user_id": "u3", "status": "active"}, {"user_id": "u2", "status": "active"}, {"user_id": "u3", "status": "active"}, {"user_id": "u2", "status": "active"}],),
+                expected=[("u2", 2), ("u3", 2)],
+            ),
+            CallCase(label="empty input", args=([],), expected=[]),
+            CallCase(
+                label="mixed active and inactive states",
+                args=([{"user_id": "x", "status": "inactive"}, {"user_id": "x", "status": "active"}, {"user_id": "y", "status": "active"}, {"user_id": "x", "status": "active"}],),
+                expected=[("x", 2), ("y", 1)],
+            ),
+        ],
+        repo_summary=(
+            "reports/activity_rankings.py feeds a nightly export that runs on a small CPU "
+            "instance and has become too slow after customer growth."
+        ),
+        changed_files=["reports/activity_rankings.py"],
+        available_files=["reports/activity_rankings.py", "tests/test_activity_rankings.py"],
+        goal="Keep the output stable while improving runtime and code quality.",
+        max_steps=10,
+        benchmark_config={"user_pool": 240, "events_per_user": 36, "iterations": 8},
+    ),
+]
+
+TASK_BY_ID = {task.task_id: task for task in TASKS}
+
+
+def list_tasks() -> List[ReviewTask]:
+    """Return all supported tasks."""
+
+    return list(TASKS)
+
+
+def get_task(task_id: str) -> ReviewTask:
+    """Fetch a task by identifier."""
+
+    try:
+        return TASK_BY_ID[task_id]
+    except KeyError as exc:
+        raise ValueError(f"Unknown task_id: {task_id}") from exc
+
+
+def select_task(seed: Optional[int] = None, task_id: Optional[str] = None) -> ReviewTask:
+    """Select a task deterministically by explicit id or seed."""
+
+    if task_id:
+        return get_task(task_id)
+    if seed is None:
+        return TASKS[0]
+    return TASKS[seed % len(TASKS)]

tests/test_multi_domain_platform.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from api.main import app
+from schemas.request import AnalyzeCodeRequest
+from services.analysis_service import AnalysisService
+
+
+def test_analysis_service_detects_web_code() -> None:
+    service = AnalysisService()
+    request = AnalyzeCodeRequest(
+        code="from fastapi import FastAPI\napp = FastAPI()\n\n@app.get('/health')\ndef health():\n    return {'status': 'ok'}\n",
+        domain_hint="auto",
+    )
+
+    result = service.analyze(request)
+
+    assert result.detected_domain == "web"
+    assert 0.0 <= result.score_breakdown.reward <= 1.0
+    assert len(result.improvement_plan) == 3
+
+
+def test_analysis_service_detects_dsa_code() -> None:
+    service = AnalysisService()
+    request = AnalyzeCodeRequest(
+        code="def has_pair(nums, target):\n    for i in range(len(nums)):\n        for j in range(i + 1, len(nums)):\n            if nums[i] + nums[j] == target:\n                return True\n    return False\n",
+        domain_hint="auto",
+    )
+
+    result = service.analyze(request)
+
+    assert result.detected_domain == "dsa"
+    assert result.static_analysis.time_complexity in {"O(n^2)", "O(n^3)"}
+
+
+def test_api_analyze_endpoint_returns_valid_payload() -> None:
+    client = TestClient(app)
+    response = client.post(
+        "/analyze",
+        json={
+            "code": "import torch\n\ndef predict(model, x):\n    return model(x)\n",
+            "context_window": "Inference helper for a classifier",
+            "traceback_text": "",
+            "domain_hint": "auto",
+        },
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert "detected_domain" in payload
+    assert "score_breakdown" in payload

tests/test_scoring.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from graders import grade_task
+from Models import PythonCodeReviewAction
+from server.env import PythonCodeReviewEnvironment
+from tasks import list_tasks
+
+
+def assert_open_unit_interval(value: float) -> None:
+    assert 0 < value < 1, f"Invalid score: {value}"
+
+
+def test_task_grades_stay_strictly_between_zero_and_one() -> None:
+    for task in list_tasks():
+        starter_grade = grade_task(task, task.starter_code, include_hidden=False)
+        reference_grade = grade_task(task, task.reference_code, include_hidden=True)
+
+        for grade in (starter_grade, reference_grade):
+            assert_open_unit_interval(grade.score)
+            assert_open_unit_interval(grade.syntax_score)
+            assert_open_unit_interval(grade.quality_score)
+            assert_open_unit_interval(grade.runtime_score)
+
+
+def test_environment_scores_and_rewards_stay_in_open_interval() -> None:
+    env = PythonCodeReviewEnvironment(verbose=False)
+    observation = env.reset(task_id="bug_fix_session_windows")
+
+    assert_open_unit_interval(observation.score)
+    assert_open_unit_interval(observation.reward_details.value)
+
+    no_op_action = PythonCodeReviewAction(action_type="edit_code", code=observation.current_code)
+    next_observation, reward, _, _ = env.step_result(no_op_action)
+    assert_open_unit_interval(next_observation.score)
+    assert_open_unit_interval(reward)
+    assert_open_unit_interval(next_observation.reward_details.value)
+
+    submit_action = PythonCodeReviewAction(action_type="submit_solution", code=env._task.reference_code)
+    final_observation, final_reward, _, _ = env.step_result(submit_action)
+    assert_open_unit_interval(final_observation.score)
+    assert_open_unit_interval(final_reward)
+    assert_open_unit_interval(final_observation.reward_details.value)

tests/test_triage_pipeline.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from triage import CodeTriageEngine, HashingEmbeddingBackend
+from triage_catalog import build_examples
+
+
+def test_hashing_backend_returns_normalized_embeddings() -> None:
+    backend = HashingEmbeddingBackend(dimensions=32)
+    embeddings = backend.embed_texts(["def foo():\n    return 1", "for x in items:\n    pass"])
+
+    assert embeddings.shape == (2, 32)
+    for row in embeddings:
+        assert round(float(row.norm().item()), 5) == 1.0
+
+
+def test_examples_map_to_expected_labels_with_fallback_backend() -> None:
+    examples = build_examples()
+    engine = CodeTriageEngine(backend=HashingEmbeddingBackend())
+
+    for example in examples:
+        result = engine.triage(example.code, example.traceback_text, example.context_window)
+        assert result.issue_label == example.label
+        assert 0.0 <= result.reward_score <= 1.0
+
+
+def test_syntax_example_exposes_parser_signal() -> None:
+    example = next(item for item in build_examples() if item.label == "syntax")
+    engine = CodeTriageEngine(backend=HashingEmbeddingBackend())
+
+    result = engine.triage(example.code, example.traceback_text, example.context_window)
+
+    assert any(signal.name == "syntax_parse" and signal.value == "fails" for signal in result.extracted_signals)
+    assert result.matched_pattern.task_id == example.task_id
+    assert result.repair_plan[0].startswith("Step 1 - Syntax checking and bug fixes")
+
+
+def test_composed_app_preserves_health_route() -> None:
+    from server.app import build_application
+
+    client = TestClient(build_application())
+    response = client.get("/health")
+
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"

triage.py

@@ -0,0 +1,473 @@
+"""PyTorch-backed triage pipeline for TorchReview Copilot."""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import os
+import re
+import time
+from functools import lru_cache
+from typing import List, Sequence
+
+import torch
+import torch.nn.functional as F
+
+try:
+    from transformers import AutoModel, AutoTokenizer
+except Exception:
+    AutoModel = None  # type: ignore[assignment]
+    AutoTokenizer = None  # type: ignore[assignment]
+
+try:
+    from .triage_catalog import build_examples, build_prototypes
+    from .triage_models import (
+        IssueLabel,
+        PrototypeMatch,
+        TriageExample,
+        TriagePrototype,
+        TriageResult,
+        TriageSignal,
+    )
+except ImportError:
+    from triage_catalog import build_examples, build_prototypes
+    from triage_models import (
+        IssueLabel,
+        PrototypeMatch,
+        TriageExample,
+        TriagePrototype,
+        TriageResult,
+        TriageSignal,
+    )
+
+
+MODEL_ID = os.getenv("TRIAGE_MODEL_ID", "huggingface/CodeBERTa-small-v1")
+MODEL_MAX_LENGTH = int(os.getenv("TRIAGE_MODEL_MAX_LENGTH", "256"))
+LABELS: tuple[IssueLabel, ...] = ("syntax", "logic", "performance")
+
+
+class _LoopDepthVisitor(ast.NodeVisitor):
+    """Track the maximum loop nesting depth in a code snippet."""
+
+    def __init__(self) -> None:
+        self.depth = 0
+        self.max_depth = 0
+
+    def _visit_loop(self, node: ast.AST) -> None:
+        self.depth += 1
+        self.max_depth = max(self.max_depth, self.depth)
+        self.generic_visit(node)
+        self.depth -= 1
+
+    def visit_For(self, node: ast.For) -> None:  # noqa: N802
+        self._visit_loop(node)
+
+    def visit_While(self, node: ast.While) -> None:  # noqa: N802
+        self._visit_loop(node)
+
+    def visit_comprehension(self, node: ast.comprehension) -> None:  # noqa: N802
+        self._visit_loop(node)
+
+
+class HashingEmbeddingBackend:
+    """Deterministic torch-native fallback when pretrained weights are unavailable."""
+
+    def __init__(self, dimensions: int = 96) -> None:
+        self.dimensions = dimensions
+        self.model_id = "hashed-token-fallback"
+        self.backend_name = "hashed-token-fallback"
+        self.notes = ["Using hashed torch embeddings because pretrained weights are unavailable."]
+
+    def embed_texts(self, texts: Sequence[str]) -> torch.Tensor:
+        rows = torch.zeros((len(texts), self.dimensions), dtype=torch.float32)
+        for row_index, text in enumerate(texts):
+            tokens = re.findall(r"[A-Za-z_]+|\d+|==|!=|<=|>=|\S", text.lower())[:512]
+            if not tokens:
+                rows[row_index, 0] = 1.0
+                continue
+            for token in tokens:
+                digest = hashlib.md5(token.encode("utf-8")).hexdigest()
+                bucket = int(digest[:8], 16) % self.dimensions
+                sign = -1.0 if int(digest[8:10], 16) % 2 else 1.0
+                rows[row_index, bucket] += sign
+        return F.normalize(rows + 1e-6, dim=1)
+
+
+class TransformersEmbeddingBackend:
+    """Mean-pool CodeBERTa embeddings via torch + transformers."""
+
+    def __init__(self, model_id: str = MODEL_ID, force_fallback: bool = False) -> None:
+        self.model_id = model_id
+        self.force_fallback = force_fallback
+        self.backend_name = model_id
+        self.notes: List[str] = []
+        self._fallback = HashingEmbeddingBackend()
+        self._tokenizer = None
+        self._model = None
+        self._load_error = ""
+        if force_fallback:
+            self.backend_name = self._fallback.backend_name
+            self.notes = list(self._fallback.notes)
+
+    def _ensure_loaded(self) -> None:
+        if self.force_fallback or self._model is not None or self._load_error:
+            return
+        if AutoTokenizer is None or AutoModel is None:
+            self._load_error = "transformers is not installed."
+        else:
+            try:
+                self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
+                self._model = AutoModel.from_pretrained(self.model_id)
+                self._model.eval()
+                self.notes.append(f"Loaded pretrained encoder `{self.model_id}` for inference.")
+            except Exception as exc:
+                self._load_error = f"{type(exc).__name__}: {exc}"
+
+        if self._load_error:
+            self.backend_name = self._fallback.backend_name
+            self.notes = list(self._fallback.notes) + [f"Pretrained load failed: {self._load_error}"]
+
+    def embed_texts(self, texts: Sequence[str]) -> torch.Tensor:
+        self._ensure_loaded()
+        if self._model is None or self._tokenizer is None:
+            return self._fallback.embed_texts(texts)
+
+        encoded = self._tokenizer(
+            list(texts),
+            padding=True,
+            truncation=True,
+            max_length=MODEL_MAX_LENGTH,
+            return_tensors="pt",
+        )
+        with torch.no_grad():
+            outputs = self._model(**encoded)
+            hidden_state = outputs.last_hidden_state
+            mask = encoded["attention_mask"].unsqueeze(-1)
+            pooled = (hidden_state * mask).sum(dim=1) / mask.sum(dim=1).clamp(min=1)
+        return F.normalize(pooled, dim=1)
+
+
+def _sanitize_text(value: str) -> str:
+    text = (value or "").strip()
+    return text[:4000]
+
+
+def _safe_softmax(scores: dict[IssueLabel, float]) -> dict[str, float]:
+    tensor = torch.tensor([scores[label] for label in LABELS], dtype=torch.float32)
+    probabilities = torch.softmax(tensor * 4.0, dim=0)
+    return {label: round(float(probabilities[index]), 4) for index, label in enumerate(LABELS)}
+
+
+def _loop_depth(code: str) -> int:
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return 0
+    visitor = _LoopDepthVisitor()
+    visitor.visit(tree)
+    return visitor.max_depth
+
+
+def _repair_risk(label: IssueLabel, confidence: float, signal_count: int) -> str:
+    base = {"syntax": 0.25, "logic": 0.55, "performance": 0.7}[label]
+    if confidence < 0.55:
+        base += 0.12
+    if signal_count >= 4:
+        base += 0.08
+    if base < 0.4:
+        return "low"
+    if base < 0.72:
+        return "medium"
+    return "high"
+
+
+def _clamp_unit(value: float) -> float:
+    return round(max(0.0, min(1.0, float(value))), 4)
+
+
+def _lint_score(code: str) -> float:
+    stripped_lines = [line.rstrip("\n") for line in code.splitlines()]
+    if not stripped_lines:
+        return 0.2
+
+    score = 1.0
+    if any(len(line) > 88 for line in stripped_lines):
+        score -= 0.15
+    if any(line.rstrip() != line for line in stripped_lines):
+        score -= 0.1
+    if any("\t" in line for line in stripped_lines):
+        score -= 0.1
+    try:
+        tree = ast.parse(code)
+        functions = [node for node in tree.body if isinstance(node, ast.FunctionDef)]
+        if functions and not ast.get_docstring(functions[0]):
+            score -= 0.08
+    except SyntaxError:
+        score -= 0.45
+    return _clamp_unit(score)
+
+
+def _complexity_penalty(code: str) -> float:
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return 0.95
+    branch_nodes = sum(isinstance(node, (ast.If, ast.For, ast.While, ast.Try, ast.Match)) for node in ast.walk(tree))
+    loop_depth = _loop_depth(code)
+    penalty = 0.1 + min(branch_nodes, 8) * 0.07 + min(loop_depth, 4) * 0.12
+    return _clamp_unit(penalty)
+
+
+class CodeTriageEngine:
+    """Combine static signals with PyTorch embeddings to classify code issues."""
+
+    def __init__(
+        self,
+        *,
+        backend: TransformersEmbeddingBackend | HashingEmbeddingBackend | None = None,
+        prototypes: Sequence[TriagePrototype] | None = None,
+        examples: Sequence[TriageExample] | None = None,
+    ) -> None:
+        self.backend = backend or TransformersEmbeddingBackend()
+        self.prototypes = list(prototypes or build_prototypes())
+        self.examples = list(examples or build_examples())
+        self._prototype_matrix: torch.Tensor | None = None
+        self._reference_code_matrix: torch.Tensor | None = None
+
+    def example_map(self) -> dict[str, TriageExample]:
+        """Return UI examples keyed by task id."""
+
+        return {example.key: example for example in self.examples}
+
+    def _build_document(self, code: str, traceback_text: str) -> str:
+        trace = _sanitize_text(traceback_text) or "No traceback supplied."
+        snippet = _sanitize_text(code) or "# No code supplied."
+        return f"Candidate code:\n{snippet}\n\nObserved failure:\n{trace}\n"
+
+    def _build_review_document(self, code: str, traceback_text: str, context_window: str) -> str:
+        context = _sanitize_text(context_window) or "No additional context window supplied."
+        return (
+            f"{self._build_document(code, traceback_text)}\n"
+            f"Context window:\n{context}\n"
+        )
+
+    def _prototype_embeddings(self) -> torch.Tensor:
+        if self._prototype_matrix is None:
+            reference_texts = [prototype.reference_text for prototype in self.prototypes]
+            self._prototype_matrix = self.backend.embed_texts(reference_texts)
+        return self._prototype_matrix
+
+    def _reference_code_embeddings(self) -> torch.Tensor:
+        if self._reference_code_matrix is None:
+            reference_codes = [prototype.reference_code for prototype in self.prototypes]
+            self._reference_code_matrix = self.backend.embed_texts(reference_codes)
+        return self._reference_code_matrix
+
+    def _extract_signals(self, code: str, traceback_text: str) -> tuple[list[TriageSignal], dict[IssueLabel, float], list[str]]:
+        trace = (traceback_text or "").lower()
+        heuristic_scores: dict[IssueLabel, float] = {label: 0.15 for label in LABELS}
+        signals: list[TriageSignal] = []
+        notes: list[str] = []
+
+        try:
+            ast.parse(code)
+            signals.append(
+                TriageSignal(
+                    name="syntax_parse",
+                    value="passes",
+                    impact="syntax",
+                    weight=0.1,
+                    evidence="Python AST parsing succeeded.",
+                )
+            )
+            heuristic_scores["logic"] += 0.05
+        except SyntaxError as exc:
+            evidence = f"{exc.msg} at line {exc.lineno}"
+            signals.append(
+                TriageSignal(
+                    name="syntax_parse",
+                    value="fails",
+                    impact="syntax",
+                    weight=0.95,
+                    evidence=evidence,
+                )
+            )
+            heuristic_scores["syntax"] += 0.85
+            notes.append(f"Parser failure detected: {evidence}")
+
+        if any(token in trace for token in ("syntaxerror", "indentationerror", "expected ':'")):
+            signals.append(
+                TriageSignal(
+                    name="traceback_keyword",
+                    value="syntaxerror",
+                    impact="syntax",
+                    weight=0.8,
+                    evidence="Traceback contains a parser error.",
+                )
+            )
+            heuristic_scores["syntax"] += 0.55
+
+        if any(token in trace for token in ("assertionerror", "expected:", "actual:", "boundary", "missing", "incorrect")):
+            signals.append(
+                TriageSignal(
+                    name="test_failure_signal",
+                    value="assertion-style failure",
+                    impact="logic",
+                    weight=0.7,
+                    evidence="Failure text points to behavioral mismatch instead of parser issues.",
+                )
+            )
+            heuristic_scores["logic"] += 0.55
+
+        if any(token in trace for token in ("timeout", "benchmark", "slow", "latency", "performance", "profiler")):
+            signals.append(
+                TriageSignal(
+                    name="performance_trace",
+                    value="latency regression",
+                    impact="performance",
+                    weight=0.85,
+                    evidence="Traceback mentions benchmark or latency pressure.",
+                )
+            )
+            heuristic_scores["performance"] += 0.7
+
+        loop_depth = _loop_depth(code)
+        if loop_depth >= 2:
+            signals.append(
+                TriageSignal(
+                    name="loop_depth",
+                    value=str(loop_depth),
+                    impact="performance",
+                    weight=0.65,
+                    evidence="Nested iteration increases runtime risk on larger fixtures.",
+                )
+            )
+            heuristic_scores["performance"] += 0.35
+
+        if "Counter(" in code or "defaultdict(" in code or "set(" in code:
+            heuristic_scores["performance"] += 0.05
+
+        if "return sessions" in code and "sessions.append" not in code:
+            signals.append(
+                TriageSignal(
+                    name="state_update_gap",
+                    value="possible missing final append",
+                    impact="logic",
+                    weight=0.45,
+                    evidence="A collection is returned without an obvious final state flush.",
+                )
+            )
+            heuristic_scores["logic"] += 0.18
+
+        return signals, heuristic_scores, notes
+
+    def _nearest_match(self, embedding: torch.Tensor) -> tuple[TriagePrototype, float, dict[str, float]]:
+        similarities = torch.matmul(embedding, self._prototype_embeddings().T)[0]
+        indexed_scores = {
+            self.prototypes[index].task_id: round(float((similarities[index] + 1.0) / 2.0), 4)
+            for index in range(len(self.prototypes))
+        }
+        best_index = int(torch.argmax(similarities).item())
+        best_prototype = self.prototypes[best_index]
+        best_similarity = float((similarities[best_index] + 1.0) / 2.0)
+        return best_prototype, best_similarity, indexed_scores
+
+    def _repair_plan(self, label: IssueLabel, matched: TriagePrototype, context_window: str) -> list[str]:
+        context = _sanitize_text(context_window)
+        step_one = {
+            "syntax": "Step 1 - Syntax checking and bug fixes: resolve the parser break before touching behavior, then align the function with the expected contract.",
+            "logic": "Step 1 - Syntax checking and bug fixes: confirm the code parses cleanly, then patch the failing branch or state update causing the incorrect result.",
+            "performance": "Step 1 - Syntax checking and bug fixes: keep the implementation correct first, then isolate the slow section without changing external behavior.",
+        }[label]
+        step_two = (
+            "Step 2 - Edge case handling: verify empty input, boundary values, missing fields, and final-state flush behavior "
+            f"against the known pattern `{matched.title}`."
+        )
+        step_three = (
+            "Step 3 - Scalability of code: remove repeated full scans, prefer linear-time data structures, "
+            "and benchmark the path on a production-like fixture."
+        )
+        if context:
+            step_two = f"{step_two} Context window to preserve: {context}"
+        return [step_one, step_two, step_three]
+
+    def _reference_quality_score(self, code: str, matched: TriagePrototype) -> float:
+        candidate = self.backend.embed_texts([_sanitize_text(code) or "# empty"])
+        match_index = next(index for index, prototype in enumerate(self.prototypes) if prototype.task_id == matched.task_id)
+        reference = self._reference_code_embeddings()[match_index : match_index + 1]
+        score = float(torch.matmul(candidate, reference.T)[0][0].item())
+        return _clamp_unit((score + 1.0) / 2.0)
+
+    def triage(self, code: str, traceback_text: str = "", context_window: str = "") -> TriageResult:
+        """Run the full triage pipeline on code plus optional failure context."""
+
+        started = time.perf_counter()
+        document = self._build_review_document(code, traceback_text, context_window)
+        signals, heuristic_scores, notes = self._extract_signals(code, traceback_text)
+
+        candidate_embedding = self.backend.embed_texts([document])
+        matched, matched_similarity, prototype_scores = self._nearest_match(candidate_embedding)
+
+        label_similarity = {label: 0.18 for label in LABELS}
+        for prototype in self.prototypes:
+            label_similarity[prototype.label] = max(
+                label_similarity[prototype.label],
+                prototype_scores[prototype.task_id],
+            )
+
+        combined_scores = {
+            label: 0.72 * label_similarity[label] + 0.28 * heuristic_scores[label]
+            for label in LABELS
+        }
+        confidence_scores = _safe_softmax(combined_scores)
+        issue_label = max(LABELS, key=lambda label: confidence_scores[label])
+        top_confidence = confidence_scores[issue_label]
+
+        top_signal = signals[0].evidence if signals else "Model similarity dominated the decision."
+        ml_quality_score = self._reference_quality_score(code, matched)
+        lint_score = _lint_score(code)
+        complexity_penalty = _complexity_penalty(code)
+        reward_score = _clamp_unit((0.5 * ml_quality_score) + (0.3 * lint_score) - (0.2 * complexity_penalty))
+        summary = (
+            f"Detected a {issue_label} issue with {top_confidence:.0%} confidence. "
+            f"The closest known failure pattern is `{matched.title}`, which indicates {matched.summary.lower()}. "
+            f"Predicted quality score is {ml_quality_score:.0%} with an RL-ready reward of {reward_score:.0%}."
+        )
+        suggested_next_action = {
+            "syntax": "Fix the parser error first, then rerun validation before changing behavior.",
+            "logic": "Step through the smallest failing case and confirm the final branch/update behavior.",
+            "performance": "Replace repeated full-list scans with a linear-time aggregation strategy, then benchmark it.",
+        }[issue_label]
+
+        return TriageResult(
+            issue_label=issue_label,
+            confidence_scores=confidence_scores,
+            repair_risk=_repair_risk(issue_label, top_confidence, len(signals)),
+            ml_quality_score=ml_quality_score,
+            lint_score=lint_score,
+            complexity_penalty=complexity_penalty,
+            reward_score=reward_score,
+            summary=summary,
+            matched_pattern=PrototypeMatch(
+                task_id=matched.task_id,
+                title=matched.title,
+                label=matched.label,
+                similarity=round(matched_similarity, 4),
+                summary=matched.summary,
+                rationale=top_signal,
+            ),
+            repair_plan=self._repair_plan(issue_label, matched, context_window),
+            suggested_next_action=suggested_next_action,
+            extracted_signals=signals,
+            model_backend=self.backend.backend_name,
+            model_id=self.backend.model_id,
+            inference_notes=list(self.backend.notes) + notes,
+            analysis_time_ms=round((time.perf_counter() - started) * 1000.0, 2),
+        )
+
+
+@lru_cache(maxsize=1)
+def get_default_engine() -> CodeTriageEngine:
+    """Return a cached triage engine for the running process."""
+
+    return CodeTriageEngine()

triage_catalog.py

@@ -0,0 +1,134 @@
+"""Curated prototypes and example inputs for TorchReview Copilot."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+try:
+    from .triage_models import IssueLabel, TriageExample, TriagePrototype
+    from .tasks import list_tasks
+except ImportError:
+    from triage_models import IssueLabel, TriageExample, TriagePrototype
+    from tasks import list_tasks
+
+
+TASK_KIND_TO_LABEL: Dict[str, IssueLabel] = {
+    "syntax_fix": "syntax",
+    "bug_fix": "logic",
+    "optimization": "performance",
+}
+
+TRACEBACK_BY_TASK_ID: Dict[str, str] = {
+    "syntax_fix_invoice_totals": (
+        "Traceback (most recent call last):\n"
+        "  File \"services/billing/reconciliation.py\", line 3\n"
+        "    for record in records\n"
+        "                      ^\n"
+        "SyntaxError: expected ':'"
+    ),
+    "bug_fix_session_windows": (
+        "AssertionError: collapse_sessions([{'minute': 1}, {'minute': 3}, {'minute': 8}], 4)\n"
+        "Expected: [(1, 3), (8, 8)]\n"
+        "Actual:   [(1, 8)]\n"
+        "Boundary handling merges the final session instead of starting a new one."
+    ),
+    "optimization_rank_active_users": (
+        "BenchmarkWarning: rank_active_users exceeded the 450ms budget on a nightly export fixture.\n"
+        "Profiler hint: repeated scans over the full event list and nested loops dominate runtime."
+    ),
+}
+
+SUMMARY_BY_TASK_ID: Dict[str, str] = {
+    "syntax_fix_invoice_totals": "Broken parser state in a billing helper blocks reconciliation jobs.",
+    "bug_fix_session_windows": "Session-boundary logic fails on inclusive idle-timeout edges.",
+    "optimization_rank_active_users": "A nightly ranking job is correct on small fixtures but too slow at production scale.",
+}
+
+CONTEXT_BY_TASK_ID: Dict[str, str] = {
+    "syntax_fix_invoice_totals": (
+        "Context window: this helper runs in an end-of-day billing reconciliation job. "
+        "Keep the public function signature intact and restore correct totals for mixed integer/string inputs."
+    ),
+    "bug_fix_session_windows": (
+        "Context window: this function groups sorted product analytics events into sessions for retention dashboards. "
+        "Boundary behavior must stay deterministic because downstream reports depend on it."
+    ),
+    "optimization_rank_active_users": (
+        "Context window: this pipeline feeds a nightly export on a small CPU instance. "
+        "Maintain identical output ordering while improving scalability on larger event volumes."
+    ),
+}
+
+
+def _prototype_text(
+    task_id: str,
+    title: str,
+    description: str,
+    repo_summary: str,
+    goal: str,
+    visible_tests: List[str],
+    starter_code: str,
+    traceback_text: str,
+) -> str:
+    visible = "\n".join(f"- {item}" for item in visible_tests) or "- none"
+    return (
+        f"Title: {title}\n"
+        f"Problem: {description}\n"
+        f"Repo context: {repo_summary}\n"
+        f"Goal: {goal}\n"
+        f"Observed failure:\n{traceback_text}\n"
+        f"Visible checks:\n{visible}\n"
+        f"Candidate code:\n{starter_code}\n"
+        f"Task id: {task_id}\n"
+    )
+
+
+def build_examples() -> List[TriageExample]:
+    """Create stable UI examples from the task catalog."""
+
+    examples: List[TriageExample] = []
+    for task in list_tasks():
+        label = TASK_KIND_TO_LABEL[task.task_kind]
+        examples.append(
+            TriageExample(
+                key=task.task_id,
+                title=task.title,
+                label=label,
+                summary=SUMMARY_BY_TASK_ID[task.task_id],
+                code=task.starter_code,
+                traceback_text=TRACEBACK_BY_TASK_ID[task.task_id],
+                context_window=CONTEXT_BY_TASK_ID[task.task_id],
+                task_id=task.task_id,
+            )
+        )
+    return examples
+
+
+def build_prototypes() -> List[TriagePrototype]:
+    """Build canonical triage prototypes from the OpenEnv tasks."""
+
+    prototypes: List[TriagePrototype] = []
+    for task in list_tasks():
+        traceback_text = TRACEBACK_BY_TASK_ID[task.task_id]
+        prototypes.append(
+            TriagePrototype(
+                task_id=task.task_id,
+                title=task.title,
+                label=TASK_KIND_TO_LABEL[task.task_kind],
+                summary=SUMMARY_BY_TASK_ID[task.task_id],
+                reference_text=_prototype_text(
+                    task.task_id,
+                    task.title,
+                    task.task_description,
+                    task.repo_summary,
+                    task.goal,
+                    list(task.visible_tests),
+                    task.reference_code,
+                    traceback_text,
+                ),
+                starter_code=task.starter_code,
+                reference_code=task.reference_code,
+                traceback_text=traceback_text,
+            )
+        )
+    return prototypes

triage_models.py

@@ -0,0 +1,79 @@
+"""Typed models for TorchReview Copilot outputs and examples."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Literal
+
+from pydantic import BaseModel, Field
+
+
+IssueLabel = Literal["syntax", "logic", "performance"]
+RiskLevel = Literal["low", "medium", "high"]
+
+
+class TriageSignal(BaseModel):
+    """One extracted signal used during issue classification."""
+
+    name: str
+    value: str
+    impact: Literal["syntax", "logic", "performance", "mixed"] = "mixed"
+    weight: float = Field(..., ge=0.0, le=1.0)
+    evidence: str = ""
+
+
+class PrototypeMatch(BaseModel):
+    """Nearest known bug pattern from the built-in task catalog."""
+
+    task_id: str
+    title: str
+    label: IssueLabel
+    similarity: float = Field(..., ge=0.0, le=1.0)
+    summary: str
+    rationale: str
+
+
+class TriageExample(BaseModel):
+    """Example payload exposed in the demo UI."""
+
+    key: str
+    title: str
+    label: IssueLabel
+    summary: str
+    code: str
+    traceback_text: str
+    context_window: str
+    task_id: str
+
+
+class TriagePrototype(BaseModel):
+    """Canonical issue-pattern representation embedded by the triage engine."""
+
+    task_id: str
+    title: str
+    label: IssueLabel
+    summary: str
+    reference_text: str
+    starter_code: str
+    reference_code: str
+    traceback_text: str
+
+
+class TriageResult(BaseModel):
+    """Structured output produced by the triage pipeline."""
+
+    issue_label: IssueLabel
+    confidence_scores: Dict[str, float]
+    repair_risk: RiskLevel
+    ml_quality_score: float = Field(..., ge=0.0, le=1.0)
+    lint_score: float = Field(..., ge=0.0, le=1.0)
+    complexity_penalty: float = Field(..., ge=0.0, le=1.0)
+    reward_score: float = Field(..., ge=0.0, le=1.0)
+    summary: str
+    matched_pattern: PrototypeMatch
+    repair_plan: List[str]
+    suggested_next_action: str
+    extracted_signals: List[TriageSignal] = Field(default_factory=list)
+    model_backend: str
+    model_id: str
+    inference_notes: List[str] = Field(default_factory=list)
+    analysis_time_ms: float = Field(..., ge=0.0)