Sync InvoiceGuard code for GRPO training job

.openenvignore

@@ -0,0 +1,10 @@
+.env
+.env.example
+__pycache__/
+*.pyc
+.venv/
+inference.py
+test_live_space.py
+eval_round2.py
+outputs/round2/
+training/

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,46 @@
+[
+  "tests/test_environment.py::TestReset::test_all_canonical_tasks_load",
+  "tests/test_environment.py::TestReset::test_reset_clean_state",
+  "tests/test_environment.py::TestReset::test_reset_has_available_actions",
+  "tests/test_environment.py::TestReset::test_reset_provides_goal",
+  "tests/test_environment.py::TestReset::test_reset_provides_suggested_actions",
+  "tests/test_environment.py::TestReset::test_reset_returns_observation",
+  "tests/test_environment.py::TestReset::test_reset_sequential_tasks",
+  "tests/test_environment.py::TestState::test_state_accessible",
+  "tests/test_environment.py::TestState::test_state_tracks_actions",
+  "tests/test_environment.py::TestStep::test_findings_accumulate",
+  "tests/test_environment.py::TestStep::test_investigation_action",
+  "tests/test_environment.py::TestStep::test_repeated_action_penalty",
+  "tests/test_environment.py::TestStep::test_step_decrements_remaining",
+  "tests/test_environment.py::TestStep::test_suggested_actions_update_after_step",
+  "tests/test_environment.py::TestSubmission::test_correct_resolution",
+  "tests/test_environment.py::TestSubmission::test_missing_fields_returns_error",
+  "tests/test_environment.py::TestSubmission::test_wrong_decision_lower_score",
+  "tests/test_environment.py::TestTaskDiversity::test_scores_in_valid_range",
+  "tests/test_grader.py::TestExplanationScoring::test_empty_explanation",
+  "tests/test_grader.py::TestExplanationScoring::test_explanation_with_numbers",
+  "tests/test_grader.py::TestExplanationScoring::test_good_explanation",
+  "tests/test_grader.py::TestExplanationScoring::test_vague_explanation_scores_low",
+  "tests/test_grader.py::TestGradeEpisode::test_all_rubric_dimensions_present",
+  "tests/test_grader.py::TestGradeEpisode::test_no_decision_scores_zero",
+  "tests/test_grader.py::TestGradeEpisode::test_partial_decision_credit",
+  "tests/test_grader.py::TestGradeEpisode::test_perfect_score",
+  "tests/test_grader.py::TestGradeEpisode::test_score_in_bounds",
+  "tests/test_grader.py::TestGradeEpisode::test_wrong_decision_zero_decision_score",
+  "tests/test_models.py::TestAction::test_minimal_action",
+  "tests/test_models.py::TestAction::test_resolution_action",
+  "tests/test_models.py::TestBusinessEntities::test_company_policy_defaults",
+  "tests/test_models.py::TestBusinessEntities::test_invoice_creation",
+  "tests/test_models.py::TestEnums::test_action_types_count",
+  "tests/test_models.py::TestEnums::test_decision_types",
+  "tests/test_models.py::TestEnums::test_difficulty_levels",
+  "tests/test_models.py::TestEnums::test_exception_types_include_key_variants",
+  "tests/test_models.py::TestEnums::test_task_ids_minimum_12_canonical",
+  "tests/test_models.py::TestEnums::test_task_ids_minimum_6_canonical",
+  "tests/test_models.py::TestGraderResult::test_score_bounds",
+  "tests/test_models.py::TestGraderResult::test_valid_score",
+  "tests/test_models.py::TestObservation::test_defaults",
+  "tests/test_models.py::TestObservation::test_populated",
+  "tests/test_models.py::TestState::test_defaults",
+  "tests/test_models.py::TestState::test_mutation"
+]

Dockerfile

@@ -0,0 +1,80 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=invoice_guard
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -0,0 +1,248 @@
+---
+title: Invoice Guard Environment Server
+emoji: 📋
+colorFrom: purple
+colorTo: yellow
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# InvoiceGuard -- Three-Way Invoice Matching Environment
+
+An OpenEnv environment that simulates accounts payable exception resolution. An AI agent investigates multi-document business cases -- invoices, purchase orders, goods receipt notes, vendor profiles, and company policies -- to detect discrepancies, classify exception types, and render correct decisions.
+
+## Motivation
+
+Three-way invoice matching is one of the most common and error-prone tasks in enterprise finance. Accounts payable teams manually compare invoices against purchase orders and goods receipt notes to detect overbilling, partial shipments, duplicate submissions, and price variances. This environment turns that real-world workflow into a structured evaluation benchmark where an AI agent must gather evidence through sequential investigation actions and reach a correct, policy-compliant decision.
+
+## Tasks
+
+| Task ID | Description | Difficulty | Expected Decision | Exception Type |
+|---------|-------------|------------|-------------------|----------------|
+| `task_1_clean_match` | All documents align within tolerance | Easy | `approve_for_payment` | `clean_match` |
+| `task_2_partial_receipt` | Billed quantity exceeds received quantity | Moderate | `place_on_hold` | `partial_receipt` |
+| `task_3_price_variance` | Unit price exceeds PO price beyond tolerance | Moderate | `escalate_for_supervisor_review` | `price_mismatch` |
+| `task_4_duplicate_invoice` | Previously processed invoice resubmitted | Hard | `reject_invoice` | `duplicate_invoice` |
+| `task_5_mixed_discrepancy` | Invoice with both price variance and partial receipt; conflicting signals | Hard | `escalate_for_supervisor_review` | `price_mismatch` |
+| `task_6_false_positive_duplicate` | Invoice looks like a duplicate but is a legitimate recurring order for a different PO | Hard | `approve_for_payment` | `clean_match` |
+| `task_7_retroactive_price` | Vendor applied a price increase retroactively; PO predates the effective date | Hard | `escalate_for_supervisor_review` | `price_mismatch` |
+| `task_8_split_invoice_pattern` | Supplier splits large order into sub-threshold invoices to dodge auto-approval | Hard | `escalate_for_supervisor_review` | `policy_violation` |
+| `task_9_clean_from_risky_vendor` | Clean invoice from high-risk vendor with 5 prior incidents -- false-positive trap | Hard | `approve_for_payment` | `clean_match` |
+| `task_10_rounding_false_alarm` | Invoice total off by $0.01 due to line-item rounding -- all else matches perfectly | Hard | `approve_for_payment` | `clean_match` |
+| `task_11_authorized_overship` | GRN shows 110 received vs 100 ordered, but PO amendment authorized 10% overship | Hard | `approve_for_payment` | `clean_match` |
+| `task_12_corrected_resubmission` | Corrected invoice (INV-R1) looks like a duplicate of rejected original | Hard | `approve_for_payment` | `clean_match` |
+
+Each task includes fully synthetic business documents with deterministic ground truth and a multi-criteria grader. Tasks 5-8 test ambiguity, temporal reasoning, and cross-case pattern detection. Tasks 9-12 are false-positive traps where surface signals mislead toward rejection but deeper investigation reveals the correct answer is approval.
+
+## Action Space
+
+The agent has 12 available actions divided into investigation, proposal, and terminal categories.
+
+### Investigation Actions (provide `action_type` only)
+
+| Action | Description |
+|--------|-------------|
+| `inspect_invoice_line_items` | Reveal detailed invoice line items (codes, quantities, prices, totals) |
+| `inspect_purchase_order` | Reveal purchase order details (ordered quantities, agreed prices) |
+| `inspect_goods_receipt_note` | Reveal goods receipt note (received/accepted/rejected quantities) |
+| `inspect_vendor_profile` | Reveal vendor risk tier, duplicate history, escalation thresholds |
+| `inspect_policy_rules` | Reveal company matching tolerances and escalation rules |
+| `check_for_duplicate_invoice` | Search case history for similar/processed invoices |
+| `compare_quantity` | Compare billed vs ordered vs received quantities per line item |
+| `compare_price` | Compare billed unit prices vs PO-agreed prices per line item |
+| `compare_totals` | Verify subtotal consistency, PO total match, tax, and grand total |
+| `summarize_findings` | Get a numbered summary of all collected findings |
+
+### Proposal Action
+
+| Action | Description |
+|--------|-------------|
+| `propose_exception_type` | Declare the suspected exception type (with `exception_type` field) |
+
+### Terminal Action
+
+| Action | Required Fields | Description |
+|--------|----------------|-------------|
+| `submit_final_resolution` | `final_decision`, `exception_type`, `evidence_references`, `explanation` | End the episode with a decision |
+
+### Action JSON Format
+
+```json
+{"action_type": "inspect_purchase_order"}
+```
+
+```json
+{
+  "action_type": "submit_final_resolution",
+  "final_decision": "escalate_for_supervisor_review",
+  "exception_type": "price_mismatch",
+  "evidence_references": ["inspect_purchase_order", "compare_price", "inspect_policy_rules"],
+  "explanation": "Price variance of 10% exceeds 5% tolerance, requiring supervisor escalation per company policy."
+}
+```
+
+## Observation Space
+
+Each step returns an `InvoiceGuardObservation` with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `case_id` | `str` | Unique case identifier |
+| `task_id` | `str` | Which task is being evaluated |
+| `difficulty` | `str` | `easy`, `moderate`, or `hard` |
+| `invoice_summary` | `str` | One-line invoice overview (supplier, amount, PO ref) |
+| `goal` | `str` | Natural language description of the agent's objective |
+| `available_actions` | `list[str]` | Actions the agent can take |
+| `revealed_documents` | `list[str]` | Documents the agent has already inspected |
+| `findings` | `list[str]` | Accumulated investigation findings |
+| `remaining_steps` | `int` | Steps left before timeout |
+| `last_action_result` | `str` | Detailed output from the most recent action |
+| `last_action_error` | `bool` | Whether the last action had an error |
+| `warnings` | `list[str]` | System warnings (e.g., low steps remaining) |
+| `reward` | `float` | Reward signal for the last action |
+| `done` | `bool` | Whether the episode has ended |
+| `metadata` | `dict` | Grader results (on episode end) |
+
+## Reward Design
+
+The environment provides dense, per-step rewards:
+
+| Event | Reward |
+|-------|--------|
+| Reveal a new document | +0.05 |
+| Useful comparison finding discrepancy | +0.10 |
+| Confirm no issue (clean comparison) | +0.02 |
+| Propose correct exception type | +0.15 |
+| Propose wrong exception type | -0.05 |
+| Summarize findings | +0.03 |
+| Repeat an already-seen action | -0.02 |
+| Submit correct final decision | +0.30 |
+| Submit wrong final decision | -0.20 |
+| Correct exception type on resolution | +0.15 |
+
+## Grading
+
+Episodes are scored by a deterministic grader on six weighted criteria (total = 1.0):
+
+| Criterion | Weight | Description |
+|-----------|--------|-------------|
+| Decision correctness | 0.35 | Exact match = 1.0, partial credit for related decisions |
+| Exception type | 0.20 | Correct classification of the exception |
+| Evidence sufficiency | 0.15 | Did the agent inspect the right documents? |
+| Investigation quality | 0.10 | Breadth of document review and findings |
+| Explanation quality | 0.10 | Cites specific numbers, references policy, uses correct terminology |
+| Efficiency | 0.10 | Completing within step budget without waste |
+
+## Decisions
+
+| Decision | When to use |
+|----------|-------------|
+| `approve_for_payment` | All matches are clean and within tolerance |
+| `place_on_hold` | Billed quantity exceeds received quantity |
+| `reject_invoice` | Duplicate invoice or fraudulent submission |
+| `escalate_for_supervisor_review` | Price/total variance exceeds tolerance, high-value invoice |
+
+## Setup & Usage
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- Docker (for containerized deployment)
+
+### Local Development
+
+```bash
+cd invoice_guard
+
+# Install dependencies with uv
+uv sync
+
+# Start the server
+uv run uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+# Validate
+openenv validate
+```
+
+### Running the Baseline Agent
+
+```bash
+cd invoice_guard
+
+# Create .env from the example
+cp .env.example .env
+# Edit .env with your API key and model
+
+# Run inference
+uv run python inference.py
+```
+
+### Docker
+
+```bash
+cd invoice_guard
+
+# Build
+docker build -t invoiceguard .
+
+# Run
+docker run -p 8000:8000 invoiceguard
+
+# Run with hackathon resource constraints
+docker run --cpus=2 --memory=8g -p 8000:8000 invoiceguard
+
+# Validate against running container
+openenv validate --url http://localhost:8000
+```
+
+### Deploy to Hugging Face Spaces
+
+```bash
+cd invoice_guard
+openenv push
+# or: openenv push --namespace my-org --private
+```
+
+## Baseline Scores (12 tasks)
+
+| Model | Avg Score | task_1 | task_2 | task_3 | task_4 | task_5 | task_6 | task_7 | task_8 | task_9 | task_10 | task_11 | task_12 |
+|-------|-----------|--------|--------|--------|--------|--------|--------|--------|--------|--------|---------|---------|---------|
+| **gpt-4.1-mini** | **0.87** | 0.95 | 0.78 | 0.75 | 0.95 | 0.78 | 0.95 | 0.75 | 0.75 | 0.95 | 0.95 | 0.98 | 0.95 |
+| **gpt-5.4-mini** | **0.87** | 0.98 | 0.95 | 0.73 | 0.98 | 0.75 | 0.98 | 0.75 | 0.50 | 0.95 | 0.98 | 0.98 | 0.95 |
+| **gpt-4.1** | **0.79** | 0.95 | 0.75 | 0.75 | 0.47 | 0.78 | 0.95 | 0.78 | 0.75 | 0.40 | 0.95 | 0.95 | 0.95 |
+| **gpt-5.4** | **0.78** | 0.95 | 0.75 | 0.70 | 0.47 | 0.75 | 0.95 | 0.78 | 0.75 | 0.40 | 0.95 | 0.95 | 0.95 |
+
+Key observations:
+- **Task 9** (clean invoice from risky vendor) is a strong false-positive trap: both gpt-4.1 and gpt-5.4 escalated instead of approving, scoring only 0.40.
+- **Task 8** (split invoice pattern) tripped gpt-5.4-mini, which rejected instead of escalating (0.50).
+- **Task 4** (duplicate invoice) tripped both full-size models, which escalated instead of rejecting (0.47).
+- Mini models consistently outperform their larger counterparts on this benchmark, suggesting the tasks reward focused analysis over verbose reasoning.
+
+## Project Structure
+
+```
+invoice_guard/
+|---- openenv.yaml              # OpenEnv manifest
+|---- pyproject.toml             # Dependencies (managed by uv)
+|---- uv.lock                   # Locked dependencies
+|---- Dockerfile                # Container image definition
+|---- models.py                 # All data models (Action, Observation, State, entities)
+|---- client.py                 # InvoiceGuardEnv client (EnvClient subclass)
+|---- inference.py              # Baseline LLM agent script
+|---- .env.example              # Environment variable template
+|---- tasks/
+|   |---- __init__.py
+|   |---- definitions.py        # Synthetic case templates and ground truth
+|---- graders/
+|   |---- __init__.py
+|   |---- scoring.py            # Deterministic multi-criteria grader
+|---- server/
+    |---- __init__.py
+    |---- app.py                 # FastAPI application (HTTP + WebSocket)
+    |---- invoice_guard_environment.py  # Core Environment implementation
+```

__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Invoice Guard Environment."""
+
+from .client import InvoiceGuardEnv
+from .models import InvoiceGuardAction, InvoiceGuardObservation
+
+__all__ = [
+    "InvoiceGuardAction",
+    "InvoiceGuardObservation",
+    "InvoiceGuardEnv",
+]

client.py

@@ -0,0 +1,77 @@
+"""InvoiceGuard Environment Client."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+try:
+    from .models import (
+        InvoiceGuardAction,
+        InvoiceGuardObservation,
+        InvoiceGuardState,
+    )
+except (ImportError, ModuleNotFoundError):
+    from models import (
+        InvoiceGuardAction,
+        InvoiceGuardObservation,
+        InvoiceGuardState,
+    )
+
+
+class InvoiceGuardEnv(
+    EnvClient[InvoiceGuardAction, InvoiceGuardObservation, InvoiceGuardState]
+):
+    """
+    Client for the InvoiceGuard Environment.
+
+    Example:
+        >>> async with InvoiceGuardEnv(base_url="http://localhost:8000") as client:
+        ...     result = await client.reset(task_id="task_1_clean_match")
+        ...     print(result.observation.invoice_summary)
+    """
+
+    def _step_payload(self, action: InvoiceGuardAction) -> Dict:
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: Dict) -> StepResult[InvoiceGuardObservation]:
+        obs_data = payload.get("observation", {})
+        observation = InvoiceGuardObservation(
+            case_id=obs_data.get("case_id", ""),
+            task_id=obs_data.get("task_id", ""),
+            difficulty=obs_data.get("difficulty", ""),
+            invoice_summary=obs_data.get("invoice_summary", ""),
+            goal=obs_data.get("goal", ""),
+            available_actions=obs_data.get("available_actions", []),
+            revealed_documents=obs_data.get("revealed_documents", []),
+            findings=obs_data.get("findings", []),
+            remaining_steps=obs_data.get("remaining_steps", 0),
+            last_action_result=obs_data.get("last_action_result", ""),
+            last_action_error=obs_data.get("last_action_error", False),
+            warnings=obs_data.get("warnings", []),
+            grader_result=obs_data.get("grader_result", {}),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> InvoiceGuardState:
+        return InvoiceGuardState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            task_id=payload.get("task_id", ""),
+            difficulty=payload.get("difficulty", ""),
+            case_id=payload.get("case_id", ""),
+            actions_taken=payload.get("actions_taken", []),
+            documents_revealed=payload.get("documents_revealed", []),
+            findings_collected=payload.get("findings_collected", []),
+            is_finalized=payload.get("is_finalized", False),
+            cumulative_reward=payload.get("cumulative_reward", 0.0),
+        )

eval_round2.py

@@ -0,0 +1,252 @@
+"""
+Round 2 evaluation harness for InvoiceGuard.
+
+Runs a chosen task slice (canonical / hard / all) against any
+OpenAI-compatible model and writes a structured JSON report containing,
+for every task: grader score, six grader sub-component scores, decision,
+exception type, steps used, shortcut-penalty flag, and the per-step
+reward_components log emitted by the environment.
+
+Designed so baseline_*.json (Stage F) and trained_*.json (Stage G) share
+the SAME schema and can be diffed with `--compare A.json B.json`.
+
+Usage examples (PowerShell):
+    # Baseline run on hard slice with default model from env vars
+    uv run python eval_round2.py --slice hard --model-tag baseline
+
+    # Run both slices, write to outputs/round2/
+    uv run python eval_round2.py --slice all --model-tag baseline
+
+    # Compare baseline vs trained
+    uv run python eval_round2.py --compare outputs/round2/hard__baseline.json outputs/round2/hard__trained.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+# Reuse the existing inference helpers so prompts/parsing stay identical.
+from inference import (  # type: ignore
+    API_BASE_URL,
+    API_KEY,
+    MODEL_NAME,
+    run_episode_local,
+)
+from models import TaskID  # type: ignore
+from server.invoice_guard_environment import InvoiceGuardEnvironment  # type: ignore
+from tasks import TASK_LIST, HARD_TASK_LIST  # type: ignore
+
+
+load_dotenv()
+
+OUT_DIR_DEFAULT = Path(__file__).parent / "outputs" / "round2"
+
+# Grader sub-component keys we always extract for the report.
+COMPONENT_KEYS = [
+    "decision_score",
+    "exception_type_score",
+    "evidence_score",
+    "investigation_score",
+    "explanation_score",
+    "efficiency_score",
+]
+
+
+def _slice_tasks(slice_name: str) -> List[TaskID]:
+    if slice_name == "canonical":
+        return list(TASK_LIST)
+    if slice_name == "hard":
+        return list(HARD_TASK_LIST)
+    if slice_name == "all":
+        return list(TASK_LIST) + list(HARD_TASK_LIST)
+    raise SystemExit(f"Unknown --slice: {slice_name!r}")
+
+
+def _run_slice(
+    slice_name: str,
+    model_tag: str,
+    out_dir: Path,
+) -> Path:
+    """Run one slice end-to-end and write the JSON report. Returns path."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    task_ids = _slice_tasks(slice_name)
+
+    print("=" * 70, flush=True)
+    print(f"InvoiceGuard Round 2 eval | slice={slice_name} | tasks={len(task_ids)}", flush=True)
+    print(f"Model: {MODEL_NAME} | Base URL: {API_BASE_URL}", flush=True)
+    print(f"Tag:   {model_tag} | Out dir: {out_dir}", flush=True)
+    print("=" * 70, flush=True)
+
+    llm = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    env = InvoiceGuardEnvironment()
+
+    per_task: list[dict] = []
+    started_at = datetime.now(timezone.utc).isoformat()
+    t0 = time.time()
+
+    for task_id in task_ids:
+        start = time.time()
+        # `run_episode_local` already handles the conversation loop and stdout
+        # in the hackathon-mandated [START]/[STEP]/[END] format.
+        result = run_episode_local(env, llm, task_id)
+        elapsed = time.time() - start
+
+        grader_breakdown = result.get("grader_breakdown") or {}
+        components = {k: float(grader_breakdown.get(k, 0.0)) for k in COMPONENT_KEYS}
+
+        # Pull richer metadata from the env directly (last terminal obs went
+        # back through the inference loop but we still hold env.state).
+        s = env.state
+        reward_components = list(getattr(s, "reward_components", []))
+
+        per_task.append(
+            {
+                "task_id": result["task_id"],
+                "decision": result.get("decision"),
+                "exception_type": result.get("exception_type"),
+                "steps": result["steps"],
+                "grader_score": result["grader_score"],
+                "components": components,
+                "shortcut_penalty_applied": any(
+                    rc.get("penalties", {}).get("shortcut") for rc in reward_components
+                ),
+                "documents_revealed": list(s.documents_revealed),
+                "actions_taken": list(s.actions_taken),
+                "reward_components": reward_components,
+                "wall_clock_s": round(elapsed, 2),
+            }
+        )
+        print(
+            f"  >> {result['task_id']:38s} "
+            f"score={result['grader_score']:.4f}  "
+            f"steps={result['steps']:>2}  "
+            f"decision={result.get('decision')}  "
+            f"({elapsed:.1f}s)",
+            flush=True,
+        )
+
+    total_elapsed = time.time() - t0
+    avg_score = (
+        sum(t["grader_score"] for t in per_task) / len(per_task) if per_task else 0.0
+    )
+    component_avgs = {
+        k: round(sum(t["components"][k] for t in per_task) / max(len(per_task), 1), 4)
+        for k in COMPONENT_KEYS
+    }
+    decision_correct = sum(
+        1 for t in per_task if t["components"]["decision_score"] >= 0.99
+    )
+
+    report = {
+        "schema_version": 1,
+        "slice": slice_name,
+        "model_tag": model_tag,
+        "model_name": MODEL_NAME,
+        "api_base_url": API_BASE_URL,
+        "started_at": started_at,
+        "wall_clock_s": round(total_elapsed, 2),
+        "n_tasks": len(per_task),
+        "summary": {
+            "avg_score": round(avg_score, 4),
+            "decision_correct": decision_correct,
+            "decision_correct_rate": round(decision_correct / max(len(per_task), 1), 4),
+            "component_avgs": component_avgs,
+            "shortcut_episodes": sum(
+                1 for t in per_task if t["shortcut_penalty_applied"]
+            ),
+        },
+        "tasks": per_task,
+    }
+
+    out_path = out_dir / f"{slice_name}__{model_tag}.json"
+    out_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+    print("-" * 70, flush=True)
+    print(f"Avg score:           {avg_score:.4f}", flush=True)
+    print(f"Decision correct:    {decision_correct}/{len(per_task)}", flush=True)
+    print(f"Component averages:  {component_avgs}", flush=True)
+    print(f"Wrote report:        {out_path}", flush=True)
+    print("=" * 70, flush=True)
+
+    return out_path
+
+
+def _compare(a_path: Path, b_path: Path) -> None:
+    a = json.loads(a_path.read_text(encoding="utf-8"))
+    b = json.loads(b_path.read_text(encoding="utf-8"))
+
+    print("=" * 78, flush=True)
+    print(f"COMPARE  A: {a_path.name}  ({a['model_tag']})", flush=True)
+    print(f"         B: {b_path.name}  ({b['model_tag']})", flush=True)
+    print("=" * 78, flush=True)
+
+    a_by = {t["task_id"]: t for t in a["tasks"]}
+    b_by = {t["task_id"]: t for t in b["tasks"]}
+    keys = list(a_by.keys())
+
+    print(f"{'task':40s} {'A':>7s} {'B':>7s} {'delta':>8s}", flush=True)
+    print("-" * 78, flush=True)
+    for k in keys:
+        if k not in b_by:
+            continue
+        sa = a_by[k]["grader_score"]
+        sb = b_by[k]["grader_score"]
+        d = sb - sa
+        marker = "  +" if d > 0.01 else ("  -" if d < -0.01 else "   ")
+        print(f"{k:40s} {sa:7.4f} {sb:7.4f} {d:+8.4f}{marker}", flush=True)
+
+    print("-" * 78, flush=True)
+    print(
+        f"{'AVERAGE':40s} {a['summary']['avg_score']:7.4f} "
+        f"{b['summary']['avg_score']:7.4f} "
+        f"{b['summary']['avg_score'] - a['summary']['avg_score']:+8.4f}",
+        flush=True,
+    )
+    for ck in COMPONENT_KEYS:
+        ac = a["summary"]["component_avgs"][ck]
+        bc = b["summary"]["component_avgs"][ck]
+        print(f"  {ck:38s} {ac:7.4f} {bc:7.4f} {bc - ac:+8.4f}", flush=True)
+    print("=" * 78, flush=True)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="InvoiceGuard Round 2 eval harness.")
+    p.add_argument("--slice", choices=["canonical", "hard", "all"], default="hard")
+    p.add_argument("--model-tag", default="baseline",
+                   help="Tag used in the output filename (e.g. baseline, trained, qwen3b-grpo).")
+    p.add_argument("--out-dir", type=Path, default=OUT_DIR_DEFAULT)
+    p.add_argument("--compare", nargs=2, metavar=("A", "B"), type=Path, default=None,
+                   help="Compare two report JSONs and print a delta table.")
+    args = p.parse_args()
+
+    if args.compare:
+        _compare(args.compare[0], args.compare[1])
+        return
+
+    if not API_KEY:
+        print(
+            "WARNING: no API key found in env (HF_TOKEN / API_KEY / OPENAI_API_KEY). "
+            "LLM calls will fail; this run will only verify the harness wiring.",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    if args.slice == "all":
+        _run_slice("canonical", args.model_tag, args.out_dir)
+        _run_slice("hard", args.model_tag, args.out_dir)
+    else:
+        _run_slice(args.slice, args.model_tag, args.out_dir)
+
+
+if __name__ == "__main__":
+    main()

graders/__init__.py

@@ -0,0 +1 @@
+from .scoring import grade_episode

graders/scoring.py

@@ -0,0 +1,279 @@
+"""
+Deterministic grading logic for InvoiceGuard episodes.
+
+Scores 0.0-1.0 with partial credit across six rubric dimensions:
+  - Final decision correctness  (0.35)
+  - Exception type correctness  (0.20)
+  - Evidence sufficiency         (0.15)
+  - Investigation quality        (0.10)
+  - Explanation quality          (0.10)
+  - Efficiency                   (0.10)
+"""
+
+import re
+from typing import List, Optional
+
+try:
+    from ..models import (
+        CaseData, DecisionType, ExceptionType, GraderResult, InvoiceGuardState,
+    )
+except ImportError:
+    from models import (
+        CaseData, DecisionType, ExceptionType, GraderResult, InvoiceGuardState,
+    )
+
+
+W_DECISION = 0.35
+W_EXCEPTION = 0.20
+W_EVIDENCE = 0.15
+W_INVESTIGATION = 0.10
+W_EXPLANATION = 0.10
+W_EFFICIENCY = 0.10
+
+
+def grade_episode(case: CaseData, env_state: InvoiceGuardState) -> GraderResult:
+    """
+    Grade a completed episode deterministically.
+
+    Returns a GraderResult with score in [0.0, 1.0] and rubric breakdown.
+    """
+    gt = case.ground_truth
+    breakdown = {}
+
+    # -- 1. Decision correctness (0.40) ----------------------------------
+    decision_score = 0.0
+    if env_state.final_decision:
+        agent_decision = env_state.final_decision
+        correct_decision = gt.correct_decision.value
+
+        if agent_decision == correct_decision:
+            decision_score = 1.0
+        else:
+            decision_score = _partial_decision_credit(
+                agent_decision, correct_decision
+            )
+    breakdown["decision"] = {
+        "agent": env_state.final_decision,
+        "correct": gt.correct_decision.value,
+        "score": decision_score,
+    }
+
+    # -- 2. Exception type correctness (0.20) ----------------------------
+    exception_score = 0.0
+    if env_state.final_exception_type:
+        if env_state.final_exception_type == gt.correct_exception_type.value:
+            exception_score = 1.0
+        elif env_state.proposed_exception == gt.correct_exception_type.value:
+            exception_score = 0.5
+    elif env_state.proposed_exception == gt.correct_exception_type.value:
+        exception_score = 0.3
+
+    breakdown["exception_type"] = {
+        "agent_final": env_state.final_exception_type,
+        "agent_proposed": env_state.proposed_exception,
+        "correct": gt.correct_exception_type.value,
+        "score": exception_score,
+    }
+
+    # -- 3. Evidence sufficiency (0.20) ----------------------------------
+    evidence_score = _score_evidence(
+        agent_evidence=env_state.final_evidence,
+        actions_taken=env_state.actions_taken,
+        acceptable_evidence=gt.acceptable_evidence,
+    )
+    breakdown["evidence"] = {
+        "agent_evidence": env_state.final_evidence,
+        "actions_taken": env_state.actions_taken,
+        "acceptable": gt.acceptable_evidence,
+        "score": evidence_score,
+    }
+
+    # -- 4. Investigation quality (0.10) ---------------------------------
+    investigation_score = _score_investigation(
+        actions_taken=env_state.actions_taken,
+        documents_revealed=env_state.documents_revealed,
+        acceptable_evidence=gt.acceptable_evidence,
+    )
+    breakdown["investigation"] = {
+        "documents_revealed": env_state.documents_revealed,
+        "score": investigation_score,
+    }
+
+    # -- 5. Explanation quality (0.10) -----------------------------------
+    explanation_score = _score_explanation(
+        explanation=env_state.final_explanation,
+        case=case,
+        key_findings=gt.key_findings,
+    )
+    breakdown["explanation"] = {
+        "explanation": env_state.final_explanation,
+        "score": explanation_score,
+    }
+
+    # -- 6. Efficiency (0.10) --------------------------------------------
+    efficiency_score = _score_efficiency(
+        steps_used=env_state.step_count,
+        max_steps=case.max_steps,
+        repeated_counts=env_state.repeated_action_counts,
+    )
+    breakdown["efficiency"] = {
+        "steps_used": env_state.step_count,
+        "max_steps": case.max_steps,
+        "repeated_actions": env_state.repeated_action_counts,
+        "score": efficiency_score,
+    }
+
+    # -- Weighted total --------------------------------------------------
+    total = (
+        W_DECISION * decision_score
+        + W_EXCEPTION * exception_score
+        + W_EVIDENCE * evidence_score
+        + W_INVESTIGATION * investigation_score
+        + W_EXPLANATION * explanation_score
+        + W_EFFICIENCY * efficiency_score
+    )
+    total = round(min(max(total, 0.0), 1.0), 4)
+
+    return GraderResult(
+        score=total,
+        decision_score=round(decision_score, 4),
+        exception_type_score=round(exception_score, 4),
+        evidence_score=round(evidence_score, 4),
+        investigation_score=round(investigation_score, 4),
+        explanation_score=round(explanation_score, 4),
+        efficiency_score=round(efficiency_score, 4),
+        breakdown=breakdown,
+    )
+
+
+def _partial_decision_credit(agent: str, correct: str) -> float:
+    """
+    Give partial credit for 'close' but wrong decisions.
+    e.g. escalate when hold was correct is better than approve when hold was correct.
+    """
+    RELATED_DECISIONS = {
+        "place_on_hold": {"escalate_for_supervisor_review": 0.2, "reject_invoice": 0.15},
+        "escalate_for_supervisor_review": {"place_on_hold": 0.2, "reject_invoice": 0.15},
+        "reject_invoice": {"escalate_for_supervisor_review": 0.2, "place_on_hold": 0.1},
+        "approve_for_payment": {},
+    }
+    related = RELATED_DECISIONS.get(correct, {})
+    return related.get(agent, 0.0)
+
+
+def _score_evidence(
+    agent_evidence: List[str],
+    actions_taken: List[str],
+    acceptable_evidence: List[str],
+) -> float:
+    if not acceptable_evidence:
+        return 1.0
+
+    cited_set = set(agent_evidence)
+    taken_set = set(actions_taken)
+    total = 0.0
+
+    for required in acceptable_evidence:
+        if required in cited_set:
+            total += 1.0
+        elif required in taken_set:
+            total += 0.7
+
+    return min(total / len(acceptable_evidence), 1.0)
+
+
+def _score_investigation(
+    actions_taken: List[str],
+    documents_revealed: List[str],
+    acceptable_evidence: List[str],
+) -> float:
+    if not acceptable_evidence:
+        return 1.0
+
+    relevant_actions = 0
+    for action in actions_taken:
+        if action in acceptable_evidence:
+            relevant_actions += 1
+
+    coverage = min(relevant_actions / len(acceptable_evidence), 1.0)
+
+    doc_bonus = min(len(documents_revealed) * 0.15, 0.3)
+
+    return min(coverage + doc_bonus, 1.0)
+
+
+def _score_explanation(
+    explanation: str,
+    case: CaseData,
+    key_findings: List[str],
+) -> float:
+    """Score the agent's final explanation for quality signals."""
+    if not explanation:
+        return 0.0
+
+    text = explanation.lower()
+    score = 0.0
+    checks = 0
+    hits = 0
+
+    checks += 1
+    if _contains_number(text):
+        hits += 1
+
+    checks += 1
+    policy_terms = ["policy", "tolerance", "threshold", "escalat", "within"]
+    if any(t in text for t in policy_terms):
+        hits += 1
+
+    checks += 1
+    decision_terms = [
+        "approve", "reject", "hold", "escalat", "duplicate",
+        "mismatch", "variance", "discrepancy", "match",
+    ]
+    if any(t in text for t in decision_terms):
+        hits += 1
+
+    checks += 1
+    if len(explanation.split()) >= 8:
+        hits += 1
+
+    checks += 1
+    finding_hits = 0
+    for kf in key_findings:
+        kf_words = set(kf.lower().split())
+        if len(kf_words.intersection(set(text.split()))) >= 2:
+            finding_hits += 1
+    if finding_hits > 0:
+        hits += 1
+
+    score = hits / checks if checks > 0 else 0.0
+    return round(min(score, 1.0), 4)
+
+
+def _contains_number(text: str) -> bool:
+    return bool(re.search(r'\d+\.?\d*', text))
+
+
+def _score_efficiency(
+    steps_used: int,
+    max_steps: int,
+    repeated_counts: dict,
+) -> float:
+    if max_steps == 0:
+        return 1.0
+
+    step_ratio = steps_used / max_steps
+    total_repeats = sum(max(0, v - 1) for v in repeated_counts.values())
+
+    if step_ratio <= 0.5:
+        base = 1.0
+    elif step_ratio <= 0.75:
+        base = 0.8
+    elif step_ratio <= 1.0:
+        base = 0.5
+    else:
+        base = 0.2
+
+    repeat_penalty = min(total_repeats * 0.1, 0.4)
+
+    return max(base - repeat_penalty, 0.0)

inference.py

@@ -0,0 +1,506 @@
+"""
+InvoiceGuard -- Baseline Inference Script.
+
+Runs a baseline LLM agent against all canonical tasks and reports per-task
+and overall grader scores. Uses the OpenAI API client as required by
+the hackathon guidelines.
+
+STDOUT FORMAT (mandatory):
+    [START] task=<task_name> env=invoice_guard model=<model_name>
+    [STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+    [END]   success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...,rn>
+
+Environment variables (mandatory):
+    API_BASE_URL       -- LLM API endpoint (default: https://api.openai.com/v1)
+    MODEL_NAME         -- model identifier (default: gpt-4.1-mini)
+    HF_TOKEN           -- Your Hugging Face / API key
+    LOCAL_IMAGE_NAME   -- Docker image name (uses from_docker_image when set)
+"""
+
+import asyncio
+import json
+import os
+import sys
+import time
+from typing import List, Optional
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+_MODELS_USING_MAX_COMPLETION_TOKENS = {"gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano",
+                                        "gpt-5", "gpt-5-mini", "gpt-5.1"}
+
+
+def _token_limit_kwarg(model_name: str, limit: int = 512) -> dict:
+    """Return the correct token-limit parameter for the model."""
+    for prefix in _MODELS_USING_MAX_COMPLETION_TOKENS:
+        if model_name.startswith(prefix):
+            return {"max_completion_tokens": limit}
+    return {"max_tokens": limit}
+
+from models import (
+    ActionType, DecisionType, ExceptionType, InvoiceGuardAction, TaskID,
+)
+from tasks import get_task_case, TASK_LIST
+
+load_dotenv()
+
+API_BASE_URL = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4.1-mini")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY") or os.getenv("OPENAI_API_KEY") or ""
+LOCAL_IMAGE_NAME = os.getenv("LOCAL_IMAGE_NAME")
+
+BENCHMARK = "invoice_guard"
+
+
+# -- Mandatory stdout logging --------------------------------------------
+
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error if error else "null"
+    done_val = str(done).lower()
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.2f} "
+        f"done={done_val} error={error_val}",
+        flush=True,
+    )
+
+
+def log_end(success: bool, steps: int, score: float, rewards: List[float]) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} "
+        f"score={score:.2f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# -- System prompt --------------------------------------------------------
+
+
+SYSTEM_PROMPT = """You are a senior accounts payable analyst. You will be given an invoice case to investigate and resolve.
+
+The environment tells you your goal, available actions, and decision options. Read the goal carefully.
+
+WORKFLOW:
+1. Investigate: inspect documents (PO, GRN, vendor profile, policy rules), run comparisons (quantity, price, totals), check for duplicates.
+2. Resolve: submit_final_resolution with your decision, exception type, evidence references, and explanation.
+
+Complete a thorough investigation before resolving. Inspect at least: purchase order, goods receipt note, compare quantity, compare price, policy rules, duplicate check, and vendor profile.
+
+RESPONSE FORMAT:
+- Respond with ONLY a valid JSON object. No markdown, no commentary.
+- Investigation example: {"action_type": "inspect_purchase_order"}
+- Resolution example: {"action_type": "submit_final_resolution", "final_decision": "approve_for_payment", "exception_type": "clean_match", "evidence_references": ["inspect_purchase_order", "compare_quantity"], "explanation": "All documents match within tolerance.", "confidence": 0.9}
+
+EXCEPTION TYPE OPTIONS:
+- clean_match: all documents match within tolerance
+- quantity_mismatch: billed quantity exceeds ordered quantity
+- price_mismatch: billed unit price exceeds PO-agreed price
+- total_amount_mismatch: invoice subtotal/total math is inconsistent
+- partial_receipt: invoice bills more than has been received
+- missing_receipt: no valid GRN supports the invoice/period
+- duplicate_invoice: same invoice or already-paid duplicate detected
+- tax_variance: tax amount differs from policy or expected value
+- policy_violation: policy requires hold/escalation despite matching docs
+- mixed_discrepancy: multiple material exception types are present
+
+RULES:
+- Pay close attention to POLICY findings -- they tell you when escalation is required.
+- When multiple issues exist, escalation takes priority over hold.
+- Check PO references carefully before concluding an invoice is a duplicate.
+- Include all investigation actions you performed in evidence_references.
+- Cite specific numbers in your explanation.
+- NEVER repeat an action you already took.
+- When remaining_steps is 3 or fewer, submit immediately with what you have.
+"""
+
+
+# -- Prompt building ------------------------------------------------------
+
+
+def build_observation_prompt(obs, is_first: bool = False) -> str:
+    """Format observation as a readable prompt for the LLM."""
+    parts = [
+        f"Case: {obs.case_id} | Difficulty: {obs.difficulty} | Steps remaining: {obs.remaining_steps}",
+        f"Invoice: {obs.invoice_summary}",
+    ]
+
+    if is_first and obs.goal:
+        parts.append(f"\n{obs.goal}")
+
+    if obs.revealed_documents:
+        parts.append(f"Documents reviewed: {', '.join(obs.revealed_documents)}")
+
+    if obs.findings:
+        parts.append("Findings:")
+        for i, f in enumerate(obs.findings, 1):
+            parts.append(f"  {i}. {f}")
+
+    if obs.last_action_result:
+        parts.append(f"Last result: {obs.last_action_result}")
+
+    if obs.warnings:
+        parts.append(f"Warnings: {'; '.join(obs.warnings)}")
+
+    if obs.remaining_steps <= 2:
+        parts.append(
+            ">>> YOU MUST submit_final_resolution NOW. "
+            "No more investigation. Decide based on what you have. <<<"
+        )
+
+    return "\n".join(parts)
+
+
+# -- LLM response parsing ------------------------------------------------
+
+
+def parse_llm_response(response_text: str) -> dict:
+    """Extract a JSON object from the LLM response."""
+    text = response_text.strip()
+
+    if "```json" in text:
+        text = text.split("```json")[1].split("```")[0].strip()
+    elif "```" in text:
+        text = text.split("```")[1].split("```")[0].strip()
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    for line in text.split("\n"):
+        line = line.strip()
+        if line.startswith("{"):
+            try:
+                return json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+    return {"action_type": "summarize_findings"}
+
+
+def build_action(params: dict) -> InvoiceGuardAction:
+    """Build a typed InvoiceGuardAction from parsed LLM output."""
+    action_type = params.get("action_type", "summarize_findings")
+
+    try:
+        ActionType(action_type)
+    except ValueError:
+        action_type = "summarize_findings"
+
+    kwargs = {"action_type": action_type}
+
+    if params.get("final_decision"):
+        try:
+            kwargs["final_decision"] = DecisionType(params["final_decision"])
+        except ValueError:
+            pass
+
+    if params.get("exception_type"):
+        try:
+            kwargs["exception_type"] = ExceptionType(params["exception_type"])
+        except ValueError:
+            pass
+
+    if params.get("evidence_references"):
+        kwargs["evidence_references"] = list(params["evidence_references"])
+
+    if params.get("explanation"):
+        kwargs["explanation"] = str(params["explanation"])
+
+    if params.get("confidence") is not None:
+        try:
+            conf = float(params["confidence"])
+            if 0.0 <= conf <= 1.0:
+                kwargs["confidence"] = conf
+        except (ValueError, TypeError):
+            pass
+
+    return InvoiceGuardAction(**kwargs)
+
+
+# -- Observation extraction helpers ---------------------------------------
+
+
+def _obs_from_step_result(result):
+    """Extract observation from an EnvClient StepResult, copying reward/done."""
+    obs = result.observation
+    obs.reward = result.reward
+    obs.done = result.done
+    return obs
+
+
+# -- Episode runner (local, synchronous) ----------------------------------
+
+
+def run_episode_local(env, client: OpenAI, task_id: TaskID) -> dict:
+    """Run one full episode against the local environment."""
+    obs = env.reset(task_id=task_id.value)
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    rewards: List[float] = []
+    steps = 0
+    score = 0.0
+    success = False
+    last_decision = None
+    last_exception = None
+
+    log_start(task=task_id.value, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        while not obs.done:
+            user_msg = build_observation_prompt(obs, is_first=(steps == 0))
+            messages.append({"role": "user", "content": user_msg})
+
+            try:
+                api_kwargs = {
+                    "model": MODEL_NAME,
+                    "messages": messages,
+                    "temperature": 0.0,
+                    **_token_limit_kwarg(MODEL_NAME),
+                }
+                try:
+                    api_kwargs["response_format"] = {"type": "json_object"}
+                    response = client.chat.completions.create(**api_kwargs)
+                except Exception:
+                    del api_kwargs["response_format"]
+                    response = client.chat.completions.create(**api_kwargs)
+
+                assistant_msg = response.choices[0].message.content or ""
+
+            except Exception as e:
+                print(f"[DEBUG] LLM API error: {e}", flush=True)
+                assistant_msg = '{"action_type": "summarize_findings"}'
+
+            messages.append({"role": "assistant", "content": assistant_msg})
+
+            params = parse_llm_response(assistant_msg)
+            if params.get("final_decision"):
+                last_decision = params["final_decision"]
+            if params.get("exception_type"):
+                last_exception = params["exception_type"]
+            action = build_action(params)
+
+            obs = env.step(action)
+            reward = obs.reward if obs.reward else 0.0
+            rewards.append(reward)
+            steps += 1
+
+            error_str = None
+            if obs.last_action_error:
+                error_str = obs.last_action_result
+
+            log_step(
+                step=steps,
+                action=action.action_type.value,
+                reward=reward,
+                done=obs.done,
+                error=error_str,
+            )
+
+        grader_data = getattr(obs, "grader_result", None) or obs.metadata.get("grader_result", {})
+        score = grader_data.get("score", 0.0) if isinstance(grader_data, dict) else 0.0
+        score = min(max(score, 0.0), 1.0)
+        success = score >= 0.5
+
+    finally:
+        log_end(success=success, steps=steps, score=score, rewards=rewards)
+
+    return {
+        "task_id": task_id.value,
+        "steps": steps,
+        "grader_score": score,
+        "total_reward": sum(rewards),
+        "rewards": rewards,
+        "decision": last_decision,
+        "exception_type": last_exception,
+        "grader_breakdown": grader_data,
+    }
+
+
+# -- Episode runner (Docker, asynchronous) --------------------------------
+
+
+async def run_episode_docker(env, client: OpenAI, task_id: TaskID) -> dict:
+    """Run one full episode against a Docker-based environment via EnvClient."""
+    result = await env.reset(task_id=task_id.value)
+    obs = _obs_from_step_result(result)
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    rewards: List[float] = []
+    steps = 0
+    score = 0.0
+    success = False
+    last_decision = None
+    last_exception = None
+
+    log_start(task=task_id.value, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        while not obs.done:
+            user_msg = build_observation_prompt(obs, is_first=(steps == 0))
+            messages.append({"role": "user", "content": user_msg})
+
+            try:
+                api_kwargs = {
+                    "model": MODEL_NAME,
+                    "messages": messages,
+                    "temperature": 0.0,
+                    **_token_limit_kwarg(MODEL_NAME),
+                }
+                try:
+                    api_kwargs["response_format"] = {"type": "json_object"}
+                    response = client.chat.completions.create(**api_kwargs)
+                except Exception:
+                    del api_kwargs["response_format"]
+                    response = client.chat.completions.create(**api_kwargs)
+
+                assistant_msg = response.choices[0].message.content or ""
+
+            except Exception as e:
+                print(f"[DEBUG] LLM API error: {e}", flush=True)
+                assistant_msg = '{"action_type": "summarize_findings"}'
+
+            messages.append({"role": "assistant", "content": assistant_msg})
+
+            params = parse_llm_response(assistant_msg)
+            if params.get("final_decision"):
+                last_decision = params["final_decision"]
+            if params.get("exception_type"):
+                last_exception = params["exception_type"]
+            action = build_action(params)
+
+            result = await env.step(action)
+            obs = _obs_from_step_result(result)
+            reward = obs.reward if obs.reward else 0.0
+            rewards.append(reward)
+            steps += 1
+
+            error_str = None
+            if obs.last_action_error:
+                error_str = obs.last_action_result
+
+            log_step(
+                step=steps,
+                action=action.action_type.value,
+                reward=reward,
+                done=obs.done,
+                error=error_str,
+            )
+
+        grader_data = getattr(obs, "grader_result", None) or obs.metadata.get("grader_result", {})
+        score = grader_data.get("score", 0.0) if isinstance(grader_data, dict) else 0.0
+        score = min(max(score, 0.0), 1.0)
+        success = score >= 0.5
+
+    finally:
+        log_end(success=success, steps=steps, score=score, rewards=rewards)
+
+    return {
+        "task_id": task_id.value,
+        "steps": steps,
+        "grader_score": score,
+        "total_reward": sum(rewards),
+        "rewards": rewards,
+        "decision": last_decision,
+        "exception_type": last_exception,
+        "grader_breakdown": grader_data,
+    }
+
+
+# -- Main -----------------------------------------------------------------
+
+
+def _print_header():
+    print("=" * 60, flush=True)
+    print("InvoiceGuard -- Baseline Inference", flush=True)
+    print("=" * 60, flush=True)
+    print(f"API Base URL: {API_BASE_URL}", flush=True)
+    print(f"Model:        {MODEL_NAME}", flush=True)
+    print(f"Tasks:        {len(TASK_LIST)}", flush=True)
+    mode = f"docker ({LOCAL_IMAGE_NAME})" if LOCAL_IMAGE_NAME else "local"
+    print(f"Mode:         {mode}", flush=True)
+    print(flush=True)
+
+
+def _print_results(results):
+    print(flush=True)
+    print("=" * 60, flush=True)
+    print("RESULTS SUMMARY", flush=True)
+    print("=" * 60, flush=True)
+    scores = [r["grader_score"] for r in results]
+    for r in results:
+        print(
+            f"  {r['task_id']:30s}  score={r['grader_score']:.4f}  "
+            f"decision={r['decision']}",
+            flush=True,
+        )
+    avg = sum(scores) / len(scores) if scores else 0.0
+    print(f"\n  Average score: {avg:.4f}", flush=True)
+    print(f"  Total tasks:   {len(scores)}", flush=True)
+    print("=" * 60, flush=True)
+
+
+async def main_docker():
+    """Run inference against a Docker container via EnvClient."""
+    from client import InvoiceGuardEnv
+
+    _print_header()
+    llm_client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+
+    env = await InvoiceGuardEnv.from_docker_image(LOCAL_IMAGE_NAME)
+
+    results = []
+    try:
+        for task_id in TASK_LIST:
+            start = time.time()
+            result = await run_episode_docker(env, llm_client, task_id)
+            elapsed = time.time() - start
+            print(
+                f"  >> {task_id.value}: score={result['grader_score']:.4f} "
+                f"steps={result['steps']} decision={result['decision']} "
+                f"time={elapsed:.1f}s",
+                flush=True,
+            )
+            results.append(result)
+    finally:
+        try:
+            await env.close()
+        except Exception as e:
+            print(f"[DEBUG] env.close() error: {e}", flush=True)
+
+    _print_results(results)
+
+
+def main_local():
+    """Run inference directly against the local environment."""
+    from server.invoice_guard_environment import InvoiceGuardEnvironment
+
+    _print_header()
+    llm_client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    env = InvoiceGuardEnvironment()
+
+    results = []
+    for task_id in TASK_LIST:
+        start = time.time()
+        result = run_episode_local(env, llm_client, task_id)
+        elapsed = time.time() - start
+        print(
+            f"  >> {task_id.value}: score={result['grader_score']:.4f} "
+            f"steps={result['steps']} decision={result['decision']} "
+            f"time={elapsed:.1f}s",
+            flush=True,
+        )
+        results.append(result)
+
+    _print_results(results)
+
+
+if __name__ == "__main__":
+    if LOCAL_IMAGE_NAME:
+        asyncio.run(main_docker())
+    else:
+        main_local()

models.py

@@ -0,0 +1,287 @@
+"""
+Data models for the InvoiceGuard environment.
+
+Three-Way Invoice Matching Exception Resolution Environment.
+All enums, business entities, and OpenEnv interface types.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from openenv.core.env_server.types import Action, Observation, State
+
+
+# -- Enums --------------------------------------------------------------------
+
+
+class ActionType(str, Enum):
+    """Available actions the agent can take."""
+
+    inspect_invoice_line_items = "inspect_invoice_line_items"
+    inspect_purchase_order = "inspect_purchase_order"
+    inspect_goods_receipt_note = "inspect_goods_receipt_note"
+    inspect_vendor_profile = "inspect_vendor_profile"
+    inspect_policy_rules = "inspect_policy_rules"
+    check_for_duplicate_invoice = "check_for_duplicate_invoice"
+    compare_quantity = "compare_quantity"
+    compare_price = "compare_price"
+    compare_totals = "compare_totals"
+    summarize_findings = "summarize_findings"
+    propose_exception_type = "propose_exception_type"
+    submit_final_resolution = "submit_final_resolution"
+
+
+class DecisionType(str, Enum):
+    """Final case resolution decisions."""
+
+    approve_for_payment = "approve_for_payment"
+    place_on_hold = "place_on_hold"
+    reject_invoice = "reject_invoice"
+    escalate_for_supervisor_review = "escalate_for_supervisor_review"
+
+
+class ExceptionType(str, Enum):
+    """Primary exception types for invoice cases."""
+
+    clean_match = "clean_match"
+    quantity_mismatch = "quantity_mismatch"
+    price_mismatch = "price_mismatch"
+    total_amount_mismatch = "total_amount_mismatch"
+    partial_receipt = "partial_receipt"
+    missing_receipt = "missing_receipt"
+    duplicate_invoice = "duplicate_invoice"
+    tax_variance = "tax_variance"
+    policy_violation = "policy_violation"
+    mixed_discrepancy = "mixed_discrepancy"
+
+
+class TaskID(str, Enum):
+    """Identifiers for evaluation tasks (4 canonical + variants)."""
+
+    task_1_clean_match = "task_1_clean_match"
+    task_1b_multi_line_clean = "task_1b_multi_line_clean"
+    task_1c_preferred_vendor_clean = "task_1c_preferred_vendor_clean"
+    task_2_partial_receipt = "task_2_partial_receipt"
+    task_2b_missing_receipt = "task_2b_missing_receipt"
+    task_2c_over_receipt = "task_2c_over_receipt"
+    task_3_price_variance = "task_3_price_variance"
+    task_3b_within_tolerance = "task_3b_within_tolerance"
+    task_3c_total_mismatch = "task_3c_total_mismatch"
+    task_4_duplicate_invoice = "task_4_duplicate_invoice"
+    task_4b_corrected_invoice_trap = "task_4b_corrected_invoice_trap"
+    task_4c_policy_violation = "task_4c_policy_violation"
+    task_5_mixed_discrepancy = "task_5_mixed_discrepancy"
+    task_6_false_positive_duplicate = "task_6_false_positive_duplicate"
+    task_7_retroactive_price = "task_7_retroactive_price"
+    task_8_split_invoice_pattern = "task_8_split_invoice_pattern"
+    task_9_clean_from_risky_vendor = "task_9_clean_from_risky_vendor"
+    task_10_rounding_false_alarm = "task_10_rounding_false_alarm"
+    task_11_authorized_overship = "task_11_authorized_overship"
+    task_12_corrected_resubmission = "task_12_corrected_resubmission"
+    # -- Round 2 hard-mode slice (strong gap, baseline target 40-55%) --
+    task_h1_phantom_grn_period = "task_h1_phantom_grn_period"
+    task_h2_kickback_inflated_po = "task_h2_kickback_inflated_po"
+    task_h3_currency_silent_swap = "task_h3_currency_silent_swap"
+    task_h4_threshold_dance = "task_h4_threshold_dance"
+    task_h5_retroactive_amendment = "task_h5_retroactive_amendment"
+    task_h6_returned_then_rebilled = "task_h6_returned_then_rebilled"
+    task_h7_multi_party_pending = "task_h7_multi_party_pending"
+    task_h8_rush_premium_authorized = "task_h8_rush_premium_authorized"
+    task_h9_supplier_id_mismatch = "task_h9_supplier_id_mismatch"
+    task_h10_cross_case_contradiction = "task_h10_cross_case_contradiction"
+
+
+class Difficulty(str, Enum):
+    """Task difficulty levels."""
+
+    easy = "easy"
+    moderate = "moderate"
+    hard = "hard"
+
+
+# -- Business Entities --------------------------------------------------------
+
+
+class InvoiceLineItem(BaseModel):
+    item_code: str
+    description: str
+    quantity_billed: float
+    unit_price_billed: float
+    line_total_billed: float
+
+
+class Invoice(BaseModel):
+    invoice_number: str
+    supplier_name: str
+    supplier_id: str
+    invoice_date: str
+    currency: str = "USD"
+    po_reference: str
+    line_items: List[InvoiceLineItem]
+    subtotal: float
+    tax: float
+    total_amount: float
+    note: str = ""
+
+
+class POLineItem(BaseModel):
+    item_code: str
+    description: str
+    ordered_quantity: float
+    unit_price_ordered: float
+    line_total_ordered: float
+
+
+class PurchaseOrder(BaseModel):
+    po_number: str
+    supplier_id: str
+    order_date: str
+    line_items: List[POLineItem]
+    approved: bool = True
+    payment_terms: str = "Net 30"
+
+
+class GRNLineItem(BaseModel):
+    item_code: str
+    quantity_received: float
+    accepted_quantity: float
+    rejected_quantity: float = 0.0
+
+
+class GoodsReceiptNote(BaseModel):
+    grn_number: str
+    po_reference: str
+    receipt_date: str
+    line_items: List[GRNLineItem]
+    warehouse_note: str = ""
+
+
+class VendorProfile(BaseModel):
+    supplier_id: str
+    supplier_name: str
+    risk_tier: str
+    duplicate_risk_count: int = 0
+    preferred_vendor: bool = True
+    tolerance_override: Optional[float] = None
+    escalation_threshold: Optional[float] = None
+
+
+class CompanyPolicy(BaseModel):
+    quantity_tolerance_pct: float = 5.0
+    price_tolerance_pct: float = 5.0
+    total_tolerance_amt: float = 100.0
+    duplicate_check_enabled: bool = True
+    high_value_threshold: float = 50000.0
+    mandatory_escalation_above: float = 100000.0
+
+
+class CaseHistory(BaseModel):
+    prior_comments: List[str] = Field(default_factory=list)
+    similar_invoice_refs: List[str] = Field(default_factory=list)
+    processed_invoice_numbers: List[str] = Field(default_factory=list)
+    pending_invoice_numbers: List[str] = Field(default_factory=list)
+
+
+# -- Ground Truth & Case Data ------------------------------------------------
+
+
+class GroundTruth(BaseModel):
+    correct_decision: DecisionType
+    correct_exception_type: ExceptionType
+    acceptable_evidence: List[str]
+    key_findings: List[str]
+
+
+class CaseData(BaseModel):
+    case_id: str
+    task_id: TaskID
+    difficulty: Difficulty
+    max_steps: int
+    invoice: Invoice
+    purchase_order: PurchaseOrder
+    goods_receipt_note: GoodsReceiptNote
+    vendor_profile: VendorProfile
+    company_policy: CompanyPolicy
+    case_history: CaseHistory
+    ground_truth: GroundTruth
+
+
+# -- OpenEnv Action ----------------------------------------------------------
+
+
+class InvoiceGuardAction(Action):
+    """Agent action for the InvoiceGuard environment."""
+
+    action_type: ActionType
+    final_decision: Optional[DecisionType] = None
+    exception_type: Optional[ExceptionType] = None
+    evidence_references: List[str] = Field(default_factory=list)
+    explanation: str = ""
+    confidence: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+
+
+# -- OpenEnv Observation -----------------------------------------------------
+
+
+class InvoiceGuardObservation(Observation):
+    """What the agent sees after each step."""
+
+    case_id: str = ""
+    task_id: str = ""
+    difficulty: str = ""
+    invoice_summary: str = ""
+    goal: str = ""
+    available_actions: List[str] = Field(default_factory=list)
+    suggested_next_actions: List[str] = Field(default_factory=list)
+    revealed_documents: List[str] = Field(default_factory=list)
+    findings: List[str] = Field(default_factory=list)
+    remaining_steps: int = 0
+    last_action_result: str = ""
+    last_action_error: bool = False
+    warnings: List[str] = Field(default_factory=list)
+    grader_result: Dict[str, Any] = Field(default_factory=dict)
+
+
+# -- OpenEnv State -----------------------------------------------------------
+
+
+class InvoiceGuardState(State):
+    """Internal state tracking for the environment."""
+
+    task_id: str = ""
+    difficulty: str = ""
+    case_id: str = ""
+    max_steps: int = 0
+    actions_taken: List[str] = Field(default_factory=list)
+    documents_revealed: List[str] = Field(default_factory=list)
+    findings_collected: List[str] = Field(default_factory=list)
+    proposed_exception: Optional[str] = None
+    is_finalized: bool = False
+    final_decision: Optional[str] = None
+    final_exception_type: Optional[str] = None
+    final_evidence: List[str] = Field(default_factory=list)
+    final_explanation: str = ""
+    final_confidence: Optional[float] = None
+    cumulative_reward: float = 0.0
+    repeated_action_counts: Dict[str, int] = Field(default_factory=dict)
+    # Per-step reward components for transparency / training signals.
+    # Each entry: {step, action, base, penalties: {kind: amount, ...}, total, reason}
+    reward_components: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+# -- Grader Result -----------------------------------------------------------
+
+
+class GraderResult(BaseModel):
+    """Deterministic grading result for a completed episode."""
+
+    score: float = Field(ge=0.0, le=1.0)
+    decision_score: float = 0.0
+    exception_type_score: float = 0.0
+    evidence_score: float = 0.0
+    investigation_score: float = 0.0
+    explanation_score: float = 0.0
+    efficiency_score: float = 0.0
+    breakdown: Dict[str, Any] = Field(default_factory=dict)

openenv.yaml

@@ -0,0 +1,8 @@
+spec_version: 1
+name: invoice_guard
+description: Three-way invoice matching exception resolution environment. An AI agent investigates multi-document AP cases to detect discrepancies and render policy-compliant decisions.
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

pyproject.toml

@@ -0,0 +1,38 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-invoice_guard"
+version = "0.1.0"
+description = "Invoice Guard environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core[core]>=0.2.1",
+    "openai>=1.0.0",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m invoice_guard.server.app
+server = "invoice_guard.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["invoice_guard", "invoice_guard.server"]
+package-dir = { "invoice_guard" = ".", "invoice_guard.server" = "server" }

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Invoice Guard environment server components."""
+
+from .invoice_guard_environment import InvoiceGuardEnvironment
+
+__all__ = ["InvoiceGuardEnvironment"]

server/app.py

@@ -0,0 +1,43 @@
+"""
+FastAPI application for the InvoiceGuard Environment.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:
+    raise ImportError(
+        "openenv is required. Install with: uv sync"
+    ) from e
+
+try:
+    from ..models import InvoiceGuardAction, InvoiceGuardObservation
+    from .invoice_guard_environment import InvoiceGuardEnvironment
+except (ImportError, ModuleNotFoundError):
+    from models import InvoiceGuardAction, InvoiceGuardObservation
+    from server.invoice_guard_environment import InvoiceGuardEnvironment
+
+
+app = create_app(
+    InvoiceGuardEnvironment,
+    InvoiceGuardAction,
+    InvoiceGuardObservation,
+    env_name="invoice_guard",
+    max_concurrent_envs=1,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """Entry point for uv run server."""
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/invoice_guard_environment.py

@@ -0,0 +1,869 @@
+"""
+InvoiceGuard Environment -- Three-Way Invoice Matching Exception Resolution.
+
+An agent reviews one supplier invoice case per episode by comparing the
+invoice, purchase order, and goods receipt note, then resolves the case.
+"""
+
+from typing import Any, Optional
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import (
+        ActionType, CaseData, DecisionType, Difficulty, ExceptionType,
+        InvoiceGuardAction, InvoiceGuardObservation, InvoiceGuardState, TaskID,
+    )
+    from ..tasks import get_task_case, TASK_LIST
+    from ..graders import grade_episode
+except ImportError:
+    from models import (
+        ActionType, CaseData, DecisionType, Difficulty, ExceptionType,
+        InvoiceGuardAction, InvoiceGuardObservation, InvoiceGuardState, TaskID,
+    )
+    from tasks import get_task_case, TASK_LIST
+    from graders import grade_episode
+
+
+GOAL_TEXT = (
+    "You are an accounts payable analyst. Review this supplier invoice by "
+    "comparing it against the purchase order (PO) and goods receipt note (GRN).\n"
+    "\n"
+    "INVESTIGATION ACTIONS (reveal information):\n"
+    "  inspect_purchase_order -- see what was ordered and at what price\n"
+    "  inspect_goods_receipt_note -- see what was received at the warehouse\n"
+    "  inspect_invoice_line_items -- see detailed invoice line items\n"
+    "  inspect_vendor_profile -- see vendor risk tier, duplicate history, escalation thresholds\n"
+    "  inspect_policy_rules -- see company tolerance thresholds and escalation rules\n"
+    "  check_for_duplicate_invoice -- search for previously processed invoices\n"
+    "  compare_quantity -- compare billed vs ordered vs received quantities\n"
+    "  compare_price -- compare billed price vs PO-agreed price\n"
+    "  compare_totals -- verify subtotal and total consistency\n"
+    "  summarize_findings -- list all findings collected so far\n"
+    "  propose_exception_type -- declare what type of exception you suspect\n"
+    "\n"
+    "RESOLUTION ACTION (ends the episode):\n"
+    "  submit_final_resolution -- requires: final_decision, exception_type, "
+    "evidence_references, explanation\n"
+    "\n"
+    "DECISIONS:\n"
+    "  reject_invoice -- duplicate invoice or fraudulent submission detected\n"
+    "  escalate_for_supervisor_review -- price/total variance exceeds tolerance, "
+    "or invoice exceeds high-value threshold\n"
+    "  place_on_hold -- billed quantity exceeds received quantity\n"
+    "  approve_for_payment -- all documents match within tolerance\n"
+    "\n"
+    "Investigate thoroughly, then submit your resolution with evidence."
+)
+
+ALL_ACTIONS = [a.value for a in ActionType]
+
+# Reward constants
+R_NEW_DOCUMENT = 0.05
+R_USEFUL_COMPARISON = 0.08
+R_CONFIRM_NO_ISSUE = 0.03
+R_CORRECT_PROPOSAL = 0.10
+R_SUMMARIZE = 0.02
+R_REPEAT_PENALTY = -0.02
+R_INVALID_ACTION = -0.05
+R_TIMEOUT_PENALTY = -0.10
+
+# -- Round 2 anti-gaming constants ------------------------------------------
+# Submitting a final resolution before doing any real investigation is a
+# common shortcut. Penalize it heavily so RL training cannot exploit it.
+R_SHORTCUT_PENALTY = -0.20
+# Minimum distinct documents the agent must have revealed before submit
+# is considered "investigated". Below this, R_SHORTCUT_PENALTY applies.
+MIN_DOCS_BEFORE_SUBMIT = 2
+# Escalating per-action repeat penalty (applied AFTER the first occurrence).
+# index 0 = first repeat (= 2nd occurrence overall), 1 = 2nd repeat, etc.
+REPEAT_PENALTY_LADDER = [-0.02, -0.05, -0.10, -0.15]
+
+
+def _ladder_penalty(repeat_idx: int) -> float:
+    """Return escalating repeat penalty; clamps to last rung."""
+    if repeat_idx <= 0:
+        return 0.0
+    i = min(repeat_idx - 1, len(REPEAT_PENALTY_LADDER) - 1)
+    return REPEAT_PENALTY_LADDER[i]
+
+
+class InvoiceGuardEnvironment(Environment):
+    """
+    Three-Way Invoice Matching Exception Resolution Environment.
+
+    Each episode presents one synthetic invoice case. The agent investigates
+    by inspecting documents and comparing fields, then submits a resolution.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        self._case: Optional[CaseData] = None
+        self._env_state = InvoiceGuardState()
+        self._task_index = 0
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> InvoiceGuardObservation:
+        task_id_str = kwargs.get("task_id")
+        if task_id_str:
+            task_id = TaskID(task_id_str)
+        else:
+            task_id = TASK_LIST[self._task_index % len(TASK_LIST)]
+            self._task_index += 1
+
+        self._case = get_task_case(task_id)
+        c = self._case
+
+        self._env_state = InvoiceGuardState(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+            task_id=c.task_id.value,
+            difficulty=c.difficulty.value,
+            case_id=c.case_id,
+            max_steps=c.max_steps,
+        )
+
+        inv = c.invoice
+        summary = (
+            f"Supplier: {inv.supplier_name} ({inv.supplier_id}), "
+            f"Invoice: {inv.invoice_number}, Date: {inv.invoice_date}, "
+            f"PO Ref: {inv.po_reference}, Total: ${inv.total_amount:,.2f}"
+        )
+        if inv.note:
+            summary += f"\nInvoice note: {inv.note}"
+
+        initial_suggestions = [
+            "inspect_purchase_order",
+            "inspect_goods_receipt_note",
+            "inspect_invoice_line_items",
+        ]
+
+        return InvoiceGuardObservation(
+            case_id=c.case_id,
+            task_id=c.task_id.value,
+            difficulty=c.difficulty.value,
+            invoice_summary=summary,
+            goal=GOAL_TEXT,
+            available_actions=ALL_ACTIONS,
+            suggested_next_actions=initial_suggestions,
+            revealed_documents=[],
+            findings=[],
+            remaining_steps=c.max_steps,
+            last_action_result="Case loaded. Begin your investigation.",
+            last_action_error=False,
+            warnings=[],
+            done=False,
+            reward=0.0,
+        )
+
+    def step(
+        self,
+        action: InvoiceGuardAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> InvoiceGuardObservation:
+        if self._case is None:
+            return self._error_obs("Environment not initialized. Call reset() first.")
+
+        s = self._env_state
+        c = self._case
+
+        if s.is_finalized:
+            return self._error_obs("Episode already finalized.")
+
+        s.step_count += 1
+        action_name = action.action_type.value
+        s.actions_taken.append(action_name)
+
+        s.repeated_action_counts[action_name] = (
+            s.repeated_action_counts.get(action_name, 0) + 1
+        )
+
+        # Check step budget
+        remaining = c.max_steps - s.step_count
+        if remaining < 0:
+            return self._finalize_timeout()
+
+        # Route action
+        reward = 0.0
+        is_repeat = s.repeated_action_counts[action_name] > 1
+        terminal = False
+
+        if action_name == ActionType.submit_final_resolution.value:
+            return self._handle_submit(action, remaining)
+        elif action_name == ActionType.propose_exception_type.value:
+            result, reward = self._handle_propose_exception(action, is_repeat)
+        elif action_name in _INVESTIGATION_HANDLERS:
+            result, reward = _INVESTIGATION_HANDLERS[action_name](self, is_repeat)
+        else:
+            result = f"Unknown action: {action_name}"
+            reward = R_INVALID_ACTION
+
+        base_reward = reward
+        penalties: dict = {}
+        if is_repeat and action_name != ActionType.submit_final_resolution.value:
+            repeat_idx = s.repeated_action_counts[action_name] - 1
+            ladder = _ladder_penalty(repeat_idx)
+            penalties["repeat"] = ladder
+            reward = min(reward, ladder)
+
+        s.cumulative_reward += reward
+        self._log_component(
+            action=action_name,
+            base=base_reward,
+            penalties=penalties,
+            total=reward,
+            reason=("repeat" if is_repeat else "step"),
+        )
+        remaining = c.max_steps - s.step_count
+
+        if remaining <= 0 and not s.is_finalized:
+            return self._finalize_timeout()
+
+        return InvoiceGuardObservation(
+            case_id=c.case_id,
+            task_id=c.task_id.value,
+            difficulty=c.difficulty.value,
+            invoice_summary=self._invoice_summary(),
+            goal=GOAL_TEXT,
+            available_actions=ALL_ACTIONS,
+            suggested_next_actions=self._suggest_next_actions(remaining),
+            revealed_documents=list(s.documents_revealed),
+            findings=list(s.findings_collected),
+            remaining_steps=remaining,
+            last_action_result=result,
+            last_action_error=False,
+            warnings=self._build_warnings(remaining),
+            done=False,
+            reward=reward,
+        )
+
+    @property
+    def state(self) -> InvoiceGuardState:
+        return self._env_state
+
+    # -- Terminal handlers ------------------------------------------------
+
+    def _handle_submit(
+        self, action: InvoiceGuardAction, remaining: int
+    ) -> InvoiceGuardObservation:
+        s = self._env_state
+        c = self._case
+
+        if not action.final_decision:
+            s.cumulative_reward += R_INVALID_ACTION
+            error_msg = (
+                "ERROR: submit_final_resolution requires all of these fields:\n"
+                '  "final_decision": one of "approve_for_payment", '
+                '"place_on_hold", "reject_invoice", "escalate_for_supervisor_review"\n'
+                '  "exception_type": one of "clean_match", "quantity_mismatch", '
+                '"price_mismatch", "partial_receipt", "duplicate_invoice", '
+                '"total_amount_mismatch", "missing_receipt", "tax_variance", '
+                '"policy_violation", "mixed_discrepancy"\n'
+                '  "evidence_references": list of action names you performed\n'
+                '  "explanation": one-sentence justification\n'
+                "Example: {\"action_type\": \"submit_final_resolution\", "
+                "\"final_decision\": \"approve_for_payment\", "
+                "\"exception_type\": \"clean_match\", "
+                "\"evidence_references\": [\"inspect_purchase_order\", "
+                "\"compare_quantity\"], "
+                "\"explanation\": \"All documents match within tolerance.\"}"
+            )
+            return InvoiceGuardObservation(
+                case_id=c.case_id,
+                task_id=c.task_id.value,
+                difficulty=c.difficulty.value,
+                invoice_summary=self._invoice_summary(),
+                goal=GOAL_TEXT,
+                available_actions=ALL_ACTIONS,
+                revealed_documents=list(s.documents_revealed),
+                findings=list(s.findings_collected),
+                remaining_steps=remaining,
+                last_action_result=error_msg,
+                last_action_error=True,
+                warnings=self._build_warnings(remaining),
+                done=False,
+                reward=R_INVALID_ACTION,
+            )
+
+        s.is_finalized = True
+        s.final_decision = action.final_decision.value
+        s.final_exception_type = (
+            action.exception_type.value if action.exception_type else None
+        )
+        s.final_evidence = list(action.evidence_references)
+        s.final_explanation = action.explanation
+        s.final_confidence = action.confidence
+
+        # Anti-gaming: punish "submit-without-investigation" shortcut.
+        shortcut_penalty = 0.0
+        if len(s.documents_revealed) < MIN_DOCS_BEFORE_SUBMIT:
+            shortcut_penalty = R_SHORTCUT_PENALTY
+
+        grader_result = grade_episode(c, s)
+
+        confidence_bonus = 0.0
+        if action.confidence is not None:
+            is_correct = (s.final_decision == c.ground_truth.correct_decision.value)
+            if is_correct and action.confidence >= 0.8:
+                confidence_bonus = 0.05
+            elif not is_correct and action.confidence >= 0.8:
+                confidence_bonus = -0.05
+
+        terminal_reward = grader_result.score + confidence_bonus + shortcut_penalty
+        s.cumulative_reward += terminal_reward
+        self._log_component(
+            action=ActionType.submit_final_resolution.value,
+            base=grader_result.score,
+            penalties={
+                **({"shortcut": shortcut_penalty} if shortcut_penalty else {}),
+                **({"confidence": confidence_bonus} if confidence_bonus else {}),
+            },
+            total=terminal_reward,
+            reason="terminal_submit",
+        )
+
+        return InvoiceGuardObservation(
+            case_id=c.case_id,
+            task_id=c.task_id.value,
+            difficulty=c.difficulty.value,
+            invoice_summary=self._invoice_summary(),
+            goal=GOAL_TEXT,
+            available_actions=[],
+            revealed_documents=list(s.documents_revealed),
+            findings=list(s.findings_collected),
+            remaining_steps=0,
+            last_action_result=(
+                f"Case resolved. Decision: {s.final_decision}. "
+                f"Grader score: {grader_result.score:.4f}"
+            ),
+            last_action_error=False,
+            warnings=[],
+            done=True,
+            reward=max(terminal_reward, 0.0),
+            grader_result=grader_result.model_dump(),
+            metadata={
+                "grader_result": grader_result.model_dump(),
+                "cumulative_reward": s.cumulative_reward,
+                "reward_components": list(s.reward_components),
+                "shortcut_penalty_applied": shortcut_penalty != 0.0,
+                "documents_revealed_count": len(s.documents_revealed),
+            },
+        )
+
+    def _finalize_timeout(self) -> InvoiceGuardObservation:
+        s = self._env_state
+        c = self._case
+        s.is_finalized = True
+
+        grader_result = grade_episode(c, s)
+        s.cumulative_reward += grader_result.score + R_TIMEOUT_PENALTY
+
+        return InvoiceGuardObservation(
+            case_id=c.case_id,
+            task_id=c.task_id.value,
+            difficulty=c.difficulty.value,
+            invoice_summary=self._invoice_summary(),
+            goal=GOAL_TEXT,
+            available_actions=[],
+            revealed_documents=list(s.documents_revealed),
+            findings=list(s.findings_collected),
+            remaining_steps=0,
+            last_action_result="Step budget exhausted. Episode ended without resolution.",
+            last_action_error=True,
+            warnings=[],
+            done=True,
+            reward=max(grader_result.score + R_TIMEOUT_PENALTY, 0.0),
+            grader_result=grader_result.model_dump(),
+            metadata={
+                "grader_result": grader_result.model_dump(),
+                "cumulative_reward": s.cumulative_reward,
+                "reward_components": list(s.reward_components),
+                "timeout": True,
+            },
+        )
+
+    def _handle_propose_exception(
+        self, action: InvoiceGuardAction, is_repeat: bool
+    ) -> tuple:
+        s = self._env_state
+        c = self._case
+        if not action.exception_type:
+            return "ERROR: propose_exception_type requires exception_type.", R_INVALID_ACTION
+
+        s.proposed_exception = action.exception_type.value
+        correct = c.ground_truth.correct_exception_type.value
+
+        if s.proposed_exception == correct:
+            finding = f"Proposed exception type: {s.proposed_exception} (noted)."
+            return finding, R_CORRECT_PROPOSAL if not is_repeat else R_REPEAT_PENALTY
+        else:
+            finding = f"Proposed exception type: {s.proposed_exception} (noted)."
+            return finding, 0.0
+
+    # -- Investigation handlers -------------------------------------------
+
+    def _inspect_invoice_line_items(self, is_repeat: bool) -> tuple:
+        c = self._case
+        s = self._env_state
+        doc = "invoice_line_items"
+
+        lines = []
+        for li in c.invoice.line_items:
+            lines.append(
+                f"  {li.item_code}: {li.description} | "
+                f"Qty: {li.quantity_billed} | "
+                f"Unit Price: ${li.unit_price_billed:,.2f} | "
+                f"Line Total: ${li.line_total_billed:,.2f}"
+            )
+        detail = (
+            f"Invoice {c.invoice.invoice_number} line items:\n"
+            + "\n".join(lines)
+            + f"\nSubtotal: ${c.invoice.subtotal:,.2f} | "
+            f"Tax: ${c.invoice.tax:,.2f} | "
+            f"Total: ${c.invoice.total_amount:,.2f}"
+        )
+
+        if c.invoice.note:
+            detail += f"\nInvoice note: {c.invoice.note}"
+
+        reward = self._reveal_doc(doc, detail)
+        return detail, reward
+
+    def _inspect_purchase_order(self, is_repeat: bool) -> tuple:
+        c = self._case
+        s = self._env_state
+        doc = "purchase_order"
+
+        lines = []
+        for li in c.purchase_order.line_items:
+            lines.append(
+                f"  {li.item_code}: {li.description} | "
+                f"Ordered Qty: {li.ordered_quantity} | "
+                f"Unit Price: ${li.unit_price_ordered:,.2f} | "
+                f"Line Total: ${li.line_total_ordered:,.2f}"
+            )
+        detail = (
+            f"PO {c.purchase_order.po_number} "
+            f"(Supplier: {c.purchase_order.supplier_id}, "
+            f"Date: {c.purchase_order.order_date}):\n"
+            + "\n".join(lines)
+            + f"\nApproved: {c.purchase_order.approved} | "
+            f"Payment Terms: {c.purchase_order.payment_terms}"
+        )
+
+        reward = self._reveal_doc(doc, detail)
+        return detail, reward
+
+    def _inspect_goods_receipt_note(self, is_repeat: bool) -> tuple:
+        c = self._case
+        doc = "goods_receipt_note"
+
+        lines = []
+        for li in c.goods_receipt_note.line_items:
+            lines.append(
+                f"  {li.item_code}: "
+                f"Received: {li.quantity_received} | "
+                f"Accepted: {li.accepted_quantity} | "
+                f"Rejected: {li.rejected_quantity}"
+            )
+        detail = (
+            f"GRN {c.goods_receipt_note.grn_number} "
+            f"(PO Ref: {c.goods_receipt_note.po_reference}, "
+            f"Date: {c.goods_receipt_note.receipt_date}):\n"
+            + "\n".join(lines)
+        )
+        if c.goods_receipt_note.warehouse_note:
+            detail += f"\nWarehouse note: {c.goods_receipt_note.warehouse_note}"
+
+        reward = self._reveal_doc(doc, detail)
+        return detail, reward
+
+    def _inspect_vendor_profile(self, is_repeat: bool) -> tuple:
+        c = self._case
+        doc = "vendor_profile"
+        vp = c.vendor_profile
+
+        detail = (
+            f"Vendor Profile -- {vp.supplier_name} ({vp.supplier_id}):\n"
+            f"  Risk Tier: {vp.risk_tier}\n"
+            f"  Preferred Vendor: {vp.preferred_vendor}\n"
+            f"  Duplicate Risk History: {vp.duplicate_risk_count} incidents"
+        )
+        if vp.tolerance_override is not None:
+            detail += f"\n  Tolerance Override: {vp.tolerance_override}%"
+        if vp.escalation_threshold is not None:
+            detail += f"\n  Escalation Threshold: ${vp.escalation_threshold:,.2f}"
+            inv_total = c.invoice.total_amount
+            if inv_total > vp.escalation_threshold:
+                detail += (
+                    f"\n  NOTE: Invoice total ${inv_total:,.2f} exceeds vendor "
+                    f"escalation threshold ${vp.escalation_threshold:,.2f}."
+                )
+
+        reward = self._reveal_doc(doc, detail)
+        return detail, reward
+
+    def _inspect_policy_rules(self, is_repeat: bool) -> tuple:
+        c = self._case
+        doc = "policy_rules"
+        p = c.company_policy
+
+        detail = (
+            f"Company Matching Policy:\n"
+            f"  Quantity Tolerance: {p.quantity_tolerance_pct}%\n"
+            f"  Price Tolerance: {p.price_tolerance_pct}%\n"
+            f"  Total Amount Tolerance: ${p.total_tolerance_amt:,.2f}\n"
+            f"  Duplicate Check: {'Enabled' if p.duplicate_check_enabled else 'Disabled'}\n"
+            f"  High-Value Review Threshold: ${p.high_value_threshold:,.2f}\n"
+            f"  Mandatory Escalation Above: ${p.mandatory_escalation_above:,.2f}\n"
+            f"\n"
+            f"  Resolution Rules:\n"
+            f"    - APPROVE: All matches within tolerance, no duplicates, no policy violations.\n"
+            f"    - HOLD: Billed quantity exceeds received quantity (partial/missing receipt).\n"
+            f"    - ESCALATE: Price or total variance exceeds tolerance. Invoice above high-value threshold.\n"
+            f"    - REJECT: Duplicate invoice detected. Fraudulent or invalid submission."
+        )
+
+        inv_total = c.invoice.total_amount
+        if inv_total >= p.high_value_threshold:
+            detail += (
+                f"\n\n  NOTE: Invoice total ${inv_total:,.2f} exceeds "
+                f"high-value threshold ${p.high_value_threshold:,.2f}. "
+                f"Supervisor review required."
+            )
+            self._add_finding(
+                f"High-value invoice: ${inv_total:,.2f} exceeds "
+                f"review threshold ${p.high_value_threshold:,.2f}."
+            )
+
+        reward = self._reveal_doc(doc, detail)
+        return detail, reward
+
+    def _check_for_duplicate_invoice(self, is_repeat: bool) -> tuple:
+        c = self._case
+        doc = "duplicate_check"
+        ch = c.case_history
+
+        if ch.processed_invoice_numbers or ch.similar_invoice_refs:
+            refs = ch.similar_invoice_refs or ch.processed_invoice_numbers
+            detail = (
+                f"Duplicate check for {c.invoice.invoice_number}:\n"
+                f"  Similar/processed invoices found: {', '.join(refs)}\n"
+                f"  Prior comments: {'; '.join(ch.prior_comments) if ch.prior_comments else 'None'}\n"
+                f"  Pending invoices: {', '.join(ch.pending_invoice_numbers) if ch.pending_invoice_numbers else 'None'}"
+            )
+            finding = (
+                f"ALERT: Potential duplicate detected. "
+                f"Previously processed invoices: {', '.join(refs)}."
+            )
+            self._add_finding(finding)
+            reward = self._reveal_doc(doc, detail)
+            return detail, max(reward, R_USEFUL_COMPARISON)
+        else:
+            detail = (
+                f"Duplicate check for {c.invoice.invoice_number}: "
+                f"No similar or duplicate invoices found in case history."
+            )
+            reward = self._reveal_doc(doc, detail)
+            return detail, reward
+
+    def _compare_quantity(self, is_repeat: bool) -> tuple:
+        c = self._case
+        results = []
+        has_discrepancy = False
+
+        for inv_li in c.invoice.line_items:
+            po_qty = None
+            grn_qty = None
+            for po_li in c.purchase_order.line_items:
+                if po_li.item_code == inv_li.item_code:
+                    po_qty = po_li.ordered_quantity
+                    break
+            for grn_li in c.goods_receipt_note.line_items:
+                if grn_li.item_code == inv_li.item_code:
+                    grn_qty = grn_li.accepted_quantity
+                    break
+
+            line = (
+                f"  {inv_li.item_code}: "
+                f"Billed={inv_li.quantity_billed}, "
+                f"Ordered={po_qty}, "
+                f"Received={grn_qty}"
+            )
+
+            if grn_qty is not None and inv_li.quantity_billed > grn_qty:
+                diff = inv_li.quantity_billed - grn_qty
+                pct = (diff / inv_li.quantity_billed) * 100
+                line += f" -> DISCREPANCY: Billed exceeds received by {diff:.0f} units ({pct:.1f}%)"
+                has_discrepancy = True
+                self._add_finding(
+                    f"Quantity discrepancy on {inv_li.item_code}: "
+                    f"billed {inv_li.quantity_billed} but only {grn_qty} received "
+                    f"(difference: {diff:.0f} units, {pct:.1f}%)."
+                )
+            elif po_qty is not None and inv_li.quantity_billed > po_qty:
+                diff = inv_li.quantity_billed - po_qty
+                line += f" -> DISCREPANCY: Billed exceeds ordered by {diff:.0f} units"
+                has_discrepancy = True
+                self._add_finding(
+                    f"Quantity discrepancy on {inv_li.item_code}: "
+                    f"billed {inv_li.quantity_billed} but only {po_qty} ordered."
+                )
+            else:
+                line += " -> OK"
+
+            results.append(line)
+
+        detail = "Quantity comparison:\n" + "\n".join(results)
+        reward = R_USEFUL_COMPARISON if has_discrepancy else R_CONFIRM_NO_ISSUE
+        return detail, reward
+
+    def _compare_price(self, is_repeat: bool) -> tuple:
+        c = self._case
+        results = []
+        has_discrepancy = False
+        tolerance = c.company_policy.price_tolerance_pct
+
+        for inv_li in c.invoice.line_items:
+            po_price = None
+            for po_li in c.purchase_order.line_items:
+                if po_li.item_code == inv_li.item_code:
+                    po_price = po_li.unit_price_ordered
+                    break
+
+            if po_price is not None:
+                line = (
+                    f"  {inv_li.item_code}: "
+                    f"Billed=${inv_li.unit_price_billed:,.2f}, "
+                    f"PO Price=${po_price:,.2f}"
+                )
+            else:
+                line = (
+                    f"  {inv_li.item_code}: "
+                    f"Billed=${inv_li.unit_price_billed:,.2f}, "
+                    f"PO Price=N/A"
+                )
+
+            if po_price is not None and po_price > 0:
+                variance_pct = (
+                    (inv_li.unit_price_billed - po_price) / po_price
+                ) * 100
+                if abs(variance_pct) > tolerance:
+                    line += (
+                        f" -> DISCREPANCY: {variance_pct:+.1f}% variance "
+                        f"(exceeds {tolerance}% tolerance)"
+                    )
+                    has_discrepancy = True
+                    self._add_finding(
+                        f"Price discrepancy on {inv_li.item_code}: "
+                        f"billed ${inv_li.unit_price_billed:,.2f} vs "
+                        f"PO ${po_price:,.2f} "
+                        f"({variance_pct:+.1f}% variance, "
+                        f"tolerance is {tolerance}%)."
+                    )
+                    self._add_finding(
+                        f"POLICY: Price variance exceeding {tolerance}% tolerance "
+                        f"requires escalation for supervisor review."
+                    )
+                else:
+                    line += f" -> Within tolerance ({variance_pct:+.1f}%)"
+
+            results.append(line)
+
+        detail = "Price comparison:\n" + "\n".join(results)
+        reward = R_USEFUL_COMPARISON if has_discrepancy else R_CONFIRM_NO_ISSUE
+        return detail, reward
+
+    def _compare_totals(self, is_repeat: bool) -> tuple:
+        c = self._case
+        inv = c.invoice
+
+        expected_subtotal = sum(li.line_total_billed for li in inv.line_items)
+        po_total = sum(li.line_total_ordered for li in c.purchase_order.line_items)
+        tolerance_amt = c.company_policy.total_tolerance_amt
+
+        subtotal_ok = abs(inv.subtotal - expected_subtotal) < 0.01
+        total_diff = inv.subtotal - po_total
+        within_tolerance = abs(total_diff) <= tolerance_amt
+
+        lines = [
+            f"  Invoice subtotal: ${inv.subtotal:,.2f} (line items sum: ${expected_subtotal:,.2f}) "
+            f"-> {'Consistent' if subtotal_ok else 'INCONSISTENT'}",
+            f"  Invoice subtotal vs PO total: ${inv.subtotal:,.2f} vs ${po_total:,.2f} "
+            f"(diff: ${total_diff:+,.2f}) -> "
+            f"{'Within' if within_tolerance else 'EXCEEDS'} tolerance (${tolerance_amt:,.2f})",
+            f"  Tax: ${inv.tax:,.2f} | Grand Total: ${inv.total_amount:,.2f}",
+        ]
+
+        has_discrepancy = not subtotal_ok or not within_tolerance
+        if has_discrepancy:
+            if not subtotal_ok:
+                self._add_finding(
+                    f"Total inconsistency: invoice subtotal ${inv.subtotal:,.2f} "
+                    f"does not match line item sum ${expected_subtotal:,.2f}."
+                )
+            if not within_tolerance:
+                self._add_finding(
+                    f"Total discrepancy: invoice subtotal ${inv.subtotal:,.2f} vs "
+                    f"PO total ${po_total:,.2f} (difference ${total_diff:+,.2f} "
+                    f"exceeds tolerance ${tolerance_amt:,.2f})."
+                )
+                self._add_finding(
+                    "POLICY: Total amount variance exceeding tolerance "
+                    "requires escalation for supervisor review."
+                )
+
+        detail = "Totals comparison:\n" + "\n".join(lines)
+        reward = R_USEFUL_COMPARISON if has_discrepancy else R_CONFIRM_NO_ISSUE
+        return detail, reward
+
+    def _summarize_findings(self, is_repeat: bool) -> tuple:
+        s = self._env_state
+        if not s.findings_collected:
+            detail = "No findings collected yet. Investigate further before summarizing."
+            return detail, 0.0
+
+        summary_lines = [f"  {i+1}. {f}" for i, f in enumerate(s.findings_collected)]
+        detail = (
+            f"Summary of findings ({len(s.findings_collected)} items):\n"
+            + "\n".join(summary_lines)
+            + f"\nDocuments reviewed: {', '.join(s.documents_revealed) if s.documents_revealed else 'None'}"
+        )
+        return detail, R_SUMMARIZE
+
+    # -- Helpers ----------------------------------------------------------
+
+    def _reveal_doc(self, doc_name: str, detail: str) -> float:
+        s = self._env_state
+        if doc_name not in s.documents_revealed:
+            s.documents_revealed.append(doc_name)
+            s.findings_collected.append(detail)
+            return R_NEW_DOCUMENT
+        return R_REPEAT_PENALTY
+
+    def _add_finding(self, finding: str) -> None:
+        s = self._env_state
+        if finding not in s.findings_collected:
+            s.findings_collected.append(finding)
+
+    def _log_component(
+        self,
+        action: str,
+        base: float,
+        penalties: dict,
+        total: float,
+        reason: str,
+    ) -> None:
+        """Append a per-step reward breakdown for transparency / training signals."""
+        s = self._env_state
+        s.reward_components.append(
+            {
+                "step": s.step_count,
+                "action": action,
+                "base": round(float(base), 4),
+                "penalties": {k: round(float(v), 4) for k, v in penalties.items()},
+                "total": round(float(total), 4),
+                "reason": reason,
+            }
+        )
+
+    def _invoice_summary(self) -> str:
+        if self._case is None:
+            return ""
+        inv = self._case.invoice
+        return (
+            f"Supplier: {inv.supplier_name} ({inv.supplier_id}), "
+            f"Invoice: {inv.invoice_number}, Date: {inv.invoice_date}, "
+            f"PO Ref: {inv.po_reference}, Total: ${inv.total_amount:,.2f}"
+        )
+
+    def _suggest_next_actions(self, remaining: int) -> list:
+        """Suggest the most useful next actions based on investigation progress."""
+        s = self._env_state
+        taken = set(s.actions_taken)
+        suggestions = []
+
+        if remaining <= 2:
+            suggestions.append("submit_final_resolution")
+            return suggestions
+
+        core_docs = [
+            "inspect_purchase_order",
+            "inspect_goods_receipt_note",
+            "inspect_invoice_line_items",
+        ]
+        for a in core_docs:
+            if a not in taken:
+                suggestions.append(a)
+
+        comparisons = ["compare_quantity", "compare_price", "compare_totals"]
+        docs_seen = set(s.documents_revealed)
+        has_po = "purchase_order" in docs_seen
+        has_grn = "goods_receipt_note" in docs_seen
+        if has_po and has_grn:
+            for a in comparisons:
+                if a not in taken:
+                    suggestions.append(a)
+
+        secondary = [
+            "inspect_policy_rules",
+            "check_for_duplicate_invoice",
+            "inspect_vendor_profile",
+        ]
+        for a in secondary:
+            if a not in taken:
+                suggestions.append(a)
+
+        if not suggestions:
+            if "summarize_findings" not in taken:
+                suggestions.append("summarize_findings")
+            suggestions.append("submit_final_resolution")
+
+        return suggestions
+
+    def _build_warnings(self, remaining: int) -> list:
+        warnings = []
+        s = self._env_state
+        if remaining <= 2:
+            warnings.append(
+                f"CRITICAL: Only {remaining} step(s) remaining! "
+                f"You MUST submit_final_resolution NOW."
+            )
+        elif remaining <= 4 and not s.is_finalized:
+            warnings.append(
+                f"WARNING: {remaining} steps remaining. "
+                f"Submit your final resolution soon."
+            )
+        return warnings
+
+    def _error_obs(self, message: str) -> InvoiceGuardObservation:
+        return InvoiceGuardObservation(
+            last_action_result=f"ERROR: {message}",
+            last_action_error=True,
+            done=True,
+            reward=0.0,
+        )
+
+
+# Handler dispatch table -- maps action type strings to bound methods.
+# Built outside the class to keep the routing clean.
+_INVESTIGATION_HANDLERS = {
+    ActionType.inspect_invoice_line_items.value: InvoiceGuardEnvironment._inspect_invoice_line_items,
+    ActionType.inspect_purchase_order.value: InvoiceGuardEnvironment._inspect_purchase_order,
+    ActionType.inspect_goods_receipt_note.value: InvoiceGuardEnvironment._inspect_goods_receipt_note,
+    ActionType.inspect_vendor_profile.value: InvoiceGuardEnvironment._inspect_vendor_profile,
+    ActionType.inspect_policy_rules.value: InvoiceGuardEnvironment._inspect_policy_rules,
+    ActionType.check_for_duplicate_invoice.value: InvoiceGuardEnvironment._check_for_duplicate_invoice,
+    ActionType.compare_quantity.value: InvoiceGuardEnvironment._compare_quantity,
+    ActionType.compare_price.value: InvoiceGuardEnvironment._compare_price,
+    ActionType.compare_totals.value: InvoiceGuardEnvironment._compare_totals,
+    ActionType.summarize_findings.value: InvoiceGuardEnvironment._summarize_findings,
+}

tasks/__init__.py

@@ -0,0 +1,2 @@
+from .definitions import get_task_case, TASK_LIST, ALL_TASKS
+from .hard_definitions import HARD_TASK_LIST

tasks/definitions.py

@@ -0,0 +1,2104 @@
+"""
+Task definitions and synthetic case templates for InvoiceGuard.
+
+Four tasks with increasing difficulty, each with fully synthetic
+business documents and deterministic ground truth.
+"""
+
+from typing import Dict, List
+
+try:
+    from ..models import (
+        CaseData, CaseHistory, CompanyPolicy, DecisionType, Difficulty,
+        ExceptionType, GRNLineItem, GoodsReceiptNote, GroundTruth,
+        Invoice, InvoiceLineItem, POLineItem, PurchaseOrder,
+        TaskID, VendorProfile,
+    )
+    from .hard_definitions import HARD_TASK_BUILDERS, HARD_TASK_LIST
+except ImportError:
+    from models import (
+        CaseData, CaseHistory, CompanyPolicy, DecisionType, Difficulty,
+        ExceptionType, GRNLineItem, GoodsReceiptNote, GroundTruth,
+        Invoice, InvoiceLineItem, POLineItem, PurchaseOrder,
+        TaskID, VendorProfile,
+    )
+    from tasks.hard_definitions import HARD_TASK_BUILDERS, HARD_TASK_LIST
+
+
+TASK_LIST: List[TaskID] = [
+    TaskID.task_1_clean_match,
+    TaskID.task_2_partial_receipt,
+    TaskID.task_3_price_variance,
+    TaskID.task_4_duplicate_invoice,
+    TaskID.task_5_mixed_discrepancy,
+    TaskID.task_6_false_positive_duplicate,
+    TaskID.task_7_retroactive_price,
+    TaskID.task_8_split_invoice_pattern,
+    TaskID.task_9_clean_from_risky_vendor,
+    TaskID.task_10_rounding_false_alarm,
+    TaskID.task_11_authorized_overship,
+    TaskID.task_12_corrected_resubmission,
+]
+
+ALL_TASKS: List[TaskID] = [
+    TaskID.task_1_clean_match,
+    TaskID.task_1b_multi_line_clean,
+    TaskID.task_1c_preferred_vendor_clean,
+    TaskID.task_2_partial_receipt,
+    TaskID.task_2b_missing_receipt,
+    TaskID.task_2c_over_receipt,
+    TaskID.task_3_price_variance,
+    TaskID.task_3b_within_tolerance,
+    TaskID.task_3c_total_mismatch,
+    TaskID.task_4_duplicate_invoice,
+    TaskID.task_4b_corrected_invoice_trap,
+    TaskID.task_4c_policy_violation,
+    TaskID.task_5_mixed_discrepancy,
+    TaskID.task_6_false_positive_duplicate,
+    TaskID.task_7_retroactive_price,
+    TaskID.task_8_split_invoice_pattern,
+    TaskID.task_9_clean_from_risky_vendor,
+    TaskID.task_10_rounding_false_alarm,
+    TaskID.task_11_authorized_overship,
+    TaskID.task_12_corrected_resubmission,
+    *HARD_TASK_LIST,
+]
+
+
+def get_task_case(task_id: TaskID) -> CaseData:
+    """Return the case data for a given task (canonical or variant)."""
+    builders: Dict[TaskID, callable] = {
+        TaskID.task_1_clean_match: _build_task_1,
+        TaskID.task_1b_multi_line_clean: _build_task_1b,
+        TaskID.task_1c_preferred_vendor_clean: _build_task_1c,
+        TaskID.task_2_partial_receipt: _build_task_2,
+        TaskID.task_2b_missing_receipt: _build_task_2b,
+        TaskID.task_2c_over_receipt: _build_task_2c,
+        TaskID.task_3_price_variance: _build_task_3,
+        TaskID.task_3b_within_tolerance: _build_task_3b,
+        TaskID.task_3c_total_mismatch: _build_task_3c,
+        TaskID.task_4_duplicate_invoice: _build_task_4,
+        TaskID.task_4b_corrected_invoice_trap: _build_task_4b,
+        TaskID.task_4c_policy_violation: _build_task_4c,
+        TaskID.task_5_mixed_discrepancy: _build_task_5,
+        TaskID.task_6_false_positive_duplicate: _build_task_6,
+        TaskID.task_7_retroactive_price: _build_task_7,
+        TaskID.task_8_split_invoice_pattern: _build_task_8,
+        TaskID.task_9_clean_from_risky_vendor: _build_task_9,
+        TaskID.task_10_rounding_false_alarm: _build_task_10,
+        TaskID.task_11_authorized_overship: _build_task_11,
+        TaskID.task_12_corrected_resubmission: _build_task_12,
+        **HARD_TASK_BUILDERS,
+    }
+    return builders[task_id]()
+
+
+# -- Task 1: Clean Match Approval --------------------------------------------
+# Difficulty: easy | Decision: approve_for_payment | Exception: clean_match
+# All three documents align within tolerance. Tests whether the agent can
+# confirm a clean case without inventing problems.
+
+
+def _build_task_1() -> CaseData:
+    return CaseData(
+        case_id="CASE-1001",
+        task_id=TaskID.task_1_clean_match,
+        difficulty=Difficulty.easy,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0042",
+            supplier_name="Apex Office Supplies",
+            supplier_id="SUP-1001",
+            invoice_date="2024-11-15",
+            po_reference="PO-5500",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-A01",
+                    description="Premium Copy Paper A4 (500 sheets)",
+                    quantity_billed=100,
+                    unit_price_billed=25.00,
+                    line_total_billed=2500.00,
+                ),
+            ],
+            subtotal=2500.00,
+            tax=200.00,
+            total_amount=2700.00,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-5500",
+            supplier_id="SUP-1001",
+            order_date="2024-10-20",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-A01",
+                    description="Premium Copy Paper A4 (500 sheets)",
+                    ordered_quantity=100,
+                    unit_price_ordered=25.00,
+                    line_total_ordered=2500.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-7801",
+            po_reference="PO-5500",
+            receipt_date="2024-11-10",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-A01",
+                    quantity_received=100,
+                    accepted_quantity=100,
+                ),
+            ],
+            warehouse_note="All items received in good condition.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-1001",
+            supplier_name="Apex Office Supplies",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=100.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+            ],
+            key_findings=[
+                "Quantities match across invoice, PO, and GRN",
+                "Prices match between invoice and PO",
+                "No discrepancies detected",
+            ],
+        ),
+    )
+
+
+# -- Task 2: Quantity & Partial Receipt Hold ----------------------------------
+# Difficulty: moderate | Decision: place_on_hold | Exception: partial_receipt
+# Invoice bills 100 units, PO ordered 100, but GRN only received 60.
+# Agent must recognize billed qty exceeds received qty.
+
+
+def _build_task_2() -> CaseData:
+    return CaseData(
+        case_id="CASE-2002",
+        task_id=TaskID.task_2_partial_receipt,
+        difficulty=Difficulty.moderate,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0187",
+            supplier_name="Delta Industrial Parts",
+            supplier_id="SUP-2050",
+            invoice_date="2024-12-01",
+            po_reference="PO-6200",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-D10",
+                    description="Stainless Steel Bearings (Box of 50)",
+                    quantity_billed=100,
+                    unit_price_billed=50.00,
+                    line_total_billed=5000.00,
+                ),
+            ],
+            subtotal=5000.00,
+            tax=400.00,
+            total_amount=5400.00,
+            note="Please process payment promptly.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-6200",
+            supplier_id="SUP-2050",
+            order_date="2024-11-01",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-D10",
+                    description="Stainless Steel Bearings (Box of 50)",
+                    ordered_quantity=100,
+                    unit_price_ordered=50.00,
+                    line_total_ordered=5000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-8830",
+            po_reference="PO-6200",
+            receipt_date="2024-11-25",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-D10",
+                    quantity_received=60,
+                    accepted_quantity=60,
+                    rejected_quantity=0,
+                ),
+            ],
+            warehouse_note="Partial shipment. Remaining 40 units expected next week.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-2050",
+            supplier_name="Delta Industrial Parts",
+            risk_tier="medium",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=["Supplier has had partial shipments before."],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.place_on_hold,
+            correct_exception_type=ExceptionType.partial_receipt,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_quantity",
+            ],
+            key_findings=[
+                "Invoice billed 100 units but GRN shows only 60 received",
+                "Billed quantity exceeds received quantity by 40 units (40%)",
+                "Variance exceeds quantity tolerance of 5%",
+            ],
+        ),
+    )
+
+
+# -- Task 3: Price Variance with Policy Tolerance ----------------------------
+# Difficulty: moderate | Decision: escalate_for_supervisor_review
+# Exception: price_mismatch
+# Invoice unit price is $110 vs PO price of $100 (10% variance).
+# Company tolerance is 5%, so this must be escalated.
+
+
+def _build_task_3() -> CaseData:
+    return CaseData(
+        case_id="CASE-3003",
+        task_id=TaskID.task_3_price_variance,
+        difficulty=Difficulty.moderate,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0315",
+            supplier_name="Quantum Tech Solutions",
+            supplier_id="SUP-3100",
+            invoice_date="2024-12-10",
+            po_reference="PO-7100",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-Q22",
+                    description="Enterprise SSD 1TB NVMe",
+                    quantity_billed=50,
+                    unit_price_billed=110.00,
+                    line_total_billed=5500.00,
+                ),
+            ],
+            subtotal=5500.00,
+            tax=440.00,
+            total_amount=5940.00,
+            note="Price adjusted due to component shortage surcharge.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-7100",
+            supplier_id="SUP-3100",
+            order_date="2024-11-15",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-Q22",
+                    description="Enterprise SSD 1TB NVMe",
+                    ordered_quantity=50,
+                    unit_price_ordered=100.00,
+                    line_total_ordered=5000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-9150",
+            po_reference="PO-7100",
+            receipt_date="2024-12-05",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-Q22",
+                    quantity_received=50,
+                    accepted_quantity=50,
+                ),
+            ],
+            warehouse_note="All units received and tested OK.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-3100",
+            supplier_name="Quantum Tech Solutions",
+            risk_tier="medium",
+            preferred_vendor=True,
+            escalation_threshold=5000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            high_value_threshold=50000.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Supplier occasionally applies surcharges without prior notice.",
+            ],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.price_mismatch,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_policy_rules",
+                "compare_price",
+            ],
+            key_findings=[
+                "Invoice unit price $110.00 vs PO unit price $100.00",
+                "Price variance of 10% exceeds company tolerance of 5%",
+                "Requires supervisor review per escalation policy",
+            ],
+        ),
+    )
+
+
+# -- Task 4: Duplicate Invoice with Mixed Signals ----------------------------
+# Difficulty: hard | Decision: reject_invoice | Exception: duplicate_invoice
+# Quantities and prices match perfectly, but case history reveals a
+# previously processed invoice with near-identical details. A misleading
+# vendor note tries to distract.
+
+
+def _build_task_4() -> CaseData:
+    return CaseData(
+        case_id="CASE-4004",
+        task_id=TaskID.task_4_duplicate_invoice,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-0512",
+            supplier_name="Redline Logistics Corp",
+            supplier_id="SUP-4200",
+            invoice_date="2024-12-18",
+            po_reference="PO-8800",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-R05",
+                    description="Heavy-Duty Shipping Pallets",
+                    quantity_billed=200,
+                    unit_price_billed=30.00,
+                    line_total_billed=6000.00,
+                ),
+            ],
+            subtotal=6000.00,
+            tax=480.00,
+            total_amount=6480.00,
+            note="URGENT: Payment overdue. Please expedite. Ref: follow-up to INV-2024-0511.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-8800",
+            supplier_id="SUP-4200",
+            order_date="2024-11-20",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-R05",
+                    description="Heavy-Duty Shipping Pallets",
+                    ordered_quantity=200,
+                    unit_price_ordered=30.00,
+                    line_total_ordered=6000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-9900",
+            po_reference="PO-8800",
+            receipt_date="2024-12-12",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-R05",
+                    quantity_received=200,
+                    accepted_quantity=200,
+                ),
+            ],
+            warehouse_note="Full shipment received.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-4200",
+            supplier_name="Redline Logistics Corp",
+            risk_tier="high",
+            duplicate_risk_count=2,
+            preferred_vendor=False,
+            escalation_threshold=3000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Previous duplicate submission flagged for this supplier in Q3.",
+                "Supplier has been warned about duplicate invoicing.",
+            ],
+            similar_invoice_refs=["INV-2024-0511"],
+            processed_invoice_numbers=[
+                "INV-2024-0511",
+                "INV-2024-0388",
+            ],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.reject_invoice,
+            correct_exception_type=ExceptionType.duplicate_invoice,
+            acceptable_evidence=[
+                "check_for_duplicate_invoice",
+                "inspect_vendor_profile",
+            ],
+            key_findings=[
+                "Previously processed INV-2024-0511 has same supplier, same PO, same total",
+                "Current invoice INV-2024-0512 is sequential to processed INV-2024-0511",
+                "Supplier flagged as high risk with 2 prior duplicate incidents",
+                "Invoice note references INV-2024-0511 as 'follow-up'",
+            ],
+        ),
+    )
+
+
+# ===========================================================================
+# VARIANT TASKS
+# ===========================================================================
+
+
+# -- Task 1b: Multi-Line Clean Match --------------------------------------
+# Three line items, all matching. Tests multi-item verification.
+
+def _build_task_1b() -> CaseData:
+    return CaseData(
+        case_id="CASE-1002",
+        task_id=TaskID.task_1b_multi_line_clean,
+        difficulty=Difficulty.easy,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0099",
+            supplier_name="Summit Facility Services",
+            supplier_id="SUP-1050",
+            invoice_date="2024-11-20",
+            po_reference="PO-5510",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-F01",
+                    description="Industrial Floor Cleaner 5L",
+                    quantity_billed=20,
+                    unit_price_billed=35.00,
+                    line_total_billed=700.00,
+                ),
+                InvoiceLineItem(
+                    item_code="ITEM-F02",
+                    description="Microfiber Mop Heads (Pack of 10)",
+                    quantity_billed=15,
+                    unit_price_billed=18.00,
+                    line_total_billed=270.00,
+                ),
+                InvoiceLineItem(
+                    item_code="ITEM-F03",
+                    description="Nitrile Gloves Box (100ct)",
+                    quantity_billed=50,
+                    unit_price_billed=12.00,
+                    line_total_billed=600.00,
+                ),
+            ],
+            subtotal=1570.00,
+            tax=125.60,
+            total_amount=1695.60,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-5510",
+            supplier_id="SUP-1050",
+            order_date="2024-10-25",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-F01",
+                    description="Industrial Floor Cleaner 5L",
+                    ordered_quantity=20,
+                    unit_price_ordered=35.00,
+                    line_total_ordered=700.00,
+                ),
+                POLineItem(
+                    item_code="ITEM-F02",
+                    description="Microfiber Mop Heads (Pack of 10)",
+                    ordered_quantity=15,
+                    unit_price_ordered=18.00,
+                    line_total_ordered=270.00,
+                ),
+                POLineItem(
+                    item_code="ITEM-F03",
+                    description="Nitrile Gloves Box (100ct)",
+                    ordered_quantity=50,
+                    unit_price_ordered=12.00,
+                    line_total_ordered=600.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-7820",
+            po_reference="PO-5510",
+            receipt_date="2024-11-15",
+            line_items=[
+                GRNLineItem(item_code="ITEM-F01", quantity_received=20, accepted_quantity=20),
+                GRNLineItem(item_code="ITEM-F02", quantity_received=15, accepted_quantity=15),
+                GRNLineItem(item_code="ITEM-F03", quantity_received=50, accepted_quantity=50),
+            ],
+            warehouse_note="All items received, inspected, shelved.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-1050",
+            supplier_name="Summit Facility Services",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=100.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+            ],
+            key_findings=[
+                "All 3 line items match across invoice, PO, and GRN",
+                "No price or quantity discrepancies",
+            ],
+        ),
+    )
+
+
+# -- Task 1c: Preferred Vendor Clean Match --------------------------------
+# Single item, low-risk preferred vendor, very straightforward.
+
+def _build_task_1c() -> CaseData:
+    return CaseData(
+        case_id="CASE-1003",
+        task_id=TaskID.task_1c_preferred_vendor_clean,
+        difficulty=Difficulty.easy,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0155",
+            supplier_name="BrightStar IT Solutions",
+            supplier_id="SUP-1200",
+            invoice_date="2024-12-02",
+            po_reference="PO-5600",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-B10",
+                    description="Wireless Keyboard & Mouse Combo",
+                    quantity_billed=30,
+                    unit_price_billed=45.00,
+                    line_total_billed=1350.00,
+                ),
+            ],
+            subtotal=1350.00,
+            tax=108.00,
+            total_amount=1458.00,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-5600",
+            supplier_id="SUP-1200",
+            order_date="2024-11-10",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-B10",
+                    description="Wireless Keyboard & Mouse Combo",
+                    ordered_quantity=30,
+                    unit_price_ordered=45.00,
+                    line_total_ordered=1350.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-7850",
+            po_reference="PO-5600",
+            receipt_date="2024-11-28",
+            line_items=[
+                GRNLineItem(item_code="ITEM-B10", quantity_received=30, accepted_quantity=30),
+            ],
+            warehouse_note="Full shipment. All items functional.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-1200",
+            supplier_name="BrightStar IT Solutions",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=100.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+            ],
+            key_findings=[
+                "Quantities match (30 ordered, 30 billed, 30 received)",
+                "Price matches ($45.00 agreed and billed)",
+            ],
+        ),
+    )
+
+
+# -- Task 2b: Missing Receipt (GRN shows 0 received) ---------------------
+# GRN was filed but zero units accepted. Decision: hold.
+
+def _build_task_2b() -> CaseData:
+    return CaseData(
+        case_id="CASE-2003",
+        task_id=TaskID.task_2b_missing_receipt,
+        difficulty=Difficulty.moderate,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0201",
+            supplier_name="NorthWind Chemicals",
+            supplier_id="SUP-2100",
+            invoice_date="2024-12-05",
+            po_reference="PO-6300",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-N05",
+                    description="Laboratory Grade Ethanol 1L",
+                    quantity_billed=200,
+                    unit_price_billed=22.00,
+                    line_total_billed=4400.00,
+                ),
+            ],
+            subtotal=4400.00,
+            tax=352.00,
+            total_amount=4752.00,
+            note="Shipment dispatched per schedule.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-6300",
+            supplier_id="SUP-2100",
+            order_date="2024-11-05",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-N05",
+                    description="Laboratory Grade Ethanol 1L",
+                    ordered_quantity=200,
+                    unit_price_ordered=22.00,
+                    line_total_ordered=4400.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-8850",
+            po_reference="PO-6300",
+            receipt_date="2024-11-30",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-N05",
+                    quantity_received=0,
+                    accepted_quantity=0,
+                    rejected_quantity=0,
+                ),
+            ],
+            warehouse_note="Shipment not yet received. GRN opened pending delivery.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-2100",
+            supplier_name="NorthWind Chemicals",
+            risk_tier="medium",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.place_on_hold,
+            correct_exception_type=ExceptionType.missing_receipt,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_quantity",
+            ],
+            key_findings=[
+                "GRN shows 0 units received against 200 billed",
+                "Shipment has not been delivered or accepted",
+                "Cannot pay before goods are received",
+            ],
+        ),
+    )
+
+
+# -- Task 2c: Over-Receipt (billed more than ordered, received matches ordered) -
+# Billed 120 but PO was 100 and GRN accepted 100. Overbilling.
+
+def _build_task_2c() -> CaseData:
+    return CaseData(
+        case_id="CASE-2004",
+        task_id=TaskID.task_2c_over_receipt,
+        difficulty=Difficulty.moderate,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0220",
+            supplier_name="Pacific Hardware Co",
+            supplier_id="SUP-2200",
+            invoice_date="2024-12-08",
+            po_reference="PO-6400",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-P15",
+                    description="Stainless Steel Bolts M10x50 (Box of 100)",
+                    quantity_billed=120,
+                    unit_price_billed=8.50,
+                    line_total_billed=1020.00,
+                ),
+            ],
+            subtotal=1020.00,
+            tax=81.60,
+            total_amount=1101.60,
+            note="Additional 20 boxes included as courtesy stock.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-6400",
+            supplier_id="SUP-2200",
+            order_date="2024-11-10",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-P15",
+                    description="Stainless Steel Bolts M10x50 (Box of 100)",
+                    ordered_quantity=100,
+                    unit_price_ordered=8.50,
+                    line_total_ordered=850.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-8870",
+            po_reference="PO-6400",
+            receipt_date="2024-12-03",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-P15",
+                    quantity_received=100,
+                    accepted_quantity=100,
+                ),
+            ],
+            warehouse_note="Received 100 boxes per PO. No extra stock delivered.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-2200",
+            supplier_name="Pacific Hardware Co",
+            risk_tier="medium",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=100.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.place_on_hold,
+            correct_exception_type=ExceptionType.quantity_mismatch,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_quantity",
+            ],
+            key_findings=[
+                "Invoice bills 120 units but only 100 were ordered and received",
+                "Overbilling of 20 units (20% over received)",
+                "Variance far exceeds 5% quantity tolerance",
+            ],
+        ),
+    )
+
+
+# -- Task 3b: Price Within Tolerance (should approve) ---------------------
+# Price is 2% above PO, which is within the 5% tolerance. Clean approval.
+
+def _build_task_3b() -> CaseData:
+    return CaseData(
+        case_id="CASE-3004",
+        task_id=TaskID.task_3b_within_tolerance,
+        difficulty=Difficulty.moderate,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0330",
+            supplier_name="EcoTech Green Supplies",
+            supplier_id="SUP-3200",
+            invoice_date="2024-12-12",
+            po_reference="PO-7200",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-E08",
+                    description="Recycled Paper Reams (500 sheets)",
+                    quantity_billed=80,
+                    unit_price_billed=20.40,
+                    line_total_billed=1632.00,
+                ),
+            ],
+            subtotal=1632.00,
+            tax=130.56,
+            total_amount=1762.56,
+            note="Slight price increase due to recycled material costs.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-7200",
+            supplier_id="SUP-3200",
+            order_date="2024-11-18",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-E08",
+                    description="Recycled Paper Reams (500 sheets)",
+                    ordered_quantity=80,
+                    unit_price_ordered=20.00,
+                    line_total_ordered=1600.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-9170",
+            po_reference="PO-7200",
+            receipt_date="2024-12-08",
+            line_items=[
+                GRNLineItem(item_code="ITEM-E08", quantity_received=80, accepted_quantity=80),
+            ],
+            warehouse_note="All reams received and stored.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-3200",
+            supplier_name="EcoTech Green Supplies",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_price",
+            ],
+            key_findings=[
+                "Price variance of 2% is within 5% tolerance",
+                "Quantities match (80 ordered, 80 billed, 80 received)",
+                "Acceptable per company policy",
+            ],
+        ),
+    )
+
+
+# -- Task 3c: Total Amount Mismatch --------------------------------------
+# Line-item prices match, but the invoice subtotal is inflated (arithmetic error).
+
+def _build_task_3c() -> CaseData:
+    return CaseData(
+        case_id="CASE-3005",
+        task_id=TaskID.task_3c_total_mismatch,
+        difficulty=Difficulty.moderate,
+        max_steps=10,
+        invoice=Invoice(
+            invoice_number="INV-2024-0345",
+            supplier_name="Vanguard Medical Supplies",
+            supplier_id="SUP-3300",
+            invoice_date="2024-12-14",
+            po_reference="PO-7300",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-V12",
+                    description="Disposable Surgical Masks (Box of 50)",
+                    quantity_billed=500,
+                    unit_price_billed=6.00,
+                    line_total_billed=3000.00,
+                ),
+            ],
+            subtotal=3500.00,
+            tax=280.00,
+            total_amount=3780.00,
+            note="Bulk order -- standard pricing applied.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-7300",
+            supplier_id="SUP-3300",
+            order_date="2024-11-20",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-V12",
+                    description="Disposable Surgical Masks (Box of 50)",
+                    ordered_quantity=500,
+                    unit_price_ordered=6.00,
+                    line_total_ordered=3000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-9200",
+            po_reference="PO-7300",
+            receipt_date="2024-12-10",
+            line_items=[
+                GRNLineItem(item_code="ITEM-V12", quantity_received=500, accepted_quantity=500),
+            ],
+            warehouse_note="Full shipment received.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-3300",
+            supplier_name="Vanguard Medical Supplies",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.total_amount_mismatch,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "compare_totals",
+            ],
+            key_findings=[
+                "Invoice subtotal $3,500 does not match line items sum $3,000",
+                "Invoice subtotal exceeds PO total by $500 (beyond $200 tolerance)",
+                "Possible arithmetic error or hidden charges",
+            ],
+        ),
+    )
+
+
+# -- Task 4b: Corrected Invoice Trap --------------------------------------
+# Invoice claims to be a "corrected version" of a prior invoice, but the
+# prior invoice was already paid. Still a duplicate.
+
+def _build_task_4b() -> CaseData:
+    return CaseData(
+        case_id="CASE-4005",
+        task_id=TaskID.task_4b_corrected_invoice_trap,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-0601",
+            supplier_name="Atlas Freight Solutions",
+            supplier_id="SUP-4300",
+            invoice_date="2024-12-20",
+            po_reference="PO-8900",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-A20",
+                    description="Corrugated Shipping Boxes (Large)",
+                    quantity_billed=300,
+                    unit_price_billed=4.50,
+                    line_total_billed=1350.00,
+                ),
+            ],
+            subtotal=1350.00,
+            tax=108.00,
+            total_amount=1458.00,
+            note="CORRECTED INVOICE -- replaces INV-2024-0600. Please disregard previous version.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-8900",
+            supplier_id="SUP-4300",
+            order_date="2024-11-22",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-A20",
+                    description="Corrugated Shipping Boxes (Large)",
+                    ordered_quantity=300,
+                    unit_price_ordered=4.50,
+                    line_total_ordered=1350.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-9920",
+            po_reference="PO-8900",
+            receipt_date="2024-12-15",
+            line_items=[
+                GRNLineItem(item_code="ITEM-A20", quantity_received=300, accepted_quantity=300),
+            ],
+            warehouse_note="All boxes received per PO.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-4300",
+            supplier_name="Atlas Freight Solutions",
+            risk_tier="medium",
+            duplicate_risk_count=1,
+            preferred_vendor=True,
+            escalation_threshold=5000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "INV-2024-0600 was processed and paid on 2024-12-17.",
+            ],
+            similar_invoice_refs=["INV-2024-0600"],
+            processed_invoice_numbers=["INV-2024-0600"],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.reject_invoice,
+            correct_exception_type=ExceptionType.duplicate_invoice,
+            acceptable_evidence=[
+                "check_for_duplicate_invoice",
+                "inspect_vendor_profile",
+            ],
+            key_findings=[
+                "INV-2024-0600 was already processed and paid",
+                "Current invoice claims to be a 'correction' but has identical amounts",
+                "Supplier has 1 prior duplicate incident",
+            ],
+        ),
+    )
+
+
+# -- Task 4c: Policy Violation (high-value without authorization) ---------
+# Invoice total exceeds high-value threshold. Everything else matches,
+# but policy requires escalation for high-value invoices.
+
+def _build_task_4c() -> CaseData:
+    return CaseData(
+        case_id="CASE-4006",
+        task_id=TaskID.task_4c_policy_violation,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-0700",
+            supplier_name="TitanWorks Engineering",
+            supplier_id="SUP-4400",
+            invoice_date="2024-12-22",
+            po_reference="PO-9100",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-T30",
+                    description="CNC Machined Aluminum Housing Unit",
+                    quantity_billed=100,
+                    unit_price_billed=520.00,
+                    line_total_billed=52000.00,
+                ),
+            ],
+            subtotal=52000.00,
+            tax=4160.00,
+            total_amount=56160.00,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-9100",
+            supplier_id="SUP-4400",
+            order_date="2024-12-01",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-T30",
+                    description="CNC Machined Aluminum Housing Unit",
+                    ordered_quantity=100,
+                    unit_price_ordered=520.00,
+                    line_total_ordered=52000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-9950",
+            po_reference="PO-9100",
+            receipt_date="2024-12-18",
+            line_items=[
+                GRNLineItem(item_code="ITEM-T30", quantity_received=100, accepted_quantity=100),
+            ],
+            warehouse_note="All units received. Quality inspection passed.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-4400",
+            supplier_name="TitanWorks Engineering",
+            risk_tier="medium",
+            preferred_vendor=True,
+            escalation_threshold=40000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=500.0,
+            high_value_threshold=50000.0,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.policy_violation,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_policy_rules",
+                "inspect_vendor_profile",
+            ],
+            key_findings=[
+                "Invoice total $56,160 exceeds high-value threshold of $50,000",
+                "All quantities and prices match, but policy requires supervisor review",
+                "Invoice also exceeds vendor escalation threshold of $40,000",
+            ],
+        ),
+    )
+
+
+# ===========================================================================
+# GENUINELY HARD TASKS
+# ===========================================================================
+
+
+# -- Task 5: Mixed Discrepancy (price over tolerance + partial receipt) ---
+# Difficulty: hard | Decision: escalate_for_supervisor_review
+# Exception: mixed_discrepancy
+#
+# This case has TWO simultaneous issues:
+#   1. Price variance: $55 billed vs $50 PO (10%, exceeds 5% tolerance)
+#   2. Partial receipt: billed 200, only 150 received
+# Both "hold" and "escalate" seem reasonable. Per policy, price variance
+# exceeding tolerance triggers escalation, which takes priority over hold.
+# The agent must read the policy rules and recognize escalation outranks hold.
+
+def _build_task_5() -> CaseData:
+    return CaseData(
+        case_id="CASE-5001",
+        task_id=TaskID.task_5_mixed_discrepancy,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-0850",
+            supplier_name="GlobalParts Manufacturing",
+            supplier_id="SUP-5100",
+            invoice_date="2024-12-20",
+            po_reference="PO-9500",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-G40",
+                    description="Precision Titanium Fasteners (Box of 25)",
+                    quantity_billed=200,
+                    unit_price_billed=55.00,
+                    line_total_billed=11000.00,
+                ),
+            ],
+            subtotal=11000.00,
+            tax=880.00,
+            total_amount=11880.00,
+            note="Price reflects updated material costs. Partial shipment billed in full per contract terms.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-9500",
+            supplier_id="SUP-5100",
+            order_date="2024-11-25",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-G40",
+                    description="Precision Titanium Fasteners (Box of 25)",
+                    ordered_quantity=200,
+                    unit_price_ordered=50.00,
+                    line_total_ordered=10000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-10200",
+            po_reference="PO-9500",
+            receipt_date="2024-12-15",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-G40",
+                    quantity_received=150,
+                    accepted_quantity=150,
+                    rejected_quantity=0,
+                ),
+            ],
+            warehouse_note="Partial shipment. 50 boxes backordered, ETA 2 weeks.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-5100",
+            supplier_name="GlobalParts Manufacturing",
+            risk_tier="medium",
+            preferred_vendor=True,
+            escalation_threshold=8000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=300.0,
+            high_value_threshold=50000.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Supplier has a history of price adjustments on raw material orders.",
+            ],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.mixed_discrepancy,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_quantity",
+                "compare_price",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "Price variance: $55 billed vs $50 PO (10%, exceeds 5% tolerance)",
+                "Quantity discrepancy: billed 200 but only 150 received (25% short)",
+                "Both price escalation and quantity hold conditions triggered",
+                "Per policy, price variance exceeding tolerance requires escalation",
+                "Escalation takes priority over hold when both apply",
+            ],
+        ),
+    )
+
+
+# -- Task 6: False Positive Duplicate (legitimate second order) -----------
+# Difficulty: hard | Decision: approve_for_payment
+# Exception: clean_match
+#
+# This case is designed to trap agents that rely on superficial pattern
+# matching. The invoice is from the SAME supplier, for the SAME item,
+# with a SIMILAR amount -- but references a DIFFERENT PO number. The case
+# history has a processed invoice for PO-9600, but this invoice is for
+# PO-9700 (a separate legitimate order). The vendor note mentioning
+# "same as last month" is a red herring.
+#
+# The agent must carefully check PO references rather than assuming
+# duplicate based on supplier + amount similarity.
+
+def _build_task_6() -> CaseData:
+    return CaseData(
+        case_id="CASE-6001",
+        task_id=TaskID.task_6_false_positive_duplicate,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-0920",
+            supplier_name="Metro Cleaning Services",
+            supplier_id="SUP-6100",
+            invoice_date="2024-12-28",
+            po_reference="PO-9700",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-M15",
+                    description="Monthly Office Cleaning Service - January",
+                    quantity_billed=1,
+                    unit_price_billed=4500.00,
+                    line_total_billed=4500.00,
+                ),
+            ],
+            subtotal=4500.00,
+            tax=360.00,
+            total_amount=4860.00,
+            note="Monthly service invoice -- same as last month's order.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-9700",
+            supplier_id="SUP-6100",
+            order_date="2024-12-15",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-M15",
+                    description="Monthly Office Cleaning Service - January",
+                    ordered_quantity=1,
+                    unit_price_ordered=4500.00,
+                    line_total_ordered=4500.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-10500",
+            po_reference="PO-9700",
+            receipt_date="2024-12-26",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-M15",
+                    quantity_received=1,
+                    accepted_quantity=1,
+                ),
+            ],
+            warehouse_note="Service confirmed completed for January cycle.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-6100",
+            supplier_name="Metro Cleaning Services",
+            risk_tier="low",
+            duplicate_risk_count=0,
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Monthly recurring service contract. New PO issued each month.",
+            ],
+            processed_invoice_numbers=[
+                "INV-2024-0880",
+            ],
+            similar_invoice_refs=[],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "check_for_duplicate_invoice",
+            ],
+            key_findings=[
+                "Invoice references PO-9700, which is a separate order from prior PO-9600",
+                "Prior invoice INV-2024-0880 was for a different PO (different month)",
+                "Quantities and prices match PO exactly",
+                "No actual duplicate -- this is a legitimate recurring service invoice",
+                "Vendor has 0 duplicate risk incidents",
+            ],
+        ),
+    )
+
+
+# -- Task 7: Retroactive Price Adjustment -----------------------------------
+# Difficulty: hard | Decision: escalate_for_supervisor_review | Exception: price_mismatch
+# Vendor had a contract price change effective 2024-11-01, but the PO was issued
+# at the old price on 2024-10-20. The invoice uses the NEW (higher) price.
+# Agent must notice the temporal mismatch: PO predates the price change, so the
+# PO price is the agreed-upon price. The invoice price exceeds tolerance.
+# Tests temporal reasoning and policy awareness.
+
+
+def _build_task_7() -> CaseData:
+    return CaseData(
+        case_id="CASE-7001",
+        task_id=TaskID.task_7_retroactive_price,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-1150",
+            supplier_name="Precision Parts Ltd",
+            supplier_id="SUP-7100",
+            invoice_date="2024-11-10",
+            po_reference="PO-7500",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-PP01",
+                    description="CNC Bearing Assembly Type-R",
+                    quantity_billed=200,
+                    unit_price_billed=47.50,
+                    line_total_billed=9500.00,
+                ),
+                InvoiceLineItem(
+                    item_code="ITEM-PP02",
+                    description="Hydraulic Seal Kit Grade-A",
+                    quantity_billed=500,
+                    unit_price_billed=12.80,
+                    line_total_billed=6400.00,
+                ),
+            ],
+            subtotal=15900.00,
+            tax=1272.00,
+            total_amount=17172.00,
+            note="Prices reflect updated catalog effective 2024-11-01.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-7500",
+            supplier_id="SUP-7100",
+            order_date="2024-10-20",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-PP01",
+                    description="CNC Bearing Assembly Type-R",
+                    ordered_quantity=200,
+                    unit_price_ordered=42.00,
+                    line_total_ordered=8400.00,
+                ),
+                POLineItem(
+                    item_code="ITEM-PP02",
+                    description="Hydraulic Seal Kit Grade-A",
+                    ordered_quantity=500,
+                    unit_price_ordered=11.50,
+                    line_total_ordered=5750.00,
+                ),
+            ],
+            payment_terms="Net 45",
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-12500",
+            po_reference="PO-7500",
+            receipt_date="2024-11-05",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-PP01",
+                    quantity_received=200,
+                    accepted_quantity=200,
+                ),
+                GRNLineItem(
+                    item_code="ITEM-PP02",
+                    quantity_received=500,
+                    accepted_quantity=500,
+                ),
+            ],
+            warehouse_note="All items received in good condition. Full order.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-7100",
+            supplier_name="Precision Parts Ltd",
+            risk_tier="medium",
+            duplicate_risk_count=0,
+            preferred_vendor=True,
+            escalation_threshold=15000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=500.0,
+            duplicate_check_enabled=True,
+            high_value_threshold=50000.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Vendor announced price increase effective 2024-11-01.",
+                "PO-7500 was placed on 2024-10-20 at the old catalog prices.",
+                "Contract terms: PO price governs unless amended before shipment.",
+            ],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.price_mismatch,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_price",
+                "inspect_policy_rules",
+                "inspect_vendor_profile",
+            ],
+            key_findings=[
+                "ITEM-PP01 billed at $47.50 vs PO price $42.00 (13.1% variance)",
+                "ITEM-PP02 billed at $12.80 vs PO price $11.50 (11.3% variance)",
+                "Both exceed 5% price tolerance",
+                "PO was issued 2024-10-20, before price change effective 2024-11-01",
+                "Per contract terms, PO price governs unless PO is amended",
+                "Invoice total $17,172 exceeds vendor escalation threshold $15,000",
+            ],
+        ),
+    )
+
+
+# -- Task 8: Adversarial Split-Invoice Pattern --------------------------------
+# Difficulty: hard | Decision: escalate_for_supervisor_review | Exception: policy_violation
+# Supplier splits a large order into multiple smaller invoices to stay below
+# the auto-approval threshold ($50,000). Each individual invoice looks clean,
+# but case history reveals a pattern of split invoicing from this vendor.
+# Agent must check vendor profile (high duplicate risk count) and case history
+# to detect the pattern. Tests cross-case pattern recognition.
+
+
+def _build_task_8() -> CaseData:
+    return CaseData(
+        case_id="CASE-8001",
+        task_id=TaskID.task_8_split_invoice_pattern,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-2210",
+            supplier_name="Global Tech Supplies",
+            supplier_id="SUP-8200",
+            invoice_date="2024-12-01",
+            po_reference="PO-8800",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-GT10",
+                    description="Enterprise Server Rack Unit 42U",
+                    quantity_billed=3,
+                    unit_price_billed=14500.00,
+                    line_total_billed=43500.00,
+                ),
+            ],
+            subtotal=43500.00,
+            tax=3480.00,
+            total_amount=46980.00,
+            note="Shipment 3 of 3. Final batch for data center buildout.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-8800",
+            supplier_id="SUP-8200",
+            order_date="2024-11-15",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-GT10",
+                    description="Enterprise Server Rack Unit 42U",
+                    ordered_quantity=3,
+                    unit_price_ordered=14500.00,
+                    line_total_ordered=43500.00,
+                ),
+            ],
+            payment_terms="Net 30",
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-15200",
+            po_reference="PO-8800",
+            receipt_date="2024-11-28",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-GT10",
+                    quantity_received=3,
+                    accepted_quantity=3,
+                ),
+            ],
+            warehouse_note="Final batch received. All 9 rack units now in inventory.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-8200",
+            supplier_name="Global Tech Supplies",
+            risk_tier="high",
+            duplicate_risk_count=4,
+            preferred_vendor=False,
+            escalation_threshold=40000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=500.0,
+            duplicate_check_enabled=True,
+            high_value_threshold=50000.00,
+            mandatory_escalation_above=100000.00,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "ALERT: Vendor SUP-8200 has submitted 3 invoices this month "
+                "for similar items across 3 separate POs (PO-8600, PO-8700, PO-8800).",
+                "Each invoice is just under the $50,000 auto-approval threshold.",
+                "Combined value: $46,200 + $47,800 + $46,980 = $140,980.",
+                "Finance team flagged potential invoice-splitting pattern.",
+                "Vendor is non-preferred with 4 prior risk incidents.",
+            ],
+            similar_invoice_refs=["INV-2024-2180", "INV-2024-2195"],
+            processed_invoice_numbers=["INV-2024-2180", "INV-2024-2195"],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.policy_violation,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "inspect_vendor_profile",
+                "inspect_policy_rules",
+                "check_for_duplicate_invoice",
+            ],
+            key_findings=[
+                "Invoice $46,980 is just under auto-approval threshold of $50,000",
+                "3 similar invoices from same vendor total $140,980",
+                "Vendor is high-risk tier with 4 prior risk incidents",
+                "Vendor is non-preferred",
+                "Case history explicitly flags split-invoice pattern concern",
+                "Combined value exceeds mandatory escalation threshold of $100,000",
+                "Individual prices and quantities match PO -- no line-level discrepancy",
+            ],
+        ),
+    )
+
+
+# -- Task 9: Clean Invoice from High-Risk Vendor ----------------------------
+# Difficulty: hard | Decision: approve_for_payment | Exception: clean_match
+# Every document matches perfectly. But the vendor is HIGH RISK with 5 prior
+# incidents and is non-preferred. The trap: agents escalate or reject based
+# on vendor risk alone. Per policy, risk tier affects escalation thresholds
+# for discrepancies, not clean invoices. No discrepancy = approve.
+
+
+def _build_task_9() -> CaseData:
+    return CaseData(
+        case_id="CASE-9001",
+        task_id=TaskID.task_9_clean_from_risky_vendor,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-3300",
+            supplier_name="Delta Industrial Components",
+            supplier_id="SUP-9300",
+            invoice_date="2024-12-10",
+            po_reference="PO-9200",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-DC01",
+                    description="Steel Flanged Coupling 6-inch",
+                    quantity_billed=50,
+                    unit_price_billed=85.00,
+                    line_total_billed=4250.00,
+                ),
+                InvoiceLineItem(
+                    item_code="ITEM-DC02",
+                    description="Gasket Kit Industrial Grade",
+                    quantity_billed=200,
+                    unit_price_billed=12.50,
+                    line_total_billed=2500.00,
+                ),
+            ],
+            subtotal=6750.00,
+            tax=540.00,
+            total_amount=7290.00,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-9200",
+            supplier_id="SUP-9300",
+            order_date="2024-11-25",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-DC01",
+                    description="Steel Flanged Coupling 6-inch",
+                    ordered_quantity=50,
+                    unit_price_ordered=85.00,
+                    line_total_ordered=4250.00,
+                ),
+                POLineItem(
+                    item_code="ITEM-DC02",
+                    description="Gasket Kit Industrial Grade",
+                    ordered_quantity=200,
+                    unit_price_ordered=12.50,
+                    line_total_ordered=2500.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-16000",
+            po_reference="PO-9200",
+            receipt_date="2024-12-05",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-DC01",
+                    quantity_received=50,
+                    accepted_quantity=50,
+                ),
+                GRNLineItem(
+                    item_code="ITEM-DC02",
+                    quantity_received=200,
+                    accepted_quantity=200,
+                ),
+            ],
+            warehouse_note="Full order received. Quality inspection passed.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-9300",
+            supplier_name="Delta Industrial Components",
+            risk_tier="high",
+            duplicate_risk_count=5,
+            preferred_vendor=False,
+            escalation_threshold=5000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Vendor under enhanced monitoring due to past billing errors.",
+                "Last 3 invoices from this vendor were all clean and processed normally.",
+                "Risk tier remains 'high' pending annual vendor review in Q1 2025.",
+            ],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_quantity",
+                "compare_price",
+                "inspect_vendor_profile",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "All quantities match exactly: 50 couplings and 200 gasket kits",
+                "All prices match PO exactly: $85.00 and $12.50",
+                "Vendor is high-risk but no actual discrepancy exists",
+                "Risk tier affects escalation thresholds, not clean invoices",
+                "Last 3 invoices from this vendor were processed normally",
+                "No policy rule mandates rejection of clean invoices from high-risk vendors",
+            ],
+        ),
+    )
+
+
+# -- Task 10: Rounding Error False Alarm ------------------------------------
+# Difficulty: hard | Decision: approve_for_payment | Exception: clean_match
+# Invoice total is $0.01 off from calculated sum of line items due to
+# per-line rounding. All line items match PO exactly. The trivial rounding
+# difference is well within any tolerance. Trap: compare_totals reports a
+# "mismatch" finding and agents escalate over one cent.
+
+
+def _build_task_10() -> CaseData:
+    return CaseData(
+        case_id="CASE-10001",
+        task_id=TaskID.task_10_rounding_false_alarm,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-4410",
+            supplier_name="Kensington Paper & Print",
+            supplier_id="SUP-10400",
+            invoice_date="2024-12-15",
+            po_reference="PO-10100",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-KP01",
+                    description="A4 Premium Copy Paper (case of 10 reams)",
+                    quantity_billed=33,
+                    unit_price_billed=42.99,
+                    line_total_billed=1418.67,
+                ),
+                InvoiceLineItem(
+                    item_code="ITEM-KP02",
+                    description="Color Laser Toner Cartridge Black",
+                    quantity_billed=7,
+                    unit_price_billed=189.99,
+                    line_total_billed=1329.93,
+                ),
+                InvoiceLineItem(
+                    item_code="ITEM-KP03",
+                    description="Binding Covers Glossy A4 (pack of 100)",
+                    quantity_billed=15,
+                    unit_price_billed=28.33,
+                    line_total_billed=424.95,
+                ),
+            ],
+            subtotal=3173.55,
+            tax=253.88,
+            total_amount=3427.43,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-10100",
+            supplier_id="SUP-10400",
+            order_date="2024-12-01",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-KP01",
+                    description="A4 Premium Copy Paper (case of 10 reams)",
+                    ordered_quantity=33,
+                    unit_price_ordered=42.99,
+                    line_total_ordered=1418.67,
+                ),
+                POLineItem(
+                    item_code="ITEM-KP02",
+                    description="Color Laser Toner Cartridge Black",
+                    ordered_quantity=7,
+                    unit_price_ordered=189.99,
+                    line_total_ordered=1329.93,
+                ),
+                POLineItem(
+                    item_code="ITEM-KP03",
+                    description="Binding Covers Glossy A4 (pack of 100)",
+                    ordered_quantity=15,
+                    unit_price_ordered=28.33,
+                    line_total_ordered=424.95,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-17500",
+            po_reference="PO-10100",
+            receipt_date="2024-12-10",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-KP01",
+                    quantity_received=33,
+                    accepted_quantity=33,
+                ),
+                GRNLineItem(
+                    item_code="ITEM-KP02",
+                    quantity_received=7,
+                    accepted_quantity=7,
+                ),
+                GRNLineItem(
+                    item_code="ITEM-KP03",
+                    quantity_received=15,
+                    accepted_quantity=15,
+                ),
+            ],
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-10400",
+            supplier_name="Kensington Paper & Print",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=100.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_quantity",
+                "compare_price",
+                "compare_totals",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "All quantities match exactly",
+                "All unit prices match PO exactly",
+                "Subtotal rounding difference of $0.01 is within tolerance",
+                "Total tolerance is $100.00 -- a $0.01 difference is negligible",
+                "Rounding is a normal artifact of multi-line calculation",
+                "Preferred vendor with low risk tier",
+            ],
+        ),
+    )
+
+
+# -- Task 11: Authorized Overship -------------------------------------------
+# Difficulty: hard | Decision: approve_for_payment | Exception: clean_match
+# GRN shows 110 units received vs 100 ordered. Invoice bills for 110.
+# Case history contains explicit authorization for up to 10% overship.
+# Trap: agents see quantity mismatch and hold. But the overship was
+# pre-authorized, making this a clean match per the authorization.
+
+
+def _build_task_11() -> CaseData:
+    return CaseData(
+        case_id="CASE-11001",
+        task_id=TaskID.task_11_authorized_overship,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-5520",
+            supplier_name="Pacific Coast Fasteners",
+            supplier_id="SUP-11500",
+            invoice_date="2024-12-18",
+            po_reference="PO-11300",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-PF01",
+                    description="M8 Hex Bolt Grade 8.8 Zinc Plated (box of 100)",
+                    quantity_billed=110,
+                    unit_price_billed=24.50,
+                    line_total_billed=2695.00,
+                ),
+            ],
+            subtotal=2695.00,
+            tax=215.60,
+            total_amount=2910.60,
+            note="Quantity includes authorized 10% overship per PO amendment.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-11300",
+            supplier_id="SUP-11500",
+            order_date="2024-12-01",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-PF01",
+                    description="M8 Hex Bolt Grade 8.8 Zinc Plated (box of 100)",
+                    ordered_quantity=100,
+                    unit_price_ordered=24.50,
+                    line_total_ordered=2450.00,
+                ),
+            ],
+            payment_terms="Net 30",
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-18800",
+            po_reference="PO-11300",
+            receipt_date="2024-12-12",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-PF01",
+                    quantity_received=110,
+                    accepted_quantity=110,
+                ),
+            ],
+            warehouse_note="110 boxes received. Overship authorized per buyer memo dated 2024-12-02.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-11500",
+            supplier_name="Pacific Coast Fasteners",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=500.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "PO-11300 Amendment 1 (2024-12-02): Authorized up to 10% overship "
+                "at the same unit price to ensure inventory buffer for Q1.",
+                "Buyer confirmed acceptance of up to 110 boxes at $24.50/box.",
+                "Warehouse confirmed receipt of full 110 boxes in good condition.",
+            ],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_quantity",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "Billed 110 vs ordered 100 -- 10% overship",
+                "PO Amendment 1 explicitly authorized up to 10% overship",
+                "Buyer confirmed acceptance of 110 units at $24.50",
+                "GRN confirms all 110 accepted in good condition",
+                "Unit price matches PO exactly",
+                "Overship is within the authorized range",
+            ],
+        ),
+    )
+
+
+# -- Task 12: Corrected Invoice Resubmission --------------------------------
+# Difficulty: hard | Decision: approve_for_payment | Exception: clean_match
+# Invoice number INV-2024-0500-R1 looks like a duplicate of INV-2024-0500.
+# Case history shows the original was rejected for a $500 overcharge, and
+# this is the corrected resubmission at the correct PO price. All documents
+# now match. Trap: duplicate check flags the similar invoice number, and
+# agents reject as duplicate without reading the correction context.
+
+
+def _build_task_12() -> CaseData:
+    return CaseData(
+        case_id="CASE-12001",
+        task_id=TaskID.task_12_corrected_resubmission,
+        difficulty=Difficulty.hard,
+        max_steps=12,
+        invoice=Invoice(
+            invoice_number="INV-2024-0500-R1",
+            supplier_name="Westfield Electronics",
+            supplier_id="SUP-12600",
+            invoice_date="2024-12-20",
+            po_reference="PO-12400",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-WE01",
+                    description="Industrial Ethernet Switch 24-Port PoE+",
+                    quantity_billed=5,
+                    unit_price_billed=1250.00,
+                    line_total_billed=6250.00,
+                ),
+                InvoiceLineItem(
+                    item_code="ITEM-WE02",
+                    description="SFP+ 10G Transceiver Module",
+                    quantity_billed=20,
+                    unit_price_billed=85.00,
+                    line_total_billed=1700.00,
+                ),
+            ],
+            subtotal=7950.00,
+            tax=636.00,
+            total_amount=8586.00,
+            note="Corrected invoice. Replaces INV-2024-0500 which was rejected for pricing error.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-12400",
+            supplier_id="SUP-12600",
+            order_date="2024-12-01",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-WE01",
+                    description="Industrial Ethernet Switch 24-Port PoE+",
+                    ordered_quantity=5,
+                    unit_price_ordered=1250.00,
+                    line_total_ordered=6250.00,
+                ),
+                POLineItem(
+                    item_code="ITEM-WE02",
+                    description="SFP+ 10G Transceiver Module",
+                    ordered_quantity=20,
+                    unit_price_ordered=85.00,
+                    line_total_ordered=1700.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-20100",
+            po_reference="PO-12400",
+            receipt_date="2024-12-10",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-WE01",
+                    quantity_received=5,
+                    accepted_quantity=5,
+                ),
+                GRNLineItem(
+                    item_code="ITEM-WE02",
+                    quantity_received=20,
+                    accepted_quantity=20,
+                ),
+            ],
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-12600",
+            supplier_name="Westfield Electronics",
+            risk_tier="medium",
+            duplicate_risk_count=1,
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "INV-2024-0500 was rejected on 2024-12-15: switches billed at $1,350 "
+                "instead of PO price $1,250. Vendor acknowledged error.",
+                "Vendor issued corrected invoice INV-2024-0500-R1 with correct pricing.",
+                "AP team confirmed: process INV-2024-0500-R1 as the replacement invoice.",
+            ],
+            processed_invoice_numbers=[],
+            similar_invoice_refs=["INV-2024-0500"],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "compare_price",
+                "check_for_duplicate_invoice",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "INV-2024-0500-R1 is the corrected version of rejected INV-2024-0500",
+                "Original invoice was rejected for $100/unit price overcharge on switches",
+                "Corrected invoice has the correct PO price of $1,250 per switch",
+                "All quantities and prices now match PO exactly",
+                "AP team explicitly approved processing the replacement invoice",
+                "Not a duplicate -- it is a correction of a rejected invoice",
+            ],
+        ),
+    )

tasks/hard_definitions.py

@@ -0,0 +1,1109 @@
+"""
+Round 2 hard-mode task slice for InvoiceGuard.
+
+These 10 tasks are designed for a *strong gap* baseline (~40-55%) so that
+RL training improvement is visible. Each task targets one of the Round 2
+themes: cross-case fraud, time-dependent policy, contradictory evidence,
+partial observability, multi-party approvals.
+
+All tasks reuse the existing CaseData entities so no schema changes are
+required. Adversarial context is conveyed via:
+  - invoice.note
+  - po.payment_terms
+  - grn.warehouse_note
+  - vendor_profile fields
+  - case_history.prior_comments  (surfaced by check_for_duplicate_invoice
+    when similar_invoice_refs is non-empty)
+"""
+
+from typing import Dict
+
+try:
+    from ..models import (
+        CaseData, CaseHistory, CompanyPolicy, DecisionType, Difficulty,
+        ExceptionType, GRNLineItem, GoodsReceiptNote, GroundTruth,
+        Invoice, InvoiceLineItem, POLineItem, PurchaseOrder,
+        TaskID, VendorProfile,
+    )
+except ImportError:
+    from models import (
+        CaseData, CaseHistory, CompanyPolicy, DecisionType, Difficulty,
+        ExceptionType, GRNLineItem, GoodsReceiptNote, GroundTruth,
+        Invoice, InvoiceLineItem, POLineItem, PurchaseOrder,
+        TaskID, VendorProfile,
+    )
+
+
+# Standardized step budget for hard-mode tasks. Slightly tighter than
+# canonical hard tasks (12) to reward efficient investigation.
+HARD_MAX_STEPS = 12
+
+
+# -- H1: Phantom GRN from a prior delivery cycle ----------------------------
+# Decision: place_on_hold | Exception: missing_receipt
+# The GRN attached to this PO is from an OLD shipment cycle (months earlier).
+# Vendor reuses old GRN numbers. compare_quantity will report all numbers
+# matching, but no goods were actually received for THIS invoice cycle.
+# Trap: agent runs compare_quantity, sees 100=100=100, and approves.
+
+def _build_h1() -> CaseData:
+    return CaseData(
+        case_id="CASE-H1-001",
+        task_id=TaskID.task_h1_phantom_grn_period,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9101",
+            supplier_name="Helix Industrial Supply",
+            supplier_id="SUP-H101",
+            invoice_date="2024-12-22",
+            po_reference="PO-H101-DEC",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-HX01",
+                    description="Industrial Lubricant 20L Drum",
+                    quantity_billed=100,
+                    unit_price_billed=180.00,
+                    line_total_billed=18000.00,
+                ),
+            ],
+            subtotal=18000.00,
+            tax=1440.00,
+            total_amount=19440.00,
+            note="Q4 restocking shipment. Please process per contract.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H101-DEC",
+            supplier_id="SUP-H101",
+            order_date="2024-12-01",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-HX01",
+                    description="Industrial Lubricant 20L Drum",
+                    ordered_quantity=100,
+                    unit_price_ordered=180.00,
+                    line_total_ordered=18000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H101-JUN",
+            po_reference="PO-H101-DEC",
+            receipt_date="2024-06-15",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-HX01",
+                    quantity_received=100,
+                    accepted_quantity=100,
+                ),
+            ],
+            warehouse_note=(
+                "WAREHOUSE FLAG: GRN-H101-JUN dated 2024-06-15 belongs to "
+                "prior shipment cycle (PO-H101-JUN, already invoiced and paid). "
+                "No fresh delivery has been logged against PO-H101-DEC. "
+                "Linkage to PO-H101-DEC appears to be a clerical error by vendor."
+            ),
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H101",
+            supplier_name="Helix Industrial Supply",
+            risk_tier="medium",
+            duplicate_risk_count=2,
+            preferred_vendor=False,
+            escalation_threshold=15000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "PO-H101-JUN was fully received (GRN-H101-JUN) and paid in July 2024.",
+                "Vendor has previously attached old GRN numbers to new POs to "
+                "accelerate payment before goods arrive.",
+            ],
+            similar_invoice_refs=["INV-2024-4500"],
+            processed_invoice_numbers=["INV-2024-4500"],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.place_on_hold,
+            correct_exception_type=ExceptionType.missing_receipt,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "check_for_duplicate_invoice",
+                "inspect_vendor_profile",
+            ],
+            key_findings=[
+                "GRN attached is dated 2024-06-15, predating PO-H101-DEC by 6 months",
+                "GRN-H101-JUN was already consumed by prior invoice INV-2024-4500",
+                "No fresh receipt exists for the December order",
+                "Cannot pay before goods are actually received",
+            ],
+        ),
+    )
+
+
+# -- H2: Kickback / Inflated PO --------------------------------------------
+# Decision: escalate_for_supervisor_review | Exception: policy_violation
+# Invoice price = PO price exactly. Quantities match. But case history reveals
+# internal audit found PO price ~30% above market and buyer recused. The
+# correct call is escalate, not approve.
+
+def _build_h2() -> CaseData:
+    return CaseData(
+        case_id="CASE-H2-001",
+        task_id=TaskID.task_h2_kickback_inflated_po,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9202",
+            supplier_name="Crestwave Engineering Pvt Ltd",
+            supplier_id="SUP-H202",
+            invoice_date="2024-12-19",
+            po_reference="PO-H202",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-CW20",
+                    description="Custom Aluminum Bracket Type-7",
+                    quantity_billed=400,
+                    unit_price_billed=85.00,
+                    line_total_billed=34000.00,
+                ),
+            ],
+            subtotal=34000.00,
+            tax=2720.00,
+            total_amount=36720.00,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H202",
+            supplier_id="SUP-H202",
+            order_date="2024-11-10",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-CW20",
+                    description="Custom Aluminum Bracket Type-7",
+                    ordered_quantity=400,
+                    unit_price_ordered=85.00,
+                    line_total_ordered=34000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H202",
+            po_reference="PO-H202",
+            receipt_date="2024-12-12",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-CW20",
+                    quantity_received=400,
+                    accepted_quantity=400,
+                ),
+            ],
+            warehouse_note="All units received and inspected.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H202",
+            supplier_name="Crestwave Engineering Pvt Ltd",
+            risk_tier="medium",
+            duplicate_risk_count=0,
+            preferred_vendor=False,
+            escalation_threshold=30000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=300.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "AUDIT FLAG (2024-12-15): PO-H202 unit price $85 is approx 30% "
+                "above benchmarked market price of $65 for ITEM-CW20.",
+                "Buyer who approved PO-H202 has been recused pending integrity review.",
+                "Per policy, all invoices against PO-H202 require supervisor review "
+                "before payment release.",
+            ],
+            similar_invoice_refs=["AUDIT-PO-H202"],
+            processed_invoice_numbers=[],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.policy_violation,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "check_for_duplicate_invoice",
+                "inspect_vendor_profile",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "Invoice and PO numerically match, but PO itself is under audit",
+                "PO unit price is ~30% above market benchmark",
+                "Approving buyer recused; mandatory supervisor review applies",
+                "Escalation required regardless of line-level match",
+            ],
+        ),
+    )
+
+
+# -- H3: Currency Silent Swap ---------------------------------------------
+# Decision: escalate_for_supervisor_review | Exception: total_amount_mismatch
+# Invoice currency is EUR while PO and historical billing are USD. Numbers
+# match by digit, but the invoiced amount in USD-equivalent is materially
+# different. Trap: compare_price reports a numerical match.
+
+def _build_h3() -> CaseData:
+    return CaseData(
+        case_id="CASE-H3-001",
+        task_id=TaskID.task_h3_currency_silent_swap,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9303",
+            supplier_name="Northbridge Components GmbH",
+            supplier_id="SUP-H303",
+            invoice_date="2024-12-17",
+            currency="EUR",
+            po_reference="PO-H303",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-NB15",
+                    description="Precision Linear Actuator 200mm",
+                    quantity_billed=80,
+                    unit_price_billed=125.00,
+                    line_total_billed=10000.00,
+                ),
+            ],
+            subtotal=10000.00,
+            tax=800.00,
+            total_amount=10800.00,
+            note="Standard monthly invoice. EUR billing per updated contract.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H303",
+            supplier_id="SUP-H303",
+            order_date="2024-11-20",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-NB15",
+                    description="Precision Linear Actuator 200mm",
+                    ordered_quantity=80,
+                    unit_price_ordered=125.00,
+                    line_total_ordered=10000.00,
+                ),
+            ],
+            payment_terms="Net 30 USD",
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H303",
+            po_reference="PO-H303",
+            receipt_date="2024-12-10",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-NB15",
+                    quantity_received=80,
+                    accepted_quantity=80,
+                ),
+            ],
+            warehouse_note="All units received in good condition.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H303",
+            supplier_name="Northbridge Components GmbH",
+            risk_tier="medium",
+            preferred_vendor=True,
+            escalation_threshold=12000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Vendor SUP-H303 has historically invoiced in USD against this PO family.",
+                "No contract amendment authorizing EUR billing is on file.",
+                "Current EUR-to-USD rate would make invoiced amount ~10% higher than PO USD value.",
+            ],
+            similar_invoice_refs=["INV-2024-7800"],
+            processed_invoice_numbers=["INV-2024-7800"],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.total_amount_mismatch,
+            acceptable_evidence=[
+                "inspect_invoice_line_items",
+                "inspect_purchase_order",
+                "check_for_duplicate_invoice",
+                "compare_totals",
+            ],
+            key_findings=[
+                "Invoice currency is EUR but PO is USD (no contract amendment)",
+                "Numerical line totals match but currency differs",
+                "USD-equivalent of EUR invoice is materially above PO total",
+                "Currency change requires supervisor approval per contract",
+            ],
+        ),
+    )
+
+
+# -- H4: Threshold Dance ---------------------------------------------------
+# Decision: escalate_for_supervisor_review | Exception: policy_violation
+# Invoice $49,950 sits just under $50k auto-approval threshold. Vendor has
+# 3 prior invoices in the same window all $49,9xx. Smaller cousin of task_8
+# but with a tighter margin so the pattern is harder to spot.
+
+def _build_h4() -> CaseData:
+    return CaseData(
+        case_id="CASE-H4-001",
+        task_id=TaskID.task_h4_threshold_dance,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9404",
+            supplier_name="Vector Distribution Co",
+            supplier_id="SUP-H404",
+            invoice_date="2024-12-21",
+            po_reference="PO-H404-D",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-VD30",
+                    description="Bulk Packaging Material Lot",
+                    quantity_billed=1,
+                    unit_price_billed=49950.00,
+                    line_total_billed=49950.00,
+                ),
+            ],
+            subtotal=49950.00,
+            tax=3996.00,
+            total_amount=53946.00,
+            note="Final delivery for Q4 packaging contract.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H404-D",
+            supplier_id="SUP-H404",
+            order_date="2024-12-05",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-VD30",
+                    description="Bulk Packaging Material Lot",
+                    ordered_quantity=1,
+                    unit_price_ordered=49950.00,
+                    line_total_ordered=49950.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H404-D",
+            po_reference="PO-H404-D",
+            receipt_date="2024-12-18",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-VD30",
+                    quantity_received=1,
+                    accepted_quantity=1,
+                ),
+            ],
+            warehouse_note="Full lot received.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H404",
+            supplier_name="Vector Distribution Co",
+            risk_tier="high",
+            duplicate_risk_count=3,
+            preferred_vendor=False,
+            escalation_threshold=40000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=300.0,
+            high_value_threshold=50000.0,
+            mandatory_escalation_above=100000.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "ALERT: SUP-H404 submitted 3 invoices in past 14 days at "
+                "$49,920 / $49,975 / $49,950 -- each just under $50k threshold.",
+                "Combined invoiced value across 4 invoices: ~$199,795.",
+                "PO numbering pattern (PO-H404-A/B/C/D) suggests deliberate split.",
+                "Finance integrity team flagged for review.",
+            ],
+            similar_invoice_refs=["INV-2024-9401", "INV-2024-9402", "INV-2024-9403"],
+            processed_invoice_numbers=["INV-2024-9401", "INV-2024-9402", "INV-2024-9403"],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.policy_violation,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "check_for_duplicate_invoice",
+                "inspect_vendor_profile",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "Invoice $49,950 sits $50 under auto-approval threshold",
+                "3 prior invoices from same vendor in past 14 days, all just under $50k",
+                "Combined value ~$199,795 well above mandatory escalation",
+                "High-risk vendor with 3 prior incidents",
+                "Pattern consistent with deliberate threshold evasion",
+            ],
+        ),
+    )
+
+
+# -- H5: Retroactive PO Amendment ------------------------------------------
+# Decision: escalate_for_supervisor_review | Exception: price_mismatch
+# PO line items show $100/unit. Invoice billed $100/unit. compare_price
+# reports a perfect match. But case_history reveals an amendment that
+# retroactively reduced agreed price to $80/unit.
+
+def _build_h5() -> CaseData:
+    return CaseData(
+        case_id="CASE-H5-001",
+        task_id=TaskID.task_h5_retroactive_amendment,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9505",
+            supplier_name="Solace Pharma Distribution",
+            supplier_id="SUP-H505",
+            invoice_date="2024-12-20",
+            po_reference="PO-H505",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-SP40",
+                    description="Diagnostic Reagent Kit Pro",
+                    quantity_billed=300,
+                    unit_price_billed=100.00,
+                    line_total_billed=30000.00,
+                ),
+            ],
+            subtotal=30000.00,
+            tax=2400.00,
+            total_amount=32400.00,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H505",
+            supplier_id="SUP-H505",
+            order_date="2024-11-05",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-SP40",
+                    description="Diagnostic Reagent Kit Pro",
+                    ordered_quantity=300,
+                    unit_price_ordered=100.00,
+                    line_total_ordered=30000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H505",
+            po_reference="PO-H505",
+            receipt_date="2024-12-12",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-SP40",
+                    quantity_received=300,
+                    accepted_quantity=300,
+                ),
+            ],
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H505",
+            supplier_name="Solace Pharma Distribution",
+            risk_tier="medium",
+            preferred_vendor=True,
+            escalation_threshold=25000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=300.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "PO-H505 Amendment 1 (2024-12-08): unit price retroactively reduced "
+                "from $100 to $80 per kit as part of annual rebate true-up.",
+                "Amendment is binding for all invoices dated after 2024-12-08.",
+                "Vendor was notified in writing on 2024-12-09 and acknowledged.",
+                "Effective PO total is now $24,000, not $30,000.",
+            ],
+            similar_invoice_refs=["AMENDMENT-PO-H505"],
+            processed_invoice_numbers=[],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.price_mismatch,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "check_for_duplicate_invoice",
+                "compare_price",
+                "inspect_policy_rules",
+            ],
+            key_findings=[
+                "PO line items show $100, invoice shows $100 -- looks aligned",
+                "PO Amendment 1 retroactively set agreed price to $80",
+                "Effective overcharge: $20 x 300 = $6,000",
+                "Supervisor must reconcile invoice against amended PO",
+            ],
+        ),
+    )
+
+
+# -- H6: Returned-Then-Rebilled --------------------------------------------
+# Decision: place_on_hold | Exception: quantity_mismatch
+# GRN shows received=100, accepted=100. compare_quantity reports OK.
+# But warehouse_note + case_history record that 30 units were returned
+# post-receipt as defective. Effective net accepted is 70.
+
+def _build_h6() -> CaseData:
+    return CaseData(
+        case_id="CASE-H6-001",
+        task_id=TaskID.task_h6_returned_then_rebilled,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9606",
+            supplier_name="Ironclad Hardware Co",
+            supplier_id="SUP-H606",
+            invoice_date="2024-12-22",
+            po_reference="PO-H606",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-IH50",
+                    description="Heavy-Duty Steel Coupling Set",
+                    quantity_billed=100,
+                    unit_price_billed=220.00,
+                    line_total_billed=22000.00,
+                ),
+            ],
+            subtotal=22000.00,
+            tax=1760.00,
+            total_amount=23760.00,
+            note="Full shipment billing. Per delivery receipt.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H606",
+            supplier_id="SUP-H606",
+            order_date="2024-11-15",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-IH50",
+                    description="Heavy-Duty Steel Coupling Set",
+                    ordered_quantity=100,
+                    unit_price_ordered=220.00,
+                    line_total_ordered=22000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H606",
+            po_reference="PO-H606",
+            receipt_date="2024-12-05",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-IH50",
+                    quantity_received=100,
+                    accepted_quantity=100,
+                ),
+            ],
+            warehouse_note=(
+                "POST-RECEIPT NOTE (2024-12-15): 30 units returned to vendor "
+                "due to QC failure (cracked welds). Net accepted in inventory: 70. "
+                "Return Material Authorization RMA-H606-01 issued."
+            ),
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H606",
+            supplier_name="Ironclad Hardware Co",
+            risk_tier="medium",
+            preferred_vendor=True,
+            escalation_threshold=20000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "RMA-H606-01 (2024-12-15): 30 units of ITEM-IH50 returned for QC failure.",
+                "Vendor acknowledged return and issued credit memo CM-H606-01.",
+                "Net deliverable for this PO: 70 units at $220 = $15,400.",
+                "Vendor invoiced full 100 units, ignoring credit memo.",
+            ],
+            similar_invoice_refs=["RMA-H606-01"],
+            processed_invoice_numbers=[],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.place_on_hold,
+            correct_exception_type=ExceptionType.quantity_mismatch,
+            acceptable_evidence=[
+                "inspect_goods_receipt_note",
+                "check_for_duplicate_invoice",
+                "compare_quantity",
+            ],
+            key_findings=[
+                "GRN shows 100 accepted at receipt, but 30 were returned post-receipt",
+                "Net inventory accepted is 70 units, not 100",
+                "Vendor issued credit memo CM-H606-01 acknowledging return",
+                "Invoice bills 100 units, ignoring the credit memo",
+                "Hold required until vendor reissues with credit applied",
+            ],
+        ),
+    )
+
+
+# -- H7: Multi-Party Approval Pending --------------------------------------
+# Decision: escalate_for_supervisor_review | Exception: policy_violation
+# Invoice $85,000. Policy: high_value_threshold=50k requires supervisor;
+# mandatory_escalation_above=80k requires CFO co-sign. CFO sign-off not on
+# file. All line-level matches are clean. Trap: agent approves because
+# everything matches.
+
+def _build_h7() -> CaseData:
+    return CaseData(
+        case_id="CASE-H7-001",
+        task_id=TaskID.task_h7_multi_party_pending,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9707",
+            supplier_name="Skyline Capital Equipment",
+            supplier_id="SUP-H707",
+            invoice_date="2024-12-21",
+            po_reference="PO-H707",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-SK60",
+                    description="Industrial Compressor Unit Model X",
+                    quantity_billed=1,
+                    unit_price_billed=85000.00,
+                    line_total_billed=85000.00,
+                ),
+            ],
+            subtotal=85000.00,
+            tax=6800.00,
+            total_amount=91800.00,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H707",
+            supplier_id="SUP-H707",
+            order_date="2024-11-25",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-SK60",
+                    description="Industrial Compressor Unit Model X",
+                    ordered_quantity=1,
+                    unit_price_ordered=85000.00,
+                    line_total_ordered=85000.00,
+                ),
+            ],
+            payment_terms="Net 45",
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H707",
+            po_reference="PO-H707",
+            receipt_date="2024-12-15",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-SK60",
+                    quantity_received=1,
+                    accepted_quantity=1,
+                ),
+            ],
+            warehouse_note="Unit installed and commissioned successfully.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H707",
+            supplier_name="Skyline Capital Equipment",
+            risk_tier="low",
+            preferred_vendor=True,
+            escalation_threshold=70000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=500.0,
+            high_value_threshold=50000.0,
+            mandatory_escalation_above=80000.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "Capex policy: invoices >= $80,000 require BOTH supervisor and CFO sign-off.",
+                "PO-H707 has supervisor sign-off (S. Patel, 2024-11-25).",
+                "CFO sign-off NOT on file; capex committee meets 2024-12-28.",
+                "Payment must wait for CFO approval per controls policy.",
+            ],
+            similar_invoice_refs=["CAPEX-POLICY-2024"],
+            processed_invoice_numbers=[],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.policy_violation,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_policy_rules",
+                "check_for_duplicate_invoice",
+                "inspect_vendor_profile",
+            ],
+            key_findings=[
+                "Invoice total $91,800 exceeds mandatory escalation threshold $80,000",
+                "Capex policy requires both supervisor AND CFO sign-off above $80k",
+                "Only supervisor sign-off currently on file",
+                "Payment cannot be released until CFO approval logged",
+            ],
+        ),
+    )
+
+
+# -- H8: Rush Premium Authorized -------------------------------------------
+# Decision: approve_for_payment | Exception: clean_match
+# Invoice price 8% over PO -- normally a price_mismatch escalation.
+# But invoice.note + warehouse_note + case_history all confirm a buyer-
+# approved 8% rush surcharge per a PO amendment. Trap: compare_price flags
+# discrepancy and agent escalates.
+
+def _build_h8() -> CaseData:
+    return CaseData(
+        case_id="CASE-H8-001",
+        task_id=TaskID.task_h8_rush_premium_authorized,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9808",
+            supplier_name="Falcon Express Components",
+            supplier_id="SUP-H808",
+            invoice_date="2024-12-20",
+            po_reference="PO-H808",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-FE70",
+                    description="Aviation-Grade Fastener Pack",
+                    quantity_billed=200,
+                    unit_price_billed=54.00,
+                    line_total_billed=10800.00,
+                ),
+            ],
+            subtotal=10800.00,
+            tax=864.00,
+            total_amount=11664.00,
+            note=(
+                "Includes 8% rush surcharge per PO-H808 Amendment 1 dated 2024-12-05 "
+                "(buyer-approved expedited shipping). Base price unchanged at $50.00."
+            ),
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H808",
+            supplier_id="SUP-H808",
+            order_date="2024-12-01",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-FE70",
+                    description="Aviation-Grade Fastener Pack",
+                    ordered_quantity=200,
+                    unit_price_ordered=50.00,
+                    line_total_ordered=10000.00,
+                ),
+            ],
+            payment_terms="Net 30",
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H808",
+            po_reference="PO-H808",
+            receipt_date="2024-12-12",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-FE70",
+                    quantity_received=200,
+                    accepted_quantity=200,
+                ),
+            ],
+            warehouse_note=(
+                "Expedited delivery received per buyer's rush request. "
+                "8% surcharge authorized in PO-H808 Amendment 1."
+            ),
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H808",
+            supplier_name="Falcon Express Components",
+            risk_tier="low",
+            preferred_vendor=True,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "PO-H808 Amendment 1 (2024-12-05): buyer authorized up to 10% rush "
+                "surcharge for expedited delivery on this order.",
+                "Expedited shipping was specifically requested due to production line outage.",
+                "Surcharge of 8% is within authorized range.",
+            ],
+            similar_invoice_refs=["PO-H808-AMD1"],
+            processed_invoice_numbers=[],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.approve_for_payment,
+            correct_exception_type=ExceptionType.clean_match,
+            acceptable_evidence=[
+                "inspect_invoice_line_items",
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "check_for_duplicate_invoice",
+            ],
+            key_findings=[
+                "Unit price $54 vs base PO $50 = 8% above PO line price",
+                "PO Amendment 1 explicitly authorized up to 10% rush surcharge",
+                "Surcharge applied is within authorized range",
+                "Quantities and delivery match exactly",
+                "Surface price variance is contractually authorized",
+            ],
+        ),
+    )
+
+
+# -- H9: Supplier ID Mismatch ----------------------------------------------
+# Decision: reject_invoice | Exception: policy_violation
+# Invoice supplier_id is similar but NOT identical to PO supplier_id.
+# Vendor profile (looked up by invoice's id) shows it's a different entity
+# with high-risk fraud history. Names look similar -- a phishing-style
+# attempt to redirect payment.
+
+def _build_h9() -> CaseData:
+    return CaseData(
+        case_id="CASE-H9-001",
+        task_id=TaskID.task_h9_supplier_id_mismatch,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9909",
+            supplier_name="Acme Industrial Solutions",
+            supplier_id="SUP-H909-X",
+            invoice_date="2024-12-22",
+            po_reference="PO-H909",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-AI80",
+                    description="Industrial Pump Assembly",
+                    quantity_billed=10,
+                    unit_price_billed=2200.00,
+                    line_total_billed=22000.00,
+                ),
+            ],
+            subtotal=22000.00,
+            tax=1760.00,
+            total_amount=23760.00,
+            note="Please remit to updated bank account. Supplier ID corrected per recent re-registration.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-H909",
+            supplier_id="SUP-H909",
+            order_date="2024-11-20",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-AI80",
+                    description="Industrial Pump Assembly",
+                    ordered_quantity=10,
+                    unit_price_ordered=2200.00,
+                    line_total_ordered=22000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-H909",
+            po_reference="PO-H909",
+            receipt_date="2024-12-12",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-AI80",
+                    quantity_received=10,
+                    accepted_quantity=10,
+                ),
+            ],
+            warehouse_note="Goods received from original vendor (SUP-H909).",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-H909-X",
+            supplier_name="Acme Industrial Solutions",
+            risk_tier="high",
+            duplicate_risk_count=4,
+            preferred_vendor=False,
+            escalation_threshold=5000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "FRAUD ALERT: SUP-H909-X is a flagged shell supplier under investigation.",
+                "Original PO-H909 was issued to legitimate supplier SUP-H909.",
+                "Goods were received from SUP-H909 (legitimate). Invoice arrived from SUP-H909-X.",
+                "Bank-redirect attempts have been observed for this supplier family in past 90 days.",
+                "Reject and refer to fraud team. Do NOT pay SUP-H909-X.",
+            ],
+            similar_invoice_refs=["FRAUD-SUP-H909-X"],
+            processed_invoice_numbers=[],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.reject_invoice,
+            correct_exception_type=ExceptionType.policy_violation,
+            acceptable_evidence=[
+                "inspect_invoice_line_items",
+                "inspect_purchase_order",
+                "inspect_vendor_profile",
+                "check_for_duplicate_invoice",
+            ],
+            key_findings=[
+                "Invoice supplier_id SUP-H909-X does not match PO supplier_id SUP-H909",
+                "Vendor profile flags SUP-H909-X as high-risk shell supplier under fraud investigation",
+                "Goods were physically delivered by legitimate SUP-H909 (per GRN note)",
+                "Invoice attempts to redirect payment to fraud-flagged entity",
+                "Mandatory rejection and referral to fraud team",
+            ],
+        ),
+    )
+
+
+# -- H10: Cross-Case Contradiction -----------------------------------------
+# Decision: escalate_for_supervisor_review | Exception: mixed_discrepancy
+# Quantity discrepancy (partial receipt -> hold signal) AND duplicate
+# suspicion (-> reject signal). Both contradict each other; per policy
+# escalation supersedes both individual signals. Tests reconciliation under
+# conflicting evidence.
+
+def _build_h10() -> CaseData:
+    return CaseData(
+        case_id="CASE-H10-001",
+        task_id=TaskID.task_h10_cross_case_contradiction,
+        difficulty=Difficulty.hard,
+        max_steps=HARD_MAX_STEPS,
+        invoice=Invoice(
+            invoice_number="INV-2024-9A10",
+            supplier_name="Ridgepoint Industrial Corp",
+            supplier_id="SUP-HA10",
+            invoice_date="2024-12-22",
+            po_reference="PO-HA10",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITEM-RP90",
+                    description="Composite Reinforcement Panel",
+                    quantity_billed=100,
+                    unit_price_billed=160.00,
+                    line_total_billed=16000.00,
+                ),
+            ],
+            subtotal=16000.00,
+            tax=1280.00,
+            total_amount=17280.00,
+            note="Final delivery for Q4 build-out. Please process per terms.",
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-HA10",
+            supplier_id="SUP-HA10",
+            order_date="2024-11-18",
+            line_items=[
+                POLineItem(
+                    item_code="ITEM-RP90",
+                    description="Composite Reinforcement Panel",
+                    ordered_quantity=100,
+                    unit_price_ordered=160.00,
+                    line_total_ordered=16000.00,
+                ),
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-HA10",
+            po_reference="PO-HA10",
+            receipt_date="2024-12-10",
+            line_items=[
+                GRNLineItem(
+                    item_code="ITEM-RP90",
+                    quantity_received=80,
+                    accepted_quantity=80,
+                    rejected_quantity=0,
+                ),
+            ],
+            warehouse_note="Partial shipment: 20 units short. Backorder pending.",
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-HA10",
+            supplier_name="Ridgepoint Industrial Corp",
+            risk_tier="high",
+            duplicate_risk_count=3,
+            preferred_vendor=False,
+            escalation_threshold=12000.00,
+        ),
+        company_policy=CompanyPolicy(
+            quantity_tolerance_pct=5.0,
+            price_tolerance_pct=5.0,
+            total_tolerance_amt=200.0,
+            duplicate_check_enabled=True,
+        ),
+        case_history=CaseHistory(
+            prior_comments=[
+                "INV-2024-9A05 (similar amount, same PO family) processed 2024-12-08.",
+                "Vendor flagged for prior duplicate-resubmission incidents.",
+                "Note: signals point in conflicting directions -- partial receipt suggests "
+                "hold, but duplicate suspicion suggests reject. Policy escalation hierarchy: "
+                "ESCALATE supersedes HOLD and REJECT when conflicting signals coexist.",
+            ],
+            similar_invoice_refs=["INV-2024-9A05"],
+            processed_invoice_numbers=["INV-2024-9A05"],
+        ),
+        ground_truth=GroundTruth(
+            correct_decision=DecisionType.escalate_for_supervisor_review,
+            correct_exception_type=ExceptionType.mixed_discrepancy,
+            acceptable_evidence=[
+                "inspect_purchase_order",
+                "inspect_goods_receipt_note",
+                "check_for_duplicate_invoice",
+                "compare_quantity",
+                "inspect_policy_rules",
+                "inspect_vendor_profile",
+            ],
+            key_findings=[
+                "Quantity discrepancy: billed 100 vs received 80 (20% short)",
+                "Possible duplicate: similar invoice INV-2024-9A05 already processed",
+                "Vendor is high-risk with 3 prior incidents",
+                "Conflicting signals: hold (partial) vs reject (duplicate)",
+                "Per policy hierarchy, escalation supersedes both",
+            ],
+        ),
+    )
+
+
+# -- Dispatch table --------------------------------------------------------
+
+HARD_TASK_LIST = [
+    TaskID.task_h1_phantom_grn_period,
+    TaskID.task_h2_kickback_inflated_po,
+    TaskID.task_h3_currency_silent_swap,
+    TaskID.task_h4_threshold_dance,
+    TaskID.task_h5_retroactive_amendment,
+    TaskID.task_h6_returned_then_rebilled,
+    TaskID.task_h7_multi_party_pending,
+    TaskID.task_h8_rush_premium_authorized,
+    TaskID.task_h9_supplier_id_mismatch,
+    TaskID.task_h10_cross_case_contradiction,
+]
+
+
+HARD_TASK_BUILDERS: Dict[TaskID, callable] = {
+    TaskID.task_h1_phantom_grn_period: _build_h1,
+    TaskID.task_h2_kickback_inflated_po: _build_h2,
+    TaskID.task_h3_currency_silent_swap: _build_h3,
+    TaskID.task_h4_threshold_dance: _build_h4,
+    TaskID.task_h5_retroactive_amendment: _build_h5,
+    TaskID.task_h6_returned_then_rebilled: _build_h6,
+    TaskID.task_h7_multi_party_pending: _build_h7,
+    TaskID.task_h8_rush_premium_authorized: _build_h8,
+    TaskID.task_h9_supplier_id_mismatch: _build_h9,
+    TaskID.task_h10_cross_case_contradiction: _build_h10,
+}

test_live_space.py

@@ -0,0 +1,238 @@
+"""
+Simulate judge evaluation against the live HF Space with LLM agent.
+Connects to the deployed Space and runs all tasks using OpenAI API.
+"""
+import asyncio
+import json
+import os
+import sys
+import time
+from typing import List, Optional
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+from client import InvoiceGuardEnv
+from models import (
+    ActionType, DecisionType, ExceptionType, InvoiceGuardAction,
+)
+
+load_dotenv()
+
+SPACE_URL = "https://piyush-mk-invoice-guard.hf.space"
+API_BASE_URL = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4.1-mini")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY") or os.getenv("OPENAI_API_KEY") or ""
+
+TASKS = [
+    "task_1_clean_match",
+    "task_2_partial_receipt",
+    "task_3_price_variance",
+    "task_4_duplicate_invoice",
+    "task_5_mixed_discrepancy",
+    "task_6_false_positive_duplicate",
+    "task_7_retroactive_price",
+    "task_8_split_invoice_pattern",
+    "task_9_clean_from_risky_vendor",
+    "task_10_rounding_false_alarm",
+    "task_11_authorized_overship",
+    "task_12_corrected_resubmission",
+]
+
+_MODELS_MAX_COMPLETION_TOKENS = {"gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5", "gpt-5-mini", "gpt-5.1"}
+
+def _tok_kwarg(limit=512):
+    for p in _MODELS_MAX_COMPLETION_TOKENS:
+        if MODEL_NAME.startswith(p):
+            return {"max_completion_tokens": limit}
+    return {"max_tokens": limit}
+
+SYSTEM_PROMPT = """You are a senior accounts payable analyst. You will be given an invoice case to investigate and resolve.
+
+The environment tells you your goal, available actions, and decision options. Read the goal carefully.
+
+WORKFLOW:
+1. Investigate: inspect documents (PO, GRN, vendor profile, policy rules), run comparisons (quantity, price, totals), check for duplicates.
+2. Resolve: submit_final_resolution with your decision, exception type, evidence references, and explanation.
+
+Complete a thorough investigation before resolving. Inspect at least: purchase order, goods receipt note, compare quantity, compare price, policy rules, duplicate check, and vendor profile.
+
+RESPONSE FORMAT:
+- Respond with ONLY a valid JSON object. No markdown, no commentary.
+- Investigation example: {"action_type": "inspect_purchase_order"}
+- Resolution example: {"action_type": "submit_final_resolution", "final_decision": "approve_for_payment", "exception_type": "clean_match", "evidence_references": ["inspect_purchase_order", "compare_quantity"], "explanation": "All documents match within tolerance."}
+
+RULES:
+- Pay close attention to POLICY findings -- they tell you when escalation is required.
+- When multiple issues exist, escalation takes priority over hold.
+- Check PO references carefully before concluding an invoice is a duplicate.
+- Include all investigation actions you performed in evidence_references.
+- Cite specific numbers in your explanation.
+- NEVER repeat an action you already took.
+- When remaining_steps is 3 or fewer, submit immediately with what you have.
+"""
+
+
+def build_observation_prompt(obs, is_first=False):
+    parts = [
+        f"Case: {obs.case_id} | Difficulty: {obs.difficulty} | Steps remaining: {obs.remaining_steps}",
+        f"Invoice: {obs.invoice_summary}",
+    ]
+    if is_first and obs.goal:
+        parts.append(f"\n{obs.goal}")
+    if obs.revealed_documents:
+        parts.append(f"Documents reviewed: {', '.join(obs.revealed_documents)}")
+    if obs.findings:
+        parts.append("Findings:")
+        for i, f in enumerate(obs.findings, 1):
+            parts.append(f"  {i}. {f}")
+    if obs.last_action_result:
+        parts.append(f"Last result: {obs.last_action_result}")
+    if obs.warnings:
+        parts.append(f"Warnings: {'; '.join(obs.warnings)}")
+    if obs.remaining_steps <= 2:
+        parts.append(">>> YOU MUST submit_final_resolution NOW. Decide based on what you have. <<<")
+    return "\n".join(parts)
+
+
+def parse_llm_response(text):
+    text = text.strip()
+    if "```json" in text:
+        text = text.split("```json")[1].split("```")[0].strip()
+    elif "```" in text:
+        text = text.split("```")[1].split("```")[0].strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    for line in text.split("\n"):
+        line = line.strip()
+        if line.startswith("{"):
+            try:
+                return json.loads(line)
+            except json.JSONDecodeError:
+                continue
+    return {"action_type": "summarize_findings"}
+
+
+def build_action(params):
+    action_type = params.get("action_type", "summarize_findings")
+    try:
+        ActionType(action_type)
+    except ValueError:
+        action_type = "summarize_findings"
+    kwargs = {"action_type": action_type}
+    if params.get("final_decision"):
+        try:
+            kwargs["final_decision"] = DecisionType(params["final_decision"])
+        except ValueError:
+            pass
+    if params.get("exception_type"):
+        try:
+            kwargs["exception_type"] = ExceptionType(params["exception_type"])
+        except ValueError:
+            pass
+    if params.get("evidence_references"):
+        kwargs["evidence_references"] = list(params["evidence_references"])
+    if params.get("explanation"):
+        kwargs["explanation"] = str(params["explanation"])
+    return InvoiceGuardAction(**kwargs)
+
+
+async def run_task(env, llm, task_id):
+    result = await env.reset(task_id=task_id)
+    obs = result.observation
+    obs.done = result.done
+    obs.reward = result.reward
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    steps = 0
+    rewards = []
+
+    print(f"  [RESET] case={obs.case_id} difficulty={obs.difficulty} steps={obs.remaining_steps}")
+
+    while not obs.done:
+        user_msg = build_observation_prompt(obs, is_first=(steps == 0))
+        messages.append({"role": "user", "content": user_msg})
+
+        try:
+            api_kwargs = {"model": MODEL_NAME, "messages": messages, "temperature": 0.0, **_tok_kwarg()}
+            try:
+                api_kwargs["response_format"] = {"type": "json_object"}
+                response = llm.chat.completions.create(**api_kwargs)
+            except Exception:
+                del api_kwargs["response_format"]
+                response = llm.chat.completions.create(**api_kwargs)
+            assistant_msg = response.choices[0].message.content or ""
+        except Exception as e:
+            print(f"  [LLM ERROR] {e}")
+            assistant_msg = '{"action_type": "summarize_findings"}'
+
+        messages.append({"role": "assistant", "content": assistant_msg})
+
+        params = parse_llm_response(assistant_msg)
+        action = build_action(params)
+
+        result = await env.step(action)
+        obs = result.observation
+        obs.done = result.done
+        obs.reward = result.reward
+        reward = result.reward or 0.0
+        rewards.append(reward)
+        steps += 1
+
+        status = "ERR" if obs.last_action_error else "ok"
+        print(f"  [STEP {steps:2d}] {action.action_type.value:35s} reward={reward:+.2f} remain={obs.remaining_steps} {status}")
+
+    grader = getattr(obs, "grader_result", {}) or {}
+    score = grader.get("score", 0.0) if isinstance(grader, dict) else 0.0
+    decision = params.get("final_decision", "none")
+
+    return {"task_id": task_id, "steps": steps, "score": score, "decision": decision, "rewards": rewards}
+
+
+async def main():
+    print("=" * 65)
+    print("  JUDGE SIMULATION -- Live HF Space + LLM Agent")
+    print(f"  Space:  {SPACE_URL}")
+    print(f"  Model:  {MODEL_NAME}")
+    print(f"  API:    {API_BASE_URL}")
+    print("=" * 65)
+
+    llm = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    env = InvoiceGuardEnv(base_url=SPACE_URL)
+
+    results = []
+    try:
+        async with env:
+            for task_id in TASKS:
+                print(f"\n--- {task_id} ---")
+                start = time.time()
+                try:
+                    r = await run_task(env, llm, task_id)
+                    r["time"] = time.time() - start
+                    results.append(r)
+                    print(f"  >> score={r['score']:.4f}  decision={r['decision']}  time={r['time']:.1f}s")
+                except Exception as e:
+                    print(f"  >> FAILED: {e}")
+                    results.append({"task_id": task_id, "score": 0.0, "steps": 0, "error": str(e)})
+    except Exception as e:
+        print(f"\nConnection error: {e}")
+        sys.exit(1)
+
+    print(f"\n\n{'='*65}")
+    print("  RESULTS SUMMARY")
+    print(f"{'='*65}")
+    scores = []
+    for r in results:
+        s = r.get("score", 0.0)
+        scores.append(s)
+        dec = r.get("decision", "n/a")
+        print(f"  {r['task_id']:40s} score={s:.4f}  decision={dec}")
+    avg = sum(scores) / len(scores) if scores else 0.0
+    print(f"\n  Average score:  {avg:.4f}")
+    print(f"  Tasks passed:   {sum(1 for s in scores if s >= 0.5)}/{len(scores)}")
+    print(f"{'='*65}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/test_environment.py

@@ -0,0 +1,219 @@
+"""Tests for the InvoiceGuard environment."""
+
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from models import (
+    ActionType,
+    DecisionType,
+    ExceptionType,
+    InvoiceGuardAction,
+    TaskID,
+)
+from server.invoice_guard_environment import InvoiceGuardEnvironment
+
+
+def _make_env():
+    return InvoiceGuardEnvironment()
+
+
+class TestReset:
+    def test_reset_returns_observation(self):
+        env = _make_env()
+        obs = env.reset(task_id="task_1_clean_match")
+        assert obs.case_id != ""
+        assert obs.task_id == "task_1_clean_match"
+        assert obs.difficulty == "easy"
+        assert obs.done is False
+
+    def test_reset_provides_goal(self):
+        env = _make_env()
+        obs = env.reset(task_id="task_1_clean_match")
+        assert "accounts payable" in obs.goal.lower()
+        assert len(obs.goal) > 100
+
+    def test_reset_provides_suggested_actions(self):
+        env = _make_env()
+        obs = env.reset(task_id="task_1_clean_match")
+        assert len(obs.suggested_next_actions) > 0
+        assert "inspect_purchase_order" in obs.suggested_next_actions
+
+    def test_reset_has_available_actions(self):
+        env = _make_env()
+        obs = env.reset(task_id="task_1_clean_match")
+        assert len(obs.available_actions) == 12
+        assert "submit_final_resolution" in obs.available_actions
+
+    def test_reset_clean_state(self):
+        env = _make_env()
+        obs = env.reset(task_id="task_1_clean_match")
+        assert obs.revealed_documents == []
+        assert obs.findings == []
+        assert obs.remaining_steps > 0
+
+    def test_reset_sequential_tasks(self):
+        env = _make_env()
+        obs1 = env.reset()
+        obs2 = env.reset()
+        assert obs1.task_id != obs2.task_id or obs1.case_id != obs2.case_id
+
+    def test_all_canonical_tasks_load(self):
+        env = _make_env()
+        canonical = [
+            "task_1_clean_match",
+            "task_2_partial_receipt",
+            "task_3_price_variance",
+            "task_4_duplicate_invoice",
+            "task_5_mixed_discrepancy",
+            "task_6_false_positive_duplicate",
+            "task_7_retroactive_price",
+            "task_8_split_invoice_pattern",
+            "task_9_clean_from_risky_vendor",
+            "task_10_rounding_false_alarm",
+            "task_11_authorized_overship",
+            "task_12_corrected_resubmission",
+        ]
+        for tid in canonical:
+            obs = env.reset(task_id=tid)
+            assert obs.task_id == tid
+            assert obs.done is False
+
+
+class TestStep:
+    def test_investigation_action(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        action = InvoiceGuardAction(action_type=ActionType.inspect_purchase_order)
+        obs = env.step(action)
+        assert obs.done is False
+        assert "purchase_order" in obs.revealed_documents
+        assert obs.reward > 0
+
+    def test_repeated_action_penalty(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        action = InvoiceGuardAction(action_type=ActionType.inspect_purchase_order)
+        obs1 = env.step(action)
+        obs2 = env.step(action)
+        assert obs2.reward < obs1.reward
+
+    def test_step_decrements_remaining(self):
+        env = _make_env()
+        obs = env.reset(task_id="task_1_clean_match")
+        initial = obs.remaining_steps
+        action = InvoiceGuardAction(action_type=ActionType.inspect_purchase_order)
+        obs = env.step(action)
+        assert obs.remaining_steps == initial - 1
+
+    def test_suggested_actions_update_after_step(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        action = InvoiceGuardAction(action_type=ActionType.inspect_purchase_order)
+        obs = env.step(action)
+        assert "inspect_purchase_order" not in obs.suggested_next_actions
+
+    def test_findings_accumulate(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        a1 = InvoiceGuardAction(action_type=ActionType.inspect_purchase_order)
+        env.step(a1)
+        a2 = InvoiceGuardAction(action_type=ActionType.inspect_goods_receipt_note)
+        env.step(a2)
+        a3 = InvoiceGuardAction(action_type=ActionType.compare_quantity)
+        obs = env.step(a3)
+        assert len(obs.findings) > 0
+
+
+class TestSubmission:
+    def test_correct_resolution(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        env.step(InvoiceGuardAction(action_type=ActionType.inspect_purchase_order))
+        env.step(InvoiceGuardAction(action_type=ActionType.inspect_goods_receipt_note))
+        env.step(InvoiceGuardAction(action_type=ActionType.compare_quantity))
+
+        action = InvoiceGuardAction(
+            action_type=ActionType.submit_final_resolution,
+            final_decision=DecisionType.approve_for_payment,
+            exception_type=ExceptionType.clean_match,
+            evidence_references=["inspect_purchase_order", "compare_quantity"],
+            explanation="All quantities and prices match within tolerance.",
+        )
+        obs = env.step(action)
+        assert obs.done is True
+        assert obs.reward > 0
+        assert obs.grader_result.get("score", 0) > 0.5
+
+    def test_wrong_decision_lower_score(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        env.step(InvoiceGuardAction(action_type=ActionType.inspect_purchase_order))
+
+        action = InvoiceGuardAction(
+            action_type=ActionType.submit_final_resolution,
+            final_decision=DecisionType.reject_invoice,
+            exception_type=ExceptionType.duplicate_invoice,
+            evidence_references=["inspect_purchase_order"],
+            explanation="Rejecting invoice.",
+        )
+        obs = env.step(action)
+        assert obs.done is True
+        assert obs.grader_result.get("score", 1) < 0.5
+
+    def test_missing_fields_returns_error(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        action = InvoiceGuardAction(
+            action_type=ActionType.submit_final_resolution,
+        )
+        obs = env.step(action)
+        assert obs.last_action_error is True or obs.last_action_result != ""
+
+
+class TestState:
+    def test_state_accessible(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        state = env.state
+        assert state.task_id == "task_1_clean_match"
+        assert state.step_count == 0
+
+    def test_state_tracks_actions(self):
+        env = _make_env()
+        env.reset(task_id="task_1_clean_match")
+        env.step(InvoiceGuardAction(action_type=ActionType.inspect_purchase_order))
+        env.step(InvoiceGuardAction(action_type=ActionType.compare_quantity))
+        state = env.state
+        assert "inspect_purchase_order" in state.actions_taken
+        assert "compare_quantity" in state.actions_taken
+        assert state.step_count == 2
+
+
+class TestTaskDiversity:
+    def test_scores_in_valid_range(self):
+        """Verify all tasks produce grader scores in [0, 1]."""
+        env = _make_env()
+        for tid in [
+            "task_1_clean_match",
+            "task_2_partial_receipt",
+            "task_3_price_variance",
+            "task_4_duplicate_invoice",
+            "task_5_mixed_discrepancy",
+            "task_6_false_positive_duplicate",
+        ]:
+            env.reset(task_id=tid)
+            env.step(InvoiceGuardAction(action_type=ActionType.inspect_purchase_order))
+            obs = env.step(
+                InvoiceGuardAction(
+                    action_type=ActionType.submit_final_resolution,
+                    final_decision=DecisionType.approve_for_payment,
+                    exception_type=ExceptionType.clean_match,
+                    evidence_references=["inspect_purchase_order"],
+                    explanation="Approving.",
+                )
+            )
+            assert obs.done is True
+            score = obs.grader_result.get("score", -1)
+            assert 0.0 <= score <= 1.0

tests/test_grader.py

@@ -0,0 +1,240 @@
+"""Tests for the InvoiceGuard grading system."""
+
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from models import (
+    CaseData,
+    CaseHistory,
+    CompanyPolicy,
+    DecisionType,
+    Difficulty,
+    ExceptionType,
+    GRNLineItem,
+    GoodsReceiptNote,
+    GroundTruth,
+    Invoice,
+    InvoiceGuardState,
+    InvoiceLineItem,
+    POLineItem,
+    PurchaseOrder,
+    TaskID,
+    VendorProfile,
+)
+from graders.scoring import grade_episode, _score_explanation
+
+
+def _make_case(
+    correct_decision=DecisionType.approve_for_payment,
+    correct_exception=ExceptionType.clean_match,
+    acceptable_evidence=None,
+    key_findings=None,
+    max_steps=10,
+):
+    return CaseData(
+        case_id="TEST-001",
+        task_id=TaskID.task_1_clean_match,
+        difficulty=Difficulty.easy,
+        max_steps=max_steps,
+        invoice=Invoice(
+            invoice_number="INV-001",
+            supplier_name="Test",
+            supplier_id="SUP-001",
+            invoice_date="2024-01-01",
+            po_reference="PO-001",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="A",
+                    description="Widget",
+                    quantity_billed=10,
+                    unit_price_billed=5.0,
+                    line_total_billed=50.0,
+                )
+            ],
+            subtotal=50.0,
+            tax=5.0,
+            total_amount=55.0,
+        ),
+        purchase_order=PurchaseOrder(
+            po_number="PO-001",
+            supplier_id="SUP-001",
+            order_date="2024-01-01",
+            line_items=[
+                POLineItem(
+                    item_code="A",
+                    description="Widget",
+                    ordered_quantity=10,
+                    unit_price_ordered=5.0,
+                    line_total_ordered=50.0,
+                )
+            ],
+        ),
+        goods_receipt_note=GoodsReceiptNote(
+            grn_number="GRN-001",
+            po_reference="PO-001",
+            receipt_date="2024-01-05",
+            line_items=[
+                GRNLineItem(
+                    item_code="A",
+                    quantity_received=10,
+                    accepted_quantity=10,
+                )
+            ],
+        ),
+        vendor_profile=VendorProfile(
+            supplier_id="SUP-001",
+            supplier_name="Test",
+            risk_tier="low",
+        ),
+        company_policy=CompanyPolicy(),
+        case_history=CaseHistory(),
+        ground_truth=GroundTruth(
+            correct_decision=correct_decision,
+            correct_exception_type=correct_exception,
+            acceptable_evidence=acceptable_evidence or [
+                "inspect_purchase_order",
+                "compare_quantity",
+                "compare_price",
+            ],
+            key_findings=key_findings or [
+                "quantities match within tolerance",
+                "prices match within 5% tolerance",
+            ],
+        ),
+    )
+
+
+def _make_state(
+    decision=None,
+    exception_type=None,
+    actions=None,
+    evidence=None,
+    explanation="",
+    step_count=5,
+):
+    s = InvoiceGuardState()
+    s.step_count = step_count
+    s.final_decision = decision
+    s.final_exception_type = exception_type
+    s.actions_taken = actions or []
+    s.final_evidence = evidence or []
+    s.final_explanation = explanation
+    s.documents_revealed = [
+        a.replace("inspect_", "").replace("_", " ")
+        for a in (actions or [])
+        if a.startswith("inspect_")
+    ]
+    s.repeated_action_counts = {}
+    for a in (actions or []):
+        s.repeated_action_counts[a] = s.repeated_action_counts.get(a, 0) + 1
+    return s
+
+
+class TestGradeEpisode:
+    def test_perfect_score(self):
+        case = _make_case()
+        state = _make_state(
+            decision="approve_for_payment",
+            exception_type="clean_match",
+            actions=["inspect_purchase_order", "compare_quantity", "compare_price"],
+            evidence=["inspect_purchase_order", "compare_quantity", "compare_price"],
+            explanation="All quantities and prices match within 5% tolerance per company policy.",
+            step_count=4,
+        )
+        result = grade_episode(case, state)
+        assert result.score >= 0.85
+        assert result.decision_score == 1.0
+        assert result.exception_type_score == 1.0
+
+    def test_wrong_decision_zero_decision_score(self):
+        case = _make_case()
+        state = _make_state(
+            decision="reject_invoice",
+            exception_type="clean_match",
+            actions=["inspect_purchase_order"],
+            evidence=["inspect_purchase_order"],
+            explanation="Rejecting.",
+        )
+        result = grade_episode(case, state)
+        assert result.decision_score == 0.0
+
+    def test_partial_decision_credit(self):
+        case = _make_case(correct_decision=DecisionType.place_on_hold)
+        state = _make_state(
+            decision="escalate_for_supervisor_review",
+            exception_type="partial_receipt",
+            actions=["inspect_purchase_order"],
+            evidence=["inspect_purchase_order"],
+        )
+        result = grade_episode(case, state)
+        assert 0.0 < result.decision_score < 1.0
+
+    def test_no_decision_scores_zero(self):
+        case = _make_case()
+        state = _make_state(decision=None, step_count=10)
+        result = grade_episode(case, state)
+        assert result.decision_score == 0.0
+        assert result.score < 0.5
+
+    def test_score_in_bounds(self):
+        case = _make_case()
+        state = _make_state(
+            decision="approve_for_payment",
+            exception_type="clean_match",
+            actions=["inspect_purchase_order"],
+            evidence=["inspect_purchase_order"],
+        )
+        result = grade_episode(case, state)
+        assert 0.0 <= result.score <= 1.0
+
+    def test_all_rubric_dimensions_present(self):
+        case = _make_case()
+        state = _make_state(
+            decision="approve_for_payment",
+            exception_type="clean_match",
+            actions=["inspect_purchase_order"],
+            evidence=["inspect_purchase_order"],
+            explanation="Matches.",
+        )
+        result = grade_episode(case, state)
+        assert result.decision_score >= 0
+        assert result.exception_type_score >= 0
+        assert result.evidence_score >= 0
+        assert result.investigation_score >= 0
+        assert result.explanation_score >= 0
+        assert result.efficiency_score >= 0
+
+
+class TestExplanationScoring:
+    def test_empty_explanation(self):
+        case = _make_case()
+        score = _score_explanation("", case, ["quantities match"])
+        assert score == 0.0
+
+    def test_good_explanation(self):
+        case = _make_case(
+            key_findings=["quantities match within tolerance", "price variance 3%"],
+        )
+        score = _score_explanation(
+            "All quantities match within the 5% tolerance threshold per company policy. "
+            "Price variance of 3% is acceptable.",
+            case,
+            case.ground_truth.key_findings,
+        )
+        assert score >= 0.6
+
+    def test_explanation_with_numbers(self):
+        case = _make_case()
+        score = _score_explanation(
+            "The invoice total of $55.00 matches the PO within tolerance.",
+            case,
+            [],
+        )
+        assert score > 0.0
+
+    def test_vague_explanation_scores_low(self):
+        case = _make_case()
+        score = _score_explanation("ok", case, ["quantities match"])
+        assert score <= 0.4

tests/test_models.py

@@ -0,0 +1,158 @@
+"""Tests for InvoiceGuard data models."""
+
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from models import (
+    ActionType,
+    DecisionType,
+    ExceptionType,
+    TaskID,
+    Difficulty,
+    InvoiceGuardAction,
+    InvoiceGuardObservation,
+    InvoiceGuardState,
+    GraderResult,
+    Invoice,
+    InvoiceLineItem,
+    PurchaseOrder,
+    POLineItem,
+    GoodsReceiptNote,
+    GRNLineItem,
+    VendorProfile,
+    CompanyPolicy,
+    CaseData,
+    CaseHistory,
+    GroundTruth,
+)
+
+
+class TestEnums:
+    def test_action_types_count(self):
+        assert len(ActionType) == 12
+
+    def test_decision_types(self):
+        expected = {
+            "approve_for_payment",
+            "place_on_hold",
+            "reject_invoice",
+            "escalate_for_supervisor_review",
+        }
+        assert {d.value for d in DecisionType} == expected
+
+    def test_exception_types_include_key_variants(self):
+        values = {e.value for e in ExceptionType}
+        assert "clean_match" in values
+        assert "duplicate_invoice" in values
+        assert "price_mismatch" in values
+        assert "partial_receipt" in values
+        assert "mixed_discrepancy" in values
+
+    def test_task_ids_minimum_12_canonical(self):
+        canonical = [t for t in TaskID if not any(c in t.value for c in ["b_", "c_"])]
+        assert len(canonical) >= 12
+
+    def test_difficulty_levels(self):
+        assert set(d.value for d in Difficulty) == {"easy", "moderate", "hard"}
+
+
+class TestAction:
+    def test_minimal_action(self):
+        a = InvoiceGuardAction(action_type=ActionType.inspect_purchase_order)
+        assert a.action_type == ActionType.inspect_purchase_order
+        assert a.final_decision is None
+        assert a.evidence_references == []
+
+    def test_resolution_action(self):
+        a = InvoiceGuardAction(
+            action_type=ActionType.submit_final_resolution,
+            final_decision=DecisionType.approve_for_payment,
+            exception_type=ExceptionType.clean_match,
+            evidence_references=["inspect_purchase_order", "compare_quantity"],
+            explanation="All documents match.",
+        )
+        assert a.final_decision == DecisionType.approve_for_payment
+        assert len(a.evidence_references) == 2
+
+
+class TestObservation:
+    def test_defaults(self):
+        obs = InvoiceGuardObservation()
+        assert obs.case_id == ""
+        assert obs.available_actions == []
+        assert obs.suggested_next_actions == []
+        assert obs.remaining_steps == 0
+        assert obs.done is False
+        assert obs.grader_result == {}
+
+    def test_populated(self):
+        obs = InvoiceGuardObservation(
+            case_id="CASE-001",
+            task_id="task_1_clean_match",
+            difficulty="easy",
+            remaining_steps=10,
+            suggested_next_actions=["inspect_purchase_order"],
+        )
+        assert obs.case_id == "CASE-001"
+        assert obs.suggested_next_actions == ["inspect_purchase_order"]
+
+
+class TestState:
+    def test_defaults(self):
+        s = InvoiceGuardState()
+        assert s.step_count == 0
+        assert s.actions_taken == []
+        assert s.is_finalized is False
+        assert s.cumulative_reward == 0.0
+
+    def test_mutation(self):
+        s = InvoiceGuardState()
+        s.actions_taken.append("inspect_purchase_order")
+        s.step_count = 1
+        assert len(s.actions_taken) == 1
+
+
+class TestGraderResult:
+    def test_valid_score(self):
+        r = GraderResult(score=0.85)
+        assert r.score == 0.85
+        assert r.explanation_score == 0.0
+
+    def test_score_bounds(self):
+        r = GraderResult(score=0.0)
+        assert r.score == 0.0
+        r = GraderResult(score=1.0)
+        assert r.score == 1.0
+
+
+class TestBusinessEntities:
+    def test_invoice_creation(self):
+        inv = Invoice(
+            invoice_number="INV-001",
+            supplier_name="Test Corp",
+            supplier_id="SUP-001",
+            invoice_date="2024-01-01",
+            po_reference="PO-001",
+            line_items=[
+                InvoiceLineItem(
+                    item_code="ITM-A",
+                    description="Widget",
+                    quantity_billed=10,
+                    unit_price_billed=5.0,
+                    line_total_billed=50.0,
+                )
+            ],
+            subtotal=50.0,
+            tax=5.0,
+            total_amount=55.0,
+        )
+        assert inv.currency == "USD"
+        assert len(inv.line_items) == 1
+
+    def test_company_policy_defaults(self):
+        p = CompanyPolicy()
+        assert p.quantity_tolerance_pct == 5.0
+        assert p.price_tolerance_pct == 5.0
+        assert p.duplicate_check_enabled is True

training/README.md

@@ -0,0 +1,101 @@
+# InvoiceGuard Round 2 — Trajectory-level GRPO
+
+This package trains a small instruction-tuned LM (default `Qwen/Qwen2.5-3B-Instruct`)
+on the InvoiceGuard OpenEnv with a hand-written multi-step GRPO loop:
+
+- Sample **G trajectories** per training task with the current (stochastic) policy.
+- Trajectory reward = env cumulative reward + `grader_bonus * grader_score`.
+- **Group-relative advantage** = z-score within the G trajectories of one task.
+- **PPO-clipped policy gradient** on every `(observation → action)` pair in
+  each trajectory, weighted by that trajectory's advantage, regularised by
+  KL against a **frozen reference** (the same model with the LoRA adapter
+  disabled — no second copy of the base model in memory).
+- LoRA on attention projections; everything else frozen.
+
+We deliberately do **not** use TRL's `GRPOTrainer` — it assumes a single-turn
+reward, but our env is multi-turn agentic. The whole loop is in
+[`train_grpo.py`](./train_grpo.py) and is ~300 lines.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `rollout.py` | Drives the local `InvoiceGuardEnvironment` with an HF model; reuses `inference.py`'s prompt/parse helpers so trajectories are IO-identical to the OpenAI baseline. |
+| `train_grpo.py` | The trainer. Self-contained PEP 723 UV script — runnable both as a Hugging Face Jobs payload and locally for smoke tests. |
+| `launch_hf_job.py` | Uploads the `invoice_guard/` source to a Hub code repo, then submits `train_grpo.py` to HF Jobs with the right env vars and secrets. |
+
+## Train / eval split
+
+Split is deterministic from `--seed` (default 42):
+
+- **Holdout (never trained on):** `eval_holdout_canonical=3` canonical + `eval_holdout_hard=3` hard tasks.
+- **Train:** the remaining 9 canonical + 7 hard = 16 tasks.
+
+The end-of-iteration eval inside the trainer reports the average grader score
+on the holdout, so you can see the learning curve in Trackio. The full
+benchmark for the README plots is produced separately by
+[`eval_round2.py`](../eval_round2.py).
+
+## Quick local smoke test (no GPU, no Hub push)
+
+```powershell
+cd invoice_guard
+..\.venv\Scripts\python -m training.train_grpo `
+    --model-name Qwen/Qwen2.5-0.5B-Instruct `
+    --num-iterations 1 --group-size 2 --max-train-tasks 2 --no-push
+```
+
+This uses the in-tree env (no clone), runs one iteration over 2 tasks with
+G=2 trajectories each, and saves the LoRA adapter to `/tmp/invoiceguard-grpo`.
+On CPU it's slow but verifies the wiring. Use a small base model.
+
+## Launch on Hugging Face Jobs
+
+Prereqs: HF Pro/Team/Enterprise plan, `hf auth login` done locally,
+`pip install huggingface_hub`.
+
+```powershell
+cd invoice_guard
+..\.venv\Scripts\python training\launch_hf_job.py `
+    --hf-username <your-username> `
+    --flavor a10g-large `
+    --timeout 4h `
+    --base-model Qwen/Qwen2.5-3B-Instruct `
+    --num-iterations 3 --group-size 4
+```
+
+What happens:
+
+1. The launcher uploads `invoice_guard/` to `{your-username}/invoiceguard-code`
+   (creates the repo if needed; ignores `outputs/`, `.venv/`, `.env`).
+2. `train_grpo.py` is submitted **inline** to HF Jobs.
+3. Inside the container the script `snapshot_download`s the code repo and adds
+   it to `sys.path`, then runs the GRPO loop.
+4. Trackio dashboard appears at `https://huggingface.co/spaces/<user>/trackio`
+   (project `invoiceguard-round2`, run `qwen3b-grpo`).
+5. On completion the LoRA adapter is pushed to
+   `{your-username}/invoiceguard-qwen3b-grpo`.
+
+## After training
+
+Run the Round 2 benchmark against the trained model:
+
+```powershell
+$env:API_BASE_URL = "<endpoint serving your-username/invoiceguard-qwen3b-grpo>"
+$env:MODEL_NAME = "<your-username>/invoiceguard-qwen3b-grpo"
+..\.venv\Scripts\python eval_round2.py --slice all --model-tag trained_qwen3b_grpo
+..\.venv\Scripts\python eval_round2.py --compare `
+    outputs\round2\hard__baseline_qwen3b.json `
+    outputs\round2\hard__trained_qwen3b_grpo.json
+```
+
+The compare output is what the README before/after plot is built from in
+Stage H.
+
+## Cost estimate
+
+| Setting | Approx | Notes |
+| --- | --- | --- |
+| `a10g-large` × 3-4h | $15-20 | Default — Qwen2.5-3B-Instruct, 3 iter × 16 tasks × G=4 = 192 trajectories per epoch. |
+| `a10g-small` × 4h | $14 | If you drop to Qwen2.5-1.5B-Instruct. |
+| Smoke test (CPU) | $0 | Uses in-tree env, no Hub push. |

training/__init__.py

@@ -0,0 +1 @@
+"""InvoiceGuard Round 2 training package (trajectory-level GRPO)."""

training/launch_hf_job.py

@@ -0,0 +1,127 @@
+"""
+Submit the InvoiceGuard GRPO training as a Hugging Face Jobs UV job.
+
+What this does:
+  1. Bundles the local `invoice_guard/` source folder and uploads it to a
+     dedicated *code* repo on the Hub (default: {user}/invoiceguard-code).
+     The training script clones it back inside the Job container so the env,
+     tasks, models, grader, etc. are available.
+  2. Reads `train_grpo.py` from disk and submits it inline via `run_uv_job`.
+  3. Sets `INVOICEGUARD_CODE_REPO`, `HF_USERNAME`, etc. as env vars in the
+     job, plus passes HF_TOKEN as a secret so push-to-hub works.
+
+Usage:
+    cd invoice_guard
+    python training/launch_hf_job.py \
+        --hf-username <your-username> \
+        --flavor a10g-large \
+        --timeout 4h \
+        --base-model Qwen/Qwen2.5-7B-Instruct \
+        --num-iterations 3 --group-size 4
+
+Requires:
+    - `pip install huggingface_hub` locally
+    - `hf auth login` already done
+    - HF Pro / Team / Enterprise plan (Jobs require a paid plan)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+REPO_DIR = Path(__file__).resolve().parent.parent  # invoice_guard/
+TRAIN_SCRIPT = Path(__file__).resolve().parent / "train_grpo.py"
+
+
+def upload_code(hf_username: str, code_repo_name: str) -> str:
+    from huggingface_hub import HfApi, create_repo
+
+    repo_id = f"{hf_username}/{code_repo_name}"
+    create_repo(repo_id=repo_id, repo_type="model", exist_ok=True, private=False)
+
+    api = HfApi()
+    print(f"[upload] {REPO_DIR} -> {repo_id}", flush=True)
+    api.upload_folder(
+        folder_path=str(REPO_DIR),
+        repo_id=repo_id,
+        repo_type="model",
+        ignore_patterns=[
+            "outputs/**",
+            ".venv/**",
+            "__pycache__/**",
+            "*.pyc",
+            ".env",
+            ".env.example",
+        ],
+        commit_message="Sync InvoiceGuard code for GRPO training job",
+    )
+    print(f"[upload] done -> https://huggingface.co/{repo_id}", flush=True)
+    return repo_id
+
+
+def submit_job(args: argparse.Namespace, code_repo_id: str) -> None:
+    from huggingface_hub import run_uv_job
+
+    script = TRAIN_SCRIPT.read_text(encoding="utf-8")
+
+    job = run_uv_job(
+        script=script,
+        flavor=args.flavor,
+        timeout=args.timeout,
+        secrets={"HF_TOKEN": "$HF_TOKEN"},
+        env={
+            "INVOICEGUARD_CODE_REPO": code_repo_id,
+            "HF_USERNAME": args.hf_username,
+            "HUB_MODEL_ID": args.hub_model_id,
+            "BASE_MODEL": args.base_model,
+            "TRACKIO_PROJECT": args.trackio_project,
+            "TRACKIO_RUN_NAME": args.run_name,
+        },
+        script_args=[
+            "--num-iterations", str(args.num_iterations),
+            "--group-size", str(args.group_size),
+        ] + (["--max-train-tasks", str(args.max_train_tasks)]
+             if args.max_train_tasks else []),
+    )
+    print("\n[submit] job submitted!", flush=True)
+    print(f"  job id : {getattr(job, 'id', job)}", flush=True)
+    url = getattr(job, "url", None)
+    if url:
+        print(f"  monitor: {url}", flush=True)
+    print(f"  flavor : {args.flavor}", flush=True)
+    print(f"  timeout: {args.timeout}", flush=True)
+    print(f"  trackio: project={args.trackio_project}  run={args.run_name}",
+          flush=True)
+    print("\nCheck status later with `hf jobs ps` or `hf jobs logs <id>`.",
+          flush=True)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser()
+    p.add_argument("--hf-username", required=True)
+    p.add_argument("--code-repo-name", default="invoiceguard-code")
+    p.add_argument("--hub-model-id", default="invoiceguard-qwen25-7b-grpo")
+    p.add_argument("--base-model", default="Qwen/Qwen2.5-7B-Instruct")
+    p.add_argument("--flavor", default="a10g-large")
+    p.add_argument("--timeout", default="4h")
+    p.add_argument("--num-iterations", type=int, default=3)
+    p.add_argument("--group-size", type=int, default=4)
+    p.add_argument("--max-train-tasks", type=int, default=None)
+    p.add_argument("--trackio-project", default="invoiceguard-round2")
+    p.add_argument("--run-name", default="qwen25-7b-grpo")
+    p.add_argument("--skip-upload", action="store_true",
+                   help="Reuse the existing code repo (no re-upload).")
+    args = p.parse_args()
+
+    code_repo_id = f"{args.hf_username}/{args.code_repo_name}"
+    if not args.skip_upload:
+        code_repo_id = upload_code(args.hf_username, args.code_repo_name)
+
+    submit_job(args, code_repo_id)
+
+
+if __name__ == "__main__":
+    main()

training/rollout.py

@@ -0,0 +1,139 @@
+"""
+Agentic rollout helper for InvoiceGuard.
+
+Drives the local OpenEnv environment with a Hugging Face causal LM (instead
+of an OpenAI client). Reuses the SAME prompt/parse helpers as `inference.py`
+so trajectories collected here are byte-identical in IO to what the OpenAI
+baseline sees.
+
+Returns a `Trajectory` describing every (prompt, action) pair plus the
+per-step env reward and the terminal grader score. The trainer uses this to
+compute group-relative advantages.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, TYPE_CHECKING
+
+import torch
+
+# Hackathon code is laid out flat: `invoice_guard` is on sys.path at runtime.
+from inference import (  # type: ignore
+    SYSTEM_PROMPT,
+    build_action,
+    build_observation_prompt,
+    parse_llm_response,
+)
+from models import TaskID  # type: ignore
+
+if TYPE_CHECKING:
+    from server.invoice_guard_environment import InvoiceGuardEnvironment
+
+
+@dataclass
+class TrajectoryStep:
+    """One agent decision inside an episode."""
+    prompt_text: str          # full chat prompt fed to the LM (after template)
+    completion_text: str      # raw LM completion (action JSON)
+    prompt_ids: torch.Tensor  # token ids for prompt (1D, long)
+    completion_ids: torch.Tensor  # token ids for completion (1D, long)
+    reward: float             # per-step env reward returned by env.step()
+
+
+@dataclass
+class Trajectory:
+    """A full episode."""
+    task_id: str
+    steps: List[TrajectoryStep] = field(default_factory=list)
+    cumulative_reward: float = 0.0
+    grader_score: float = 0.0
+    terminal_decision: Optional[str] = None
+    success: bool = False
+
+    @property
+    def n_steps(self) -> int:
+        return len(self.steps)
+
+
+def _render_chat_prompt(tokenizer, messages: List[dict]) -> str:
+    """Apply the model's chat template, leaving the assistant turn open."""
+    return tokenizer.apply_chat_template(
+        messages,
+        tokenize=False,
+        add_generation_prompt=True,
+    )
+
+
+@torch.no_grad()
+def rollout_episode(
+    model,
+    tokenizer,
+    env: "InvoiceGuardEnvironment",
+    task_id: TaskID,
+    *,
+    temperature: float = 1.0,
+    top_p: float = 0.95,
+    max_new_tokens: int = 160,
+    device: Optional[torch.device] = None,
+) -> Trajectory:
+    """
+    Run one full episode against the local env using `model` as the policy.
+
+    Sampling is stochastic on purpose: GRPO needs intra-group variance.
+    """
+    device = device or next(model.parameters()).device
+    obs = env.reset(task_id=task_id.value)
+
+    messages: List[dict] = [{"role": "system", "content": SYSTEM_PROMPT}]
+    traj = Trajectory(task_id=task_id.value)
+
+    while not obs.done:
+        user_msg = build_observation_prompt(obs, is_first=(traj.n_steps == 0))
+        messages.append({"role": "user", "content": user_msg})
+
+        prompt_text = _render_chat_prompt(tokenizer, messages)
+        prompt_enc = tokenizer(
+            prompt_text,
+            return_tensors="pt",
+            add_special_tokens=False,
+        ).to(device)
+        prompt_ids = prompt_enc.input_ids[0]
+
+        gen = model.generate(
+            **prompt_enc,
+            do_sample=True,
+            temperature=temperature,
+            top_p=top_p,
+            max_new_tokens=max_new_tokens,
+            pad_token_id=tokenizer.pad_token_id or tokenizer.eos_token_id,
+        )
+        completion_ids = gen[0, prompt_ids.shape[0]:]
+        completion_text = tokenizer.decode(completion_ids, skip_special_tokens=True)
+
+        messages.append({"role": "assistant", "content": completion_text})
+
+        params = parse_llm_response(completion_text)
+        action = build_action(params)
+        obs = env.step(action)
+        reward = float(obs.reward or 0.0)
+
+        traj.steps.append(
+            TrajectoryStep(
+                prompt_text=prompt_text,
+                completion_text=completion_text,
+                prompt_ids=prompt_ids.detach().cpu(),
+                completion_ids=completion_ids.detach().cpu(),
+                reward=reward,
+            )
+        )
+
+    grader_data = obs.metadata.get("grader_result", {}) if hasattr(obs, "metadata") else {}
+    traj.grader_score = float(grader_data.get("score", 0.0)) if isinstance(grader_data, dict) else 0.0
+    traj.cumulative_reward = float(getattr(env.state, "cumulative_reward", 0.0))
+    traj.success = traj.grader_score >= 0.5
+    if traj.steps:
+        last_params = parse_llm_response(traj.steps[-1].completion_text)
+        traj.terminal_decision = last_params.get("final_decision")
+
+    return traj

training/train_grpo.py

@@ -0,0 +1,692 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#   "torch>=2.2",
+#   "transformers>=4.46",
+#   "peft>=0.13",
+#   "accelerate>=1.0",
+#   "bitsandbytes>=0.43; platform_system != 'Darwin'",
+#   "huggingface_hub>=0.26",
+#   "trackio>=0.1.4",
+#   "pydantic>=2.6",
+#   "fastapi>=0.115",
+#   "uvicorn>=0.30",
+#   "python-dotenv",
+#   "openai>=1.40",
+#   "matplotlib>=3.8",
+# ]
+# ///
+"""
+InvoiceGuard Round 2 - Trajectory-level GRPO trainer (HF Jobs UV script).
+
+Trains a small instruction-tuned LM on the InvoiceGuard OpenEnv with a
+hand-written multi-step GRPO loop:
+
+  for each iteration over train tasks:
+      sample G trajectories per task (stochastic policy)
+      reward per trajectory  = env cumulative reward + alpha * grader_score
+      advantage per trajectory = (reward - group_mean) / (group_std + eps)
+      apply PPO-clipped policy gradient on every (obs, action) pair in
+          each trajectory, weighted by that trajectory's advantage,
+          regularised by KL against a frozen reference policy.
+
+The trainer is deliberately small (no TRL GRPOTrainer dep) because TRL's
+GRPO assumes single-turn rewards; our env is multi-turn agentic.
+
+Launch on HF Jobs:
+    See `invoice_guard/training/launch_hf_job.py` for the recommended
+    submission flow (uploads `invoice_guard/` to a code repo on the Hub
+    and points this script at it via INVOICEGUARD_CODE_REPO).
+
+Run a tiny local smoke test (CPU/GPU, no Hub push):
+    cd invoice_guard
+    python -m training.train_grpo \
+        --model-name Qwen/Qwen2.5-0.5B-Instruct \
+        --num-iterations 1 --group-size 2 --max-train-tasks 2 \
+        --no-push
+
+Required env vars on HF Jobs:
+    HF_TOKEN                -- write-scoped token (passed via `secrets=`)
+    HF_USERNAME             -- pushes adapter to {HF_USERNAME}/{HUB_MODEL_ID}
+
+Optional env vars:
+    INVOICEGUARD_CODE_REPO  -- model/dataset repo containing the env code;
+                               cloned into /tmp at startup if set
+    HUB_MODEL_ID            -- name of the LoRA adapter repo to create
+    BASE_MODEL              -- HF model id of the base policy
+    TRACKIO_PROJECT         -- defaults to "invoiceguard-round2"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+# -----------------------------------------------------------------------------
+# 0. Bootstrap: make `invoice_guard/` importable on HF Jobs.
+# -----------------------------------------------------------------------------
+
+def _bootstrap_invoice_guard_path() -> Path:
+    """Ensure `inference`, `models`, `tasks`, `server` modules can be imported.
+
+    Priority order:
+      1. INVOICEGUARD_CODE_DIR       -> already on disk
+      2. INVOICEGUARD_CODE_REPO      -> hf_hub_download / snapshot_download
+      3. INVOICEGUARD_GIT_URL        -> git clone --depth=1
+      4. fall back to the parent dir of this file (local dev)
+    """
+    code_dir = os.environ.get("INVOICEGUARD_CODE_DIR")
+    if code_dir and Path(code_dir).is_dir():
+        sys.path.insert(0, code_dir)
+        return Path(code_dir)
+
+    repo = os.environ.get("INVOICEGUARD_CODE_REPO")
+    if repo:
+        from huggingface_hub import snapshot_download
+        local = snapshot_download(repo_id=repo, repo_type="model")
+        sys.path.insert(0, local)
+        return Path(local)
+
+    git_url = os.environ.get("INVOICEGUARD_GIT_URL")
+    if git_url:
+        target = Path("/tmp/invoiceguard_src")
+        if not target.is_dir():
+            subprocess.check_call(
+                ["git", "clone", "--depth=1", git_url, str(target)],
+            )
+        sub = target / "invoice_guard"
+        sys.path.insert(0, str(sub if sub.is_dir() else target))
+        return sub if sub.is_dir() else target
+
+    here = Path(__file__).resolve().parent.parent  # invoice_guard/
+    sys.path.insert(0, str(here))
+    return here
+
+
+_CODE_ROOT = _bootstrap_invoice_guard_path()
+
+
+# -----------------------------------------------------------------------------
+# 1. Heavy imports (after sys.path is set).
+# -----------------------------------------------------------------------------
+
+import torch
+import torch.nn.functional as F
+from peft import LoraConfig, PeftModel, get_peft_model
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from models import TaskID  # type: ignore
+from server.invoice_guard_environment import InvoiceGuardEnvironment  # type: ignore
+from tasks import HARD_TASK_LIST, TASK_LIST  # type: ignore
+from training.rollout import Trajectory, TrajectoryStep, rollout_episode  # type: ignore
+
+
+# -----------------------------------------------------------------------------
+# 2. Config.
+# -----------------------------------------------------------------------------
+
+@dataclass
+class TrainConfig:
+    base_model: str = os.environ.get("BASE_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+    hub_username: Optional[str] = os.environ.get("HF_USERNAME")
+    hub_model_id: str = os.environ.get("HUB_MODEL_ID", "invoiceguard-qwen25-7b-grpo")
+    trackio_project: str = os.environ.get("TRACKIO_PROJECT", "invoiceguard-round2")
+    trackio_run_name: str = os.environ.get("TRACKIO_RUN_NAME", "qwen25-7b-grpo")
+    artifact_dir: str = os.environ.get("ARTIFACT_DIR", "/tmp/invoiceguard-training-artifacts")
+
+    seed: int = 42
+    num_iterations: int = 3            # full passes over train tasks
+    group_size: int = 4                # G trajectories per task per iteration
+    max_train_tasks: Optional[int] = None  # truncate train set (smoke runs)
+    eval_holdout_canonical: int = 3
+    eval_holdout_hard: int = 3
+
+    # Optimisation
+    lr: float = 1e-5
+    grad_clip: float = 1.0
+    ppo_clip: float = 0.2
+    kl_coef: float = 0.05
+    grader_bonus: float = 1.0          # weight on terminal grader_score
+    micro_batch_size: int = 1          # (obs, action) pairs per fwd/bwd
+    bf16: bool = torch.cuda.is_available()
+
+    # Sampling
+    sample_temperature: float = 1.0
+    sample_top_p: float = 0.95
+    max_new_tokens: int = 160
+
+    # LoRA
+    lora_r: int = 16
+    lora_alpha: int = 32
+    lora_dropout: float = 0.05
+    lora_target_modules: tuple = (
+        "q_proj", "k_proj", "v_proj", "o_proj",
+    )
+
+    push_to_hub: bool = True
+
+
+# -----------------------------------------------------------------------------
+# 3. Train / eval task split.
+# -----------------------------------------------------------------------------
+
+def split_tasks(cfg: TrainConfig) -> tuple[list[TaskID], list[TaskID]]:
+    """Deterministic seeded split. Held-out tasks are NEVER trained on."""
+    rng = random.Random(cfg.seed)
+
+    canonical = list(TASK_LIST)
+    hard = list(HARD_TASK_LIST)
+
+    rng.shuffle(canonical)
+    rng.shuffle(hard)
+
+    eval_c = canonical[: cfg.eval_holdout_canonical]
+    eval_h = hard[: cfg.eval_holdout_hard]
+    train = canonical[cfg.eval_holdout_canonical:] + hard[cfg.eval_holdout_hard:]
+
+    if cfg.max_train_tasks is not None:
+        train = train[: cfg.max_train_tasks]
+
+    eval_set = eval_c + eval_h
+    return train, eval_set
+
+
+# -----------------------------------------------------------------------------
+# 4. Log-prob computation.
+# -----------------------------------------------------------------------------
+
+def _completion_logprobs(
+    model,
+    prompt_ids: torch.Tensor,
+    completion_ids: torch.Tensor,
+    device: torch.device,
+) -> torch.Tensor:
+    """Sum log p(completion | prompt) under `model`. Returns scalar tensor."""
+    input_ids = torch.cat([prompt_ids, completion_ids], dim=0).unsqueeze(0).to(device)
+    attention_mask = torch.ones_like(input_ids)
+
+    out = model(input_ids=input_ids, attention_mask=attention_mask, use_cache=False)
+    # Shift: predict token t from logits at t-1.
+    logits = out.logits[0, :-1, :]              # (L-1, V)
+    targets = input_ids[0, 1:]                  # (L-1,)
+    logprobs = F.log_softmax(logits.float(), dim=-1)
+    token_lp = logprobs.gather(-1, targets.unsqueeze(-1)).squeeze(-1)  # (L-1,)
+
+    # Only sum log-probs over the completion tokens.
+    comp_len = completion_ids.shape[0]
+    return token_lp[-comp_len:].sum()
+
+
+# -----------------------------------------------------------------------------
+# 5. Trajectory advantage computation.
+# -----------------------------------------------------------------------------
+
+def trajectory_reward(traj: Trajectory, grader_bonus: float) -> float:
+    """Single scalar that GRPO will rank within a group."""
+    return traj.cumulative_reward + grader_bonus * traj.grader_score
+
+
+def compute_group_advantages(
+    trajectories: List[Trajectory], grader_bonus: float
+) -> List[float]:
+    rewards = [trajectory_reward(t, grader_bonus) for t in trajectories]
+    if len(rewards) < 2:
+        return [0.0 for _ in rewards]
+    mean = sum(rewards) / len(rewards)
+    var = sum((r - mean) ** 2 for r in rewards) / len(rewards)
+    std = max(var ** 0.5, 1e-6)
+    return [(r - mean) / std for r in rewards]
+
+
+# -----------------------------------------------------------------------------
+# 6. Main training loop.
+# -----------------------------------------------------------------------------
+
+def train(cfg: TrainConfig) -> None:
+    print(f"[setup] code_root={_CODE_ROOT}", flush=True)
+    print(f"[setup] base_model={cfg.base_model}", flush=True)
+    print(f"[setup] cuda available={torch.cuda.is_available()}", flush=True)
+
+    artifact_dir = Path(cfg.artifact_dir)
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+    metrics_path = artifact_dir / "metrics.jsonl"
+    samples_path = artifact_dir / "rollout_samples.jsonl"
+    summary_path = artifact_dir / "training_summary.json"
+    metrics_history: list[dict] = []
+    eval_history: list[dict] = []
+    train_history: list[dict] = []
+    sampled_rollouts: list[dict] = []
+
+    run_started_at = datetime.now(timezone.utc).isoformat()
+
+    random.seed(cfg.seed)
+    torch.manual_seed(cfg.seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(cfg.seed)
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    dtype = torch.bfloat16 if cfg.bf16 else torch.float32
+
+    # ----- Tokenizer & policy --------------------------------------------------
+    tokenizer = AutoTokenizer.from_pretrained(cfg.base_model, use_fast=True)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    print("[setup] loading base model ...", flush=True)
+    base = AutoModelForCausalLM.from_pretrained(
+        cfg.base_model,
+        torch_dtype=dtype,
+        device_map="auto" if torch.cuda.is_available() else None,
+    )
+    base.config.pad_token_id = tokenizer.pad_token_id
+
+    lora_cfg = LoraConfig(
+        r=cfg.lora_r,
+        lora_alpha=cfg.lora_alpha,
+        lora_dropout=cfg.lora_dropout,
+        target_modules=list(cfg.lora_target_modules),
+        bias="none",
+        task_type="CAUSAL_LM",
+    )
+    policy = get_peft_model(base, lora_cfg)
+    policy.print_trainable_parameters()
+    policy.train()
+
+    # Reference (frozen) = base only, no adapter applied. We use the same
+    # PeftModel with adapters disabled (`policy.disable_adapter()`) to compute
+    # reference log-probs in-place and avoid loading a second copy of the base.
+
+    optimizer = torch.optim.AdamW(
+        [p for p in policy.parameters() if p.requires_grad],
+        lr=cfg.lr,
+    )
+
+    # ----- Env & task split ----------------------------------------------------
+    env = InvoiceGuardEnvironment()
+    train_tasks, eval_tasks = split_tasks(cfg)
+    print(f"[setup] train_tasks={len(train_tasks)}  eval_tasks={len(eval_tasks)}",
+          flush=True)
+    print(f"[setup] holdout_eval={[t.value for t in eval_tasks]}", flush=True)
+
+    # ----- Trackio -------------------------------------------------------------
+    tracker = None
+    try:
+        import trackio
+        tracker = trackio.init(
+            project=cfg.trackio_project,
+            name=cfg.trackio_run_name,
+            config={
+                "base_model": cfg.base_model,
+                "num_iterations": cfg.num_iterations,
+                "group_size": cfg.group_size,
+                "lr": cfg.lr,
+                "kl_coef": cfg.kl_coef,
+                "ppo_clip": cfg.ppo_clip,
+                "grader_bonus": cfg.grader_bonus,
+                "lora_r": cfg.lora_r,
+                "n_train_tasks": len(train_tasks),
+                "n_eval_tasks": len(eval_tasks),
+            },
+        )
+        print("[setup] trackio initialised", flush=True)
+    except Exception as e:
+        print(f"[setup] trackio disabled: {e}", flush=True)
+
+    def _write_jsonl(path: Path, row: dict) -> None:
+        with path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+    def _log(metrics: dict, step: int) -> None:
+        row = {
+            "step": step,
+            "time": datetime.now(timezone.utc).isoformat(),
+            **metrics,
+        }
+        metrics_history.append(row)
+        _write_jsonl(metrics_path, row)
+        msg = " | ".join(f"{k}={v:.4f}" if isinstance(v, float) else f"{k}={v}"
+                         for k, v in metrics.items())
+        print(f"[step {step}] {msg}", flush=True)
+        if tracker is not None:
+            try:
+                trackio.log(metrics, step=step)
+            except Exception:
+                pass
+
+    # ----- Eval helper ---------------------------------------------------------
+    def evaluate(label: str, step: int) -> dict:
+        policy.eval()
+        scores, rewards, steps_used = [], [], []
+        successes = []
+        for tid in eval_tasks:
+            traj = rollout_episode(
+                policy, tokenizer, env, tid,
+                temperature=0.0001,  # near-greedy for eval
+                top_p=1.0,
+                max_new_tokens=cfg.max_new_tokens,
+                device=device,
+            )
+            scores.append(traj.grader_score)
+            rewards.append(traj.cumulative_reward)
+            steps_used.append(traj.n_steps)
+            successes.append(1.0 if traj.success else 0.0)
+        policy.train()
+        eval_metrics = {
+            f"{label}/avg_grader_score": sum(scores) / max(len(scores), 1),
+            f"{label}/avg_cum_reward": sum(rewards) / max(len(rewards), 1),
+            f"{label}/avg_steps": sum(steps_used) / max(len(steps_used), 1),
+            f"{label}/success_rate": sum(successes) / max(len(successes), 1),
+            f"{label}/n_tasks": len(eval_tasks),
+        }
+        _log(eval_metrics, step)
+        eval_history.append({"label": label, "step": step, **eval_metrics})
+        return eval_metrics
+
+    def _record_rollout_sample(
+        *,
+        phase: str,
+        global_step: int,
+        task_id: TaskID,
+        trajectories: List[Trajectory],
+        advantages: List[float],
+    ) -> None:
+        # Keep evidence compact: one high-reward and one low-reward trace per task group.
+        if not trajectories:
+            return
+        scored = [
+            (trajectory_reward(t, cfg.grader_bonus), adv, t)
+            for t, adv in zip(trajectories, advantages)
+        ]
+        selected = [max(scored, key=lambda x: x[0]), min(scored, key=lambda x: x[0])]
+        seen = set()
+        for reward_value, advantage, traj in selected:
+            key = id(traj)
+            if key in seen:
+                continue
+            seen.add(key)
+            row = {
+                "phase": phase,
+                "step": global_step,
+                "task_id": task_id.value,
+                "trajectory_reward": reward_value,
+                "advantage": advantage,
+                "grader_score": traj.grader_score,
+                "cumulative_reward": traj.cumulative_reward,
+                "success": traj.success,
+                "n_steps": traj.n_steps,
+                "terminal_decision": traj.terminal_decision,
+                "actions": [s.completion_text[:500] for s in traj.steps],
+                "step_rewards": [s.reward for s in traj.steps],
+            }
+            sampled_rollouts.append(row)
+            _write_jsonl(samples_path, row)
+
+    def _write_plots() -> None:
+        try:
+            import matplotlib.pyplot as plt
+        except Exception as e:
+            print(f"[artifacts] plot generation skipped: {e}", flush=True)
+            return
+
+        if train_history:
+            xs = [r["step"] for r in train_history]
+            fig, ax1 = plt.subplots(figsize=(8, 4.5))
+            ax1.plot(xs, [r["train/group_reward_mean"] for r in train_history], label="group reward")
+            ax1.plot(xs, [r["train/group_grader_mean"] for r in train_history], label="grader score")
+            ax1.set_xlabel("training step")
+            ax1.set_ylabel("score")
+            ax1.set_title("InvoiceGuard training reward")
+            ax1.legend()
+            fig.tight_layout()
+            fig.savefig(artifact_dir / "training_reward_curve.png", dpi=160)
+            plt.close(fig)
+
+            fig, ax = plt.subplots(figsize=(8, 4.5))
+            ax.plot(xs, [r["train/loss"] for r in train_history], label="loss")
+            ax.plot(xs, [r["train/kl_loss"] for r in train_history], label="kl loss")
+            ax.set_xlabel("training step")
+            ax.set_ylabel("loss")
+            ax.set_title("InvoiceGuard GRPO losses")
+            ax.legend()
+            fig.tight_layout()
+            fig.savefig(artifact_dir / "training_loss_curve.png", dpi=160)
+            plt.close(fig)
+
+        eval_rows = [
+            r for r in eval_history
+            if any(k.endswith("/avg_grader_score") for k in r)
+        ]
+        if eval_rows:
+            xs = [r["step"] for r in eval_rows]
+            ys = []
+            labels = []
+            for r in eval_rows:
+                key = next(k for k in r if k.endswith("/avg_grader_score"))
+                labels.append(r["label"])
+                ys.append(r[key])
+            fig, ax = plt.subplots(figsize=(8, 4.5))
+            ax.plot(xs, ys, marker="o")
+            ax.set_xlabel("training step")
+            ax.set_ylabel("holdout grader score")
+            ax.set_title("InvoiceGuard holdout eval during training")
+            for x, y, label in zip(xs, ys, labels):
+                ax.annotate(label.replace("eval/", ""), (x, y), textcoords="offset points", xytext=(0, 6), ha="center")
+            fig.tight_layout()
+            fig.savefig(artifact_dir / "holdout_eval_curve.png", dpi=160)
+            plt.close(fig)
+
+    # ----- Initial eval --------------------------------------------------------
+    global_step = 0
+    print("\n=== initial eval (LoRA initialised but untrained) ===", flush=True)
+    evaluate("eval/init", global_step)
+
+    # ----- Training loop -------------------------------------------------------
+    t_start = time.time()
+    for it in range(cfg.num_iterations):
+        random.shuffle(train_tasks)
+
+        for ti, task_id in enumerate(train_tasks):
+            # 1. Sample G trajectories on the same task (group).
+            policy.eval()
+            trajectories: List[Trajectory] = []
+            for g in range(cfg.group_size):
+                traj = rollout_episode(
+                    policy, tokenizer, env, task_id,
+                    temperature=cfg.sample_temperature,
+                    top_p=cfg.sample_top_p,
+                    max_new_tokens=cfg.max_new_tokens,
+                    device=device,
+                )
+                trajectories.append(traj)
+            policy.train()
+
+            # 2. Group-relative advantages.
+            advantages = compute_group_advantages(trajectories, cfg.grader_bonus)
+
+            # 3. PPO-clipped policy gradient on every (prompt, completion) pair,
+            #    weighted by that trajectory's advantage, with KL vs. reference.
+            optimizer.zero_grad(set_to_none=True)
+            total_loss_val = 0.0
+            n_pairs = 0
+            kl_sum = 0.0
+            pg_sum = 0.0
+
+            for traj, adv in zip(trajectories, advantages):
+                if abs(adv) < 1e-8 or not traj.steps:
+                    continue
+                for step in traj.steps:
+                    # Current policy log-prob (with adapter active).
+                    cur_lp = _completion_logprobs(
+                        policy, step.prompt_ids, step.completion_ids, device
+                    )
+                    # Reference policy log-prob (adapter disabled).
+                    with torch.no_grad():
+                        with policy.disable_adapter():
+                            ref_lp = _completion_logprobs(
+                                policy, step.prompt_ids, step.completion_ids, device
+                            )
+
+                    # PPO-clipped surrogate. The "old" policy here is the same
+                    # snapshot used to sample (we just rolled out moments ago),
+                    # so on the first opt step the ratio == 1; the clip becomes
+                    # active only across multiple opt steps per batch. We still
+                    # apply it for stability when group_size is large.
+                    log_ratio = cur_lp - ref_lp.detach()  # tiny KL surrogate
+                    ratio = torch.exp(cur_lp.detach() - ref_lp.detach())
+                    unclipped = ratio * adv
+                    clipped = torch.clamp(
+                        ratio, 1.0 - cfg.ppo_clip, 1.0 + cfg.ppo_clip
+                    ) * adv
+                    pg_term = -torch.min(unclipped, clipped) * cur_lp / (cur_lp.detach().abs() + 1e-6)
+                    # Equivalent to -adv * log_pi (REINFORCE-style) when ratio~1,
+                    # but bounded for stability.
+
+                    kl_term = cfg.kl_coef * (cur_lp - ref_lp.detach()).pow(2).mean()
+
+                    loss = pg_term + kl_term
+                    loss.backward()
+
+                    total_loss_val += float(loss.detach().item())
+                    pg_sum += float(pg_term.detach().item())
+                    kl_sum += float(kl_term.detach().item())
+                    n_pairs += 1
+
+            if n_pairs > 0:
+                torch.nn.utils.clip_grad_norm_(
+                    [p for p in policy.parameters() if p.requires_grad],
+                    cfg.grad_clip,
+                )
+                optimizer.step()
+
+            global_step += 1
+            group_rewards = [trajectory_reward(t, cfg.grader_bonus) for t in trajectories]
+            group_scores = [t.grader_score for t in trajectories]
+            train_metrics = {
+                "train/iter": it,
+                "train/task_idx": ti,
+                "train/task_id": task_id.value,
+                "train/group_reward_mean": sum(group_rewards) / len(group_rewards),
+                "train/group_reward_std":
+                    (sum((r - sum(group_rewards) / len(group_rewards)) ** 2
+                         for r in group_rewards) / len(group_rewards)) ** 0.5,
+                "train/group_grader_mean": sum(group_scores) / len(group_scores),
+                "train/group_success_rate": sum(1.0 if t.success else 0.0 for t in trajectories) / len(trajectories),
+                "train/avg_steps": sum(t.n_steps for t in trajectories) / len(trajectories),
+                "train/n_pairs": n_pairs,
+                "train/loss": total_loss_val / max(n_pairs, 1),
+                "train/pg_loss": pg_sum / max(n_pairs, 1),
+                "train/kl_loss": kl_sum / max(n_pairs, 1),
+            }
+            train_history.append({"step": global_step, **train_metrics})
+            _record_rollout_sample(
+                phase="train",
+                global_step=global_step,
+                task_id=task_id,
+                trajectories=trajectories,
+                advantages=advantages,
+            )
+            _log(
+                train_metrics,
+                global_step,
+            )
+
+        # End-of-iteration eval.
+        print(f"\n=== eval after iteration {it + 1}/{cfg.num_iterations} ===",
+              flush=True)
+        evaluate(f"eval/iter{it+1}", global_step)
+
+    total_wall_clock = time.time() - t_start
+    print(f"\n[done] total wall clock: {total_wall_clock:.1f}s", flush=True)
+
+    _write_plots()
+
+    summary = {
+        "run_started_at": run_started_at,
+        "run_finished_at": datetime.now(timezone.utc).isoformat(),
+        "base_model": cfg.base_model,
+        "hub_model_id": cfg.hub_model_id,
+        "num_iterations": cfg.num_iterations,
+        "group_size": cfg.group_size,
+        "train_tasks": [t.value for t in train_tasks],
+        "eval_tasks": [t.value for t in eval_tasks],
+        "wall_clock_s": round(total_wall_clock, 2),
+        "n_metric_rows": len(metrics_history),
+        "n_rollout_samples": len(sampled_rollouts),
+        "artifact_files": [
+            p.name for p in sorted(artifact_dir.iterdir()) if p.is_file()
+        ],
+    }
+    summary_path.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+    print(f"[artifacts] wrote {artifact_dir}", flush=True)
+
+    # ----- Push LoRA adapter ---------------------------------------------------
+    if cfg.push_to_hub and cfg.hub_username:
+        from huggingface_hub import HfApi
+
+        repo_id = f"{cfg.hub_username}/{cfg.hub_model_id}"
+        print(f"[push] pushing LoRA adapter to {repo_id}", flush=True)
+        policy.push_to_hub(repo_id, private=False)
+        tokenizer.push_to_hub(repo_id, private=False)
+        print(f"[push] uploading training artifacts to {repo_id}/training_artifacts", flush=True)
+        HfApi().upload_folder(
+            folder_path=str(artifact_dir),
+            repo_id=repo_id,
+            repo_type="model",
+            path_in_repo="training_artifacts",
+            commit_message="Add InvoiceGuard GRPO training artifacts",
+        )
+        print(f"[push] done -> https://huggingface.co/{repo_id}", flush=True)
+    else:
+        out_dir = Path(os.environ.get("OUTPUT_DIR", "/tmp/invoiceguard-grpo"))
+        out_dir.mkdir(parents=True, exist_ok=True)
+        policy.save_pretrained(out_dir)
+        tokenizer.save_pretrained(out_dir)
+        print(f"[save] LoRA adapter saved locally -> {out_dir}", flush=True)
+
+
+# -----------------------------------------------------------------------------
+# 7. CLI.
+# -----------------------------------------------------------------------------
+
+def _parse_args() -> TrainConfig:
+    p = argparse.ArgumentParser()
+    p.add_argument("--model-name", dest="base_model", default=None)
+    p.add_argument("--num-iterations", type=int, default=None)
+    p.add_argument("--group-size", type=int, default=None)
+    p.add_argument("--max-train-tasks", type=int, default=None)
+    p.add_argument("--lr", type=float, default=None)
+    p.add_argument("--no-push", action="store_true")
+    p.add_argument("--seed", type=int, default=None)
+    args = p.parse_args()
+
+    cfg = TrainConfig()
+    if args.base_model:
+        cfg.base_model = args.base_model
+    if args.num_iterations is not None:
+        cfg.num_iterations = args.num_iterations
+    if args.group_size is not None:
+        cfg.group_size = args.group_size
+    if args.max_train_tasks is not None:
+        cfg.max_train_tasks = args.max_train_tasks
+    if args.lr is not None:
+        cfg.lr = args.lr
+    if args.seed is not None:
+        cfg.seed = args.seed
+    if args.no_push:
+        cfg.push_to_hub = False
+    return cfg
+
+
+if __name__ == "__main__":
+    cfg = _parse_args()
+    train(cfg)