Merge branch 'fix/scoring-mismatch'

.env.example

@@ -8,7 +8,7 @@
 # Primary model and base URL
 # Default is https://router.huggingface.co/v1
 API_BASE_URL=https://router.huggingface.co/v1
-MODEL_NAME=gpt-4o-mini
+MODEL_NAME=gpt-4.1-mini
 
 # Your Hugging Face Token (used by inference.py and run_baseline.py)
 HF_TOKEN=hf_your_token_here
@@ -27,5 +27,5 @@ ENV_BASE_URL=http://localhost:8000
 # (Optional) Local Baseline Run Settings
 # ---------------------------------------------------------------------------
 baseline_provider=openai
-baseline_model=gpt-4o-mini
+baseline_model=gpt-4.1-mini
 baseline_temp=0.1

README.md

@@ -86,7 +86,7 @@ Use the `run_baseline.py` script for local testing and developer iteration.
 uv run python run_baseline.py --mode local
 
 # Run LLM-based baseline (requires OpenAI-compatible API)
-uv run python run_baseline.py --mode llm --model gpt-4o-mini
+uv run python run_baseline.py --mode llm --model gpt-4.1-mini
 ```
 
 ---
@@ -106,7 +106,7 @@ This environment adheres to the OpenEnv standard. You can interact with it via t
 The `inference.py` script outputs the following standardized format for automated validation:
 
 ```text
-[START] task=easy env=revlogixenv_v0 model=gpt-4o-mini
+[START] task=easy env=revlogixenv_v0 model=gpt-4.1-mini
 [STEP] step=1 action=inspect reward=0.43 done=false error=null
 ...
 [END] success=true steps=20 score=0.717 rewards=0.43,0.50,...
@@ -117,6 +117,42 @@ The `inference.py` script outputs the following standardized format for automate
 
 ---
 
+## Task Configurations
+
+The environment supports three difficulty tiers plus legacy compatibility aliases:
+
+| Task | Items | Fraud | Noise | Delay | Scoring |
+|------|-------|-------|-------|-------|---------|
+| `easy` | 20 | No | Medium | Fixed (3 steps) | Oracle-margin |
+| `medium` | 30 | Yes | Hard | Variable | Oracle-margin |
+| `hard` | 40 | Yes | Extra-hard | Variable | 0.6×margin + 0.4×fraud-F1 |
+| `_legacy_easy` | 10 | No | Easy | Immediate | Oracle-margin |
+
+The `_legacy_easy` task is preserved for backward compatibility with early experiments.
+Internal environment code may also reference `_old_easy`, `_old_medium`, and `_old_hard`
+keys — these are functionally identical to `easy`, `medium`, and `hard` respectively.
+
+## Scoring Contexts
+
+RevLogiXenv has **two independent scoring modes** that target different use cases:
+
+1. **Inference mode** (hackathon Phase 2): `score = mean(step_rewards)`, each reward clamped to `(0.01, 0.99)`. This is what `inference.py` emits and what the hackathon validator parses.
+
+2. **Grader mode** (local Python evaluation): Oracle-normalized margin score, with a fraud-F1 composite for `hard` tasks. Computed by the `Grader` class. This is used for local policy comparison and benchmarking.
+
+Both modes enforce the same `(0.01, 0.99)` bounded range. The `openenv.yaml` manifest declares the inference-mode formula.
+
+## Observation Fields
+
+The `ReturnsObservation.reward_detail` field exposes a structured `Reward` payload with detailed economics:
+
+- `value`: The shaped reward (clamped, used by inference)
+- `raw_step_reward`: Unclamped raw economics in dollars
+- `margin_component`: Shaped margin signal (0.01–0.99)
+- `fraud_component`: Shaped fraud signal (0.01–0.99)
+- `components`: Dict of line-item economics (`processing`, `revenue`, `fraud_recovery`, etc.)
+- `penalties`: Dict of applied penalties and their strength
+
 ## Documentation
 
 - [Technical Details](RevLogiXenv_v0/README.md): Deep dive into environment dynamics and models.

RevLogiXenv_v0/baseline.py

@@ -18,49 +18,11 @@ from typing import Iterable
 from .environment import AutonomousReturnsEnv
 from .grader import Grader
 from .models import DispositionAction, ReturnsAction, ReturnsObservation
-
-ACTION_STRINGS = [a.value for a in DispositionAction]
-
-LLM_SYSTEM_PROMPT = """You are a reverse-logistics triage agent for AutonomousReturns-v0.
-
-NOISE MODEL (CRITICAL):
-- Items have HIDDEN TRUE CONDITION: perfect, lightly_used, damaged, fraudulent
-- You observe NOISY condition scores (0-10), NOT ground truth
-- Fraudulent items score HIGH (mean=7.8, std=0.70) to mimic quality items
-- Perfect items score highest (mean=8.9), damaged score lowest (mean=3.0)
-- High score + fraud history = SUSPICIOUS (may be fraudulent mimicking quality)
-- High score + clean history = likely good
-
-CUSTOMER PROFILE INTERPRETATION:
-- RETURNS: number of previous returns (0-4+)
-- HIST_FRAUD_FLAGS: past fraud indicators (0 = clean, 2+ = high risk)
-- RECENT_ABUSE: True if customer shows abuse patterns
-
-FRAUD INDICATORS (strongest to weakest):
-1. 'wrong item' or 'missing parts' in return reason
-2. high HIST_FRAUD_FLAGS (>0)
-3. RECENT_ABUSE = True
-4. 'mismatch'/'suspect'/'serial' in inspection note
-5. 'missing' packaging
-
-DISPOSITION VALUE GUIDE:
-- RESELL_FULL: Best for PERFECT ($0.98x). Bad for damaged ($0.22x) or fraud ($0.10x)
-- RESELL_DISCOUNT_15: Good for LIGHTLY_USED ($0.82x). Avoid on fraud ($0.22x)
-- RESELL_DISCOUNT_30: General lightly-used fallback
-- RESELL_DISCOUNT_50: Damaged items, low-value situations
-- REFURBISH: High-price damaged items only ($18 fixed + 15% variable)
-- DISPOSE: Low-price (<$90) damaged items
-- FLAG_FRAUD: Only with 3+ fraud signals. Costs $6+$0.03x. Recovers $0.88x if correct
-- INSPECT: Uncertain expensive items ($250+). Reduces noise 14x but costs $5
-
-RULES:
-- score > 8.0 AND no fraud history → likely PERFECT → RESELL_FULL or RESELL_DISCOUNT_15
-- score 5.0-7.5 AND fraud signals → INSPECT before deciding
-- score < 4.0 → likely damaged → REFURBISH (high$) or DISPOSE (low$)
-- NEVER flag fraud with < 3 signals (causes expensive false positives)
-
-Choose EXACTLY ONE action: RESELL_FULL, RESELL_DISCOUNT_15, RESELL_DISCOUNT_30, RESELL_DISCOUNT_50, REFURBISH, DISPOSE, FLAG_FRAUD, INSPECT, WAIT
-Return ONLY the action name. No explanation. No punctuation."""
+from .prompting import (
+    FULL_SYSTEM_PROMPT as LLM_SYSTEM_PROMPT,
+    observation_to_prompt_baseline as observation_to_prompt,
+    parse_action_baseline as parse_action,
+)
 
 
 @dataclass(frozen=True)
@@ -94,7 +56,7 @@ class BaselineAgent:
         base_url = os.environ.get("API_BASE_URL") or os.environ.get("OPENAI_API_BASE_URL")
         self.client = OpenAI(api_key=api_key, base_url=base_url)
         if not self.model:
-            self.model = os.environ.get("MODEL_NAME", "gpt-4o-mini")
+            self.model = os.environ.get("MODEL_NAME", "gpt-4.1-mini")
 
     def _call_llm(self, prompt: str) -> str:
         response = self.client.chat.completions.create(
@@ -110,63 +72,12 @@ class BaselineAgent:
         return text.strip()
 
     def observation_to_prompt(self, obs: ReturnsObservation) -> str:
-        if obs.current_item is None:
-            return (
-                "No current item is available. "
-                f"Pending resolutions: {obs.pending_resolution_count}. "
-                "Output exactly one action token: wait"
-            )
-
-        item = obs.current_item
-        lines: list[str] = [
-            f"Product: {item.product_title}",
-            f"Category: {item.category}",
-            f"Price: {item.price:.2f}",
-            f"Noisy condition score: {item.noisy_condition_score:.2f}/10",
-            f"Return reason: {item.stated_return_reason}",
-            f"Customer profile: RETURNS={item.customer_profile.total_returns}, "
-            f"HIST_FRAUD_FLAGS={item.customer_profile.historical_fraud_flags}, "
-            f"RECENT_ABUSE={item.customer_profile.recent_abuse_signals}",
-            f"Packaging: {item.packaging_condition}",
-        ]
-        if item.damage_flags:
-            lines.append(f"Damage flags: {', '.join(item.damage_flags)}")
-        if item.inspection_note:
-            lines.append(f"Inspection note: {item.inspection_note}")
-
-        lines.append(f"Remaining items: {obs.remaining_items}")
-        lines.append(f"Pending resolutions: {obs.pending_resolution_count}")
-        lines.append(f"Running ledger: {obs.running_ledger:.4f}")
-
-        if obs.last_three_resolutions:
-            lines.append("Recent outcomes:")
-            for r in obs.last_three_resolutions:
-                lines.append(
-                    f"- action={r.action.value} normalized_reward={r.normalized_reward:.4f}"
-                )
-
-        lines.append("")
-        lines.append("Choose one action token exactly from:")
-        lines.append(", ".join(ACTION_STRINGS))
-        return "\n".join(lines)
+        return observation_to_prompt(obs)
 
     def parse_action(
         self, response_text: str, obs: ReturnsObservation
     ) -> ReturnsAction:
-        text = (response_text or "").strip().lower()
-
-        if obs.current_item is None:
-            return ReturnsAction(action=DispositionAction.WAIT)
-
-        for act in DispositionAction:
-            if act.value == text:
-                return ReturnsAction(action=act)
-
-        for act in DispositionAction:
-            if act.value in text:
-                return ReturnsAction(action=act)
-
-        return ReturnsAction(action=DispositionAction.RESELL_DISCOUNT_30)
+        return parse_action(response_text, obs)
 
     def act(self, obs: ReturnsObservation) -> ReturnsAction:
         if obs.current_item is None:
@@ -251,7 +162,7 @@ class BaselineAgent:
 
 
 def run_openai_baseline(
-    model: str = "gpt-4o-mini",
+    model: str = "gpt-4.1-mini",
     seeds: Iterable[int] = (42,),
     verbose: bool = False,
 ) -> dict:

RevLogiXenv_v0/environment.py

@@ -166,6 +166,12 @@ TASK_CONFIG = {
         "noise_level": "extra_hard",
         "delay_type": "variable",
     },
+    "_legacy_easy": {
+        "num_items": 10,
+        "fraud_enabled": False,
+        "noise_level": "easy",
+        "delay_type": "immediate",
+    },
     "_old_easy": {
         "num_items": 20,
         "fraud_enabled": False,
@@ -417,6 +423,26 @@ class AutonomousReturnsEnv(Environment[ReturnsAction, ReturnsObservation, EnvSta
     def close(self) -> None:
         return None
 
+    @property
+    def episode_snapshot(self) -> list[EpisodeRecord]:
+        """
+        Read-only snapshot of ground-truth episode data captured at reset time.
+
+        This is used by the Grader and Oracle to evaluate agent performance
+        without relying on private-name access (_episode_snapshot).
+        """
+        return self._episode_snapshot
+
+    @property
+    def full_resolution_history(self) -> list[ResolutionSummary]:
+        """
+        Read-only list of all resolved item summaries across the full episode.
+
+        Unlike ``resolution_history`` which is capped at the last 3 for display,
+        this contains every resolved item and is used by the Grader for fraud metrics.
+        """
+        return self._full_resolution_history
+
     def _set_task(self, task: str) -> None:
         if not isinstance(task, str):
             raise TypeError("Task override must be a string.")

RevLogiXenv_v0/grader.py

@@ -33,10 +33,17 @@ class Grader:
     Final scores are strictly clamped to the (0.01, 0.99) range to comply
     with hackathon validation requirements.
 
-    Scoring:
-    - easy:  final_score = margin_score
+    Scoring (Grader mode — used by Python API):
+    - easy:  final_score = margin_score  (oracle-normalized profit)
     - medium: final_score = margin_score
-    - hard: final_score = 0.6 * margin_score + 0.4 * fraud_f1
+    - hard:  final_score = 0.6 * margin_score + 0.4 * fraud_f1
+
+    Note: There are TWO independent scoring contexts in RevLogiXenv:
+    1. Inference mode (hackathon Phase 2): score = mean(step_rewards), clamped to (0.01, 0.99).
+       This is what inference.py outputs and is parsed by the hackathon validator.
+    2. Grader mode (local Python evaluation): oracle-margin + fraud-F1 composite, above.
+       This is what the Grader class computes and is used for local policy comparison.
+    The openenv.yaml manifest declares the inference-mode formula (mean step rewards).
     """
     MIN_SCORE = 0.01
     MAX_SCORE = 0.99
@@ -92,12 +99,24 @@ class Grader:
             raise RuntimeError(
                 "Cannot score an incomplete episode. Roll out until observation.done == True."
             )
-        if not getattr(self.env, "_episode_snapshot", None):
+        if not self.env.episode_snapshot:
             raise RuntimeError(
                 "Cannot score episode before reset. Call env.reset(...) and run at least one rollout."
             )
 
     def _compute_scores(self) -> dict:
+        """
+        Compute bounded scores for the current episode.
+
+        Returns a dict with two scoring annotations:
+        - _scoring_mode: always "grader" for this method
+        - _score_formula: human-readable formula string
+
+        The actual final_score value is computed in "grader mode"
+        (oracle-normalized margin, with fraud-F1 composite for hard tasks).
+        This differs from the inference-mode score (mean of clamped step
+        rewards) declared in openenv.yaml and emitted by inference.py.
+        """
         if self.oracle is None:
             raise RuntimeError("Oracle not initialized. Call grade() first.")
 
@@ -128,6 +147,14 @@ class Grader:
                 "f1": fraud.f1,
             },
             "final_score": final_score,
+            # Explicit scoring mode marker so consumers know which formula applies.
+            # Grader mode: oracle-normalized margin + optional fraud F1 composite.
+            "_scoring_mode": "grader",
+            "_score_formula": (
+                "0.6 * margin_score + 0.4 * fraud_f1"
+                if self.task == "hard"
+                else "margin_score"
+            ),
         }
 
     def _compute_fraud_metrics(self) -> FraudMetrics:
@@ -144,10 +171,10 @@ class Grader:
 
         snapshot_by_item = {
             int(record.item_id): record.hidden_condition
-            for record in getattr(self.env, "_episode_snapshot", [])
+            for record in self.env.episode_snapshot
         }
 
-        for resolution in self.env._full_resolution_history:
+        for resolution in self.env.full_resolution_history:
             hidden = snapshot_by_item.get(int(resolution.item_id))
             is_fraud = hidden == Condition.FRAUDULENT
             flagged = resolution.action == DispositionAction.FLAG_FRAUD

RevLogiXenv_v0/oracle.py

@@ -34,7 +34,7 @@ class Oracle:
         self._precompute()
 
     def _build_snapshot(self) -> list[OracleRecord]:
-        raw = getattr(self._env, "_episode_snapshot", None)
+        raw = self._env.episode_snapshot
         if not raw:
             raise ValueError(
                 "Environment snapshot is empty. Reset the environment before creating Oracle."

RevLogiXenv_v0/prompting.py

@@ -0,0 +1,217 @@
+"""
+Shared LLM prompting utilities for RevLogiXenv.
+
+Provides unified prompt construction and action parsing for both the
+hackathon inference entrypoint (inference.py) and the baseline agent
+(baseline.py).
+
+Two system prompts are exported to allow callers to choose the level of
+detail:
+- MINIMAL_SYSTEM_PROMPT: concise, single-sentence instruction (inference.py style)
+- FULL_SYSTEM_PROMPT: detailed domain briefing with noise model and rules (baseline.py style)
+"""
+
+from __future__ import annotations
+
+import re
+
+from .models import DispositionAction, ReturnsAction, ReturnsObservation
+
+# Minimal prompt — used by inference.py for hackathon Phase 2 validation.
+MINIMAL_SYSTEM_PROMPT = (
+    "You are a reverse-logistics triage agent. Output EXACTLY ONE WORD from this list: "
+    "RESELL_FULL, RESELL_DISCOUNT_15, RESELL_DISCOUNT_30, RESELL_DISCOUNT_50, REFURBISH, "
+    "DISPOSE, FLAG_FRAUD, INSPECT, WAIT. No explanation. No punctuation. Just the single word."
+)
+
+# Full prompt — used by baseline.py for richer LLM reasoning.
+FULL_SYSTEM_PROMPT = """You are a reverse-logistics triage agent for AutonomousReturns-v0.
+
+NOISE MODEL (CRITICAL):
+- Items have HIDDEN TRUE CONDITION: perfect, lightly_used, damaged, fraudulent
+- You observe NOISY condition scores (0-10), NOT ground truth
+- Fraudulent items score HIGH (mean=7.8, std=0.70) to mimic quality items
+- Perfect items score highest (mean=8.9), damaged score lowest (mean=3.0)
+- High score + fraud history = SUSPICIOUS (may be fraudulent mimicking quality)
+- High score + clean history = likely good
+
+CUSTOMER PROFILE INTERPRETATION:
+- RETURNS: number of previous returns (0-4+)
+- HIST_FRAUD_FLAGS: past fraud indicators (0 = clean, 2+ = high risk)
+- RECENT_ABUSE: True if customer shows abuse patterns
+
+FRAUD INDICATORS (strongest to weakest):
+1. 'wrong item' or 'missing parts' in return reason
+2. high HIST_FRAUD_FLAGS (>0)
+3. RECENT_ABUSE = True
+4. 'mismatch'/'suspect'/'serial' in inspection note
+5. 'missing' packaging
+
+DISPOSITION VALUE GUIDE:
+- RESELL_FULL: Best for PERFECT ($0.98x). Bad for damaged ($0.22x) or fraud ($0.10x)
+- RESELL_DISCOUNT_15: Good for LIGHTLY_USED ($0.82x). Avoid on fraud ($0.22x)
+- RESELL_DISCOUNT_30: General lightly-used fallback
+- RESELL_DISCOUNT_50: Damaged items, low-value situations
+- REFURBISH: High-price damaged items only ($18 fixed + 15% variable)
+- DISPOSE: Low-price (<$90) damaged items
+- FLAG_FRAUD: Only with 3+ fraud signals. Costs $6+$0.03x. Recovers $0.88x if correct
+- INSPECT: Uncertain expensive items ($250+). Reduces noise 14x but costs $5
+
+RULES:
+- score > 8.0 AND no fraud history → likely PERFECT → RESELL_FULL or RESELL_DISCOUNT_15
+- score 5.0-7.5 AND fraud signals → INSPECT before deciding
+- score < 4.0 → likely damaged → REFURBISH (high$) or DISPOSE (low$)
+- NEVER flag fraud with < 3 signals (causes expensive false positives)
+
+Choose EXACTLY ONE action: RESELL_FULL, RESELL_DISCOUNT_15, RESELL_DISCOUNT_30, RESELL_DISCOUNT_50, REFURBISH, DISPOSE, FLAG_FRAUD, INSPECT, WAIT
+Return ONLY the action name. No explanation. No punctuation."""
+
+
+def observation_to_prompt_inference(obs: ReturnsObservation) -> str:
+    """
+    Build a concise LLM prompt from an observation.
+    Used by inference.py for hackathon Phase 2 validation.
+    """
+    if obs.current_item is None:
+        return "No items left. Output exactly: wait"
+
+    item = obs.current_item
+    lines: list[str] = [
+        f"Product: {item.product_title}",
+        f"Price: ${item.price:.2f}",
+        f"Score: {item.noisy_condition_score:.1f}/10",
+        f"Reason: {item.stated_return_reason}",
+        f"Returns: {item.customer_profile.total_returns}",
+        f"Fraud flags: {item.customer_profile.historical_fraud_flags}",
+        f"Abuse: {item.customer_profile.recent_abuse_signals}",
+        f"Packaging: {item.packaging_condition}",
+    ]
+    if item.damage_flags:
+        lines.append(f"Damage: {', '.join(item.damage_flags)}")
+    if item.inspection_note:
+        lines.append(f"Note: {item.inspection_note}")
+
+    lines.append(f"Remaining: {obs.remaining_items}, Pending: {obs.pending_resolution_count}")
+    lines.append(f"Ledger: ${obs.running_ledger:.2f}")
+    if obs.last_three_resolutions:
+        lines.append("Recent:")
+        for resolution in obs.last_three_resolutions:
+            lines.append(f"{resolution.action.value}={resolution.normalized_reward:.2f}")
+    lines.append("")
+    lines.append(
+        "Output ONE word: RESELL_FULL, RESELL_DISCOUNT_15, RESELL_DISCOUNT_30, "
+        "RESELL_DISCOUNT_50, REFURBISH, DISPOSE, FLAG_FRAUD, INSPECT, or WAIT"
+    )
+    return "\n".join(lines)
+
+
+def observation_to_prompt_baseline(obs: ReturnsObservation) -> str:
+    """
+    Build a detailed LLM prompt from an observation.
+    Used by baseline.py for richer LLM reasoning.
+    """
+    if obs.current_item is None:
+        return (
+            "No current item is available. "
+            f"Pending resolutions: {obs.pending_resolution_count}. "
+            "Output exactly one action token: wait"
+        )
+
+    item = obs.current_item
+    lines: list[str] = [
+        f"Product: {item.product_title}",
+        f"Category: {item.category}",
+        f"Price: {item.price:.2f}",
+        f"Noisy condition score: {item.noisy_condition_score:.2f}/10",
+        f"Return reason: {item.stated_return_reason}",
+        f"Customer profile: RETURNS={item.customer_profile.total_returns}, "
+        f"HIST_FRAUD_FLAGS={item.customer_profile.historical_fraud_flags}, "
+        f"RECENT_ABUSE={item.customer_profile.recent_abuse_signals}",
+        f"Packaging: {item.packaging_condition}",
+    ]
+    if item.damage_flags:
+        lines.append(f"Damage flags: {', '.join(item.damage_flags)}")
+    if item.inspection_note:
+        lines.append(f"Inspection note: {item.inspection_note}")
+
+    lines.append(f"Remaining items: {obs.remaining_items}")
+    lines.append(f"Pending resolutions: {obs.pending_resolution_count}")
+    lines.append(f"Running ledger: {obs.running_ledger:.4f}")
+
+    if obs.last_three_resolutions:
+        lines.append("Recent outcomes:")
+        for r in obs.last_three_resolutions:
+            lines.append(
+                f"- action={r.action.value} normalized_reward={r.normalized_reward:.4f}"
+            )
+
+    lines.append("")
+    lines.append("Choose one action token exactly from:")
+    action_strings = [a.value for a in DispositionAction]
+    lines.append(", ".join(action_strings))
+    return "\n".join(lines)
+
+
+def parse_action_inference(response_text: str, obs: ReturnsObservation) -> ReturnsAction:
+    """
+    Parse an LLM response into a ReturnsAction using regex.
+    Searches all lines and returns the last match found.
+    Falls back to WAIT if no match.
+    Used by inference.py.
+    """
+    if obs.current_item is None:
+        return ReturnsAction(action=DispositionAction.WAIT)
+
+    text = (response_text or "").lower().strip()
+    actions = [
+        "resell_full",
+        "resell_discount_15",
+        "resell_discount_30",
+        "resell_discount_50",
+        "refurbish",
+        "dispose",
+        "flag_fraud",
+        "inspect",
+        "wait",
+    ]
+    pattern = r"\b(" + "|".join(sorted(actions, key=len, reverse=True)) + r")\b"
+
+    lines = [line.strip() for line in text.split("\n") if line.strip()]
+    for line in reversed(lines):
+        line_match = re.fullmatch(pattern, line)
+        if line_match:
+            matched = line_match.group(1)
+            for action in DispositionAction:
+                if action.value == matched:
+                    return ReturnsAction(action=action)
+
+    matches = re.findall(pattern, text)
+    if matches:
+        matched = matches[-1]
+        for action in DispositionAction:
+            if action.value == matched:
+                return ReturnsAction(action=action)
+
+    return ReturnsAction(action=DispositionAction.WAIT)
+
+
+def parse_action_baseline(response_text: str, obs: ReturnsObservation) -> ReturnsAction:
+    """
+    Parse an LLM response into a ReturnsAction using exact + substring matching.
+    Tries exact match first, then substring match, then falls back to default.
+    Used by baseline.py.
+    """
+    text = (response_text or "").strip().lower()
+
+    if obs.current_item is None:
+        return ReturnsAction(action=DispositionAction.WAIT)
+
+    for act in DispositionAction:
+        if act.value == text:
+            return ReturnsAction(action=act)
+
+    for act in DispositionAction:
+        if act.value in text:
+            return ReturnsAction(action=act)
+
+    return ReturnsAction(action=DispositionAction.RESELL_DISCOUNT_30)

inference.py

@@ -24,6 +24,11 @@ from openai import OpenAI
 
 from RevLogiXenv_v0 import AutonomousReturnsEnv
 from RevLogiXenv_v0.models import DispositionAction, ReturnsAction, ReturnsObservation
+from RevLogiXenv_v0.prompting import (
+    MINIMAL_SYSTEM_PROMPT,
+    observation_to_prompt_inference as observation_to_prompt,
+    parse_action_inference as parse_action,
+)
 
 load_dotenv()
 
@@ -48,12 +53,6 @@ MAX_TOKENS = 64
 _REWARD_MIN = 0.01
 _REWARD_MAX = 0.99
 
-LLM_SYSTEM_PROMPT = (
-    "You are a reverse-logistics triage agent. Output EXACTLY ONE WORD from this list: "
-    "RESELL_FULL, RESELL_DISCOUNT_15, RESELL_DISCOUNT_30, RESELL_DISCOUNT_50, REFURBISH, "
-    "DISPOSE, FLAG_FRAUD, INSPECT, WAIT. No explanation. No punctuation. Just the single word."
-)
-
 
 def log_start(task: str, env: str, model: str) -> None:
     print(f"[START] task={task} env={env} model={model}", flush=True)
@@ -88,83 +87,12 @@ def _clamp_reward(r: float) -> float:
     return max(_REWARD_MIN, min(_REWARD_MAX, r))
 
 
-def observation_to_prompt(obs: ReturnsObservation) -> str:
-    if obs.current_item is None:
-        return "No items left. Output exactly: wait"
-
-    item = obs.current_item
-    lines: list[str] = [
-        f"Product: {item.product_title}",
-        f"Price: ${item.price:.2f}",
-        f"Score: {item.noisy_condition_score:.1f}/10",
-        f"Reason: {item.stated_return_reason}",
-        f"Returns: {item.customer_profile.total_returns}",
-        f"Fraud flags: {item.customer_profile.historical_fraud_flags}",
-        f"Abuse: {item.customer_profile.recent_abuse_signals}",
-        f"Packaging: {item.packaging_condition}",
-    ]
-    if item.damage_flags:
-        lines.append(f"Damage: {', '.join(item.damage_flags)}")
-    if item.inspection_note:
-        lines.append(f"Note: {item.inspection_note}")
-
-    lines.append(f"Remaining: {obs.remaining_items}, Pending: {obs.pending_resolution_count}")
-    lines.append(f"Ledger: ${obs.running_ledger:.2f}")
-    if obs.last_three_resolutions:
-        lines.append("Recent:")
-        for resolution in obs.last_three_resolutions:
-            lines.append(f"{resolution.action.value}={resolution.normalized_reward:.2f}")
-    lines.append("")
-    lines.append(
-        "Output ONE word: RESELL_FULL, RESELL_DISCOUNT_15, RESELL_DISCOUNT_30, "
-        "RESELL_DISCOUNT_50, REFURBISH, DISPOSE, FLAG_FRAUD, INSPECT, or WAIT"
-    )
-    return "\n".join(lines)
-
-
-def parse_action(response_text: str, obs: ReturnsObservation) -> ReturnsAction:
-    if obs.current_item is None:
-        return ReturnsAction(action=DispositionAction.WAIT)
-
-    text = (response_text or "").lower().strip()
-    actions = [
-        "resell_full",
-        "resell_discount_15",
-        "resell_discount_30",
-        "resell_discount_50",
-        "refurbish",
-        "dispose",
-        "flag_fraud",
-        "inspect",
-        "wait",
-    ]
-    pattern = r"\b(" + "|".join(sorted(actions, key=len, reverse=True)) + r")\b"
-
-    lines = [line.strip() for line in text.split("\n") if line.strip()]
-    for line in reversed(lines):
-        line_match = re.fullmatch(pattern, line)
-        if line_match:
-            matched = line_match.group(1)
-            for action in DispositionAction:
-                if action.value == matched:
-                    return ReturnsAction(action=action)
-
-    matches = re.findall(pattern, text)
-    if matches:
-        matched = matches[-1]
-        for action in DispositionAction:
-            if action.value == matched:
-                return ReturnsAction(action=action)
-
-    return ReturnsAction(action=DispositionAction.WAIT)
-
-
 def get_model_response(client: OpenAI, prompt: str) -> str:
     try:
         completion = client.chat.completions.create(
             model=MODEL_NAME,
             messages=[
-                {"role": "system", "content": LLM_SYSTEM_PROMPT},
+                {"role": "system", "content": MINIMAL_SYSTEM_PROMPT},
                 {"role": "user", "content": prompt},
             ],
             temperature=TEMPERATURE,

openenv.yaml

@@ -38,11 +38,8 @@ tasks:
     noise_level: hard
     delay_type: variable
     scoring:
-      type: composite
+      type: margin
       range: [0.01, 0.99]
-      weights:
-        margin: 0.6
-        fraud_f1: 0.4
 
   hard:
     description: "Extreme uncertainty + adversarial noise - new extra-hard difficulty"
@@ -125,4 +122,12 @@ reward:
 scoring:
   reward_range: [0.01, 0.99]
   success_threshold: 0.5
+  # Inference-mode score: mean of per-step shaped rewards, clamped to (0.01, 0.99).
+  # The hackathon Phase 2 validator derives the task score from the rewards list
+  # emitted by inference.py, so this must match what inference.py computes.
   score_formula: mean(step_rewards)
+  # Grader-mode score (Python API via Grader class):
+  #   easy/medium: final_score = oracle_margin_score  (oracle-normalized profit)
+  #   hard:        final_score = 0.6 * oracle_margin_score + 0.4 * fraud_f1
+  # These two scoring modes target different use cases (hackathon validation vs
+  # local Python-based evaluation) and are intentionally kept separate.

tests/test_grader_edge_cases.py

@@ -0,0 +1,161 @@
+"""
+Tests for Grader edge cases and fraud metric robustness.
+
+Covers:
+- No fraud items present, agent does not flag anything → f1 near perfect
+- No fraud items present, agent does flag something → f1 low floor
+- All fraud items correctly flagged → f1 perfect
+- Legacy easy task alias still works
+- extra_hard noise level is accessible
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "RevLogiXenv_v0"))
+
+from RevLogiXenv_v0 import AutonomousReturnsEnv, Grader
+from RevLogiXenv_v0.models import DispositionAction, ReturnsAction
+
+
+def _run_episode_with_action(task: str, seed: int, policy_fn) -> AutonomousReturnsEnv:
+    """Helper: run a full episode with a given policy function."""
+    env = AutonomousReturnsEnv(task)
+    obs = env.reset(seed=seed)
+    while not obs.done:
+        action = policy_fn(obs)
+        obs = env.step(action)
+    return env
+
+
+def _always_wait(obs):
+    """Policy that always waits — useful for draining queues without penalty."""
+    return ReturnsAction(action=DispositionAction.WAIT)
+
+
+def _always_resell_full(obs):
+    """Policy that always resells at full — used to probe fraud metrics."""
+    return ReturnsAction(action=DispositionAction.RESELL_FULL)
+
+
+def test_no_fraud_items_no_flags_yields_high_f1():
+    """
+    When no fraudulent items exist in the episode and the agent never flags
+    anything, the fraud F1 should be clamped to near-perfect (0.99).
+    """
+    # easy task has fraud_enabled: false — guaranteed no fraud items
+    env = _run_episode_with_action("easy", seed=7, policy_fn=_always_wait)
+    grader = Grader("easy")
+    result = grader.score_completed_episode(env=env)
+
+    f1 = result["fraud_metrics"]["f1"]
+    assert f1 == 0.99, f"Expected f1=0.99 for no-fraud task, got {f1}"
+
+
+def test_easy_task_alias_legacy_easy_still_works():
+    """
+    The _legacy_easy task alias is declared in openenv.yaml and must be
+    accepted by the runtime environment.
+    """
+    env = AutonomousReturnsEnv("_legacy_easy")
+    obs = env.reset(seed=1)
+    assert obs is not None
+    assert env._config["num_items"] == 10
+    assert env._config["noise_level"] == "easy"
+    assert env._config["delay_type"] == "immediate"
+
+    # Backward compatibility alias should continue to work as before.
+    legacy_alias_env = AutonomousReturnsEnv("_old_easy")
+    alias_obs = legacy_alias_env.reset(seed=1)
+    assert alias_obs is not None
+    steps = 0
+    while not obs.done and steps < 50:
+        action = ReturnsAction(action=DispositionAction.WAIT)
+        obs = env.step(action)
+        steps += 1
+    assert steps > 0
+
+
+def test_extra_hard_noise_level_accessible():
+    """
+    Verify that the 'extra_hard' noise level can be set via task configuration
+    and does not raise errors during item generation.
+    """
+    # 'hard' task uses noise_level: extra_hard — verify this works end-to-end
+    env = AutonomousReturnsEnv("hard")
+    obs = env.reset(seed=999)
+    steps = 0
+    while not obs.done and steps < 100:
+        action = ReturnsAction(action=DispositionAction.RESELL_DISCOUNT_30)
+        obs = env.step(action)
+        steps += 1
+    assert obs.done, "hard task should complete within 100 steps"
+
+
+def test_grader_rejects_incomplete_episode():
+    """Grader must raise RuntimeError when scoring an incomplete episode."""
+    env = AutonomousReturnsEnv("easy")
+    env.reset(seed=42)
+    # Don't run any steps — episode is incomplete
+    grader = Grader("easy")
+    try:
+        grader.score_completed_episode(env=env)
+        assert False, "Expected RuntimeError for incomplete episode"
+    except RuntimeError as e:
+        assert "incomplete" in str(e).lower()
+
+
+def test_grader_rejects_no_snapshot():
+    """Grader must raise RuntimeError when environment has no episode snapshot."""
+    # Create env but don't call reset()
+    env = AutonomousReturnsEnv("easy")
+    grader = Grader("easy")
+    try:
+        grader.score_completed_episode(env=env)
+        assert False, "Expected RuntimeError for missing episode snapshot"
+    except RuntimeError as e:
+        assert "snapshot" in str(e).lower() or "reset" in str(e).lower()
+
+
+def test_reward_detail_components_populated():
+    """
+    Verify that reward_detail.components is populated during normal episode execution.
+    At least one step should have non-empty components dict.
+    """
+    env = AutonomousReturnsEnv("medium")
+    obs = env.reset(seed=55)
+
+    components_seen: list[dict] = []
+    while not obs.done:
+        action = ReturnsAction(action=DispositionAction.RESELL_DISCOUNT_30)
+        obs = env.step(action)
+        if obs.reward_detail and obs.reward_detail.components:
+            components_seen.append(obs.reward_detail.components)
+
+    assert len(components_seen) > 0, "Expected at least one step with populated components"
+
+
+def test_fraud_metrics_precision_recall_clamped():
+    """All fraud precision/recall/f1 values must be within [0.01, 0.99] inclusive."""
+    env = _run_episode_with_action("medium", seed=21, policy_fn=_always_resell_full)
+    grader = Grader("medium")
+    result = grader.score_completed_episode(env=env)
+
+    fm = result["fraud_metrics"]
+    for key in ("precision", "recall", "f1"):
+        score = fm[key]
+        # Clamped scores are in the inclusive [0.01, 0.99] range per grader._clamp_score
+        assert 0.01 <= score <= 0.99, f"{key}={score} outside [0.01, 0.99]"
+
+
+if __name__ == "__main__":
+    test_no_fraud_items_no_flags_yields_high_f1()
+    test_easy_task_alias_legacy_easy_still_works()
+    test_extra_hard_noise_level_accessible()
+    test_grader_rejects_incomplete_episode()
+    test_grader_rejects_no_snapshot()
+    test_reward_detail_components_populated()
+    test_fraud_metrics_precision_recall_clamped()
+    print("All grader edge-case tests passed.")

tests/test_policies_improvements.py

@@ -111,3 +111,39 @@ def test_policy_config_inspect_thresholds():
     assert config.inspect_score_low == 5.0
     assert config.inspect_score_high == 7.5
     assert config.inspect_min_price == 250.0
+
+
+def test_heuristic_does_not_repeat_inspect_after_note_update():
+    """
+    After an INSPECT action updates the item's inspection note, the next policy
+    decision for the same item should not INSPECT again.
+    """
+    policy = HeuristicPolicy()
+    env = AutonomousReturnsEnv("hard")
+    obs = env.reset(seed=42)
+
+    inspected_once = False
+    steps = 0
+
+    while not obs.done and steps < 200:
+        action = policy(obs)
+
+        if not inspected_once:
+            if action.action == DispositionAction.INSPECT and obs.current_item is not None:
+                inspected_once = True
+                item_id = obs.current_item.item_id
+                obs = env.step(action)
+                assert obs.current_item is not None
+                assert obs.current_item.item_id == item_id
+                assert obs.current_item.inspection_note is not None
+
+                next_action = policy(obs)
+                assert next_action.action != DispositionAction.INSPECT, (
+                    "Policy repeated INSPECT on same item after inspection note update"
+                )
+                break
+
+        obs = env.step(action)
+        steps += 1
+
+    assert inspected_once, "Did not encounter an INSPECT scenario in hard task"

tests/test_scoring_consistency.py

@@ -0,0 +1,132 @@
+"""
+Tests for scoring consistency across inference-mode and grader-mode outputs.
+
+Verifies that:
+1. inference.py and grader.py both produce scores within (0.01, 0.99).
+2. _scoring_mode and _score_formula markers are present in grader output.
+3. The two scoring modes are intentionally different (documented in openenv.yaml).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Allow imports from RevLogiXenv_v0 in the worktree
+sys.path.insert(0, str(Path(__file__).parent.parent / "RevLogiXenv_v0"))
+
+from RevLogiXenv_v0 import AutonomousReturnsEnv, Grader
+from RevLogiXenv_v0.policies import heuristic_action
+
+
+def test_grader_output_contains_scoring_markers():
+    """Grader._compute_scores() must include _scoring_mode and _score_formula."""
+    env = AutonomousReturnsEnv("easy")
+    obs = env.reset(seed=42)
+
+    while not obs.done:
+        action = heuristic_action(obs)
+        obs = env.step(action)
+
+    grader = Grader("easy")
+    result = grader.score_completed_episode(env=env)
+
+    assert "_scoring_mode" in result, "Grader output missing _scoring_mode"
+    assert result["_scoring_mode"] == "grader"
+    assert "_score_formula" in result, "Grader output missing _score_formula"
+    assert result["_score_formula"] == "margin_score"
+
+
+def test_grader_hard_task_has_composite_formula():
+    """Hard task grader must report the composite fraud formula."""
+    env = AutonomousReturnsEnv("hard")
+    obs = env.reset(seed=99)
+
+    while not obs.done:
+        action = heuristic_action(obs)
+        obs = env.step(action)
+
+    grader = Grader("hard")
+    result = grader.score_completed_episode(env=env)
+
+    assert result["_scoring_mode"] == "grader"
+    assert "0.6 * margin_score + 0.4 * fraud_f1" in result["_score_formula"]
+
+
+def test_grader_scores_bounded_to_open_interval():
+    """All grader scores must be strictly within (0.01, 0.99)."""
+    env = AutonomousReturnsEnv("medium")
+    obs = env.reset(seed=7)
+
+    while not obs.done:
+        action = heuristic_action(obs)
+        obs = env.step(action)
+
+    grader = Grader("medium")
+    result = grader.score_completed_episode(env=env)
+
+    for key in ("final_score", "margin_score"):
+        score = result[key]
+        assert 0.01 < score < 0.99, f"{key}={score} outside (0.01, 0.99)"
+
+    f1 = result["fraud_metrics"]["f1"]
+    assert 0.01 < f1 < 0.99, f"fraud_f1={f1} outside (0.01, 0.99)"
+
+
+def test_grader_consistent_across_tasks():
+    """Grader must produce valid output for easy, medium, and hard tasks."""
+    tasks = ["easy", "medium", "hard"]
+    for task in tasks:
+        env = AutonomousReturnsEnv(task)
+        obs = env.reset(seed=123)
+
+        while not obs.done:
+            action = heuristic_action(obs)
+            obs = env.step(action)
+
+        grader = Grader(task)
+        result = grader.score_completed_episode(env=env)
+
+        assert "final_score" in result
+        assert "margin_score" in result
+        assert "fraud_metrics" in result
+        assert "profit" in result
+        assert 0.01 < result["final_score"] < 0.99
+
+
+def test_inference_score_mean_of_step_rewards():
+    """
+    The inference-mode score formula is mean(step_rewards), clamped to (0.01, 0.99).
+    This test verifies that the inference.py output format matches the documented formula.
+    """
+    # We test the computation logic without an LLM by directly exercising
+    # the reward-collection path in an episode.
+    from RevLogiXenv_v0.environment import AutonomousReturnsEnv
+    from RevLogiXenv_v0.policies import heuristic_action
+
+    REWARD_MIN = 0.01
+    REWARD_MAX = 0.99
+
+    task = "easy"
+    env = AutonomousReturnsEnv(task)
+    obs = env.reset(seed=42)
+
+    step_rewards: list[float] = []
+    while not obs.done:
+        action = heuristic_action(obs)
+        obs = env.step(action)
+        if obs.reward is not None:
+            clamped = float(max(REWARD_MIN, min(REWARD_MAX, obs.reward)))
+            step_rewards.append(clamped)
+
+    inference_score = sum(step_rewards) / len(step_rewards) if step_rewards else 0.0
+    assert 0.01 < inference_score < 0.99
+
+
+if __name__ == "__main__":
+    test_grader_output_contains_scoring_markers()
+    test_grader_hard_task_has_composite_formula()
+    test_grader_scores_bounded_to_open_interval()
+    test_grader_consistent_across_tasks()
+    test_inference_score_mean_of_step_rewards()
+    print("All scoring consistency tests passed.")