Initial Commit

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.env
+.venv
+venv/
+env/
+*.log
+.DS_Store

Dockerfile

@@ -0,0 +1,44 @@
+# ---------------------------------------------------------------------------
+# PayOps OpenEnv — Production Dockerfile
+# ---------------------------------------------------------------------------
+# Builds a lightweight, reproducible container that runs the FastAPI server.
+# Compatible with HuggingFace Spaces (port 7860) and local development (8000).
+# ---------------------------------------------------------------------------
+
+FROM python:3.11-slim
+
+# Non-root user for security
+RUN useradd -m -u 1000 appuser
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy and install Python dependencies first (layer caching)
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project source
+COPY . /app/payops_env
+
+# Put parent directory on PYTHONPATH so `payops_env` is importable
+ENV PYTHONPATH="/app:${PYTHONPATH}"
+
+# HuggingFace Spaces requires port 7860; default to 8000 locally
+ENV PORT=7860
+
+# Switch to non-root user
+USER appuser
+
+EXPOSE 7860
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
+    CMD curl -f http://localhost:${PORT}/health || exit 1
+
+CMD ["sh", "-c", "uvicorn payops_env.server.app:app --host 0.0.0.0 --port ${PORT}"]
+

PayOps_v2.postman_collection.json

@@ -0,0 +1,1196 @@
+{
+  "info": {
+    "_postman_id": "payops-v2-full-suite",
+    "name": "PayOps v2 — Full Test Suite",
+    "description": "Complete Postman collection for PayOps v2.0.0 environment.\nGroups: Infrastructure · Tasks · Reset · Terminal Actions · Wrong Actions · Investigation · State · Grader · Replay · Baseline · Analytics · Leaderboard · Edge Cases · Perfect Episode · Budget Mechanics\n\nBase URL variable: {{base_url}} = http://localhost:8000",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "variable": [
+    {
+      "key": "base_url",
+      "value": "http://localhost:8000",
+      "type": "string"
+    },
+    {
+      "key": "episode_id",
+      "value": "",
+      "type": "string"
+    }
+  ],
+  "item": [
+
+    {
+      "name": "A — Infrastructure",
+      "item": [
+        {
+          "name": "A-01 Health check",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('Status 200', () => pm.response.to.have.status(200));",
+            "pm.test('status=ok', () => pm.expect(pm.response.json().status).to.eql('ok'));",
+            "pm.test('version=2.0.0', () => pm.expect(pm.response.json().version).to.eql('2.0.0'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/health", "host": ["{{base_url}}"], "path": ["health"]}
+          }
+        },
+        {
+          "name": "A-02 Schema — models present",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('Status 200', () => pm.response.to.have.status(200));",
+            "const body = pm.response.text();",
+            "pm.test('PayOpsAction in schema', () => pm.expect(body).to.include('PayOpsAction'));",
+            "pm.test('PayOpsObservation in schema', () => pm.expect(body).to.include('PayOpsObservation'));",
+            "pm.test('PayOpsState in schema', () => pm.expect(body).to.include('PayOpsState'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/schema", "host": ["{{base_url}}"], "path": ["schema"]}
+          }
+        },
+        {
+          "name": "A-03 Schema — all 10 action types",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const body = pm.response.text();",
+            "['approve','reject','flag','escalate','hold','inspect','request_docs','verify_kyc','contact_sender','file_sar'].forEach(a => {",
+            "  pm.test(`action ${a} in schema`, () => pm.expect(body).to.include(a));",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/schema", "host": ["{{base_url}}"], "path": ["schema"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "B — Tasks Endpoint",
+      "item": [
+        {
+          "name": "B-01 Tasks — count=20",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('Status 200', () => pm.response.to.have.status(200));",
+            "const d = pm.response.json();",
+            "pm.test('count=20', () => pm.expect(d.count).to.eql(20));",
+            "pm.test('tasks array length=20', () => pm.expect(d.tasks.length).to.eql(20));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/tasks", "host": ["{{base_url}}"], "path": ["tasks"]}
+          }
+        },
+        {
+          "name": "B-02 Tasks — all 4 difficulty tiers",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const tasks = pm.response.json().tasks;",
+            "const diffs = tasks.map(t => t.difficulty);",
+            "['easy','medium','hard','critical'].forEach(d => {",
+            "  pm.test(`tier '${d}' present`, () => pm.expect(diffs).to.include(d));",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/tasks", "host": ["{{base_url}}"], "path": ["tasks"]}
+          }
+        },
+        {
+          "name": "B-03 Tasks — task structure fields",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const t = pm.response.json().tasks[0];",
+            "['task_id','difficulty','correct_action','requires_investigation','regulatory_action','chain_total'].forEach(f => {",
+            "  pm.test(`field '${f}' present`, () => pm.expect(t).to.have.property(f));",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/tasks", "host": ["{{base_url}}"], "path": ["tasks"]}
+          }
+        },
+        {
+          "name": "B-04 Tasks — chain_total >= 1 on all",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const tasks = pm.response.json().tasks;",
+            "pm.test('all tasks have chain_total >= 1', () => {",
+            "  tasks.forEach(t => pm.expect(t.chain_total).to.be.at.least(1));",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/tasks", "host": ["{{base_url}}"], "path": ["tasks"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "C — Reset",
+      "item": [
+        {
+          "name": "C-01 Reset — first observation",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('Status 200', () => pm.response.to.have.status(200));",
+            "const d = pm.response.json();",
+            "pm.test('first task is EASY-001', () => pm.expect(d.task_id).to.eql('EASY-001'));",
+            "pm.test('done=false', () => pm.expect(d.done).to.eql(false));",
+            "pm.test('budget_remaining=5.0', () => pm.expect(d.budget_remaining).to.eql(5.0));",
+            "pm.test('risk_score present', () => pm.expect(d).to.have.property('risk_score'));",
+            "pm.test('ml_confidence present', () => pm.expect(d).to.have.property('ml_confidence'));",
+            "pm.test('chain_total present', () => pm.expect(d).to.have.property('chain_total'));",
+            "pm.test('steps_remaining present', () => pm.expect(d).to.have.property('steps_remaining'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "url": {"raw": "{{base_url}}/reset", "host": ["{{base_url}}"], "path": ["reset"]}
+          }
+        },
+        {
+          "name": "C-02 State after reset",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('episode_id set', () => pm.expect(d.episode_id).to.be.a('string').and.not.empty);",
+            "pm.collectionVariables.set('episode_id', d.episode_id);",
+            "pm.test('step_count=0', () => pm.expect(d.step_count).to.eql(0));",
+            "pm.test('budget_spent=0', () => pm.expect(d.budget_spent).to.eql(0));",
+            "pm.test('correct_decisions=0', () => pm.expect(d.correct_decisions).to.eql(0));",
+            "pm.test('investigation_actions_used is array', () => pm.expect(d.investigation_actions_used).to.be.an('array'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/state", "host": ["{{base_url}}"], "path": ["state"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "D — Terminal Actions (Correct)",
+      "item": [
+        {
+          "name": "D-01 EASY-001 approve → reward=1.0",
+          "event": [
+            {"listen": "prerequest", "script": {"exec": ["// ensure fresh episode"], "type": "text/javascript"}},
+            {"listen": "test", "script": {"exec": [
+              "const d = pm.response.json();",
+              "pm.test('reward=1.0', () => pm.expect(d.reward).to.eql(1.0));",
+              "pm.test('advances to EASY-002', () => pm.expect(d.task_id).to.eql('EASY-002'));"
+            ], "type": "text/javascript"}}
+          ],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-02 EASY-002 reject → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"reject\", \"transaction_id\": \"TXN-E002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-03 EASY-003 approve → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-E003\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-04 EASY-004 flag → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"flag\", \"transaction_id\": \"TXN-E004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-05 MED-001 escalate → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"escalate\", \"transaction_id\": \"TXN-M001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-06 MED-002 hold → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"hold\", \"transaction_id\": \"TXN-M002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-07 MED-003 flag → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"flag\", \"transaction_id\": \"TXN-M003\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-08 MED-004 flag → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"flag\", \"transaction_id\": \"TXN-M004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-09 MED-005 hold → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"hold\", \"transaction_id\": \"TXN-M005\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-10 MED-006 escalate → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"escalate\", \"transaction_id\": \"TXN-M006\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-11 HARD-001 escalate → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"escalate\", \"transaction_id\": \"TXN-H001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-12 HARD-002 reject → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"reject\", \"transaction_id\": \"TXN-H002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-13 HARD-003 reject → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"reject\", \"transaction_id\": \"TXN-H003\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-14 HARD-004 approve → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-H004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-15 HARD-005 escalate → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"escalate\", \"transaction_id\": \"TXN-H005\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-16 HARD-006 flag → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"flag\", \"transaction_id\": \"TXN-H006\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-17 CRIT-001 approve → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-C001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-18 CRIT-002 reject → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"reject\", \"transaction_id\": \"TXN-C002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-19 CRIT-003 escalate → reward=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=1.0', () => pm.expect(pm.response.json().reward).to.eql(1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"escalate\", \"transaction_id\": \"TXN-C003\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "D-20 CRIT-004 reject → reward=1.0 + done=true",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('reward=1.0', () => pm.expect(d.reward).to.eql(1.0));",
+            "pm.test('episode done', () => pm.expect(d.done).to.eql(true));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"reject\", \"transaction_id\": \"TXN-C004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "E — Wrong Actions & Partial Credit",
+      "item": [
+        {
+          "name": "E-00 Reset before wrong-action tests",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reset ok', () => pm.response.to.have.status(200));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "url": {"raw": "{{base_url}}/reset", "host": ["{{base_url}}"], "path": ["reset"]}
+          }
+        },
+        {
+          "name": "E-01 Approve legit EASY-001 (correct, advance)",
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "E-02 Approve fraud EASY-002 → reward=-1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=-1.0 for fraud approval', () => pm.expect(pm.response.json().reward).to.eql(-1.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-E002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "E-03 Reject legit EASY-003 → reward=-0.5",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('reward=-0.5 for wrong reject', () => pm.expect(pm.response.json().reward).to.eql(-0.5));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"reject\", \"transaction_id\": \"TXN-E003\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "E-04 Flag EASY-004 correct → reward=1.0",
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"flag\", \"transaction_id\": \"TXN-E004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "E-05 Partial credit — flag instead of escalate (MED-001)",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('partial credit reward > -1 and < 1', () => {",
+            "  pm.expect(d.reward).to.be.greaterThan(-1.0);",
+            "  pm.expect(d.reward).to.be.lessThan(1.0);",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"flag\", \"transaction_id\": \"TXN-M001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "F — Investigation Sub-Actions",
+      "item": [
+        {
+          "name": "F-00 Reset before investigation tests",
+          "request": {
+            "method": "POST",
+            "url": {"raw": "{{base_url}}/reset", "host": ["{{base_url}}"], "path": ["reset"]}
+          }
+        },
+        {
+          "name": "F-01 inspect → reward=0.15, notes populated, budget=4.9",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('reward=0.15', () => pm.expect(d.reward).to.eql(0.15));",
+            "pm.test('task unchanged (EASY-001)', () => pm.expect(d.task_id).to.eql('EASY-001'));",
+            "pm.test('inspection_notes populated', () => pm.expect(d.inspection_notes).to.be.a('string').and.not.empty);",
+            "pm.test('budget_remaining=4.9', () => pm.expect(d.budget_remaining).to.eql(4.9));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"inspect\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-02 inspect again (duplicate) → reward=0.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('duplicate inspect reward=0.0', () => pm.expect(pm.response.json().reward).to.eql(0.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"inspect\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-03 approve EASY-001 (advance to E-002)",
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-04 request_docs → reward=0.15, docs_notes, budget-0.2",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('reward=0.15', () => pm.expect(d.reward).to.eql(0.15));",
+            "pm.test('docs_notes populated', () => pm.expect(d.docs_notes).to.be.a('string').and.not.empty);",
+            "pm.test('budget decreased by 0.2', () => pm.expect(d.budget_remaining).to.be.closeTo(4.6, 0.01));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"request_docs\", \"transaction_id\": \"TXN-E002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-05 request_docs again (duplicate) → reward=0.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('duplicate request_docs reward=0.0', () => pm.expect(pm.response.json().reward).to.eql(0.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"request_docs\", \"transaction_id\": \"TXN-E002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-06 reject EASY-002 (advance to E-003)",
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"reject\", \"transaction_id\": \"TXN-E002\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-07 verify_kyc → reward=0.15, kyc_notes, budget-0.2",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('reward=0.15', () => pm.expect(d.reward).to.eql(0.15));",
+            "pm.test('kyc_notes populated', () => pm.expect(d.kyc_notes).to.be.a('string').and.not.empty);",
+            "pm.test('budget decreased by 0.2', () => pm.expect(d.budget_remaining).to.be.closeTo(4.2, 0.05));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"verify_kyc\", \"transaction_id\": \"TXN-E003\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-08 approve EASY-003 (advance to E-004)",
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"approve\", \"transaction_id\": \"TXN-E003\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-09 contact_sender → reward=0.15, contact_notes, budget-0.3",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('reward=0.15', () => pm.expect(d.reward).to.eql(0.15));",
+            "pm.test('contact_notes populated', () => pm.expect(d.contact_notes).to.be.a('string').and.not.empty);",
+            "pm.test('budget decreased by 0.3', () => pm.expect(d.budget_remaining).to.be.lessThan(4.2));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"contact_sender\", \"transaction_id\": \"TXN-E004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-10 flag EASY-004 (advance to M-001)",
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"flag\", \"transaction_id\": \"TXN-E004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "F-11 file_sar → reward=0.15, docs_notes has SAR, budget-0.05",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('reward=0.15', () => pm.expect(d.reward).to.eql(0.15));",
+            "pm.test('docs_notes contains SAR', () => pm.expect(d.docs_notes).to.include('SAR'));",
+            "pm.test('budget_remaining updated', () => pm.expect(d.budget_remaining).to.be.lessThan(5.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"file_sar\", \"transaction_id\": \"TXN-M001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "G — State Endpoint",
+      "item": [
+        {
+          "name": "G-01 State — all required fields",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('status 200', () => pm.response.to.have.status(200));",
+            "['episode_id','step_count','budget_spent','budget_limit','investigation_actions_used','correct_decisions','wrong_high_cost','recent_decisions'].forEach(f => {",
+            "  pm.test(`field '${f}' present`, () => pm.expect(d).to.have.property(f));",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/state", "host": ["{{base_url}}"], "path": ["state"]}
+          }
+        },
+        {
+          "name": "G-02 State — budget_spent reflects investigation costs",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('budget_spent > 0', () => pm.expect(pm.response.json().budget_spent).to.be.greaterThan(0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/state", "host": ["{{base_url}}"], "path": ["state"]}
+          }
+        },
+        {
+          "name": "G-03 State — investigation_actions_used is array",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('investigation_actions_used is array', () => pm.expect(pm.response.json().investigation_actions_used).to.be.an('array'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/state", "host": ["{{base_url}}"], "path": ["state"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "H — Grader Endpoint",
+      "item": [
+        {
+          "name": "H-01 Grader — full result structure",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('status 200', () => pm.response.to.have.status(200));",
+            "['normalised_score','total_reward','max_possible_reward','budget_spent','budget_penalty','per_task','passed'].forEach(f => {",
+            "  pm.test(`field '${f}' present`, () => pm.expect(d).to.have.property(f));",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/grader", "host": ["{{base_url}}"], "path": ["grader"]}
+          }
+        },
+        {
+          "name": "H-02 Grader — per_task has reward_breakdown",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('per_task is array', () => pm.expect(d.per_task).to.be.an('array'));",
+            "if (d.per_task.length > 0) {",
+            "  pm.test('per_task[0] has reward_breakdown', () => pm.expect(d.per_task[0]).to.have.property('reward_breakdown'));",
+            "  pm.test('per_task[0] has difficulty', () => pm.expect(d.per_task[0]).to.have.property('difficulty'));",
+            "}"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/grader", "host": ["{{base_url}}"], "path": ["grader"]}
+          }
+        },
+        {
+          "name": "H-03 Grader — normalised_score in [0,1]",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const s = pm.response.json().normalised_score;",
+            "pm.test('score in [0,1]', () => { pm.expect(s).to.be.at.least(0); pm.expect(s).to.be.at.most(1); });"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/grader", "host": ["{{base_url}}"], "path": ["grader"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "I — Replay Endpoint",
+      "item": [
+        {
+          "name": "I-01 Replay — 20 all-correct actions → score=1.0",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('normalised_score=1.0', () => pm.expect(d.normalised_score).to.eql(1.0));",
+            "pm.test('passed=true', () => pm.expect(d.passed).to.eql(true));",
+            "pm.test('budget_spent=0.0', () => pm.expect(d.budget_spent).to.eql(0.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\n  \"actions\": [\n    \"approve\", \"reject\", \"approve\", \"flag\",\n    \"escalate\", \"hold\", \"flag\", \"flag\", \"hold\", \"escalate\",\n    \"escalate\", \"reject\", \"reject\", \"approve\", \"escalate\", \"flag\",\n    \"approve\", \"reject\", \"escalate\", \"reject\"\n  ]\n}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        },
+        {
+          "name": "I-02 Replay — with inspect sub-actions → budget_spent=0.1",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('budget_spent=0.1', () => pm.expect(d.budget_spent).to.eql(0.1));",
+            "pm.test('per_task present', () => pm.expect(d.per_task).to.be.an('array'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\n  \"actions\": [\n    \"inspect\", \"approve\", \"reject\", \"approve\", \"flag\",\n    \"escalate\", \"hold\", \"flag\", \"flag\", \"hold\", \"escalate\",\n    \"escalate\", \"reject\", \"reject\", \"approve\", \"escalate\", \"flag\",\n    \"approve\", \"reject\", \"escalate\", \"reject\"\n  ]\n}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        },
+        {
+          "name": "I-03 Replay — with confidences",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('accepts confidences, returns score', () => pm.expect(pm.response.json()).to.have.property('normalised_score'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\n  \"actions\": [\"approve\", \"reject\"],\n  \"confidences\": [0.95, 0.88]\n}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        },
+        {
+          "name": "I-04 Replay — all-wrong actions → score very low",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('all-wrong score < 0.3', () => pm.expect(d.normalised_score).to.be.lessThan(0.3));",
+            "pm.test('passed=false', () => pm.expect(d.passed).to.eql(false));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\n  \"actions\": [\n    \"reject\", \"approve\", \"reject\", \"reject\",\n    \"reject\", \"reject\", \"reject\", \"reject\", \"reject\", \"reject\",\n    \"reject\", \"approve\", \"approve\", \"reject\", \"reject\", \"reject\",\n    \"reject\", \"approve\", \"reject\", \"approve\"\n  ]\n}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        },
+        {
+          "name": "I-05 Replay — invalid action → 422",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('422 or error body', () => {",
+            "  const ok = pm.response.code === 422 || (pm.response.code === 400);",
+            "  const hasError = pm.response.text().includes('Invalid') || pm.response.text().includes('detail');",
+            "  pm.expect(ok || hasError).to.be.true;",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"actions\": [\"delete\", \"approve\"]}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        },
+        {
+          "name": "I-06 Replay — empty actions list",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('handles empty list gracefully', () => pm.expect(pm.response.json()).to.have.property('normalised_score'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"actions\": []}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        },
+        {
+          "name": "I-07 Replay — does NOT alter live server state",
+          "event": [
+            {"listen": "prerequest", "script": {"exec": [
+              "// capture current state to compare after replay",
+              "pm.sendRequest(`${pm.collectionVariables.get('base_url') || 'http://localhost:8000'}/state`, (err, res) => {",
+              "  if (!err) pm.collectionVariables.set('state_before', JSON.stringify(res.json().step_count));",
+              "});"
+            ], "type": "text/javascript"}},
+            {"listen": "test", "script": {"exec": [
+              "pm.sendRequest(`${pm.collectionVariables.get('base_url') || 'http://localhost:8000'}/state`, (err, res) => {",
+              "  const before = pm.collectionVariables.get('state_before');",
+              "  const after = JSON.stringify(res.json().step_count);",
+              "  pm.test('server state unchanged after replay', () => pm.expect(before).to.eql(after));",
+              "});"
+            ], "type": "text/javascript"}}
+          ],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"actions\": [\"approve\", \"reject\"]}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "J — Baseline Endpoint",
+      "item": [
+        {
+          "name": "J-01 Baseline — full result",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('status 200', () => pm.response.to.have.status(200));",
+            "['normalised_score','total_reward','steps','scores'].forEach(f => {",
+            "  pm.test(`field '${f}' present`, () => pm.expect(d).to.have.property(f));",
+            "});",
+            "pm.test('score > 0.5', () => pm.expect(d.normalised_score).to.be.greaterThan(0.5));",
+            "pm.test('steps = 20', () => pm.expect(d.steps).to.eql(20));",
+            "pm.test('scores length = 20', () => pm.expect(d.scores.length).to.eql(20));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "url": {"raw": "{{base_url}}/baseline", "host": ["{{base_url}}"], "path": ["baseline"]}
+          }
+        },
+        {
+          "name": "J-02 Baseline — passed=true",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('passed=true', () => pm.expect(pm.response.json().passed).to.eql(true));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "url": {"raw": "{{base_url}}/baseline", "host": ["{{base_url}}"], "path": ["baseline"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "K — Analytics Endpoint",
+      "item": [
+        {
+          "name": "K-01 Analytics — structure",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('status 200', () => pm.response.to.have.status(200));",
+            "const d = pm.response.json();",
+            "const hasMsg = d.message !== undefined;",
+            "const hasData = d.episodes_completed !== undefined;",
+            "pm.test('returns message or episode data', () => pm.expect(hasMsg || hasData).to.be.true);"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/analytics", "host": ["{{base_url}}"], "path": ["analytics"]}
+          }
+        },
+        {
+          "name": "K-02 Analytics — after completed episode",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('episodes_completed >= 1', () => pm.expect(d.episodes_completed).to.be.at.least(1));",
+            "pm.test('best_score present', () => pm.expect(d).to.have.property('best_score'));",
+            "pm.test('avg_score present', () => pm.expect(d).to.have.property('avg_score'));",
+            "pm.test('by_difficulty present', () => pm.expect(d).to.have.property('by_difficulty'));",
+            "pm.test('easy accuracy present', () => pm.expect(d.by_difficulty).to.have.property('easy'));",
+            "pm.test('critical accuracy present', () => pm.expect(d.by_difficulty).to.have.property('critical'));"
+          ], "type": "text/javascript"}},
+          {"listen": "prerequest", "script": {"exec": [
+            "// Run a complete episode first so analytics has data",
+            "const base = pm.collectionVariables.get('base_url') || 'http://localhost:8000';",
+            "const actions = [",
+            "  ['approve','TXN-E001'],['reject','TXN-E002'],['approve','TXN-E003'],['flag','TXN-E004'],",
+            "  ['escalate','TXN-M001'],['hold','TXN-M002'],['flag','TXN-M003'],['flag','TXN-M004'],",
+            "  ['hold','TXN-M005'],['escalate','TXN-M006'],",
+            "  ['escalate','TXN-H001'],['reject','TXN-H002'],['reject','TXN-H003'],['approve','TXN-H004'],",
+            "  ['escalate','TXN-H005'],['flag','TXN-H006'],",
+            "  ['approve','TXN-C001'],['reject','TXN-C002'],['escalate','TXN-C003'],['reject','TXN-C004']",
+            "];",
+            "// Note: triggering via test runner means sequence matters — this prerequest",
+            "// runs before the actual GET /analytics is sent."
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/analytics", "host": ["{{base_url}}"], "path": ["analytics"]}
+          }
+        },
+        {
+          "name": "K-03 Analytics — current_episode present",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('current_episode field present', () => pm.expect(pm.response.json()).to.have.property('current_episode'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/analytics", "host": ["{{base_url}}"], "path": ["analytics"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "L — Leaderboard Endpoint",
+      "item": [
+        {
+          "name": "L-01 Leaderboard — structure",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('status 200', () => pm.response.to.have.status(200));",
+            "pm.test('count field present', () => pm.expect(d).to.have.property('count'));",
+            "pm.test('entries field present', () => pm.expect(d).to.have.property('entries'));",
+            "pm.test('entries is array', () => pm.expect(d.entries).to.be.an('array'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/leaderboard", "host": ["{{base_url}}"], "path": ["leaderboard"]}
+          }
+        },
+        {
+          "name": "L-02 Leaderboard — entry structure",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "if (d.entries.length > 0) {",
+            "  const e = d.entries[0];",
+            "  ['episode_id','normalised_score','timestamp','budget_spent'].forEach(f => {",
+            "    pm.test(`entry has field '${f}'`, () => pm.expect(e).to.have.property(f));",
+            "  });",
+            "} else {",
+            "  pm.test('no entries yet (ok before completing episode)', () => true);",
+            "}"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/leaderboard", "host": ["{{base_url}}"], "path": ["leaderboard"]}
+          }
+        },
+        {
+          "name": "L-03 Leaderboard — after baseline run, count >= 1",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('at least one entry after baseline', () => pm.expect(pm.response.json().count).to.be.at.least(1));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/leaderboard", "host": ["{{base_url}}"], "path": ["leaderboard"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "M — Budget Mechanics",
+      "item": [
+        {
+          "name": "M-00 Reset for budget test",
+          "request": {
+            "method": "POST",
+            "url": {"raw": "{{base_url}}/reset", "host": ["{{base_url}}"], "path": ["reset"]}
+          }
+        },
+        {
+          "name": "M-01 contact_sender (cost=0.3) → budget=4.7",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('budget_remaining=4.7', () => pm.expect(pm.response.json().budget_remaining).to.be.closeTo(4.7, 0.01));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"contact_sender\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "M-02 request_docs (cost=0.2) → budget=4.5",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('budget_remaining=4.5', () => pm.expect(pm.response.json().budget_remaining).to.be.closeTo(4.5, 0.01));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"request_docs\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "M-03 verify_kyc (cost=0.2) → budget=4.3",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('budget_remaining=4.3', () => pm.expect(pm.response.json().budget_remaining).to.be.closeTo(4.3, 0.01));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"verify_kyc\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "M-04 file_sar (cost=0.05) → budget=4.25",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('budget_remaining=4.25', () => pm.expect(pm.response.json().budget_remaining).to.be.closeTo(4.25, 0.01));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"file_sar\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "M-05 Grader shows non-zero budget_spent",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('budget_spent > 0', () => pm.expect(pm.response.json().budget_spent).to.be.greaterThan(0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/grader", "host": ["{{base_url}}"], "path": ["grader"]}
+          }
+        },
+        {
+          "name": "M-06 Replay — heavy investigation causes budget_penalty",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('budget_overspend > 0', () => pm.expect(d.budget_overspend).to.be.greaterThan(0));",
+            "pm.test('budget_penalty > 0', () => pm.expect(d.budget_penalty).to.be.greaterThan(0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\n  \"actions\": [\n    \"contact_sender\",\"contact_sender\",\"contact_sender\",\"contact_sender\",\n    \"contact_sender\",\"contact_sender\",\"contact_sender\",\"contact_sender\",\n    \"contact_sender\",\"contact_sender\",\"contact_sender\",\"contact_sender\",\n    \"contact_sender\",\"contact_sender\",\"contact_sender\",\"contact_sender\",\n    \"contact_sender\",\"contact_sender\",\n    \"approve\",\"reject\",\"approve\",\"flag\",\n    \"escalate\",\"hold\",\"flag\",\"flag\",\"hold\",\"escalate\",\n    \"escalate\",\"reject\",\"reject\",\"approve\",\"escalate\",\"flag\",\n    \"approve\",\"reject\",\"escalate\",\"reject\"\n  ]\n}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "N — Edge Cases & Errors",
+      "item": [
+        {
+          "name": "N-01 Unknown action_type → 422",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('error response', () => {",
+            "  const code = pm.response.code;",
+            "  pm.expect([400, 422]).to.include(code);",
+            "});"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\": \"nuke\", \"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "N-02 Missing action_type → 422",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('422 for missing field', () => pm.expect([400, 422]).to.include(pm.response.code));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"transaction_id\": \"TXN-E001\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "N-03 Empty POST body → 422",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('422 for empty body', () => pm.expect([400, 422]).to.include(pm.response.code));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "N-04 Replay with partial confidences (shorter than actions)",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('handles partial confidences gracefully', () => pm.expect(pm.response.json()).to.have.property('normalised_score'));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"actions\": [\"approve\", \"reject\", \"approve\"], \"confidences\": [0.9]}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        },
+        {
+          "name": "N-05 Replay with invalid JSON → 422",
+          "event": [{"listen": "test", "script": {"exec": [
+            "pm.test('error on invalid JSON', () => pm.expect([400, 422]).to.include(pm.response.code));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{broken json}"},
+            "url": {"raw": "{{base_url}}/replay", "host": ["{{base_url}}"], "path": ["replay"]}
+          }
+        }
+      ]
+    },
+
+    {
+      "name": "O — Perfect Episode (Full Run)",
+      "item": [
+        {
+          "name": "O-00 Reset (start fresh)",
+          "request": {
+            "method": "POST",
+            "url": {"raw": "{{base_url}}/reset", "host": ["{{base_url}}"], "path": ["reset"]}
+          }
+        },
+        {"name": "O-01 EASY-001 approve", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"approve\",\"transaction_id\":\"TXN-E001\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-02 EASY-002 reject", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"reject\",\"transaction_id\":\"TXN-E002\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-03 EASY-003 approve", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"approve\",\"transaction_id\":\"TXN-E003\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-04 EASY-004 flag", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"flag\",\"transaction_id\":\"TXN-E004\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-05 MED-001 escalate", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"escalate\",\"transaction_id\":\"TXN-M001\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-06 MED-002 hold", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"hold\",\"transaction_id\":\"TXN-M002\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-07 MED-003 flag", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"flag\",\"transaction_id\":\"TXN-M003\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-08 MED-004 flag", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"flag\",\"transaction_id\":\"TXN-M004\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-09 MED-005 hold", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"hold\",\"transaction_id\":\"TXN-M005\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-10 MED-006 escalate", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"escalate\",\"transaction_id\":\"TXN-M006\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-11 HARD-001 escalate", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"escalate\",\"transaction_id\":\"TXN-H001\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-12 HARD-002 reject", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"reject\",\"transaction_id\":\"TXN-H002\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-13 HARD-003 reject", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"reject\",\"transaction_id\":\"TXN-H003\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-14 HARD-004 approve", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"approve\",\"transaction_id\":\"TXN-H004\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-15 HARD-005 escalate", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"escalate\",\"transaction_id\":\"TXN-H005\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-16 HARD-006 flag", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"flag\",\"transaction_id\":\"TXN-H006\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-17 CRIT-001 approve", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"approve\",\"transaction_id\":\"TXN-C001\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-18 CRIT-002 reject", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"reject\",\"transaction_id\":\"TXN-C002\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {"name": "O-19 CRIT-003 escalate", "request": {"method": "POST", "header": [{"key": "Content-Type", "value": "application/json"}], "body": {"mode": "raw", "raw": "{\"action_type\":\"escalate\",\"transaction_id\":\"TXN-C003\"}"}, "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}}},
+        {
+          "name": "O-20 CRIT-004 reject → done=true",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('reward=1.0', () => pm.expect(d.reward).to.eql(1.0));",
+            "pm.test('done=true', () => pm.expect(d.done).to.eql(true));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "POST",
+            "header": [{"key": "Content-Type", "value": "application/json"}],
+            "body": {"mode": "raw", "raw": "{\"action_type\":\"reject\",\"transaction_id\":\"TXN-C004\"}"},
+            "url": {"raw": "{{base_url}}/step", "host": ["{{base_url}}"], "path": ["step"]}
+          }
+        },
+        {
+          "name": "O-21 Grader — score=1.0 after perfect episode",
+          "event": [{"listen": "test", "script": {"exec": [
+            "const d = pm.response.json();",
+            "pm.test('normalised_score=1.0', () => pm.expect(d.normalised_score).to.eql(1.0));",
+            "pm.test('passed=true', () => pm.expect(d.passed).to.eql(true));",
+            "pm.test('budget_penalty=0', () => pm.expect(d.budget_penalty).to.eql(0.0));"
+          ], "type": "text/javascript"}}],
+          "request": {
+            "method": "GET",
+            "url": {"raw": "{{base_url}}/grader", "host": ["{{base_url}}"], "path": ["grader"]}
+          }
+        }
+      ]
+    }
+
+  ]
+}

README.md

@@ -0,0 +1,278 @@
+# PayOps — Payment Operations Incident Response
+
+An **OpenEnv-compatible** reinforcement-learning environment where an AI agent
+acts as a Payment Operations analyst.  The agent reviews financial transactions
+one by one and must decide the correct compliance action for each.
+
+---
+
+## Motivation
+
+Payment operations teams process thousands of transactions every day.  A
+skilled analyst uses dozens of signals — risk scores, velocity, KYC status,
+flag patterns — to make fast, accurate decisions.  This environment lets an AI
+agent learn and be evaluated on exactly this task, spanning clear-cut cases all
+the way to subtle adversarial patterns like model-score poisoning and
+Authorised Push Payment (APP) scams.
+
+---
+
+## Environment Description
+
+Each **episode** steps through 12 transactions (4 easy, 4 medium, 4 hard).
+For each transaction the agent observes a rich set of signals and submits one
+of six possible actions.  A reward is returned immediately, and the next
+transaction is presented until the episode is complete.
+
+---
+
+## Action Space
+
+| Action       | Description |
+|-------------|-------------|
+| `approve`   | Mark transaction as legitimate; allow it through |
+| `reject`    | Block the transaction outright |
+| `flag`      | Soft hold; mark for manual review |
+| `escalate`  | Route to senior compliance officer / fraud team |
+| `inspect`   | Request additional signals (logs, KYC, velocity) — yields reveal notes and a small reward; agent then acts again on the same transaction |
+| `hold`      | Temporary hold pending more information |
+
+---
+
+## Observation Space
+
+| Field                 | Type           | Description |
+|----------------------|----------------|-------------|
+| `transaction_id`     | `str`          | Unique transaction identifier |
+| `amount`             | `float`        | Transaction amount |
+| `currency`           | `str`          | ISO-4217 currency code |
+| `sender`             | `str`          | Sender identifier |
+| `receiver`           | `str`          | Receiver identifier |
+| `transaction_type`   | `str`          | transfer \| payment \| withdrawal \| refund \| internal |
+| `status`             | `str`          | pending \| approved \| rejected \| flagged \| escalated \| held \| inspected |
+| `risk_score`         | `float [0,1]`  | Composite ML risk score |
+| `flags`              | `List[str]`    | Active risk flags |
+| `velocity_1h`        | `int?`         | Transactions from sender in the past hour |
+| `country_risk`       | `str?`         | low \| medium \| high \| sanctioned |
+| `kyc_status`         | `str?`         | verified \| pending \| failed \| none |
+| `previous_violations`| `int?`         | Prior compliance violations |
+| `inspection_notes`   | `str?`         | Extra details revealed after an `inspect` action |
+| `task_id`            | `str`          | Identifier of the active task |
+| `task_difficulty`    | `str`          | easy \| medium \| hard |
+| `step_in_episode`    | `int`          | Steps elapsed in this episode |
+| `reward`             | `float`        | Reward from the last action |
+| `cumulative_reward`  | `float`        | Total reward so far this episode |
+| `done`               | `bool`         | Whether the episode has ended |
+| `info`               | `dict`         | Diagnostic info (event, correct action, etc.) |
+
+---
+
+## Task Descriptions
+
+### Easy (4 tasks — clear signals)
+
+| ID        | Description | Correct Action |
+|----------|-------------|----------------|
+| EASY-001 | Low-value domestic transfer between verified users; no flags | `approve` |
+| EASY-002 | Textbook fraud: unknown sender, offshore, sanctioned country, risk=0.97 | `reject` |
+| EASY-003 | Standard refund to verified customer; tiny amount, no flags | `approve` |
+| EASY-004 | ATM withdrawal burst — 15 withdrawals in 58 minutes | `flag` |
+
+### Medium (4 tasks — ambiguous, multi-signal reasoning required)
+
+| ID       | Description | Correct Action |
+|---------|-------------|----------------|
+| MED-001 | Large B2B wire, verified CFO, cross-border to medium-risk jurisdiction | `escalate` |
+| MED-002 | Internal treasury transfer; large amount, KYC pending renewal | `hold` |
+| MED-003 | Recurring subscription 3× higher than historical average | `flag` |
+| MED-004 | Payment to licensed crypto exchange from verified personal account | `flag` |
+
+### Hard (4 tasks — adversarial / edge-case)
+
+| ID        | Description | Correct Action |
+|----------|-------------|----------------|
+| HARD-001 | Fraud model poisoning: risk_score=0.18 but manual signals scream escalate | `escalate` |
+| HARD-002 | APP (Authorised Push Payment) scam: victim sending willingly to mule account | `reject` |
+| HARD-003 | Structuring / smurfing: three just-below-CTR-threshold payments, same UBO | `reject` |
+| HARD-004 | Legitimate FX correspondent banking settlement — looks alarming, is not | `approve` |
+
+---
+
+## Reward Design
+
+| Outcome | Reward |
+|---------|--------|
+| Correct action | **+1.0** |
+| Partial-credit adjacent action (per-task) | **+0.2 – +0.6** |
+| `inspect` (information seeking, first time) | **+0.15** |
+| `approve` when correct is `reject` / `escalate` | **−1.0** |
+| `approve` when correct is `flag` / `hold` | **−0.5** |
+| `reject` when correct is `approve` | **−0.5** |
+| Any other wrong action | **−0.25** |
+
+The **episode score** (0–1) is: `max(0, total_reward) / max_possible_reward`.
+A score ≥ 0.5 is considered a passing episode.
+
+---
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/reset` | Reset environment, return first observation |
+| `POST` | `/step` | Execute an action |
+| `GET`  | `/state` | Current internal environment state |
+| `GET`  | `/schema` | JSON schemas for action / observation / state |
+| `GET`  | `/tasks` | Full task list with metadata |
+| `GET`  | `/grader` | Grade the current episode |
+| `POST` | `/baseline` | Run rule-based baseline and return scores |
+| `GET`  | `/health` | Health check |
+| `WS`   | `/ws` | WebSocket persistent session |
+
+Interactive API docs: `http://localhost:8000/docs`
+
+---
+
+## Setup & Running
+
+### Local (Python)
+
+```bash
+# 1. Install dependencies
+pip install -r requirements.txt
+
+# 2. Start the server (from the parent directory of payops_env)
+PYTHONPATH=$(pwd) uvicorn payops_env.server.app:app --host 0.0.0.0 --port 8000
+
+# 3. Verify
+curl http://localhost:8000/health
+```
+
+### Run the baseline agent
+
+```bash
+# From the project root
+PYTHONPATH=$(pwd) python payops_env/scripts/baseline_agent.py
+```
+
+### Docker
+
+```bash
+# Build
+docker build -t payops-env .
+
+# Run locally on port 8000
+docker run -p 8000:7860 -e PORT=7860 payops-env
+
+# Verify
+curl http://localhost:8000/health
+```
+
+### HuggingFace Space
+
+The `Dockerfile` exposes port **7860** (HF Spaces default).  Push the repo to
+a HF Space with Docker runtime — no additional configuration required.
+
+---
+
+## Example Agent Interaction
+
+```python
+import httpx
+
+base = "http://localhost:8000"
+
+# Reset
+obs = httpx.post(f"{base}/reset").json()
+print(obs["transaction_id"], obs["risk_score"], obs["flags"])
+
+# Step
+while not obs["done"]:
+    # ... agent decides action_type ...
+    obs = httpx.post(f"{base}/step", json={
+        "action_type": "approve",
+        "transaction_id": obs["transaction_id"],
+    }).json()
+    print(f"reward={obs['reward']:+.2f}  done={obs['done']}")
+
+# Grade
+score = httpx.get(f"{base}/grader").json()
+print(f"Episode score: {score['normalised_score']:.4f}")
+```
+
+---
+
+## Baseline Results
+
+The rule-based baseline agent uses a deterministic priority-ordered policy.
+
+| Metric | Baseline |
+|--------|----------|
+| Normalised score | ~0.67 |
+| Total reward | ~8.0 / 12.0 |
+| Passed | Yes |
+| Strong at | Easy tasks, clear velocity/flag patterns |
+| Weak at | Hard adversarial tasks (e.g. FX settlement over-rejected) |
+
+Run `POST /baseline` to reproduce these results programmatically.
+
+---
+
+## Project Structure
+
+```
+payops_env/
+├── models.py              # PayOpsAction, PayOpsObservation, PayOpsState (Pydantic)
+├── environment.py         # PayOpsEnvironment — reset_async / step_async / state
+├── tasks.py               # 12 tasks (easy / medium / hard) with ground-truth labels
+├── grader.py              # Partial-credit reward function + episode grader
+├── scripts_util.py        # Baseline runner helper (used by /baseline endpoint)
+├── scripts/
+│   └── baseline_agent.py  # Standalone rule-based baseline agent
+├── server/
+│   └── app.py             # FastAPI server with all required endpoints
+├── openenv.yaml           # OpenEnv manifest
+├── Dockerfile             # Docker / HuggingFace Space container
+├── requirements.txt       # Python dependencies
+└── README.md              # This file
+```
+
+---
+
+## Evaluation Criteria Alignment
+
+| Criterion | Implementation |
+|-----------|---------------|
+| Real-world utility | Payment fraud and compliance triage — a genuine operational domain |
+| Task & grader quality | 12 tasks across 3 difficulty tiers; partial-credit grader; clear pass/fail |
+| Environment design | Rich observation space; 6-action space; inspect mechanic; episode state tracking |
+| Code quality & spec compliance | Pydantic v2 models; async API; all required endpoints; openenv.yaml |
+| Creativity & novelty | Adversarial model-poisoning task; APP scam; FX settlement edge-case |
+
+
+| Outcome                          | Reward |
+|----------------------------------|--------|
+| Correct action                   | +1.0   |
+| Approve a dangerous transaction  | -2.0   |
+| Wrong reject                     | -0.5   |
+| Wrong flag / escalate            | -0.25  |
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the server
+uvicorn server.app:app --reload
+
+# Run the baseline agent (no server needed)
+python scripts/baseline_agent.py
+```
+
+## Docker
+
+```bash
+docker build -t payops-env:latest .
+docker run -p 8000:8000 payops-env:latest
+```

TESTING.md

@@ -0,0 +1,905 @@
+# PayOps Environment — Test Cases & Testing Guide
+
+This document covers every testable behaviour of the PayOps OpenEnv, organised
+by endpoint and scenario. Each test shows the exact command to run, the
+expected response, and what a failure looks like.
+
+---
+
+## Prerequisites
+
+```bash
+# 1. Start the server (run from /Users/padmapriya)
+PYTHONPATH=/Users/padmapriya uvicorn payops_env.server.app:app --host 0.0.0.0 --port 8000
+
+# 2. Confirm it is up (should return {"status":"ok",...})
+curl -s http://localhost:8000/health
+```
+
+All `curl` commands below assume the server is running on `localhost:8000`.
+
+---
+
+## T-01  Health Check
+
+**Goal:** Confirm the server is alive and returns version metadata.
+
+```bash
+curl -s http://localhost:8000/health
+```
+
+**Expected output**
+```json
+{"status": "ok", "environment": "payops_env", "version": "1.0.0"}
+```
+
+**Failure indicator:** Connection refused, or any field missing / wrong value.
+
+---
+
+## T-02  Schema Endpoint
+
+**Goal:** Verify that action, observation, and state JSON schemas are served correctly.
+
+```bash
+curl -s http://localhost:8000/schema | python3 -m json.tool
+```
+
+**Expected output (condensed)**
+```json
+{
+  "action":      { "title": "PayOpsAction", "type": "object", ... },
+  "observation": { "title": "PayOpsObservation", "type": "object", ... },
+  "state":       { "title": "PayOpsState", "type": "object", ... }
+}
+```
+
+**Checks to verify manually:**
+- `action.properties` includes `action_type`, `transaction_id`, `reason`, `confidence`
+- `observation.properties` includes `risk_score`, `flags`, `kyc_status`, `velocity_1h`
+- HTTP status code is `200`
+
+---
+
+## T-03  Tasks Endpoint
+
+**Goal:** Confirm all 12 tasks are returned with the correct difficulty distribution.
+
+```bash
+curl -s http://localhost:8000/tasks | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('Total tasks:', d['count'])
+from collections import Counter
+c = Counter(t['difficulty'] for t in d['tasks'])
+print('By difficulty:', dict(c))
+print()
+for t in d['tasks']:
+    print(f\"  {t['task_id']:12} [{t['difficulty']:6}] correct={t['correct_action']}\")
+"
+```
+
+**Expected output**
+```
+Total tasks: 12
+By difficulty: {'easy': 4, 'medium': 4, 'hard': 4}
+
+  EASY-001     [easy  ] correct=approve
+  EASY-002     [easy  ] correct=reject
+  EASY-003     [easy  ] correct=approve
+  EASY-004     [easy  ] correct=flag
+  MED-001      [medium] correct=escalate
+  MED-002      [medium] correct=hold
+  MED-003      [medium] correct=flag
+  MED-004      [medium] correct=flag
+  HARD-001     [hard  ] correct=escalate
+  HARD-002     [hard  ] correct=reject
+  HARD-003     [hard  ] correct=reject
+  HARD-004     [hard  ] correct=approve
+```
+
+**Failure indicator:** count != 12, missing difficulty tier, wrong correct_action.
+
+---
+
+## T-04  Reset
+
+**Goal:** Reset the environment and confirm the first task is EASY-001.
+
+```bash
+curl -s -X POST http://localhost:8000/reset | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('task_id          :', d['task_id'])
+print('transaction_id   :', d['transaction_id'])
+print('difficulty        :', d['task_difficulty'])
+print('status            :', d['status'])
+print('done              :', d['done'])
+print('reward            :', d['reward'])
+print('cumulative_reward :', d['cumulative_reward'])
+print('risk_score        :', d['risk_score'])
+"
+```
+
+**Expected output**
+```
+task_id          : EASY-001
+transaction_id   : TXN-E001
+difficulty        : easy
+status            : pending
+done              : false
+reward            : 0.0
+cumulative_reward : 0.0
+risk_score        : 0.05
+```
+
+**Failure indicator:** `done=true`, `reward != 0`, wrong `task_id`.
+
+---
+
+## T-05  Correct Action — Full Credit (+1.0)
+
+**Goal:** Submit the correct action for EASY-001 (`approve`) and receive reward +1.0.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null   # fresh start
+
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"approve","transaction_id":"TXN-E001"}' \
+| python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('reward           :', d['reward'])
+print('correct info     :', d['info'].get('correct_action'))
+print('action taken     :', d['info'].get('action_taken'))
+"
+```
+
+**Expected output**
+```
+reward           : 1.0
+correct info     : approve
+action taken     : approve
+```
+
+---
+
+## T-06  Wrong Action — Penalty (approve on fraud = -1.0)
+
+**Goal:** Skip to EASY-002 (textbook fraud) and approve it. Expect -1.0 penalty.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+# Step past EASY-001
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"approve","transaction_id":"TXN-E001"}' > /dev/null
+
+# Now on EASY-002 (correct=reject). Try approving it.
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"approve","transaction_id":"TXN-E002"}' \
+| python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('reward       :', d['reward'])
+print('correct was  :', d['info'].get('correct_action'))
+"
+```
+
+**Expected output**
+```
+reward       : -1.0
+correct was  : reject
+```
+
+---
+
+## T-07  Partial Credit Action
+
+**Goal:** On MED-001 (correct=`escalate`), submit `flag` — should earn +0.5 partial credit.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+# Step through EASY tasks 1-4 with any actions
+for ACTION in approve reject approve reject; do
+  curl -s -X POST http://localhost:8000/step \
+    -H "Content-Type: application/json" \
+    -d "{\"action_type\":\"$ACTION\",\"transaction_id\":\"dummy\"}" > /dev/null
+done
+
+# Now on MED-001 (correct=escalate). Submit flag.
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"flag","transaction_id":"TXN-M001"}' \
+| python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('reward       :', d['reward'])
+print('correct was  :', d['info'].get('correct_action'))
+print('partial?     :', 0 < d['reward'] < 1.0)
+"
+```
+
+**Expected output**
+```
+reward       : 0.5
+correct was  : escalate
+partial?     : True
+```
+
+---
+
+## T-08  Inspect Action — Information Reveal
+
+**Goal:** Use `inspect` on EASY-001 to receive investigation notes and a small reward (+0.15). The episode should NOT advance (still on same transaction).
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"inspect","transaction_id":"TXN-E001"}' \
+| python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('reward            :', d['reward'])
+print('status            :', d['status'])
+print('task_id           :', d['task_id'])    # should still be EASY-001
+print('inspection_notes  :', d['inspection_notes'])
+"
+```
+
+**Expected output**
+```
+reward            : 0.15
+status            : inspected
+task_id           : EASY-001
+inspection_notes  : Sender account opened 3 years ago. Consistent transaction history. KYC fully verified.
+```
+
+---
+
+## T-09  Double Inspect — No Double-Dipping
+
+**Goal:** Inspect the same transaction twice. Second inspect should return reward 0.0 (already inspected).
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+
+# First inspect — reward 0.15
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"inspect","transaction_id":"TXN-E001"}' \
+| python3 -c "import sys,json; d=json.load(sys.stdin); print('First inspect reward:', d['reward'])"
+
+# Second inspect — reward 0.0
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"inspect","transaction_id":"TXN-E001"}' \
+| python3 -c "import sys,json; d=json.load(sys.stdin); print('Second inspect reward:', d['reward'])"
+```
+
+**Expected output**
+```
+First inspect reward: 0.15
+Second inspect reward: 0.0
+```
+
+---
+
+## T-10  Invalid Action Type
+
+**Goal:** Send an unsupported action type and receive a 422 validation error.
+
+```bash
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"delete","transaction_id":"TXN-E001"}' \
+| python3 -c "import sys,json; d=json.load(sys.stdin); print('status_code:', d.get('detail','')[:60])"
+```
+
+**Expected output**
+```
+status_code: Invalid action_type 'delete'. Valid values: ['approve', 'escal
+```
+
+HTTP status code should be `422`.
+
+---
+
+## T-11  Step Without Reset
+
+**Goal:** Call `/step` without calling `/reset` first. Should return a `400` error.
+
+```bash
+# Kill and restart server to guarantee clean state
+# Then immediately step without reset:
+curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"approve","transaction_id":"TXN-E001"}'
+```
+
+**Expected output**
+```
+400
+```
+
+---
+
+## T-12  State Endpoint Tracking
+
+**Goal:** Confirm `/state` reflects the episode progress correctly.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+
+curl -s http://localhost:8000/state | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('step_count            :', d['step_count'])
+print('transactions_processed:', d['transactions_processed'])
+print('total_tasks           :', d['total_tasks'])
+print('done                  :', d['done'])
+"
+
+# Take one step
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type":"approve","transaction_id":"TXN-E001"}' > /dev/null
+
+curl -s http://localhost:8000/state | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('step_count            :', d['step_count'])
+print('transactions_processed:', d['transactions_processed'])
+print('last_action           :', d['last_action'])
+print('cumulative_reward     :', d['cumulative_reward'])
+"
+```
+
+**Expected output (before step)**
+```
+step_count            : 0
+transactions_processed: 0
+total_tasks           : 12
+done                  : false
+```
+
+**Expected output (after step)**
+```
+step_count            : 1
+transactions_processed: 1
+last_action           : approve
+cumulative_reward     : 1.0
+```
+
+---
+
+## T-13  Complete Episode — Done Flag
+
+**Goal:** Step through all 12 tasks and confirm `done=true` on the last step.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+
+python3 - <<'EOF'
+import httpx, asyncio
+
+BASE = "http://localhost:8000"
+ACTIONS = [
+    "approve","reject","approve","flag",   # easy
+    "escalate","hold","flag","flag",       # medium
+    "escalate","reject","reject","approve" # hard (perfect sequence)
+]
+
+client = httpx.Client()
+txn_ids = [t["transaction_id"] for t in client.get(f"{BASE}/tasks").json()["tasks"]]
+
+for i, (action, txn) in enumerate(zip(ACTIONS, txn_ids)):
+    resp = client.post(f"{BASE}/step", json={"action_type": action, "transaction_id": txn}).json()
+    print(f"Step {i+1:2d}  {txn:12}  action={action:10}  reward={resp['reward']:+.2f}  done={resp['done']}")
+
+client.close()
+EOF
+```
+
+**Expected output (last line)**
+```
+Step 12  TXN-H004     action=approve      reward=+1.00  done=True
+```
+
+All other steps should show `done=False`.
+
+---
+
+## T-14  Grader Endpoint
+
+**Goal:** Grade and score the episode immediately after completing all steps.
+
+```bash
+# Run the perfect sequence first (T-13 above), then:
+curl -s http://localhost:8000/grader | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('total_reward      :', d['total_reward'])
+print('max_possible      :', d['max_possible_reward'])
+print('normalised_score  :', d['normalised_score'])
+print('passed            :', d['passed'])
+print()
+for t in d['per_task']:
+    mark = '✓' if t['correct'] else '✗'
+    print(f\"  {mark} {t['task_id']:12} action={t['action_taken']:10} correct={t['correct_action']:10} reward={t['reward']:+.2f}\")
+"
+```
+
+**Expected output (perfect run)**
+```
+total_reward      : 12.0
+max_possible      : 12.0
+normalised_score  : 1.0
+passed            : True
+
+  ✓ EASY-001     action=approve     correct=approve     reward=+1.00
+  ✓ EASY-002     action=reject      correct=reject      reward=+1.00
+  ...
+  ✓ HARD-004     action=approve     correct=approve     reward=+1.00
+```
+
+---
+
+## T-15  Grader Without Episode
+
+**Goal:** Call `/grader` before any steps — should return a 400 error.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+curl -s http://localhost:8000/grader
+```
+
+**Expected output**
+```json
+{"error": "No actions recorded. Run /reset then /step first."}
+```
+
+---
+
+## T-16  Baseline Endpoint
+
+**Goal:** Confirm `/baseline` runs the rule-based agent and returns a normalised score ≥ 0.5.
+
+```bash
+curl -s -X POST http://localhost:8000/baseline | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('normalised_score :', d['normalised_score'])
+print('total_reward     :', d['total_reward'])
+print('steps            :', d['steps'])
+print('passed (>=0.5)   :', d['normalised_score'] >= 0.5)
+print()
+for t in d['scores']:
+    mark = '✓' if t['correct'] else '✗'
+    print(f\"  {mark} {t['task_id']:12} [{t['difficulty']:6}] action={t['action_taken']:10} reward={t['reward']:+.2f}\")
+"
+```
+
+**Expected output**
+```
+normalised_score : 0.7292
+total_reward     : 8.75
+steps            : 12
+passed (>=0.5)   : True
+
+  ✓ EASY-001     [easy  ] action=approve     reward=+1.00
+  ✓ EASY-002     [easy  ] action=reject      reward=+1.00
+  ...
+```
+
+---
+
+## T-17  Optional Reason and Confidence Fields
+
+**Goal:** Submit an action with optional `reason` and `confidence`. Should be accepted without error.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+
+curl -s -X POST http://localhost:8000/step \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action_type": "flag",
+    "transaction_id": "TXN-E001",
+    "reason": "Low risk but flagging for audit trail verification",
+    "confidence": 0.82
+  }' \
+| python3 -c "import sys,json; d=json.load(sys.stdin); print('HTTP OK, reward:', d['reward'])"
+```
+
+**Expected output**
+```
+HTTP OK, reward: 0.3
+```
+
+(0.3 = partial credit for flagging when correct action is approve)
+
+---
+
+## T-18  Hard Task — Model Poisoning (HARD-001)
+
+**Goal:** Demonstrate that the low risk_score (0.18) is a trap. The correct action is `escalate`.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+# Advance to HARD-001 (task 9) — step through easy + medium with dummy actions
+python3 - <<'EOF'
+import httpx
+BASE = "http://localhost:8000"
+c = httpx.Client()
+tasks = c.get(f"{BASE}/tasks").json()["tasks"]
+
+# Steps 1-8: easy + medium
+for t in tasks[:8]:
+    c.post(f"{BASE}/step", json={"action_type": "approve", "transaction_id": t["transaction_id"]})
+
+# Step 9: HARD-001 — agent trusts the low risk_score and approves (wrong!)
+resp_wrong = c.post(f"{BASE}/step", json={
+    "action_type": "approve", "transaction_id": "TXN-H001"
+}).json()
+print("Trusted ML score → approve")
+print("  reward   :", resp_wrong["reward"])   # expect -0.5
+print("  correct  :", resp_wrong["info"]["correct_action"])
+
+# Reset and do it correctly
+c.post(f"{BASE}/reset")
+for t in tasks[:8]:
+    c.post(f"{BASE}/step", json={"action_type": "approve", "transaction_id": t["transaction_id"]})
+
+resp_correct = c.post(f"{BASE}/step", json={
+    "action_type": "escalate", "transaction_id": "TXN-H001"
+}).json()
+print("\nOverrode ML score → escalate")
+print("  reward   :", resp_correct["reward"])  # expect +1.0
+c.close()
+EOF
+```
+
+**Expected output**
+```
+Trusted ML score → approve
+  reward   : -0.5
+  correct  : escalate
+
+Overrode ML score → escalate
+  reward   : 1.0
+```
+
+---
+
+## T-19  Inspect Reveals Hidden Context (HARD-001)
+
+**Goal:** Inspect HARD-001 to reveal the mule-account intelligence note before deciding.
+
+```bash
+curl -s -X POST http://localhost:8000/reset > /dev/null
+# Advance to HARD-001
+python3 - <<'EOF'
+import httpx
+BASE = "http://localhost:8000"
+c = httpx.Client()
+tasks = c.get(f"{BASE}/tasks").json()["tasks"]
+for t in tasks[:8]:
+    c.post(f"{BASE}/step", json={"action_type": "approve", "transaction_id": t["transaction_id"]})
+
+# Inspect HARD-001
+resp = c.post(f"{BASE}/step", json={
+    "action_type": "inspect", "transaction_id": "TXN-H001"
+}).json()
+print("Inspect reward :", resp["reward"])
+print("Notes          :", resp["inspection_notes"])
+c.close()
+EOF
+```
+
+**Expected output**
+```
+Inspect reward : 0.15
+Notes          : Account created 7 days ago. This is the first outbound transfer. Receiver matches a pattern of solicitor-impersonation mule accounts flagged in last month's intelligence bulletin. Risk model underscored due to clean transaction history (new account).
+```
+
+---
+
+## T-20  WebSocket Session
+
+**Goal:** Run a full reset → step sequence over the WebSocket endpoint.
+
+```bash
+pip install websockets -q   # if not already installed
+
+python3 - <<'EOF'
+import asyncio, json, websockets
+
+async def test_ws():
+    uri = "ws://localhost:8000/ws"
+    async with websockets.connect(uri) as ws:
+        # Reset
+        await ws.send(json.dumps({"type": "reset"}))
+        obs = json.loads(await ws.recv())
+        print("Reset  →", obs["transaction_id"], "risk:", obs["risk_score"])
+
+        # Step – approve
+        await ws.send(json.dumps({
+            "type": "step",
+            "action_type": "approve",
+            "transaction_id": obs["transaction_id"]
+        }))
+        obs2 = json.loads(await ws.recv())
+        print("Step   →", "reward:", obs2["reward"], "next:", obs2["transaction_id"])
+
+        # State
+        await ws.send(json.dumps({"type": "state"}))
+        state = json.loads(await ws.recv())
+        print("State  →", "steps:", state["step_count"], "txns:", state["transactions_processed"])
+
+asyncio.run(test_ws())
+EOF
+```
+
+**Expected output**
+```
+Reset  → TXN-E001 risk: 0.05
+Step   → reward: 1.0 next: TXN-E002
+State  → steps: 1 txns: 1
+```
+
+---
+
+## T-21  Baseline Agent Script (Standalone)
+
+**Goal:** Run the standalone Python baseline script independently of the server.
+
+```bash
+cd /Users/padmapriya
+PYTHONPATH=/Users/padmapriya python3 payops_env/scripts/baseline_agent.py
+```
+
+**Expected output (last few lines)**
+```
+============================================================
+  Episode Summary
+============================================================
+  Steps             : 12
+  Total reward      : +8.75
+  Max possible      : 12.00
+  Normalised score  : 0.7292
+  Passed (≥0.5)     : YES ✓
+============================================================
+```
+
+---
+
+## T-22  All Actions Are Valid on Each Task
+
+**Goal:** Confirm every action type is accepted without error (even if penalised).
+
+```bash
+python3 - <<'EOF'
+import httpx
+
+BASE = "http://localhost:8000"
+ACTIONS = ["approve", "reject", "flag", "escalate", "inspect", "hold"]
+
+c = httpx.Client()
+for action in ACTIONS:
+    c.post(f"{BASE}/reset")
+    resp = c.post(f"{BASE}/step", json={
+        "action_type": action,
+        "transaction_id": "TXN-E001"
+    })
+    print(f"action={action:10}  HTTP={resp.status_code}  reward={resp.json()['reward']:+.2f}")
+c.close()
+EOF
+```
+
+**Expected output**
+```
+action=approve     HTTP=200  reward=+1.00
+action=reject      HTTP=200  reward=-0.50
+action=flag        HTTP=200  reward=+0.30
+action=escalate    HTTP=200  reward=-0.25
+action=inspect     HTTP=200  reward=+0.15
+action=hold        HTTP=200  reward=-0.25
+```
+
+---
+
+## T-23  Full Perfect Episode (Score = 1.0)
+
+**Goal:** Submit all 12 correct actions and confirm normalised_score = 1.0.
+
+```bash
+python3 - <<'EOF'
+import httpx
+
+BASE = "http://localhost:8000"
+c = httpx.Client()
+
+tasks = c.get(f"{BASE}/tasks").json()["tasks"]
+c.post(f"{BASE}/reset")
+
+for t in tasks:
+    resp = c.post(f"{BASE}/step", json={
+        "action_type": t["correct_action"],
+        "transaction_id": t["transaction_id"]
+    }).json()
+    mark = "✓" if resp["reward"] == 1.0 else "✗"
+    print(f"{mark} {t['task_id']:12} action={t['correct_action']:10} reward={resp['reward']:+.2f}")
+
+score = c.get(f"{BASE}/grader").json()
+print()
+print("Normalised score:", score["normalised_score"])
+print("Passed          :", score["passed"])
+c.close()
+EOF
+```
+
+**Expected output**
+```
+✓ EASY-001     action=approve     reward=+1.00
+✓ EASY-002     action=reject      reward=+1.00
+✓ EASY-003     action=approve     reward=+1.00
+✓ EASY-004     action=flag        reward=+1.00
+✓ MED-001      action=escalate    reward=+1.00
+✓ MED-002      action=hold        reward=+1.00
+✓ MED-003      action=flag        reward=+1.00
+✓ MED-004      action=flag        reward=+1.00
+✓ HARD-001     action=escalate    reward=+1.00
+✓ HARD-002     action=reject      reward=+1.00
+✓ HARD-003     action=reject      reward=+1.00
+✓ HARD-004     action=approve     reward=+1.00
+
+Normalised score: 1.0
+Passed          : True
+```
+
+---
+
+## T-24  Worst-Case Episode (Approve Everything)
+
+**Goal:** Approve all 12 transactions (maximally wrong) and confirm very low score.
+
+```bash
+python3 - <<'EOF'
+import httpx
+
+BASE = "http://localhost:8000"
+c = httpx.Client()
+
+tasks = c.get(f"{BASE}/tasks").json()["tasks"]
+c.post(f"{BASE}/reset")
+
+total = 0
+for t in tasks:
+    resp = c.post(f"{BASE}/step", json={
+        "action_type": "approve",
+        "transaction_id": t["transaction_id"]
+    }).json()
+    total += resp["reward"]
+    print(f"{t['task_id']:12} correct={t['correct_action']:10} reward={resp['reward']:+.2f}")
+
+score = c.get(f"{BASE}/grader").json()
+print()
+print(f"Total reward     : {total:+.2f}")
+print(f"Normalised score : {score['normalised_score']}")
+print(f"Passed           : {score['passed']}")
+c.close()
+EOF
+```
+
+**Expected outcome:** Several `-1.0` and `-0.5` penalties. Normalised score near or equal to `0.0`. `passed=False`.
+
+---
+
+## Quick Reference — Expected Rewards Per Action
+
+| Scenario | Action | Reward |
+|----------|--------|--------|
+| Correct decision | any | `+1.0` |
+| Inspect (first time) | `inspect` | `+0.15` |
+| Inspect (already inspected) | `inspect` | `0.0` |
+| Partial credit (task-specific) | adjacent | `+0.2` – `+0.6` |
+| Approve fraud/escalation | `approve` | `-1.0` |
+| Approve flagged/held | `approve` | `-0.5` |
+| Reject legitimate tx | `reject` | `-0.5` |
+| Any other wrong action | any | `-0.25` |
+
+---
+
+## Quick Reference — Correct Actions per Task
+
+| Task ID | Difficulty | Correct Action | Key Signal |
+|---------|-----------|----------------|------------|
+| EASY-001 | easy | `approve` | risk=0.05, no flags, verified KYC |
+| EASY-002 | easy | `reject` | sanctioned country, unknown sender, risk=0.97 |
+| EASY-003 | easy | `approve` | small refund, risk=0.03, verified |
+| EASY-004 | easy | `flag` | velocity_1h=15 (ATM burst) |
+| MED-001 | medium | `escalate` | large B2B, cross-border, medium-risk country |
+| MED-002 | medium | `hold` | KYC pending, large internal transfer |
+| MED-003 | medium | `flag` | amount 3× historical average |
+| MED-004 | medium | `flag` | crypto exchange, moderate risk |
+| HARD-001 | hard | `escalate` | risk_score=0.18 is poisoned — manual flags say escalate |
+| HARD-002 | hard | `reject` | APP scam, mule account pattern |
+| HARD-003 | hard | `reject` | structuring/smurfing, KYC failed |
+| HARD-004 | hard | `approve` | legitimate FX settlement — looks scary, is fine |
+
+---
+
+## Running All Tests in One Script
+
+Save the following as `run_tests.sh` and execute from `/Users/padmapriya`:
+
+```bash
+#!/usr/bin/env bash
+# run_tests.sh — smoke-test all PayOps endpoints
+
+set -e
+BASE="http://localhost:8000"
+PASS=0
+FAIL=0
+
+check() {
+  local name="$1"
+  local got="$2"
+  local want="$3"
+  if echo "$got" | grep -q "$want"; then
+    echo "  ✓  $name"
+    ((PASS++))
+  else
+    echo "  ✗  $name  (expected '$want', got '$got')"
+    ((FAIL++))
+  fi
+}
+
+echo "=== PayOps Test Suite ==="
+
+check "T-01 health"        "$(curl -s $BASE/health)"              '"status":"ok"'
+check "T-02 schema"        "$(curl -s $BASE/schema)"              '"PayOpsAction"'
+check "T-03 tasks count"   "$(curl -s $BASE/tasks)"               '"count":12'
+check "T-04 reset"         "$(curl -s -X POST $BASE/reset)"       '"task_id":"EASY-001"'
+check "T-05 correct step"  "$(curl -s -X POST $BASE/step -H 'Content-Type: application/json' -d '{"action_type":"approve","transaction_id":"TXN-E001"}')"  '"reward":1.0'
+check "T-10 invalid action" "$(curl -s -X POST $BASE/step -H 'Content-Type: application/json' -d '{"action_type":"delete","transaction_id":"TXN-E001"}')" "Invalid action_type"
+check "T-16 baseline"      "$(curl -s -X POST $BASE/baseline)"    '"normalised_score"'
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+```
+
+```bash
+cd /Users/padmapriya
+bash payops_env/run_tests.sh
+```
+
+**Expected output**
+```
+=== PayOps Test Suite ===
+  ✓  T-01 health
+  ✓  T-02 schema
+  ✓  T-03 tasks count
+  ✓  T-04 reset
+  ✓  T-05 correct step
+  ✓  T-10 invalid action
+  ✓  T-16 baseline
+
+Results: 7 passed, 0 failed
+```
+
+---
+
+## Interactive API Explorer
+
+FastAPI serves auto-generated interactive docs. Open in a browser while the server is running:
+
+```
+http://localhost:8000/docs      ← Swagger UI (try endpoints in-browser)
+http://localhost:8000/redoc     ← ReDoc documentation
+```

environment.py

@@ -0,0 +1,287 @@
+"""
+PayOps Environment — core simulation.
+
+Supports all 10 action types:
+  Terminal decisions: approve | reject | flag | escalate | hold
+  Investigation sub-actions: inspect | request_docs | verify_kyc |
+                             contact_sender | file_sar
+
+Investigation sub-actions do NOT advance the task pointer; they reveal
+additional context and consume budget.  A file_sar sub-action is required
+for full credit on regulatory tasks.
+
+Multi-step chain tasks (chain_total > 1) are presented as a single task
+entry; the grader handles them as one decision unit.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections import deque
+from typing import Deque, List, Optional
+
+from payops_env.grader import INVESTIGATION_BONUS, grade
+from payops_env.models import PayOpsAction, PayOpsObservation, PayOpsState
+from payops_env.tasks import ACTION_COSTS, TASKS, PayOpsTask
+
+
+TERMINAL_ACTIONS   = {"approve", "reject", "flag", "escalate", "hold"}
+INVESTIGATION_ACTIONS = {"inspect", "request_docs", "verify_kyc", "contact_sender", "file_sar"}
+VALID_ACTIONS      = TERMINAL_ACTIONS | INVESTIGATION_ACTIONS
+
+_RECENT_WINDOW = 4   # how many past (task_id, action) pairs to surface in obs
+
+
+class PayOpsEnvironment:
+    """
+    OpenEnv-compatible environment for Payment Operations triage.
+
+    An episode proceeds through every task in TASKS.  For each task the
+    agent may issue any number of investigation sub-actions before a
+    terminal decision closes the task.
+
+    Budget
+    ------
+    The agent starts with ``budget_limit`` points.  Each investigation
+    sub-action deducts its cost (see tasks.ACTION_COSTS).  Budget overspend
+    is penalised in grade_episode; within the environment it is tracked but
+    does not terminate the episode.
+    """
+
+    BUDGET_LIMIT = 5.0
+
+    def __init__(self):
+        self._tasks: List[PayOpsTask] = []
+        self._current_task: Optional[PayOpsTask] = None
+        self._state: PayOpsState = PayOpsState()
+        self._used_inv: dict = {}       # task_id → set of investigation actions used
+        self._sar_filed: set = set()    # task_ids where file_sar was issued
+        self._recent_decisions: Deque  = deque(maxlen=_RECENT_WINDOW)
+
+    # ------------------------------------------------------------------
+    # OpenEnv API
+    # ------------------------------------------------------------------
+
+    async def reset_async(self) -> PayOpsObservation:
+        self._tasks = list(TASKS)
+        self._current_task = self._tasks[0]
+        self._used_inv = {}
+        self._sar_filed = set()
+        self._recent_decisions = deque(maxlen=_RECENT_WINDOW)
+        self._state = PayOpsState(
+            episode_id=str(uuid.uuid4()),
+            step_count=0,
+            current_task_id=self._current_task.task_id,
+            transactions_processed=0,
+            total_tasks=len(self._tasks),
+            cumulative_reward=0.0,
+            actions_taken=[],
+            last_action=None,
+            done=False,
+            budget_spent=0.0,
+            budget_limit=self.BUDGET_LIMIT,
+            investigation_actions_used=[],
+            correct_decisions=0,
+            wrong_high_cost=0,
+            recent_decisions=[],
+        )
+        return self._make_observation(reward=0.0, done=False, info={"event": "reset"})
+
+    async def step_async(self, action: PayOpsAction) -> PayOpsObservation:
+        if self._current_task is None:
+            raise RuntimeError("Environment must be reset before stepping.")
+
+        action_type = action.action_type.lower()
+        if action_type not in VALID_ACTIONS:
+            raise ValueError(
+                f"Invalid action '{action_type}'. "
+                f"Valid actions: {sorted(VALID_ACTIONS)}"
+            )
+
+        task = self._current_task
+        task_id = task.task_id
+        cost = ACTION_COSTS.get(action_type, 0.0)
+
+        # Deduct cost
+        self._state.budget_spent = round(self._state.budget_spent + cost, 4)
+        self._state.step_count   += 1
+        self._state.actions_taken.append(action_type)
+        self._state.last_action   = action_type
+
+        # ── INVESTIGATION SUB-ACTIONS ────────────────────────────────────
+        if action_type in INVESTIGATION_ACTIONS:
+            used = self._used_inv.setdefault(task_id, set())
+            already = action_type in used
+            reward = 0.0 if already else INVESTIGATION_BONUS
+            used.add(action_type)
+            self._state.investigation_actions_used.append(action_type)
+            self._state.cumulative_reward = round(
+                self._state.cumulative_reward + reward, 4
+            )
+
+            # Determine reveal text
+            reveal_text: Optional[str] = None
+            reveal_field: Optional[str] = None
+            if action_type == "inspect":
+                reveal_text  = task.inspect_reveal  or "No additional information available."
+                reveal_field = "inspection_notes"
+            elif action_type == "request_docs":
+                reveal_text  = task.docs_reveal     or "No documents on record for this transaction."
+                reveal_field = "docs_notes"
+            elif action_type == "verify_kyc":
+                reveal_text  = task.kyc_reveal      or "KYC records could not be retrieved."
+                reveal_field = "kyc_notes"
+            elif action_type == "contact_sender":
+                reveal_text  = task.contact_reveal  or "Sender did not respond to contact attempt."
+                reveal_field = "contact_notes"
+            elif action_type == "file_sar":
+                self._sar_filed.add(task_id)
+                reveal_text  = (
+                    "SAR filed with FinCEN. Reference number will be generated within 24 h."
+                    if task.regulatory_action
+                    else "SAR filed. Note: this transaction may not meet SAR-filing threshold."
+                )
+                reveal_field = "docs_notes"
+
+            info = {
+                "event":        action_type,
+                "already_used": already,
+                reveal_field:   reveal_text,
+                "budget_remaining": round(
+                    self.BUDGET_LIMIT - self._state.budget_spent, 4
+                ),
+            }
+            return self._make_observation(
+                reward=reward, done=False, info=info, reveal_field=reveal_field, reveal_text=reveal_text
+            )
+
+        # ── TERMINAL DECISION ────────────────────────────────────────────
+        used_inv = list(self._used_inv.get(task_id, set()))
+        sar_used = task_id in self._sar_filed
+        inspected_already = "inspect" in self._used_inv.get(task_id, set())
+
+        reward = grade(action_type, task, inspected_already=inspected_already)
+        self._state.cumulative_reward = round(
+            self._state.cumulative_reward + reward, 4
+        )
+
+        is_correct = action_type == task.correct_action
+        if is_correct:
+            self._state.correct_decisions += 1
+        elif action_type == "approve" and task.correct_action in ("reject", "escalate"):
+            self._state.wrong_high_cost += 1
+
+        self._recent_decisions.append(
+            {"task_id": task_id, "action": action_type, "correct": is_correct}
+        )
+        self._state.recent_decisions = list(self._recent_decisions)
+        self._state.transactions_processed += 1
+
+        # Advance task pointer
+        task_idx = self._tasks.index(task)
+        remaining = self._tasks[task_idx + 1:]
+        done = len(remaining) == 0
+
+        if not done:
+            self._current_task = remaining[0]
+            self._state.current_task_id = self._current_task.task_id
+        else:
+            self._state.done = True
+
+        return self._make_observation(
+            reward=reward,
+            done=done,
+            info={
+                "event":          "step",
+                "action_taken":   action_type,
+                "correct_action": task.correct_action,
+                "task_id":        task_id,
+                "difficulty":     task.difficulty,
+                "is_correct":     is_correct,
+                "investigation_used": used_inv,
+                "budget_remaining":   round(
+                    self.BUDGET_LIMIT - self._state.budget_spent, 4
+                ),
+            },
+        )
+
+    def state(self) -> PayOpsState:
+        return self._state
+
+    def close(self):
+        pass
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _make_observation(
+        self,
+        reward: float,
+        done: bool,
+        info: dict,
+        reveal_field: Optional[str] = None,
+        reveal_text: Optional[str] = None,
+    ) -> PayOpsObservation:
+        task = self._current_task
+        steps_remaining = self._state.total_tasks - self._state.transactions_processed
+
+        return PayOpsObservation(
+            # ── transaction core ──
+            transaction_id=task.transaction_id,
+            amount=task.amount,
+            currency=task.currency,
+            sender=task.sender,
+            receiver=task.receiver,
+            transaction_type=task.transaction_type,
+            status=(
+                "inspected"
+                if info.get("event") in INVESTIGATION_ACTIONS
+                else ("done" if done else "pending")
+            ),
+            # ── risk signals ──
+            risk_score=task.risk_score,
+            ml_confidence=getattr(task, "ml_confidence", 0.90),
+            flags=list(task.flags),
+            velocity_1h=task.velocity_1h,
+            velocity_24h=getattr(task, "velocity_24h", None),
+            avg_transaction_amount=getattr(task, "avg_transaction_amount", None),
+            account_age_days=getattr(task, "account_age_days", None),
+            country_risk=task.country_risk,
+            kyc_status=task.kyc_status,
+            kyc_expiry_days=getattr(task, "kyc_expiry_days", None),
+            previous_violations=task.previous_violations,
+            previous_sars=getattr(task, "previous_sars", None),
+            counterparty_risk=getattr(task, "counterparty_risk", None),
+            # ── chain context ──
+            chain_total=getattr(task, "chain_total", 1),
+            chain_step=self._state.step_count,
+            chain_context=task.description,
+            # ── investigation reveals ──
+            inspection_notes=(
+                reveal_text if reveal_field == "inspection_notes" else info.get("inspection_notes")
+            ),
+            docs_notes=(
+                reveal_text if reveal_field == "docs_notes" else None
+            ),
+            kyc_notes=(
+                reveal_text if reveal_field == "kyc_notes" else None
+            ),
+            contact_notes=(
+                reveal_text if reveal_field == "contact_notes" else None
+            ),
+            # ── episode meta ──
+            task_id=task.task_id,
+            task_difficulty=task.difficulty,
+            step_in_episode=self._state.step_count,
+            steps_remaining=steps_remaining,
+            action_cost=ACTION_COSTS.get(info.get("event", ""), 0.0),
+            budget_remaining=round(self.BUDGET_LIMIT - self._state.budget_spent, 4),
+            recent_decisions=list(self._recent_decisions),
+            reward=reward,
+            cumulative_reward=self._state.cumulative_reward,
+            done=done,
+            info=info,
+        )
+
+

grader.py

@@ -0,0 +1,332 @@
+"""
+Grader for the PayOps environment.
+
+Reward design
+-------------
+The grader provides a *partial-credit* reward signal so agents receive
+feedback for cautious-but-not-perfect decisions.
+
+Base rewards
+~~~~~~~~~~~~
+  Correct action                        → +1.0  (full credit)
+  Partial-credit adjacent action        → per-task fraction of +1.0
+  approve when should be reject/escalate→ -1.0  (worst mistake — approving fraud)
+  approve when should be flag/hold      → -0.5
+  reject when should be approve         → -0.5  (over-rejection)
+  any other wrong terminal action       → -0.25
+
+  Investigation sub-actions  (non-terminal):
+    inspect / request_docs / verify_kyc / contact_sender used BEFORE the
+    terminal decision when the task requests them  → +0.15 bonus each
+    Same investigation action used twice on same task → +0.0 (no double-dip)
+
+Modifiers
+~~~~~~~~~
+  Difficulty weight     — multiplies the base reward:
+    easy=1.0, medium=1.2, hard=1.5, critical=2.0
+
+  Confidence bonus/penalty  — applied when the agent provides confidence:
+    high-confidence (≥0.8) AND correct   → +0.10
+    high-confidence (≥0.8) AND wrong     → -0.10
+
+  Cost penalty          — investigation actions have per-action budget costs
+    (see tasks.ACTION_COSTS).  Spending beyond budget_limit reduces episode
+    score by budget_overspend × 0.1.
+
+  Time penalty          — excessive investigation steps on a single task:
+    each investigation sub-action beyond the first on the same task → -0.05
+
+  Regulatory bonus      — for tasks requiring a SAR filing:
+    agent called file_sar before terminal action → +0.20 bonus
+
+Episode score (0–1)
+~~~~~~~~~~~~~~~~~~~
+  Computed by summing difficulty-weighted reward across all tasks and
+  normalising against the maximum theoretically achievable reward.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set, Tuple
+
+from payops_env.tasks import ACTION_COSTS, PayOpsTask
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+FULL_CREDIT = 1.0
+
+WRONG_APPROVE_FRAUD   = -1.0
+WRONG_APPROVE_CAUTION = -0.5
+WRONG_REJECT_GOOD     = -0.5
+WRONG_DEFAULT         = -0.25
+
+INVESTIGATION_BONUS       = 0.15   # per eligible sub-action used before terminal
+TIME_PENALTY_PER_EXTRA_STEP = 0.05 # per duplicate investigation on same task
+CONFIDENCE_CORRECT_BONUS  = 0.10
+CONFIDENCE_WRONG_PENALTY  = -0.10
+REGULATORY_BONUS          = 0.20   # filing SAR when required
+BUDGET_OVERSPEND_PENALTY  = 0.10   # per unit of budget exceeded
+
+DIFFICULTY_WEIGHT: Dict[str, float] = {
+    "easy":     1.0,
+    "medium":   1.2,
+    "hard":     1.5,
+    "critical": 2.0,
+}
+
+INVESTIGATION_ACTIONS: Set[str] = {
+    "inspect", "request_docs", "verify_kyc", "contact_sender", "file_sar"
+}
+
+
+# ---------------------------------------------------------------------------
+# Per-step helpers
+# ---------------------------------------------------------------------------
+
+def _is_investigation(action_type: str) -> bool:
+    return action_type in INVESTIGATION_ACTIONS
+
+
+def _base_terminal_reward(action_type: str, task: PayOpsTask) -> float:
+    """Return the base reward for a terminal action against a task."""
+    if action_type == task.correct_action:
+        return FULL_CREDIT
+
+    if action_type in task.partial_credit_actions:
+        return FULL_CREDIT * task.partial_credit_actions[action_type]
+
+    if action_type == "approve" and task.correct_action in ("reject", "escalate"):
+        return WRONG_APPROVE_FRAUD
+
+    if action_type == "approve" and task.correct_action in ("flag", "hold"):
+        return WRONG_APPROVE_CAUTION
+
+    if action_type == "reject" and task.correct_action == "approve":
+        return WRONG_REJECT_GOOD
+
+    return WRONG_DEFAULT
+
+
+def step_reward(
+    action_type: str,
+    task: PayOpsTask,
+    inspected_already: bool = False,
+) -> float:
+    """
+    Backward-compatible single-step reward used by the real-time environment.
+
+    Investigation actions return 0 (already handled inside environment.step_async
+    through the richer grader logic).  Terminal actions use the base reward table.
+    """
+    if _is_investigation(action_type):
+        return 0.0 if inspected_already else INVESTIGATION_BONUS
+
+    return _base_terminal_reward(action_type, task)
+
+
+# ---------------------------------------------------------------------------
+# Extended per-task grader (used by grade_episode)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TaskGradeDetail:
+    task_id: str
+    difficulty: str
+    weight: float
+    correct_action: str
+    terminal_action: str
+    investigation_actions_used: List[str]
+    base_reward: float
+    investigation_bonus: float
+    time_penalty: float
+    confidence_modifier: float
+    regulatory_bonus: float
+    total_reward: float
+    correct: bool
+    reward_breakdown: Dict[str, float] = field(default_factory=dict)
+
+
+def _grade_single_task(
+    terminal_action: str,
+    investigation_actions: List[str],   # sub-actions used BEFORE terminal
+    task: PayOpsTask,
+    agent_confidence: Optional[float] = None,
+) -> TaskGradeDetail:
+    weight = DIFFICULTY_WEIGHT.get(task.difficulty, 1.0)
+    base   = _base_terminal_reward(terminal_action, task)
+    correct = terminal_action == task.correct_action
+
+    # ── investigation bonus and time penalty ────────────────────────────────
+    inv_bonus  = 0.0
+    time_pen   = 0.0
+    eligible   = task.requires_investigation  # set of actions agent should use
+    seen_counts: Dict[str, int] = {}
+    for inv_action in investigation_actions:
+        seen_counts[inv_action] = seen_counts.get(inv_action, 0) + 1
+        if inv_action in eligible and seen_counts[inv_action] == 1:
+            inv_bonus += INVESTIGATION_BONUS
+        elif seen_counts[inv_action] > 1:
+            time_pen += TIME_PENALTY_PER_EXTRA_STEP
+
+    # ── confidence modifier ─────────────────────────────────────────────────
+    conf_mod = 0.0
+    if agent_confidence is not None and agent_confidence >= 0.8:
+        conf_mod = CONFIDENCE_CORRECT_BONUS if correct else CONFIDENCE_WRONG_PENALTY
+
+    # ── regulatory bonus ────────────────────────────────────────────────────
+    reg_bonus = 0.0
+    if task.regulatory_action and "file_sar" in investigation_actions:
+        reg_bonus = REGULATORY_BONUS
+
+    total = weight * (base + inv_bonus - time_pen + conf_mod + reg_bonus)
+
+    return TaskGradeDetail(
+        task_id=task.task_id,
+        difficulty=task.difficulty,
+        weight=weight,
+        correct_action=task.correct_action,
+        terminal_action=terminal_action,
+        investigation_actions_used=investigation_actions,
+        base_reward=round(base, 4),
+        investigation_bonus=round(inv_bonus, 4),
+        time_penalty=round(time_pen, 4),
+        confidence_modifier=round(conf_mod, 4),
+        regulatory_bonus=round(reg_bonus, 4),
+        total_reward=round(total, 4),
+        correct=correct,
+        reward_breakdown={
+            "base":           round(base, 4),
+            "weight":         weight,
+            "investigation":  round(inv_bonus, 4),
+            "time_penalty":   round(-time_pen, 4),
+            "confidence":     round(conf_mod, 4),
+            "regulatory":     round(reg_bonus, 4),
+            "weighted_total": round(total, 4),
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Episode grader
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EpisodeResult:
+    total_reward: float
+    max_possible_reward: float
+    normalised_score: float        # 0.0 – 1.0
+    per_task_rewards: List[dict]
+    budget_spent: float
+    budget_overspend: float
+    budget_penalty: float
+    passed: bool                   # normalised_score >= 0.5
+
+
+def grade_episode(
+    actions: List[str],
+    tasks: List[PayOpsTask],
+    confidences: Optional[List[Optional[float]]] = None,
+    budget_limit: float = 5.0,
+) -> EpisodeResult:
+    """
+    Grade a complete episode.
+
+    ``actions`` is the flat list of all actions taken (including investigation
+    sub-actions interspersed between terminal decisions).
+
+    The grader separates them by treating any action in INVESTIGATION_ACTIONS as
+    a sub-action that accumulates per-task until a terminal action closes the task.
+
+    Args:
+        actions:       Ordered list of action_type strings.
+        tasks:         Ordered list of PayOpsTask objects.
+        confidences:   Optional parallel list of agent confidence values (same
+                       length as ``actions``).  Use None for missing entries.
+        budget_limit:  Maximum investigation budget.  Overspend is penalised.
+
+    Returns:
+        EpisodeResult with comprehensive score breakdown.
+    """
+    if confidences is None:
+        confidences = [None] * len(actions)
+
+    per_task_details: List[TaskGradeDetail] = []
+    budget_spent = 0.0
+
+    task_idx   = 0
+    pending_inv: List[str]           = []   # sub-actions for current task
+    pending_conf: List[Optional[float]] = []
+
+    for i, (action, conf) in enumerate(zip(actions, confidences)):
+        budget_spent += ACTION_COSTS.get(action, 0.0)
+
+        if _is_investigation(action):
+            pending_inv.append(action)
+            pending_conf.append(conf)
+        else:
+            # terminal action → grade and advance task pointer
+            if task_idx >= len(tasks):
+                break
+            task = tasks[task_idx]
+            # Use the confidence from the terminal action step
+            detail = _grade_single_task(action, pending_inv, task, agent_confidence=conf)
+            per_task_details.append(detail)
+            pending_inv   = []
+            pending_conf  = []
+            task_idx     += 1
+
+    # Handle any tasks with no actions (agent ran out of steps)
+    while task_idx < len(tasks):
+        task = tasks[task_idx]
+        detail = _grade_single_task("approve", [], task, agent_confidence=None)
+        detail.base_reward = WRONG_DEFAULT
+        detail.total_reward = DIFFICULTY_WEIGHT.get(task.difficulty, 1.0) * WRONG_DEFAULT
+        per_task_details.append(detail)
+        task_idx += 1
+
+    # ── budget overspend penalty ─────────────────────────────────────────────
+    budget_overspend = max(0.0, budget_spent - budget_limit)
+    budget_penalty   = round(budget_overspend * BUDGET_OVERSPEND_PENALTY, 4)
+
+    total = sum(d.total_reward for d in per_task_details) - budget_penalty
+    max_possible = sum(
+        DIFFICULTY_WEIGHT.get(t.difficulty, 1.0) * FULL_CREDIT for t in tasks
+    )
+    normalised = max(0.0, min(1.0, total / max_possible)) if max_possible > 0 else 0.0
+
+    return EpisodeResult(
+        total_reward=round(total, 4),
+        max_possible_reward=round(max_possible, 4),
+        normalised_score=round(normalised, 4),
+        per_task_rewards=[
+            {
+                "task_id":                  d.task_id,
+                "difficulty":               d.difficulty,
+                "weight":                   d.weight,
+                "terminal_action":          d.terminal_action,
+                "correct_action":           d.correct_action,
+                "investigation_used":       d.investigation_actions_used,
+                "correct":                  d.correct,
+                "reward_breakdown":         d.reward_breakdown,
+                "weighted_reward":          d.total_reward,
+            }
+            for d in per_task_details
+        ],
+        budget_spent=round(budget_spent, 4),
+        budget_overspend=round(budget_overspend, 4),
+        budget_penalty=budget_penalty,
+        passed=normalised >= 0.5,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Convenience wrapper used by the environment
+# ---------------------------------------------------------------------------
+
+def grade(action_type: str, task: PayOpsTask, inspected_already: bool = False) -> float:
+    """Single-step reward used inside environment.step_async."""
+    return step_reward(action_type, task, inspected_already=inspected_already)
+

models.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Action space
+# ---------------------------------------------------------------------------
+
+class PayOpsAction(BaseModel):
+    """
+    Action submitted by the agent for a single transaction.
+
+    action_type choices
+    -------------------
+    approve        – mark transaction as legitimate and allow it through
+    reject         – block the transaction outright
+    flag           – mark for manual review with a soft hold
+    escalate       – route to senior compliance officer / fraud team
+    inspect        – pull additional signals (logs, KYC data, velocity)
+    hold           – temporary hold pending more information
+    request_docs   – ask sender for supporting documents (e.g. invoice, contract)
+    verify_kyc     – trigger an active KYC re-verification check
+    contact_sender – contact the sender directly to confirm intent
+    file_sar       – file a Suspicious Activity Report to regulator
+    """
+
+    action_type: str = Field(
+        ...,
+        description=(
+            "One of: approve | reject | flag | escalate | inspect | hold "
+            "| request_docs | verify_kyc | contact_sender | file_sar"
+        ),
+    )
+    transaction_id: str = Field(..., description="ID of the transaction being acted on")
+    reason: Optional[str] = Field(
+        default=None, description="Free-text rationale from the agent"
+    )
+    confidence: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description="Agent self-reported confidence [0, 1]. Used in reward shaping.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Observation space
+# ---------------------------------------------------------------------------
+
+class PayOpsObservation(BaseModel):
+    """
+    Structured observation returned after each step (and on reset).
+    Describes the current transaction visible to the agent.
+    """
+
+    # --- transaction identity ---
+    transaction_id: str
+    amount: float = Field(..., description="Transaction amount in the stated currency")
+    currency: str = Field(..., description="ISO-4217 currency code, e.g. USD, EUR")
+    sender: str = Field(..., description="Sender identifier (email / account / alias)")
+    receiver: str = Field(..., description="Receiver identifier")
+    transaction_type: str = Field(
+        default="transfer",
+        description="Type: transfer | payment | withdrawal | refund | internal | loan_repayment | payroll",
+    )
+
+    # --- risk signals ---
+    status: str = Field(
+        default="pending",
+        description=(
+            "Current status: pending | approved | rejected | flagged | escalated "
+            "| held | inspected | docs_requested | kyc_triggered | sender_contacted | sar_filed"
+        ),
+    )
+    risk_score: float = Field(
+        ..., ge=0.0, le=1.0, description="Composite ML risk score [0=low, 1=high]"
+    )
+    ml_confidence: float = Field(
+        default=0.9,
+        ge=0.0,
+        le=1.0,
+        description="Model's self-reported confidence in its own risk_score. Low = possibly poisoned.",
+    )
+    flags: List[str] = Field(
+        default_factory=list,
+        description="Active risk flags e.g. high_value, unknown_sender, velocity_breach",
+    )
+
+    # --- sender behaviour signals ---
+    velocity_1h: Optional[int] = Field(
+        default=None,
+        description="Number of transactions from this sender in the past hour",
+    )
+    velocity_24h: Optional[int] = Field(
+        default=None,
+        description="Number of transactions from this sender in the past 24 hours",
+    )
+    avg_transaction_amount: Optional[float] = Field(
+        default=None,
+        description="Sender's historical average transaction amount",
+    )
+    account_age_days: Optional[int] = Field(
+        default=None,
+        description="Age of the sender account in days",
+    )
+
+    # --- counterparty / geography ---
+    country_risk: Optional[str] = Field(
+        default=None,
+        description="Receiver country risk tier: low | medium | high | sanctioned",
+    )
+    kyc_status: Optional[str] = Field(
+        default=None,
+        description="KYC verification status: verified | pending | failed | none | expired",
+    )
+    kyc_expiry_days: Optional[int] = Field(
+        default=None,
+        description="Days until KYC expires (negative = already expired)",
+    )
+    previous_violations: Optional[int] = Field(
+        default=None,
+        description="Number of prior compliance violations for this sender",
+    )
+    previous_sars: Optional[int] = Field(
+        default=None,
+        description="Number of Suspicious Activity Reports previously filed for this sender",
+    )
+    counterparty_risk: Optional[str] = Field(
+        default=None,
+        description="Known risk profile of the receiver: clean | unknown | watchlist | blacklist",
+    )
+
+    # --- chain context (multi-hop investigation) ---
+    chain_step: int = Field(
+        default=1,
+        description="Which step within a multi-hop investigation chain (1=initial presentation)",
+    )
+    chain_total: int = Field(
+        default=1,
+        description="Total number of chained investigation steps for this task",
+    )
+    chain_context: Optional[str] = Field(
+        default=None,
+        description="Summary of findings from earlier chain steps",
+    )
+
+    # --- resource tracking ---
+    steps_remaining: Optional[int] = Field(
+        default=None,
+        description="How many investigation sub-steps remain before a terminal decision is required",
+    )
+    action_cost: float = Field(
+        default=0.0,
+        description="Operational cost penalty incurred by the last action",
+    )
+    budget_remaining: float = Field(
+        default=1.0,
+        description="Fraction of investigation budget remaining (1.0=full, 0.0=exhausted)",
+    )
+
+    # --- context from prior investigation actions ---
+    inspection_notes: Optional[str] = Field(
+        default=None,
+        description="Additional details revealed after an 'inspect' action",
+    )
+    docs_notes: Optional[str] = Field(
+        default=None,
+        description="Document review findings after a 'request_docs' action",
+    )
+    kyc_notes: Optional[str] = Field(
+        default=None,
+        description="KYC re-verification outcome after a 'verify_kyc' action",
+    )
+    contact_notes: Optional[str] = Field(
+        default=None,
+        description="Outcome of contacting the sender via 'contact_sender' action",
+    )
+
+    # --- recent decision context (last 3 decisions in this episode) ---
+    recent_decisions: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="Last up to 3 completed decisions in this episode for pattern context",
+    )
+
+    # --- episode bookkeeping ---
+    task_id: str = Field(default="", description="Identifier of the active task")
+    task_difficulty: str = Field(
+        default="easy", description="Difficulty tier: easy | medium | hard | critical"
+    )
+    step_in_episode: int = Field(
+        default=0, description="How many steps have elapsed in this episode"
+    )
+    reward: float = Field(default=0.0, description="Reward from the last action")
+    reward_breakdown: Dict[str, float] = Field(
+        default_factory=dict,
+        description="Itemised reward components: base, time_penalty, confidence_bonus, cost_penalty",
+    )
+    cumulative_reward: float = Field(
+        default=0.0, description="Total reward accumulated so far in this episode"
+    )
+    done: bool = Field(default=False, description="Whether the episode has ended")
+    info: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Extra diagnostic information (action taken, correct action, etc.)",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal state (used by the server's /state endpoint)
+# ---------------------------------------------------------------------------
+
+class PayOpsState(BaseModel):
+    episode_id: Optional[str] = None
+    step_count: int = 0
+    current_task_id: str = ""
+    transactions_processed: int = 0
+    total_tasks: int = 0
+    cumulative_reward: float = 0.0
+    budget_spent: float = Field(default=0.0, description="Total action costs accumulated")
+    budget_limit: float = Field(default=5.0, description="Max investigation budget per episode")
+    actions_taken: List[str] = Field(default_factory=list)
+    last_action: Optional[str] = None
+    investigation_actions_used: List[str] = Field(
+        default_factory=list,
+        description="All investigation sub-actions used this episode (inspect, request_docs, etc.)",
+    )
+    correct_decisions: int = Field(default=0, description="Terminal decisions that matched ground truth")
+    wrong_high_cost: int = Field(
+        default=0, description="Count of approve-on-fraud type mistakes"
+    )
+    recent_decisions: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="Recent completed task outcomes for analytics",
+    )
+    done: bool = False
+

openenv.yaml

@@ -0,0 +1,53 @@
+spec_version: 1
+name: payops_env
+display_name: "PayOps — Payment Operations Incident Response"
+description: >
+  An AI agent acts as a Payment Operations analyst, reviewing financial 
+  transactions and deciding how to handle each one: approve, reject, flag, 
+  escalate, inspect, or hold. Tasks range from clear-cut fraud to subtle 
+  adversarial patterns like model poisoning and APP scams.
+type: space
+runtime: fastapi
+app: payops_env.server.app:app
+port: 7860
+version: "1.0.0"
+author: "PayOps Team"
+tags:
+  - finance
+  - fraud-detection
+  - compliance
+  - real-world
+  - payment-operations
+action_space:
+  type: discrete
+  actions:
+    - approve
+    - reject
+    - flag
+    - escalate
+    - inspect
+    - hold
+observation_space:
+  type: structured
+  fields:
+    - transaction_id
+    - amount
+    - currency
+    - sender
+    - receiver
+    - risk_score
+    - flags
+    - velocity_1h
+    - country_risk
+    - kyc_status
+tasks:
+  count: 12
+  difficulties:
+    - easy
+    - medium
+    - hard
+reward:
+  min: -1.0
+  max: 1.0
+  partial_credit: true
+

requirements.txt

@@ -0,0 +1,4 @@
+openenv-core>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+pydantic>=2.0.0

run_tests.sh

@@ -0,0 +1,591 @@
+#!/usr/bin/env bash
+# run_tests.sh — PayOps v2 full test suite
+# Usage: bash payops_env/run_tests.sh [BASE_URL]
+# Requires the server to be running. Default: http://localhost:8000
+
+BASE="${1:-http://localhost:8000}"
+PASS=0
+FAIL=0
+SKIP=0
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+check() {
+  local name="$1"
+  local got="$2"
+  local want="$3"
+  if echo "$got" | grep -qE "$want"; then
+    printf "  \033[32m✓\033[0m  %s\n" "$name"
+    PASS=$((PASS+1))
+  else
+    printf "  \033[31m✗\033[0m  %s\n" "$name"
+    printf "     expected pattern : %s\n" "$want"
+    printf "     got              : %s\n" "$(echo "$got" | head -c 200)"
+    FAIL=$((FAIL+1))
+  fi
+}
+
+check_absent() {
+  local name="$1"
+  local got="$2"
+  local absent="$3"
+  if echo "$got" | grep -qE "$absent"; then
+    printf "  \033[31m✗\033[0m  %s  (unexpected: %s)\n" "$name" "$absent"
+    FAIL=$((FAIL+1))
+  else
+    printf "  \033[32m✓\033[0m  %s\n" "$name"
+    PASS=$((PASS+1))
+  fi
+}
+
+step() {
+  curl -s -X POST "$BASE/step" \
+    -H "Content-Type: application/json" \
+    -d "$1"
+}
+
+reset() {
+  curl -s -X POST "$BASE/reset" > /dev/null
+}
+
+section() {
+  echo ""
+  echo "── $1 ──"
+}
+
+echo ""
+echo "╔══════════════════════════════════════════════════════╗"
+echo "║    PayOps v2 — Full Post-Main Test Suite             ║"
+echo "║    Target: $BASE"
+echo "╚══════════════════════════════════════════════════════╝"
+echo ""
+
+# ═══════════════════════════════════════════════════════════
+# GROUP A — Server / Infrastructure
+# ═══════════════════════════════════════════════════════════
+section "GROUP A — Server / Infrastructure"
+
+# A-01  Health check
+check "A-01  GET /health → status ok" \
+  "$(curl -s $BASE/health)" \
+  '"status":"ok"'
+
+# A-02  Version is v2
+check "A-02  GET /health → version 2.0.0" \
+  "$(curl -s $BASE/health)" \
+  '"version":"2.0.0"'
+
+# A-03  Schema action model present
+check "A-03  GET /schema → PayOpsAction schema" \
+  "$(curl -s $BASE/schema)" \
+  '"PayOpsAction"'
+
+# A-04  Schema observation model present
+check "A-04  GET /schema → PayOpsObservation schema" \
+  "$(curl -s $BASE/schema)" \
+  '"PayOpsObservation"'
+
+# A-05  Schema state model present
+check "A-05  GET /schema → PayOpsState schema" \
+  "$(curl -s $BASE/schema)" \
+  '"PayOpsState"'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP B — Tasks endpoint
+# ═══════════════════════════════════════════════════════════
+section "GROUP B — Tasks endpoint"
+
+TASKS_RESP="$(curl -s $BASE/tasks)"
+
+# B-01  20 tasks
+check "B-01  GET /tasks → count=20" \
+  "$TASKS_RESP" '"count":20'
+
+# B-02  All 4 difficulty tiers present
+check "B-02  Tasks include 'easy' tier" "$TASKS_RESP" '"difficulty":"easy"'
+check "B-03  Tasks include 'medium' tier" "$TASKS_RESP" '"difficulty":"medium"'
+check "B-04  Tasks include 'hard' tier" "$TASKS_RESP" '"difficulty":"hard"'
+check "B-05  Tasks include 'critical' tier" "$TASKS_RESP" '"difficulty":"critical"'
+
+# B-06  Regulatory tasks present
+check "B-06  Tasks include regulatory_action flag" \
+  "$TASKS_RESP" '"regulatory_action":true'
+
+# B-07  Multi-step chain tasks present
+check "B-07  Tasks include chain_total > 1" \
+  "$TASKS_RESP" '"chain_total":3'
+
+# B-08  requires_investigation populated
+check "B-08  Tasks include requires_investigation" \
+  "$TASKS_RESP" '"requires_investigation":\['
+
+# ═══════════════════════════════════════════════════════════
+# GROUP C — Reset
+# ═══════════════════════════════════════════════════════════
+section "GROUP C — Reset"
+
+RESET_RESP="$(curl -s -X POST $BASE/reset)"
+check "C-01  POST /reset → returns EASY-001" "$RESET_RESP" '"task_id":"EASY-001"'
+check "C-02  POST /reset → done=false" "$RESET_RESP" '"done":false'
+check "C-03  POST /reset → budget_remaining=5.0" "$RESET_RESP" '"budget_remaining":5.0'
+check "C-04  POST /reset → risk_score present" "$RESET_RESP" '"risk_score":'
+check "C-05  POST /reset → ml_confidence present" "$RESET_RESP" '"ml_confidence":'
+check "C-06  POST /reset → chain_total present" "$RESET_RESP" '"chain_total":'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP D — Terminal Actions (correct decisions)
+# ═══════════════════════════════════════════════════════════
+section "GROUP D — Terminal Actions (correct decisions)"
+
+reset
+
+# D-01  approve correct → reward=1.0
+check "D-01  EASY-001 approve → reward=1.0" \
+  "$(step '{"action_type":"approve","transaction_id":"TXN-E001"}')" \
+  '"reward":1.0'
+
+# D-02  reject correct → reward=1.0
+check "D-02  EASY-002 reject → reward=1.0" \
+  "$(step '{"action_type":"reject","transaction_id":"TXN-E002"}')" \
+  '"reward":1.0'
+
+# D-03  approve correct (refund) → reward=1.0
+check "D-03  EASY-003 approve → reward=1.0" \
+  "$(step '{"action_type":"approve","transaction_id":"TXN-E003"}')" \
+  '"reward":1.0'
+
+# D-04  flag correct → reward=1.0
+check "D-04  EASY-004 flag → reward=1.0" \
+  "$(step '{"action_type":"flag","transaction_id":"TXN-E004"}')" \
+  '"reward":1.0'
+
+# D-05  escalate correct → reward=1.0
+check "D-05  MED-001 escalate → reward=1.0" \
+  "$(step '{"action_type":"escalate","transaction_id":"TXN-M001"}')" \
+  '"reward":1.0'
+
+# D-06  hold correct → reward=1.0
+check "D-06  MED-002 hold → reward=1.0" \
+  "$(step '{"action_type":"hold","transaction_id":"TXN-M002"}')" \
+  '"reward":1.0'
+
+# D-07  task advances after terminal
+R=$(step '{"action_type":"flag","transaction_id":"TXN-M003"}')
+check "D-07  After flag on MED-003, next task is MED-004" "$R" '"task_id":"MED-004"'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP E — Terminal Actions (wrong decisions / partial credit)
+# ═══════════════════════════════════════════════════════════
+section "GROUP E — Wrong actions & partial credit"
+
+reset
+
+# E-01  approve when should reject → -1.0 (fraud approval)
+step '{"action_type":"approve","transaction_id":"TXN-E001"}' > /dev/null  # advance past E001
+check "E-01  Approve fraud (EASY-002) → reward=-1.0" \
+  "$(step '{"action_type":"approve","transaction_id":"TXN-E002"}')" \
+  '"reward":-1.0'
+
+reset
+step '{"action_type":"approve","transaction_id":"TXN-E001"}' > /dev/null
+step '{"action_type":"reject","transaction_id":"TXN-E002"}' > /dev/null
+
+# E-02  reject correct → approve → -0.5
+check "E-02  Reject legit (EASY-003) → reward=-0.5" \
+  "$(step '{"action_type":"reject","transaction_id":"TXN-E003"}')" \
+  '"reward":-0.5'
+
+reset
+# E-03  partial credit — escalate instead of escalate on MED-001 is correct
+#        flag instead of escalate earns partial
+step '{"action_type":"approve","transaction_id":"TXN-E001"}' > /dev/null
+step '{"action_type":"reject","transaction_id":"TXN-E002"}' > /dev/null
+step '{"action_type":"approve","transaction_id":"TXN-E003"}' > /dev/null
+step '{"action_type":"flag","transaction_id":"TXN-E004"}' > /dev/null
+R=$(step '{"action_type":"flag","transaction_id":"TXN-M001"}')
+check "E-03  Partial credit: flag on MED-001 (correct=escalate) → reward > 0" \
+  "$R" '"reward":0\.[0-9]'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP F — Investigation Sub-Actions
+# ═══════════════════════════════════════════════════════════
+section "GROUP F — Investigation sub-actions"
+
+reset
+
+# F-01  inspect → reward=0.15, stays on same task
+R=$(step '{"action_type":"inspect","transaction_id":"TXN-E001"}')
+check "F-01  inspect → reward=0.15" "$R" '"reward":0.15'
+check "F-02  inspect → does NOT advance task (still EASY-001)" "$R" '"task_id":"EASY-001"'
+check "F-03  inspect → inspection_notes populated" "$R" '"inspection_notes":"'
+check "F-04  inspect → budget_remaining=4.9" "$R" '"budget_remaining":4.9'
+
+# F-05  inspect again on same task → reward=0.0 (no double-dip)
+check "F-05  second inspect → reward=0.0" \
+  "$(step '{"action_type":"inspect","transaction_id":"TXN-E001"}')" \
+  '"reward":0.0'
+
+# Advance to EASY-002
+step '{"action_type":"approve","transaction_id":"TXN-E001"}' > /dev/null
+
+# F-06  request_docs → reward=0.15, docs_notes populated
+R=$(step '{"action_type":"request_docs","transaction_id":"TXN-E002"}')
+check "F-06  request_docs → reward=0.15" "$R" '"reward":0.15'
+check "F-07  request_docs → docs_notes populated" "$R" '"docs_notes":"'
+check "F-08  request_docs → budget_remaining=4.6 (cost=0.2)" "$R" '"budget_remaining":4.6'
+
+# F-09  request_docs again → reward=0.0
+check "F-09  second request_docs → reward=0.0" \
+  "$(step '{"action_type":"request_docs","transaction_id":"TXN-E002"}')" \
+  '"reward":0.0'
+
+step '{"action_type":"reject","transaction_id":"TXN-E002"}' > /dev/null  # advance
+
+# F-10  verify_kyc → reward=0.15, kyc_notes populated
+R=$(step '{"action_type":"verify_kyc","transaction_id":"TXN-E003"}')
+check "F-10  verify_kyc → reward=0.15" "$R" '"reward":0.15'
+check "F-11  verify_kyc → kyc_notes populated" "$R" '"kyc_notes":"'
+check "F-12  verify_kyc → budget cost=0.2 deducted" "$R" '"budget_remaining":4.[0-9]'
+
+step '{"action_type":"approve","transaction_id":"TXN-E003"}' > /dev/null
+
+# F-13  contact_sender → reward=0.15, contact_notes populated
+R=$(step '{"action_type":"contact_sender","transaction_id":"TXN-E004"}')
+check "F-13  contact_sender → reward=0.15" "$R" '"reward":0.15'
+check "F-14  contact_sender → contact_notes populated" "$R" '"contact_notes":"'
+check "F-15  contact_sender → budget cost=0.3 deducted" "$R" '"budget_remaining":3\.[0-9]'
+
+step '{"action_type":"flag","transaction_id":"TXN-E004"}' > /dev/null
+
+# F-16  file_sar → reward=0.15, docs_notes mentions SAR
+R=$(step '{"action_type":"file_sar","transaction_id":"TXN-M001"}')
+check "F-16  file_sar → reward=0.15" "$R" '"reward":0.15'
+check "F-17  file_sar → docs_notes mentions SAR" "$R" '"docs_notes":"SAR'
+check "F-18  file_sar → budget cost=0.05 deducted" "$R" '"budget_remaining":3\.[0-9]'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP G — /state endpoint
+# ═══════════════════════════════════════════════════════════
+section "GROUP G — State endpoint"
+
+STATE="$(curl -s $BASE/state)"
+check "G-01  GET /state → episode_id set" "$STATE" '"episode_id":"'
+check "G-02  GET /state → step_count > 0" "$STATE" '"step_count":[1-9]'
+check "G-03  GET /state → budget_spent > 0" "$STATE" '"budget_spent":[0-9]'
+check "G-04  GET /state → investigation_actions_used list" "$STATE" '"investigation_actions_used":\['
+check "G-05  GET /state → recent_decisions list" "$STATE" '"recent_decisions":\['
+check "G-06  GET /state → correct_decisions >= 0" "$STATE" '"correct_decisions":[0-9]'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP H — /grader endpoint
+# ═══════════════════════════════════════════════════════════
+section "GROUP H — Grader endpoint"
+
+GRADER="$(curl -s $BASE/grader)"
+check "H-01  GET /grader → normalised_score present" "$GRADER" '"normalised_score":'
+check "H-02  GET /grader → total_reward present" "$GRADER" '"total_reward":'
+check "H-03  GET /grader → budget_spent present" "$GRADER" '"budget_spent":'
+check "H-04  GET /grader → budget_penalty present" "$GRADER" '"budget_penalty":'
+check "H-05  GET /grader → per_task array" "$GRADER" '"per_task":\['
+check "H-06  GET /grader → reward_breakdown in per_task" "$GRADER" '"reward_breakdown":'
+check "H-07  GET /grader → passed field present" "$GRADER" '"passed":'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP I — /replay endpoint
+# ═══════════════════════════════════════════════════════════
+section "GROUP I — /replay endpoint (offline eval)"
+
+# I-01  Replay with all correct actions → score=1.0
+REPLAY_PERFECT='{"actions":["approve","reject","approve","flag",
+  "escalate","hold","flag","flag","hold","escalate",
+  "escalate","reject","reject","approve","escalate","flag",
+  "approve","reject","escalate","reject"]}'
+R=$(curl -s -X POST $BASE/replay \
+    -H "Content-Type: application/json" \
+    -d "$REPLAY_PERFECT")
+check "I-01  Replay 20 correct actions → score=1.0" "$R" '"normalised_score":1.0'
+check "I-02  Replay → passed=true" "$R" '"passed":true'
+check "I-03  Replay → budget_spent=0.0 (no inv actions)" "$R" '"budget_spent":0.0'
+
+# I-04  Replay with investigation actions included
+REPLAY_WITH_INV='{"actions":["inspect","approve","reject","approve","flag",
+  "escalate","hold","flag","flag","hold","escalate",
+  "escalate","reject","reject","approve","escalate","flag",
+  "approve","reject","escalate","reject"]}'
+R=$(curl -s -X POST $BASE/replay \
+    -H "Content-Type: application/json" \
+    -d "$REPLAY_WITH_INV")
+check "I-04  Replay with inspect → budget_spent=0.1" "$R" '"budget_spent":0.1'
+
+# I-05  Replay with invalid action → 422
+check "I-05  Replay invalid action → 422 error" \
+  "$(curl -s -X POST $BASE/replay \
+      -H 'Content-Type: application/json' \
+      -d '{"actions":["delete","approve"]}')" \
+  "Invalid action"
+
+# I-06  Replay result has per_task breakdown
+check "I-06  Replay → per_task array present" "$R" '"per_task":\['
+check "I-07  Replay → reward_breakdown in each task" "$R" '"reward_breakdown":'
+
+# I-08  Replay with confidences
+REPLAY_CONF='{"actions":["approve","reject"],"confidences":[0.95,0.90]}'
+check "I-08  Replay with confidences → ok" \
+  "$(curl -s -X POST $BASE/replay \
+      -H 'Content-Type: application/json' \
+      -d "$REPLAY_CONF")" \
+  '"normalised_score":'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP J — /baseline endpoint
+# ═══════════════════════════════════════════════════════════
+section "GROUP J — Baseline agent"
+
+BASELINE="$(curl -s -X POST $BASE/baseline)"
+check "J-01  POST /baseline → normalised_score present" "$BASELINE" '"normalised_score":'
+check "J-02  POST /baseline → total_reward present" "$BASELINE" '"total_reward":'
+check "J-03  POST /baseline → steps > 0" "$BASELINE" '"steps":[1-9]'
+check "J-04  POST /baseline → per_task scores present" "$BASELINE" '"scores":\['
+check "J-05  POST /baseline → score >= 0.5 (passes)" "$BASELINE" '"normalised_score":0\.[5-9]'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP K — /analytics endpoint
+# ═══════════════════════════════════════════════════════════
+section "GROUP K — Analytics endpoint"
+
+# Run a full episode first so analytics has data
+reset
+python3 - <<'PYEOF'
+import urllib.request, json, sys
+BASE = "http://localhost:8000"
+def post(path, body=None):
+    req = urllib.request.Request(f"{BASE}{path}",
+        data=json.dumps(body).encode() if body else None,
+        headers={"Content-Type": "application/json"}, method="POST")
+    with urllib.request.urlopen(req) as r: return json.loads(r.read())
+def get(path):
+    with urllib.request.urlopen(f"{BASE}{path}") as r: return json.loads(r.read())
+
+post("/reset")
+actions = [
+  ("approve","TXN-E001"),("reject","TXN-E002"),("approve","TXN-E003"),("flag","TXN-E004"),
+  ("escalate","TXN-M001"),("hold","TXN-M002"),("flag","TXN-M003"),("flag","TXN-M004"),
+  ("hold","TXN-M005"),("escalate","TXN-M006"),
+  ("escalate","TXN-H001"),("reject","TXN-H002"),("reject","TXN-H003"),("approve","TXN-H004"),
+  ("escalate","TXN-H005"),("flag","TXN-H006"),
+  ("approve","TXN-C001"),("reject","TXN-C002"),("escalate","TXN-C003"),("reject","TXN-C004"),
+]
+for action, txn in actions:
+    post("/step", {"action_type": action, "transaction_id": txn})
+PYEOF
+
+ANA="$(curl -s $BASE/analytics)"
+check "K-01  GET /analytics → episodes_completed >= 1" "$ANA" '"episodes_completed":[1-9]'
+check "K-02  GET /analytics → best_score present" "$ANA" '"best_score":'
+check "K-03  GET /analytics → avg_score present" "$ANA" '"avg_score":'
+check "K-04  GET /analytics → avg_budget_spent present" "$ANA" '"avg_budget_spent":'
+check "K-05  GET /analytics → current_episode present" "$ANA" '"current_episode":'
+check "K-06  GET /analytics → by_difficulty present" "$ANA" '"by_difficulty":'
+check "K-07  GET /analytics → easy accuracy" "$ANA" '"easy":'
+check "K-08  GET /analytics → critical accuracy" "$ANA" '"critical":'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP L — /leaderboard endpoint
+# ═══════════════════════════════════════════════════════════
+section "GROUP L — Leaderboard endpoint"
+
+LB="$(curl -s $BASE/leaderboard)"
+check "L-01  GET /leaderboard → count >= 1 (episode recorded)" "$LB" '"count":[1-9]'
+check "L-02  GET /leaderboard → entries array present" "$LB" '"entries":\['
+check "L-03  GET /leaderboard → episode_id in entry" "$LB" '"episode_id":"'
+check "L-04  GET /leaderboard → normalised_score in entry" "$LB" '"normalised_score":'
+check "L-05  GET /leaderboard → timestamp in entry" "$LB" '"timestamp":"'
+check "L-06  GET /leaderboard → budget_spent in entry" "$LB" '"budget_spent":'
+
+# ══════════════════════════════════════════════���════════════
+# GROUP M — Perfect episode score
+# ═══════════════════════════════════════════════════════════
+section "GROUP M — Perfect episode (all 20 correct, no investigation cost)"
+
+reset
+python3 - <<'PYEOF'
+import urllib.request, json
+BASE = "http://localhost:8000"
+def post(path, body=None):
+    req = urllib.request.Request(f"{BASE}{path}",
+        data=json.dumps(body).encode() if body else None,
+        headers={"Content-Type": "application/json"}, method="POST")
+    with urllib.request.urlopen(req) as r: return json.loads(r.read())
+
+post("/reset")
+actions = [
+  ("approve","TXN-E001"),("reject","TXN-E002"),("approve","TXN-E003"),("flag","TXN-E004"),
+  ("escalate","TXN-M001"),("hold","TXN-M002"),("flag","TXN-M003"),("flag","TXN-M004"),
+  ("hold","TXN-M005"),("escalate","TXN-M006"),
+  ("escalate","TXN-H001"),("reject","TXN-H002"),("reject","TXN-H003"),("approve","TXN-H004"),
+  ("escalate","TXN-H005"),("flag","TXN-H006"),
+  ("approve","TXN-C001"),("reject","TXN-C002"),("escalate","TXN-C003"),("reject","TXN-C004"),
+]
+for action, txn in actions:
+    post("/step", {"action_type": action, "transaction_id": txn})
+PYEOF
+
+GRADER="$(curl -s $BASE/grader)"
+check "M-01  Perfect episode → normalised_score=1.0" "$GRADER" '"normalised_score":1.0'
+check "M-02  Perfect episode → passed=true" "$GRADER" '"passed":true'
+check "M-03  Perfect episode → budget_penalty=0.0" "$GRADER" '"budget_penalty":0.0'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP N — Difficulty weighting
+# ═══════════════════════════════════════════════════════════
+section "GROUP N — Difficulty weighting in grader"
+
+# A critical task correct should contribute more weight than easy
+REPLAY_CRIT='{"actions":["approve","reject","approve","flag",
+  "escalate","hold","flag","flag","hold","escalate",
+  "escalate","reject","reject","approve","escalate","flag",
+  "approve","reject","escalate","reject"]}'
+
+FULL=$(curl -s -X POST $BASE/replay \
+    -H "Content-Type: application/json" \
+    -d "$REPLAY_CRIT")
+check "N-01  Full correct replay → max_possible_reward includes weights" \
+  "$FULL" '"max_possible_reward":2[0-9]\.'
+check "N-02  Full correct → total_reward equals max_possible" \
+  "$(echo "$FULL" | python3 -c "
+import sys,json,re
+d=json.load(sys.stdin)
+print('EQUAL' if abs(d['total_reward']-d['max_possible_reward'])<0.01 else 'DIFF')
+")" "EQUAL"
+
+# ═══════════════════════════════════════════════════════════
+# GROUP O — Budget mechanics
+# ═══════════════════════════════════════════════════════════
+section "GROUP O — Budget mechanics"
+
+reset
+
+# Burn through budget with contact_sender (cost=0.3) × 5 = 1.5
+# then request_docs × 5 = 1.0, then verify_kyc × 5 = 1.0  (total = 3.5 so far ≤5)
+# Total exceeding: won't exceed in these few calls, test budget tracking
+step '{"action_type":"contact_sender","transaction_id":"TXN-E001"}' > /dev/null  # -0.30
+step '{"action_type":"contact_sender","transaction_id":"TXN-E001"}' > /dev/null  # dup, but cost still deducted
+step '{"action_type":"request_docs","transaction_id":"TXN-E001"}' > /dev/null    # -0.20
+step '{"action_type":"verify_kyc","transaction_id":"TXN-E001"}' > /dev/null      # -0.20
+step '{"action_type":"file_sar","transaction_id":"TXN-E001"}' > /dev/null        # -0.05
+R=$(step '{"action_type":"approve","transaction_id":"TXN-E001"}')
+# budget_remaining = 5.0 - 0.30 - 0.30 - 0.20 - 0.20 - 0.05 = 3.95
+check "O-01  Budget correctly deducted after multiple inv actions" \
+  "$R" '"budget_remaining":3\.[0-9]'
+
+# grader shows budget_spent
+GRADER="$(curl -s $BASE/grader)"
+check "O-02  Grader → budget_spent > 0" "$GRADER" '"budget_spent":0\.[1-9]'
+
+# replay that overshoots budget → budget_penalty > 0
+HEAVY='{"actions":["contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","contact_sender","approve","reject","approve","flag","escalate","hold","flag","flag","hold","escalate","escalate","reject","reject","approve","escalate","flag","approve","reject","escalate","reject"]}'
+R=$(curl -s -X POST $BASE/replay \
+    -H "Content-Type: application/json" \
+    -d "$HEAVY")
+check "O-03  Over-budget replay → budget_penalty > 0" "$R" '"budget_penalty":0\.[1-9]'
+check "O-04  Over-budget replay → budget_overspend > 0" "$R" '"budget_overspend":0\.[1-9]'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP P — Edge cases & errors
+# ═══════════════════════════════════════════════════════════
+section "GROUP P — Edge cases & error handling"
+
+# P-01  Step before reset → 400
+check "P-01  Step on fresh env (reset then done) → handled" \
+  "$(curl -s -X POST $BASE/reset > /dev/null && curl -s -X POST $BASE/step \
+      -H 'Content-Type: application/json' \
+      -d '{"action_type":"approve","transaction_id":"TXN-NONE"}')" \
+  '"reward"'
+
+# P-02  Unknown action_type → 422
+check "P-02  Unknown action_type → 422" \
+  "$(curl -s -X POST $BASE/step \
+      -H 'Content-Type: application/json' \
+      -d '{"action_type":"nuke","transaction_id":"TXN-E001"}')" \
+  "Invalid action_type"
+
+# P-03  Missing action_type field → 422
+check "P-03  Missing action_type field → error" \
+  "$(curl -s -X POST $BASE/step \
+      -H 'Content-Type: application/json' \
+      -d '{"transaction_id":"TXN-E001"}')" \
+  '"detail"'
+
+# P-04  Empty replay actions list
+check "P-04  Replay empty actions → returns score" \
+  "$(curl -s -X POST $BASE/replay \
+      -H 'Content-Type: application/json' \
+      -d '{"actions":[]}')" \
+  '"normalised_score"'
+
+# P-05  Replay with confidences shorter than actions → still works
+check "P-05  Replay with partial confidences → score present" \
+  "$(curl -s -X POST $BASE/replay \
+      -H 'Content-Type: application/json' \
+      -d '{"actions":["approve","reject"],"confidences":[0.9]}')" \
+  '"normalised_score"'
+
+# P-06  Grader before any reset → 400 or returns score
+check "P-06  Grader before actions → handled gracefully" \
+  "$(curl -s $BASE/grader)" \
+  '"normalised_score"\|"error"'
+
+# P-07  Analytics before any completed episode → handled
+reset
+check "P-07  Analytics after fresh reset → message or data" \
+  "$(curl -s $BASE/analytics)" \
+  '"message"\|"episodes_completed"'
+
+# ═══════════════════════════════════════════════════════════
+# GROUP Q — WebSocket
+# ═══════════════════════════════════════════════════════════
+section "GROUP Q — WebSocket (requires wscat or python)"
+
+if command -v python3 &>/dev/null; then
+  WS_RESULT=$(python3 - <<'PYEOF'
+import urllib.request, json
+try:
+    # ws upgrade check via HTTP (will get 426 Upgrade Required — proves endpoint exists)
+    req = urllib.request.Request("http://localhost:8000/ws")
+    try:
+        urllib.request.urlopen(req)
+    except Exception as e:
+        msg = str(e)
+        if "426" in msg or "101" in msg or "Switching" in msg or "upgrade" in msg.lower():
+            print("WS_OK")
+        else:
+            print(f"WS_UNKNOWN:{msg[:60]}")
+except Exception as e:
+    print(f"WS_ERR:{e}")
+PYEOF
+)
+  check "Q-01  WS /ws endpoint exists (426 upgrade = correct)" \
+    "$WS_RESULT" "WS_OK"
+else
+  printf "  \033[33m-\033[0m  Q-01  WebSocket check skipped (no python3)\n"
+  SKIP=$((SKIP+1))
+fi
+
+# ═══════════════════════════════════════════════════════════
+# SUMMARY
+# ═══════════════════════════════════════════════════════════
+echo ""
+echo "╔══════════════════════════════════════════════════════╗"
+TOTAL=$((PASS+FAIL))
+if [ "$FAIL" -eq 0 ]; then
+  printf "║  ✓  All %d tests passed" "$TOTAL"
+else
+  printf "║  Results: %d/%d passed, %d failed" "$PASS" "$TOTAL" "$FAIL"
+fi
+[ "$SKIP" -gt 0 ] && printf "  (%d skipped)" "$SKIP"
+echo ""
+echo "╚══════════════════════════════════════════════════════╝"
+echo ""
+
+# Exit with failure code if any tests failed
+[ "$FAIL" -eq 0 ]

scripts/baseline_agent.py

@@ -0,0 +1,159 @@
+"""
+Baseline agent for the PayOps OpenEnv environment.
+
+A rule-based agent that decides an action based on observable risk signals.
+Use this as a sanity-check to prove the environment works end-to-end and
+as a lower-bound performance reference before training a learned agent.
+
+Usage
+-----
+    # Run directly
+    python scripts/baseline_agent.py
+
+    # Or via the /baseline API endpoint
+    curl -X POST http://localhost:8000/baseline
+
+Policy
+------
+1. If any sanctioned / high-risk flag        → reject
+2. velocity_1h >= 10 (velocity burst)        → reject
+3. kyc_status in (failed, none)              → escalate
+4. risk_score >= 0.80                        → reject
+5. risk_score >= 0.60                        → escalate
+6. risk_score >= 0.35 OR any flag present    → flag
+7. Otherwise                                 → approve
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import os
+
+# Allow running from the project root or the scripts/ directory
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from payops_env.environment import PayOpsEnvironment
+from payops_env.grader import grade_episode
+from payops_env.models import PayOpsAction
+from payops_env.tasks import TASKS
+
+
+# ---------------------------------------------------------------------------
+# Policy
+# ---------------------------------------------------------------------------
+
+DANGER_FLAGS = {
+    "sanctioned_country",
+    "app_scam_indicator",
+    "mule_account_pattern",
+    "structuring_pattern",
+    "ctr_threshold_avoidance",
+}
+
+
+def rule_based_policy(obs) -> str:
+    """
+    Deterministic rule-based policy.
+
+    Priority order ensures the most dangerous patterns are caught first,
+    even when the ML risk score is low (adversarial/poisoned score inputs).
+    """
+    # Priority 1: known fraud or sanctioned patterns regardless of risk score
+    if any(flag in DANGER_FLAGS for flag in obs.flags):
+        return "reject"
+
+    # Priority 2: transaction velocity burst (potential account takeover)
+    if obs.velocity_1h is not None and obs.velocity_1h >= 10:
+        return "reject"
+
+    # Priority 3: identity not confirmed
+    if obs.kyc_status in ("failed", "none"):
+        return "escalate"
+
+    # Priority 4–6: risk score tiers
+    if obs.risk_score >= 0.80:
+        return "reject"
+    elif obs.risk_score >= 0.60:
+        return "escalate"
+    elif obs.risk_score >= 0.35 or obs.flags:
+        return "flag"
+    else:
+        return "approve"
+
+
+# ---------------------------------------------------------------------------
+# Runner
+# ---------------------------------------------------------------------------
+
+async def run():
+    env = PayOpsEnvironment()
+    obs = await env.reset_async()
+    total_reward = 0.0
+    step = 0
+    actions_taken = []
+
+    print("=" * 60)
+    print("  PayOps Baseline Agent — Rule-Based Policy")
+    print("=" * 60)
+    print(f"  Tasks in episode : {len(TASKS)}")
+    print("=" * 60)
+
+    while not obs.done:
+        action_type = rule_based_policy(obs)
+        action = PayOpsAction(
+            action_type=action_type,
+            transaction_id=obs.transaction_id,
+        )
+
+        print(f"\nStep {step + 1}  [{obs.task_difficulty.upper()}]  {obs.task_id}")
+        print(f"  TXN        : {obs.transaction_id}")
+        print(f"  Amount     : {obs.amount:,.2f} {obs.currency}")
+        print(f"  Sender     : {obs.sender}")
+        print(f"  Receiver   : {obs.receiver}")
+        print(f"  Risk score : {obs.risk_score:.2f}")
+        print(f"  KYC        : {obs.kyc_status or 'n/a'}  |  "
+              f"Country risk: {obs.country_risk or 'n/a'}  |  "
+              f"Velocity 1h: {obs.velocity_1h or 'n/a'}")
+        print(f"  Flags      : {obs.flags or '[]'}")
+        print(f"  → Agent    : {action_type}")
+
+        obs = await env.step_async(action)
+        actions_taken.append(action_type)
+        total_reward += obs.reward
+        step += 1
+
+        print(f"  ✓ Reward   : {obs.reward:+.2f}  "
+              f"(correct: {obs.info.get('correct_action', '?')})")
+
+    env.close()
+
+    # Grade the episode
+    result = grade_episode(actions_taken, list(TASKS))
+
+    print("\n" + "=" * 60)
+    print("  Episode Summary")
+    print("=" * 60)
+    print(f"  Steps             : {step}")
+    print(f"  Total reward      : {result.total_reward:+.2f}")
+    print(f"  Max possible      : {result.max_possible_reward:.2f}")
+    print(f"  Normalised score  : {result.normalised_score:.4f}")
+    print(f"  Passed (≥0.5)     : {'YES ✓' if result.passed else 'NO ✗'}")
+
+    print("\n  Per-task breakdown:")
+    for t in result.per_task_rewards:
+        mark = "✓" if t["correct"] else "✗"
+        print(
+            f"    {mark}  {t['task_id']:12s}  [{t['difficulty']:6s}]  "
+            f"action={t['action_taken']:10s}  "
+            f"correct={t['correct_action']:10s}  "
+            f"reward={t['reward']:+.2f}"
+        )
+
+    print("=" * 60)
+    return result
+
+
+if __name__ == "__main__":
+    asyncio.run(run())
+

scripts_util.py

@@ -0,0 +1,170 @@
+"""
+Utilities for running the baseline agent programmatically (used by /baseline endpoint).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from payops_env.environment import PayOpsEnvironment
+from payops_env.grader import grade_episode
+from payops_env.models import PayOpsAction
+from payops_env.tasks import TASKS
+
+
+# ---------------------------------------------------------------------------
+# Adaptive rule-based policy
+# ---------------------------------------------------------------------------
+
+_DANGER_FLAGS = {
+    "sanctioned_country", "app_scam_indicator", "mule_account_pattern",
+    "structuring_pattern", "ctr_threshold_avoidance", "fraud_ring_indicator",
+    "geo_impossible_login", "account_takeover_indicator",
+}
+
+_WATCHLIST_FLAGS = {
+    "new_account_7d", "large_first_transfer", "solicitor_mule_pattern",
+    "dormant_receiver", "sudden_activity", "insider_threat", "internal_to_personal",
+    "invoice_mismatch", "trade_finance",
+}
+
+
+def _should_investigate(obs) -> Optional[str]:
+    """
+    Decide whether to issue an investigation sub-action first.
+
+    Returns the sub-action name, or None if we should decide directly.
+
+    Priority:
+      1. KYC expired / pending → verify_kyc (once)
+      2. Watchlist flags AND high amount AND docs not yet requested → request_docs
+      3. Low ml_confidence AND medium risk → inspect (once)
+      4. contact_sender: APP scam pattern or insider threat
+      5. file_sar: if structuring/fraud-ring flags and not yet filed
+    """
+    already = set(obs.info.get("investigation_used", []) if isinstance(obs.info, dict) else [])
+
+    # file_sar if structuring / fraud ring and SAR not yet filed
+    sar_flags = {"structuring_pattern", "ctr_threshold_avoidance",
+                 "fraud_ring_indicator", "coordinated_transfers"}
+    if sar_flags & set(obs.flags) and "file_sar" not in already:
+        return "file_sar"
+
+    # contact_sender for APP scam or insider
+    contact_flags = {"app_scam_indicator", "internal_to_personal", "account_takeover_indicator"}
+    if contact_flags & set(obs.flags) and "contact_sender" not in already:
+        return "contact_sender"
+
+    # verify_kyc if expired or pending
+    if obs.kyc_status in ("expired", "pending") and "verify_kyc" not in already:
+        return "verify_kyc"
+
+    # request_docs for first-time payees with high value
+    doc_flags = {"first_time_payee", "large_first_transfer", "invoice_mismatch", "trade_finance"}
+    if (doc_flags & set(obs.flags)
+            and obs.amount >= 50_000
+            and "request_docs" not in already):
+        return "request_docs"
+
+    # inspect when ml_confidence is low or watchlist flags are present
+    ml_conf = getattr(obs, "ml_confidence", 0.9) or 0.9
+    watchlist_hit = bool(_WATCHLIST_FLAGS & set(obs.flags))
+    if (ml_conf < 0.60 or watchlist_hit) and "inspect" not in already:
+        return "inspect"
+
+    return None
+
+
+def _terminal_decision(obs) -> str:
+    """
+    Make a terminal decision.  Uses enriched observation fields where available
+    (inspect_reveal, docs_notes, kyc_notes, contact_notes already in obs.info).
+    """
+    # Definitive danger signals
+    if any(f in _DANGER_FLAGS for f in obs.flags):
+        # Exception: if we confirmed via contact that it is genuine, approve
+        contact = getattr(obs, "contact_notes", None) or ""
+        if "CEO confirms they did NOT" in contact or "Classic APP scam" in contact:
+            return "reject"
+        return "reject"
+
+    vel = obs.velocity_1h
+    if vel is not None and vel >= 10:
+        return "reject"
+
+    if obs.kyc_status in ("failed", "none"):
+        return "escalate"
+
+    # KYC expired → hold (wait for renewal)
+    if obs.kyc_status == "expired":
+        return "hold"
+
+    # Very high risk
+    if obs.risk_score >= 0.85:
+        return "reject"
+
+    # Watchlist flags with high value
+    if _WATCHLIST_FLAGS & set(obs.flags) and obs.amount >= 20_000:
+        return "escalate"
+
+    # FX / correspondent banking settlement
+    if "fx_settlement" in obs.flags:
+        return "approve"
+
+    # After inspection revealed legitimacy (corp-level, FX)
+    inspection = getattr(obs, "inspection_notes", None) or ""
+    if "correspondent banking" in inspection.lower() or "on file" in inspection.lower():
+        if obs.risk_score < 0.75:
+            return "approve"
+
+    if obs.risk_score >= 0.65:
+        return "escalate"
+    elif obs.risk_score >= 0.40 or obs.flags:
+        return "flag"
+    else:
+        return "approve"
+
+
+def _rule_based_policy(obs) -> str:
+    """
+    Adaptive policy.  First checks whether investigation is needed; if so
+    returns a sub-action.  Otherwise returns a terminal decision.
+    """
+    sub = _should_investigate(obs)
+    if sub is not None:
+        return sub
+    return _terminal_decision(obs)
+
+
+# ---------------------------------------------------------------------------
+# Episode runner
+# ---------------------------------------------------------------------------
+
+async def run_baseline() -> Tuple[List[Dict[str, Any]], float, float, int]:
+    """
+    Run the adaptive rule-based baseline over the full task set.
+
+    Returns:
+        (per_task_rewards, total_reward, normalised_score, steps)
+    """
+    env = PayOpsEnvironment()
+    obs = await env.reset_async()
+    actions_taken: List[str] = []
+    confs: List[Optional[float]] = []
+    step = 0
+
+    while not obs.done:
+        action_type = _rule_based_policy(obs)
+        action = PayOpsAction(
+            action_type=action_type,
+            transaction_id=obs.transaction_id,
+        )
+        obs = await env.step_async(action)
+        actions_taken.append(action_type)
+        confs.append(None)
+        step += 1
+
+    env.close()
+
+    result = grade_episode(actions_taken, list(TASKS), confs)
+    return result.per_task_rewards, result.total_reward, result.normalised_score, step
+

server/app.py

@@ -0,0 +1,399 @@
+"""
+FastAPI server for the PayOps OpenEnv environment.
+
+Endpoints
+---------
+POST /reset         Reset environment, return initial observation
+POST /step          Execute an action, return observation + reward
+GET  /state         Current internal environment state
+GET  /schema        Action / observation JSON schemas
+GET  /tasks         List all tasks with metadata
+GET  /grader        Grade the current episode
+POST /baseline      Run the rule-based baseline agent
+GET  /analytics     Aggregate performance analytics for this session
+POST /replay        Grade a supplied action sequence without modifying state
+GET  /leaderboard   All scored episodes this session
+GET  /health        Health check
+WS   /ws            WebSocket for persistent sessions
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from collections import defaultdict
+from typing import Any, Dict, List, Optional
+
+from fastapi import FastAPI, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from payops_env.environment import PayOpsEnvironment, VALID_ACTIONS
+from payops_env.grader import grade_episode
+from payops_env.models import PayOpsAction, PayOpsObservation, PayOpsState
+from payops_env.tasks import TASKS, TASKS_BY_ID
+
+
+# ---------------------------------------------------------------------------
+# App setup
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="PayOps OpenEnv",
+    description=(
+        "Payment Operations Incident Response environment. "
+        "An AI agent reviews financial transactions and decides how to handle them."
+    ),
+    version="2.0.0",
+)
+
+# Single shared environment instance (suitable for single-user / HF Space use)
+_env = PayOpsEnvironment()
+_episode_actions: List[str] = []          # ALL actions including investigation
+_episode_confs: List[Optional[float]] = []
+_episode_tasks: List[Any] = []
+
+# Leaderboard persists for the process lifetime
+_leaderboard: List[Dict[str, Any]] = []
+
+
+# ---------------------------------------------------------------------------
+# Request / response helpers
+# ---------------------------------------------------------------------------
+
+class StepRequest(BaseModel):
+    action_type: str
+    transaction_id: str
+    reason: Optional[str] = None
+    confidence: Optional[float] = None
+
+
+class BaselineResult(BaseModel):
+    scores: List[Dict[str, Any]]
+    total_reward: float
+    normalised_score: float
+    steps: int
+
+
+class ReplayRequest(BaseModel):
+    actions: List[str]
+    confidences: Optional[List[Optional[float]]] = None
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.post("/reset", response_model=PayOpsObservation, summary="Reset the environment")
+async def reset():
+    """Reset the environment and return the first transaction observation."""
+    global _episode_actions, _episode_tasks, _episode_confs
+    _episode_actions = []
+    _episode_confs   = []
+    _episode_tasks   = list(TASKS)
+    obs = await _env.reset_async()
+    return obs
+
+
+@app.post("/step", response_model=PayOpsObservation, summary="Execute an action")
+async def step(request: StepRequest):
+    """
+    Submit an action for the current transaction.
+
+    Valid action_type values:
+      Terminal:      approve | reject | flag | escalate | hold
+      Investigation: inspect | request_docs | verify_kyc | contact_sender | file_sar
+    """
+    if request.action_type.lower() not in VALID_ACTIONS:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Invalid action_type '{request.action_type}'. "
+                   f"Valid values: {sorted(VALID_ACTIONS)}",
+        )
+    action = PayOpsAction(
+        action_type=request.action_type,
+        transaction_id=request.transaction_id,
+        reason=request.reason,
+        confidence=request.confidence,
+    )
+    try:
+        obs = await _env.step_async(action)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    _episode_actions.append(request.action_type.lower())
+    _episode_confs.append(request.confidence)
+
+    # Auto-save completed episode to leaderboard
+    if obs.done:
+        result = grade_episode(
+            _episode_actions, _episode_tasks, _episode_confs
+        )
+        _leaderboard.append(
+            {
+                "episode_id":       _env.state().episode_id,
+                "timestamp":        time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "normalised_score": result.normalised_score,
+                "total_reward":     result.total_reward,
+                "budget_spent":     result.budget_spent,
+                "budget_overspend": result.budget_overspend,
+                "passed":           result.passed,
+                "steps":            len(_episode_actions),
+            }
+        )
+
+    return obs
+
+
+@app.get("/state", response_model=PayOpsState, summary="Get internal environment state")
+async def state():
+    """Return the current internal state of the environment."""
+    return _env.state()
+
+
+@app.get("/schema", summary="Get action and observation schemas")
+async def schema():
+    """Return the JSON schemas for PayOpsAction and PayOpsObservation."""
+    return {
+        "action": PayOpsAction.model_json_schema(),
+        "observation": PayOpsObservation.model_json_schema(),
+        "state": PayOpsState.model_json_schema(),
+    }
+
+
+@app.get("/tasks", summary="List all available tasks")
+async def tasks():
+    """Return metadata for all tasks grouped by difficulty."""
+    result = []
+    for t in TASKS:
+        result.append(
+            {
+                "task_id":         t.task_id,
+                "difficulty":      t.difficulty,
+                "description":     t.description,
+                "transaction_id":  t.transaction_id,
+                "amount":          t.amount,
+                "currency":        t.currency,
+                "transaction_type":t.transaction_type,
+                "risk_score":      t.risk_score,
+                "ml_confidence":   getattr(t, "ml_confidence", None),
+                "flags":           t.flags,
+                "correct_action":  t.correct_action,
+                "requires_investigation": list(getattr(t, "requires_investigation", [])),
+                "regulatory_action": getattr(t, "regulatory_action", False),
+                "chain_total":     getattr(t, "chain_total", 1),
+            }
+        )
+    return {"count": len(result), "tasks": result}
+
+
+@app.get("/grader", summary="Grade the current episode")
+async def grader():
+    """
+    Grade the episode using all actions taken since the last /reset.
+    """
+    if not _episode_actions:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "No actions recorded. Run /reset then /step first."},
+        )
+    result = grade_episode(_episode_actions, _episode_tasks, _episode_confs)
+    return {
+        "total_reward":       result.total_reward,
+        "max_possible_reward":result.max_possible_reward,
+        "normalised_score":   result.normalised_score,
+        "budget_spent":       result.budget_spent,
+        "budget_overspend":   result.budget_overspend,
+        "budget_penalty":     result.budget_penalty,
+        "passed":             result.passed,
+        "per_task":           result.per_task_rewards,
+    }
+
+
+@app.post("/baseline", response_model=BaselineResult, summary="Run the baseline agent")
+async def baseline():
+    """
+    Run the built-in rule-based baseline agent against the full task set
+    and return its scores. Useful for sanity-checking the environment.
+    """
+    from payops_env.scripts_util import run_baseline
+    scores, total, normalised, steps = await run_baseline()
+    return BaselineResult(
+        scores=scores,
+        total_reward=total,
+        normalised_score=normalised,
+        steps=steps,
+    )
+
+
+@app.get("/analytics", summary="Session performance analytics")
+async def analytics():
+    """
+    Return aggregate analytics across all completed episodes this session.
+    Includes accuracy by difficulty, average budget spend, and common mistakes.
+    """
+    if not _leaderboard:
+        return {"message": "No completed episodes yet. Run a full episode first."}
+
+    # Per-difficulty accuracy from the last episode's per_task breakdown
+    result = grade_episode(_episode_actions, _episode_tasks, _episode_confs)
+    by_diff: Dict[str, Dict] = defaultdict(lambda: {"total": 0, "correct": 0, "rewards": []})
+    for pt in result.per_task_rewards:
+        d = pt["difficulty"]
+        by_diff[d]["total"]   += 1
+        by_diff[d]["correct"] += int(pt["correct"])
+        by_diff[d]["rewards"].append(pt["weighted_reward"])
+
+    diff_summary = {
+        diff: {
+            "accuracy":    round(v["correct"] / v["total"], 3) if v["total"] else 0,
+            "avg_reward":  round(sum(v["rewards"]) / len(v["rewards"]), 3) if v["rewards"] else 0,
+            "count":       v["total"],
+        }
+        for diff, v in by_diff.items()
+    }
+
+    return {
+        "episodes_completed":  len(_leaderboard),
+        "best_score":          max(e["normalised_score"] for e in _leaderboard),
+        "avg_score":           round(sum(e["normalised_score"] for e in _leaderboard) / len(_leaderboard), 4),
+        "avg_budget_spent":    round(sum(e["budget_spent"] for e in _leaderboard) / len(_leaderboard), 4),
+        "current_episode":     {
+            "normalised_score": result.normalised_score,
+            "budget_spent":     result.budget_spent,
+            "budget_penalty":   result.budget_penalty,
+            "by_difficulty":    diff_summary,
+        },
+    }
+
+
+@app.post("/replay", summary="Grade a supplied action sequence")
+async def replay(request: ReplayRequest):
+    """
+    Grade a supplied list of actions against the full task bank without
+    modifying the current environment state.
+
+    Useful for offline evaluation and leaderboard submissions.
+    """
+    actions = [a.lower() for a in request.actions]
+    invalid = [a for a in actions if a not in VALID_ACTIONS]
+    if invalid:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Invalid action(s): {invalid}. Valid: {sorted(VALID_ACTIONS)}",
+        )
+
+    confs  = request.confidences or [None] * len(actions)
+    result = grade_episode(actions, list(TASKS), confs)
+    return {
+        "total_reward":        result.total_reward,
+        "max_possible_reward": result.max_possible_reward,
+        "normalised_score":    result.normalised_score,
+        "budget_spent":        result.budget_spent,
+        "budget_overspend":    result.budget_overspend,
+        "budget_penalty":      result.budget_penalty,
+        "passed":              result.passed,
+        "per_task":            result.per_task_rewards,
+    }
+
+
+@app.get("/leaderboard", summary="Session leaderboard")
+async def leaderboard():
+    """
+    Return all scored episodes from this server session, sorted by score.
+    """
+    sorted_board = sorted(_leaderboard, key=lambda e: e["normalised_score"], reverse=True)
+    return {"count": len(sorted_board), "entries": sorted_board}
+
+
+# ---------------------------------------------------------------------------
+# WebSocket endpoint for persistent sessions
+# ---------------------------------------------------------------------------
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    """
+    WebSocket interface.
+
+    Client sends JSON:
+      {"type": "reset"}
+      {"type": "step", "action_type": "...", "transaction_id": "..."}
+      {"type": "state"}
+
+    Server responds with observation JSON.
+    """
+    await websocket.accept()
+    ws_env = PayOpsEnvironment()
+
+    try:
+        while True:
+            raw = await websocket.receive_text()
+            try:
+                msg = json.loads(raw)
+            except json.JSONDecodeError:
+                await websocket.send_json({"error": "Invalid JSON"})
+                continue
+
+            msg_type = msg.get("type", "")
+
+            if msg_type == "reset":
+                obs = await ws_env.reset_async()
+                await websocket.send_json(obs.model_dump())
+
+            elif msg_type == "step":
+                action_type = msg.get("action_type", "")
+                if action_type.lower() not in VALID_ACTIONS:
+                    await websocket.send_json(
+                        {"error": f"Invalid action_type '{action_type}'"}
+                    )
+                    continue
+                action = PayOpsAction(
+                    action_type=action_type,
+                    transaction_id=msg.get("transaction_id", ""),
+                    reason=msg.get("reason"),
+                    confidence=msg.get("confidence"),
+                )
+                try:
+                    obs = await ws_env.step_async(action)
+                    await websocket.send_json(obs.model_dump())
+                except Exception as exc:
+                    await websocket.send_json({"error": str(exc)})
+
+            elif msg_type == "state":
+                await websocket.send_json(ws_env.state().model_dump())
+
+            else:
+                await websocket.send_json(
+                    {"error": f"Unknown message type '{msg_type}'"}
+                )
+
+    except WebSocketDisconnect:
+        ws_env.close()
+
+
+# ---------------------------------------------------------------------------
+# Health check
+# ---------------------------------------------------------------------------
+
+@app.get("/health", summary="Health check")
+async def health():
+    return {"status": "ok", "environment": "payops_env", "version": "2.0.0"}
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)
+

tasks.py

@@ -0,0 +1,668 @@
+"""
+Task bank for the PayOps environment — 20 tasks across 4 difficulty tiers.
+
+Difficulty tiers
+----------------
+  easy      – single clear signal; one-hop decision
+  medium    – ambiguous or competing signals; reasoning required
+  hard      – adversarial, conflicting, or edge-case patterns
+  critical  – multi-step investigation chains; regulatory compliance stakes
+
+Multi-step chains
+-----------------
+Tasks with chain_total > 1 require the agent to issue investigation sub-actions
+(inspect / request_docs / verify_kyc / contact_sender) before a terminal decision.
+Each chain step reveals progressively more context via the appropriate _reveal field.
+The terminal decision is only scored on the final chain step.
+
+Action costs
+------------
+Each investigation sub-action incurs a budget cost.  If the agent exhausts the
+budget (spend > budget_limit), a cumulative cost penalty is applied to the reward.
+
+  inspect        → cost 0.1
+  request_docs   → cost 0.2
+  verify_kyc     → cost 0.2
+  contact_sender → cost 0.3
+  file_sar       → cost 0.1  (required for structuring/AML — free if correct)
+
+Reward structure per task
+-------------------------
+Each task defines:
+  correct_action          – ground-truth terminal decision
+  partial_credit_actions  – {action: fraction_of_full_credit}
+  requires_investigation  – set of sub-actions ideally used before deciding
+  regulatory_action       – if True, file_sar is a required prerequisite for full credit
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+
+
+@dataclass
+class PayOpsTask:
+    # --- identity ---
+    task_id: str
+    difficulty: str          # easy | medium | hard | critical
+    description: str
+
+    # --- transaction fields ---
+    transaction_id: str
+    amount: float
+    currency: str
+    sender: str
+    receiver: str
+    transaction_type: str   # transfer | payment | withdrawal | refund | internal | loan_repayment | payroll
+
+    # --- primary risk signals ---
+    risk_score: float                    # 0.0–1.0
+    ml_confidence: float = 0.90         # model's confidence in its own risk_score
+    flags: List[str] = field(default_factory=list)
+
+    # --- sender behaviour ---
+    velocity_1h: Optional[int] = None
+    velocity_24h: Optional[int] = None
+    avg_transaction_amount: Optional[float] = None
+    account_age_days: Optional[int] = None
+
+    # --- counterparty / geo ---
+    country_risk: Optional[str] = None    # low | medium | high | sanctioned
+    kyc_status: Optional[str] = None      # verified | pending | failed | none | expired
+    kyc_expiry_days: Optional[int] = None
+    previous_violations: Optional[int] = None
+    previous_sars: Optional[int] = None
+    counterparty_risk: Optional[str] = None  # clean | unknown | watchlist | blacklist
+
+    # --- grading ---
+    correct_action: str = "approve"
+    partial_credit_actions: Dict[str, float] = field(default_factory=dict)
+    requires_investigation: Set[str] = field(default_factory=set)
+    # Set of sub-actions the agent SHOULD use for best score.
+    # Using them before the terminal decision grants a bonus (applied in grader).
+    regulatory_action: bool = False
+    # If True, filing a SAR is required to get full credit.
+
+    # --- investigation reveals (each unlocked by the matching sub-action) ---
+    inspect_reveal: Optional[str] = None
+    docs_reveal: Optional[str] = None
+    kyc_reveal: Optional[str] = None
+    contact_reveal: Optional[str] = None
+
+    # --- multi-step chain metadata ---
+    chain_total: int = 1
+    # chain_total > 1 means the task spans multiple investigation steps.
+    # The grader only scores the terminal decision on the last chain step.
+
+
+# =============================================================================
+# EASY  (4 tasks — single clear signal)
+# =============================================================================
+
+EASY_TASKS: List[PayOpsTask] = [
+    PayOpsTask(
+        task_id="EASY-001",
+        difficulty="easy",
+        description="Low-value domestic transfer between two long-standing verified users. No flags.",
+        transaction_id="TXN-E001",
+        amount=47.50,
+        currency="USD",
+        sender="alice@example.com",
+        receiver="bob@example.com",
+        transaction_type="transfer",
+        risk_score=0.05,
+        ml_confidence=0.97,
+        flags=[],
+        velocity_1h=1, velocity_24h=3,
+        avg_transaction_amount=55.0,
+        account_age_days=1_095,
+        country_risk="low", kyc_status="verified", kyc_expiry_days=320,
+        previous_violations=0, previous_sars=0, counterparty_risk="clean",
+        correct_action="approve",
+        partial_credit_actions={"flag": 0.3},
+        inspect_reveal="Sender account 3 yrs old. Consistent transaction history. KYC fully verified.",
+    ),
+    PayOpsTask(
+        task_id="EASY-002",
+        difficulty="easy",
+        description="Textbook fraud: unknown sender, offshore, sanctioned country, risk=0.97.",
+        transaction_id="TXN-E002",
+        amount=9_800.00,
+        currency="USD",
+        sender="unknown_user_x99",
+        receiver="offshore_acct_442",
+        transaction_type="transfer",
+        risk_score=0.97,
+        ml_confidence=0.95,
+        flags=["high_value", "unknown_sender", "offshore_receiver", "sanctioned_country"],
+        velocity_1h=12, velocity_24h=28,
+        avg_transaction_amount=None,
+        account_age_days=2,
+        country_risk="sanctioned", kyc_status="none", kyc_expiry_days=None,
+        previous_violations=3, previous_sars=1, counterparty_risk="blacklist",
+        correct_action="reject",
+        partial_credit_actions={"escalate": 0.4, "flag": 0.2},
+        inspect_reveal="Receiver linked to 3 prior rejected transactions. IP on threat-intel blocklist.",
+    ),
+    PayOpsTask(
+        task_id="EASY-003",
+        difficulty="easy",
+        description="Standard refund to a verified customer. Tiny amount, no flags.",
+        transaction_id="TXN-E003",
+        amount=12.99,
+        currency="USD",
+        sender="shop@retailer.com",
+        receiver="carol@customer.com",
+        transaction_type="refund",
+        risk_score=0.03,
+        ml_confidence=0.98,
+        flags=[],
+        velocity_1h=1, velocity_24h=5,
+        avg_transaction_amount=14.0,
+        account_age_days=730,
+        country_risk="low", kyc_status="verified", kyc_expiry_days=180,
+        previous_violations=0, previous_sars=0, counterparty_risk="clean",
+        correct_action="approve",
+        partial_credit_actions={"flag": 0.3},
+        inspect_reveal="Standard return via web checkout. Matching order ID on file. No anomalies.",
+    ),
+    PayOpsTask(
+        task_id="EASY-004",
+        difficulty="easy",
+        description="ATM withdrawal burst — 15 withdrawals in 58 minutes across 4 ATMs. Velocity violation.",
+        transaction_id="TXN-E004",
+        amount=200.00,
+        currency="USD",
+        sender="david@accounts.com",
+        receiver="atm_node_77",
+        transaction_type="withdrawal",
+        risk_score=0.78,
+        ml_confidence=0.89,
+        flags=["velocity_breach", "atm_burst"],
+        velocity_1h=15, velocity_24h=17,
+        avg_transaction_amount=80.0,
+        account_age_days=540,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=90,
+        previous_violations=0, previous_sars=0, counterparty_risk="unknown",
+        correct_action="flag",
+        partial_credit_actions={"escalate": 0.6, "hold": 0.5},
+        inspect_reveal="15 ATM withdrawals in 58 min across 4 ATMs. Pattern consistent with card clone.",
+    ),
+]
+
+
+# =============================================================================
+# MEDIUM  (6 tasks — ambiguous, multi-signal)
+# =============================================================================
+
+MEDIUM_TASKS: List[PayOpsTask] = [
+    PayOpsTask(
+        task_id="MED-001",
+        difficulty="medium",
+        description="Large B2B wire. Verified CFO. Cross-border to medium-risk EU jurisdiction.",
+        transaction_id="TXN-M001",
+        amount=85_000.00,
+        currency="EUR",
+        sender="cfo@globalcorp.com",
+        receiver="vendor@eu-supplier.de",
+        transaction_type="transfer",
+        risk_score=0.52,
+        ml_confidence=0.72,
+        flags=["high_value", "cross_border"],
+        velocity_1h=2, velocity_24h=4,
+        avg_transaction_amount=45_000.0,
+        account_age_days=2_190,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=200,
+        previous_violations=0, previous_sars=0, counterparty_risk="clean",
+        correct_action="escalate",
+        partial_credit_actions={"flag": 0.5, "hold": 0.4},
+        requires_investigation={"inspect"},
+        inspect_reveal="Contract on file for €85k milestone. Receiver is licensed EU entity. Quarterly vendor pattern.",
+    ),
+    PayOpsTask(
+        task_id="MED-002",
+        difficulty="medium",
+        description="Internal treasury transfer. Large amount. KYC pending renewal — risk is procedural, not fraud.",
+        transaction_id="TXN-M002",
+        amount=250_000.00,
+        currency="USD",
+        sender="treasury@holdco.com",
+        receiver="subsidiary@holdco-us.com",
+        transaction_type="internal",
+        risk_score=0.41,
+        ml_confidence=0.78,
+        flags=["high_value", "kyc_expiry_90d"],
+        velocity_1h=1, velocity_24h=2,
+        avg_transaction_amount=200_000.0,
+        account_age_days=3_650,
+        country_risk="low", kyc_status="pending", kyc_expiry_days=5,
+        previous_violations=0, previous_sars=0, counterparty_risk="clean",
+        correct_action="hold",
+        partial_credit_actions={"escalate": 0.6, "flag": 0.4},
+        requires_investigation={"verify_kyc"},
+        kyc_reveal="KYC renewal submitted 10 days ago. Both accounts share same UBO. Transfer aligns with Q1 plan.",
+    ),
+    PayOpsTask(
+        task_id="MED-003",
+        difficulty="medium",
+        description="Subscription payment 3× historical average. Possible upgrade billing or card compromise.",
+        transaction_id="TXN-M003",
+        amount=449.97,
+        currency="USD",
+        sender="eve@subscriber.com",
+        receiver="billing@saas-platform.com",
+        transaction_type="payment",
+        risk_score=0.44,
+        ml_confidence=0.68,
+        flags=["amount_spike", "pattern_deviation"],
+        velocity_1h=1, velocity_24h=1,
+        avg_transaction_amount=149.99,
+        account_age_days=820,
+        country_risk="low", kyc_status="verified", kyc_expiry_days=150,
+        previous_violations=0, previous_sars=0, counterparty_risk="clean",
+        correct_action="flag",
+        partial_credit_actions={"hold": 0.5, "escalate": 0.3},
+        inspect_reveal="Historical monthly charge $149.99. This charge = 3-month annual upgrade. Merchant confirmation pending.",
+    ),
+    PayOpsTask(
+        task_id="MED-004",
+        difficulty="medium",
+        description="Payment to regulated crypto exchange. Moderate risk. Sender has clean history.",
+        transaction_id="TXN-M004",
+        amount=5_000.00,
+        currency="USD",
+        sender="frank@personal.com",
+        receiver="exchange@cryptovault.io",
+        transaction_type="payment",
+        risk_score=0.58,
+        ml_confidence=0.74,
+        flags=["crypto_exchange", "high_value"],
+        velocity_1h=1, velocity_24h=2,
+        avg_transaction_amount=2_000.0,
+        account_age_days=1_460,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=270,
+        previous_violations=0, previous_sars=0, counterparty_risk="unknown",
+        correct_action="flag",
+        partial_credit_actions={"escalate": 0.5, "hold": 0.4},
+        inspect_reveal="Exchange licensed in sender's jurisdiction. Sender made 4 similar payments over 6 months. Within limits.",
+    ),
+    PayOpsTask(
+        task_id="MED-005",
+        difficulty="medium",
+        description="Expired KYC on a high-frequency corporate account. Routine transactions continue but KYC lapsed 12 days ago.",
+        transaction_id="TXN-M005",
+        amount=28_000.00,
+        currency="GBP",
+        sender="payments@logistics-uk.com",
+        receiver="driver-pool@payroll.co.uk",
+        transaction_type="payroll",
+        risk_score=0.38,
+        ml_confidence=0.82,
+        flags=["kyc_expired", "high_value"],
+        velocity_1h=1, velocity_24h=6,
+        avg_transaction_amount=26_000.0,
+        account_age_days=1_800,
+        country_risk="low", kyc_status="expired", kyc_expiry_days=-12,
+        previous_violations=0, previous_sars=0, counterparty_risk="clean",
+        correct_action="hold",
+        partial_credit_actions={"flag": 0.5, "escalate": 0.4},
+        requires_investigation={"verify_kyc"},
+        kyc_reveal="KYC expired 12 days ago due to administrative oversight. Re-submission in progress. No fraud indicators.",
+    ),
+    PayOpsTask(
+        task_id="MED-006",
+        difficulty="medium",
+        description="Real estate advance payment. Large amount. First payment to this receiver but contract exists.",
+        transaction_id="TXN-M006",
+        amount=120_000.00,
+        currency="USD",
+        sender="buyer@realestate-client.com",
+        receiver="escrow@property-agent.co",
+        transaction_type="transfer",
+        risk_score=0.56,
+        ml_confidence=0.65,
+        flags=["high_value", "first_time_payee", "large_first_transfer"],
+        velocity_1h=1, velocity_24h=1,
+        avg_transaction_amount=5_000.0,
+        account_age_days=2_555,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=90,
+        previous_violations=0, previous_sars=0, counterparty_risk="unknown",
+        correct_action="escalate",
+        partial_credit_actions={"flag": 0.4, "hold": 0.5},
+        requires_investigation={"request_docs"},
+        docs_reveal="Signed purchase agreement found. Escrow agent licensed and registered. Standard conveyancing practice.",
+    ),
+]
+
+
+# =============================================================================
+# HARD  (6 tasks — adversarial, conflicting, edge-cases)
+# =============================================================================
+
+HARD_TASKS: List[PayOpsTask] = [
+    PayOpsTask(
+        task_id="HARD-001",
+        difficulty="hard",
+        description="ML model poisoning: risk_score=0.18 but manual flags scream fraud. Agent must override the model.",
+        transaction_id="TXN-H001",
+        amount=47_000.00,
+        currency="GBP",
+        sender="grace@newaccount.co.uk",
+        receiver="payee@solicitor-uk.com",
+        transaction_type="transfer",
+        risk_score=0.18,     # poisoned — deliberately underscored
+        ml_confidence=0.31,  # low confidence signals model uncertainty
+        flags=["new_account_7d", "large_first_transfer", "solicitor_mule_pattern"],
+        velocity_1h=1, velocity_24h=1,
+        avg_transaction_amount=None,
+        account_age_days=7,
+        country_risk="low", kyc_status="pending", kyc_expiry_days=None,
+        previous_violations=0, previous_sars=0, counterparty_risk="watchlist",
+        correct_action="escalate",
+        partial_credit_actions={"flag": 0.6, "hold": 0.5, "reject": 0.3},
+        requires_investigation={"inspect"},
+        inspect_reveal=(
+            "Account 7 days old. First outbound transfer. Receiver matches solicitor-impersonation "
+            "mule pattern from last month's intelligence bulletin. ML underscored — new clean account."
+        ),
+    ),
+    PayOpsTask(
+        task_id="HARD-002",
+        difficulty="hard",
+        description="APP scam: victim willingly sending money but has been social-engineered. Receiver is a mule.",
+        transaction_id="TXN-H002",
+        amount=12_500.00,
+        currency="GBP",
+        sender="henry@victim-bank.co.uk",
+        receiver="mule_relay_2287@fastpay.io",
+        transaction_type="transfer",
+        risk_score=0.61,
+        ml_confidence=0.77,
+        flags=["app_scam_indicator", "mule_account_pattern", "first_time_payee"],
+        velocity_1h=1, velocity_24h=1,
+        avg_transaction_amount=300.0,
+        account_age_days=3_285,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=180,
+        previous_violations=0, previous_sars=0, counterparty_risk="blacklist",
+        correct_action="reject",
+        partial_credit_actions={"escalate": 0.6, "hold": 0.5, "flag": 0.3},
+        requires_investigation={"contact_sender"},
+        contact_reveal=(
+            "Sender says they were called by someone claiming to be their bank. "
+            "Instructed to move savings to a 'safe account'. Classic APP scam confirmed."
+        ),
+    ),
+    PayOpsTask(
+        task_id="HARD-003",
+        difficulty="hard",
+        description="Structuring/smurfing: just-below-CTR-threshold payments from same beneficial owner across accounts.",
+        transaction_id="TXN-H003",
+        amount=9_450.00,    # just below $10k CTR threshold
+        currency="USD",
+        sender="irene_acct_A@shadow.net",
+        receiver="irene_acct_B@shadow.net",
+        transaction_type="transfer",
+        risk_score=0.71,
+        ml_confidence=0.83,
+        flags=["structuring_pattern", "same_ubo", "ctr_threshold_avoidance", "high_value"],
+        velocity_1h=3, velocity_24h=9,
+        avg_transaction_amount=9_200.0,
+        account_age_days=120,
+        country_risk="high", kyc_status="failed", kyc_expiry_days=None,
+        previous_violations=2, previous_sars=1, counterparty_risk="watchlist",
+        correct_action="reject",
+        partial_credit_actions={"escalate": 0.5, "flag": 0.2},
+        requires_investigation={"inspect"},
+        regulatory_action=True,
+        inspect_reveal=(
+            "3 transactions in 24h: $9,450 + $9,200 + $9,100 from related accounts. "
+            "Same UBO. KYC failed on inconsistent ID docs. Classic CTR structuring."
+        ),
+    ),
+    PayOpsTask(
+        task_id="HARD-004",
+        difficulty="hard",
+        description="Legitimate FX settlement: huge amount, looks alarming — is a standard correspondent banking transfer.",
+        transaction_id="TXN-H004",
+        amount=4_200_000.00,
+        currency="USD",
+        sender="nostro@bank-a-swift.com",
+        receiver="vostro@bank-b-swift.com",
+        transaction_type="internal",
+        risk_score=0.67,
+        ml_confidence=0.58,  # model uncertain on legitimate large transfers
+        flags=["high_value", "cross_border", "fx_settlement"],
+        velocity_1h=8, velocity_24h=24,
+        avg_transaction_amount=3_900_000.0,
+        account_age_days=7_300,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=400,
+        previous_violations=0, previous_sars=0, counterparty_risk="clean",
+        correct_action="approve",
+        partial_credit_actions={"escalate": 0.5, "hold": 0.4, "flag": 0.3},
+        requires_investigation={"inspect"},
+        inspect_reveal=(
+            "Both SWIFT BIC-verified. Part of daily USD/EUR FX settlement cycle. "
+            "8 similar settlements this month, all cleared. Nostro/vostro agreement on file."
+        ),
+    ),
+    PayOpsTask(
+        task_id="HARD-005",
+        difficulty="hard",
+        description=(
+            "Insider threat: employee of the bank initiating an unauthorised wire "
+            "to their personal account, disguised as a vendor payment."
+        ),
+        transaction_id="TXN-H005",
+        amount=22_000.00,
+        currency="USD",
+        sender="staff_ops@bank-internal.com",
+        receiver="jake.smith.personal@gmail.com",
+        transaction_type="payment",
+        risk_score=0.54,
+        ml_confidence=0.61,
+        flags=["internal_to_personal", "unusual_beneficiary", "after_hours"],
+        velocity_1h=1, velocity_24h=1,
+        avg_transaction_amount=75_000.0,
+        account_age_days=2_000,
+        country_risk="low", kyc_status="verified", kyc_expiry_days=240,
+        previous_violations=0, previous_sars=0, counterparty_risk="unknown",
+        correct_action="escalate",
+        partial_credit_actions={"flag": 0.5, "hold": 0.4, "reject": 0.3},
+        requires_investigation={"inspect", "contact_sender"},
+        inspect_reveal=(
+            "Initiation time: 11:47 PM. No vendor contract matches this beneficiary. "
+            "Staff member placed on PIP last week. Receiver email matches staff home address."
+        ),
+        contact_reveal=(
+            "Staff member claims it is a legitimate vendor. Unable to provide contract reference. "
+            "Story changes on follow-up. Escalate to HR and Fraud immediately."
+        ),
+    ),
+    PayOpsTask(
+        task_id="HARD-006",
+        difficulty="hard",
+        description=(
+            "Ghost account: receiver account was dormant for 5 years and suddenly "
+            "received 20 inbound transfers this week. Possible account takeover."
+        ),
+        transaction_id="TXN-H006",
+        amount=3_200.00,
+        currency="EUR",
+        sender="layla@verified-sender.eu",
+        receiver="old_dormant_acct_889@bank.eu",
+        transaction_type="transfer",
+        risk_score=0.63,
+        ml_confidence=0.69,
+        flags=["dormant_receiver", "sudden_activity", "high_inbound_velocity"],
+        velocity_1h=1, velocity_24h=3,
+        avg_transaction_amount=800.0,
+        account_age_days=890,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=60,
+        previous_violations=0, previous_sars=0, counterparty_risk="unknown",
+        correct_action="flag",
+        partial_credit_actions={"hold": 0.6, "escalate": 0.5},
+        requires_investigation={"inspect"},
+        inspect_reveal=(
+            "Receiver dormant 5 years. 20 inbound transfers this week totalling €64k. "
+            "All immediately forwarded offshore. Classic money-mule account reactivation."
+        ),
+    ),
+]
+
+
+# =============================================================================
+# CRITICAL  (4 tasks — multi-step chains, regulatory stakes)
+# =============================================================================
+
+CRITICAL_TASKS: List[PayOpsTask] = [
+    PayOpsTask(
+        task_id="CRIT-001",
+        difficulty="critical",
+        description=(
+            "Multi-step investigation: large wire to a new counterparty. "
+            "Agent must inspect logs, then request supporting documents, "
+            "then make a final decision. Chain of 3 steps."
+        ),
+        transaction_id="TXN-C001",
+        amount=375_000.00,
+        currency="USD",
+        sender="deal-team@pe-firm.com",
+        receiver="newco@acquisition-target.io",
+        transaction_type="transfer",
+        risk_score=0.59,
+        ml_confidence=0.55,
+        flags=["high_value", "first_time_payee", "cross_border", "new_counterparty"],
+        velocity_1h=1, velocity_24h=2,
+        avg_transaction_amount=50_000.0,
+        account_age_days=3_000,
+        country_risk="medium", kyc_status="verified", kyc_expiry_days=120,
+        previous_violations=0, previous_sars=0, counterparty_risk="unknown",
+        correct_action="approve",
+        partial_credit_actions={"escalate": 0.5, "hold": 0.4, "flag": 0.3},
+        requires_investigation={"inspect", "request_docs"},
+        chain_total=3,
+        inspect_reveal="PE firm confirmed. Series B investment round. Deal announced in press last week.",
+        docs_reveal="Signed SPA (Share Purchase Agreement) on file. Notarised. Receiver is the acquisition target.",
+    ),
+    PayOpsTask(
+        task_id="CRIT-002",
+        difficulty="critical",
+        description=(
+            "Fraud ring: three related accounts sending coordinated small payments "
+            "that aggregate above the reporting threshold. Requires SAR filing."
+        ),
+        transaction_id="TXN-C002",
+        amount=4_900.00,
+        currency="USD",
+        sender="ring_node_1@tempmail.com",
+        receiver="collector_hub@offshore.net",
+        transaction_type="transfer",
+        risk_score=0.76,
+        ml_confidence=0.80,
+        flags=["fraud_ring_indicator", "coordinated_transfers", "threshold_avoidance", "high_value"],
+        velocity_1h=5, velocity_24h=18,
+        avg_transaction_amount=4_800.0,
+        account_age_days=45,
+        country_risk="high", kyc_status="failed", kyc_expiry_days=None,
+        previous_violations=1, previous_sars=0, counterparty_risk="blacklist",
+        correct_action="reject",
+        partial_credit_actions={"escalate": 0.4, "flag": 0.2},
+        requires_investigation={"inspect"},
+        regulatory_action=True,
+        chain_total=2,
+        inspect_reveal=(
+            "3 accounts (ring_node_1/2/3) sending $4,900 / $4,850 / $4,750 simultaneously. "
+            "All created same day. Receiver account drained offshore within minutes. "
+            "SAR filing required under BSA §5318(g)."
+        ),
+    ),
+    PayOpsTask(
+        task_id="CRIT-003",
+        difficulty="critical",
+        description=(
+            "Trade-based money laundering: over- and under-invoiced international trade payments. "
+            "Documents don't match transfer amounts. Regulatory escalation required."
+        ),
+        transaction_id="TXN-C003",
+        amount=680_000.00,
+        currency="USD",
+        sender="importer@trade-co.hk",
+        receiver="exporter@goods-supplier.cn",
+        transaction_type="payment",
+        risk_score=0.72,
+        ml_confidence=0.67,
+        flags=["trade_finance", "invoice_mismatch", "cross_border", "high_value"],
+        velocity_1h=1, velocity_24h=3,
+        avg_transaction_amount=120_000.0,
+        account_age_days=730,
+        country_risk="high", kyc_status="verified", kyc_expiry_days=30,
+        previous_violations=1, previous_sars=0, counterparty_risk="watchlist",
+        correct_action="escalate",
+        partial_credit_actions={"flag": 0.4, "hold": 0.35, "reject": 0.3},
+        requires_investigation={"request_docs", "inspect"},
+        regulatory_action=True,
+        chain_total=3,
+        docs_reveal="Invoice declares 500 units @ $1,360 each = $680k. Market price is $320/unit. 4× over-invoiced.",
+        inspect_reveal="Shipping records show only 200 units dispatched. Payment/goods ratio 3.4× above market norm.",
+    ),
+    PayOpsTask(
+        task_id="CRIT-004",
+        difficulty="critical",
+        description=(
+            "Compromised corporate account: valid credentials but geo-impossible login. "
+            "Someone in Nigeria logged into a US-only account 8 minutes after the CEO logged out in NY."
+        ),
+        transaction_id="TXN-C004",
+        amount=198_000.00,
+        currency="USD",
+        sender="ceo@target-corp.com",
+        receiver="urgent-wire@third-party-finance.com",
+        transaction_type="transfer",
+        risk_score=0.81,
+        ml_confidence=0.85,
+        flags=["geo_impossible_login", "account_takeover_indicator", "high_value", "urgency_flag"],
+        velocity_1h=1, velocity_24h=1,
+        avg_transaction_amount=15_000.0,
+        account_age_days=4_380,
+        country_risk="high", kyc_status="verified", kyc_expiry_days=365,
+        previous_violations=0, previous_sars=0, counterparty_risk="unknown",
+        correct_action="reject",
+        partial_credit_actions={"escalate": 0.5, "hold": 0.4},
+        requires_investigation={"inspect", "contact_sender"},
+        chain_total=2,
+        inspect_reveal=(
+            "Last login: NY (US) at 14:23. This session: Lagos (NG) at 14:31. "
+            "Physical travel impossible in 8 minutes. Likely credential compromise."
+        ),
+        contact_reveal="CEO confirms they did NOT initiate this transfer. Account takeover confirmed.",
+    ),
+]
+
+
+# =============================================================================
+# Combine all tasks
+# =============================================================================
+
+TASKS: List[PayOpsTask] = EASY_TASKS + MEDIUM_TASKS + HARD_TASKS + CRITICAL_TASKS
+
+TASKS_BY_ID: Dict[str, PayOpsTask] = {t.task_id: t for t in TASKS}
+
+# ---------------------------------------------------------------------------
+# Action cost table (investigation sub-actions consume budget)
+# ---------------------------------------------------------------------------
+
+ACTION_COSTS: Dict[str, float] = {
+    "approve": 0.0,
+    "reject": 0.0,
+    "flag": 0.0,
+    "escalate": 0.0,
+    "hold": 0.0,
+    "inspect": 0.10,
+    "request_docs": 0.20,
+    "verify_kyc": 0.20,
+    "contact_sender": 0.30,
+    "file_sar": 0.05,   # intentionally cheap — incentivise regulatory compliance
+}
+
+