Upload folder using huggingface_hub

Dockerfile

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

README.md

@@ -1,10 +1,135 @@
 ---
-title: Ad Audit
-emoji: 🐢
-colorFrom: yellow
-colorTo: gray
+title: Ad Audit Environment
+emoji: 🕵️
+colorFrom: red
+colorTo: yellow
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Ad Audit Environment
+
+An RL environment for **detecting advertising fraud** in a simulated 14-day ad campaign. Agents monitor publisher traffic metrics, investigate suspicious patterns, and flag fraudulent publishers while avoiding false positives.
+
+## The Challenge
+
+You manage a digital ad campaign with multiple publishers. Some are legitimate, some are committing fraud. Each day you see traffic metrics and must decide: monitor, investigate, or flag.
+
+**Fraud types:**
+- **Bot Traffic** — CTR spikes dramatically, CVR drops near zero (bots click but never convert)
+- **Click Injection** — CVR becomes abnormally high (fake conversions injected)
+- **Domain Spoofing** — Impressions surge while CVR drops (fake ad inventory)
+
+**The catch:** False positives are heavily penalized, investigations cost budget, and fraudsters adapt when investigated.
+
+## Quick Start
+
+```python
+import asyncio
+from Ad_Audit import AdAuditAction, AdAuditEnv
+
+async def main():
+    env = await AdAuditEnv.from_docker_image("adaudit-env:latest")
+    try:
+        result = await env.reset(episode_id="medium")
+        obs = result.observation
+        print(f"Day {obs.day}: {len(obs.daily_metrics)} publishers")
+
+        # Monitor day 1
+        result = await env.step(AdAuditAction(action_type="monitor"))
+
+        # Investigate a suspicious publisher
+        result = await env.step(AdAuditAction(
+            action_type="investigate_publisher",
+            publisher_id="pub_003",
+            tool="click_timestamps"
+        ))
+
+        # Flag fraud with evidence
+        result = await env.step(AdAuditAction(
+            action_type="flag_fraud",
+            publisher_id="pub_003",
+            fraud_type="bot_traffic",
+            evidence=["click_timestamps", "ip_distribution"]
+        ))
+        print(f"Reward: {result.reward}")
+    finally:
+        await env.close()
+
+asyncio.run(main())
+```
+
+## Actions
+
+| Action | Description | Cost |
+|--------|-------------|------|
+| `monitor` | Observe metrics, take no action | Free |
+| `investigate_publisher` | Run a tool on one publisher | 1 investigation budget |
+| `flag_fraud` | Flag publisher as fraudulent (irreversible) | Free but false positives penalized |
+| `submit_report` | End the episode early | Free |
+
+**Investigation tools:** click_timestamps, ip_distribution, device_fingerprints, referral_urls, viewability_scores, conversion_quality
+
+## Observation
+
+Each step returns:
+- **daily_metrics** — Per-publisher: impressions, clicks, conversions, spend, CTR, CVR
+- **investigation_results** — Tool output (if investigated)
+- **publisher_status** — Active or flagged
+- **budget_status** — Campaign spend and remaining investigation budget
+
+## Tasks
+
+| Task | Publishers | Fraudsters | Investigation Budget | Difficulty |
+|------|-----------|------------|---------------------|------------|
+| `easy` | 2 | 1 (bot_traffic) | 10 | Obvious signals |
+| `medium` | 4 | 2 (bot_traffic + click_injection) | 10 | Mixed fraud types |
+| `hard` | 4 | 2 (domain_spoofing + bot_traffic) | 6 | Subtle signals, tight budget |
+
+## Scoring
+
+Final score (0-1) is weighted:
+- **Fraud detection accuracy** (50%) — Correct flags with right fraud type
+- **Detection timeliness** (30%) — How early fraud was caught
+- **Investigation efficiency** (20%) — Budget usage and false positive avoidance
+
+## Deployment
+
+```bash
+# Build Docker image
+docker build -t adaudit-env .
+
+# Run locally
+docker run -p 8000:8000 adaudit-env
+
+# Or without Docker
+ENABLE_WEB_INTERFACE=true python -m server.app
+```
+
+**Endpoints:**
+- `/web` — Interactive Gradio UI
+- `/docs` — API documentation
+- `/health` — Health check
+- `/ws` — WebSocket for persistent sessions
+
+## Project Structure
+
+```
+Ad_Audit/
+├── inference.py           # LLM agent + rule-based fallback
+├── models.py              # Action / Observation / State models
+├── client.py              # WebSocket client (AdAuditEnv)
+├── cases/                 # Task definitions (easy/medium/hard)
+└── server/
+    ├── app.py             # FastAPI server
+    ├── Ad_Audit_environment.py  # Core environment logic
+    ├── fraud_engine.py    # Suspicion tracking & fraud intensity
+    ├── publisher_engine.py # Traffic generation
+    ├── response_generator.py # Investigation tool responses
+    ├── step_reward.py     # Per-step reward calculator
+    └── grader.py          # Episode-end scoring
+```

__init__.py

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

cases/easy.json

@@ -0,0 +1,59 @@
+{
+  "case_id": "easy",
+  "difficulty": "easy",
+  "campaign": {
+    "name": "Summer Electronics Sale",
+    "duration_days": 14,
+    "total_budget": 10000,
+    "conversion_value": 10.0,
+    "investigation_budget": 10,
+    "industry_benchmarks": {
+      "avg_ctr": 0.020,
+      "avg_cvr": 0.030
+    }
+  },
+  "publishers": {
+    "pub_001": {
+      "name": "TechReview Daily",
+      "is_fraudulent": false,
+      "fraud_type": null,
+      "base_traffic_rate": 10000,
+      "true_ctr": 0.021,
+      "true_cvr": 0.031,
+      "cpm_rate": 2.0,
+      "budget_allocation": 0.5,
+      "suspicion_reactivity": 1.0,
+      "fraud_schedule": {},
+      "fake_ctr": 0.0,
+      "fake_cvr": 0.0,
+      "day_factors": [1.0, 1.02, 0.98, 1.01, 1.03, 0.97, 0.95, 1.04, 1.01, 0.99, 1.02, 1.03, 0.98, 1.0],
+      "noise_factors": [1.01, 0.99, 1.02, 0.98, 1.0, 1.01, 0.99, 1.01, 1.0, 0.99, 1.01, 1.0, 0.99, 1.01]
+    },
+    "pub_002": {
+      "name": "BargainClicks Network",
+      "is_fraudulent": true,
+      "fraud_type": "bot_traffic",
+      "base_traffic_rate": 8000,
+      "true_ctr": 0.019,
+      "true_cvr": 0.028,
+      "cpm_rate": 2.0,
+      "budget_allocation": 0.5,
+      "suspicion_reactivity": 0.3,
+      "fraud_schedule": {
+        "start_day": 2,
+        "ramp_days": 2,
+        "peak_intensity": 3.5
+      },
+      "fake_ctr": 0.08,
+      "fake_cvr": 0.0005,
+      "day_factors": [1.0, 1.03, 1.08, 1.15, 1.20, 1.22, 1.20, 1.23, 1.25, 1.23, 1.25, 1.23, 1.22, 1.20],
+      "noise_factors": [1.0, 1.01, 0.99, 1.02, 1.0, 0.98, 1.01, 1.0, 0.99, 1.02, 1.0, 0.98, 1.01, 1.0]
+    }
+  },
+  "ground_truth": {
+    "fraudulent_publishers": ["pub_002"],
+    "fraud_types": {
+      "pub_002": "bot_traffic"
+    }
+  }
+}

cases/hard.json

@@ -0,0 +1,96 @@
+{
+  "case_id": "hard",
+  "difficulty": "hard",
+  "campaign": {
+    "name": "Global Auto Insurance Q4 Push",
+    "duration_days": 14,
+    "total_budget": 20000,
+    "conversion_value": 10.0,
+    "investigation_budget": 6,
+    "industry_benchmarks": {
+      "avg_ctr": 0.021,
+      "avg_cvr": 0.028
+    }
+  },
+  "publishers": {
+    "pub_001": {
+      "name": "AutoInsure Direct",
+      "is_fraudulent": false,
+      "fraud_type": null,
+      "base_traffic_rate": 11000,
+      "true_ctr": 0.023,
+      "true_cvr": 0.033,
+      "cpm_rate": 2.0,
+      "budget_allocation": 0.25,
+      "suspicion_reactivity": 1.0,
+      "fraud_schedule": {},
+      "fake_ctr": 0.0,
+      "fake_cvr": 0.0,
+      "day_factors": [1.0, 1.01, 0.99, 1.02, 1.0, 0.97, 0.94, 1.02, 1.01, 0.99, 1.01, 1.02, 0.98, 1.0],
+      "noise_factors": [1.0, 0.99, 1.01, 1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01]
+    },
+    "pub_002": {
+      "name": "SafeDrive Media",
+      "is_fraudulent": false,
+      "fraud_type": null,
+      "base_traffic_rate": 8000,
+      "true_ctr": 0.020,
+      "true_cvr": 0.029,
+      "cpm_rate": 2.0,
+      "budget_allocation": 0.25,
+      "suspicion_reactivity": 1.0,
+      "fraud_schedule": {},
+      "fake_ctr": 0.0,
+      "fake_cvr": 0.0,
+      "day_factors": [1.0, 0.99, 1.01, 1.0, 1.02, 0.97, 0.94, 1.01, 1.0, 0.99, 1.01, 1.0, 0.98, 1.01],
+      "noise_factors": [1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01]
+    },
+    "pub_003": {
+      "name": "ShadowNet Ads",
+      "is_fraudulent": true,
+      "fraud_type": "domain_spoofing",
+      "base_traffic_rate": 12000,
+      "true_ctr": 0.019,
+      "true_cvr": 0.025,
+      "cpm_rate": 2.5,
+      "budget_allocation": 0.25,
+      "suspicion_reactivity": 1.8,
+      "fraud_schedule": {
+        "start_day": 4,
+        "ramp_days": 3,
+        "peak_intensity": 1.8
+      },
+      "fake_ctr": 0.025,
+      "fake_cvr": 0.003,
+      "day_factors": [1.0, 1.02, 1.04, 1.08, 1.10, 1.08, 1.10, 1.12, 1.10, 1.08, 1.10, 1.12, 1.10, 1.08],
+      "noise_factors": [1.0, 1.01, 0.99, 1.02, 1.0, 0.98, 1.01, 1.0, 0.99, 1.01, 1.0, 0.99, 1.01, 1.0]
+    },
+    "pub_004": {
+      "name": "ConvertMax Pro",
+      "is_fraudulent": true,
+      "fraud_type": "bot_traffic",
+      "base_traffic_rate": 9000,
+      "true_ctr": 0.021,
+      "true_cvr": 0.029,
+      "cpm_rate": 2.0,
+      "budget_allocation": 0.25,
+      "suspicion_reactivity": 1.5,
+      "fraud_schedule": {
+        "start_day": 5,
+        "ramp_days": 3,
+        "peak_intensity": 1.5
+      },
+      "fake_ctr": 0.04,
+      "fake_cvr": 0.002,
+      "day_factors": [1.0, 1.0, 1.0, 1.01, 1.03, 1.05, 1.06, 1.07, 1.06, 1.07, 1.06, 1.07, 1.06, 1.05],
+      "noise_factors": [1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.02, 1.0, 0.98, 1.01, 1.0, 0.99, 1.01, 1.0]
+    }
+  },
+  "ground_truth": {
+    "fraudulent_publishers": ["pub_003", "pub_004"],
+    "fraud_types": {
+      "pub_003": "domain_spoofing",
+      "pub_004": "bot_traffic"
+    }
+  }
+}

cases/medium.json

@@ -0,0 +1,96 @@
+{
+  "case_id": "medium",
+  "difficulty": "medium",
+  "campaign": {
+    "name": "Holiday Fashion Campaign",
+    "duration_days": 14,
+    "total_budget": 15000,
+    "conversion_value": 10.0,
+    "investigation_budget": 10,
+    "industry_benchmarks": {
+      "avg_ctr": 0.021,
+      "avg_cvr": 0.028
+    }
+  },
+  "publishers": {
+    "pub_001": {
+      "name": "StyleMaven Magazine",
+      "is_fraudulent": false,
+      "fraud_type": null,
+      "base_traffic_rate": 12000,
+      "true_ctr": 0.022,
+      "true_cvr": 0.032,
+      "cpm_rate": 2.5,
+      "budget_allocation": 0.30,
+      "suspicion_reactivity": 1.0,
+      "fraud_schedule": {},
+      "fake_ctr": 0.0,
+      "fake_cvr": 0.0,
+      "day_factors": [1.0, 1.01, 0.99, 1.02, 1.0, 0.97, 0.95, 1.03, 1.01, 0.99, 1.02, 1.0, 0.98, 1.01],
+      "noise_factors": [1.0, 0.99, 1.01, 1.0, 0.98, 1.02, 1.0, 0.99, 1.01, 1.0, 0.98, 1.01, 1.0, 0.99]
+    },
+    "pub_002": {
+      "name": "FashionForward Hub",
+      "is_fraudulent": false,
+      "fraud_type": null,
+      "base_traffic_rate": 7000,
+      "true_ctr": 0.019,
+      "true_cvr": 0.027,
+      "cpm_rate": 2.0,
+      "budget_allocation": 0.20,
+      "suspicion_reactivity": 1.0,
+      "fraud_schedule": {},
+      "fake_ctr": 0.0,
+      "fake_cvr": 0.0,
+      "day_factors": [1.0, 0.99, 1.01, 1.0, 1.02, 0.96, 0.94, 1.01, 1.0, 0.99, 1.01, 1.02, 0.98, 1.0],
+      "noise_factors": [1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01, 0.99, 1.0, 1.01]
+    },
+    "pub_003": {
+      "name": "LuxeAds Premium",
+      "is_fraudulent": true,
+      "fraud_type": "bot_traffic",
+      "base_traffic_rate": 11000,
+      "true_ctr": 0.020,
+      "true_cvr": 0.026,
+      "cpm_rate": 3.0,
+      "budget_allocation": 0.25,
+      "suspicion_reactivity": 0.5,
+      "fraud_schedule": {
+        "start_day": 3,
+        "ramp_days": 2,
+        "peak_intensity": 2.5
+      },
+      "fake_ctr": 0.06,
+      "fake_cvr": 0.001,
+      "day_factors": [1.0, 1.01, 1.0, 1.05, 1.10, 1.12, 1.10, 1.13, 1.12, 1.10, 1.12, 1.13, 1.11, 1.10],
+      "noise_factors": [1.01, 1.0, 0.99, 1.01, 1.0, 0.99, 1.01, 1.0, 0.98, 1.02, 1.0, 0.99, 1.01, 1.0]
+    },
+    "pub_004": {
+      "name": "ClickBoost Pro",
+      "is_fraudulent": true,
+      "fraud_type": "click_injection",
+      "base_traffic_rate": 8000,
+      "true_ctr": 0.018,
+      "true_cvr": 0.024,
+      "cpm_rate": 2.0,
+      "budget_allocation": 0.25,
+      "suspicion_reactivity": 0.5,
+      "fraud_schedule": {
+        "start_day": 3,
+        "ramp_days": 3,
+        "peak_intensity": 2.0
+      },
+      "fake_ctr": 0.04,
+      "fake_cvr": 0.07,
+      "day_factors": [1.0, 1.0, 1.0, 1.03, 1.06, 1.08, 1.10, 1.08, 1.10, 1.08, 1.10, 1.08, 1.10, 1.08],
+      "noise_factors": [1.0, 1.01, 0.99, 1.0, 0.98, 1.02, 1.0, 0.99, 1.01, 1.0, 0.99, 1.01, 1.0, 0.99]
+    }
+  },
+  "ground_truth": {
+    "fraudulent_publishers": ["pub_003", "pub_004"],
+    "fraud_types": {
+      "pub_003": "bot_traffic",
+      "pub_004": "click_injection"
+    }
+  }
+}

client.py

@@ -0,0 +1,77 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Ad Audit Environment Client."""
+
+from typing import Any, Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+
+try:
+    from .models import AdAuditAction, AdAuditObservation, AdAuditState
+except ImportError:
+    from models import AdAuditAction, AdAuditObservation, AdAuditState  # type: ignore[no-redef]
+
+
+class AdAuditEnv(
+    EnvClient[AdAuditAction, AdAuditObservation, AdAuditState]
+):
+    """
+    Client for the Ad Audit Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example with Docker:
+        >>> client = await AdAuditEnv.from_docker_image("adaudit-env:latest")
+        >>> try:
+        ...     result = await client.reset(episode_id="medium")
+        ...     result = await client.step(AdAuditAction(action_type="monitor"))
+        ... finally:
+        ...     await client.close()
+    """
+
+    def _step_payload(self, action: AdAuditAction) -> Dict[str, Any]:
+        """
+        Convert AdAuditAction to JSON payload for step message.
+
+        The server deserializes this via AdAuditAction.model_validate(),
+        so we just send the pydantic model_dump with None fields excluded.
+        """
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[AdAuditObservation]:
+        """
+        Parse server response into StepResult[AdAuditObservation].
+
+        The server sends:
+        {
+            "observation": { ... AdAuditObservation fields (minus reward/done/metadata) ... },
+            "reward": float | None,
+            "done": bool,
+        }
+        """
+        obs_data = payload.get("observation", {})
+
+        # Re-inject reward/done so the Observation model has them
+        obs_data["reward"] = payload.get("reward")
+        obs_data["done"] = payload.get("done", False)
+
+        observation = AdAuditObservation.model_validate(obs_data)
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> AdAuditState:
+        """
+        Parse server response into AdAuditState.
+        """
+        return AdAuditState.model_validate(payload)

inference.py

@@ -0,0 +1,425 @@
+"""
+Inference Script for AdAudit
+===================================
+MANDATORY
+- Before submitting, ensure the following variables are defined in your environment configuration:
+    API_BASE_URL   The API endpoint for the LLM.
+    MODEL_NAME     The model identifier to use for inference.
+    HF_TOKEN       Your Hugging Face / API key.
+    LOCAL_IMAGE_NAME The name of the local image to use for the environment if you are using from_docker_image()
+                     method
+
+- Defaults are set only for API_BASE_URL and MODEL_NAME
+    (and should reflect your active inference setup):
+    API_BASE_URL = os.getenv("API_BASE_URL", "<your-active-endpoint>")
+    MODEL_NAME = os.getenv("MODEL_NAME", "<your-active-model>")
+
+- The inference script must be named `inference.py` and placed in the root directory of the project
+- Participants must use OpenAI Client for all LLM calls using above variables
+
+STDOUT FORMAT
+- The script must emit exactly three line types to stdout, in this order:
+
+    [START] task=<task_name> env=<benchmark> model=<model_name>
+    [STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+    [END]   success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...,rn>
+
+  Rules:
+    - One [START] line at episode begin.
+    - One [STEP] line per step, immediately after env.step() returns.
+    - One [END] line after env.close(), always emitted (even on exception).
+    - reward and rewards are formatted to 2 decimal places.
+    - done and success are lowercase booleans: true or false.
+    - error is the raw last_action_error string, or null if none.
+    - All fields on a single line with no newlines within a line.
+    - Each tasks should return score in [0, 1]
+
+  Example:
+    [START] task=click-test env=miniwob model=Qwen3-VL-30B
+    [STEP] step=1 action=click('123') reward=0.00 done=false error=null
+    [STEP] step=2 action=fill('456','text') reward=0.00 done=false error=null
+    [STEP] step=3 action=click('789') reward=1.00 done=true error=null
+    [END] success=true steps=3 score=1.00 rewards=0.00,0.00,1.00
+"""
+
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from openai import OpenAI
+
+from server.Ad_Audit_environment import AdAuditEnv, EPISODE_DAYS
+from models import AdAuditAction
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+IMAGE_NAME = os.getenv("LOCAL_IMAGE_NAME")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-7B-Instruct")
+
+_VALID_TASKS = {"easy", "medium", "hard"}
+_task_env = os.getenv("ADAUDIT_TASK", "").strip().lower()
+TASK_NAME = _task_env if _task_env in _VALID_TASKS else "hard"
+BENCHMARK = os.getenv("ADAUDIT_BENCHMARK", "adaudit")
+TEMPERATURE = 0.0
+MAX_TOKENS = 2048
+HISTORY_WINDOW = 5
+BASELINE_DAYS = 3
+SUCCESS_SCORE_THRESHOLD = 0.5
+
+# Rule-based investigation tools per fraud type
+TOOLS_FOR = {
+    "bot_traffic": ["click_timestamps", "ip_distribution"],
+    "click_injection": ["conversion_quality", "click_timestamps"],
+    "domain_spoofing": ["referral_urls", "viewability_scores"],
+}
+
+SYSTEM_PROMPT = """\
+You are an ad fraud analyst monitoring a 14-day campaign with multiple publishers.
+Each day you see metrics (impressions, clicks, conversions, CTR, CVR) and take ONE action.
+
+## ACTIONS
+
+Use publisher IDs (pub_001, pub_002, etc.), never publisher names.
+
+1. Monitor — observe metrics, take no action:
+   {"action_type": "monitor"}
+2. Investigate — run one tool on one publisher (costs 1 budget):
+   {"action_type": "investigate_publisher", "publisher_id": "pub_001", "tool": "click_timestamps"}
+3. Flag fraud — flag a publisher as fraudulent (irreversible):
+   {"action_type": "flag_fraud", "publisher_id": "pub_001", "fraud_type": "bot_traffic", "evidence": ["click_timestamps", "ip_distribution"]}
+4. Submit report — end the episode:
+   {"action_type": "submit_report", "summary": "..."}
+
+Valid tools: click_timestamps, ip_distribution, device_fingerprints, \
+referral_urls, viewability_scores, conversion_quality
+Valid fraud types: bot_traffic, domain_spoofing, click_injection
+
+## STRATEGY
+1. Monitor days 1-3 to establish baselines. Then compare each publisher's CTR/CVR against its own baseline. Only publishers with BIG shifts (CTR doubled, CVR crashed, impressions tripled) are suspicious. Stable metrics = clean.
+2. Investigate suspicious publishers with 2 tools before flagging. bot_traffic = CTR spikes + CVR near zero. click_injection = CVR abnormally high (5%+). domain_spoofing = impressions surge + CVR drops.
+3. False positives are heavily penalized. When in doubt, monitor. 
+4. Do not submit report until you are confident you have found and flagged ALL fraudsters.
+
+Respond with ONLY a JSON action in ```json``` markers.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Logging helpers
+# ---------------------------------------------------------------------------
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error if error else "null"
+    done_val = str(done).lower()
+    print(f"[STEP] step={step} action={action} reward={reward:.2f} done={done_val} error={error_val}", flush=True)
+
+
+def log_end(success: bool, steps: int, score: float, rewards: List[float]) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(f"[END] success={str(success).lower()} steps={steps} score={score:.3f} rewards={rewards_str}", flush=True)
+
+
+# ---------------------------------------------------------------------------
+# Observation formatting (for LLM)
+# ---------------------------------------------------------------------------
+
+def format_observation(obs_dict: Dict[str, Any], action_log: List[str] = None) -> str:
+    parts: List[str] = []
+    parts.append(f"=== DAY {obs_dict['day']} of {obs_dict.get('campaign_day_total', 14)} ===\n")
+
+    if action_log:
+        parts.append("Past actions: " + " | ".join(action_log))
+        parts.append("")
+
+    if obs_dict.get("daily_metrics"):
+        parts.append("Metrics:")
+        parts.append(f"{'ID':<10} {'Publisher':<22} {'Impressions':>12} {'Clicks':>8} {'Conversions':>12} {'Spend ($)':>10} {'CTR':>7} {'CVR':>7}")
+        for m in obs_dict["daily_metrics"]:
+            parts.append(
+                f"{m['publisher_id']:<10} {m['name']:<22} {m['impressions']:>12,} {m['clicks']:>8,} "
+                f"{m['conversions']:>12,} {m['spend']:>10,.2f} {m['ctr']:>6.2%} {m['cvr']:>6.2%}"
+            )
+        parts.append("")
+
+    if obs_dict.get("investigation_results"):
+        inv = obs_dict["investigation_results"]
+        if isinstance(inv, dict):
+            if "error" in inv:
+                parts.append(f"Investigation ERROR: {inv['error']}")
+            else:
+                parts.append(f"Investigation ({inv.get('tool', '?')}) for {inv.get('publisher_id', '?')}:")
+                for k, v in inv.items():
+                    if k not in ("tool", "publisher_id"):
+                        parts.append(f"  {k}: {v}")
+        parts.append("")
+
+    pub_status = obs_dict.get("publisher_status", {})
+    if pub_status:
+        flagged_pubs = [pid for pid, s in pub_status.items() if s == "flagged"]
+        active = [pid for pid, s in pub_status.items() if s == "active"]
+        if flagged_pubs:
+            parts.append(f"FLAGGED: {', '.join(flagged_pubs)}")
+        parts.append(f"Active publishers: {', '.join(active)}")
+
+    b = obs_dict.get("budget_status", {})
+    if b:
+        parts.append(
+            f"Budget: ${b.get('remaining',0):,.0f} remaining | "
+            f"Investigations left: {b.get('investigation_budget_remaining', 0)}"
+        )
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Action parsing (for LLM)
+# ---------------------------------------------------------------------------
+
+def parse_action(text: str) -> Dict[str, Any]:
+    match = re.search(r"```json\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if match:
+        try:
+            return json.loads(match.group(1))
+        except json.JSONDecodeError:
+            pass
+    for line in reversed(text.strip().split("\n")):
+        line = line.strip()
+        if line.startswith("{") and line.endswith("}"):
+            try:
+                return json.loads(line)
+            except json.JSONDecodeError:
+                continue
+    return {"action_type": "monitor"}
+
+
+# ---------------------------------------------------------------------------
+# LLM action
+# ---------------------------------------------------------------------------
+
+def get_llm_action(
+    client: OpenAI,
+    obs_text: str,
+    history: List[Dict[str, str]],
+) -> Optional[Dict[str, Any]]:
+    """Try to get an action from the LLM. Returns None on failure."""
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    messages.extend(history)
+    messages.append({"role": "user", "content": obs_text})
+
+    try:
+        response = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=messages,
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+        )
+        text = response.choices[0].message.content or ""
+        return parse_action(text)
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Rule-based fallback
+# ---------------------------------------------------------------------------
+
+def score_publishers(metrics_history: Dict[str, List[Dict]]) -> List[Tuple[str, float, str]]:
+    """Score each publisher's suspicion based on accumulated metrics."""
+    results = []
+    for pid, hist in metrics_history.items():
+        if len(hist) < 2:
+            continue
+        recent = hist[-3:]
+        avg_ctr = sum(h["ctr"] for h in recent) / len(recent)
+        avg_cvr = sum(h["cvr"] for h in recent) / len(recent)
+        baseline = hist[:2]
+        base_ctr = sum(h["ctr"] for h in baseline) / len(baseline)
+        base_cvr = sum(h["cvr"] for h in baseline) / len(baseline)
+
+        score = 0.0
+        fraud_type = "bot_traffic"
+
+        if base_ctr > 0:
+            ctr_rise = avg_ctr / base_ctr
+            if ctr_rise > 1.5:
+                score += 0.4
+            if ctr_rise > 2.0:
+                score += 0.3
+        if base_cvr > 0:
+            cvr_drop = avg_cvr / base_cvr
+            if cvr_drop < 0.5:
+                score += 0.3
+            if cvr_drop < 0.2:
+                score += 0.3
+        if avg_cvr > 0.04:
+            score += 0.5
+            fraud_type = "click_injection"
+        if base_ctr > 0 and base_cvr > 0:
+            ctr_rise = avg_ctr / base_ctr
+            cvr_drop = avg_cvr / base_cvr
+            if 1.2 < ctr_rise < 2.0 and 0.2 < cvr_drop < 0.6:
+                if fraud_type == "bot_traffic" and score < 0.5:
+                    fraud_type = "domain_spoofing"
+
+        if score > 0.2:
+            results.append((pid, score, fraud_type))
+
+    results.sort(key=lambda x: -x[1])
+    return results
+
+
+def get_rule_action(
+    obs_dict: Dict[str, Any],
+    metrics_history: Dict[str, List[Dict]],
+    investigated: Dict[str, List[str]],
+    flagged: set,
+) -> Dict[str, Any]:
+    """Deterministic rule-based action selection."""
+    day = obs_dict["day"]
+    budget_left = obs_dict.get("budget_status", {}).get("investigation_budget_remaining", 0)
+
+    if day <= BASELINE_DAYS:
+        return {"action_type": "monitor"}
+
+    suspects = score_publishers(metrics_history)
+    suspects = [(pid, sc, ft) for pid, sc, ft in suspects if pid not in flagged]
+
+    for pid, _, ft in suspects:
+        tools_done = investigated.get(pid, [])
+        if len(tools_done) >= 2:
+            flagged.add(pid)
+            return {
+                "action_type": "flag_fraud",
+                "publisher_id": pid,
+                "fraud_type": ft,
+                "evidence": tools_done,
+            }
+
+    if budget_left > 0 and suspects:
+        for pid, _, ft in suspects:
+            if pid in flagged:
+                continue
+            tools_done = investigated.get(pid, [])
+            tools_to_try = TOOLS_FOR.get(ft, TOOLS_FOR["bot_traffic"])
+            for tool in tools_to_try:
+                if tool not in tools_done:
+                    investigated.setdefault(pid, []).append(tool)
+                    return {
+                        "action_type": "investigate_publisher",
+                        "publisher_id": pid,
+                        "tool": tool,
+                    }
+
+    return {"action_type": "monitor"}
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    # Try to init LLM client; fall back to rule-based if it fails
+    llm_client: Optional[OpenAI] = None
+    try:
+        llm_client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+        llm_client.models.list()
+    except Exception:
+        llm_client = None
+
+    use_rules = llm_client is None
+
+    env = AdAuditEnv()
+
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+
+    # LLM state
+    history: List[Dict[str, str]] = []
+    action_log: List[str] = []
+
+    # Rule-based state
+    metrics_history: Dict[str, List[Dict]] = {}
+    investigated: Dict[str, List[str]] = {}
+    flagged: set = set()
+
+    log_start(task=TASK_NAME, env=BENCHMARK, model=MODEL_NAME if not use_rules else "rule-based")
+
+    try:
+        obs = env.reset(episode_id=TASK_NAME)
+        obs_dict = obs.model_dump()
+
+        while not obs_dict.get("done", False) and steps_taken < EPISODE_DAYS:
+            # Track metrics for rule-based fallback
+            for m in obs_dict.get("daily_metrics", []):
+                metrics_history.setdefault(m["publisher_id"], []).append(m)
+
+            action = None
+
+            if not use_rules:
+                obs_text = format_observation(obs_dict, action_log)
+                action = get_llm_action(llm_client, obs_text, history[-HISTORY_WINDOW * 2:])
+                if action is None:
+                    use_rules = True
+
+            if action is None:
+                action = get_rule_action(obs_dict, metrics_history, investigated, flagged)
+
+            # Validate action
+            try:
+                action_obj = AdAuditAction(**action)
+            except Exception:
+                action_obj = AdAuditAction(action_type="invalid")
+
+            # Build action log entry
+            log_entry = f"D{obs_dict['day']}:{action_obj.action_type}"
+            if action_obj.publisher_id:
+                log_entry += f"({action_obj.publisher_id}"
+                if action_obj.tool:
+                    log_entry += f",{action_obj.tool}"
+                if action_obj.fraud_type:
+                    log_entry += f",{action_obj.fraud_type}"
+                log_entry += ")"
+            action_log.append(log_entry)
+
+            # Update LLM history
+            if not use_rules:
+                history.append({"role": "user", "content": obs_text})
+                history.append({"role": "assistant", "content": json.dumps(action)})
+
+            # Step environment
+            obs = env.step(action_obj)
+            obs_dict = obs.model_dump()
+            steps_taken += 1
+
+            reward = obs_dict.get("reward", 0.0)
+            done = obs_dict.get("done", False)
+            error = None
+            rewards.append(reward)
+
+            action_str = json.dumps(action, separators=(",", ":"))
+            log_step(step=steps_taken, action=action_str, reward=reward, done=done, error=error)
+
+        # Final grading
+        state = env.state
+        grader = state.grader_inputs
+        score = grader.get("final_score", 0.0)
+        score = min(max(score, 0.0), 1.0)
+        success = score >= SUCCESS_SCORE_THRESHOLD
+
+    finally:
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,152 @@
+"""
+Pydantic models for the AdAudit environment.
+
+Defines Action, Observation, and State types that conform to the OpenEnv spec.
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from openenv.core.env_server.types import Action, Observation, State
+
+
+# ---------------------------------------------------------------------------
+# Action
+# ---------------------------------------------------------------------------
+
+class AdAuditAction(Action):
+    """Single discrete action the agent takes each day."""
+
+    action_type: Literal[
+        "monitor",
+        "investigate_publisher",
+        "flag_fraud",
+        "submit_report",
+        "invalid",
+    ] = Field(..., description="The type of action to take")
+
+    publisher_id: Optional[str] = Field(
+        default=None, description="Target publisher for investigate/flag actions"
+    )
+
+    # investigate_publisher
+    tool: Optional[Literal[
+        "click_timestamps",
+        "ip_distribution",
+        "device_fingerprints",
+        "referral_urls",
+        "viewability_scores",
+        "conversion_quality",
+    ]] = Field(default=None, description="Investigation tool to use")
+
+    # flag_fraud
+    fraud_type: Optional[Literal[
+        "bot_traffic",
+        "domain_spoofing",
+        "click_injection",
+    ]] = Field(default=None, description="Fraud type to flag")
+    evidence: Optional[List[str]] = Field(
+        default=None, description="List of tool names used as evidence"
+    )
+
+    # submit_report
+    summary: Optional[str] = Field(default=None)
+
+
+# ---------------------------------------------------------------------------
+# Observation helpers
+# ---------------------------------------------------------------------------
+
+class DailyPublisherMetrics(BaseModel):
+    """Traffic metrics for one publisher on one day."""
+
+    publisher_id: str
+    name: str
+    impressions: int
+    clicks: int
+    conversions: int
+    spend: float
+    ctr: float
+    cvr: float
+
+
+class BudgetStatus(BaseModel):
+    """Campaign and investigation budget snapshot."""
+
+    total_campaign_budget: float
+    spent_so_far: float
+    remaining: float
+    investigation_budget_remaining: int
+    daily_spend_rate: float
+
+
+# ---------------------------------------------------------------------------
+# Observation
+# ---------------------------------------------------------------------------
+
+class AdAuditObservation(Observation):
+    """What the agent sees after each step.
+
+    Inherits ``done``, ``reward``, and ``metadata`` from the OpenEnv
+    ``Observation`` base class.  ``reward`` carries the daily P&L.
+    """
+
+    day: int = Field(..., description="Current campaign day (1-30)")
+    campaign_day_total: int = Field(default=14)
+
+    daily_metrics: List[DailyPublisherMetrics] = Field(default_factory=list)
+    cumulative_metrics: List[DailyPublisherMetrics] = Field(default_factory=list)
+
+    trend_data: str = Field(default="", description="Trend summary")
+    investigation_results: Optional[Dict[str, Any]] = Field(
+        default=None, description="Structured metrics from investigation tool"
+    )
+    alerts: List[str] = Field(default_factory=list)
+
+    budget_status: Optional[BudgetStatus] = None
+    publisher_status: Dict[str, str] = Field(
+        default_factory=dict,
+        description="publisher_id -> active|flagged",
+    )
+
+    cumulative_reward: float = Field(default=0.0)
+    done_reason: Optional[str] = Field(default=None)
+
+
+# ---------------------------------------------------------------------------
+# State (hidden — used for grading / debugging)
+# ---------------------------------------------------------------------------
+
+class PublisherState(BaseModel):
+    """Public publisher state (visible via /state)."""
+
+    publisher_id: str
+    name: str
+    is_flagged: bool = False
+    budget_allocation: float = 0.0
+    tools_used: List[str] = Field(default_factory=list)
+    day_flagged: Optional[int] = None
+
+
+class AdAuditState(State):
+    """Full internal state for debugging and grading.
+
+    Inherits ``episode_id`` and ``step_count`` from OpenEnv ``State``.
+    """
+
+    case_id: str = ""
+    current_day: int = 0
+
+    publishers: List[PublisherState] = Field(default_factory=list)
+
+    action_history: List[Dict[str, Any]] = Field(default_factory=list)
+    daily_rewards: List[float] = Field(default_factory=list)
+    cumulative_reward: float = 0.0
+
+    investigation_budget_total: int = 0
+    investigation_budget_used: int = 0
+
+    flags_submitted: List[Dict[str, Any]] = Field(default_factory=list)
+
+    grader_inputs: Dict[str, Any] = Field(default_factory=dict)

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: Ad_Audit
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

pyproject.toml

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-Ad_Audit"
+version = "0.1.0"
+description = "Ad Audit environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m Ad_Audit.server.app
+server = "Ad_Audit.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["Ad_Audit", "Ad_Audit.server"]
+package-dir = { "Ad_Audit" = ".", "Ad_Audit.server" = "server" }

results.json

@@ -0,0 +1,7 @@
+{
+  "hard": {
+    "task_id": "hard",
+    "steps": 13,
+    "final_score": 0.5312230769230769
+  }
+}

server/Ad_Audit_environment.py

@@ -0,0 +1,527 @@
+"""
+AdAuditEnv — main environment class.
+
+Wires together publisher_engine, fraud_engine, response_generator,
+step_reward, and grader into the OpenEnv Environment interface.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+
+try:
+    from ..models import (
+        AdAuditAction,
+        AdAuditObservation,
+        AdAuditState,
+        BudgetStatus,
+        DailyPublisherMetrics,
+        PublisherState,
+    )
+    from .fraud_engine import (
+        decay_suspicion,
+        get_adaptation_stage,
+        update_suspicion,
+    )
+    from .publisher_engine import generate_daily_traffic
+    from .response_generator import (
+        generate_alerts,
+        generate_investigation_metrics,
+        generate_trend_summary,
+    )
+    from .step_reward import compute_step_reward
+    from .grader import grade_episode
+except ImportError:
+    from models import (  # type: ignore[no-redef]
+        AdAuditAction,
+        AdAuditObservation,
+        AdAuditState,
+        BudgetStatus,
+        DailyPublisherMetrics,
+        PublisherState,
+    )
+    from server.fraud_engine import (  # type: ignore[no-redef]
+        decay_suspicion,
+        get_adaptation_stage,
+        update_suspicion,
+    )
+    from server.publisher_engine import generate_daily_traffic  # type: ignore[no-redef]
+    from server.response_generator import (  # type: ignore[no-redef]
+        generate_alerts,
+        generate_investigation_metrics,
+        generate_trend_summary,
+    )
+    from server.step_reward import compute_step_reward  # type: ignore[no-redef]
+    from server.grader import grade_episode  # type: ignore[no-redef]
+
+CASES_DIR = Path(__file__).resolve().parent.parent / "cases"
+
+TASK_MAP = {
+    "easy": "easy.json",
+    "medium": "medium.json",
+    "hard": "hard.json",
+}
+
+EPISODE_DAYS = 14
+
+
+class _PubInternal:
+    """Hidden per-publisher state (not exposed via /state)."""
+    __slots__ = (
+        "is_fraudulent", "fraud_type", "suspicion_level", "adaptation_stage",
+        "total_fraudulent_spend", "total_legitimate_spend", "total_legitimate_revenue",
+    )
+
+    def __init__(self, is_fraudulent: bool = False, fraud_type: str = None):
+        self.is_fraudulent = is_fraudulent
+        self.fraud_type = fraud_type
+        self.suspicion_level = 0.0
+        self.adaptation_stage = "normal"
+        self.total_fraudulent_spend = 0.0
+        self.total_legitimate_spend = 0.0
+        self.total_legitimate_revenue = 0.0
+
+
+class AdAuditEnv(Environment[AdAuditAction, AdAuditObservation, AdAuditState]):
+    """OpenEnv-compatible RL environment for ad fraud detection."""
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    @classmethod
+    def get_tasks(cls) -> List[str]:
+        return list(TASK_MAP.keys())
+
+    _TASK_CYCLE = ["easy", "medium", "hard"]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._case: Dict[str, Any] = {}
+        self._state = AdAuditState()
+        self._pub_cfgs: Dict[str, Dict[str, Any]] = {}
+        self._pub_names: Dict[str, str] = {}
+        self._pub_internal: Dict[str, _PubInternal] = {}
+        self._daily_logs: Dict[str, List[Dict[str, Any]]] = {}
+        self._step_action: Optional[AdAuditAction] = None
+        self._cycle_index: int = 0
+        self._invalid_action: bool = False
+
+    # ------------------------------------------------------------------
+    # reset
+    # ------------------------------------------------------------------
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> AdAuditObservation:
+        task_id = kwargs.get("task_id") or episode_id
+        if not task_id:
+            task_id = self._TASK_CYCLE[self._cycle_index % len(self._TASK_CYCLE)]
+            self._cycle_index += 1
+        case_file = CASES_DIR / TASK_MAP.get(task_id, f"{task_id}.json")
+        with open(case_file) as f:
+            self._case = json.load(f)
+
+        campaign = self._case["campaign"]
+        publishers = self._case["publishers"]
+
+        pub_states: List[PublisherState] = []
+        self._pub_cfgs = {}
+        self._pub_names = {}
+        self._pub_internal = {}
+        self._daily_logs = {}
+
+        for pub_id, cfg in publishers.items():
+            self._pub_cfgs[pub_id] = cfg
+            self._pub_names[pub_id] = cfg.get("name", pub_id)
+            self._daily_logs[pub_id] = []
+
+            pub_states.append(PublisherState(
+                publisher_id=pub_id,
+                name=cfg.get("name", pub_id),
+                budget_allocation=cfg.get("budget_allocation", 1.0 / len(publishers)),
+            ))
+
+            self._pub_internal[pub_id] = _PubInternal(
+                is_fraudulent=cfg.get("is_fraudulent", False),
+                fraud_type=cfg.get("fraud_type"),
+            )
+
+        self._state = AdAuditState(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+            case_id=self._case.get("case_id", task_id),
+            current_day=0,
+            publishers=pub_states,
+            investigation_budget_total=campaign.get("investigation_budget", 8),
+            investigation_budget_used=0,
+        )
+
+        self._step_action = None
+        self._invalid_action = False
+        return self._advance_day()
+
+    # ------------------------------------------------------------------
+    # step
+    # ------------------------------------------------------------------
+
+    def step(
+        self,
+        action: AdAuditAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> AdAuditObservation:
+        if self._state.current_day >= EPISODE_DAYS:
+            return self._finalize("Campaign ended.")
+
+        investigation_result: Optional[Dict[str, Any]] = None
+        self._invalid_action = False
+        at = action.action_type
+        self._state.action_history.append(action.model_dump(exclude_none=True))
+        self._step_action = action
+
+        if at == "monitor":
+            pass
+        elif at == "investigate_publisher":
+            investigation_result = self._handle_investigate(action)
+            if investigation_result and "error" in investigation_result:
+                self._invalid_action = True
+        elif at == "flag_fraud":
+            ps = self._get_pub_state(action.publisher_id)
+            if ps is None or ps.is_flagged or not action.fraud_type:
+                self._invalid_action = True
+            else:
+                self._handle_flag_fraud(action)
+        elif at == "submit_report":
+            return self._finalize("Agent submitted report.")
+        else:
+            self._invalid_action = True
+
+        return self._advance_day(investigation_result=investigation_result)
+
+    # ------------------------------------------------------------------
+    # state property
+    # ------------------------------------------------------------------
+
+    @property
+    def state(self) -> AdAuditState:
+        return self._state
+
+    # ------------------------------------------------------------------
+    # Action handlers
+    # ------------------------------------------------------------------
+
+    def _handle_investigate(self, action: AdAuditAction) -> Optional[Dict[str, Any]]:
+        pub_id = action.publisher_id
+        tool = action.tool
+        if not pub_id or not tool:
+            return {"error": "publisher_id and tool are required"}
+
+        ps = self._get_pub_state(pub_id)
+        if ps is None:
+            valid = [p.publisher_id for p in self._state.publishers]
+            return {"error": f"unknown publisher_id: {pub_id}. Valid IDs: {valid}"}
+
+        if ps.is_flagged:
+            return {"error": f"{pub_id} is already flagged."}
+
+        budget_remaining = (
+            self._state.investigation_budget_total
+            - self._state.investigation_budget_used
+        )
+        if budget_remaining <= 0:
+            return {"error": "no investigation budget remaining"}
+
+        self._state.investigation_budget_used += 1
+
+        cfg = self._pub_cfgs.get(pub_id, {})
+        hi = self._pub_internal[pub_id]
+
+        if tool not in ps.tools_used:
+            ps.tools_used.append(tool)
+
+        if hi.is_fraudulent:
+            hi.suspicion_level = update_suspicion(
+                hi.suspicion_level, tool, cfg.get("suspicion_reactivity", 1.0),
+            )
+            hi.adaptation_stage = get_adaptation_stage(hi.suspicion_level)
+
+        return generate_investigation_metrics(
+            case_id=self._state.case_id,
+            publisher_id=pub_id,
+            publisher_cfg=cfg,
+            tool_name=tool,
+            adaptation_stage=hi.adaptation_stage,
+        )
+
+    def _handle_flag_fraud(self, action: AdAuditAction) -> None:
+        pub_id = action.publisher_id
+        ps = self._get_pub_state(pub_id)
+        hi = self._pub_internal[pub_id]
+
+        ps.is_flagged = True
+        ps.day_flagged = self._state.current_day + 1
+
+        is_correct = hi.is_fraudulent
+        type_correct = (action.fraud_type == hi.fraud_type) if is_correct else False
+
+        self._state.flags_submitted.append({
+            "publisher_id": pub_id,
+            "fraud_type": action.fraud_type,
+            "evidence": action.evidence or [],
+            "day": self._state.current_day + 1,
+            "correct": is_correct,
+            "type_correct": type_correct,
+        })
+
+    # ------------------------------------------------------------------
+    # Day advancement
+    # ------------------------------------------------------------------
+
+    def _advance_day(
+        self,
+        investigation_result: Optional[Dict[str, Any]] = None,
+    ) -> AdAuditObservation:
+        self._state.current_day += 1
+        self._state.step_count = self._state.current_day
+        day = self._state.current_day
+
+        # Decay suspicion for publishers NOT investigated today
+        investigated_today = set()
+        if self._state.action_history:
+            last = self._state.action_history[-1]
+            if last.get("action_type") == "investigate_publisher" and last.get("publisher_id"):
+                investigated_today.add(last["publisher_id"])
+
+        for ps in self._state.publishers:
+            hi = self._pub_internal[ps.publisher_id]
+            if hi.is_fraudulent and ps.publisher_id not in investigated_today:
+                hi.suspicion_level = decay_suspicion(hi.suspicion_level)
+                hi.adaptation_stage = get_adaptation_stage(hi.suspicion_level)
+
+        # Generate traffic
+        daily_traffic: List[Dict[str, Any]] = []
+        daily_metrics: List[DailyPublisherMetrics] = []
+        campaign = self._case["campaign"]
+        benchmarks = campaign.get("industry_benchmarks", {})
+
+        daily_fraud_spend = 0.0
+        for ps in self._state.publishers:
+            cfg = self._pub_cfgs.get(ps.publisher_id, {})
+            hi = self._pub_internal[ps.publisher_id]
+            traffic = generate_daily_traffic(
+                day=day, publisher_cfg=cfg,
+                budget_allocation=ps.budget_allocation,
+                adaptation_stage=hi.adaptation_stage,
+                is_paused=ps.is_flagged,
+            )
+            daily_traffic.append(traffic)
+            self._daily_logs[ps.publisher_id].append(traffic)
+
+            hi.total_legitimate_spend += traffic["legitimate_spend"]
+            hi.total_fraudulent_spend += traffic["fraudulent_spend"]
+            hi.total_legitimate_revenue += traffic["legitimate_revenue"]
+
+            if hi.is_fraudulent and not ps.is_flagged:
+                daily_fraud_spend += traffic["fraudulent_spend"]
+
+            daily_metrics.append(DailyPublisherMetrics(
+                publisher_id=ps.publisher_id, name=ps.name,
+                impressions=traffic["impressions"], clicks=traffic["clicks"],
+                conversions=traffic["conversions"], spend=traffic["spend"],
+                ctr=traffic["ctr"], cvr=traffic["cvr"],
+            ))
+
+        # --- Compute step reward ---
+        action = self._step_action
+        total_budget = campaign["total_budget"]
+
+        if action is None:
+            step_reward = 0.0
+        elif self._invalid_action:
+            step_reward = compute_step_reward(
+                action_type="invalid",
+                daily_fraud_spend=daily_fraud_spend,
+                total_budget=total_budget,
+                day=day,
+                episode_days=EPISODE_DAYS,
+            )
+        elif action.action_type == "flag_fraud":
+            last_flag = self._state.flags_submitted[-1] if self._state.flags_submitted else {}
+            step_reward = compute_step_reward(
+                action_type="flag_fraud",
+                flag_correct=last_flag.get("correct"),
+                flag_type_correct=last_flag.get("type_correct"),
+                daily_fraud_spend=daily_fraud_spend,
+                total_budget=total_budget,
+                day=day,
+                episode_days=EPISODE_DAYS,
+            )
+        elif action.action_type == "investigate_publisher":
+            pub_cfg = self._pub_cfgs.get(action.publisher_id, {})
+            step_reward = compute_step_reward(
+                action_type="investigate_publisher",
+                publisher_cfg=pub_cfg,
+                daily_fraud_spend=daily_fraud_spend,
+                total_budget=total_budget,
+                day=day,
+                episode_days=EPISODE_DAYS,
+            )
+        else:
+            step_reward = compute_step_reward(
+                action_type=action.action_type,
+                daily_fraud_spend=daily_fraud_spend,
+                total_budget=total_budget,
+                day=day,
+                episode_days=EPISODE_DAYS,
+            )
+
+        # Trend + alerts
+        trend_data = ""  # TODO: generate_trend_summary(self._daily_logs, self._pub_names, day)
+        raw_metrics = [
+            {"publisher_id": m.publisher_id, "ctr": m.ctr, "cvr": m.cvr,
+             "impressions": m.impressions, "clicks": m.clicks}
+            for m in daily_metrics
+        ]
+        alerts = []  # TODO: generate_alerts(raw_metrics, benchmarks, self._pub_names)
+
+        cumulative_metrics = self._compute_cumulative_metrics()
+
+        total_spend = sum(
+            hi.total_legitimate_spend + hi.total_fraudulent_spend
+            for hi in self._pub_internal.values()
+        )
+        budget_status = BudgetStatus(
+            total_campaign_budget=campaign["total_budget"],
+            spent_so_far=round(total_spend, 2),
+            remaining=round(campaign["total_budget"] - total_spend, 2),
+            investigation_budget_remaining=(
+                self._state.investigation_budget_total
+                - self._state.investigation_budget_used
+            ),
+            daily_spend_rate=round(total_spend / day, 2) if day > 0 else 0.0,
+        )
+
+        pub_status = {
+            ps.publisher_id: ("flagged" if ps.is_flagged else "active")
+            for ps in self._state.publishers
+        }
+
+        # Termination
+        done = False
+        done_reason: Optional[str] = None
+
+        if day >= EPISODE_DAYS:
+            done = True
+            done_reason = f"Campaign ended (day {EPISODE_DAYS})."
+        elif budget_status.remaining <= 0:
+            done = True
+            done_reason = "Campaign budget exhausted."
+
+        # On episode end, compute grader (stored separately, not in step reward)
+        if done:
+            self._state.grader_inputs = grade_episode(
+                self._build_grader_state(), self._case,
+            )
+
+        step_reward = round(max(0.0, min(1.0, step_reward)), 4)
+        self._state.daily_rewards.append(step_reward)
+        self._state.cumulative_reward += step_reward
+
+        return self._apply_transform(AdAuditObservation(
+            day=day,
+            campaign_day_total=EPISODE_DAYS,
+            daily_metrics=daily_metrics,
+            cumulative_metrics=cumulative_metrics,
+            trend_data=trend_data,
+            investigation_results=investigation_result,
+            alerts=alerts,
+            budget_status=budget_status,
+            publisher_status=pub_status,
+            cumulative_reward=round(self._state.cumulative_reward, 4),
+            done=done,
+            done_reason=done_reason,
+            reward=step_reward,
+        ))
+
+    # ------------------------------------------------------------------
+    # Finalize
+    # ------------------------------------------------------------------
+
+    def _finalize(self, reason: str) -> AdAuditObservation:
+        self._state.grader_inputs = grade_episode(
+            self._build_grader_state(), self._case,
+        )
+        grader_score = self._state.grader_inputs.get("final_score", 0.0)
+
+        step_reward = grader_score
+        self._state.daily_rewards.append(step_reward)
+        self._state.cumulative_reward += step_reward
+
+        return AdAuditObservation(
+            day=self._state.current_day,
+            campaign_day_total=EPISODE_DAYS,
+            trend_data=f"Episode complete. Grader score: {grader_score:.4f}",
+            done=True,
+            done_reason=reason,
+            reward=step_reward,
+            cumulative_reward=round(self._state.cumulative_reward, 4),
+            publisher_status={
+                ps.publisher_id: ("flagged" if ps.is_flagged else "active")
+                for ps in self._state.publishers
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _get_pub_state(self, pub_id: Optional[str]) -> Optional[PublisherState]:
+        for ps in self._state.publishers:
+            if ps.publisher_id == pub_id:
+                return ps
+        return None
+
+    def _build_grader_state(self) -> Dict[str, Any]:
+        """Build the state dict the grader expects, including hidden fields."""
+        state_dict = self._state.model_dump()
+        # Enrich publisher entries with hidden internal state for grading
+        for pub_dict in state_dict["publishers"]:
+            pub_id = pub_dict["publisher_id"]
+            hi = self._pub_internal[pub_id]
+            pub_dict["is_fraudulent"] = hi.is_fraudulent
+            pub_dict["fraud_type"] = hi.fraud_type
+            pub_dict["suspicion_level"] = hi.suspicion_level
+            pub_dict["total_fraudulent_spend"] = hi.total_fraudulent_spend
+            pub_dict["total_legitimate_spend"] = hi.total_legitimate_spend
+        return state_dict
+
+    def _compute_cumulative_metrics(self) -> List[DailyPublisherMetrics]:
+        result = []
+        for ps in self._state.publishers:
+            logs = self._daily_logs.get(ps.publisher_id, [])
+            if not logs:
+                continue
+            total_imp = sum(d["impressions"] for d in logs)
+            total_clicks = sum(d["clicks"] for d in logs)
+            total_conv = sum(d["conversions"] for d in logs)
+            total_spend = sum(d["spend"] for d in logs)
+            ctr = total_clicks / total_imp if total_imp > 0 else 0.0
+            cvr = total_conv / total_clicks if total_clicks > 0 else 0.0
+            result.append(DailyPublisherMetrics(
+                publisher_id=ps.publisher_id, name=ps.name,
+                impressions=total_imp, clicks=total_clicks,
+                conversions=total_conv, spend=round(total_spend, 2),
+                ctr=round(ctr, 4), cvr=round(cvr, 4),
+            ))
+        return result
+
+
+# Alias used by app.py and server/__init__.py
+AdAuditEnvironment = AdAuditEnv

server/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Ad Audit environment server components."""
+
+try:
+    from .Ad_Audit_environment import AdAuditEnvironment
+except ImportError:
+    from server.Ad_Audit_environment import AdAuditEnvironment  # type: ignore[no-redef]
+
+__all__ = ["AdAuditEnvironment"]

server/app.py

@@ -0,0 +1,84 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Ad Audit Environment.
+
+This module creates an HTTP server that exposes the AdAuditEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+import os
+
+os.environ.setdefault("ENABLE_WEB_INTERFACE", "true")
+os.environ.setdefault("ENV_README_PATH", os.path.join(os.path.dirname(os.path.dirname(__file__)), "README.md"))
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import AdAuditAction, AdAuditObservation
+    from .Ad_Audit_environment import AdAuditEnvironment
+except (ImportError, ModuleNotFoundError):
+    from models import AdAuditAction, AdAuditObservation
+    from server.Ad_Audit_environment import AdAuditEnvironment
+
+
+# Create the app with web interface and README integration
+app = create_app(
+    AdAuditEnvironment,
+    AdAuditAction,
+    AdAuditObservation,
+    env_name="Ad_Audit",
+    max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        uv run --project . server --port 8001
+        python -m Ad_Audit.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+
+    For production deployments, consider using uvicorn directly with
+    multiple workers:
+        uvicorn Ad_Audit.server.app:app --workers 4
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/fraud_engine.py

@@ -0,0 +1,84 @@
+"""
+Fraud engine — suspicion tracking and fraud intensity for adaptive publishers.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+# ── Suspicion tracking ────────────────────────────────────────────────────
+
+def update_suspicion(
+    current_level: float,
+    tool: str,
+    reactivity: float,
+) -> float:
+    """Increase suspicion after an investigation tool is used on a fraudster.
+
+    Each tool adds a fixed bump scaled by the publisher's reactivity.
+    """
+    bump = {
+        "click_timestamps": 0.15,
+        "ip_distribution": 0.12,
+        "device_fingerprints": 0.10,
+        "referral_urls": 0.10,
+        "viewability_scores": 0.08,
+        "conversion_quality": 0.10,
+    }.get(tool, 0.10)
+    return min(1.0, current_level + bump * reactivity)
+
+
+def decay_suspicion(level: float, rate: float = 0.05) -> float:
+    """Decay suspicion each day a fraudster is NOT investigated."""
+    return max(0.0, level - rate)
+
+
+def get_adaptation_stage(suspicion_level: float) -> str:
+    """Map suspicion level to an adaptation stage for response generation."""
+    if suspicion_level >= 0.8:
+        return "dark"
+    if suspicion_level >= 0.5:
+        return "covering_tracks"
+    if suspicion_level >= 0.25:
+        return "cautious"
+    return "normal"
+
+
+# ── Fraud intensity ───────────────────────────────────────────────────────
+
+def compute_fraud_intensity(
+    day: int,
+    fraud_schedule: Dict[str, Any],
+    adaptation_stage: str,
+) -> float:
+    """Compute how aggressively a publisher is committing fraud on a given day.
+
+    ``fraud_schedule`` comes from the case profile and has:
+        start_day: int — first day fraud begins
+        ramp_days: int — days to ramp from 0 → peak
+        peak_intensity: float — maximum multiplier on legitimate traffic
+    """
+    start = fraud_schedule.get("start_day", 1)
+    ramp = fraud_schedule.get("ramp_days", 3)
+    peak = fraud_schedule.get("peak_intensity", 1.0)
+
+    if day < start:
+        return 0.0
+
+    # Ramp up
+    days_active = day - start
+    if ramp > 0 and days_active < ramp:
+        base = peak * (days_active / ramp)
+    else:
+        base = peak
+
+    # Adaptation dampening — fraudster backs off when suspicion rises
+    stage_mult = {
+        "normal": 1.0,
+        "cautious": 0.7,
+        "covering_tracks": 0.4,
+        "dark": 0.05,
+    }.get(adaptation_stage, 1.0)
+
+    return base * stage_mult

server/grader.py

@@ -0,0 +1,134 @@
+"""Episode-end grader [0, 1].
+
+Three components:
+  1. Fraud detection accuracy  (weight 0.50)
+  2. Detection timeliness      (weight 0.30)
+  3. Investigation efficiency   (weight 0.20)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+
+def grade_episode(
+    state_dict: Dict[str, Any],
+    case_dict: Dict[str, Any],
+) -> Dict:
+    """Return grading breakdown and final score in [0, 1].
+
+    Args:
+        state_dict: Result of _build_grader_state() — enriched AdAuditState dict.
+        case_dict: The raw case JSON (with publisher configs).
+    """
+    publishers = state_dict.get("publishers", [])
+    flags_submitted = state_dict.get("flags_submitted", [])
+    investigation_budget_used = state_dict.get("investigation_budget_used", 0)
+    investigation_budget_total = state_dict.get("investigation_budget_total", 0)
+
+    # Derive fraud info from the enriched publisher entries
+    fraudulent_publishers: List[str] = []
+    fraud_types: Dict[str, str] = {}
+    publisher_internals: Dict[str, Dict] = {}
+    tools_used_per_publisher: Dict[str, List[str]] = {}
+
+    case_publishers = case_dict.get("publishers", {})
+
+    for pub in publishers:
+        pid = pub["publisher_id"]
+        tools_used_per_publisher[pid] = pub.get("tools_used", [])
+
+        if pub.get("is_fraudulent"):
+            fraudulent_publishers.append(pid)
+            fraud_types[pid] = pub.get("fraud_type", "")
+
+            # Get fraud_start_day from case config's fraud_schedule
+            cfg = case_publishers.get(pid, {})
+            fraud_schedule = cfg.get("fraud_schedule", {})
+            publisher_internals[pid] = {
+                "fraud_start_day": fraud_schedule.get("start_day", 1),
+            }
+
+    num_fraudulent = len(fraudulent_publishers)
+    if num_fraudulent == 0:
+        return {
+            "accuracy": 1.0,
+            "timeliness": 1.0,
+            "efficiency": 1.0,
+            "final_score": 1.0,
+            "num_fraudulent": 0,
+            "num_flagged_correct": 0,
+            "num_false_positives": 0,
+        }
+
+    # Build lookup of flags by publisher_id
+    flag_lookup: Dict[str, Dict] = {}
+    for f in flags_submitted:
+        flag_lookup[f["publisher_id"]] = f
+
+    # Count false positives
+    flagged_ids = {f["publisher_id"] for f in flags_submitted}
+    false_positives = [pid for pid in flagged_ids if pid not in fraudulent_publishers]
+    num_false_positives = len(false_positives)
+
+    # ── 1. Fraud Detection Accuracy ─────────────────────────────────────
+    accuracy = 0.0
+    for pid in fraudulent_publishers:
+        if pid in flag_lookup:
+            if flag_lookup[pid].get("type_correct"):
+                accuracy += 1.0 / num_fraudulent
+            else:
+                accuracy += 0.5 / num_fraudulent
+    # Penalty for false positives
+    accuracy -= num_false_positives * (0.5 / num_fraudulent)
+    accuracy = max(0.0, min(1.0, accuracy))
+
+    # ── 2. Detection Timeliness ─────────────────────────────────────────
+    timeliness_scores = []
+    for pid in fraudulent_publishers:
+        internal = publisher_internals.get(pid, {})
+        fraud_start = internal.get("fraud_start_day", 1)
+        if pid in flag_lookup:
+            day_flagged = flag_lookup[pid].get("day", 14)
+            denom = 14 - fraud_start
+            if denom <= 0:
+                t = 1.0
+            else:
+                t = 1.0 - (day_flagged - fraud_start) / denom
+            timeliness_scores.append(max(0.0, min(1.0, t)))
+        else:
+            timeliness_scores.append(0.0)
+    timeliness = sum(timeliness_scores) / len(timeliness_scores) if timeliness_scores else 0.0
+
+    # ── 3. Investigation Efficiency ─────────────────────────────────────
+    total = investigation_budget_used
+    useful = 0
+    for pid in fraudulent_publishers:
+        useful += len(tools_used_per_publisher.get(pid, []))
+
+    if total > 0:
+        information_value = useful / total
+    else:
+        information_value = 0.0
+
+    if investigation_budget_total > 0:
+        budget_efficiency = 1.0 - (total / investigation_budget_total)
+    else:
+        budget_efficiency = 1.0
+
+    fp_penalty = num_false_positives * 0.2
+    efficiency = 0.5 * information_value + 0.3 * budget_efficiency - fp_penalty
+    efficiency = max(0.0, min(1.0, efficiency))
+
+    # ── Final Score ─────────────────────────────────────────────────────
+    final = min(1.0, 0.50 * accuracy + 0.30 * timeliness + 0.20 * efficiency)
+
+    return {
+        "accuracy": round(accuracy, 4),
+        "timeliness": round(timeliness, 4),
+        "efficiency": round(efficiency, 4),
+        "final_score": round(final, 4),
+        "num_fraudulent": num_fraudulent,
+        "num_flagged_correct": sum(1 for pid in fraudulent_publishers if pid in flag_lookup),
+        "num_false_positives": num_false_positives,
+    }

server/publisher_engine.py

@@ -0,0 +1,103 @@
+"""
+Publisher engine — per-publisher traffic generation each day.
+
+All randomness is pre-baked into ``day_factors`` and ``noise_factors``
+arrays in the case profile, ensuring full determinism.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .fraud_engine import compute_fraud_intensity
+
+
+def generate_daily_traffic(
+    day: int,
+    publisher_cfg: Dict[str, Any],
+    budget_allocation: float,
+    adaptation_stage: str,
+    is_paused: bool,
+) -> Dict[str, Any]:
+    """Generate one day of traffic for a single publisher.
+
+    Returns a dict with keys:
+        impressions, clicks, conversions, spend,
+        ctr, cvr,
+        legitimate_spend, fraudulent_spend, legitimate_revenue
+    """
+    if is_paused:
+        return _zero_traffic()
+
+    day_idx = day - 1  # 0-indexed into factor arrays
+    day_factors = publisher_cfg.get("day_factors", [1.0] * 30)
+    noise_factors = publisher_cfg.get("noise_factors", [1.0] * 30)
+
+    day_factor = day_factors[day_idx] if day_idx < len(day_factors) else 1.0
+    noise_factor = noise_factors[day_idx] if day_idx < len(noise_factors) else 1.0
+
+    base_rate: float = publisher_cfg["base_traffic_rate"]
+    true_ctr: float = publisher_cfg["true_ctr"]
+    true_cvr: float = publisher_cfg["true_cvr"]
+    cpm_rate: float = publisher_cfg.get("cpm_rate", 2.0)
+    conversion_value: float = publisher_cfg.get("conversion_value", 10.0)
+
+    # --- Legitimate traffic ---
+    legit_impressions = base_rate * budget_allocation * day_factor * noise_factor
+    legit_clicks = legit_impressions * true_ctr * noise_factor
+    legit_conversions = legit_clicks * true_cvr * noise_factor
+    legit_spend = legit_impressions * cpm_rate / 1000.0
+    legit_revenue = legit_conversions * conversion_value
+
+    # --- Fraudulent traffic (only for fraudulent publishers) ---
+    fraud_impressions = 0.0
+    fraud_clicks = 0.0
+    fraud_conversions = 0.0
+    fraud_spend = 0.0
+
+    if publisher_cfg.get("is_fraudulent", False):
+        fraud_schedule = publisher_cfg.get("fraud_schedule", {})
+        if fraud_schedule:
+            intensity = compute_fraud_intensity(day, fraud_schedule, adaptation_stage)
+            if intensity > 0:
+                fake_ctr = publisher_cfg.get("fake_ctr", 0.045)
+                fake_cvr = publisher_cfg.get("fake_cvr", 0.001)
+
+                fraud_impressions = legit_impressions * intensity
+                fraud_clicks = fraud_impressions * fake_ctr
+                fraud_conversions = fraud_clicks * fake_cvr
+                fraud_spend = fraud_impressions * cpm_rate / 1000.0
+
+    total_impressions = int(round(legit_impressions + fraud_impressions))
+    total_clicks = int(round(legit_clicks + fraud_clicks))
+    total_conversions = int(round(legit_conversions + fraud_conversions))
+    total_spend = legit_spend + fraud_spend
+
+    ctr = total_clicks / total_impressions if total_impressions > 0 else 0.0
+    cvr = total_conversions / total_clicks if total_clicks > 0 else 0.0
+
+    return {
+        "impressions": total_impressions,
+        "clicks": total_clicks,
+        "conversions": total_conversions,
+        "spend": round(total_spend, 2),
+        "ctr": round(ctr, 4),
+        "cvr": round(cvr, 4),
+        "legitimate_spend": round(legit_spend, 2),
+        "fraudulent_spend": round(fraud_spend, 2),
+        "legitimate_revenue": round(legit_revenue, 2),
+    }
+
+
+def _zero_traffic() -> Dict[str, Any]:
+    return {
+        "impressions": 0,
+        "clicks": 0,
+        "conversions": 0,
+        "spend": 0.0,
+        "ctr": 0.0,
+        "cvr": 0.0,
+        "legitimate_spend": 0.0,
+        "fraudulent_spend": 0.0,
+        "legitimate_revenue": 0.0,
+    }

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+

server/response_generator.py

@@ -0,0 +1,344 @@
+"""Investigation tool response generator.
+
+Returns structured numerical metrics deterministically via SHA256 seeding.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Dict
+
+# ── Legitimate metric ranges ────────────────────────────────────────────────
+
+LEGIT_RANGES: Dict[str, Dict[str, tuple]] = {
+    "click_timestamps": {
+        "avg_interval_seconds": (30.0, 90.0),
+        "interval_std_dev": (15.0, 45.0),
+        "pct_clicks_2am_5am": (0.02, 0.08),
+        "weekday_weekend_ratio": (1.2, 2.5),
+        "pct_sub_second_pairs": (0.0, 0.02),
+        "hourly_entropy": (3.0, 3.8),
+    },
+    "ip_distribution": {
+        "unique_ips_per_1000_clicks": (600.0, 950.0),
+        "top_ip_pct": (0.5, 3.0),
+        "pct_datacenter_ips": (2.0, 8.0),
+        "pct_residential_ips": (85.0, 95.0),
+        "country_entropy": (1.5, 3.0),
+        "pct_ip_subnet_collision": (1.0, 5.0),
+    },
+    "device_fingerprints": {
+        "unique_fps_per_1000_clicks": (700.0, 950.0),
+        "top_fp_pct": (0.3, 2.0),
+        "pct_headless_browser": (0.0, 0.5),
+        "avg_screen_resolutions": (8.0, 25.0),
+        "pct_mismatched_timezone_ip": (1.0, 5.0),
+        "os_entropy": (1.5, 2.5),
+    },
+    "referral_urls": {
+        "pct_direct_navigation": (15.0, 40.0),
+        "pct_referral_domain_mismatch": (1.0, 5.0),
+        "unique_referral_domains": (50.0, 200.0),
+        "pct_referral_chain_length_gt_2": (1.0, 5.0),
+        "referral_domain_entropy": (3.0, 4.5),
+    },
+    "viewability_scores": {
+        "pct_in_viewport_gt_1s": (60.0, 85.0),
+        "avg_viewport_dwell_seconds": (3.0, 12.0),
+        "pct_zero_pixel_ads": (0.0, 0.5),
+        "pct_stacked_ads": (0.0, 1.0),
+        "avg_focus_time_seconds": (5.0, 20.0),
+        "pct_mouse_nearby": (30.0, 60.0),
+    },
+    "conversion_quality": {
+        "click_to_conversion_seconds_mean": (120.0, 1800.0),
+        "conversion_rate": (1.0, 8.0),
+        "pct_bounce_after_click": (30.0, 55.0),
+        "avg_pages_per_session": (2.5, 6.0),
+        "pct_prior_engagement": (20.0, 50.0),
+        "pct_last_click_attributed": (40.0, 70.0),
+    },
+}
+
+# ── Fraud metric ranges ─────────────────────────────────────────────────────
+# fraud_type -> adaptation_stage -> tool -> metric -> (lo, hi)
+# Only distinctive signals are defined; unlisted combos fall through to LEGIT.
+
+FRAUD_RANGES: Dict[str, Dict[str, Dict[str, Dict[str, tuple]]]] = {
+    "bot_traffic": {
+        "normal": {
+            "click_timestamps": {
+                "avg_interval_seconds": (2.0, 5.0),
+                "interval_std_dev": (0.5, 2.0),
+                "pct_clicks_2am_5am": (0.20, 0.45),
+                "pct_sub_second_pairs": (0.10, 0.35),
+                "hourly_entropy": (1.0, 2.0),
+            },
+            "ip_distribution": {
+                "unique_ips_per_1000_clicks": (50.0, 200.0),
+                "top_ip_pct": (10.0, 35.0),
+                "pct_datacenter_ips": (60.0, 90.0),
+                "pct_residential_ips": (10.0, 35.0),
+                "pct_ip_subnet_collision": (20.0, 50.0),
+            },
+            "device_fingerprints": {
+                "unique_fps_per_1000_clicks": (20.0, 100.0),
+                "top_fp_pct": (15.0, 45.0),
+                "pct_headless_browser": (30.0, 80.0),
+                "pct_mismatched_timezone_ip": (15.0, 40.0),
+                "os_entropy": (0.3, 0.8),
+            },
+            "referral_urls": {
+                "pct_direct_navigation": (60.0, 90.0),
+                "unique_referral_domains": (3.0, 15.0),
+                "referral_domain_entropy": (0.5, 1.5),
+            },
+            "viewability_scores": {
+                "pct_in_viewport_gt_1s": (10.0, 30.0),
+                "avg_viewport_dwell_seconds": (0.2, 1.5),
+                "avg_focus_time_seconds": (0.1, 1.0),
+                "pct_mouse_nearby": (0.0, 5.0),
+            },
+            "conversion_quality": {
+                "conversion_rate": (0.0, 0.1),
+                "pct_bounce_after_click": (85.0, 99.0),
+                "avg_pages_per_session": (1.0, 1.2),
+                "pct_prior_engagement": (0.0, 2.0),
+            },
+        },
+        "cautious": {
+            "click_timestamps": {
+                "avg_interval_seconds": (8.0, 20.0),
+                "interval_std_dev": (3.0, 10.0),
+                "pct_clicks_2am_5am": (0.10, 0.25),
+                "pct_sub_second_pairs": (0.05, 0.15),
+                "hourly_entropy": (2.0, 2.8),
+            },
+            "ip_distribution": {
+                "unique_ips_per_1000_clicks": (200.0, 400.0),
+                "top_ip_pct": (5.0, 15.0),
+                "pct_datacenter_ips": (30.0, 55.0),
+                "pct_residential_ips": (40.0, 65.0),
+                "pct_ip_subnet_collision": (10.0, 25.0),
+            },
+            "device_fingerprints": {
+                "unique_fps_per_1000_clicks": (200.0, 450.0),
+                "top_fp_pct": (5.0, 15.0),
+                "pct_headless_browser": (10.0, 30.0),
+                "pct_mismatched_timezone_ip": (8.0, 20.0),
+                "os_entropy": (0.8, 1.3),
+            },
+            "referral_urls": {
+                "pct_direct_navigation": (40.0, 65.0),
+                "unique_referral_domains": (15.0, 40.0),
+                "referral_domain_entropy": (1.5, 2.5),
+            },
+            "viewability_scores": {
+                "pct_in_viewport_gt_1s": (25.0, 45.0),
+                "avg_viewport_dwell_seconds": (1.0, 3.0),
+                "avg_focus_time_seconds": (1.0, 3.0),
+                "pct_mouse_nearby": (5.0, 15.0),
+            },
+            "conversion_quality": {
+                "conversion_rate": (0.1, 0.5),
+                "pct_bounce_after_click": (70.0, 85.0),
+                "avg_pages_per_session": (1.2, 1.8),
+                "pct_prior_engagement": (2.0, 8.0),
+            },
+        },
+        "covering_tracks": {
+            "click_timestamps": {
+                "avg_interval_seconds": (18.0, 35.0),
+                "interval_std_dev": (8.0, 18.0),
+                "pct_clicks_2am_5am": (0.06, 0.12),
+                "pct_sub_second_pairs": (0.02, 0.06),
+                "hourly_entropy": (2.5, 3.2),
+            },
+            "ip_distribution": {
+                "unique_ips_per_1000_clicks": (400.0, 600.0),
+                "top_ip_pct": (3.0, 8.0),
+                "pct_datacenter_ips": (12.0, 25.0),
+                "pct_residential_ips": (65.0, 82.0),
+                "pct_ip_subnet_collision": (5.0, 12.0),
+            },
+            "device_fingerprints": {
+                "unique_fps_per_1000_clicks": (450.0, 650.0),
+                "top_fp_pct": (2.0, 6.0),
+                "pct_headless_browser": (2.0, 8.0),
+                "pct_mismatched_timezone_ip": (4.0, 10.0),
+                "os_entropy": (1.2, 1.8),
+            },
+            "conversion_quality": {
+                "conversion_rate": (0.5, 1.5),
+                "pct_bounce_after_click": (55.0, 70.0),
+                "avg_pages_per_session": (1.5, 2.5),
+            },
+        },
+        "dark": {},  # no fraud signals — looks legit
+    },
+    "domain_spoofing": {
+        "normal": {
+            "referral_urls": {
+                "pct_referral_domain_mismatch": (40.0, 75.0),
+                "pct_referral_chain_length_gt_2": (15.0, 35.0),
+                "referral_domain_entropy": (0.8, 1.8),
+            },
+            "viewability_scores": {
+                "pct_zero_pixel_ads": (15.0, 45.0),
+                "pct_stacked_ads": (10.0, 30.0),
+                "pct_in_viewport_gt_1s": (15.0, 35.0),
+                "avg_viewport_dwell_seconds": (0.5, 2.0),
+            },
+            "ip_distribution": {
+                "pct_datacenter_ips": (25.0, 50.0),
+                "pct_residential_ips": (45.0, 70.0),
+            },
+            "device_fingerprints": {
+                "pct_headless_browser": (5.0, 20.0),
+            },
+            "click_timestamps": {
+                "avg_interval_seconds": (15.0, 35.0),
+                "pct_clicks_2am_5am": (0.10, 0.20),
+            },
+            "conversion_quality": {
+                "pct_bounce_after_click": (65.0, 85.0),
+                "avg_pages_per_session": (1.2, 2.0),
+            },
+        },
+        "cautious": {
+            "referral_urls": {
+                "pct_referral_domain_mismatch": (20.0, 40.0),
+                "pct_referral_chain_length_gt_2": (8.0, 18.0),
+                "referral_domain_entropy": (1.8, 2.8),
+            },
+            "viewability_scores": {
+                "pct_zero_pixel_ads": (5.0, 15.0),
+                "pct_stacked_ads": (3.0, 10.0),
+                "pct_in_viewport_gt_1s": (35.0, 50.0),
+                "avg_viewport_dwell_seconds": (2.0, 4.0),
+            },
+        },
+        "covering_tracks": {
+            "referral_urls": {
+                "pct_referral_domain_mismatch": (8.0, 18.0),
+                "pct_referral_chain_length_gt_2": (4.0, 8.0),
+            },
+            "viewability_scores": {
+                "pct_zero_pixel_ads": (1.0, 5.0),
+                "pct_stacked_ads": (1.0, 3.0),
+                "pct_in_viewport_gt_1s": (45.0, 60.0),
+            },
+        },
+        "dark": {},
+    },
+    "click_injection": {
+        "normal": {
+            "conversion_quality": {
+                "click_to_conversion_seconds_mean": (2.0, 15.0),
+                "conversion_rate": (15.0, 50.0),
+                "pct_last_click_attributed": (85.0, 99.0),
+                "pct_bounce_after_click": (10.0, 25.0),
+                "avg_pages_per_session": (1.0, 1.5),
+            },
+            "click_timestamps": {
+                "avg_interval_seconds": (5.0, 15.0),
+                "pct_sub_second_pairs": (0.15, 0.40),
+                "hourly_entropy": (1.5, 2.5),
+            },
+            "device_fingerprints": {
+                "pct_headless_browser": (5.0, 25.0),
+                "pct_mismatched_timezone_ip": (10.0, 25.0),
+            },
+            "ip_distribution": {
+                "pct_datacenter_ips": (15.0, 35.0),
+            },
+        },
+        "cautious": {
+            "conversion_quality": {
+                "click_to_conversion_seconds_mean": (15.0, 60.0),
+                "conversion_rate": (8.0, 20.0),
+                "pct_last_click_attributed": (70.0, 85.0),
+                "pct_bounce_after_click": (25.0, 40.0),
+            },
+            "click_timestamps": {
+                "avg_interval_seconds": (12.0, 25.0),
+                "pct_sub_second_pairs": (0.05, 0.15),
+                "hourly_entropy": (2.2, 3.0),
+            },
+            "device_fingerprints": {
+                "pct_headless_browser": (2.0, 8.0),
+                "pct_mismatched_timezone_ip": (5.0, 12.0),
+            },
+        },
+        "covering_tracks": {
+            "conversion_quality": {
+                "click_to_conversion_seconds_mean": (50.0, 120.0),
+                "conversion_rate": (5.0, 10.0),
+                "pct_last_click_attributed": (60.0, 72.0),
+            },
+            "click_timestamps": {
+                "avg_interval_seconds": (20.0, 35.0),
+                "pct_sub_second_pairs": (0.02, 0.06),
+            },
+        },
+        "dark": {},
+    },
+}
+
+
+# ── Seeded value generator ──────────────────────────────────────────────────
+
+def _seeded_value(seed_str: str, lo: float, hi: float) -> float:
+    h = int(hashlib.sha256(seed_str.encode()).hexdigest()[:8], 16)
+    t = (h % 10000) / 10000.0
+    return round(lo + t * (hi - lo), 4)
+
+
+# ── Public API ──────────────────────────────────────────────────────────────
+
+def generate_investigation_metrics(
+    case_id: str,
+    publisher_id: str,
+    publisher_cfg: Dict[str, Any],
+    tool_name: str,
+    adaptation_stage: str,
+) -> Dict[str, Any]:
+    """Return structured numerical metrics for an investigation tool."""
+    is_fraudulent = publisher_cfg.get("is_fraudulent", False)
+    fraud_type = publisher_cfg.get("fraud_type")
+
+    legit = LEGIT_RANGES.get(tool_name, {})
+    if not legit:
+        return {"error": f"Unknown tool: {tool_name}"}
+
+    # Determine which ranges to use
+    fraud_tool_ranges: Dict[str, tuple] = {}
+    if is_fraudulent and fraud_type and adaptation_stage != "dark":
+        type_ranges = FRAUD_RANGES.get(fraud_type, {})
+        stage_ranges = type_ranges.get(adaptation_stage, {})
+        fraud_tool_ranges = stage_ranges.get(tool_name, {})
+
+    metrics: Dict[str, Any] = {}
+    for metric_name, legit_range in legit.items():
+        seed = f"{case_id}:{publisher_id}:{tool_name}:{metric_name}"
+        if metric_name in fraud_tool_ranges:
+            lo, hi = fraud_tool_ranges[metric_name]
+        else:
+            lo, hi = legit_range
+        metrics[metric_name] = _seeded_value(seed, lo, hi)
+
+    return {
+        "tool": tool_name,
+        "publisher_id": publisher_id,
+        "metrics": metrics,
+    }
+
+
+def generate_trend_summary() -> str:
+    """Placeholder for trend summary (currently muted)."""
+    return ""
+
+
+def generate_alerts() -> list:
+    """Placeholder for alerts (currently muted)."""
+    return []

server/step_reward.py

@@ -0,0 +1,49 @@
+"""Per-step reward calculator [0, 1]."""
+
+
+def compute_step_reward(
+    action_type: str,
+    daily_fraud_spend: float,
+    total_budget: float,
+    publisher_cfg: dict | None = None,
+    flag_correct: bool | None = None,
+    flag_type_correct: bool | None = None,
+    day: int = 1,
+    episode_days: int = 14,
+) -> float:
+    """Return a reward in [0.0, 1.0] for a single step.
+
+    Centered at 0.5 (neutral). Rewards scale with timing and precision.
+    """
+    if action_type == "monitor":
+        if daily_fraud_spend > 0:
+            # Active unflagged fraud — penalty grows with time (urgency)
+            progress = day / episode_days  # 0.07 on day 1, 1.0 on day 14
+            penalty = 0.10 + 0.20 * progress  # 0.10 early, up to 0.30 late
+            return max(0.05, 0.50 - penalty)
+        return 0.50
+
+    if action_type == "investigate_publisher":
+        if publisher_cfg is not None and publisher_cfg.get("is_fraudulent"):
+            # Investigating a real fraudster — reward scales with how early
+            early_bonus = max(0.0, (episode_days - day) / episode_days) * 0.10
+            return min(1.0, 0.55 + early_bonus)
+        # Investigating a clean publisher — wastes budget
+        return 0.35
+
+    if action_type == "flag_fraud":
+        if flag_correct is True and flag_type_correct is True:
+            # Perfect flag — bonus for catching it early
+            early_bonus = max(0.0, (episode_days - day) / episode_days) * 0.05
+            return min(1.0, 0.95 + early_bonus)
+        if flag_correct is True:
+            # Right publisher, wrong type
+            return 0.70
+        # False positive — heavy penalty
+        return 0.05
+
+    if action_type == "submit_report":
+        return 0.50
+
+    # invalid / malformed
+    return 0.05