Refine FraudShield snapshot pipeline

README.md

@@ -1,19 +1,40 @@
 # FraudShield
 
-FraudShield is an OpenEnv environment for marketplace fraud review. An agent receives one e-commerce transaction at a time, decides whether it is `fraud` or `legitimate`, and gets dense reward shaped by business impact, confidence calibration, and correctness.
+FraudShield is an OpenEnv environment for marketplace fraud review. An agent inspects one transaction at a time, predicts whether it is `fraud` or `legitimate`, and receives dense reward shaped by business impact, confidence calibration, and correctness.
 
-The environment is built from a compact task bundle derived from the Kaggle credit card fraud dataset. The bundle is committed as `data/fraudshield_cases.json`, so the repo stays self-contained for Docker and Hugging Face Spaces while still grounding the tasks in real fraud data.
+The environment is grounded in real public fraud data, but it does not fetch live records during `reset()` or `step()`. Instead, it uses a frozen, versioned snapshot stored in `data/fraudshield_cases.json`. That gives you real-world grounding with deterministic grading, fast Docker startup, and reproducible evaluation on Hugging Face Spaces.
 
-## Why this environment
+## Why this design
 
-Real commerce teams review risky orders all day: new sellers, chargeback-heavy merchants, reused devices, flash-sale spikes, and account-takeover style behavior. FraudShield turns that workflow into an agent training environment with:
+For an OpenEnv submission, the safest pattern is:
 
-- A real-world domain instead of a toy game
-- Typed `Action`, `Observation`, and `Reward` models
-- `reset()`, `step()`, and `state()` APIs
-- Three graded tasks with deterministic scoring from `0.0` to `1.0`
-- Dense step rewards with partial progress signals
-- A root `inference.py` baseline compatible with the required OpenAI client flow
+- Fetch or refresh public source data offline
+- Build a deterministic FraudShield snapshot
+- Commit the snapshot used for evaluation
+- Keep the environment runtime fully offline
+
+That avoids runtime API failures, privacy issues, and non-reproducible scores.
+
+## Real-world data strategy
+
+FraudShield currently builds its snapshot from the public Kaggle / ULB credit card fraud dataset:
+
+- Source ID: `kaggle_creditcardfraud`
+- Dataset: `mlg-ulb/creditcardfraud`
+- URL: `https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud`
+
+The loader is now source-agnostic in code:
+
+- `data_loader.py` exposes a public-source snapshot pipeline
+- `download_kaggle_data.py` refreshes the local source CSV and rebuilds the frozen snapshot
+- `fraudshield_env.py` reads the snapshot only at runtime
+
+The checked-in snapshot currently reports:
+
+- Snapshot ID: `fraudshield-realworld-v2`
+- Schema version: `2.0`
+- Seed: `42`
+- Task sizes: easy `24`, medium `36`, hard `48`
 
 ## Tasks
 
@@ -23,11 +44,9 @@ Real commerce teams review risky orders all day: new sellers, chargeback-heavy m
 | Medium | 36 | Balance fraud capture with calibration | No single signal is decisive; tradeoffs matter |
 | Hard | 48 | Handle coordinated abuse and edge-case legitimate traffic | Fraud rings and flash-sale behavior intentionally overlap |
 
-Each task uses a deterministic grader in [graders.py](/c:/Users/Jayashanker/Downloads/fraudshield_kaggle_ready/fraudshield_kaggle/graders.py).
-
 ## Action space
 
-Agents emit a single [FraudCheckAction](/c:/Users/Jayashanker/Downloads/fraudshield_kaggle_ready/fraudshield_kaggle/models.py):
+Agents emit a single `FraudCheckAction`:
 
 ```python
 FraudCheckAction(
@@ -40,15 +59,15 @@ FraudCheckAction(
 
 ## Observation space
 
-Each step returns a [FraudCheckObservation](/c:/Users/Jayashanker/Downloads/fraudshield_kaggle_ready/fraudshield_kaggle/models.py) with structured transaction facts and rolling context:
+Each step returns a `FraudCheckObservation` with:
 
-- Transaction facts: amount, seller age, buyer age, payment method, geo mismatch, rating, prior flags, chargeback rate, shared-device counts, same-address velocity, and more
-- Historical context: seller velocity, linked cards, refund counts, cluster alert score, and task-specific notes
-- Task metadata: difficulty and episode step
+- Structured transaction facts such as amount, seller age, buyer age, geo mismatch, rating, prior flags, chargeback rate, shared-device counts, and address velocity
+- Historical context such as seller velocity, linked cards, refund counts, cluster alert score, and source snapshot metadata
+- Task metadata including difficulty and episode step
 
 ## Reward design
 
-Rewards are dense and cost-sensitive in [fraudshield_env.py](/c:/Users/Jayashanker/Downloads/fraudshield_kaggle_ready/fraudshield_kaggle/fraudshield_env.py):
+Rewards in `fraudshield_env.py` are dense and cost-sensitive:
 
 - Correct fraud catches receive the strongest positive reward
 - Correct legitimate approvals still earn positive reward, but less than catching fraud
@@ -56,11 +75,9 @@ Rewards are dense and cost-sensitive in [fraudshield_env.py](/c:/Users/Jayashank
 - Confidence is rewarded when it matches hidden case difficulty and punished when it is overconfident
 - Submitting the wrong `transaction_id` adds an extra penalty
 
-This gives the agent signal across the full trajectory instead of only at episode end.
-
 ## Graders
 
-The three task graders are deterministic and return `0.0` to `1.0`.
+The three task graders in `graders.py` are deterministic and return scores from `0.0` to `1.0`.
 
 - Easy: accuracy, F1, recall, and specificity
 - Medium: F1, ROC-AUC, precision, and confidence calibration
@@ -68,10 +85,10 @@ The three task graders are deterministic and return `0.0` to `1.0`.
 
 ## Baseline inference
 
-The required root script is [inference.py](/c:/Users/Jayashanker/Downloads/fraudshield_kaggle_ready/fraudshield_kaggle/inference.py).
+The required root script is `inference.py`.
 
 - Competition mode: if `API_BASE_URL`, `MODEL_NAME`, and `HF_TOKEN` are set, it uses the OpenAI client against that endpoint
-- Local smoke-test mode: if those variables are missing, it falls back to a deterministic heuristic agent so the repo can still be verified offline
+- Local smoke-test mode: if those variables are missing, it falls back to a deterministic heuristic agent
 
 Required environment variables for the competition path:
 
@@ -87,11 +104,11 @@ Run it with:
 python inference.py
 ```
 
-The script writes `fraudshield_baseline_results.json` in the project root.
+The script writes `fraudshield_baseline_results.json` to the project root.
 
-### Local offline baseline
+### Tested local baseline
 
-With the deterministic heuristic fallback and seed `42`, the current local smoke-test scores are:
+I reran the baseline after the snapshot-loader changes. With the deterministic heuristic fallback and seed `42`, the tested local scores are:
 
 | Task | Score |
 | --- | ---: |
@@ -103,23 +120,23 @@ With the deterministic heuristic fallback and seed `42`, the current local smoke
 ## Project layout
 
 ```text
-fraudshield_kaggle/
-├── data/
-│   └── fraudshield_cases.json
-├── server/
-│   ├── __init__.py
-│   └── app.py
-├── data_loader.py
-├── download_kaggle_data.py
-├── Dockerfile
-├── fraudshield_env.py
-├── graders.py
-├── inference.py
-├── inference_llm.py
-├── llm_agent.py
-├── models.py
-├── openenv.yaml
-└── pyproject.toml
+fraudshield/
+|-- data/
+|   |-- fraudshield_cases.json
+|-- server/
+|   |-- __init__.py
+|   `-- app.py
+|-- data_loader.py
+|-- download_kaggle_data.py
+|-- Dockerfile
+|-- fraudshield_env.py
+|-- graders.py
+|-- inference.py
+|-- inference_llm.py
+|-- llm_agent.py
+|-- models.py
+|-- openenv.yaml
+`-- pyproject.toml
 ```
 
 ## Setup
@@ -130,14 +147,16 @@ Install the project:
 python -m pip install -e .
 ```
 
-Optional: if you want to regenerate the compact bundle from the original Kaggle CSV instead of using the committed task file:
+If you want to rebuild the frozen snapshot from the public source CSV:
 
 ```bash
 python -m pip install -e ".[data]"
 python download_kaggle_data.py
 ```
 
-## Running the environment locally
+If `data/creditcard.csv` already exists locally, the script rebuilds the snapshot without needing to download again.
+
+## Running locally
 
 ### Python API
 
@@ -146,7 +165,7 @@ from fraudshield_env import FraudShieldEnvironment
 from models import DecisionEnum, FraudCheckAction
 
 env = FraudShieldEnvironment(data_path="data", seed=42)
-env.load_kaggle_data()
+env.load_data()
 reset_result = env.reset("medium")
 
 action = FraudCheckAction(
@@ -184,16 +203,7 @@ docker build -t fraudshield .
 docker run -p 7860:7860 fraudshield
 ```
 
-The container listens on port `7860`, which is the expected default for Hugging Face Docker Spaces.
-
-## Hugging Face Spaces
-
-This repo is ready for a Docker Space:
-
-- Include `openenv` in the Space tags
-- Use the provided `Dockerfile`
-- Expose the app on port `7860`
-- Set `API_BASE_URL`, `MODEL_NAME`, and `HF_TOKEN` in the Space secrets if you want the LLM baseline to run there
+The container listens on port `7860`, which matches Hugging Face Docker Spaces expectations.
 
 ## Validation checklist
 
@@ -213,6 +223,6 @@ Then verify:
 
 ## Notes
 
-- The committed task bundle is small on purpose so the repo stays deployable without external downloads
-- The source CSV is optional and only needed if you want to regenerate the bundle
-- `inference_llm.py` is kept as a backward-compatible wrapper to the main baseline entrypoint
+- Runtime uses the committed snapshot only
+- Public source refresh is optional and intended for offline rebuilds
+- `inference_llm.py` remains as a thin wrapper to `inference.py`

data/fraudshield_cases.json

@@ -1,6 +1,21 @@
 {
-  "seed": 42,
-  "source": "Kaggle creditcardfraud",
+  "metadata": {
+    "snapshot_id": "fraudshield-realworld-v2",
+    "schema_version": "2.0",
+    "generated_at": "2026-03-30T18:13:06.935921+00:00",
+    "seed": 42,
+    "build_notes": "Runtime uses this frozen snapshot only. Public source downloads are optional and intended for rebuilding the snapshot offline.",
+    "sources": [
+      {
+        "source_id": "kaggle_creditcardfraud",
+        "provider": "Kaggle / ULB",
+        "dataset_id": "mlg-ulb/creditcardfraud",
+        "title": "Credit Card Fraud Detection",
+        "source_url": "https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud",
+        "license_note": "Refer to the dataset page for license and usage terms."
+      }
+    ]
+  },
   "tasks": {
     "easy": [
       {
@@ -33,6 +48,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 2,
@@ -72,6 +89,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 13,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 1,
@@ -111,6 +130,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 1,
@@ -150,6 +171,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 0,
@@ -189,6 +212,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 2,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 0,
@@ -228,6 +253,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 16,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 1,
@@ -267,6 +294,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 2,
@@ -306,6 +335,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 16,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 1,
@@ -345,6 +376,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 1,
@@ -384,6 +417,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 5,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 2,
@@ -423,6 +458,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 18,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 1,
@@ -462,6 +499,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 1,
@@ -501,6 +540,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 8,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 1,
@@ -540,6 +581,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 8,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 1,
@@ -579,6 +622,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 6,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 2,
@@ -618,6 +663,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 9,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 1,
@@ -657,6 +704,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 11,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 1,
@@ -696,6 +745,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 2,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 1,
@@ -735,6 +786,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 10,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 0,
@@ -774,6 +827,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 1,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 1,
@@ -813,6 +868,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 5,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 2,
@@ -852,6 +909,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 2,
@@ -891,6 +950,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 14,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 1,
@@ -930,6 +991,8 @@
         },
         "historical_context": {
           "task_focus": "Obvious fraud markers such as new sellers, price gaps, and geo mismatch.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 10,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 1,
@@ -971,6 +1034,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 11,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 5,
@@ -1010,6 +1075,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 2,
@@ -1049,6 +1116,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 6,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 5,
@@ -1088,6 +1157,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 3,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 1,
@@ -1127,6 +1198,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 0,
@@ -1166,6 +1239,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 6,
@@ -1205,6 +1280,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 1,
@@ -1244,6 +1321,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 8,
           "recent_refunds_7d": 2,
@@ -1283,6 +1362,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 10,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 1,
@@ -1322,6 +1403,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 12,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 6,
@@ -1361,6 +1444,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 18,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 3,
@@ -1400,6 +1485,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 6,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 1,
@@ -1439,6 +1526,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 8,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 2,
@@ -1478,6 +1567,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 10,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 6,
@@ -1517,6 +1608,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 3,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 4,
@@ -1556,6 +1649,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 5,
@@ -1595,6 +1690,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 5,
@@ -1634,6 +1731,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 5,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 1,
@@ -1673,6 +1772,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 5,
@@ -1712,6 +1813,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 1,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 6,
@@ -1751,6 +1854,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 14,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 3,
@@ -1790,6 +1895,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 18,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 4,
@@ -1829,6 +1936,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 10,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 3,
@@ -1868,6 +1977,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 13,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 6,
@@ -1907,6 +2018,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 6,
@@ -1946,6 +2059,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 7,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 3,
@@ -1985,6 +2100,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 14,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 2,
@@ -2024,6 +2141,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 8,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 5,
@@ -2063,6 +2182,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 5,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 1,
@@ -2102,6 +2223,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 5,
@@ -2141,6 +2264,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 2,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 4,
@@ -2180,6 +2305,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 13,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 3,
@@ -2219,6 +2346,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 8,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 6,
@@ -2258,6 +2387,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 1,
@@ -2297,6 +2428,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 4,
@@ -2336,6 +2469,8 @@
         },
         "historical_context": {
           "task_focus": "Mixed-signal reviews where no single indicator is decisive.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 12,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 2,
@@ -2377,6 +2512,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 4,
@@ -2416,6 +2553,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 27,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 6,
@@ -2455,6 +2594,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 18,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 0,
@@ -2494,6 +2635,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 26,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 4,
@@ -2533,6 +2676,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 4,
@@ -2572,6 +2717,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 3,
@@ -2611,6 +2758,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 9,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 2,
@@ -2650,6 +2799,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 13,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 6,
@@ -2689,6 +2840,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 2,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 6,
@@ -2728,6 +2881,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 14,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 4,
@@ -2767,6 +2922,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 21,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 2,
@@ -2806,6 +2963,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 24,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 4,
@@ -2845,6 +3004,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 21,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 1,
@@ -2884,6 +3045,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 3,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 5,
@@ -2923,6 +3086,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 29,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 5,
@@ -2962,6 +3127,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 4,
@@ -3001,6 +3168,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 31,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 2,
@@ -3040,6 +3209,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 12,
           "linked_cards_7d": 8,
           "recent_refunds_7d": 4,
@@ -3079,6 +3250,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 13,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 0,
@@ -3118,6 +3291,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 21,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 5,
@@ -3157,6 +3332,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 7,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 1,
@@ -3196,6 +3373,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 2,
@@ -3235,6 +3414,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 1,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 4,
@@ -3274,6 +3455,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 31,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 2,
@@ -3313,6 +3496,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 31,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 5,
@@ -3352,6 +3537,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 15,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 4,
@@ -3391,6 +3578,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 2,
@@ -3430,6 +3619,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 25,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 1,
@@ -3469,6 +3660,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 18,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 2,
@@ -3508,6 +3701,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 3,
@@ -3547,6 +3742,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 24,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 4,
@@ -3586,6 +3783,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 7,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 3,
@@ -3625,6 +3824,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 23,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 3,
@@ -3664,6 +3865,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 14,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 5,
@@ -3703,6 +3906,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 4,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 5,
@@ -3742,6 +3947,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 17,
           "linked_cards_7d": 3,
           "recent_refunds_7d": 6,
@@ -3781,6 +3988,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 8,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 5,
@@ -3820,6 +4029,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 7,
           "linked_cards_7d": 1,
           "recent_refunds_7d": 5,
@@ -3859,6 +4070,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 30,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 0,
@@ -3898,6 +4111,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 2,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 4,
@@ -3937,6 +4152,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 9,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 4,
@@ -3976,6 +4193,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 27,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 6,
@@ -4015,6 +4234,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 21,
           "linked_cards_7d": 6,
           "recent_refunds_7d": 2,
@@ -4054,6 +4275,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 18,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 4,
@@ -4093,6 +4316,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 21,
           "linked_cards_7d": 4,
           "recent_refunds_7d": 6,
@@ -4132,6 +4357,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 34,
           "linked_cards_7d": 5,
           "recent_refunds_7d": 6,
@@ -4171,6 +4398,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 25,
           "linked_cards_7d": 7,
           "recent_refunds_7d": 2,
@@ -4210,6 +4439,8 @@
         },
         "historical_context": {
           "task_focus": "Coordinated abuse and high-volume legitimate edge cases with overlap.",
+          "snapshot_id": "fraudshield-realworld-v1",
+          "source_id": "kaggle_creditcardfraud",
           "seller_transactions_1h": 9,
           "linked_cards_7d": 2,
           "recent_refunds_7d": 2,

data_loader.py

@@ -1,11 +1,11 @@
-"""Deterministic FraudShield task bundle loader."""
+"""Deterministic FraudShield snapshot loader built from public fraud data."""
 
 from __future__ import annotations
 
 import hashlib
 import json
 import logging
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Tuple
 
@@ -14,6 +14,19 @@ import pandas as pd
 
 logger = logging.getLogger(__name__)
 
+PRIMARY_SOURCE_ID = "kaggle_creditcardfraud"
+BUNDLE_SCHEMA_VERSION = "2.0"
+
+PUBLIC_SOURCE_CATALOG: Dict[str, Dict[str, str]] = {
+    PRIMARY_SOURCE_ID: {
+        "provider": "Kaggle / ULB",
+        "dataset_id": "mlg-ulb/creditcardfraud",
+        "title": "Credit Card Fraud Detection",
+        "source_url": "https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud",
+        "license_note": "Refer to the dataset page for license and usage terms.",
+    }
+}
+
 TASK_SPECS: Dict[str, Dict[str, Any]] = {
     "easy": {
         "per_class": 12,
@@ -36,8 +49,8 @@ TASK_SPECS: Dict[str, Dict[str, Any]] = {
 }
 
 
-class KaggleDataLoader:
-    """Loads the curated FraudShield task bundle or builds it from Kaggle data."""
+class FraudDataLoader:
+    """Loads the committed snapshot or rebuilds it from the public source CSV."""
 
     def __init__(self, data_path: str = "data", seed: int = 42):
         self.seed = seed
@@ -47,54 +60,98 @@ class KaggleDataLoader:
         self.bundle_file = self.data_path / "fraudshield_cases.json"
         self.df: pd.DataFrame | None = None
         self.task_bundle: Dict[str, List[Dict[str, Any]]] = {}
+        self.bundle_metadata: Dict[str, Any] = {}
+        self.source_catalog = PUBLIC_SOURCE_CATALOG.copy()
 
-    def download_data(self) -> bool:
-        """Download the source Kaggle dataset for bundle regeneration."""
+    def download_source_data(self, source_id: str = PRIMARY_SOURCE_ID) -> bool:
+        """Download the public source dataset used to build the local snapshot."""
+
+        if source_id != PRIMARY_SOURCE_ID:
+            raise ValueError(f"Unsupported source_id: {source_id}")
 
         try:
             import kaggle
 
-            logger.info("Downloading Kaggle Credit Card Fraud dataset...")
+            logger.info("Downloading public source dataset %s...", source_id)
             kaggle.api.dataset_download_files(
-                "mlg-ulb/creditcardfraud",
+                self.source_catalog[source_id]["dataset_id"],
                 path=str(self.data_path),
                 unzip=True,
             )
             logger.info("Downloaded source data to %s", self.data_path)
             return True
         except Exception as exc:  # pragma: no cover - external dependency
-            logger.error("Failed to download Kaggle data: %s", exc)
+            logger.error("Failed to download source data: %s", exc)
             return False
 
-    def load_data(self) -> bool:
-        """Load the compact task bundle, building it from CSV if needed."""
+    def download_data(self) -> bool:
+        """Backward-compatible wrapper for the old method name."""
+
+        return self.download_source_data()
+
+    def load_bundle(self) -> bool:
+        """Load the compact snapshot, or build it from the local source CSV."""
 
         if self.bundle_file.exists():
-            self.task_bundle = json.loads(self.bundle_file.read_text(encoding="utf-8"))["tasks"]
-            logger.info("Loaded curated task bundle from %s", self.bundle_file)
+            payload = json.loads(self.bundle_file.read_text(encoding="utf-8"))
+            self.task_bundle = payload["tasks"]
+            self.bundle_metadata = self._normalize_bundle_metadata(payload)
+            logger.info(
+                "Loaded FraudShield snapshot %s from %s",
+                self.bundle_metadata.get("snapshot_id", "unknown"),
+                self.bundle_file,
+            )
             return True
 
         if not self.csv_file.exists():
             logger.error("Neither %s nor %s is available.", self.bundle_file, self.csv_file)
             return False
 
-        logger.info("Building curated task bundle from %s", self.csv_file)
+        logger.info("Building FraudShield snapshot from %s", self.csv_file)
         self.df = pd.read_csv(self.csv_file)
         self.task_bundle = self._build_task_bundle()
-        payload = {
-            "seed": self.seed,
-            "source": "Kaggle creditcardfraud",
-            "tasks": self.task_bundle,
-        }
+        payload = self._build_bundle_payload()
+        self.bundle_metadata = payload["metadata"]
         self.bundle_file.write_text(json.dumps(payload, indent=2), encoding="utf-8")
-        logger.info("Wrote deterministic task bundle to %s", self.bundle_file)
+        logger.info("Wrote deterministic FraudShield snapshot to %s", self.bundle_file)
         return True
 
+    def load_data(self) -> bool:
+        """Backward-compatible wrapper for the old method name."""
+
+        return self.load_bundle()
+
+    def get_bundle_summary(self) -> Dict[str, Any]:
+        """Return source and snapshot metadata for docs, APIs, and evals."""
+
+        if not self.bundle_metadata:
+            return {}
+
+        sources = self.bundle_metadata.get("sources", [])
+        return {
+            "snapshot_id": self.bundle_metadata.get("snapshot_id"),
+            "schema_version": self.bundle_metadata.get("schema_version"),
+            "generated_at": self.bundle_metadata.get("generated_at"),
+            "seed": self.bundle_metadata.get("seed", self.seed),
+            "source_count": len(sources),
+            "sources": [
+                {
+                    "source_id": source.get("source_id"),
+                    "provider": source.get("provider"),
+                    "title": source.get("title"),
+                    "dataset_id": source.get("dataset_id"),
+                    "source_url": source.get("source_url"),
+                }
+                for source in sources
+            ],
+            "task_sizes": {task_name: len(cases) for task_name, cases in self.task_bundle.items()},
+        }
+
     def get_task_cases(self, task: str) -> List[Dict[str, Any]]:
         """Return the full case records for a given task."""
 
         if not self.task_bundle:
-            raise RuntimeError("Data not loaded. Call load_data() first.")
+            raise RuntimeError("Data not loaded. Call load_bundle() first.")
         if task not in self.task_bundle:
             raise ValueError(f"Unknown task: {task}")
         return list(self.task_bundle[task])
@@ -116,8 +173,59 @@ class KaggleDataLoader:
             [case["label"] for case in hard_cases],
         )
 
+    def _normalize_bundle_metadata(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Support both the original bundle shape and the new metadata-rich one."""
+
+        metadata = payload.get("metadata")
+        if metadata:
+            return metadata
+
+        source_name = payload.get("source", "Public fraud source")
+        return {
+            "snapshot_id": "fraudshield-realworld-v1",
+            "schema_version": "1.0",
+            "generated_at": None,
+            "seed": payload.get("seed", self.seed),
+            "sources": [
+                {
+                    "source_id": PRIMARY_SOURCE_ID,
+                    "provider": self.source_catalog[PRIMARY_SOURCE_ID]["provider"],
+                    "title": source_name,
+                    "dataset_id": self.source_catalog[PRIMARY_SOURCE_ID]["dataset_id"],
+                    "source_url": self.source_catalog[PRIMARY_SOURCE_ID]["source_url"],
+                }
+            ],
+        }
+
+    def _build_bundle_payload(self) -> Dict[str, Any]:
+        """Build the full snapshot payload written to disk."""
+
+        sources = [
+            {
+                "source_id": source_id,
+                **details,
+            }
+            for source_id, details in self.source_catalog.items()
+            if source_id == PRIMARY_SOURCE_ID
+        ]
+        metadata = {
+            "snapshot_id": "fraudshield-realworld-v2",
+            "schema_version": BUNDLE_SCHEMA_VERSION,
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "seed": self.seed,
+            "build_notes": (
+                "Runtime uses this frozen snapshot only. Public source downloads are optional and "
+                "intended for rebuilding the snapshot offline."
+            ),
+            "sources": sources,
+        }
+        return {
+            "metadata": metadata,
+            "tasks": self.task_bundle,
+        }
+
     def _build_task_bundle(self) -> Dict[str, List[Dict[str, Any]]]:
-        """Create deterministic tasks from the Kaggle dataset."""
+        """Create deterministic tasks from the public source dataset."""
 
         if self.df is None:
             raise RuntimeError("Source dataframe is not loaded.")
@@ -199,7 +307,7 @@ class KaggleDataLoader:
         label: str,
         local_index: int,
     ) -> Dict[str, Any]:
-        """Convert a Kaggle row into one deterministic marketplace case."""
+        """Convert a source row into one deterministic marketplace case."""
 
         row_id = int(row["row_id"])
         anomaly_strength = float(row["case_score"])
@@ -256,7 +364,7 @@ class KaggleDataLoader:
         )
 
         business_cost = self._business_cost(task_name, label, anomaly_strength)
-        case = {
+        return {
             "transaction_id": f"{task_name}_{label}_{row_id}",
             "label": label,
             "risk_score": round(base_risk, 4),
@@ -264,7 +372,6 @@ class KaggleDataLoader:
             "transaction_data": transaction_data,
             "historical_context": historical_context,
         }
-        return case
 
     @staticmethod
     def _timestamp_from_seconds(raw_seconds: float) -> str:
@@ -529,10 +636,20 @@ class KaggleDataLoader:
         fraud_ring_group: int | None,
         flash_sale_group: int | None,
     ) -> Dict[str, Any]:
-        seller_velocity = self._stable_int(1, 18 if task_name != "hard" else 35, "seller-velocity", task_name, label, row_id)
+        seller_velocity = self._stable_int(
+            1,
+            18 if task_name != "hard" else 35,
+            "seller-velocity",
+            task_name,
+            label,
+            row_id,
+        )
         linked_cards = self._stable_int(1, 4 if task_name == "easy" else 8, "linked-cards", task_name, label, row_id)
         recent_refunds = self._stable_int(0, 2 if task_name == "easy" else 6, "refunds", task_name, label, row_id)
-        cluster_alert = round(self._clamp(0.20 + anomaly_strength * 0.55 + (0.10 if fraud_ring_group is not None else 0.0)), 3)
+        cluster_alert = round(
+            self._clamp(0.20 + anomaly_strength * 0.55 + (0.10 if fraud_ring_group is not None else 0.0)),
+            3,
+        )
 
         note = TASK_SPECS[task_name]["focus"]
         if fraud_ring_group is not None:
@@ -542,6 +659,8 @@ class KaggleDataLoader:
 
         return {
             "task_focus": TASK_SPECS[task_name]["focus"],
+            "snapshot_id": self.bundle_metadata.get("snapshot_id") if self.bundle_metadata else "fraudshield-realworld-v1",
+            "source_id": PRIMARY_SOURCE_ID,
             "seller_transactions_1h": seller_velocity,
             "linked_cards_7d": linked_cards,
             "recent_refunds_7d": recent_refunds,
@@ -555,3 +674,7 @@ class KaggleDataLoader:
         task_bias = {"easy": 0.00, "medium": 0.10, "hard": 0.18}[task_name]
         label_bias = 0.28 if label == "fraud" else 0.02
         return self._clamp(0.75 + task_bias + label_bias + anomaly_strength * 0.35, 0.55, 1.85)
+
+
+# Backward-compatible alias to avoid breaking older imports.
+KaggleDataLoader = FraudDataLoader

download_kaggle_data.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Download the Kaggle source CSV and regenerate the compact FraudShield bundle."""
+"""Refresh the local FraudShield snapshot from the public source dataset."""
 
 from __future__ import annotations
 
@@ -7,14 +7,14 @@ import logging
 import sys
 from pathlib import Path
 
-from data_loader import KaggleDataLoader
+from data_loader import FraudDataLoader
 
 logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
 logger = logging.getLogger(__name__)
 
 
 def check_kaggle_setup() -> bool:
-    """Validate that the local Kaggle token exists."""
+    """Validate that the local Kaggle token exists when a download is needed."""
 
     kaggle_json = Path.home() / ".kaggle" / "kaggle.json"
     if kaggle_json.exists():
@@ -22,27 +22,31 @@ def check_kaggle_setup() -> bool:
         return True
 
     logger.error("kaggle.json was not found at %s", kaggle_json)
-    logger.error("Create a Kaggle API token and place it there before running this script.")
+    logger.error("Create a Kaggle API token and place it there before downloading source data.")
     return False
 
 
 def main() -> int:
-    """Download or refresh the source dataset, then rebuild the task bundle."""
+    """Rebuild the FraudShield snapshot from the local CSV or download it first if missing."""
 
-    if not check_kaggle_setup():
-        return 1
+    loader = FraudDataLoader(data_path="data", seed=42)
 
-    loader = KaggleDataLoader(data_path="data", seed=42)
-    if not loader.download_data():
-        return 1
+    if not loader.csv_file.exists():
+        if not check_kaggle_setup():
+            return 1
+        if not loader.download_source_data():
+            return 1
+    else:
+        logger.info("Found existing public source CSV at %s", loader.csv_file)
 
     if loader.bundle_file.exists():
         loader.bundle_file.unlink()
 
-    if not loader.load_data():
+    if not loader.load_bundle():
         return 1
 
-    logger.info("Task bundle is ready at %s", loader.bundle_file)
+    logger.info("Snapshot summary: %s", loader.get_bundle_summary())
+    logger.info("FraudShield snapshot is ready at %s", loader.bundle_file)
     return 0
 
 

fraudshield_env.py

@@ -6,7 +6,7 @@ import uuid
 from datetime import datetime
 from typing import Any, Dict, List
 
-from data_loader import KaggleDataLoader
+from data_loader import FraudDataLoader
 from models import (
     DecisionEnum,
     EpisodeState,
@@ -25,7 +25,7 @@ class FraudShieldEnvironment:
 
     def __init__(self, data_path: str = "data", seed: int = 42):
         self.seed = seed
-        self.data_loader = KaggleDataLoader(data_path=data_path, seed=seed)
+        self.data_loader = FraudDataLoader(data_path=data_path, seed=seed)
         self.data_loaded = False
 
         self.episode_id = ""
@@ -47,16 +47,21 @@ class FraudShieldEnvironment:
             TaskDifficulty.HARD: 48,
         }
 
-    def load_kaggle_data(self) -> bool:
-        """Load the bundled cases or build them from the local CSV."""
+    def load_data(self) -> bool:
+        """Load the committed snapshot or rebuild it from the local public source CSV."""
 
         self.data_loaded = self.data_loader.load_data()
         return self.data_loaded
 
+    def load_kaggle_data(self) -> bool:
+        """Backward-compatible wrapper for the previous method name."""
+
+        return self.load_data()
+
     def ensure_data_loaded(self) -> None:
         """Load data on demand so server startup can stay simple."""
 
-        if not self.data_loaded and not self.load_kaggle_data():
+        if not self.data_loaded and not self.load_data():
             raise RuntimeError("FraudShield data bundle could not be loaded.")
 
     def reset(self, task: str = "easy") -> ResetResult:
@@ -83,6 +88,7 @@ class FraudShieldEnvironment:
             "episode_id": self.episode_id,
             "task": task,
             "task_focus": observation.historical_context.get("task_focus") if observation.historical_context else None,
+            "data_snapshot": self.data_loader.get_bundle_summary(),
             "max_steps": self.max_steps[self.current_task],
             "num_transactions": len(self.current_cases),
             "fraud_count": sum(1 for label in self.ground_truth_labels if label == "fraud"),

inference.py

@@ -67,7 +67,7 @@ def main() -> Dict[str, object]:
     logger.info("%s", "=" * 72)
 
     env = FraudShieldEnvironment(data_path="data", seed=42)
-    if not env.load_kaggle_data():
+    if not env.load_data():
         logger.error("FraudShield data could not be loaded from ./data")
         sys.exit(1)
 
@@ -99,6 +99,7 @@ def main() -> Dict[str, object]:
         "api_base_url": os.getenv("API_BASE_URL", "https://router.huggingface.co/v1"),
         "model_name": os.getenv("MODEL_NAME", ""),
         "seed": 42,
+        "data_snapshot": env.data_loader.get_bundle_summary(),
         "tasks": {
             "easy": len(easy_ground_truth),
             "medium": len(medium_ground_truth),

openenv.yaml

@@ -1,6 +1,6 @@
 name: fraudshield
 version: 0.2.0
-description: OpenEnv environment for marketplace fraud review built from curated Kaggle transactions.
+description: OpenEnv environment for marketplace fraud review built from a frozen public-data snapshot.
 author: Devika J
 
 environment:

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "fraudshield"
 version = "0.2.0"
-description = "OpenEnv fraud review environment built from curated Kaggle transactions"
+description = "OpenEnv fraud review environment built from a frozen public-data snapshot"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }

server/app.py

@@ -25,7 +25,7 @@ env = FraudShieldEnvironment(data_path=str(DATA_PATH), seed=42)
 async def lifespan(_: FastAPI):
     """Load the bundled task set when the API process starts."""
 
-    if not env.load_kaggle_data():
+    if not env.load_data():
         logger.error("FraudShield failed to load its bundled data from %s", DATA_PATH)
     yield
 
@@ -43,7 +43,7 @@ async def health_check() -> Dict[str, Any]:
     """Container health probe."""
 
     if not env.data_loaded:
-        env.load_kaggle_data()
+        env.load_data()
 
     return {
         "status": "healthy" if env.data_loaded else "degraded",
@@ -103,12 +103,13 @@ async def get_info() -> Dict[str, Any]:
     return {
         "name": "fraudshield",
         "version": "0.2.0",
-        "description": "E-commerce fraud review environment built from curated Kaggle cases.",
+        "description": "E-commerce fraud review environment built from a frozen public-data snapshot.",
         "tasks": {
             task.value: {"max_steps": max_steps}
             for task, max_steps in env.max_steps.items()
         },
         "data_path": str(DATA_PATH),
+        "data_snapshot": env.data_loader.get_bundle_summary(),
     }