Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
+# Install openenv-core from source (not on PyPI)
+RUN pip install --no-cache-dir git+https://github.com/meta-pytorch/OpenEnv.git
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,128 @@
 ---
-title: Gtm Strategy Optimizer
-emoji: 🐠
-colorFrom: indigo
-colorTo: red
+title: GTM Strategy Optimizer
+emoji: 📈
+colorFrom: purple
+colorTo: blue
 sdk: docker
-pinned: false
+app_port: 8000
+tags:
+  - openenv
+base_path: /web
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GTM Strategy Optimizer — OpenEnv Environment
+
+An RL environment that simulates **Go-To-Market (GTM) strategy optimization** for product launches. Agents learn to allocate marketing budgets, target customer segments, craft messaging, run experiments, and adjust pricing to maximize revenue under uncertainty.
+
+## Why GTM?
+
+Every startup and growth team does GTM optimization manually — iterating on channels, messaging, and targeting through trial and error. This environment captures the real complexity: noisy metrics, delayed brand effects, diminishing returns on ad spend, and the tension between short-term revenue and long-term brand strength.
+
+## Action Space
+
+Each timestep (1 week), the agent chooses:
+
+| Action | Type | Description |
+|--------|------|-------------|
+| `budget_allocation` | `dict[str, float]` | Channel → fraction of weekly budget (sum ≤ 1.0) |
+| `segment_targeting` | `dict[str, float]` | Segment → targeting weight (sum ≈ 1.0) |
+| `messaging` | `dict[str, float]` | Dimension → emphasis weight (sum ≈ 1.0) |
+| `experiment` | `str \| null` | Optional experiment to launch |
+| `pricing_action` | `str \| null` | Optional pricing change |
+
+**Messaging dimensions:** cost_savings, performance, reliability, innovation, ease_of_use, security
+
+## Observation Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `week` / `total_weeks` | `int` | Current week and episode length |
+| `budget_remaining` | `float` | Remaining budget |
+| `channel_metrics` | `dict` | Per-channel: impressions, clicks, conversions, spend, CTR, CVR, ROI |
+| `funnel` | `dict` | Visitors, signups, activations, retained users + rates |
+| `segment_performance` | `dict` | Per-segment: conversion rate, engagement, churn, revenue |
+| `experiment_result` | `dict \| null` | Completed experiment results |
+| `brand_score` | `float` | Noisy proxy for brand health (0-100) |
+| `total_revenue` | `float` | Cumulative revenue |
+| `message` | `str` | Human-readable summary |
+
+## Tasks
+
+| Task | Difficulty | Weeks | Channels | Segments | Features |
+|------|-----------|-------|----------|----------|----------|
+| `channel_optimizer` | Easy | 12 | 3 | 2 | Budget + targeting only |
+| `growth_strategist` | Medium | 24 | 5 | 3 | + experiments, pricing, brand management |
+| `market_dominator` | Hard | 36 | 7 | 4 | + active competitor, market regime shifts, compliance traps |
+
+## Setup & Usage
+
+### Local Development
+
+```bash
+pip install -r requirements.txt
+uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### Docker
+
+```bash
+docker build -t gtm-optimizer -f server/Dockerfile .
+docker run -p 8000:8000 gtm-optimizer
+```
+
+### Client Usage
+
+```python
+from client import GTMEnv
+from models import GTMAction
+
+with GTMEnv(base_url="http://localhost:8000").sync() as env:
+    result = env.reset(task_id="channel_optimizer")
+    while not result.done:
+        action = GTMAction(
+            budget_allocation={"paid_search": 0.5, "paid_social": 0.3, "email_lifecycle": 0.2},
+            segment_targeting={"startup_founders": 0.6, "smb_owners": 0.4},
+            messaging={"performance": 0.3, "innovation": 0.3, "ease_of_use": 0.2, "cost_savings": 0.1, "reliability": 0.05, "security": 0.05},
+        )
+        result = env.step(action)
+    print(f"Score: {result.observation.reward}")
+```
+
+### Baseline Inference
+
+```bash
+export OPENAI_API_KEY=sk-...
+python baseline.py --model gpt-4o-mini
+```
+
+### API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/tasks` | GET | List all tasks with action schemas |
+| `/baseline` | POST | Run heuristic baseline, return scores |
+| `/grader` | POST | Get grader score for a task |
+| `/reset` | POST | Reset environment for a task |
+| `/step` | POST | Execute one action step |
+| `/state` | GET | Get current episode state |
+| `/health` | GET | Health check |
+| `/ws` | WS | WebSocket endpoint for persistent sessions |
+
+## Baseline Scores
+
+| Task | Heuristic (equal alloc) |
+|------|------------------------|
+| `channel_optimizer` | ~0.51 |
+| `growth_strategist` | ~0.33 |
+| `market_dominator` | ~0.42 |
+
+Scores improve with intelligent channel selection, messaging alignment, and experimentation.
+
+## Environment Dynamics
+
+- **Diminishing returns**: Channel effectiveness decays with cumulative spend
+- **Brand evolution**: Consistent messaging builds brand; variance erodes it
+- **Noisy observations**: All metrics include noise proportional to difficulty
+- **Delayed effects**: Brand investment pays off over weeks, not immediately
+- **Competitor response** (hard mode): Competitor increases aggression when you perform well
+- **Market shifts** (hard mode): Demand shocks at weeks ~12 and ~24

baseline.py

@@ -0,0 +1,259 @@
+"""Baseline inference script for the GTM Strategy Optimizer.
+
+Uses the OpenAI API to run an LLM agent against all 3 tasks.
+Reads OPENAI_API_KEY from environment variables.
+
+Usage:
+    export OPENAI_API_KEY=sk-...
+    python baseline.py [--task TASK_ID] [--model MODEL]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+# Add parent to path for imports
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from openai import OpenAI
+
+from models import GTMAction
+from server.simulation import MESSAGING_DIMS
+from server.tasks import create_simulator, get_task, TASKS
+
+
+SYSTEM_PROMPT = """You are a Go-To-Market (GTM) strategy optimizer. You manage a product launch by making weekly decisions about:
+
+1. **Budget allocation**: How to split your weekly marketing budget across available channels
+2. **Segment targeting**: How to weight your targeting across customer segments
+3. **Messaging**: Which value propositions to emphasize
+4. **Experiments** (if available): Which experiments to run
+5. **Pricing** (if available): Whether to adjust pricing
+
+You receive weekly performance metrics and must respond with a JSON action.
+
+Strategy tips:
+- Diversify budget initially, then double down on high-performing channels
+- Match messaging to segment preferences (e.g., startups care about innovation/performance)
+- Maintain brand consistency — don't change messaging wildly week to week
+- Use experiments to validate hypotheses before scaling
+- Monitor ROI per channel and shift budget away from underperforming channels
+
+Your response must be ONLY valid JSON matching this schema:
+{
+    "budget_allocation": {"channel_name": fraction, ...},  // fractions sum to <= 1.0
+    "segment_targeting": {"segment_name": weight, ...},    // weights sum to ~1.0
+    "messaging": {"dimension": weight, ...},               // weights sum to ~1.0
+    "experiment": "experiment_type" or null,
+    "pricing_action": "action" or null
+}
+"""
+
+
+def format_observation(obs_dict: dict) -> str:
+    """Format observation into a readable prompt for the LLM."""
+    parts = [f"**Week {obs_dict['week']}/{obs_dict['total_weeks']}**"]
+    parts.append(f"Budget remaining: ${obs_dict['budget_remaining']:,.0f} (${obs_dict['weekly_budget']:,.0f}/week)")
+    parts.append(f"Brand score: {obs_dict['brand_score']:.0f}/100")
+    parts.append(f"Total revenue: ${obs_dict['total_revenue']:,.0f} | Conversions: {obs_dict['total_conversions']} | Avg CAC: ${obs_dict['average_cac']:,.0f}")
+
+    parts.append("\n**Channel Performance:**")
+    for ch, m in obs_dict.get("channel_metrics", {}).items():
+        parts.append(
+            f"  {ch}: {m['impressions']} imp, {m['clicks']} clicks, "
+            f"{m['conversions']} conv, ${m['spend']:,.0f} spend, ROI={m['roi']:.2f}"
+        )
+
+    parts.append("\n**Segment Performance:**")
+    for seg, m in obs_dict.get("segment_performance", {}).items():
+        parts.append(
+            f"  {seg}: CVR={m['conversion_rate']:.4f}, "
+            f"engagement={m['engagement_score']:.1f}, ${m['revenue']:,.0f} rev"
+        )
+
+    if obs_dict.get("experiment_result"):
+        er = obs_dict["experiment_result"]
+        parts.append(f"\n**Experiment Result:** {er['recommendation']}")
+
+    parts.append(f"\nAvailable channels: {obs_dict['available_channels']}")
+    parts.append(f"Available segments: {obs_dict['available_segments']}")
+    if obs_dict.get("available_experiments"):
+        parts.append(f"Available experiments: {obs_dict['available_experiments']}")
+    if obs_dict.get("available_pricing_actions"):
+        parts.append(f"Available pricing actions: {obs_dict['available_pricing_actions']}")
+    parts.append(f"Messaging dimensions: {obs_dict['messaging_dimensions']}")
+
+    return "\n".join(parts)
+
+
+def parse_llm_action(response_text: str, task_id: str) -> dict:
+    """Parse LLM response into an action dict. Falls back to equal allocation."""
+    task_def = get_task(task_id)
+    channels = [c.name for c in task_def.channels]
+    segments = [s.name for s in task_def.segments]
+
+    # Default fallback
+    fallback = {
+        "budget_allocation": {ch: 1.0 / len(channels) for ch in channels},
+        "segment_targeting": {seg: 1.0 / len(segments) for seg in segments},
+        "messaging": {dim: 1.0 / len(MESSAGING_DIMS) for dim in MESSAGING_DIMS},
+        "experiment": None,
+        "pricing_action": None,
+    }
+
+    try:
+        # Try to extract JSON from response
+        text = response_text.strip()
+        if "```json" in text:
+            text = text.split("```json")[1].split("```")[0].strip()
+        elif "```" in text:
+            text = text.split("```")[1].split("```")[0].strip()
+
+        action = json.loads(text)
+
+        # Validate keys exist
+        if "budget_allocation" not in action:
+            action["budget_allocation"] = fallback["budget_allocation"]
+        if "segment_targeting" not in action:
+            action["segment_targeting"] = fallback["segment_targeting"]
+        if "messaging" not in action:
+            action["messaging"] = fallback["messaging"]
+
+        return action
+    except (json.JSONDecodeError, IndexError, KeyError):
+        return fallback
+
+
+def run_episode(task_id: str, model: str = "gpt-4o-mini", seed: int = 42, verbose: bool = True) -> float:
+    """Run one episode of the given task with an LLM agent."""
+    client = OpenAI()
+    task_def = get_task(task_id)
+    sim = create_simulator(task_id, seed=seed)
+
+    channels = list(sim.channels.keys())
+    segments = list(sim.segments.keys())
+
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+    # Initial observation prompt
+    initial_msg = (
+        f"You are managing a GTM campaign: **{task_def.name}** ({task_def.difficulty})\n"
+        f"{task_def.description}\n\n"
+        f"Duration: {task_def.total_weeks} weeks | Budget: ${task_def.total_budget:,.0f}\n"
+        f"Channels: {channels}\n"
+        f"Segments: {segments}\n"
+        f"Messaging dimensions: {MESSAGING_DIMS}\n"
+    )
+    if task_def.available_experiments:
+        initial_msg += f"Experiments: {task_def.available_experiments}\n"
+    if task_def.available_pricing_actions:
+        initial_msg += f"Pricing actions: {task_def.available_pricing_actions}\n"
+    initial_msg += "\nProvide your first week's action as JSON."
+
+    messages.append({"role": "user", "content": initial_msg})
+
+    while not sim.is_done:
+        # Get LLM action
+        try:
+            response = client.chat.completions.create(
+                model=model,
+                messages=messages,
+                temperature=0.3,
+                max_tokens=500,
+            )
+            llm_text = response.choices[0].message.content or ""
+        except Exception as e:
+            if verbose:
+                print(f"  LLM API error: {e}, using fallback")
+            llm_text = ""
+
+        action = parse_llm_action(llm_text, task_id)
+
+        # Step simulation
+        result = sim.step(
+            budget_allocation=action.get("budget_allocation", {}),
+            segment_targeting=action.get("segment_targeting", {}),
+            messaging=action.get("messaging", {}),
+            experiment=action.get("experiment"),
+            pricing_action=action.get("pricing_action"),
+        )
+
+        if verbose:
+            print(
+                f"  Week {sim.state.week}/{sim.state.total_weeks} | "
+                f"Rev: ${result['weekly_revenue']:,.0f} | "
+                f"Total: ${sim.state.total_revenue:,.0f} | "
+                f"Brand: {result['brand_score_observed']:.0f}"
+            )
+
+        # Build observation for next turn
+        obs_dict = {
+            "week": sim.state.week,
+            "total_weeks": sim.state.total_weeks,
+            "budget_remaining": sim.state.budget_remaining,
+            "weekly_budget": sim.state.weekly_budget,
+            "brand_score": result["brand_score_observed"],
+            "total_revenue": sim.state.total_revenue,
+            "total_conversions": sim.state.total_conversions,
+            "average_cac": sim.state.total_spend / max(sim.state.total_conversions, 1),
+            "channel_metrics": result["channel_metrics"],
+            "segment_performance": result["segment_performance"],
+            "experiment_result": result["experiment_result"],
+            "available_channels": channels,
+            "available_segments": segments,
+            "available_experiments": task_def.available_experiments,
+            "available_pricing_actions": task_def.available_pricing_actions,
+            "messaging_dimensions": MESSAGING_DIMS,
+        }
+
+        if not sim.is_done:
+            messages.append({"role": "assistant", "content": llm_text})
+            messages.append({
+                "role": "user",
+                "content": format_observation(obs_dict) + "\n\nProvide your next action as JSON.",
+            })
+
+            # Keep context manageable — trim old turns
+            if len(messages) > 12:
+                messages = [messages[0]] + messages[-10:]
+
+    score = task_def.grader(sim.state)
+    return score
+
+
+def main():
+    parser = argparse.ArgumentParser(description="GTM Baseline Inference")
+    parser.add_argument("--task", type=str, default=None, help="Run specific task (default: all)")
+    parser.add_argument("--model", type=str, default="gpt-4o-mini", help="OpenAI model name")
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args()
+
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Error: OPENAI_API_KEY environment variable not set")
+        sys.exit(1)
+
+    tasks_to_run = [args.task] if args.task else list(TASKS.keys())
+    scores = {}
+
+    for task_id in tasks_to_run:
+        print(f"\n{'='*60}")
+        print(f"Running task: {task_id}")
+        print(f"{'='*60}")
+        score = run_episode(task_id, model=args.model, seed=args.seed, verbose=not args.quiet)
+        scores[task_id] = score
+        print(f"Grader score: {score:.4f}")
+
+    print(f"\n{'='*60}")
+    print("BASELINE RESULTS")
+    print(f"{'='*60}")
+    for task_id, score in scores.items():
+        print(f"  {task_id}: {score:.4f}")
+    print(f"  Average: {sum(scores.values()) / len(scores):.4f}")
+
+
+if __name__ == "__main__":
+    main()

client.py

@@ -0,0 +1,94 @@
+"""Client for the GTM Strategy Optimizer environment."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from models import (
+    ChannelMetrics,
+    ExperimentResult,
+    FunnelMetrics,
+    GTMAction,
+    GTMObservation,
+    GTMState,
+    SegmentMetrics,
+)
+
+
+class GTMEnv(EnvClient[GTMAction, GTMObservation, GTMState]):
+    """WebSocket client for the GTM Strategy Optimizer environment."""
+
+    def _step_payload(self, action: GTMAction) -> Dict[str, Any]:
+        """Serialize a GTMAction to JSON for the wire."""
+        return action.model_dump(exclude={"metadata"})
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[GTMObservation]:
+        """Parse server response into StepResult[GTMObservation]."""
+        obs_data = payload.get("observation", {})
+
+        # Parse nested channel metrics
+        channel_metrics = {}
+        for ch, m in obs_data.get("channel_metrics", {}).items():
+            channel_metrics[ch] = ChannelMetrics(**m) if isinstance(m, dict) else m
+
+        # Parse funnel
+        funnel_data = obs_data.get("funnel", {})
+        funnel = FunnelMetrics(**funnel_data) if isinstance(funnel_data, dict) else FunnelMetrics()
+
+        # Parse segment performance
+        segment_perf = {}
+        for seg, m in obs_data.get("segment_performance", {}).items():
+            segment_perf[seg] = SegmentMetrics(**m) if isinstance(m, dict) else m
+
+        # Parse experiment result
+        exp_data = obs_data.get("experiment_result")
+        exp_result = ExperimentResult(**exp_data) if exp_data else None
+
+        obs = GTMObservation(
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            week=obs_data.get("week", 0),
+            total_weeks=obs_data.get("total_weeks", 12),
+            budget_remaining=obs_data.get("budget_remaining", 0.0),
+            weekly_budget=obs_data.get("weekly_budget", 0.0),
+            channel_metrics=channel_metrics,
+            funnel=funnel,
+            segment_performance=segment_perf,
+            experiment_result=exp_result,
+            brand_score=obs_data.get("brand_score", 50.0),
+            total_revenue=obs_data.get("total_revenue", 0.0),
+            total_conversions=obs_data.get("total_conversions", 0),
+            average_cac=obs_data.get("average_cac", 0.0),
+            available_channels=obs_data.get("available_channels", []),
+            available_segments=obs_data.get("available_segments", []),
+            available_experiments=obs_data.get("available_experiments", []),
+            available_pricing_actions=obs_data.get("available_pricing_actions", []),
+            messaging_dimensions=obs_data.get("messaging_dimensions", []),
+            message=obs_data.get("message", ""),
+        )
+
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> GTMState:
+        """Parse server state response into GTMState."""
+        return GTMState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            task_id=payload.get("task_id", "channel_optimizer"),
+            difficulty=payload.get("difficulty", "easy"),
+            true_brand_strength=payload.get("true_brand_strength", 50.0),
+            true_market_demand=payload.get("true_market_demand", 1.0),
+            total_revenue=payload.get("total_revenue", 0.0),
+            total_spend=payload.get("total_spend", 0.0),
+            total_conversions=payload.get("total_conversions", 0),
+            compliance_violations=payload.get("compliance_violations", 0),
+            experiments_run=payload.get("experiments_run", 0),
+            useful_experiments=payload.get("useful_experiments", 0),
+        )

models.py

@@ -0,0 +1,135 @@
+"""Pydantic models for the GTM Strategy Optimizer environment."""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from openenv.core.env_server import Action, Observation, State
+
+
+# ── Sub-models for structured metrics ──────────────────────────────────────
+
+
+class ChannelMetrics(BaseModel):
+    """Performance metrics for a single marketing channel."""
+
+    impressions: int = 0
+    clicks: int = 0
+    conversions: int = 0
+    spend: float = 0.0
+    ctr: float = 0.0
+    cvr: float = 0.0
+    roi: float = 0.0
+
+
+class FunnelMetrics(BaseModel):
+    """Funnel-level metrics across all channels."""
+
+    visitors: int = 0
+    signups: int = 0
+    activations: int = 0
+    retained_users: int = 0
+    signup_rate: float = 0.0
+    activation_rate: float = 0.0
+    retention_rate: float = 0.0
+
+
+class SegmentMetrics(BaseModel):
+    """Performance metrics for a customer segment."""
+
+    conversion_rate: float = 0.0
+    engagement_score: float = 0.0
+    churn_rate: float = 0.0
+    revenue: float = 0.0
+
+
+class ExperimentResult(BaseModel):
+    """Result of a completed experiment."""
+
+    experiment_type: str
+    uplift_estimate: float
+    confidence: float
+    recommendation: str
+
+
+# ── Action ─────────────────────────────────────────────────────────────────
+
+
+class GTMAction(Action):
+    """Agent's weekly GTM decisions.
+
+    All allocation dicts map names to fractions (0.0-1.0).
+    Fractions in budget_allocation should sum to <= 1.0.
+    Fractions in segment_targeting and messaging should each sum to ~1.0.
+    """
+
+    budget_allocation: Dict[str, float] = Field(
+        default_factory=dict,
+        description="Channel name -> fraction of weekly budget to allocate",
+    )
+    segment_targeting: Dict[str, float] = Field(
+        default_factory=dict,
+        description="Segment name -> targeting weight (should sum to ~1.0)",
+    )
+    messaging: Dict[str, float] = Field(
+        default_factory=dict,
+        description="Messaging dimension -> emphasis weight. Dimensions: cost_savings, performance, reliability, innovation, ease_of_use, security",
+    )
+    experiment: Optional[str] = Field(
+        default=None,
+        description="Experiment to launch: 'ab_test_landing', 'ab_test_pricing', 'ab_test_creative', 'run_survey', 'competitor_analysis', or null",
+    )
+    pricing_action: Optional[str] = Field(
+        default=None,
+        description="Pricing change: 'discount_10', 'discount_20', 'raise_5', 'add_free_trial', or null",
+    )
+
+
+# ── Observation ────────────────────────────────────────────────────────────
+
+
+class GTMObservation(Observation):
+    """What the agent observes after each week of GTM activity."""
+
+    week: int = 0
+    total_weeks: int = 12
+    budget_remaining: float = 0.0
+    weekly_budget: float = 0.0
+
+    channel_metrics: Dict[str, ChannelMetrics] = Field(default_factory=dict)
+    funnel: FunnelMetrics = Field(default_factory=FunnelMetrics)
+    segment_performance: Dict[str, SegmentMetrics] = Field(default_factory=dict)
+
+    experiment_result: Optional[ExperimentResult] = None
+
+    brand_score: float = 50.0
+
+    total_revenue: float = 0.0
+    total_conversions: int = 0
+    average_cac: float = 0.0
+
+    available_channels: List[str] = Field(default_factory=list)
+    available_segments: List[str] = Field(default_factory=list)
+    available_experiments: List[str] = Field(default_factory=list)
+    available_pricing_actions: List[str] = Field(default_factory=list)
+    messaging_dimensions: List[str] = Field(default_factory=list)
+
+    message: str = ""
+
+
+# ── State ──────────────────────────────────────────────────────────────────
+
+
+class GTMState(State):
+    """Internal environment state (includes hidden ground truth)."""
+
+    task_id: str = "channel_optimizer"
+    difficulty: str = "easy"
+    true_brand_strength: float = 50.0
+    true_market_demand: float = 1.0
+    total_revenue: float = 0.0
+    total_spend: float = 0.0
+    total_conversions: int = 0
+    compliance_violations: int = 0
+    experiments_run: int = 0
+    useful_experiments: int = 0

openenv.yaml

@@ -0,0 +1,3 @@
+name: gtm-strategy-optimizer
+version: "1.0.0"
+description: "RL environment simulating Go-To-Market strategy optimization — budget allocation, ICP targeting, messaging, and experimentation under uncertainty"

prd.md

@@ -0,0 +1,615 @@
+# PRD + Design Doc
+
+# Autonomous GTM Strategy Optimizer (RL Environment)
+
+## 1. Objective
+
+Build a **reinforcement learning environment** that simulates the real-world Go-To-Market (GTM) lifecycle for launching and scaling a product.
+
+The environment must capture the complexity faced by real growth teams:
+
+* budget allocation across channels
+* ICP discovery
+* messaging optimization
+* funnel optimization
+* experimentation planning
+* tradeoff between short-term revenue vs long-term brand strength
+* noisy and delayed feedback
+* competitor reactions
+* market regime shifts
+
+The RL agent must learn a **policy that maximizes long-term business outcomes** under uncertainty and constraints.
+
+---
+
+# 2. Real-world task being simulated
+
+Human teams perform iterative GTM optimization:
+
+1. define positioning
+2. select customer segment
+3. allocate budget
+4. launch campaigns
+5. observe funnel metrics
+6. run experiments
+7. refine messaging
+8. reallocate budget
+9. scale successful channels
+10. adjust pricing/packaging
+
+The environment simulates:
+
+* imperfect attribution
+* delayed conversions
+* creative fatigue
+* nonlinear scaling effects
+* interactions between channels
+
+---
+
+# 3. Scope of environment
+
+Episode represents:
+
+> lifecycle of a product launch (12–52 timesteps)
+
+Each timestep simulates:
+
+> 1 week of GTM activity
+
+---
+
+# 4. Core entities in environment
+
+### Product
+
+```json
+{
+ category,
+ price_range,
+ complexity,
+ differentiation_strength,
+ maturity_stage
+}
+```
+
+### Market
+
+```json
+{
+ total_demand,
+ growth_rate,
+ noise_level,
+ competition_intensity,
+ seasonality_pattern
+}
+```
+
+### Customer segments
+
+example:
+
+```json
+[
+ {
+   name: "startup_founders",
+   price_sensitivity: high,
+   feature_preference_vector,
+   acquisition_channel_affinity,
+   churn_probability
+ }
+]
+```
+
+### Channels
+
+* paid search
+* paid social
+* organic content
+* outbound sales
+* partnerships
+* email lifecycle
+* influencer marketing
+
+Each channel has:
+
+```json
+{
+ base_ctr,
+ base_cvr,
+ saturation_point,
+ cost_curve,
+ response_variance
+}
+```
+
+---
+
+# 5. Environment inputs
+
+## static inputs
+
+### product description
+
+text embedding or structured attributes
+
+### initial market conditions
+
+### initial budget
+
+### initial ICP guess
+
+### campaign constraints
+
+---
+
+## dynamic observations per timestep
+
+### performance metrics
+
+```json
+{
+ impressions,
+ clicks,
+ conversions,
+ CAC,
+ revenue,
+ ROI
+}
+```
+
+### funnel metrics
+
+```json
+{
+ visitors,
+ signup_rate,
+ activation_rate,
+ retention_rate
+}
+```
+
+### segment performance
+
+```json
+{
+ segment_name,
+ conversion_rate,
+ engagement_score,
+ churn_rate
+}
+```
+
+### experiment results
+
+```json
+{
+ experiment_id,
+ uplift_estimate,
+ confidence,
+ sample_size
+}
+```
+
+### brand state
+
+latent variable:
+
+```json
+{
+ trust_score,
+ awareness_score,
+ positioning_consistency
+}
+```
+
+not directly observable; inferred via noisy proxy metrics.
+
+---
+
+# 6. State representation
+
+state is partially observable.
+
+true state:
+
+```json
+{
+ latent_market_demand,
+ true_segment_preferences,
+ competitor_strategy,
+ brand_strength,
+ channel_effectiveness_curves
+}
+```
+
+observed state:
+
+```json
+s_t = {
+ time_step,
+ budget_remaining,
+ channel_metrics,
+ funnel_metrics,
+ experiment_results,
+ estimated_segment_response,
+ historical_actions
+}
+```
+
+state representation can be encoded as:
+
+* structured tensor
+* graph of relationships
+* time series embedding
+
+---
+
+# 7. Action space
+
+multi-discrete or parameterized actions.
+
+agent chooses set of actions each timestep.
+
+---
+
+## A. budget allocation actions
+
+continuous:
+
+```json
+allocate_budget(channel_i, amount)
+```
+
+constraint:
+
+```json
+sum(budget_i) <= budget_remaining
+```
+
+---
+
+## B. ICP targeting actions
+
+discrete:
+
+* select target segment
+* adjust segment weighting
+
+example:
+
+```json
+{
+ startup_founders: 0.6,
+ enterprises: 0.3,
+ smb: 0.1
+}
+```
+
+---
+
+## C. messaging actions
+
+agent selects messaging vector:
+
+dimensions:
+
+* cost savings
+* performance
+* reliability
+* innovation
+* ease of use
+* security
+
+example:
+
+```json
+message_vector = [0.2, 0.5, 0.1, 0.1, 0.05, 0.05]
+```
+
+---
+
+## D. experimentation actions
+
+agent can:
+
+* launch A/B test
+* change landing page variant
+* test pricing tier
+* test creative
+
+cost incurred:
+
+budget + delay.
+
+---
+
+## E. pricing actions
+
+* adjust price
+* introduce discount
+* introduce tier
+* change free trial duration
+
+---
+
+## F. information gathering actions
+
+agent can call simulated tools:
+
+### tools
+
+* run survey
+* analyze cohort
+* competitor intelligence query
+* attribution analysis
+
+these reduce uncertainty but cost time/budget.
+
+---
+
+# 8. Legal action constraints
+
+environment enforces compliance constraints:
+
+## disallowed actions
+
+* discriminatory targeting
+* false claims
+* privacy violations
+* prohibited data usage
+* dark patterns
+
+violations incur heavy penalty:
+
+```python
+reward -= compliance_penalty
+```
+
+example constraints:
+
+### privacy
+
+cannot use sensitive attributes:
+
+* race
+* religion
+* health status
+
+### advertising standards
+
+cannot claim:
+
+* false performance metrics
+* fabricated testimonials
+
+---
+
+# 9. Transition dynamics
+
+environment simulates market response.
+
+## demand generation
+
+```math
+conversions =
+demand(segment)
+× channel_effectiveness(channel, segment)
+× message_alignment(message, segment)
+× brand_strength
+× noise
+```
+
+---
+
+## diminishing returns
+
+channel effectiveness decreases as spend increases:
+
+```math
+effectiveness = base * exp(-alpha * spend)
+```
+
+---
+
+## delayed reward dynamics
+
+brand strength evolves:
+
+```math
+brand_{t+1} =
+brand_t
++ beta * consistency_score
+- gamma * messaging_variance
+```
+
+---
+
+## competitor response
+
+optional module:
+
+competitor reacts:
+
+* price drop
+* increased ad spend
+* new messaging
+
+---
+
+# 10. Reward function
+
+multi-objective.
+
+primary:
+
+```math
+reward =
+w1 * revenue
++ w2 * conversions
+- w3 * CAC
+```
+
+secondary:
+
+```math
++ w4 * brand_strength
++ w5 * experimentation_efficiency
+```
+
+penalties:
+
+```math
+- w6 * budget_waste
+- w7 * compliance_violation
+```
+
+long-term reward accumulation:
+
+episodic return.
+
+---
+
+# 11. Policy design
+
+agent learns:
+
+```math
+π(a|s)
+```
+
+policy architecture options:
+
+### baseline
+
+MLP with structured inputs.
+
+### advanced
+
+transformer over time series:
+
+input:
+
+```math
+[s_1, s_2, ..., s_t]
+```
+
+captures temporal dependencies.
+
+---
+
+## hierarchical policy option
+
+high level:
+
+decide strategy direction every K steps.
+
+low level:
+
+execute weekly actions.
+
+---
+
+# 12. Evaluation metrics
+
+agent performance evaluated across:
+
+## financial metrics
+
+* cumulative revenue
+* CAC
+* LTV
+* ROI
+
+## efficiency metrics
+
+* time to product-market fit
+* experimentation efficiency
+* budget utilization efficiency
+
+## robustness metrics
+
+performance under:
+
+* noisy markets
+* demand shocks
+* competitor shifts
+
+---
+
+# 13. Difficulty scaling
+
+environment difficulty configurable:
+
+| parameter           | effect                   |
+| ------------------- | ------------------------ |
+| noise level         | harder signal extraction |
+| attribution error   | harder credit assignment |
+| demand volatility   | harder planning          |
+| budget size         | resource constraint      |
+| competitor strength | adversarial dynamics     |
+
+---
+
+# 14. Extensions (optional)
+
+## multi-agent version
+
+agents:
+
+* growth strategist
+* performance marketer
+* brand manager
+
+must coordinate.
+
+---
+
+## LLM-powered environment components
+
+LLM simulates:
+
+* customer feedback
+* survey responses
+* qualitative insights
+
+---
+
+## causal structure
+
+introduce structural causal graph:
+
+message → perception → conversion.
+
+agent must discover relationships.
+
+---
+
+# 15. Deliverables
+
+## core
+
+* gym environment
+* baseline policy
+* evaluation benchmark
+* visualization dashboard
+
+## documentation
+
+* state schema
+* action definitions
+* reward function
+* environment dynamics
+
+---
+
+If useful next, I can provide:
+
+1. exact state tensor structure
+2. reward function code
+3. transition simulator pseudocode
+4. baseline PPO implementation
+5. architecture diagram
+6. realistic parameter ranges
+7. ablation ideas to impress judges
+

pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gtm-strategy-optimizer"
+version = "1.0.0"
+description = "OpenEnv RL environment for Go-To-Market strategy optimization"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core>=0.2.2",
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+    "pydantic>=2.0.0",
+    "websockets>=15.0.1",
+    "openai>=1.0.0",
+    "numpy>=1.24.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["gtm_env*", "server*"]

requirements.txt

@@ -0,0 +1,7 @@
+openenv-core>=0.2.2
+fastapi>=0.104.0
+uvicorn>=0.24.0
+pydantic>=2.0.0
+websockets>=15.0.1
+openai>=1.0.0
+numpy>=1.24.0

server/Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install git for openenv-core from GitHub
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

server/app.py

@@ -0,0 +1,177 @@
+"""FastAPI application for the GTM Strategy Optimizer environment."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Ensure parent directory is on path for imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from typing import Optional
+
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+from openenv.core.env_server import create_fastapi_app
+
+from models import GTMAction, GTMObservation
+from server.environment import GTMEnvironment
+from server.tasks import TASKS
+from server.simulation import MESSAGING_DIMS
+
+# Create the core OpenEnv app
+app = create_fastapi_app(GTMEnvironment, GTMAction, GTMObservation)
+
+
+# ── Custom endpoints required by the hackathon ─────────────────────────────
+
+
+class TaskInfo(BaseModel):
+    task_id: str
+    name: str
+    difficulty: str
+    description: str
+    total_weeks: int
+    total_budget: float
+    channels: list[str]
+    segments: list[str]
+    messaging_dimensions: list[str]
+    available_experiments: list[str]
+    available_pricing_actions: list[str]
+    action_schema: dict
+
+
+@app.get("/tasks")
+def list_tasks() -> list[TaskInfo]:
+    """Return list of tasks and the action schema."""
+    result = []
+    for task_id, t in TASKS.items():
+        result.append(
+            TaskInfo(
+                task_id=task_id,
+                name=t.name,
+                difficulty=t.difficulty,
+                description=t.description,
+                total_weeks=t.total_weeks,
+                total_budget=t.total_budget,
+                channels=[c.name for c in t.channels],
+                segments=[s.name for s in t.segments],
+                messaging_dimensions=MESSAGING_DIMS,
+                available_experiments=t.available_experiments,
+                available_pricing_actions=t.available_pricing_actions,
+                action_schema={
+                    "budget_allocation": {
+                        "type": "object",
+                        "description": "channel_name -> fraction of weekly budget (sum <= 1.0)",
+                        "keys": [c.name for c in t.channels],
+                    },
+                    "segment_targeting": {
+                        "type": "object",
+                        "description": "segment_name -> weight (should sum to ~1.0)",
+                        "keys": [s.name for s in t.segments],
+                    },
+                    "messaging": {
+                        "type": "object",
+                        "description": "dimension -> weight (should sum to ~1.0)",
+                        "keys": MESSAGING_DIMS,
+                    },
+                    "experiment": {
+                        "type": "string|null",
+                        "options": t.available_experiments,
+                    },
+                    "pricing_action": {
+                        "type": "string|null",
+                        "options": t.available_pricing_actions,
+                    },
+                },
+            )
+        )
+    return result
+
+
+class GraderRequest(BaseModel):
+    task_id: str
+    episode_id: str
+
+
+class GraderResponse(BaseModel):
+    task_id: str
+    episode_id: str
+    score: Optional[float]
+    message: str
+
+
+@app.post("/grader")
+def run_grader(req: GraderRequest) -> GraderResponse:
+    """Return grader score after an episode is completed.
+
+    Note: In a full production setup, this would look up completed episodes.
+    For the hackathon, we run a quick deterministic episode if needed.
+    """
+    if req.task_id not in TASKS:
+        raise HTTPException(status_code=400, detail=f"Unknown task_id: {req.task_id}")
+
+    # Run a deterministic episode to produce a grader score
+    from server.tasks import create_simulator, get_task
+
+    task_def = get_task(req.task_id)
+    sim = create_simulator(req.task_id, seed=42)
+
+    # Simple heuristic agent: equal allocation
+    channels = list(sim.channels.keys())
+    segments = list(sim.segments.keys())
+    equal_budget = {ch: 1.0 / len(channels) for ch in channels}
+    equal_segments = {seg: 1.0 / len(segments) for seg in segments}
+    equal_messaging = {dim: 1.0 / len(MESSAGING_DIMS) for dim in MESSAGING_DIMS}
+
+    while not sim.is_done:
+        sim.step(
+            budget_allocation=equal_budget,
+            segment_targeting=equal_segments,
+            messaging=equal_messaging,
+        )
+
+    score = task_def.grader(sim.state)
+    return GraderResponse(
+        task_id=req.task_id,
+        episode_id=req.episode_id,
+        score=score,
+        message=f"Grader score for {task_def.name}: {score:.4f}",
+    )
+
+
+class BaselineResponse(BaseModel):
+    scores: dict[str, float]
+    message: str
+
+
+@app.post("/baseline")
+def run_baseline() -> BaselineResponse:
+    """Run a deterministic heuristic baseline and return scores for all 3 tasks."""
+    from server.tasks import create_simulator, get_task
+
+    scores = {}
+    for task_id in TASKS:
+        task_def = get_task(task_id)
+        sim = create_simulator(task_id, seed=42)
+
+        channels = list(sim.channels.keys())
+        segments = list(sim.segments.keys())
+        equal_budget = {ch: 1.0 / len(channels) for ch in channels}
+        equal_segments = {seg: 1.0 / len(segments) for seg in segments}
+        equal_messaging = {dim: 1.0 / len(MESSAGING_DIMS) for dim in MESSAGING_DIMS}
+
+        while not sim.is_done:
+            sim.step(
+                budget_allocation=equal_budget,
+                segment_targeting=equal_segments,
+                messaging=equal_messaging,
+            )
+
+        scores[task_id] = task_def.grader(sim.state)
+
+    return BaselineResponse(
+        scores=scores,
+        message="Baseline (equal-allocation heuristic) scores for all tasks",
+    )

server/environment.py

@@ -0,0 +1,252 @@
+"""GTM Strategy Optimizer — OpenEnv Environment implementation."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Optional
+
+from openenv.core.env_server import Environment
+
+from models import (
+    ChannelMetrics,
+    ExperimentResult,
+    FunnelMetrics,
+    GTMAction,
+    GTMObservation,
+    GTMState,
+    SegmentMetrics,
+)
+from server.simulation import EXPERIMENT_TYPES, MESSAGING_DIMS, PRICING_ACTIONS
+from server.tasks import create_simulator, get_task, TASKS
+
+
+class GTMEnvironment(Environment):
+    """OpenEnv environment simulating Go-To-Market strategy optimization.
+
+    Each episode represents a product launch lifecycle. The agent makes weekly
+    decisions about budget allocation, customer targeting, messaging, experiments,
+    and pricing to maximize revenue under uncertainty.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        self._state = GTMState()
+        self._sim = None
+        self._task_def = None
+        self._grader_scores: dict[str, float] = {}
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        task_id: str = "channel_optimizer",
+        **kwargs: Any,
+    ) -> GTMObservation:
+        """Start a new GTM episode for the given task."""
+        task_def = get_task(task_id)
+        self._task_def = task_def
+        self._sim = create_simulator(task_id, seed=seed)
+
+        self._state = GTMState(
+            episode_id=episode_id or str(uuid.uuid4()),
+            step_count=0,
+            task_id=task_id,
+            difficulty=task_def.difficulty,
+            true_brand_strength=50.0,
+            true_market_demand=1.0,
+            total_revenue=0.0,
+            total_spend=0.0,
+            total_conversions=0,
+            compliance_violations=0,
+            experiments_run=0,
+            useful_experiments=0,
+        )
+
+        s = self._sim.state
+        channels = list(self._sim.channels.keys())
+        segments = list(self._sim.segments.keys())
+
+        return GTMObservation(
+            done=False,
+            reward=None,
+            week=0,
+            total_weeks=s.total_weeks,
+            budget_remaining=s.budget_remaining,
+            weekly_budget=s.weekly_budget,
+            channel_metrics={ch: ChannelMetrics() for ch in channels},
+            funnel=FunnelMetrics(),
+            segment_performance={seg: SegmentMetrics() for seg in segments},
+            experiment_result=None,
+            brand_score=50.0,
+            total_revenue=0.0,
+            total_conversions=0,
+            average_cac=0.0,
+            available_channels=channels,
+            available_segments=segments,
+            available_experiments=self._task_def.available_experiments,
+            available_pricing_actions=self._task_def.available_pricing_actions,
+            messaging_dimensions=MESSAGING_DIMS,
+            message=self._initial_message(task_def),
+        )
+
+    def step(
+        self,
+        action: GTMAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> GTMObservation:
+        """Execute one week of GTM activity."""
+        if self._sim is None:
+            raise RuntimeError("Must call reset() before step()")
+
+        self._state.step_count += 1
+
+        # Run simulation step
+        result = self._sim.step(
+            budget_allocation=action.budget_allocation,
+            segment_targeting=action.segment_targeting,
+            messaging=action.messaging,
+            experiment=action.experiment if action.experiment in self._task_def.available_experiments else None,
+            pricing_action=action.pricing_action if action.pricing_action in self._task_def.available_pricing_actions else None,
+        )
+
+        s = self._sim.state
+        done = self._sim.is_done
+
+        # Update internal state
+        self._state.true_brand_strength = s.brand_strength
+        self._state.true_market_demand = s.market_demand
+        self._state.total_revenue = s.total_revenue
+        self._state.total_spend = s.total_spend
+        self._state.total_conversions = s.total_conversions
+        self._state.compliance_violations = s.compliance_violations
+        self._state.experiments_run = s.experiments_run
+        self._state.useful_experiments = s.useful_experiments
+
+        # Compute step reward (partial progress signal)
+        reward = self._compute_reward(result, s)
+
+        # If episode done, also compute and store grader score
+        if done:
+            grader_score = self._task_def.grader(s)
+            self._grader_scores[self._state.episode_id] = grader_score
+
+        # Build observation
+        channel_metrics = {
+            ch: ChannelMetrics(**m) for ch, m in result["channel_metrics"].items()
+        }
+        funnel = FunnelMetrics(**result["funnel"])
+        segment_perf = {
+            seg: SegmentMetrics(**m) for seg, m in result["segment_performance"].items()
+        }
+        exp_result = None
+        if result["experiment_result"]:
+            exp_result = ExperimentResult(**result["experiment_result"])
+
+        avg_cac = s.total_spend / max(s.total_conversions, 1)
+
+        return GTMObservation(
+            done=done,
+            reward=round(reward, 4),
+            week=s.week,
+            total_weeks=s.total_weeks,
+            budget_remaining=round(s.budget_remaining, 2),
+            weekly_budget=round(s.weekly_budget, 2),
+            channel_metrics=channel_metrics,
+            funnel=funnel,
+            segment_performance=segment_perf,
+            experiment_result=exp_result,
+            brand_score=result["brand_score_observed"],
+            total_revenue=round(s.total_revenue, 2),
+            total_conversions=s.total_conversions,
+            average_cac=round(avg_cac, 2),
+            available_channels=list(self._sim.channels.keys()),
+            available_segments=list(self._sim.segments.keys()),
+            available_experiments=self._task_def.available_experiments,
+            available_pricing_actions=self._task_def.available_pricing_actions,
+            messaging_dimensions=MESSAGING_DIMS,
+            message=self._step_message(result, s, done),
+        )
+
+    @property
+    def state(self) -> GTMState:
+        return self._state
+
+    def get_grader_score(self, episode_id: str) -> Optional[float]:
+        """Get the grader score for a completed episode."""
+        return self._grader_scores.get(episode_id)
+
+    # ── Private helpers ────────────────────────────────────────────
+
+    def _compute_reward(self, result: dict, s) -> float:
+        """Per-step reward with partial progress signal."""
+        weekly_rev = result["weekly_revenue"]
+        target_weekly = self._task_def.revenue_target / self._task_def.total_weeks
+
+        # revenue component (0-0.5)
+        rev_reward = min(0.5, 0.5 * weekly_rev / max(target_weekly, 1.0))
+
+        # efficiency bonus (0-0.2)
+        weekly_spend = sum(
+            m.get("spend", 0.0) for m in result["channel_metrics"].values()
+        )
+        if weekly_spend > 0:
+            roi = weekly_rev / weekly_spend
+            eff_reward = min(0.2, 0.2 * roi / 3.0)
+        else:
+            eff_reward = 0.0
+
+        # brand maintenance (0-0.15)
+        brand_reward = 0.15 * (s.brand_strength / 100.0)
+
+        # penalties
+        waste_penalty = 0.0
+        for ch_name, m in result["channel_metrics"].items():
+            if m.get("spend", 0) > 100 and m.get("conversions", 0) == 0:
+                waste_penalty += 0.05
+
+        compliance_penalty = s.compliance_violations * 0.1
+
+        reward = rev_reward + eff_reward + brand_reward - waste_penalty - compliance_penalty
+        return max(-1.0, min(1.0, reward))
+
+    def _initial_message(self, task_def) -> str:
+        channels = ", ".join(c.name for c in task_def.channels)
+        segments = ", ".join(s.name for s in task_def.segments)
+        return (
+            f"Welcome to the GTM Strategy Optimizer — Task: {task_def.name} ({task_def.difficulty})\n"
+            f"\n"
+            f"{task_def.description}\n"
+            f"\n"
+            f"Duration: {task_def.total_weeks} weeks | Budget: ${task_def.total_budget:,.0f} "
+            f"(${task_def.total_budget / task_def.total_weeks:,.0f}/week)\n"
+            f"Channels: {channels}\n"
+            f"Segments: {segments}\n"
+            f"Product price: ${task_def.product.base_price:.0f}\n"
+            f"\n"
+            f"Allocate your budget wisely across channels and segments. "
+            f"Craft messaging that resonates with your target customers. "
+            f"Maximize revenue while building brand strength."
+        )
+
+    def _step_message(self, result: dict, s, done: bool) -> str:
+        weekly_rev = result["weekly_revenue"]
+        parts = [f"Week {s.week}/{s.total_weeks} | Revenue this week: ${weekly_rev:,.0f}"]
+        parts.append(
+            f"Cumulative: ${s.total_revenue:,.0f} revenue, "
+            f"{s.total_conversions} conversions, "
+            f"${s.budget_remaining:,.0f} budget remaining"
+        )
+        parts.append(f"Brand health: {result['brand_score_observed']:.0f}/100")
+
+        if result["experiment_result"]:
+            er = result["experiment_result"]
+            parts.append(f"Experiment result: {er['recommendation']}")
+
+        if done:
+            grader = self._task_def.grader(s)
+            parts.append(f"\nEpisode complete! Final grader score: {grader:.4f}")
+
+        return " | ".join(parts) if not done else "\n".join(parts)

server/simulation.py

@@ -0,0 +1,473 @@
+"""Market dynamics simulation engine for the GTM environment."""
+
+from __future__ import annotations
+
+import math
+import random
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+
+# ── Channel configuration ──────────────────────────────────────────────────
+
+
+@dataclass
+class ChannelConfig:
+    """Static properties of a marketing channel."""
+
+    name: str
+    base_ctr: float  # base click-through rate
+    base_cvr: float  # base conversion rate
+    saturation_alpha: float  # diminishing returns steepness
+    cost_per_impression: float  # cost per 1k impressions
+    min_spend_for_signal: float  # minimum spend to get any data
+    # affinity per segment (segment_name -> multiplier 0-2)
+    segment_affinity: Dict[str, float] = field(default_factory=dict)
+
+
+@dataclass
+class SegmentConfig:
+    """Static properties of a customer segment."""
+
+    name: str
+    size: float  # relative market size
+    price_sensitivity: float  # 0-1, higher = more price sensitive
+    # preferred messaging dimensions (dim -> ideal weight)
+    message_preference: Dict[str, float] = field(default_factory=dict)
+    base_churn: float = 0.05
+
+
+@dataclass
+class ProductConfig:
+    """Product being marketed."""
+
+    base_price: float = 99.0
+    differentiation: float = 0.7  # 0-1
+    complexity: float = 0.4  # 0-1
+
+
+# ── Simulation state ───────────────────────────────────────────────────────
+
+
+@dataclass
+class SimState:
+    """Mutable simulation state tracking all dynamics."""
+
+    week: int = 0
+    total_weeks: int = 12
+    budget_remaining: float = 50000.0
+    weekly_budget: float = 5000.0
+
+    # true latent variables
+    brand_strength: float = 50.0  # 0-100
+    market_demand: float = 1.0  # multiplier
+    competitor_aggression: float = 0.0  # 0-1
+
+    # cumulative metrics
+    total_revenue: float = 0.0
+    total_spend: float = 0.0
+    total_conversions: int = 0
+    total_impressions: int = 0
+
+    # channel cumulative spend (for diminishing returns)
+    channel_cumulative_spend: Dict[str, float] = field(default_factory=dict)
+
+    # messaging history (for consistency tracking)
+    messaging_history: List[Dict[str, float]] = field(default_factory=list)
+
+    # experiment state
+    pending_experiment: Optional[Tuple[str, int]] = None  # (type, completion_week)
+    experiments_run: int = 0
+    useful_experiments: int = 0
+
+    # pricing state
+    current_discount: float = 0.0
+    has_free_trial: bool = False
+
+    # compliance
+    compliance_violations: int = 0
+
+    # per-week tracking for grading
+    weekly_revenues: List[float] = field(default_factory=list)
+    weekly_brand_scores: List[float] = field(default_factory=list)
+
+
+MESSAGING_DIMS = [
+    "cost_savings",
+    "performance",
+    "reliability",
+    "innovation",
+    "ease_of_use",
+    "security",
+]
+
+EXPERIMENT_TYPES = [
+    "ab_test_landing",
+    "ab_test_pricing",
+    "ab_test_creative",
+    "run_survey",
+    "competitor_analysis",
+]
+
+PRICING_ACTIONS = [
+    "discount_10",
+    "discount_20",
+    "raise_5",
+    "add_free_trial",
+]
+
+
+# ── Market Simulator ───────────────────────────────────────────────────────
+
+
+class MarketSimulator:
+    """Simulates market response to GTM actions for one episode."""
+
+    def __init__(
+        self,
+        channels: List[ChannelConfig],
+        segments: List[SegmentConfig],
+        product: ProductConfig,
+        total_weeks: int = 12,
+        total_budget: float = 50000.0,
+        noise_level: float = 0.1,
+        enable_competitor: bool = False,
+        enable_regime_shifts: bool = False,
+        seed: Optional[int] = None,
+    ):
+        self.channels = {c.name: c for c in channels}
+        self.segments = {s.name: s for s in segments}
+        self.product = product
+        self.noise_level = noise_level
+        self.enable_competitor = enable_competitor
+        self.enable_regime_shifts = enable_regime_shifts
+        self.rng = random.Random(seed)
+
+        weekly_budget = total_budget / total_weeks
+        self.state = SimState(
+            total_weeks=total_weeks,
+            budget_remaining=total_budget,
+            weekly_budget=weekly_budget,
+            channel_cumulative_spend={c.name: 0.0 for c in channels},
+        )
+
+    def reset(self, seed: Optional[int] = None) -> SimState:
+        """Reset to initial state."""
+        if seed is not None:
+            self.rng = random.Random(seed)
+        total_budget = self.state.weekly_budget * self.state.total_weeks
+        self.state = SimState(
+            total_weeks=self.state.total_weeks,
+            budget_remaining=total_budget,
+            weekly_budget=total_budget / self.state.total_weeks,
+            channel_cumulative_spend={c: 0.0 for c in self.channels},
+        )
+        return self.state
+
+    def step(
+        self,
+        budget_allocation: Dict[str, float],
+        segment_targeting: Dict[str, float],
+        messaging: Dict[str, float],
+        experiment: Optional[str] = None,
+        pricing_action: Optional[str] = None,
+    ) -> Dict:
+        """Advance one week and return metrics.
+
+        Returns dict with keys:
+            channel_metrics, funnel, segment_performance,
+            experiment_result, brand_score_observed, weekly_revenue
+        """
+        s = self.state
+        s.week += 1
+
+        # ── Apply pricing action ───────────────────────────────────
+        self._apply_pricing(pricing_action)
+
+        # ── Budget spend ───────────────────────────────────────────
+        total_alloc = sum(budget_allocation.values())
+        if total_alloc > 1.0:
+            # normalize
+            factor = 1.0 / total_alloc
+            budget_allocation = {k: v * factor for k, v in budget_allocation.items()}
+
+        weekly_spend = min(s.weekly_budget, s.budget_remaining)
+        channel_spends = {}
+        for ch_name, frac in budget_allocation.items():
+            if ch_name in self.channels:
+                channel_spends[ch_name] = frac * weekly_spend
+
+        actual_total_spend = sum(channel_spends.values())
+        s.budget_remaining -= actual_total_spend
+        s.total_spend += actual_total_spend
+
+        # ── Normalize targeting & messaging ────────────────────────
+        segment_targeting = self._normalize_weights(
+            segment_targeting, list(self.segments.keys())
+        )
+        messaging = self._normalize_weights(messaging, MESSAGING_DIMS)
+        s.messaging_history.append(messaging.copy())
+
+        # ── Compute channel performance ────────────────────────────
+        channel_metrics = {}
+        total_visitors = 0
+        total_signups = 0
+        total_activations = 0
+        segment_conversions: Dict[str, float] = {seg: 0.0 for seg in self.segments}
+        segment_revenue: Dict[str, float] = {seg: 0.0 for seg in self.segments}
+        segment_engagement: Dict[str, float] = {seg: 0.0 for seg in self.segments}
+        weekly_revenue = 0.0
+
+        for ch_name, ch_cfg in self.channels.items():
+            spend = channel_spends.get(ch_name, 0.0)
+            s.channel_cumulative_spend[ch_name] += spend
+
+            if spend < ch_cfg.min_spend_for_signal:
+                channel_metrics[ch_name] = {
+                    "impressions": 0, "clicks": 0, "conversions": 0,
+                    "spend": spend, "ctr": 0.0, "cvr": 0.0, "roi": 0.0,
+                }
+                continue
+
+            # impressions from spend (cost_per_impression is CPM)
+            # Apply diminishing returns: more spend -> higher effective CPM
+            cumulative = s.channel_cumulative_spend[ch_name]
+            diminishing = math.exp(-ch_cfg.saturation_alpha * cumulative / 100000)
+            # Weekly spend also has diminishing returns (audience saturation)
+            weekly_diminishing = 1.0 / (1.0 + spend / 2000.0)
+            effective_impressions = spend / ch_cfg.cost_per_impression * 1000 * weekly_diminishing * diminishing
+            impressions = int(max(0, effective_impressions))
+
+            # compute per-segment clicks and conversions
+            ch_clicks = 0
+            ch_conversions = 0
+            ch_revenue = 0.0
+            for seg_name, seg_cfg in self.segments.items():
+                seg_weight = segment_targeting.get(seg_name, 0.0)
+                if seg_weight < 0.01:
+                    continue
+
+                seg_impressions = int(impressions * seg_weight)
+                affinity = ch_cfg.segment_affinity.get(seg_name, 1.0)
+                msg_alignment = self._message_alignment(messaging, seg_cfg)
+                brand_mult = s.brand_strength / 100.0
+
+                eff_ctr = (
+                    ch_cfg.base_ctr
+                    * affinity
+                    * brand_mult
+                    * s.market_demand
+                    * (1.0 + self._noise(0.1))
+                )
+                eff_cvr = (
+                    ch_cfg.base_cvr
+                    * msg_alignment
+                    * self.product.differentiation
+                    * (1.0 + self._noise(0.1))
+                )
+
+                clicks = int(seg_impressions * min(eff_ctr, 0.5))
+                convs = int(clicks * min(eff_cvr, 0.8))
+
+                # revenue per conversion
+                price = self.product.base_price * (1.0 - s.current_discount)
+                price_mult = 1.0 - seg_cfg.price_sensitivity * s.current_discount * 0.5
+                rev = convs * price * max(price_mult, 0.3)
+
+                ch_clicks += clicks
+                ch_conversions += convs
+                ch_revenue += rev
+                segment_conversions[seg_name] += convs
+                segment_revenue[seg_name] += rev
+                segment_engagement[seg_name] += clicks * 0.01
+
+            ctr = ch_clicks / max(impressions, 1)
+            cvr = ch_conversions / max(ch_clicks, 1)
+            roi = (ch_revenue - spend) / max(spend, 1.0)
+
+            channel_metrics[ch_name] = {
+                "impressions": impressions,
+                "clicks": ch_clicks,
+                "conversions": ch_conversions,
+                "spend": round(spend, 2),
+                "ctr": round(ctr, 4),
+                "cvr": round(cvr, 4),
+                "roi": round(roi, 4),
+            }
+
+            total_visitors += ch_clicks
+            total_signups += ch_conversions
+            weekly_revenue += ch_revenue
+            s.total_conversions += ch_conversions
+
+        # ── Funnel metrics ─────────────────────────────────────────
+        total_activations = int(total_signups * 0.6 * (1 + self._noise(0.05)))
+        retained = int(total_activations * 0.7 * (1 + self._noise(0.05)))
+        funnel = {
+            "visitors": total_visitors,
+            "signups": total_signups,
+            "activations": total_activations,
+            "retained_users": retained,
+            "signup_rate": round(total_signups / max(total_visitors, 1), 4),
+            "activation_rate": round(total_activations / max(total_signups, 1), 4),
+            "retention_rate": round(retained / max(total_activations, 1), 4),
+        }
+
+        # ── Segment performance ────────────────────────────────────
+        segment_performance = {}
+        for seg_name in self.segments:
+            total_seg_imp = max(
+                sum(
+                    channel_metrics.get(ch, {}).get("impressions", 0)
+                    * segment_targeting.get(seg_name, 0.0)
+                    for ch in self.channels
+                ),
+                1,
+            )
+            conv_rate = segment_conversions[seg_name] / total_seg_imp
+            segment_performance[seg_name] = {
+                "conversion_rate": round(conv_rate, 6),
+                "engagement_score": round(min(segment_engagement[seg_name], 100.0), 2),
+                "churn_rate": round(self.segments[seg_name].base_churn * (1 + self._noise(0.1)), 4),
+                "revenue": round(segment_revenue[seg_name], 2),
+            }
+
+        # ── Brand evolution ────────────────────────────────────────
+        consistency = self._messaging_consistency()
+        organic_boost = sum(
+            channel_spends.get(ch, 0.0)
+            for ch in self.channels
+            if "organic" in ch or "content" in ch
+        ) / max(weekly_spend, 1.0)
+        s.brand_strength = min(100.0, max(0.0,
+            s.brand_strength
+            + 0.5 * consistency
+            + 0.3 * organic_boost
+            - 0.2 * (1.0 - consistency)
+            + self._noise(0.3)
+        ))
+        brand_observed = s.brand_strength + self._noise(5.0) * self.noise_level * 10
+        brand_observed = max(0.0, min(100.0, brand_observed))
+
+        # ── Competitor response (hard mode) ────────────────────────
+        if self.enable_competitor and s.week > 4:
+            if weekly_revenue > s.total_revenue / max(s.week - 1, 1) * 1.2:
+                s.competitor_aggression = min(1.0, s.competitor_aggression + 0.1)
+                s.market_demand *= max(0.9, 1.0 - s.competitor_aggression * 0.05)
+
+        # ── Market regime shifts (hard mode) ───────────────────────
+        if self.enable_regime_shifts:
+            if s.week in (12, 24):
+                shift = self.rng.uniform(-0.3, 0.3)
+                s.market_demand = max(0.5, min(1.5, s.market_demand + shift))
+
+        # ── Experiment processing ──────────────────────────────────
+        experiment_result = None
+        if experiment and experiment in EXPERIMENT_TYPES:
+            exp_cost = weekly_spend * 0.1
+            s.budget_remaining -= exp_cost
+            s.total_spend += exp_cost
+            s.experiments_run += 1
+            s.pending_experiment = (experiment, s.week + 2)
+
+        if s.pending_experiment and s.week >= s.pending_experiment[1]:
+            exp_type = s.pending_experiment[0]
+            uplift = self.rng.uniform(-0.05, 0.15)
+            confidence = self.rng.uniform(0.6, 0.95)
+            useful = uplift > 0.02 and confidence > 0.75
+            if useful:
+                s.useful_experiments += 1
+            experiment_result = {
+                "experiment_type": exp_type,
+                "uplift_estimate": round(uplift, 4),
+                "confidence": round(confidence, 4),
+                "recommendation": (
+                    f"Adopt variant — {uplift:.1%} uplift at {confidence:.0%} confidence"
+                    if useful
+                    else f"No significant uplift detected ({uplift:.1%} at {confidence:.0%} confidence)"
+                ),
+            }
+            s.pending_experiment = None
+
+        # ── Update cumulative ──────────────────────────────────────
+        s.total_revenue += weekly_revenue
+        s.weekly_revenues.append(weekly_revenue)
+        s.weekly_brand_scores.append(s.brand_strength)
+
+        return {
+            "channel_metrics": channel_metrics,
+            "funnel": funnel,
+            "segment_performance": segment_performance,
+            "experiment_result": experiment_result,
+            "brand_score_observed": round(brand_observed, 1),
+            "weekly_revenue": round(weekly_revenue, 2),
+        }
+
+    # ── Helpers ────────────────────────────────────────────────────
+
+    def _noise(self, scale: float) -> float:
+        return self.rng.gauss(0, scale * self.noise_level)
+
+    def _normalize_weights(
+        self, weights: Dict[str, float], valid_keys: List[str]
+    ) -> Dict[str, float]:
+        filtered = {k: max(v, 0.0) for k, v in weights.items() if k in valid_keys}
+        total = sum(filtered.values())
+        if total < 0.01:
+            # equal distribution
+            n = len(valid_keys)
+            return {k: 1.0 / n for k in valid_keys}
+        return {k: v / total for k, v in filtered.items()}
+
+    def _message_alignment(
+        self, messaging: Dict[str, float], segment: SegmentConfig
+    ) -> float:
+        """Cosine-like alignment between messaging and segment preference."""
+        dot = 0.0
+        mag_m = 0.0
+        mag_s = 0.0
+        for dim in MESSAGING_DIMS:
+            m = messaging.get(dim, 0.0)
+            s = segment.message_preference.get(dim, 1.0 / len(MESSAGING_DIMS))
+            dot += m * s
+            mag_m += m * m
+            mag_s += s * s
+        if mag_m < 1e-9 or mag_s < 1e-9:
+            return 0.5
+        return dot / (math.sqrt(mag_m) * math.sqrt(mag_s))
+
+    def _messaging_consistency(self) -> float:
+        """How consistent messaging has been over recent weeks."""
+        history = self.state.messaging_history
+        if len(history) < 2:
+            return 1.0
+        recent = history[-min(4, len(history)):]
+        # compute variance across dimensions
+        total_var = 0.0
+        for dim in MESSAGING_DIMS:
+            vals = [m.get(dim, 0.0) for m in recent]
+            mean = sum(vals) / len(vals)
+            var = sum((v - mean) ** 2 for v in vals) / len(vals)
+            total_var += var
+        # low variance = high consistency
+        return max(0.0, 1.0 - total_var * 10)
+
+    def _apply_pricing(self, pricing_action: Optional[str]) -> None:
+        s = self.state
+        if pricing_action == "discount_10":
+            s.current_discount = 0.10
+        elif pricing_action == "discount_20":
+            s.current_discount = 0.20
+        elif pricing_action == "raise_5":
+            s.current_discount = max(0.0, s.current_discount - 0.05)
+        elif pricing_action == "add_free_trial":
+            s.has_free_trial = True
+            # free trial boosts conversions via brand
+            s.brand_strength = min(100.0, s.brand_strength + 1.0)
+
+    @property
+    def is_done(self) -> bool:
+        return (
+            self.state.week >= self.state.total_weeks
+            or self.state.budget_remaining <= 0
+        )

server/tasks.py

@@ -0,0 +1,399 @@
+"""Task definitions and graders for the GTM Strategy Optimizer.
+
+Three tasks with increasing difficulty:
+  1. channel_optimizer (easy)   — 12 weeks, 3 channels, 2 segments
+  2. growth_strategist (medium) — 24 weeks, 5 channels, 3 segments
+  3. market_dominator  (hard)   — 36 weeks, 7 channels, 4 segments + competitor + regime shifts
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Dict, List
+
+from .simulation import (
+    ChannelConfig,
+    EXPERIMENT_TYPES,
+    MarketSimulator,
+    MESSAGING_DIMS,
+    PRICING_ACTIONS,
+    ProductConfig,
+    SegmentConfig,
+    SimState,
+)
+
+
+@dataclass
+class TaskDefinition:
+    """Everything needed to instantiate + grade a task."""
+
+    task_id: str
+    name: str
+    difficulty: str
+    description: str
+    total_weeks: int
+    total_budget: float
+    channels: List[ChannelConfig]
+    segments: List[SegmentConfig]
+    product: ProductConfig
+    noise_level: float
+    enable_competitor: bool
+    enable_regime_shifts: bool
+    revenue_target: float  # for grading
+    available_experiments: List[str]
+    available_pricing_actions: List[str]
+    grader: Callable[[SimState], float]
+
+
+# ── Grader functions ───────────────────────────────────────────────────────
+
+
+def _grade_channel_optimizer(s: SimState) -> float:
+    """Easy task: pure revenue vs target with partial credit."""
+    revenue_target = 120000.0
+    score = min(1.0, s.total_revenue / revenue_target)
+    return round(max(0.0, score), 4)
+
+
+def _grade_growth_strategist(s: SimState) -> float:
+    """Medium task: weighted score across revenue, efficiency, brand, experiments."""
+    revenue_target = 375000.0
+    rev_score = min(1.0, s.total_revenue / revenue_target)
+
+    efficiency = s.total_revenue / max(s.total_spend, 1.0)
+    eff_score = min(1.0, efficiency / 3.0)  # 3x ROI = perfect
+
+    brand_score = s.brand_strength / 100.0
+
+    exp_score = 0.0
+    if s.experiments_run > 0:
+        exp_score = min(1.0, s.useful_experiments / max(s.experiments_run * 0.5, 1.0))
+
+    score = 0.40 * rev_score + 0.30 * eff_score + 0.20 * brand_score + 0.10 * exp_score
+    return round(max(0.0, min(1.0, score)), 4)
+
+
+def _grade_market_dominator(s: SimState) -> float:
+    """Hard task: revenue, ROI, brand trajectory, adaptability, compliance."""
+    revenue_target = 400000.0
+    rev_score = min(1.0, s.total_revenue / revenue_target)
+
+    # risk-adjusted ROI
+    roi = s.total_revenue / max(s.total_spend, 1.0)
+    roi_score = min(1.0, roi / 4.0)
+
+    # brand trajectory (improving over time)
+    brand_scores = s.weekly_brand_scores
+    if len(brand_scores) >= 4:
+        first_quarter = sum(brand_scores[: len(brand_scores) // 4]) / max(len(brand_scores) // 4, 1)
+        last_quarter = sum(brand_scores[-len(brand_scores) // 4 :]) / max(len(brand_scores) // 4, 1)
+        trajectory = min(1.0, max(0.0, (last_quarter - first_quarter + 10) / 20.0))
+    else:
+        trajectory = 0.5
+
+    # adaptability: performance recovery after regime shifts
+    revenues = s.weekly_revenues
+    if len(revenues) >= 18:
+        pre_shift = sum(revenues[8:12]) / 4 if len(revenues) > 12 else 1.0
+        post_shift = sum(revenues[13:17]) / 4 if len(revenues) > 17 else 0.0
+        adapt_score = min(1.0, post_shift / max(pre_shift, 1.0))
+    else:
+        adapt_score = 0.5
+
+    # compliance
+    compliance_score = max(0.0, 1.0 - s.compliance_violations * 0.03)
+
+    score = (
+        0.35 * rev_score
+        + 0.25 * roi_score
+        + 0.20 * trajectory
+        + 0.10 * adapt_score
+        + 0.10 * compliance_score
+    )
+    return round(max(0.0, min(1.0, score)), 4)
+
+
+# ── Task configurations ───────────────────────────────────────────────────
+
+TASK_CHANNEL_OPTIMIZER = TaskDefinition(
+    task_id="channel_optimizer",
+    name="Channel Optimizer",
+    difficulty="easy",
+    description=(
+        "Maximize revenue by allocating budget across 3 marketing channels "
+        "targeting 2 customer segments over 12 weeks. Focus on finding the "
+        "right channel-segment fit."
+    ),
+    total_weeks=12,
+    total_budget=50000.0,
+    channels=[
+        ChannelConfig(
+            name="paid_search",
+            base_ctr=0.012,
+            base_cvr=0.025,
+            saturation_alpha=1.5,
+            cost_per_impression=18.0,
+            min_spend_for_signal=200.0,
+            segment_affinity={"startup_founders": 1.4, "smb_owners": 1.0},
+        ),
+        ChannelConfig(
+            name="paid_social",
+            base_ctr=0.008,
+            base_cvr=0.015,
+            saturation_alpha=2.0,
+            cost_per_impression=12.0,
+            min_spend_for_signal=150.0,
+            segment_affinity={"startup_founders": 1.2, "smb_owners": 0.8},
+        ),
+        ChannelConfig(
+            name="email_lifecycle",
+            base_ctr=0.025,
+            base_cvr=0.035,
+            saturation_alpha=1.0,
+            cost_per_impression=5.0,
+            min_spend_for_signal=100.0,
+            segment_affinity={"startup_founders": 0.9, "smb_owners": 1.5},
+        ),
+    ],
+    segments=[
+        SegmentConfig(
+            name="startup_founders",
+            size=0.6,
+            price_sensitivity=0.7,
+            message_preference={
+                "cost_savings": 0.1, "performance": 0.3, "reliability": 0.1,
+                "innovation": 0.3, "ease_of_use": 0.15, "security": 0.05,
+            },
+            base_churn=0.08,
+        ),
+        SegmentConfig(
+            name="smb_owners",
+            size=0.4,
+            price_sensitivity=0.5,
+            message_preference={
+                "cost_savings": 0.25, "performance": 0.15, "reliability": 0.25,
+                "innovation": 0.05, "ease_of_use": 0.2, "security": 0.1,
+            },
+            base_churn=0.05,
+        ),
+    ],
+    product=ProductConfig(base_price=99.0, differentiation=0.7, complexity=0.3),
+    noise_level=0.1,
+    enable_competitor=False,
+    enable_regime_shifts=False,
+    revenue_target=120000.0,
+    available_experiments=[],
+    available_pricing_actions=[],
+    grader=_grade_channel_optimizer,
+)
+
+TASK_GROWTH_STRATEGIST = TaskDefinition(
+    task_id="growth_strategist",
+    name="Growth Strategist",
+    difficulty="medium",
+    description=(
+        "Maximize revenue while maintaining brand health and budget efficiency. "
+        "Manage 5 channels, 3 segments, run experiments, and adjust pricing "
+        "over 24 weeks. Balance short-term revenue with long-term brand building."
+    ),
+    total_weeks=24,
+    total_budget=150000.0,
+    channels=[
+        ChannelConfig(
+            name="paid_search", base_ctr=0.012, base_cvr=0.022,
+            saturation_alpha=1.5, cost_per_impression=20.0, min_spend_for_signal=200.0,
+            segment_affinity={"startup_founders": 1.4, "smb_owners": 1.0, "enterprise": 0.7},
+        ),
+        ChannelConfig(
+            name="paid_social", base_ctr=0.008, base_cvr=0.012,
+            saturation_alpha=2.0, cost_per_impression=14.0, min_spend_for_signal=150.0,
+            segment_affinity={"startup_founders": 1.3, "smb_owners": 0.8, "enterprise": 0.5},
+        ),
+        ChannelConfig(
+            name="organic_content", base_ctr=0.006, base_cvr=0.030,
+            saturation_alpha=0.8, cost_per_impression=8.0, min_spend_for_signal=300.0,
+            segment_affinity={"startup_founders": 1.1, "smb_owners": 1.2, "enterprise": 1.3},
+        ),
+        ChannelConfig(
+            name="email_lifecycle", base_ctr=0.025, base_cvr=0.030,
+            saturation_alpha=1.0, cost_per_impression=5.0, min_spend_for_signal=100.0,
+            segment_affinity={"startup_founders": 0.9, "smb_owners": 1.5, "enterprise": 1.1},
+        ),
+        ChannelConfig(
+            name="outbound_sales", base_ctr=0.003, base_cvr=0.045,
+            saturation_alpha=1.2, cost_per_impression=50.0, min_spend_for_signal=500.0,
+            segment_affinity={"startup_founders": 0.5, "smb_owners": 0.9, "enterprise": 1.8},
+        ),
+    ],
+    segments=[
+        SegmentConfig(
+            name="startup_founders", size=0.4, price_sensitivity=0.7,
+            message_preference={
+                "cost_savings": 0.1, "performance": 0.3, "reliability": 0.1,
+                "innovation": 0.3, "ease_of_use": 0.15, "security": 0.05,
+            },
+            base_churn=0.08,
+        ),
+        SegmentConfig(
+            name="smb_owners", size=0.35, price_sensitivity=0.5,
+            message_preference={
+                "cost_savings": 0.25, "performance": 0.15, "reliability": 0.25,
+                "innovation": 0.05, "ease_of_use": 0.2, "security": 0.1,
+            },
+            base_churn=0.05,
+        ),
+        SegmentConfig(
+            name="enterprise", size=0.25, price_sensitivity=0.2,
+            message_preference={
+                "cost_savings": 0.05, "performance": 0.15, "reliability": 0.3,
+                "innovation": 0.1, "ease_of_use": 0.1, "security": 0.3,
+            },
+            base_churn=0.03,
+        ),
+    ],
+    product=ProductConfig(base_price=149.0, differentiation=0.65, complexity=0.5),
+    noise_level=0.15,
+    enable_competitor=False,
+    enable_regime_shifts=False,
+    revenue_target=375000.0,
+    available_experiments=EXPERIMENT_TYPES,
+    available_pricing_actions=PRICING_ACTIONS,
+    grader=_grade_growth_strategist,
+)
+
+TASK_MARKET_DOMINATOR = TaskDefinition(
+    task_id="market_dominator",
+    name="Market Dominator",
+    difficulty="hard",
+    description=(
+        "Maximize long-term revenue under adversarial conditions. "
+        "Manage 7 channels, 4 segments with an active competitor and "
+        "market regime shifts. Avoid compliance traps. 36 weeks, high noise."
+    ),
+    total_weeks=36,
+    total_budget=300000.0,
+    channels=[
+        ChannelConfig(
+            name="paid_search", base_ctr=0.010, base_cvr=0.018,
+            saturation_alpha=1.8, cost_per_impression=22.0, min_spend_for_signal=250.0,
+            segment_affinity={
+                "startup_founders": 1.3, "smb_owners": 1.0, "enterprise": 0.7, "developer": 1.1,
+            },
+        ),
+        ChannelConfig(
+            name="paid_social", base_ctr=0.007, base_cvr=0.010,
+            saturation_alpha=2.2, cost_per_impression=16.0, min_spend_for_signal=200.0,
+            segment_affinity={
+                "startup_founders": 1.3, "smb_owners": 0.7, "enterprise": 0.4, "developer": 1.0,
+            },
+        ),
+        ChannelConfig(
+            name="organic_content", base_ctr=0.005, base_cvr=0.025,
+            saturation_alpha=0.8, cost_per_impression=10.0, min_spend_for_signal=350.0,
+            segment_affinity={
+                "startup_founders": 1.1, "smb_owners": 1.1, "enterprise": 1.2, "developer": 1.5,
+            },
+        ),
+        ChannelConfig(
+            name="email_lifecycle", base_ctr=0.020, base_cvr=0.025,
+            saturation_alpha=1.0, cost_per_impression=6.0, min_spend_for_signal=100.0,
+            segment_affinity={
+                "startup_founders": 0.9, "smb_owners": 1.4, "enterprise": 1.0, "developer": 0.8,
+            },
+        ),
+        ChannelConfig(
+            name="outbound_sales", base_ctr=0.003, base_cvr=0.040,
+            saturation_alpha=1.5, cost_per_impression=55.0, min_spend_for_signal=600.0,
+            segment_affinity={
+                "startup_founders": 0.4, "smb_owners": 0.8, "enterprise": 1.9, "developer": 0.3,
+            },
+        ),
+        ChannelConfig(
+            name="partnerships", base_ctr=0.004, base_cvr=0.035,
+            saturation_alpha=1.0, cost_per_impression=35.0, min_spend_for_signal=400.0,
+            segment_affinity={
+                "startup_founders": 1.0, "smb_owners": 1.2, "enterprise": 1.5, "developer": 1.1,
+            },
+        ),
+        ChannelConfig(
+            name="influencer_marketing", base_ctr=0.009, base_cvr=0.015,
+            saturation_alpha=2.5, cost_per_impression=25.0, min_spend_for_signal=300.0,
+            segment_affinity={
+                "startup_founders": 1.5, "smb_owners": 0.6, "enterprise": 0.3, "developer": 1.4,
+            },
+        ),
+    ],
+    segments=[
+        SegmentConfig(
+            name="startup_founders", size=0.3, price_sensitivity=0.7,
+            message_preference={
+                "cost_savings": 0.1, "performance": 0.3, "reliability": 0.1,
+                "innovation": 0.3, "ease_of_use": 0.15, "security": 0.05,
+            },
+            base_churn=0.08,
+        ),
+        SegmentConfig(
+            name="smb_owners", size=0.25, price_sensitivity=0.5,
+            message_preference={
+                "cost_savings": 0.25, "performance": 0.15, "reliability": 0.25,
+                "innovation": 0.05, "ease_of_use": 0.2, "security": 0.1,
+            },
+            base_churn=0.05,
+        ),
+        SegmentConfig(
+            name="enterprise", size=0.2, price_sensitivity=0.15,
+            message_preference={
+                "cost_savings": 0.05, "performance": 0.15, "reliability": 0.3,
+                "innovation": 0.1, "ease_of_use": 0.1, "security": 0.3,
+            },
+            base_churn=0.02,
+        ),
+        SegmentConfig(
+            name="developer", size=0.25, price_sensitivity=0.6,
+            message_preference={
+                "cost_savings": 0.05, "performance": 0.35, "reliability": 0.1,
+                "innovation": 0.25, "ease_of_use": 0.2, "security": 0.05,
+            },
+            base_churn=0.1,
+        ),
+    ],
+    product=ProductConfig(base_price=199.0, differentiation=0.6, complexity=0.6),
+    noise_level=0.25,
+    enable_competitor=True,
+    enable_regime_shifts=True,
+    revenue_target=400000.0,
+    available_experiments=EXPERIMENT_TYPES,
+    available_pricing_actions=PRICING_ACTIONS,
+    grader=_grade_market_dominator,
+)
+
+
+# ── Registry ───────────────────────────────────────────────────────────────
+
+TASKS: Dict[str, TaskDefinition] = {
+    "channel_optimizer": TASK_CHANNEL_OPTIMIZER,
+    "growth_strategist": TASK_GROWTH_STRATEGIST,
+    "market_dominator": TASK_MARKET_DOMINATOR,
+}
+
+
+def get_task(task_id: str) -> TaskDefinition:
+    if task_id not in TASKS:
+        raise ValueError(f"Unknown task_id '{task_id}'. Available: {list(TASKS.keys())}")
+    return TASKS[task_id]
+
+
+def create_simulator(task_id: str, seed: int | None = None) -> MarketSimulator:
+    """Create a MarketSimulator configured for the given task."""
+    t = get_task(task_id)
+    return MarketSimulator(
+        channels=t.channels,
+        segments=t.segments,
+        product=t.product,
+        total_weeks=t.total_weeks,
+        total_budget=t.total_budget,
+        noise_level=t.noise_level,
+        enable_competitor=t.enable_competitor,
+        enable_regime_shifts=t.enable_regime_shifts,
+        seed=seed,
+    )