Add Phase 06 Plan for Adaptive Judging and Edge Intelligence; Create initial project outline for GraphReview RL Environment

code-review-env/README.md

@@ -35,6 +35,14 @@ Phase 5:
 - Added confidence scoring that balances precision/recall with severity/security coverage and attribution validity.
 - Added API endpoint to generate artifacts and CLI support for real project runs.
 
+Phase 6:
+
+- Added adaptive hard-grader fusion: deterministic graph gate + primary judge + verifier judge.
+- Added disagreement-aware reweighting to reduce single-model catastrophic errors.
+- Added per-edge `connection_summary` generation using LLM with deterministic fallback.
+- Added optional LoRA trajectory logging for cross-project learning data collection.
+- Added root `.env` support for centralized configuration management.
+
 ## Core Runtime Components
 
 - `env/environment.py`
@@ -105,6 +113,8 @@ with `auth_token` connect arg.
 
 ## LLM and Runtime Env Vars
 
+`.env` at project root is auto-loaded by runtime configuration, DB initialization, and server startup.
+
 Judge settings:
 
 - `GRAPHREVIEW_JUDGE_PROVIDER` (default `ollama_openai_compat`)
@@ -117,6 +127,39 @@ Judge settings:
 - `GRAPHREVIEW_JUDGE_MAX_CONSECUTIVE_FAILURES` (default `3`)
 - `GRAPHREVIEW_JUDGE_THINK` (`false|true|low|medium|high`, default `false`)
 
+Verifier and adaptive fusion settings:
+
+- `GRAPHREVIEW_VERIFIER_ENABLED` (default `true`)
+- `GRAPHREVIEW_VERIFIER_PROVIDER`
+- `GRAPHREVIEW_VERIFIER_MODEL`
+- `GRAPHREVIEW_VERIFIER_BASE_URL`
+- `GRAPHREVIEW_VERIFIER_API_KEY`
+- `GRAPHREVIEW_VERIFIER_TIMEOUT_SECONDS`
+- `GRAPHREVIEW_JUDGE_WEIGHT_DETERMINISTIC` (default `0.5`)
+- `GRAPHREVIEW_JUDGE_WEIGHT_PRIMARY` (default `0.3`)
+- `GRAPHREVIEW_JUDGE_WEIGHT_VERIFIER` (default `0.2`)
+- `GRAPHREVIEW_JUDGE_DISAGREEMENT_THRESHOLD` (default `0.5`)
+
+Edge summary settings:
+
+- `GRAPHREVIEW_EDGE_SUMMARY_ENABLED` (default `false`, enable when you want LLM edge summaries)
+- `GRAPHREVIEW_EDGE_SUMMARY_MODEL`
+- `GRAPHREVIEW_EDGE_SUMMARY_BASE_URL`
+- `GRAPHREVIEW_EDGE_SUMMARY_API_KEY`
+- `GRAPHREVIEW_EDGE_SUMMARY_TIMEOUT_SECONDS`
+- `GRAPHREVIEW_EDGE_SUMMARY_MAX_CALLS`
+
+LoRA trajectory hooks:
+
+- `GRAPHREVIEW_LORA_ENABLED` (default `false`)
+- `GRAPHREVIEW_LORA_DATA_PATH` (default `outputs/lora/transitions.jsonl`)
+
+Generate a LoRA-ready SFT dataset from transitions:
+
+```bash
+python -m llm.lora_finetune --transitions outputs/lora/transitions.jsonl --output outputs/lora/sft_dataset.jsonl
+```
+
 General runtime settings:
 
 - `GRAPHREVIEW_SOURCE_ROOT` (default `sample_project`)
@@ -143,6 +186,26 @@ curl -s http://localhost:8000/health
 curl -s http://localhost:8000/tasks
 ```
 
+## Unified One-Command Runner
+
+Run seed + easy/medium/hard reviews + artifact generation on any target codebase:
+
+```bash
+graphreview /absolute/path/to/your/codebase --force-seed
+```
+
+Equivalent without installing entrypoints:
+
+```bash
+python run_project.py /absolute/path/to/your/codebase --force-seed
+```
+
+Optional focused run:
+
+```bash
+graphreview /absolute/path/to/your/codebase --modules checkout auth --filter-hops 1 --report-prefix myrun
+```
+
 ## Direct Module Review (Phase 4)
 
 Example: run `logic_review` with explicit module focus:

code-review-env/db/migrations.py

@@ -6,6 +6,8 @@ from pathlib import Path
 from sqlmodel import SQLModel, create_engine
 from sqlalchemy import inspect, text
 
+from env.env_loader import load_env_file
+
 
 def get_default_db_path() -> Path:
     project_root = Path(__file__).resolve().parents[1]
@@ -13,6 +15,7 @@ def get_default_db_path() -> Path:
 
 
 def get_engine(db_path: str | Path | None = None, echo: bool = False):
+    load_env_file()
     env_url = os.getenv("GRAPHREVIEW_DATABASE_URL", "").strip()
     if env_url:
         connect_args: dict[str, object] = {}
@@ -43,6 +46,7 @@ def get_engine(db_path: str | Path | None = None, echo: bool = False):
 
 
 def init_db(db_path: str | Path | None = None, echo: bool = False) -> None:
+    load_env_file()
     from db import schema  # noqa: F401
 
     engine = get_engine(db_path=db_path, echo=echo)
@@ -66,6 +70,14 @@ def _apply_lightweight_migrations(engine) -> None:
     if "is_amendment" not in existing_columns:
         add_statements.append("ALTER TABLE reviewannotation ADD COLUMN is_amendment BOOLEAN DEFAULT 0")
 
+    if not add_statements:
+        add_statements = []
+
+    if "moduleedge" in inspector.get_table_names():
+        edge_columns = {col["name"] for col in inspector.get_columns("moduleedge")}
+        if "connection_summary" not in edge_columns:
+            add_statements.append("ALTER TABLE moduleedge ADD COLUMN connection_summary TEXT DEFAULT ''")
+
     if not add_statements:
         return
 

code-review-env/db/schema.py

@@ -53,6 +53,7 @@ class ModuleEdge(SQLModel, table=True):
     edge_type: EdgeType = Field(default=EdgeType.EXPLICIT_IMPORT)
     import_line: str
     weight: float = 1.0
+    connection_summary: str = ""
 
 
 class LinterFinding(SQLModel, table=True):

code-review-env/db/seed.py

@@ -14,6 +14,7 @@ from parser.chunker import chunk_module
 from parser.graph_builder import build_edges
 from parser.linter import run_linters
 from parser.summarizer import summarize_module
+from llm.edge_summarizer import EdgeSummarizer, EdgeSummaryInput
 
 
 _SKIP_DIRS = {
@@ -160,13 +161,24 @@ def seed_project(target_dir: Path, db_path: str | None = None, force: bool = Fal
         store.replace_findings_for_module(parsed.module_id, [issue.model_dump() for issue in issues])
 
     edges = build_edges(parsed_modules, module_ids, chunk_ids_by_parent)
+    edge_summarizer = EdgeSummarizer()
     for edge in edges:
+        connection_summary = edge_summarizer.summarize(
+            EdgeSummaryInput(
+                source_module_id=edge.source_module_id,
+                target_module_id=edge.target_module_id,
+                edge_type=edge.edge_type.value,
+                import_line=edge.import_line,
+                scope=edge.scope,
+            )
+        )
         store.upsert_edge(
             source_module_id=edge.source_module_id,
             target_module_id=edge.target_module_id,
             edge_type=edge.edge_type,
             import_line=edge.import_line,
             weight=edge.weight,
+            connection_summary=connection_summary,
         )
 
     snapshot = store.get_full_graph()

code-review-env/db/store.py

@@ -54,6 +54,7 @@ class GraphEdgeRecord(BaseModel):
     target_module_id: str
     weight: float
     import_line: str
+    connection_summary: str
 
 
 class GraphSnapshot(BaseModel):
@@ -133,6 +134,7 @@ class Store:
         edge_type: EdgeType,
         import_line: str,
         weight: float,
+        connection_summary: str = "",
     ) -> ModuleEdge:
         with Session(self.engine) as session:
             existing = session.exec(
@@ -146,6 +148,7 @@ class Store:
             if existing:
                 existing.edge_type = edge_type
                 existing.weight = weight
+                existing.connection_summary = connection_summary or existing.connection_summary
                 session.add(existing)
                 session.commit()
                 session.refresh(existing)
@@ -158,6 +161,7 @@ class Store:
                 edge_type=edge_type,
                 import_line=import_line,
                 weight=weight,
+                connection_summary=connection_summary,
             )
             session.add(edge)
             session.commit()
@@ -337,6 +341,7 @@ class Store:
                     target_module_id=edge.target_module_id,
                     weight=edge.weight,
                     import_line=edge.import_line,
+                    connection_summary=edge.connection_summary,
                 )
                 for edge in edges
             ],

code-review-env/env/env_loader.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load_env_file(path: str | Path | None = None) -> None:
+    """Load key-value pairs from .env without overriding existing env vars."""
+    env_path = Path(path) if path is not None else Path(__file__).resolve().parents[1] / ".env"
+    if not env_path.exists():
+        return
+
+    for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key and key not in os.environ:
+            os.environ[key] = value

code-review-env/env/environment.py

@@ -21,6 +21,7 @@ from graders.base_grader import BaseGrader
 from graders.easy_grader import EasyGrader
 from graders.hard_grader import HardGrader
 from graders.medium_grader import MediumGrader
+from llm.lora_adapter import LoRATrajectoryLogger
 from tasks.task_registry import TaskSpec, get_task, list_tasks, resolve_task_modules
 
 
@@ -80,6 +81,7 @@ class CodeReviewEnv:
         self.store = Store(source_root=self.source_root, db_path=self.db_path)
         self.graph_manager = GraphManager(source_root=self.source_root, db_path=self.db_path)
         self.observation_builder = ObservationBuilder(source_root=self.source_root, db_path=self.db_path)
+        self.lora_logger = LoRATrajectoryLogger()
 
         self._runtime: _EpisodeRuntime | None = None
         self._grader: BaseGrader | None = None
@@ -196,6 +198,18 @@ class CodeReviewEnv:
                 context_request=context_request,
             )
 
+        self.lora_logger.log(
+            source_root=self.source_root,
+            episode_id=runtime.episode_id,
+            module_id=module_id,
+            step_number=step_number,
+            action=action,
+            reward=reward.raw_value,
+            done=runtime.done,
+            task_id=runtime.task.task_id,
+            observation_summary=f"module={observation.module_id} actions={','.join(observation.available_actions[:6])}",
+        )
+
         return StepResult(
             observation=observation,
             reward=reward.raw_value,

code-review-env/env/reward.py

@@ -9,6 +9,7 @@ class RewardReason(StrEnum):
 	CORRECT_FLAG = "correct_flag"
 	ACCURATE_COMMENT = "accurate_comment"
 	CORRECT_DEPENDENCY_ATTRIBUTION = "correct_dependency_attribution"
+	PARTIAL_DEPENDENCY_ATTRIBUTION = "partial_dependency_attribution"
 	INCORRECT_DEPENDENCY_ATTRIBUTION = "incorrect_dependency_attribution"
 	CORRECT_AMENDMENT = "correct_amendment"
 	REQUEST_CONTEXT_COST = "request_context_cost"
@@ -23,6 +24,7 @@ RAW_REWARD_TABLE: dict[RewardReason, float] = {
 	RewardReason.CORRECT_FLAG: 0.5,
 	RewardReason.ACCURATE_COMMENT: 0.3,
 	RewardReason.CORRECT_DEPENDENCY_ATTRIBUTION: 0.6,
+	RewardReason.PARTIAL_DEPENDENCY_ATTRIBUTION: 0.35,
 	RewardReason.INCORRECT_DEPENDENCY_ATTRIBUTION: 0.1,
 	RewardReason.CORRECT_AMENDMENT: 0.4,
 	RewardReason.REQUEST_CONTEXT_COST: -0.1,

code-review-env/env/runtime_config.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import os
 from dataclasses import dataclass
 
+from env.env_loader import load_env_file
+
 
 @dataclass(frozen=True)
 class RuntimeConfig:
@@ -15,6 +17,7 @@ class RuntimeConfig:
 
 
 def load_runtime_config() -> RuntimeConfig:
+    load_env_file()
     return RuntimeConfig(
         llm_provider=os.getenv("GRAPHREVIEW_LLM_PROVIDER", "ollama_openai_compat"),
         llm_base_url=os.getenv("GRAPHREVIEW_LLM_BASE_URL", "http://localhost:11434/v1"),

code-review-env/graders/hard_grader.py

@@ -38,21 +38,36 @@ class HardGrader(MediumGrader):
 			"GRAPHREVIEW_JUDGE_PROVIDER",
 			"ollama_openai_compat",
 		)
+		self.verifier_provider = os.getenv("GRAPHREVIEW_VERIFIER_PROVIDER", self.judge_provider)
 		self.base_url = os.getenv("GRAPHREVIEW_JUDGE_BASE_URL", "http://localhost:11434/v1")
+		self.verifier_base_url = os.getenv("GRAPHREVIEW_VERIFIER_BASE_URL", self.base_url)
 		self.api_key = os.getenv("GRAPHREVIEW_JUDGE_API_KEY", "ollama")
+		self.verifier_api_key = os.getenv("GRAPHREVIEW_VERIFIER_API_KEY", self.api_key)
 		self.timeout = float(os.getenv("GRAPHREVIEW_JUDGE_TIMEOUT_SECONDS", "8"))
+		self.verifier_timeout = float(os.getenv("GRAPHREVIEW_VERIFIER_TIMEOUT_SECONDS", str(self.timeout)))
 		self.judge_system_prompt = os.getenv(
 			"GRAPHREVIEW_JUDGE_SYSTEM_PROMPT",
 			self.DEFAULT_JUDGE_SYSTEM_PROMPT,
 		)
+		self.verifier_enabled = os.getenv("GRAPHREVIEW_VERIFIER_ENABLED", "true").strip().lower() == "true"
+		self.verifier_model = os.getenv("GRAPHREVIEW_VERIFIER_MODEL", self.judge_model)
+		self.verifier_system_prompt = os.getenv(
+			"GRAPHREVIEW_VERIFIER_SYSTEM_PROMPT",
+			self.DEFAULT_JUDGE_SYSTEM_PROMPT,
+		)
 		self.reasoning_effort = os.getenv("GRAPHREVIEW_JUDGE_REASONING_EFFORT", "none")
 		self.think_value = os.getenv("GRAPHREVIEW_JUDGE_THINK", "false").strip().lower()
 		self.max_judge_calls = int(os.getenv("GRAPHREVIEW_JUDGE_MAX_CALLS", "200"))
 		self.max_consecutive_failures = int(os.getenv("GRAPHREVIEW_JUDGE_MAX_CONSECUTIVE_FAILURES", "3"))
+		self.weight_deterministic = float(os.getenv("GRAPHREVIEW_JUDGE_WEIGHT_DETERMINISTIC", "0.5"))
+		self.weight_primary = float(os.getenv("GRAPHREVIEW_JUDGE_WEIGHT_PRIMARY", "0.3"))
+		self.weight_verifier = float(os.getenv("GRAPHREVIEW_JUDGE_WEIGHT_VERIFIER", "0.2"))
+		self.disagreement_threshold = float(os.getenv("GRAPHREVIEW_JUDGE_DISAGREEMENT_THRESHOLD", "0.5"))
 		self._judge_calls = 0
 		self._consecutive_failures = 0
 		self._judge_cache: dict[str, tuple[float, str]] = {}
 		self.prompt_hash = hashlib.sha256(self.judge_system_prompt.encode("utf-8")).hexdigest()
+		self.verifier_prompt_hash = hashlib.sha256(self.verifier_system_prompt.encode("utf-8")).hexdigest()
 
 	def grade_action(
 		self,
@@ -95,39 +110,91 @@ class HardGrader(MediumGrader):
 			)
 
 		normalized_action = action.model_copy(update={"attributed_to": attributed_to})
-		judge_result = self._judge_dependency_reasoning(module_id, normalized_action)
-		if len(judge_result) == 2:
-			judge_score, explanation = judge_result
-		else:
-			judge_score, explanation = judge_result[0], judge_result[1]
-		if judge_score <= 0.0:
+		primary_score, primary_explanation = self._judge_with_model(
+			module_id=module_id,
+			action=normalized_action,
+			model=self.judge_model,
+			provider=self.judge_provider,
+			base_url=self.base_url,
+			api_key=self.api_key,
+			timeout=self.timeout,
+			system_prompt=self.judge_system_prompt,
+			cache_scope="primary",
+		)
+		verifier_score = primary_score
+		verifier_explanation = "Verifier disabled"
+		if self.verifier_enabled:
+			verifier_score, verifier_explanation = self._judge_with_model(
+				module_id=module_id,
+				action=normalized_action,
+				model=self.verifier_model,
+				provider=self.verifier_provider,
+				base_url=self.verifier_base_url,
+				api_key=self.verifier_api_key,
+				timeout=self.verifier_timeout,
+				system_prompt=self.verifier_system_prompt,
+				cache_scope="verifier",
+			)
+
+		final_score, blend = self._blend_scores(
+			deterministic_score=1.0,
+			primary_score=primary_score,
+			verifier_score=verifier_score,
+		)
+
+		if final_score < 0.45:
 			return make_reward(
 				RewardReason.INCORRECT_DEPENDENCY_ATTRIBUTION,
-				explanation,
+				f"{primary_explanation} | verifier: {verifier_explanation}",
 				metadata={
-					"judge_score": judge_score,
+					"judge_score": primary_score,
+					"verifier_score": verifier_score,
+					"final_score": final_score,
+					"blend": json.dumps(blend, sort_keys=True),
 					"judge_provider": self.judge_provider,
 					"judge_model": self.judge_model,
+					"verifier_provider": self.verifier_provider,
+					"verifier_model": self.verifier_model,
 					"temperature": 0.0,
 					"prompt_hash": self.prompt_hash,
+					"verifier_prompt_hash": self.verifier_prompt_hash,
 				},
 			)
 
 		base_reason = RewardReason.CORRECT_DEPENDENCY_ATTRIBUTION
+		if final_score < 0.75:
+			base_reason = RewardReason.PARTIAL_DEPENDENCY_ATTRIBUTION
 		reward = make_reward(
 			base_reason,
-			explanation,
+			f"{primary_explanation} | verifier: {verifier_explanation}",
 			metadata={
-				"judge_score": judge_score,
+				"judge_score": primary_score,
+				"verifier_score": verifier_score,
+				"final_score": final_score,
+				"blend": json.dumps(blend, sort_keys=True),
 				"judge_provider": self.judge_provider,
 				"judge_model": self.judge_model,
+				"verifier_provider": self.verifier_provider,
+				"verifier_model": self.verifier_model,
 				"temperature": 0.0,
 				"prompt_hash": self.prompt_hash,
+				"verifier_prompt_hash": self.verifier_prompt_hash,
 			},
 		)
 		return reward
 
-	def _judge_dependency_reasoning(self, module_id: str, action: ReviewAction) -> tuple[float, str]:
+	def _judge_with_model(
+		self,
+		module_id: str,
+		action: ReviewAction,
+		model: str,
+		provider: str,
+		base_url: str,
+		api_key: str,
+		timeout: float,
+		system_prompt: str,
+		cache_scope: str,
+	) -> tuple[float, str]:
 		if not self.judge_enabled:
 			return 1.0, "Judge disabled by configuration; graph-consistent attribution accepted"
 
@@ -145,21 +212,21 @@ class HardGrader(MediumGrader):
 			"rubric": "0.0 wrong or unsupported; 0.5 partially justified; 1.0 well-justified root cause",
 		}
 		payload_text = json.dumps(payload, sort_keys=True)
-		cache_key = hashlib.sha256(payload_text.encode("utf-8")).hexdigest()
+		cache_key = hashlib.sha256(f"{cache_scope}:{model}:{payload_text}".encode("utf-8")).hexdigest()
 		cached = self._judge_cache.get(cache_key)
 		if cached is not None:
 			return cached
 
 		try:
 			self._judge_calls += 1
-			client = OpenAI(api_key=self.api_key, base_url=self.base_url, timeout=self.timeout)
+			client = OpenAI(api_key=api_key, base_url=base_url, timeout=timeout)
 
 			request_kwargs: dict[str, Any] = {
-				"model": self.judge_model,
+				"model": model,
 				"temperature": 0.0,
 				"response_format": {"type": "json_object"},
 				"messages": [
-					{"role": "system", "content": self.judge_system_prompt},
+					{"role": "system", "content": system_prompt},
 					{"role": "user", "content": payload_text},
 				],
 			}
@@ -167,7 +234,7 @@ class HardGrader(MediumGrader):
 			if self.reasoning_effort in {"none", "low", "medium", "high"}:
 				request_kwargs["reasoning_effort"] = self.reasoning_effort
 
-			if self.judge_provider == "ollama_openai_compat":
+			if provider == "ollama_openai_compat":
 				if self.think_value in {"true", "false", "low", "medium", "high"}:
 					think: bool | str
 					if self.think_value in {"low", "medium", "high"}:
@@ -206,3 +273,43 @@ class HardGrader(MediumGrader):
 			if start >= 0 and end > start:
 				return json.loads(text[start : end + 1])
 			raise
+
+	def _blend_scores(
+		self,
+		deterministic_score: float,
+		primary_score: float,
+		verifier_score: float,
+	) -> tuple[float, dict[str, float | bool]]:
+		d = max(0.0, min(1.0, deterministic_score))
+		p = max(0.0, min(1.0, primary_score))
+		v = max(0.0, min(1.0, verifier_score))
+
+		wd = max(self.weight_deterministic, 0.0)
+		wp = max(self.weight_primary, 0.0)
+		wv = max(self.weight_verifier, 0.0)
+		disagreement = abs(p - v)
+		disagreement_guard = disagreement >= self.disagreement_threshold
+		if disagreement_guard:
+			wp = min(wp, 0.1)
+			wv = max(wv, 0.4)
+			wd = max(wd, 0.5)
+
+		total = wd + wp + wv
+		if total <= 0:
+			return 0.0, {"wd": 0.0, "wp": 0.0, "wv": 0.0, "disagreement": disagreement, "guard": disagreement_guard}
+
+		wd /= total
+		wp /= total
+		wv /= total
+
+		final = (wd * d) + (wp * p) + (wv * v)
+		if p == 1.0 and v == 0.0:
+			final = min(final, 0.45)
+
+		return final, {
+			"wd": wd,
+			"wp": wp,
+			"wv": wv,
+			"disagreement": disagreement,
+			"guard": disagreement_guard,
+		}

code-review-env/graph/graph_manager.py

@@ -57,6 +57,7 @@ class GraphManager:
                 edge_type=edge.edge_type.value,
                 import_line=edge.import_line,
                 weight=edge.weight,
+                connection_summary=edge.connection_summary,
             )
 
         self._graph_cache = graph

code-review-env/llm/__init__.py

@@ -0,0 +1 @@
+"""LLM helpers for GraphReview."""

code-review-env/llm/edge_summarizer.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+
+from openai import OpenAI
+
+
+@dataclass(frozen=True)
+class EdgeSummaryInput:
+    source_module_id: str
+    target_module_id: str
+    edge_type: str
+    import_line: str
+    scope: str
+
+
+class EdgeSummarizer:
+    """Generate concise edge relationship summaries with deterministic fallback."""
+
+    def __init__(self) -> None:
+        self.enabled = os.getenv("GRAPHREVIEW_EDGE_SUMMARY_ENABLED", "false").strip().lower() == "true"
+        if os.getenv("PYTEST_CURRENT_TEST"):
+            self.enabled = False
+        self.base_url = os.getenv("GRAPHREVIEW_EDGE_SUMMARY_BASE_URL", os.getenv("GRAPHREVIEW_LLM_BASE_URL", "http://localhost:11434/v1"))
+        self.api_key = os.getenv("GRAPHREVIEW_EDGE_SUMMARY_API_KEY", os.getenv("GRAPHREVIEW_LLM_API_KEY", "ollama"))
+        self.model = os.getenv("GRAPHREVIEW_EDGE_SUMMARY_MODEL", os.getenv("GRAPHREVIEW_LLM_MODEL_AGENT", "gemma4:e4b"))
+        self.timeout = float(os.getenv("GRAPHREVIEW_EDGE_SUMMARY_TIMEOUT_SECONDS", "8"))
+        self.max_calls = int(os.getenv("GRAPHREVIEW_EDGE_SUMMARY_MAX_CALLS", "5000"))
+        self._calls = 0
+        self._cache: dict[str, str] = {}
+
+    def summarize(self, edge: EdgeSummaryInput) -> str:
+        payload = json.dumps(edge.__dict__, sort_keys=True)
+        cache_key = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        summary = self._fallback_summary(edge)
+        if self.enabled and self._calls < self.max_calls:
+            try:
+                self._calls += 1
+                client = OpenAI(api_key=self.api_key, base_url=self.base_url, timeout=self.timeout)
+                response = client.chat.completions.create(
+                    model=self.model,
+                    temperature=0.0,
+                    messages=[
+                        {
+                            "role": "system",
+                            "content": (
+                                "You summarize Python dependency edges. Produce one sentence (max 24 words) "
+                                "explaining why source depends on target using the import/call evidence."
+                            ),
+                        },
+                        {"role": "user", "content": payload},
+                    ],
+                )
+                text = (response.choices[0].message.content or "").strip()
+                if text:
+                    summary = text[:240]
+            except Exception:
+                # Keep deterministic fallback to avoid breaking seed.
+                pass
+
+        self._cache[cache_key] = summary
+        return summary
+
+    @staticmethod
+    def _fallback_summary(edge: EdgeSummaryInput) -> str:
+        edge_kind = edge.edge_type.replace("_", " ")
+        evidence = edge.import_line.strip() or "implicit usage"
+        if len(evidence) > 120:
+            evidence = evidence[:117] + "..."
+        return (
+            f"{edge.source_module_id} depends on {edge.target_module_id} via {edge_kind}; "
+            f"evidence: {evidence}."
+        )

code-review-env/llm/lora_adapter.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from env.action import ReviewAction
+
+
+@dataclass(frozen=True)
+class TransitionRecord:
+    source_root: str
+    episode_id: str
+    module_id: str
+    step_number: int
+    action_type: str
+    reward: float
+    done: bool
+    task_id: str
+    observation_summary: str
+    action_payload: dict[str, object]
+
+
+class LoRATrajectoryLogger:
+    """Append RL transitions to JSONL for optional LoRA fine-tuning workflows."""
+
+    def __init__(self) -> None:
+        self.enabled = os.getenv("GRAPHREVIEW_LORA_ENABLED", "false").strip().lower() == "true"
+        output_path = os.getenv("GRAPHREVIEW_LORA_DATA_PATH", "outputs/lora/transitions.jsonl")
+        self.path = Path(output_path)
+
+    def log(
+        self,
+        *,
+        source_root: str,
+        episode_id: str,
+        module_id: str,
+        step_number: int,
+        action: ReviewAction,
+        reward: float,
+        done: bool,
+        task_id: str,
+        observation_summary: str,
+    ) -> None:
+        if not self.enabled:
+            return
+
+        record = TransitionRecord(
+            source_root=source_root,
+            episode_id=episode_id,
+            module_id=module_id,
+            step_number=step_number,
+            action_type=action.action_type.value,
+            reward=reward,
+            done=done,
+            task_id=task_id,
+            observation_summary=observation_summary,
+            action_payload=action.model_dump(mode="json", exclude_none=True),
+        )
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            **record.__dict__,
+            "created_at": datetime.now(UTC).isoformat(),
+        }
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, sort_keys=True) + "\n")

code-review-env/llm/lora_finetune.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+def export_sft_dataset(transitions_path: Path, output_path: Path) -> int:
+    """Convert transition logs into a simple instruction-tuning JSONL dataset."""
+    if not transitions_path.exists():
+        raise FileNotFoundError(f"Transitions file not found: {transitions_path}")
+
+    rows = transitions_path.read_text(encoding="utf-8").splitlines()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    count = 0
+    with output_path.open("w", encoding="utf-8") as out:
+        for row in rows:
+            payload = json.loads(row)
+            sample = {
+                "instruction": (
+                    "Review this module using graph-aware reasoning and choose the best next action."
+                ),
+                "input": payload.get("observation_summary", ""),
+                "output": json.dumps(payload.get("action_payload", {}), sort_keys=True),
+                "meta": {
+                    "reward": payload.get("reward", 0.0),
+                    "task_id": payload.get("task_id", ""),
+                    "module_id": payload.get("module_id", ""),
+                },
+            }
+            out.write(json.dumps(sample, sort_keys=True) + "\n")
+            count += 1
+    return count
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Prepare LoRA fine-tuning dataset from GraphReview transitions")
+    parser.add_argument(
+        "--transitions",
+        default="outputs/lora/transitions.jsonl",
+        help="Input transition JSONL produced by runtime",
+    )
+    parser.add_argument(
+        "--output",
+        default="outputs/lora/sft_dataset.jsonl",
+        help="Output SFT JSONL dataset path",
+    )
+    return parser
+
+
+def main() -> None:
+    args = _build_parser().parse_args()
+    count = export_sft_dataset(Path(args.transitions), Path(args.output))
+    print(json.dumps({"ok": True, "samples": count, "output": args.output}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

code-review-env/parser/ast_parser.py

@@ -9,6 +9,7 @@ from pydantic import BaseModel
 
 from db.schema import EdgeType
 from db.store import Store
+from llm.edge_summarizer import EdgeSummarizer, EdgeSummaryInput
 from parser.linter import run_linters
 from parser.summarizer import summarize_module
 
@@ -205,6 +206,7 @@ def parse_directory(target_dir: Path, db_path: str | None = None) -> Store:
     py_files = _iter_python_files(target_dir)
     parsed_modules = [parse_python_file(py_file, target_dir) for py_file in py_files]
     known_module_ids = {parsed.module_id for parsed in parsed_modules}
+    edge_summarizer = EdgeSummarizer()
 
     for py_file, parsed in zip(py_files, parsed_modules):
         issues = run_linters(py_file)
@@ -223,12 +225,22 @@ def parse_directory(target_dir: Path, db_path: str | None = None) -> Store:
         )
         for imported in parsed.imports:
             if imported.target_module and imported.target_module in known_module_ids:
+                connection_summary = edge_summarizer.summarize(
+                    EdgeSummaryInput(
+                        source_module_id=parsed.module_id,
+                        target_module_id=imported.target_module,
+                        edge_type=imported.edge_type.value,
+                        import_line=imported.import_line,
+                        scope=imported.scope,
+                    )
+                )
                 store.upsert_edge(
                     source_module_id=parsed.module_id,
                     target_module_id=imported.target_module,
                     edge_type=imported.edge_type,
                     import_line=imported.import_line,
                     weight=imported.weight,
+                    connection_summary=connection_summary,
                 )
 
     return store

code-review-env/parser/graph_builder.py

@@ -15,6 +15,7 @@ class EdgeRecord(BaseModel):
     import_line: str
     scope: str
     weight: float
+    connection_summary: str = ""
 
 
 def _build_intra_file_edges(parsed: ParsedModule, available_chunk_ids: set[str]) -> list[EdgeRecord]:

code-review-env/pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
 
 [project.scripts]
 server = "server.app:main"
+graphreview = "run_project:main"
 
 [tool.pytest.ini_options]
 pythonpath = ["."]

code-review-env/run_project.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from graders.review_runner import generate_reports, run_review
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Unified GraphReview runner: seed + run easy/medium/hard + generate artifacts"
+    )
+    parser.add_argument("target", help="Target Python project folder")
+    parser.add_argument("--db-path", default=None, help="Optional SQLite DB path")
+    parser.add_argument("--force-seed", action="store_true", help="Force graph reseed")
+    parser.add_argument("--skip-seed", action="store_true", help="Skip seeding and reuse DB")
+    parser.add_argument("--modules", nargs="*", default=None, help="Optional module focus list")
+    parser.add_argument("--filter-hops", type=int, default=1, help="Neighbor expansion hops for --modules")
+    parser.add_argument("--output-dir", default="outputs", help="Artifacts output directory")
+    parser.add_argument("--report-prefix", default="graphreview_full", help="Artifact prefix")
+    parser.add_argument("--no-progress", action="store_true", help="Disable progress logs")
+    parser.add_argument(
+        "--levels",
+        nargs="*",
+        choices=["easy", "medium", "hard"],
+        default=["easy", "medium", "hard"],
+        help="Review levels to run",
+    )
+    return parser
+
+
+def main() -> None:
+    args = _build_parser().parse_args()
+    target = Path(args.target).resolve()
+
+    summary: dict[str, object] = {
+        "target": str(target),
+        "levels": {},
+    }
+
+    for idx, level in enumerate(args.levels):
+        scores = run_review(
+            target=target,
+            db_path=args.db_path,
+            grader_level=level,
+            force_seed=args.force_seed if idx == 0 else False,
+            skip_seed=args.skip_seed if idx == 0 else True,
+            show_progress=not args.no_progress,
+            module_filter=args.modules,
+            filter_hops=args.filter_hops,
+        )
+        total = float(sum(scores.values()))
+        summary["levels"][level] = {
+            "modules": len(scores),
+            "raw_total": total,
+            "avg_raw_per_module": (total / len(scores)) if scores else 0.0,
+        }
+
+    artifacts = generate_reports(
+        target=target,
+        db_path=args.db_path,
+        output_dir=args.output_dir,
+        module_filter=args.modules,
+        filter_hops=args.filter_hops,
+        report_prefix=args.report_prefix,
+    )
+
+    summary["artifacts"] = {
+        "markdown": artifacts.markdown_path,
+        "json": artifacts.json_path,
+        "html": artifacts.html_path,
+        "confidence_score": artifacts.confidence_score,
+        "module_count": artifacts.module_count,
+        "edge_count": artifacts.edge_count,
+    }
+
+    print(json.dumps(summary, indent=2))
+
+
+if __name__ == "__main__":
+    main()

code-review-env/server/app.py

@@ -14,12 +14,15 @@ from sqlmodel import Session, select
 
 from db.schema import ModuleEdge, ModuleNode
 from db.store import Store
+from env.env_loader import load_env_file
 from env.action import ActionType, ReviewAction
 from env.environment import CodeReviewEnv, StepResult
 from env.observation import CodeObservation
 from env.state import GraphState
 from visualizer.report_generator import GeneratedArtifacts, generate_phase5_outputs
 
+load_env_file()
+
 
 class ResetRequest(BaseModel):
 	model_config = ConfigDict(strict=True, extra="forbid")
@@ -297,6 +300,7 @@ def ui_result(report_path: str = Query(..., min_length=1)) -> ResultDetail:
 				"edge_type",
 				"import_line",
 				"weight",
+				"connection_summary",
 			],
 		},
 	)

code-review-env/tests/test_graders.py

@@ -93,7 +93,9 @@ def test_hard_grader_dependency_attribution(tmp_path: Path) -> None:
     graph = GraphManager(source_root=str(project), db_path=str(db_path))
     grader = HardGrader(store, graph)
 
-    grader._judge_dependency_reasoning = lambda module_id, action: (1.0, "ok", "hash")  # type: ignore[method-assign]
+    grader._judge_with_model = (  # type: ignore[method-assign]
+        lambda module_id, action, model, provider, base_url, api_key, timeout, system_prompt, cache_scope: (1.0, "ok")
+    )
 
     good = grader.grade_episode(
         module_id="a",

code-review-env/visualizer/pyvis_renderer.py

@@ -54,12 +54,19 @@ def render_graph_html(
 
     for edge in edges:
         edge_type = str(edge.get("edge_type", "explicit_import"))
+        edge_title = str(edge.get("title", edge_type))
+        formatted_title = (
+            "<div style='max-width:360px'>"
+            f"<b>{edge_type}</b><br>{edge_title}"
+            "</div>"
+        )
         net.add_edge(
             source=str(edge["source"]),
             to=str(edge["target"]),
-            title=str(edge.get("title", edge_type)),
+            title=formatted_title,
             color=EDGE_COLORS.get(edge_type, EDGE_COLORS["explicit_import"]),
-            value=max(float(edge.get("weight", 1.0)), 0.2),
+            value=1.0,
+            width=max(1.0, min(float(edge.get("weight", 1.0)) * 1.3, 2.2)),
             arrows="to",
         )
 
@@ -85,7 +92,7 @@ def render_graph_html(
                 },
                 "edges": {
                     "smooth": {"enabled": False},
-                    "arrows": {"to": {"enabled": True, "scaleFactor": 0.5}},
+                    "arrows": {"to": {"enabled": True, "scaleFactor": 0.35}},
                 },
             }
         )

code-review-env/visualizer/report_generator.py

@@ -347,6 +347,7 @@ def _build_json_payload(
             "edge_type": edge.edge_type.value,
             "weight": edge.weight,
             "import_line": edge.import_line,
+            "connection_summary": edge.connection_summary,
         }
         for edge in sorted(edges, key=lambda item: (item.source_module_id, item.target_module_id, item.import_line))
     ]
@@ -562,7 +563,9 @@ def generate_phase5_outputs(
                 "target": edge.target_module_id,
                 "edge_type": edge.edge_type.value,
                 "weight": edge.weight,
-                "title": f"{edge.edge_type.value}: {edge.import_line}",
+                "title": (
+                    f"{edge.edge_type.value}: {edge.connection_summary or edge.import_line}"
+                ),
             }
         )
 

plans/phase-06-adaptive-judge-edge-summary-lora-plan.md

@@ -0,0 +1,63 @@
+# Phase 06 Plan - Adaptive Judging, Edge Intelligence, LoRA Hooks, and Config Hygiene
+
+## Objective
+Upgrade the current GraphReview environment for Round 1 reliability with:
+- Adaptive hard-grader fusion to reduce catastrophic judge mistakes.
+- Per-edge connection summaries generated by LLM (with deterministic fallback).
+- LoRA learning hooks so the system can improve across projects.
+- Centralized `.env`-driven configuration for runtime, models, server, and reporting.
+
+## Design Principles
+- Occam's Razor: add only minimal mechanisms that directly improve reliability and score.
+- Single Responsibility: parser builds graph; graders score; learning hooks collect trajectories.
+- Determinism First: easy/medium deterministic; hard judge constrained and auditable.
+- Fail-Safe Defaults: LLM optional, deterministic fallback mandatory.
+- Open/Closed: add extensible configs and adapters without rewriting core runtime.
+
+## Scope
+1. Adaptive hard-grader fusion
+- Add deterministic gate + primary judge + verifier judge fusion.
+- Dynamic weighting with disagreement-aware reweighting.
+- Persist judge metadata and fusion breakdown in annotation payload.
+
+2. Edge connection summaries
+- Extend `ModuleEdge` schema with `connection_summary`.
+- Build `llm/edge_summarizer.py` using OpenAI-compatible API.
+- Generate edge summary for each edge during seed.
+- Fallback summary if LLM unavailable.
+
+3. LoRA learning hooks
+- Add transition logging to JSONL during runtime (`state`, `action`, `reward`, `done`).
+- Add `llm/lora_finetune.py` skeleton for dataset export + optional train path.
+- Keep training optional via env vars and feature flags.
+
+4. `.env` and config hygiene
+- Add `.env` file with all tunables: host/port, DB, models, judge settings, edge summarizer, LoRA toggles.
+- Add lightweight env loader utility and invoke early in runtime/server/migrations.
+
+## Implementation Steps
+1. Add env loader and wire it to startup-sensitive modules.
+2. Add `connection_summary` field + migration + store methods.
+3. Add edge summarizer module and integrate into seed pipeline.
+4. Add adaptive hard grader fusion and metadata persistence.
+5. Add LoRA transition logger + finetune utility script.
+6. Update visualization and report generation to display connection summaries.
+7. Update README with new env variables and usage.
+
+## Verification
+- Seeding produces non-empty `connection_summary` for all stored edges.
+- Hard grader returns stable fused score and persists fusion metadata.
+- If primary judge and verifier disagree strongly, final score is reduced safely.
+- Runtime emits LoRA trajectory JSONL when enabled.
+- Server reads `.env` and applies host/port/model settings.
+
+## Risks and Mitigations
+- LLM edge summarization latency: use caching + timeout + deterministic fallback.
+- Judge model outages: keep deterministic gate and verifier fallback behavior.
+- LoRA dependency burden: keep optional and fail gracefully if packages absent.
+
+## Definition of Done
+- Plan implemented in code with passing runtime smoke checks.
+- New config values available through `.env` and documented.
+- Graph UI and reports now show concise per-edge connection summaries.
+- Hard grader is safer against single-model catastrophic errors.

temp.md

@@ -0,0 +1,1333 @@
+You are a project planning expert. I am attending a pre Hackathon competition and I need to build a rl environment. I am building this project for this submission
+
+# Builder Prompt — GraphReview RL Environment
+
+You are an expert Python engineer planner. You do not build. You can add more tools to catch more security vulnerabilities for the modules before actually sending it out. ANd you can also turn on thinking for the gemma 4 model if it works better and ensure it runs on all the modules and actually finds info not just repeating the stuff from previous models. But the previous info should also be provided as context and told to find more if possible about those errors and any new errors. a production-quality RL environment for a competitive hackathon (OpenEnv Round 1). You have one job: build the GraphReview environment correctly, phase by phase, without breaking prior work.
+
+---
+
+## What You Are Building
+
+An OpenEnv-compliant RL environment where an LLM agent reviews Python code with full dependency graph awareness. The environment parses a Python codebase into a persistent SQLite-backed dependency graph, pre-computes ground truth linter flags, and exposes a step()/reset()/state() API for an agent to interact with.
+
+This is online RL — no training dataset is needed. The ground truth (pylint/bandit/pyflakes results) is computed once at seed time and stored in SQLite. The agent explores the environment and receives rewards compared against that ground truth.
+
+The full phase plan and architecture are provided below. Read the entire plan before writing a single line of code.
+
+---
+
+## Your Operating Rules
+
+1. **Before building each phase, read the full plan for that phase.** Do not start coding until you understand what the phase produces and what its success criteria are.
+
+2. **Ask me questions before starting if any of the following are unclear:**
+   - A design decision that affects DB schema or file structure
+   - Anything that would be hard to change later (interfaces, Pydantic models, DB tables)
+   - Ambiguity in how two components interact
+   Do NOT ask about low-level implementation details — choose the best approach yourself.
+
+3. **Use context7 MCP to look up documentation** for: openenv-core, SQLAlchemy, NetworkX, Pyvis, astroid, pylint API, FastAPI, Pydantic v2. Do not rely on memory for library APIs — always verify.
+
+4. **One phase at a time.** Complete a phase fully before moving to the next. Each phase has explicit success criteria — verify them before declaring a phase done.
+
+5. **Never break prior phases.** If a later phase requires changing an earlier interface, explicitly flag it, explain why, and get confirmation before making the change.
+
+6. **DB is the source of truth.** All state lives in SQLite. Nothing important lives only in memory. reset() clears only task-run annotations — never re-parses the codebase.
+
+7. **Token budget is a hard constraint.** No observation may exceed 2000 tokens. Enforce this in token_budget.py — do not leave it as a soft guideline.
+
+8. **Graders must be deterministic.** Easy and medium graders: zero LLM calls, same input always produces same output. Hard grader: temperature=0, document prompt hash. Test this explicitly.
+
+9. **inference.py log format is mandatory.** [START], [STEP], [END] format must be exact. Any deviation causes evaluation failure. Treat this as a contract.
+
+10. **Write clean, typed Python.** All functions typed. All Pydantic models complete. No `Any` types unless unavoidable with explanation.
+
+---
+
+## Phase Plan
+
+[INSERT FULL PHASE PLAN HERE — paste the contents of the phase plan artifact]
+
+---
+
+## Sample Project Specification
+
+The sample_project/ directory must contain exactly these files with these injected bugs:
+
+```
+auth.py          — validate_token() can return None (not handled)
+checkout.py      — calls auth.validate_token(), doesn't check for None
+cart.py          — style violations only (PEP8)
+config.py        — missing required key in get_config() (root cause of cascade)
+database.py      — SQL query built with string concatenation (SQL injection)
+utils.py         — unused imports, dead code
+models.py        — clean file (no issues, tests APPROVE path)
+payments.py      — depends on checkout.py, inherits None risk
+api.py           — depends on auth.py and checkout.py
+main.py          — entry point, light glue code
+```
+
+Task mapping:
+- easy_task: cart.py (style only)
+- medium_task: checkout.py + auth.py (null reference)
+- hard_task: config.py → auth.py → checkout.py (cascade)
+
+---
+
+## Tech Stack
+
+- Python 3.11
+- SQLite via SQLAlchemy ORM
+- NetworkX + astroid + Python ast
+- pylint + bandit + pyflakes
+- Pyvis for visualization
+- Pydantic v2
+- FastAPI
+- OpenAI client (inference.py + hard grader judge)
+- openenv-core
+- context7 MCP for all library lookups
+
+---
+
+## Start Instructions
+
+Begin with Phase 1. Before writing any code:
+1. Use context7 MCP to look up: openenv-core spec, SQLAlchemy ORM setup, astroid API
+2. Ask me any design questions that affect DB schema or file structure
+3. Confirm the sample_project file list with me if you want to adjust it
+4. Then build Phase 1 completely and verify all success criteria before stopping
+
+These are the requirements
+
+Registration
+
+14th March - 3rd April
+
+Declaration
+
+Before R1
+
+Prepare
+
+Now - 25th March
+
+Round 1
+
+25th March - 8th April
+
+Results
+
+10th April
+
+Finale
+
+25th-26th April
+
+Welcome Shreyas  S Joshi!
+
+shreyasjoshi2511@gmail.com
+Copy
+Join the Discord Community
+
+All announcements, mentor access, and team matching happens here.
+
+
+Join Discord
+QUICK TOGGLe
+
+Team form Submission
+
+Preparatory Course
+
+Start Assessment
+
+FAQs
+
+step 1
+
+How will you compete?
+
+Choose solo or team before you can start the assessment
+
+Step 1 Complete
+Team: Shreyas S Joshi's team
+
+👤
+Athmabhiram S J
+athmabhiram@gmail.com
+Accepted
+👤
+Shreyas S Joshi
+shreyasjoshi2511@gmail.com
+Team Lead
+🔒
+Team is permanently locked. Changes are not allowed after confirmation.
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp
+
+OpenEnv Round 1 Bootcamp: Build Your First RL Environment
+
+Live walkthrough to submit a strong Round 1 entry
+
+timing
+
+8:00 PM Onwards
+
+Wednesday, 1st April
+
+Host
+
+
+Ben Burtenshaw
+
+Community Education in AI at Hugging Face
+
+
+Pulkit Aneja
+
+Scaler Instructor
+
+Watch Recording
+
+PROBLEM STATEMENT
+
+Round 1 — Problem Statement
+
+The Task
+
+Build a complete, real-world OpenEnv environment that an AI agent can learn from through the standard  step() / reset() / state()  API.
+
+Key Requirements at a Glance
+
+Must simulate a real-world task (not games or toys)
+
+Implement full OpenEnv spec: typed models, step()/reset()/state(), openenv.yaml
+
+Minimum 3 tasks with agent graders (easy → medium → hard, scores/reward 0.0–1.0)
+
+Meaningful reward function with partial progress signals
+
+Baseline inference script with reproducible scores
+
+Deploy to Hugging Face Spaces + working Dockerfile
+
+README with environment description, action/observation spaces, setup instructions
+
+Functional Requirements
+
+Real-world task simulation
+
+The environment must simulate a task humans actually do. Not games, not toys. Examples: email triage, code review, data cleaning, scheduling, customer support, content moderation.
+
+OpenEnv spec compliance
+
+Implement the full OpenEnv interface: typed Observation, Action, and Reward Pydantic models. step(action) → returns observation, reward, done, info. reset() → returns initial observation. state() → returns current state. openenv.yaml with metadata. Tested via openenv validate.
+
+Minimum 3 tasks with agent graders
+
+Each task defines a concrete objective an agent must accomplish, with a programmatic grader that scores performance (0.0–1.0). Tasks should range: easy → medium → hard. Graders must have clear, deterministic success/failure criteria.
+
+Meaningful reward function
+
+Provides signal over the full trajectory (not just binary end-of-episode). Rewards partial progress toward task completion. Penalizes clearly undesirable behavior (e.g. infinite loops, destructive actions).
+
+Baseline inference script
+
+Uses the OpenAI API client to run a model against the environment. Reads API credentials from environment variables (OPENAI_API_KEY). Produces a reproducible baseline score on all 3 tasks.
+
+Detailed Requirements
+
+Non-Functional Requirements
+
+Deploys to a Hugging Face Space
+
+Environment must run as a containerized HF Space tagged with openenv.
+
+Containerized execution
+
+Must include a working Dockerfile. The environment should start cleanly with docker build + docker run.
+
+Documentation
+
+README must include: environment description and motivation, action and observation space definitions, task descriptions with expected difficulty, setup and usage instructions, baseline scores.
+
+Parameter
+
+Weight
+
+Description
+
+Real-world utility
+
+30%
+
+Does the environment model a genuine task? Would someone actually use this to train or evaluate agents?
+
+Task & grader quality
+
+25%
+
+Are tasks well-defined with clear objectives? Do graders accurately and fairly measure success? Meaningful difficulty progression?
+
+Environment design
+
+20%
+
+Clean state management, sensible action/observation spaces, good reward shaping, proper episode boundaries.
+
+Code quality & spec compliance
+
+15%
+
+Follows OpenEnv spec, clean project structure, typed models, documented, tested, Dockerfile works.
+
+Creativity & novelty
+
+10%
+
+Novel problem domain, interesting mechanics, clever reward design, original approach.
+
+Scoring Breakdown
+
+Real-world utility (30%)
+
+•  0–5: Toy/artificial problem with no practical application
+
+•  6–15: Valid domain but shallow modeling of the real task
+
+•  16–25: Good domain modeling, would be useful for agent evaluation
+
+•  26–30: Excellent — fills a real gap, immediate value for the RL/agent community
+
+Task & grader quality (25%)
+
+•  3+ tasks with difficulty range?
+
+•  Graders produce scores between 0.0–1.0?
+
+•  Graders deterministic and reproducible?
+
+•  Hard task genuinely challenges frontier models?
+
+Environment design (20%)
+
+•  reset() produces clean state?
+
+•  Action/observation types well-designed and documented?
+
+•  Reward function provides useful varying signal (not just sparse)?
+
+•  Episode boundaries sensible?
+
+Code quality & spec compliance (15%)
+
+•  openenv validate passes?
+
+•  docker build && docker run works?
+
+•  HF Space deploys and responds?
+
+•  Baseline script runs and reproduces scores?
+
+Creativity & novelty (10%)
+
+•  Domain we haven’t seen in OpenEnv before?
+
+•  Reward design has interesting properties?
+
+•  Clever mechanics that make the environment engaging?
+
+Evaluation Criteria
+
+Phase 1: Automated Validation
+
+Pass/fail gate — HF Space deploys, OpenEnv spec compliance, Dockerfile builds, baseline reproduces, 3+ tasks with graders.
+
+Phase 2: Agentic Evaluation
+
+Scored — baseline agent re-run, standard Open LLM agent (e.g. Nemotron 3 Super) run against all environments, score variance check.
+
+Phase 3: Human Review
+
+Top submissions reviewed by Meta and Hugging Face engineers for real-world utility, creativity, and exploit checks.
+
+Disqualification Criteria
+
+Environment does not deploy or respond
+
+Plagiarized or trivially modified existing environments
+
+Graders that always return the same score
+
+No baseline inference script
+
+How Judging works
+
+Pre-Submission Checklist  — all must pass or you're disqualified
+
+HF Space deploys
+
+Automated ping to the Space URL — must return 200 and respond to reset()
+
+OpenEnv spec compliance
+
+Validate openenv.yaml, typed models, step()/reset()/state() endpoints
+
+Dockerfile builds
+
+Automated docker build on the submitted repo
+
+Baseline reproduces
+
+Run the submitted inference script — must complete without error and produce scores
+
+3+ tasks with graders
+
+Enumerate tasks, run each grader, verify scores/reward in 0.0–1.0 range
+
+Mandatory Additional Instructions
+
+Before submitting, ensure the following variables are defined in your environment configuration:
+
+API_BASE_URL   The API endpoint for the LLM.
+
+MODEL_NAME     The model identifier to use for inference.
+
+HF_TOKEN       Your Hugging Face / API key.
+
+The inference script must be named `inference.py` and placed in the root directory of the project
+
+Participants must use OpenAI Client for all LLM calls using above variables
+
+Participants must emit structured stdout logs strictly following the [START], [STEP], and [END] format defined in the sample inference.py provided below. Any deviation in field names, ordering, or formatting will result in incorrect evaluation scoring. Refer to the Sample Inference Script for the complete format specification and examples.
+
+Infra Restrictions
+
+Runtime of inference script should be less than 20min 
+
+Make sure your env and inference can run on a machine with vcpu=2, memory=8gb
+
+Validator
+
+Run the pre-submission validation script before submitting
+
+NEW
+Sample Inference Script 
+
+NEW
+Pre Validation Script
+
+Submission window opens on 28th March
+
+Deadline: 8 Apr 11:59 PM
+
+
+Submit your Assessment
+→
+Study material
+
+Preparatory Course
+
+4 modules · ~3.5 hours 
+
+Each module: read the README first, then open the notebook in Colab. No local setup needed.
+
+ Module 1: Why OpenEnv?
+
+ESSENTIAL FOR ROUND 1
+
+45 min
+
+Module 2: Using Existing Environments
+
+ESSENTIAL FOR ROUND 1
+
+50 min
+
+ Module 3: Deploying Environments
+
+ESSENTIAL FOR ROUND 1
+
+45 min
+
+Module 4: Building Your Own Environment
+
+ MOST IMPORTANT FOR ROUND 1
+
+60 min
+
+View full course repository
+
+GUIDE
+
+Round 1 Guide
+
+What to Expect
+
+When Round 1 opens, you'll choose 1 of 4–5 problem statements and build an OpenEnv environment around it.
+
+Example of what a problem statement looks like
+
+"Build a mini-game RL environment with clearly defined tasks, automated graders, and reward logic using the OpenEnv framework."
+
+→ Create a mini-game an AI agent can play
+
+→ Define tasks with increasing difficulty
+
+→ Write graders that verify task completion
+
+→ Define reward logic for scoring
+
+→ Package using OpenEnv for automated evaluation
+
+Evaluation Criteria
+
+Runtime correctness
+
+Runs without errors
+
+Interface compliance
+
+Follows OpenEnv standard
+
+Task design
+
+ Clear, realistic, testable
+
+Grading logic
+
+ Reward system makes sense
+
+20,000 → 3,000 teams advance
+
+Prerequisites
+
+Install before April 1st.
+
+Required
+
+Python 3.10+
+
+Install 3.10, 3.11, or 3.12.
+
+$
+python --version
+Copy
+Git + GitHub account
+
+Push your submission to GitHub or HF.
+
+$
+git --version
+Copy
+Hugging Face CLI
+
+Deploy to HF Spaces.
+
+$
+pip install huggingface_hub --version
+Copy
+$
+huggingface-cli login
+Copy
+OpenEnv
+
+The framework.
+
+$
+pip install openenv-core
+Copy
+Google Colab
+
+Prep course runs in Colab. Free tier works.
+
+$
+pip install openenv-core
+Copy
+OpenEnv
+
+The framework.
+
+→ colab.research.google.com
+Copy
+Docker
+
+Isolated container testing.
+
+docker --version
+Copy
+Recommended
+
+VS Code
+
+Best Python + Docker support
+
+How to Submit
+
+When Round 1 starts on 1 April:
+
+Step 1
+
+Application Form
+Choose 1 of the 4–5 problem statements revealed on the platform.
+
+Step 2
+
+ Scaffold
+$
+openenv init my_env
+Copy
+Generate project structure.
+
+Step 3
+
+Build
+Define your environment in the generated files.
+
+Step 4
+
+Test locally
+$
+uv run server
+Copy
+Step 5
+
+Deploy
+$
+openenv push --repo-id your-username/my-env
+Copy
+Step 6
+
+ Submit
+Paste your HF Spaces URL here before the deadline.
+
+Deadline: 8 April 2026, 11:59 PM IST
+
+Step 2
+
+Submit your Assessment
+
+Complete Step 1 first
+
+Problem Statement is live. Build and submit.
+
+Round 1 begins 
+
+Submission window opens on 28th March
+
+Deadline: 8 Apr 11:59 PM
+
+
+Submit your Assessment
+→
+NOTE: Only team leaders can make the final submission.
+
+FAQs
+
+Frequently Asked Questions
+
+
+
+
+
+
+
+
+
+
+
+
+
+Need help? Reach out to us
+
+help_openenvhackathon@scaler.com
+
+Contact Support
+
+submission Deadline: 8th April 11:59 PM
+
+
+Submit your Assessment
+→
+How to Submit?
+
+
+
+Great question. Here's exactly what the agent does in a **Code Review RL Environment:**
+
+---
+
+## 🤖 The Agent's Job
+
+The agent acts as a **junior code reviewer**. Each episode, it's shown a code snippet and must take actions to review it — just like a human would on GitHub.
+
+---
+
+## 🎮 The Action Space
+
+The agent can take these actions:
+
+```
+APPROVE          → Code looks good, no issues
+FLAG_STYLE       → Flag a style/formatting issue
+FLAG_BUG         → Flag a logic bug
+FLAG_SECURITY    → Flag a security vulnerability
+ADD_COMMENT(txt) → Leave a review comment explaining the issue
+REQUEST_CHANGES  → Block the PR from merging
+```
+
+---
+
+## 🔁 One Episode — Step by Step
+
+```
+reset()
+  → Agent receives a code snippet (the PR diff)
+
+step(FLAG_BUG)
+  → Grader checks: was there actually a bug?
+  → Reward: +0.5 if correct, -0.2 if false positive
+
+step(ADD_COMMENT("This causes a null pointer on line 12"))
+  → Grader checks comment relevance
+  → Reward: +0.3 if accurate, 0.0 if vague
+
+step(REQUEST_CHANGES)
+  → Episode ends
+  → Final reward tallied
+```
+
+---
+
+## 📊 The 3 Tasks (Easy → Hard)
+
+| Task | What the agent sees | What it must do | Grader |
+|---|---|---|---|
+| **Easy** | Code with a PEP8 style issue | Flag the style issue | Deterministic — AST/linter check |
+| **Medium** | Code with a subtle logic bug | Flag the bug + comment location | Check flag + line number accuracy |
+| **Hard** | Code with a hidden security vuln (SQL injection, path traversal) | Flag security issue + explain risk | Check flag + comment quality via LLM grader |
+
+---
+
+## 🏅 Reward Design
+
+| Action | Reward |
+|---|---|
+| Correct flag on real issue | +0.5 |
+| Accurate comment/explanation | +0.3 |
+| False positive flag | -0.2 |
+| Missed critical issue | -0.4 |
+| APPROVE on buggy code | -1.0 |
+| Clean episode completion | +0.2 bonus |
+
+This gives **partial progress signals** across the whole trajectory, not just end-of-episode — which directly satisfies one of the judging criteria.
+
+---
+
+## 🔑 Why This Works Well for You
+
+- Every action is **deterministic to grade** (you're a SE, you can write the graders confidently)
+- Code snippets can be **synthetically generated** — no dataset needed
+- The hard task grader can use an **LLM call internally** to score comment quality, which is also where GraphRAG could plug in
+
+Want me to now create the **full file structure and implementation plan** you can start coding today?
+
+Okay so basically what if I take the code covert it into a graph and then feed the model and ask it review and that also will again be stored in the graph and in the end the user will have a dependency graph and a review of each module in depth and using the LLM to read the logical reasoning behind the code not just the pylint errors beging caught.
+
+That's a genuinely clever idea! Let me break down what you're describing and stress-test it against the requirements.
+
+---
+
+## 🧠 What You're Describing
+
+```
+Codebase
+    ↓
+GraphRAG parses it → Dependency Graph (nodes = modules, edges = imports/calls)
+    ↓
+Agent receives a module + its graph context as observation
+    ↓
+Agent reviews that module (flags bugs, security issues, style)
+    ↓
+Review is stored back into the graph as an annotation
+    ↓
+Final output: Annotated dependency graph with reviews on every module
+```
+
+This is actually a **multi-episode environment** where each episode = one module, and the final deliverable is a fully reviewed codebase graph.
+
+---
+
+## ✅ Why This Is Strong
+
+| Criteria | How it scores |
+|---|---|
+| Real-world utility (30%) | Extremely high — this is literally what code review tools like CodeClimate do, but agent-driven |
+| Creativity (10%) | Very novel — graph-aware code review hasn't been done in OpenEnv |
+| Environment design (20%) | Graph context as observation is well-structured and meaningful |
+| Task & grader quality (25%) | Natural difficulty progression across modules |
+
+---
+
+## 🔁 How the RL Loop Works
+
+```
+reset()
+→ Load codebase graph
+→ Pick starting module (e.g. lowest dependency = easiest)
+→ Observation = {code, graph_neighbors, import_chain}
+
+step(action)
+→ Agent flags issues, adds comments
+→ Grader scores the review
+→ Reward returned
+→ Review annotation stored on graph node
+→ Next module selected (traversal order)
+
+state()
+→ Returns current graph with all annotations so far
+
+done = True when all modules reviewed
+```
+
+---
+
+## ⚠️ One Risk to Manage
+
+The **grader for review quality** needs to be deterministic to pass the auto-validation gate. Two ways to handle this:
+
+- **Easy/Medium tasks** — use AST + linter (pylint, bandit) as ground truth. Grader checks if agent caught what the linter already knows.
+- **Hard tasks** — LLM-as-judge internally, but with a fixed seed/prompt so it's reproducible.
+
+---
+
+## 🛠️ Tech Stack
+
+| Component | Tool |
+|---|---|
+| Graph construction | NetworkX + AST parser |
+| Graph storage | NetworkX (in-memory, no DB needed) |
+| RAG layer | LightRAG or simple vector search over node embeddings |
+| Grader (easy/medium) | pylint, bandit, pyflakes |
+| Grader (hard) | LLM-as-judge with fixed prompt |
+| Observation model | Pydantic — code + graph context |
+
+---
+
+## 💡 My Honest Take
+
+This is your **best idea yet**. It's novel, it's real-world, and the graph-as-state is a genuinely interesting RL mechanic that judges from Meta/HF will notice. The risk is build time — this is more complex than a flat code review env.
+
+**Given you have ~1.5 days, want me to scope a minimal viable version of this that hits all the judging criteria without overbuilding?**
+
+Okay so a particular module might have let's say a dependency issue but that might be due to another issue. Like that module has taken a particular decision because of a requirement in another module but due to that another issue has raised but the model might report to remove that crucial decision for the project. Also a module might be needed in a lot of places how would you suggest to traverse the graph cause you need to compare all the dependencies and issues with all the modules it's not just bfs. And is gemma 4 4Eb good enough for the demo? Search online
+
+Great questions — you're thinking about this at a deep level. Let me tackle each part.Good news on Gemma 4. Now let me address all three of your questions properly.
+
+---
+
+## 1. 🧠 The Cascading Dependency Problem
+
+You're describing a real and important issue — **a decision in module A causes a problem in module B, but the agent reviewing B in isolation flags it as wrong without knowing why.**
+
+The solution is **context-aware observations**. When the agent reviews a module, its observation must include:
+
+```
+Observation = {
+  current_module: code + issues found,
+  upstream_deps: why they made decisions that affect this module,
+  downstream_deps: what modules depend on THIS module,
+  existing_reviews: annotations already written on neighbors,
+  constraint_flags: ["decision X is forced by module Y's requirement"]
+}
+```
+
+So the agent never reviews a module in isolation. It always sees the **"why" from upstream** before flagging anything. If module B has a weird pattern because module A forced it, the agent sees that constraint and should reward `ADD_COMMENT("dependency constraint from A")` over `FLAG_BUG`.
+
+This is actually what makes your environment **genuinely novel** — most code review tools don't model this.
+
+---
+
+## 2. 🗺️ Graph Traversal Strategy
+
+You're right that BFS is wrong here. Here's what I'd suggest — a **weighted priority traversal**:
+
+```
+Score each node by:
+  - Dependency centrality (how many modules import this one)
+  - Issue density (how many raw linter flags exist)
+  - Review dependency (can't review B properly until A is reviewed)
+
+Traversal order:
+  Step 1 → Leaf modules (no dependencies) — safe to review in isolation
+  Step 2 → High centrality nodes — review these with full leaf context
+  Step 3 → Complex nodes — reviewed last with full graph context available
+```
+
+Think of it like a **topological sort weighted by centrality**. NetworkX has both `topological_sort()` and `betweenness_centrality()` built in — you can combine them directly.
+
+The key insight: **a module's review is only valid once all its dependencies have been reviewed first.** That's your episode ordering logic.
+
+---
+
+## 3. 🤖 Is Gemma 4 E4B Good Enough?
+
+**Short answer: Yes for a demo, but use the 27B MoE if you can.**
+
+Here's what the search shows:
+
+- Gemma 4 E4B is designed for edge devices, prioritizing multimodal capability, low-latency processing, and on-device utility. It's capable but optimized for efficiency over raw reasoning power.
+
+- The 26B MoE model runs almost as fast as a 4B model since it only activates 4B parameters at a time — so if your HF Space can handle it, the 27B MoE gives you much stronger reasoning at nearly the same inference speed.
+
+- E4B has a 128K context window — which is actually great for your use case since you'll be feeding code + graph context into each prompt.
+
+- Gemma 4 shows significant improvements in coding benchmarks and native function-calling support for agentic workflows — which directly maps to what your agent needs to do.
+
+**My recommendation:**
+
+| Scenario | Model |
+|---|---|
+| Local testing / dev | Gemma 4 E4B — fits in 8GB RAM |
+| HF Space demo (inference.py) | Gemma 4 27B MoE — stronger reviews, still fast |
+| Fallback if quota issues | Gemma 4 E4B is acceptable for passing evaluation |
+
+The competition's inference script runs on 2 vCPU / 8GB RAM — E4B fits, 27B MoE likely won't. So **E4B is your safest bet for the submission**, but use 27B MoE via API if you're calling it remotely.
+
+---
+
+Want me to now draft the **actual file structure and core implementation skeleton** so you can start coding today?
+
+Great questions — let me search for both.Great — I have a thorough picture now. Here's the full analysis:
+
+---
+
+## 🔍 Does Your Idea Already Exist?
+
+### What CodeRabbit Does
+
+CodeRabbit uses a "Codegraph" to understand complex dependencies across files and uncover the impact of changes, pulling in 40+ linters and security scanners. Sounds similar, right? But here's the critical difference:
+
+CodeRabbit reviews are tied to diff visibility only — it can't reason about system-wide architecture, cross-repo dependencies, or historical design decisions. It can't validate whether a microservice change breaks contracts with downstream services.
+
+That's exactly the gap your environment targets. CodeRabbit handles first-pass mechanical review: style violations, security issues, common bugs. Human reviewers still need to evaluate architecture, business logic, and design decisions.
+
+### The Core Differentiation of Your Idea
+
+| Feature | CodeRabbit | Your RL Environment |
+|---|---|---|
+| Graph of codebase | ✅ Lightweight map | ✅ Full dependency graph |
+| Context-aware review | Partial (diff only) | ✅ Full upstream/downstream context |
+| Cascading dependency reasoning | ❌ | ✅ Core mechanic |
+| Reviews stored back to graph | ❌ | ✅ Annotated output |
+| RL agent learns from rewards | ❌ Static tool | ✅ Trainable agent |
+| Final deliverable to user | PR comments | Annotated dependency map |
+
+**Your environment fills a documented gap.** This is strong for the real-world utility score (30%).
+
+---
+
+## 🏗️ Architectural Questions You Still Need to Answer
+
+### 1. Graph Schema Design
+What does a node actually contain?
+```
+Node = {
+  module_id: str,
+  code: str,
+  ast_summary: dict,       # function signatures, classes
+  linter_flags: list,      # pre-computed ground truth for graders
+  dependency_reason: str,  # WHY it depends on neighbors
+  review_annotation: dict  # written by agent, starts null
+}
+```
+You need to decide this upfront — it drives everything else.
+
+---
+
+### 2. Observation Construction Strategy
+How much graph context do you inject per step? Too little = agent reviews blindly. Too much = exceeds context window.
+
+**Recommended approach — tiered context:**
+```
+Easy task   → current module only
+Medium task → current module + direct neighbors
+Hard task   → current module + 2-hop neighborhood + existing reviews
+```
+This naturally creates difficulty progression and respects the 128K context window of Gemma 4 E4B.
+
+---
+
+### 3. Episode Boundary Design
+When does an episode end? Two valid designs:
+
+- **Per-module episodes** — one episode = one module reviewed. Fast, easy to grade.
+- **Full-codebase episodes** — one episode = entire codebase reviewed in traversal order. More realistic, harder to grade.
+
+For the submission I'd recommend **per-module with a meta-episode wrapper** — each module is an episode, but the graph state persists across them so reviews accumulate.
+
+---
+
+### 4. Reward Attribution Problem
+If the agent correctly identifies a cascading issue (bug in B caused by A), who gets the reward — the step that flagged it, or the final episode? You need a clear policy:
+
+```
+Reward policy:
+  +0.6 if agent flags issue AND correctly attributes it to upstream module
+  +0.3 if agent flags issue but misattributes cause
+  -0.3 if agent flags false positive ignoring upstream context
+```
+
+---
+
+### 5. Graph Generation Strategy
+Where does the test codebase come from? Three options:
+
+| Option | Pro | Con |
+|---|---|---|
+| Parse a real OSS repo (e.g. Flask, FastAPI) | Realistic | Complex to control |
+| Synthetically generate modules | Fully deterministic graders | Less realistic |
+| Hybrid — real structure, injected bugs | Best of both | Medium effort |
+
+**Hybrid is the right call** — use a real repo's structure but inject known bugs so graders can be 100% deterministic.
+
+---
+
+### 6. Grader Architecture (Critical for Pass/Fail Gate)
+
+```
+Easy grader   → pylint/bandit pre-run, check if agent flagged same issues ✅ fully deterministic
+Medium grader → AST diff between agent's suggested fix and ground truth ✅ deterministic  
+Hard grader   → LLM-as-judge with fixed seed + rubric for cascading reasoning ⚠️ quasi-deterministic
+```
+
+The hard grader is your biggest risk. Fix the judge prompt, temperature=0, and document it clearly in README.
+
+---
+
+### 7. State Persistence Across Episodes
+The graph with accumulated annotations IS your `state()`. You need to define:
+- What gets serialized (NetworkX graph → JSON)
+- How `reset()` clears annotations but keeps graph structure
+- Whether partial reviews survive between episodes (they should)
+
+---
+
+## ✅ Summary: What Makes You Novel vs CodeRabbit
+
+The key architectural insight is that an AI seeing only one file without context on its neighbors leads to false positives — it worries about things that are actually handled upstream. Your environment is the first RL training ground that explicitly teaches agents to reason about this. That's your pitch to the judges.
+
+---
+
+Full up and full down will be too heavy for the model to look at in complex projects right having thousands of lines of code
+
+Exactly right. You've identified the most critical architectural bottleneck. Here's how to solve it:
+
+---
+
+## 🧠 The Core Problem
+
+A real project could have:
+- Module A → 500 lines
+- 10 direct dependencies → each 300 lines
+- 2-hop neighbors → another 20 modules
+
+That's **thousands of tokens just for context**, before the agent even starts reviewing. Gemma 4 E4B's 128K window sounds big but fills fast.
+
+---
+
+## ✅ Solution: Compressed Graph Context (Not Raw Code)
+
+**Never feed raw code as context. Feed summaries.**
+
+```
+Instead of:
+  "Here is module_auth.py [500 lines of code]..."
+
+Feed:
+  "module_auth.py → exposes: validate_token(str) → User | None
+   Known issues: may return None on expired token
+   Depended on by: checkout.py, cart.py
+   Review status: flagged null return risk"
+```
+
+This is your **Graph Summary Layer** — sitting between the raw graph and the agent's observation.
+
+---
+
+## 🏗️ The 3-Layer Observation Architecture
+
+```
+Layer 1: AST Compression
+  Raw code → extract only signatures, return types, 
+  decorators, class names
+  Tool: Python's ast module
+  Output: ~50 tokens per module (vs 500+ raw)
+
+Layer 2: Graph Summary Node
+  Per node store:
+  {
+    exports: ["validate_token(str) → User | None"],
+    known_issues: ["may return None"],
+    constraint_flags: ["forced by requirement in auth_service.py"],
+    review_status: "pending | reviewed | flagged",
+    review_summary: "one line of what was found"  ← written by agent
+  }
+
+Layer 3: Agent Observation (what model actually sees)
+  {
+    current_module: full code,        ← only this is full
+    direct_deps: [graph summaries],   ← compressed
+    dependents: [graph summaries],    ← compressed
+    relevant_reviews: [one-liners]    ← already written
+  }
+```
+
+So the agent always sees **one module in full**, and everything else as compressed summaries.
+
+---
+
+## 📐 Token Budget Estimate
+
+| Component | Tokens |
+|---|---|
+| Current module (full code) | ~800 |
+| 5 dependency summaries × 50 tokens | ~250 |
+| 5 dependent summaries × 50 tokens | ~250 |
+| Existing review annotations | ~200 |
+| System prompt + action space | ~300 |
+| **Total per step** | **~1,800** |
+
+That's well within E4B's window, even for complex projects.
+
+---
+
+## 🎯 Bonus: This Becomes a Feature, Not a Workaround
+
+The **summary layer is actually what makes your environment novel**. You're teaching the agent to:
+
+1. Read compressed dependency context
+2. Decide if a deeper look is needed
+3. Optionally request full code of a neighbor via a `REQUEST_CONTEXT(module_id)` action
+
+That `REQUEST_CONTEXT` action costs a small reward penalty (simulating real reviewer time cost), which is **genuinely interesting RL reward shaping** that judges will notice.
+
+---
+
+## The Revised Action Space
+
+```
+APPROVE
+FLAG_STYLE
+FLAG_BUG  
+FLAG_SECURITY
+FLAG_DEPENDENCY_ISSUE   ← new: cascading problem from neighbor
+ADD_COMMENT(txt)
+REQUEST_CHANGES
+REQUEST_CONTEXT(module)  ← new: pay token cost, get full neighbor code
+```
+
+This elegantly solves your original cascading dependency problem too — the agent can *choose* to investigate upstream before judging.
+
+Want me to now write the full file structure and implementation skeleton?
+
+Great — these are the four hardest design questions in the project. Let me work through each one carefully.
+
+---
+
+## 1. 🔪 Converting Code Into Modules Accurately
+
+The challenge is — what IS a module? You need a deterministic answer.
+
+**Recommended: File = Module, with AST sub-structure**
+
+```
+Step 1: File-level split
+  Each .py file = one node in the graph
+  filename → module_id
+
+Step 2: AST parsing per file
+  Extract:
+  - All function signatures + return types
+  - All class definitions
+  - All imports (this gives you edges)
+  - All global variables
+
+Step 3: Edge construction from imports
+  "from auth import validate_token"
+  → edge: current_module → auth.py
+
+Step 4: Dependency reason tagging
+  Use the import line + first usage context
+  as the "why this depends on that" annotation
+```
+
+**The hard problem: implicit dependencies**
+Sometimes module B doesn't import A directly but uses a shared global or config. Handle this with a second pass:
+
+```
+Pass 1: Explicit edges (imports)
+Pass 2: Name resolution edges
+  - scan function bodies for names not defined locally
+  - trace them back to source module
+  - add a "implicit dependency" edge with lower weight
+```
+
+Python's `ast` module handles all of this natively. No external library needed.
+
+---
+
+## 2. 📊 How Reporting Works
+
+Think of reporting as **three layers that build progressively**:
+
+```
+Layer 1: Per-step annotation (live)
+  Every time agent calls ADD_COMMENT or FLAG_*,
+  that gets written immediately to the graph node
+  as a review_annotation field
+
+Layer 2: Per-module summary (end of episode)
+  When episode ends (agent calls APPROVE or REQUEST_CHANGES),
+  environment compiles all step annotations into:
+  {
+    verdict: "approved | changes_requested",
+    issues: [...],
+    dependency_notes: [...],
+    confidence: 0.0-1.0  ← derived from reward trajectory
+  }
+
+Layer 3: Full codebase report (end of all episodes)
+  state() returns the entire annotated graph
+  Serialize to:
+  - JSON (machine readable)
+  - Markdown report (human readable)
+  - Visual graph (NetworkX → graphviz or mermaid)
+```
+
+**Updating reviews as agent learns more** is the elegant part. Because reviews are stored on graph nodes, when the agent later reviews module B and discovers the root cause was actually in module A, it can call:
+
+```
+AMEND_REVIEW(module_id="auth.py", note="root cause of checkout.py null issue")
+```
+
+This updates the node annotation retroactively. The reward for this action is high — it's exactly the cascading reasoning you want to incentivize.
+
+---
+
+## 3. ✅ Does This Align With Round 1 Requirements?
+
+Let's go requirement by requirement:
+
+| Requirement | Your Design | Status |
+|---|---|---|
+| Real-world task | Code review with dependency reasoning | ✅ Strong |
+| step() / reset() / state() | Per-module episodes, graph persists in state() | ✅ |
+| Typed Pydantic models | Observation = code + summaries, Action = flag/comment/request, Reward = float | ✅ |
+| Minimum 3 tasks easy→hard | Easy: style/linter, Medium: logic bug with direct dep context, Hard: cascading bug across 2+ modules | ✅ |
+| Reward 0.0–1.0 with partial signal | Per-step rewards for each correct flag/comment/attribution | ✅ |
+| Deterministic graders | Easy/medium use AST+linter ground truth, hard uses fixed-seed LLM judge | ✅ with care |
+| Baseline inference script | Agent reviews all 3 task codebases, emits [START]/[STEP]/[END] logs | ✅ |
+| Dockerfile + HF Space | Standard containerization | ✅ |
+| openenv.yaml + validate | Standard spec compliance | ✅ |
+
+One gap to watch: **the hard task grader quasi-determinism**. Document your judge prompt and temperature=0 explicitly in README to satisfy the reproducibility requirement.
+
+---
+
+## 4. 🤖 Where Is The RL? Where Is OpenEnv?
+
+This is the most important question to be clear on — because judges WILL ask.
+
+### The RL Loop
+
+```
+Environment (your code)          Agent (Gemma 4 / any LLM)
+─────────────────────────        ──────────────────────────
+reset()                    →     receives initial observation
+                                 (module code + graph context)
+
+                           ←     action: FLAG_BUG
+
+step(FLAG_BUG)             →     returns:
+                                 - new observation (updated graph)
+                                 - reward (+0.5 if real bug)
+                                 - done (False)
+                                 - info {}
+
+                           ←     action: ADD_COMMENT("null risk line 12")
+
+step(ADD_COMMENT(...))     →     reward (+0.3 if accurate)
+
+                           ←     action: REQUEST_CHANGES
+
+step(REQUEST_CHANGES)      →     reward (+0.2 episode bonus)
+                                 done = True
+
+state()                    →     full annotated graph so far
+```
+
+The **RL part** is: the agent is learning a *policy* — which actions to take given a code observation and graph context — to maximize cumulative reward. It's not just calling an LLM once. It's a multi-step decision loop.
+
+### Where OpenEnv Fits
+
+```
+openenv.yaml
+  name: code-review-env
+  version: 1.0.0
+  tasks: [style_review, logic_review, cascading_review]
+
+environment.py
+  class CodeReviewEnv:
+    observation: CodeObservation    ← Pydantic model
+    action: ReviewAction            ← Pydantic model  
+    reward: ReviewReward            ← Pydantic model
+
+    def reset() → CodeObservation
+    def step(action) → (obs, reward, done, info)
+    def state() → GraphState
+
+graders/
+  easy_grader.py    ← linter diff check
+  medium_grader.py  ← AST + line attribution check
+  hard_grader.py    ← LLM judge, fixed seed
+
+inference.py        ← runs Gemma 4 as the agent
+  [START] task=cascading_review
+  [STEP]  action=FLAG_DEPENDENCY_ISSUE reward=0.5
+  [STEP]  action=ADD_COMMENT reward=0.3
+  [END]   total_reward=0.8
+```
+
+OpenEnv is the **standardized wrapper** that makes your environment pluggable — any agent, any model, can be dropped in and evaluated against your graders. That's the whole point of the spec.
+
+---
+
+## The One-Line Pitch to Judges
+
+> *"An RL environment where an agent learns to review code with full dependency awareness — outputting an annotated codebase graph, not just PR comments. It teaches agents to reason about WHY a bug exists, not just WHERE."*
+
+That's differentiated from CodeRabbit, aligned with all Round 1 requirements, and has a clear RL loop.
+
+**Ready to build the file skeleton now?**
+
+
+What I basically want is there should be RL in this project meaning it will first see and find out issues about the code and then there should be a review of the bug reported and if the bug is correctly reported there should be reward or else punishment and based on that the actual model should learn and understand this should be integrated into it.
+
+Also right now we have an issue where all the modules are not linked properly. And it's not just about imports but also where they are being called or run and this linking is not proper and causes isolated modules. And also for large modules it's broken into many things. Also Right now I suspect that the LLM is not grading properly the code it's just passing through it and just repeating the errors from the previous the hard filter should also catch errors and find issues and give detailed reports on all in clear tasks. Give it a super detailed agent prompt for this task and the format for output also ensuring it is adaptable. And after the errors being found it should then again verify those errors with another model which the user can define and then it will learn from it and become RL. Assign proper grades for the machine learning to be good for this particular task. Also the arrow marks in the graph are too thick sometimes and when I hover over them they give me a big like of text rather than a well formatted overlay where it gives me info about the modules and also when I click on the module it should show in the side bar the report for it well formatted