Upload README.md with huggingface_hub

README.md

@@ -1,371 +1,369 @@
----
-title: Meta Ads Attribution Environment
-emoji: 📈
-colorFrom: blue
-colorTo: indigo
-sdk: docker
-app_port: 8000
-base_path: /web
-pinned: true
----
-
-# Meta Ads Attribution Recovery Environment
-
-[![OpenEnv](https://img.shields.io/badge/OpenEnv-Compliant-brightgreen)](https://openenv.dev)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-
-**An OpenEnv-compliant reinforcement learning environment that models Meta Ads attribution recovery under iOS tracking constraints, narrow attribution windows, and incomplete conversion signals.**
-
-> **The Problem**: Meta advertisers lose significant revenue because iOS privacy changes, narrow attribution windows, and browser tracking restrictions leave **40-70% of conversions** untracked. As a result, Meta's optimization system learns from incomplete signals, often overvaluing short-lag outcomes while undervaluing high-performing ads with delayed conversions.
-
----
-
-## The Attribution Crisis Explained
-
-### What's Breaking Attribution?
-
-1. **Narrow Attribution Windows**: Defaults shifted from 28-day to 7-day (or 1-day), so later conversions are excluded.
-2. **iOS 14.5+ Privacy**: Apple ATT suppresses a large share of iOS conversion tracking via Meta Pixel.
-3. **Browser Restrictions**: Safari ITP, Firefox protections, and ad blockers further reduce signal quality.
-4. **Missing Server-Side Tracking**: Many advertisers still lack Conversions API (CAPI), limiting server-side recovery.
-
-### The Impact
-
-**Example Campaign:**
-- **Reported Metrics**: 59 conversions, $76 CPA, 0.98x ROAS -> *Appears unprofitable*
-- **True Performance**: 180 conversions, $25 CPA, 3.0x ROAS -> *Actually highly profitable!*
-- **Attribution Gap**: **67% of conversions untracked**
-
-**Result**: The optimization loop can pause profitable inventory and over-allocate spend to weaker ad sets.
-
-### This Environment Teaches Agents To:
-1. Diagnose attribution failures from campaign-level and ad set-level signals.
-2. Apply technical remediations (window expansion, CAPI, AEM).
-3. Reallocate budget using true performance rather than biased observed metrics.
-4. Recover signal quality so optimization decisions become reliable again.
-
----
-
-## Environment Overview
-
-### OpenEnv Compliance
-- **Typed Pydantic models** for Observation, Action, Reward, State
-- **Standard API**: `reset()`, `step(action)`, `state()`
-- **Three difficulty levels** with programmatic graders (0.0–1.0 scoring)
-- **Realistic simulator** modeling attribution degradation
-- **Multi-component rewards** that capture incremental progress
-
-### Key Metrics
-- **Episode Length**: 5-10 steps
-- **Success Threshold**: Score ≥0.60
-- **Action Space**: 10 discrete actions (window adjustment, CAPI, budget optimization)
-- **Observation Space**: Campaign metrics + diagnostic signals + natural language context
-
----
-
-## Action Space
-
-| Action | Parameters | Use Case |
-|--------|-----------|----------|
-| `adjust_attribution_window` | `{"window": "7d_click"}` | When window is too narrow (1d_click) |
-| `enable_conversions_api` | `{}` | When iOS >40% and Pixel signal <60% |
-| `enable_aggregated_event_measurement` | `{}` | After CAPI, for additional iOS recovery |
-| `add_utm_tracking` | `{}` | Improve cross-domain attribution |
-| `pause_underperforming_adsets` | `{"roas_threshold": 1.0}` | When true ROAS <1.0 |
-| `reallocate_to_top_performers` | `{"amount": 2000}` | Shift budget to high-ROAS adsets |
-| `adjust_budget_allocation` | `{"shifts": {...}}` | Fine-grained budget control |
-| `change_bid_strategy` | `{"strategy": "value_optimisation"}` | Optimize for ROAS vs CPA |
-| `segment_audience` | `{}` | Create better-targeted segments |
-| `no_op` | `{}` | No action needed |
-
----
-
-## Observation Space
-
-```python
-{
-  # Campaign Performance
-  "reported_conversions": 59,        # What Meta sees
-  "true_conversions": 180,            # Ground truth (hidden from algorithm)
-  "attribution_gap_pct": 0.672,       # 67% untracked!
-  "reported_roas": 0.98,              # Appears unprofitable
-  "true_roas": 3.0,                   # Actually profitable
-  
-  # Attribution Setup
-  "attribution_window": "1d_click",   # Too narrow
-  "pixel_signal_quality": 0.86,       # 14% signal loss
-  "ios_traffic_pct": 0.25,            # 25% iOS users
-  "conversions_api_enabled": false,   # Missing CAPI
-  "aem_enabled": false,               # Missing AEM
-  
-  # Natural Language Context (for LLM agents)
-  "context": "Campaign 'Spring Sale' | Objective: CONVERSIONS\n..."
-}
-```
-
----
-
-## Tasks & Difficulty
-
-### Easy: Attribution Window Fix
-**Problem**: A 1-day attribution window excludes most delayed conversions.  
-**Solution**: Adjust to 7-day click window  
-**Baseline Score**: 0.893
-
-### Medium: iOS Signal Recovery
-**Problem**: High iOS share without CAPI/AEM causes substantial signal loss.  
-**Solution**: Enable CAPI → Enable AEM  
-**Baseline Score**: 0.850
-
-### Hard: Full Attribution Audit
-**Problem**: Narrow window, high iOS exposure, missing tracking stack, and misallocated budget.  
-**Solution**: Multi-step optimization (5+ actions)  
-**Baseline Score**: 0.794
-
----
-
-## Quick Start
-
-### Installation
-
-```bash
-# Clone repository
-git clone https://github.com/yourusername/meta-ads-openenv.git
-cd meta-ads-openenv
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Set up API key (copy .env.example to .env and add your key)
-cp .env.example .env
-# Edit .env with required values:
-# API_BASE_URL=https://router.huggingface.co/v1
-# MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
-# HF_TOKEN=hf_your_token_here
-```
-
-### Run Baseline Agent
-
-```bash
-# Required (for LLM-backed paths):
-export API_BASE_URL=https://router.huggingface.co/v1
-export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
-export HF_TOKEN=hf_your_token_here
-
-# Run baseline across all 3 tasks
-python baseline/run_baseline.py
-```
-
-**Expected Output:**
-```
-TASK: EASY_ATTRIBUTION_WINDOW
-Score: 0.8926 (PASS) | Steps: 5/5
-
-TASK: MEDIUM_PIXEL_RECOVERY  
-Score: 0.8500 (PASS) | Steps: 4/7
-
-TASK: HARD_FULL_ATTRIBUTION_AUDIT
-Score: 0.7942 (PASS) | Steps: 7/10
-
-Average Score: 0.8456
-```
-
-### Launch Web UI
-
-```bash
-python -m server.app
-# Open browser to http://127.0.0.1:8000/web
-```
-
-### Use Programmatically
-
-```python
-from meta_ads_env import MetaAdsAttributionEnv
-from meta_ads_env.models import Action
-
-# Initialize
-env = MetaAdsAttributionEnv(task_id="easy_attribution_window")
-obs = env.reset()
-
-# Check initial state
-print(f"Attribution gap: {obs.attribution_gap_pct:.1%}")
-print(f"Reported ROAS: {obs.roas_reported:.2f}x")
-print(f"True ROAS: {obs.roas_true:.2f}x")
-
-# Take action
-action = Action(
-    action_type="adjust_attribution_window",
-    parameters={"window": "7d_click"}
-)
-obs, reward, done, info = env.step(action)
-
-print(f"Reward: {reward.total:.4f}")
-print(f"New gap: {obs.attribution_gap_pct:.1%}")
-
-# Grade episode
-if done:
-    result = env.grade_episode()
-    print(f"Score: {result.score:.4f} - {'PASS' if result.passed else 'FAIL'}")
-```
-
----
-
-## Baseline Results
-
-**Model**: Qwen/Qwen2.5-72B-Instruct (OpenAI-compatible interface) | **Temperature**: 0.0
-
-| Task | Score | Pass | Steps | Key Actions |
-|------|-------|------|-------|-------------|
-| Easy | 0.893 | Yes | 5/5 | Investigate + window fix + convergence handling |
-| Medium | 0.850 | Yes | 4/7 | Investigate + CAPI + AEM + modeled reporting |
-| Hard | 0.794 | Yes | 7/10 | Investigate + window + CAPI + AEM + pause + reallocate |
-| **Average** | **0.846** | **100%** | - | **All passing** |
-
----
-
-## Reward Function
-
-Multi-component reward designed to reward meaningful progress:
-
-```python
-reward = (
-    0.35 × attribution_accuracy     # Gap closure
-  + 0.25 × roas_improvement         # True ROAS increase
-  + 0.25 × signal_quality_gain      # Pixel recovery
-  + 0.10 × action_validity          # Right action for context
-  + 0.05 × step_efficiency          # Fewer steps bonus
-  - trajectory_penalty              # Harmful action penalty
-)
-```
-
-**Range**: -1.0 to 1.0 per step
-
----
-
-## Docker Deployment
-
-### Build and Run Locally
-```bash
-docker build -t meta-ads-env .
-docker run -p 7860:7860 -e API_BASE_URL=https://router.huggingface.co/v1 -e MODEL_NAME=Qwen/Qwen2.5-72B-Instruct -e HF_TOKEN=hf_your_token_here meta-ads-env
-```
-
-### Deploy to Hugging Face Spaces
-1. Create new Space (Docker SDK)
-2. Add `API_BASE_URL`, `MODEL_NAME`, and `HF_TOKEN` as Space secrets
-3. Push code to the Space repository
-4. Space auto-builds and deploys
-
----
-
-## Inference Workflow
-
-### Inference Script
-
-Use `inference.py` at the repository root to run standardized task inference with structured logs.
-
-**Set environment variables:**
-```bash
-export API_BASE_URL=https://router.huggingface.co/v1
-export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
-export HF_TOKEN=hf_your_token_here
-```
-
-**Run inference:**
-```bash
-python inference.py
-```
-
-**Output format:**
-```
-[START] task=easy_attribution_window env=meta_ads_attribution_openenv model=Qwen/Qwen2.5-72B-Instruct
-[STEP] step=1 action=investigate_attribution reward=0.09 done=false error=null
-[END] success=true steps=3 score=0.900 rewards=0.09,0.76,0.67
-...
-```
-
-This structured output is designed for easy monitoring, reproducible evaluation, and downstream parsing.
-
-### Validate Submission
-```bash
-bash validate-submission.sh <your_space_url> .
-```
-
----
-
-## Project Structure
-
-```
-meta-ads-openenv/
-├── openenv.yaml              # OpenEnv metadata
-├── inference.py              # Required hackathon inference script
-├── requirements.txt          # Dependencies
-├── Dockerfile                # Container definition
-│
-├── meta_ads_env/            # Core environment
-│   ├── env.py               # Main environment class
-│   ├── models.py            # Pydantic models
-│   ├── simulator.py         # Attribution simulator
-│   ├── reward.py            # Reward function
-│   ├── grader.py            # Task graders
-���   └── tasks.py             # Task definitions
-│
-├── baseline/                # Baseline agent
-│   ├── baseline_agent.py    # LLM-powered agent
-│   └── run_baseline.py      # Evaluation script
-│
-├── evaluation/              # Evaluation tools
-│   ├── llm_grader.py       # Optional LLM-as-judge
-│   └── metrics.py          # Aggregate metrics
-│
-└── validate-submission.sh   # Submission validator
-```
-
----
-
-## Advanced Usage
-
-### Validate OpenEnv Compliance
-```bash
-pip install openenv
-openenv validate .
-```
-
-### Custom Training Loop
-```python
-for episode in range(100):
-    obs = env.reset()
-    done = False
-    
-    while not done:
-        action = your_policy.select_action(obs)
-        obs, reward, done, info = env.step(action)
-        your_policy.update(obs, action, reward)
-```
-
-### LLM Scoring
-```python
-from evaluation.llm_grader import LLMGrader
-
-grader = LLMGrader(model="Qwen/Qwen2.5-72B-Instruct")
-result = grader.grade_trajectory(
-    task_id="hard_full_attribution_audit",
-    history=env.state().history,
-    initial_context=initial_obs.context,
-    final_context=final_obs.context
-)
-```
-
----
-
-## Acknowledgments
-
-Built to demonstrate how AI agents can solve high-impact marketing optimization problems in realistic attribution environments. Inspired by real Meta Ads attribution challenges faced by performance teams at scale.
-
-**OpenEnv**: RL environment specification  
-**Meta Ads Manager**: Real-world attribution dynamics and constraints  
-**Digital Marketing Community**: Practical insights from attribution and measurement operations
-
----
-
-**Making attribution-aware AI optimization practical and measurable**
+---
+title: Meta Ads Attribution Environment
+emoji: 📈
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: true
+---
+
+# Meta Ads Attribution Recovery Environment
+
+[![OpenEnv](https://img.shields.io/badge/OpenEnv-Compliant-brightgreen)](https://openenv.dev)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**An OpenEnv-compliant reinforcement learning environment that models Meta Ads attribution recovery under iOS tracking constraints, narrow attribution windows, and incomplete conversion signals.**
+
+> **The Problem**: Meta advertisers lose significant revenue because iOS privacy changes, narrow attribution windows, and browser tracking restrictions leave **40-70% of conversions** untracked. As a result, Meta's optimization system learns from incomplete signals, often overvaluing short-lag outcomes while undervaluing high-performing ads with delayed conversions.
+
+---
+
+## The Attribution Crisis Explained
+
+### What's Breaking Attribution?
+
+1. **Narrow Attribution Windows**: Defaults shifted from 28-day to 7-day (or 1-day), so later conversions are excluded.
+2. **iOS 14.5+ Privacy**: Apple ATT suppresses a large share of iOS conversion tracking via Meta Pixel.
+3. **Browser Restrictions**: Safari ITP, Firefox protections, and ad blockers further reduce signal quality.
+4. **Missing Server-Side Tracking**: Many advertisers still lack Conversions API (CAPI), limiting server-side recovery.
+
+### The Impact
+
+**Example Campaign:**
+- **Reported Metrics**: 59 conversions, $76 CPA, 0.98x ROAS -> *Appears unprofitable*
+- **True Performance**: 180 conversions, $25 CPA, 3.0x ROAS -> *Actually highly profitable!*
+- **Attribution Gap**: **67% of conversions untracked**
+
+**Result**: The optimization loop can pause profitable inventory and over-allocate spend to weaker ad sets.
+
+### This Environment Teaches Agents To:
+1. Diagnose attribution failures from campaign-level and ad set-level signals.
+2. Apply technical remediations (window expansion, CAPI, AEM).
+3. Reallocate budget using true performance rather than biased observed metrics.
+4. Recover signal quality so optimization decisions become reliable again.
+
+---
+
+## Environment Overview
+
+### OpenEnv Compliance
+- **Typed Pydantic models** for Observation, Action, Reward, State
+- **Standard API**: `reset()`, `step(action)`, `state()`
+- **Three difficulty levels** with programmatic graders (0.0–1.0 scoring)
+- **Realistic simulator** modeling attribution degradation
+- **Multi-component rewards** that capture incremental progress
+
+### Key Metrics
+- **Episode Length**: 5-10 steps
+- **Success Threshold**: Score ≥0.60
+- **Action Space**: 10 discrete actions (window adjustment, CAPI, budget optimization)
+- **Observation Space**: Campaign metrics + diagnostic signals + natural language context
+
+---
+
+## Action Space
+
+| Action | Parameters | Use Case |
+|--------|-----------|----------|
+| `adjust_attribution_window` | `{"window": "7d_click"}` | When window is too narrow (1d_click) |
+| `enable_conversions_api` | `{}` | When iOS >40% and Pixel signal <60% |
+| `enable_aggregated_event_measurement` | `{}` | After CAPI, for additional iOS recovery |
+| `add_utm_tracking` | `{}` | Improve cross-domain attribution |
+| `pause_underperforming_adsets` | `{"roas_threshold": 1.0}` | When true ROAS <1.0 |
+| `reallocate_to_top_performers` | `{"amount": 2000}` | Shift budget to high-ROAS adsets |
+| `adjust_budget_allocation` | `{"shifts": {...}}` | Fine-grained budget control |
+| `change_bid_strategy` | `{"strategy": "value_optimisation"}` | Optimize for ROAS vs CPA |
+| `segment_audience` | `{}` | Create better-targeted segments |
+| `no_op` | `{}` | No action needed |
+
+---
+
+## Observation Space
+
+```python
+{
+  # Campaign Performance
+  "reported_conversions": 59,        # What Meta sees
+  "true_conversions": 180,            # Ground truth (hidden from algorithm)
+  "attribution_gap_pct": 0.672,       # 67% untracked!
+  "reported_roas": 0.98,              # Appears unprofitable
+  "true_roas": 3.0,                   # Actually profitable
+  
+  # Attribution Setup
+  "attribution_window": "1d_click",   # Too narrow
+  "pixel_signal_quality": 0.86,       # 14% signal loss
+  "ios_traffic_pct": 0.25,            # 25% iOS users
+  "conversions_api_enabled": false,   # Missing CAPI
+  "aem_enabled": false,               # Missing AEM
+  
+  # Natural Language Context (for LLM agents)
+  "context": "Campaign 'Spring Sale' | Objective: CONVERSIONS\n..."
+}
+```
+
+---
+
+## Tasks & Difficulty
+
+### Easy: Attribution Window Fix
+**Problem**: A 1-day attribution window excludes most delayed conversions.  
+**Solution**: Adjust to 7-day click window  
+**Baseline Score**: 0.893
+
+### Medium: iOS Signal Recovery
+**Problem**: High iOS share without CAPI/AEM causes substantial signal loss.  
+**Solution**: Enable CAPI → Enable AEM  
+**Baseline Score**: 0.850
+
+### Hard: Full Attribution Audit
+**Problem**: Narrow window, high iOS exposure, missing tracking stack, and misallocated budget.  
+**Solution**: Multi-step optimization (5+ actions)  
+**Baseline Score**: 0.794
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/meta-ads-openenv.git
+cd meta-ads-openenv
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Set up API key (copy .env.example to .env and add your key)
+cp .env.example .env
+# Edit .env with required values:
+# API_BASE_URL=https://router.huggingface.co/v1
+# MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
+# HF_TOKEN=hf_your_token_here
+```
+
+### Run Baseline Agent
+
+```bash
+# Required (for LLM-backed paths):
+export API_BASE_URL=https://router.huggingface.co/v1
+export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
+export HF_TOKEN=hf_your_token_here
+
+# Run baseline across all 3 tasks
+python baseline/run_baseline.py
+```
+
+**Expected Output:**
+```
+TASK: EASY_ATTRIBUTION_WINDOW
+Score: 0.8926 (PASS) | Steps: 5/5
+
+TASK: MEDIUM_PIXEL_RECOVERY  
+Score: 0.8500 (PASS) | Steps: 4/7
+
+TASK: HARD_FULL_ATTRIBUTION_AUDIT
+Score: 0.7942 (PASS) | Steps: 7/10
+
+Average Score: 0.8456
+```
+
+### Launch Web UI
+
+```bash
+python -m server.app
+# Open browser to http://127.0.0.1:8000/web
+```
+
+### Use Programmatically
+
+```python
+from meta_ads_env import MetaAdsAttributionEnv
+from meta_ads_env.models import Action
+
+# Initialize
+env = MetaAdsAttributionEnv(task_id="easy_attribution_window")
+obs = env.reset()
+
+# Check initial state
+print(f"Attribution gap: {obs.attribution_gap_pct:.1%}")
+print(f"Reported ROAS: {obs.roas_reported:.2f}x")
+print(f"True ROAS: {obs.roas_true:.2f}x")
+
+# Take action
+action = Action(
+    action_type="adjust_attribution_window",
+    parameters={"window": "7d_click"}
+)
+obs, reward, done, info = env.step(action)
+
+print(f"Reward: {reward.total:.4f}")
+print(f"New gap: {obs.attribution_gap_pct:.1%}")
+
+# Grade episode
+if done:
+    result = env.grade_episode()
+    print(f"Score: {result.score:.4f} - {'PASS' if result.passed else 'FAIL'}")
+```
+
+---
+
+## Baseline Results
+
+**Model**: Qwen/Qwen2.5-72B-Instruct (OpenAI-compatible interface) | **Temperature**: 0.0
+
+| Task | Score | Pass | Steps | Key Actions |
+|------|-------|------|-------|-------------|
+| Easy | 0.893 | Yes | 5/5 | Investigate + window fix + convergence handling |
+| Medium | 0.850 | Yes | 4/7 | Investigate + CAPI + AEM + modeled reporting |
+| Hard | 0.794 | Yes | 7/10 | Investigate + window + CAPI + AEM + pause + reallocate |
+| **Average** | **0.846** | **100%** | - | **All passing** |
+
+---
+
+## Reward Function
+
+Multi-component reward designed to reward meaningful progress:
+
+```python
+reward = (
+    0.35 × attribution_accuracy     # Gap closure
+  + 0.25 × roas_improvement         # True ROAS increase
+  + 0.25 × signal_quality_gain      # Pixel recovery
+  + 0.10 × action_validity          # Right action for context
+  + 0.05 × step_efficiency          # Fewer steps bonus
+  - trajectory_penalty              # Harmful action penalty
+)
+```
+
+**Range**: -1.0 to 1.0 per step
+
+---
+
+## Docker Deployment
+
+### Build and Run Locally
+```bash
+docker build -t meta-ads-env .
+docker run -p 7860:7860 -e API_BASE_URL=https://router.huggingface.co/v1 -e MODEL_NAME=Qwen/Qwen2.5-72B-Instruct -e HF_TOKEN=hf_your_token_here meta-ads-env
+```
+
+### Deploy to Hugging Face Spaces
+1. Create new Space (Docker SDK)
+2. Add `API_BASE_URL`, `MODEL_NAME`, and `HF_TOKEN` as Space secrets
+3. Push code to the Space repository
+4. Space auto-builds and deploys
+
+---
+
+## Inference Workflow
+
+### Inference Script
+
+Use `inference.py` at the repository root to run standardized task inference with structured logs.
+
+**Set environment variables:**
+```bash
+export API_BASE_URL=https://router.huggingface.co/v1
+export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
+export HF_TOKEN=hf_your_token_here
+```
+
+**Run inference:**
+```bash
+python inference.py
+```
+
+**Output format:**
+```
+[START] task=easy_attribution_window env=meta_ads_attribution_openenv model=Qwen/Qwen2.5-72B-Instruct
+[STEP] step=1 action=investigate_attribution reward=0.09 done=false error=null
+[END] success=true steps=3 score=0.900 rewards=0.09,0.76,0.67
+...
+```
+
+This structured output is designed for easy monitoring, reproducible evaluation, and downstream parsing.
+
+### Validate Submission
+```bash
+bash validate-submission.sh <your_space_url> .
+```
+
+---
+
+## Project Structure
+
+```
+meta-ads-openenv/
+├── openenv.yaml              # OpenEnv metadata
+├── inference.py              # Required hackathon inference script
+├── requirements.txt          # Dependencies
+├── Dockerfile                # Container definition
+│
+├── meta_ads_env/            # Core environment
+│   ├── env.py               # Main environment class
+│   ├── models.py            # Pydantic models
+│   ├── simulator.py         # Attribution simulator
+│   ├── reward.py            # Reward function
+│   ├── grader.py            # Task graders
+│   └── tasks.py             # Task definitions
+│
+├── baseline/                # Baseline agent
+│   ├── baseline_agent.py    # LLM-powered agent
+│   └── run_baseline.py      # Evaluation script
+│
+├── evaluation/              # Evaluation tools
+│   ├── llm_grader.py       # Optional LLM-as-judge
+│   └── metrics.py          # Aggregate metrics
+│
+└── validate-submission.sh   # Submission validator
+```
+
+---
+
+## Advanced Usage
+
+### Validate OpenEnv Compliance
+```bash
+pip install openenv
+openenv validate .
+```
+
+### Custom Training Loop
+```python
+for episode in range(100):
+    obs = env.reset()
+    done = False
+    
+    while not done:
+        action = your_policy.select_action(obs)
+        obs, reward, done, info = env.step(action)
+        your_policy.update(obs, action, reward)
+```
+
+### LLM Scoring
+```python
+from evaluation.llm_grader import LLMGrader
+
+grader = LLMGrader(model="Qwen/Qwen2.5-72B-Instruct")
+result = grader.grade_trajectory(
+    task_id="hard_full_attribution_audit",
+    history=env.state().history,
+    initial_context=initial_obs.context,
+    final_context=final_obs.context
+)
+```
+
+---
+
+## Acknowledgments
+
+Built to demonstrate how AI agents can solve high-impact marketing optimization problems in realistic attribution environments. Inspired by real Meta Ads attribution challenges faced by performance teams at scale.
+
+**OpenEnv**: RL environment specification  
+**Meta Ads Manager**: Real-world attribution dynamics and constraints  
+**Digital Marketing Community**: Practical insights from attribution and measurement operations
+
+---
+
+**Making attribution-aware AI optimization practical and measurable**