shared.py

"""Shared, domain-agnostic prompt components.

Contains the building blocks reused by every domain-specific prompt bank
(ML, HEP, future domains):

* ``SECTION_WORD_TARGETS`` / ``_SECTION_TARGET_ALIASES`` — per-section word
  count targets used by ``executor._validate_draft_quality`` and the
  LaTeX converter completeness check.
* ``_DEFAULT_BLOCKS`` — reusable prompt fragments (title rules, safety
  disclaimers, RL guidance, …). These are *content*-agnostic infrastructure.
* ``_DEFAULT_SUB_PROMPTS`` — secondary LLM sub-calls (code repair, code
  reviewer, iterative improve, etc.). Domain-agnostic utility prompts.
"""

from __future__ import annotations

from typing import Any


# -- Canonical section word-count targets ----------------------------------
# Single source of truth for per-section word-count ranges.
# Used by executor._validate_draft_quality() and converter.check_paper_completeness().
SECTION_WORD_TARGETS: dict[str, tuple[int, int]] = {
    "abstract": (180, 220),
    "introduction": (800, 1000),
    "related work": (600, 800),
    "method": (1000, 1500),
    "experiments": (800, 1200),
    "results": (600, 800),
    "discussion": (400, 600),
    "limitations": (200, 300),
    "conclusion": (200, 300),
    "broader impact": (200, 400),
}

# Aliases mapping heading variants to canonical names in SECTION_WORD_TARGETS.
_SECTION_TARGET_ALIASES: dict[str, str] = {
    "methods": "method",
    "methodology": "method",
    "proposed method": "method",
    "approach": "method",
    "experimental setup": "experiments",
    "experimental results": "results",
    "results and discussion": "results",
    "results and analysis": "results",
    "conclusions": "conclusion",
    "conclusion and future work": "conclusion",
    "summary": "conclusion",
    "background": "related work",
    "literature review": "related work",
    "prior work": "related work",
    "limitation": "limitations",
    "limitations and future work": "limitations",
    "broader impacts": "broader impact",
    "societal impact": "broader impact",
    "ethical considerations": "broader impact",
}

# -- Reusable blocks -----------------------------------------------------

_DEFAULT_BLOCKS: dict[str, str] = {
    "title_guidelines": (
        "\n## TITLE RULES (Hard Constraints)\n"
        "1. MAXIMUM 14 words. Ideal: 8-12 words. NEVER exceed 14.\n"
        "2. Preferred structure: 'MethodName: Descriptive Phrase' (colon format)\n"
        "   - Create a catchy 1-3 word method name (acronym, portmanteau, or evocative word)\n"
        "   - Subtitle explains what it does: 'for X' / 'via Y' / 'in Z'\n"
        "   - Examples: 'AlphaEdit: Null-Space Knowledge Editing for LMs' (8 words)\n"
        "   - Examples: 'VAR: Visual Autoregressive Modeling via Next-Scale Prediction' (8 words)\n"
        "3. Alternative: Bold declarative claim that surprises the reader\n"
        "   - 'Not All Tokens Are What You Need for Pretraining' (9 words)\n"
        "   - 'Vision Transformers Need Registers' (4 words)\n"
        "4. FORBIDDEN patterns:\n"
        "   - 'Investigating...', 'An Empirical Study of...', 'Towards...'\n"
        "   - 'A Novel Approach to...', 'On the...' (generic academic filler)\n"
        "   - Repeating the full method description as title\n"
        "   - Weakness qualifiers: 'in Two Runs', 'Under Limited Data'\n"
        "5. MUST define a short method name (2-5 chars) that serves as memorable handle.\n"
        "   The reader should be able to say 'Have you read the X paper?'\n"
        "6. No abbreviations unless universally known (LLM, RL, GAN, NLP are OK).\n"
    ),
    "abstract_structure": (
        "\n## ABSTRACT (Hard Rules — 180-220 words, 5-7 sentences)\n"
        "STRUCTURE (PMR+ format):\n"
        "S1-S2: PROBLEM — What gap exists? Why does it matter? (NO method names yet)\n"
        "S3-S4: METHOD — Name your system. One-sentence description of key insight.\n"
        "S5-S6: RESULTS — At most 3 specific numbers. Use relative improvements\n"
        "  ('X% over baseline') not raw values ('0.7667'). Bold the single most\n"
        "  important result.\n"
        "S7 (optional): IMPACT — What does this enable?\n\n"
        "HARD CONSTRAINTS:\n"
        "- NO \\texttt{{}} in abstract\n"
        "- NO more than 3 numeric values in the entire abstract\n"
        "- NO per-seed breakdowns or confidence intervals\n"
        "- NO method names longer than 3 words (use the short system name)\n"
        "- The abstract must be readable by a researcher who skimmed only the title\n"
        "- First sentence must NOT start with 'We' or 'This paper'\n"
    ),
    "compute_budget": (
        "\n## Compute Budget Constraint\n"
        "- Total execution time limit: {time_budget_sec} seconds\n"
        "- You MUST design experiments that complete within this budget\n"
        "- Estimate: a simple numpy loop runs ~10M iterations/sec; a nested loop over\n"
        "  conditions runs proportionally slower\n"
        "- SCALING RULES (mandatory):\n"
        "  - If total conditions > 100: reduce seeds to 3-5 (not 20)\n"
        "  - If total conditions > 500: reduce to 2-3 representative conditions per factor\n"
        "  - If time_budget < 300s: limit total optimization steps to ≤5,000 per run\n"
        "  - If time_budget < 120s: limit total optimization steps to ≤1,000 per run\n"
        "  - Always print intermediate results so partial data is captured on timeout\n"
        "- MANDATORY: print a 'TIME_ESTIMATE: Xs' line before the main loop,\n"
        "  estimating total runtime based on a small pilot (run 1 condition, extrapolate)\n"
        "- MANDATORY: implement a time guard — check elapsed time periodically and\n"
        "  stop gracefully if approaching 80% of budget, saving all results collected so far\n"
        "- MANDATORY: add NaN/divergence fast-fail guard:\n"
        "  - After each optimization step, check if loss is NaN or > 100\n"
        "  - If detected, print 'FAIL: NaN/divergence detected', save partial results, and exit\n"
        "  - Do NOT waste compute on a diverging run\n"
        "- MINIMUM TRAINING EPOCHS (CRITICAL for meaningful results):\n"
        "  - CIFAR-10/100 with ResNet/CNN: minimum 50 epochs (200 recommended)\n"
        "  - FashionMNIST with small CNN: minimum 20 epochs\n"
        "  - RL environments: follow the RL STEP BUDGET below (CRITICAL)\n"
        "  - If time_budget is too short for minimum epochs, REDUCE model complexity\n"
        "    or dataset size INSTEAD of reducing epochs. 8 epochs on CIFAR-10 will\n"
        "    produce random-chance accuracy (~10%), making all comparisons meaningless.\n"
        "  - Use a SMALL model (simple CNN, few layers) to fit enough epochs into the budget.\n"
        "  - A converged small model is worth infinitely more than a diverged large model.\n"
        "- MANDATORY: use the experiment_harness module (pre-installed in sandbox):\n"
        "  ```\n"
        "  from experiment_harness import ExperimentHarness\n"
        "  harness = ExperimentHarness(time_budget={time_budget_sec})\n"
        "  # In your experiment loop:\n"
        "  if harness.should_stop():\n"
        "      break  # graceful stop at 80% of budget\n"
        "  if not harness.check_value(value, 'metric_name'):\n"
        "      print('SKIP: NaN/Inf detected')  # skip invalid values\n"
        "      continue\n"
        "  harness.report_metric('metric_name', value)  # validated output\n"
        "  # At the end of ALL experiments:\n"
        "  harness.finalize()  # writes results.json — MUST be called\n"
        "  ```\n"
        "  The harness provides: time budget enforcement, NaN/Inf detection,\n"
        "  validated metric reporting, and results.json output. NOT using it\n"
        "  means your metrics may be lost or malformed.\n"
    ),
    "topic_constraint": (
        "\n\n=== HARD TOPIC CONSTRAINT ===\n"
        "The paper MUST be about: {topic}\n"
        "PROHIBITED content (unless user explicitly specifies case-study mode):\n"
        "- Do NOT treat environment setup, dependency installation, or infrastructure "
        "failures as a research contribution.\n"
        "- Do NOT present debugging logs, system errors, or configuration issues "
        "as experimental findings.\n"
        "- Do NOT drift to tangential topics not directly related to the stated topic.\n"
        "- Every section MUST connect back to the core research question.\n"
        "- The Abstract and Introduction MUST clearly state the research problem "
        "derived from: {topic}\n"
        "- The Method section MUST describe a technical approach, not a workflow.\n"
        "- The Results section MUST report quantitative outcomes of experiments, "
        "not environment status.\n"
        "=== END CONSTRAINT ===\n"
    ),
    "pkg_hint_sandbox": (
        "\nAVAILABLE PACKAGES (sandbox mode): Python stdlib, numpy, math, random, "
        "statistics, json.\n"
        "Do NOT use: torch, tensorflow, jax, sklearn, pandas, scipy, matplotlib, "
        "or any deep learning framework.\n"
        "Write the experiment using ONLY numpy and stdlib.\n"
    ),
    "dataset_guidance": (
        "\n## Standard Datasets & Real Baselines (MANDATORY when applicable)\n"
        "You MUST use real benchmark datasets — NEVER synthetic torch.randn() data.\n\n"
        "### Tier 1: Pre-cached (ALWAYS available, use download=False)\n"
        "These datasets are already in the Docker image. Use download=False:\n"
        "- `torchvision.datasets.CIFAR10(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.CIFAR100(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.MNIST(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.FashionMNIST(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.STL10(root='/opt/datasets', split='train'/'test', download=False)`\n"
        "- `torchvision.datasets.SVHN(root='/opt/datasets', split='train'/'test', download=False)`\n\n"
        "### Tier 2: Downloadable (use setup.py to download before main.py runs)\n"
        "For any dataset NOT in Tier 1, create a `setup.py` file that downloads it.\n"
        "setup.py runs WITH network access; main.py runs WITHOUT network.\n"
        "- Any torchvision dataset (Caltech-101, Flowers102, etc.)\n"
        "- HuggingFace datasets: `from datasets import load_dataset`\n"
        "  Examples: IMDB, AG News, WikiText, SST-2, SQuAD, MMLU\n"
        "- OGB benchmarks: ogbg-molhiv, ogbn-arxiv, etc.\n"
        "- Tiny-ImageNet (237MB, 200 classes) — good ImageNet proxy\n\n"
        "### Tier 3: Too large for download (use alternatives)\n"
        "These datasets are TOO LARGE to download within experiment time limits:\n"
        "- ImageNet-1K (168GB) → use Tiny-ImageNet or CIFAR-100 as proxy\n"
        "- LAION (>1TB) → use smaller HuggingFace image-text datasets\n"
        "- Common Crawl, The Pile → use WikiText-103 or pre-tokenized subsets\n"
        "NEVER generate 'ImageNet-like' synthetic data — always use a real alternative.\n\n"
        "### ANTI-PATTERNS (NEVER DO THESE):\n"
        "- `torch.randn(N, 3, 224, 224)` as dataset → use real datasets\n"
        "- `download=True` in main.py → put downloads in setup.py\n"
        "- `download=False` for non-cached datasets → will FileNotFoundError\n"
        "- Random train/test splits → use official splits from dataset\n"
        "- `os.makedirs('/opt/datasets/...')` → /opt/datasets is READ-ONLY\n\n"
        "DATA PATH: For Tier 1 pre-cached datasets, use `/opt/datasets` as root.\n"
        "For Tier 2 datasets downloaded by setup.py, use `/workspace/data` as root.\n"
        "WARNING: `/opt/datasets` is READ-ONLY. NEVER call os.makedirs() on it.\n"
        "Just pass `root='/opt/datasets'` directly to torchvision dataset constructors.\n\n"
        "DISTRIBUTION SHIFT — use torchvision corruption transforms:\n"
        "- Gaussian noise: `transforms.Lambda(lambda x: x + torch.randn_like(x) * sigma)`\n"
        "- Brightness shift: `transforms.ColorJitter(brightness=0.5)`\n"
        "- Contrast shift: `transforms.ColorJitter(contrast=0.5)`\n"
        "- Blur: `transforms.GaussianBlur(kernel_size=5, sigma=(0.1, 2.0))`\n"
        "- For CIFAR-10-C style corruptions, apply transforms to test set only.\n\n"
        "REAL BASELINES & MODERN BENCHMARKS (CRITICAL):\n"
        "- Use proper train/test splits from the dataset (never split randomly in code)\n"
        "- Use standard architectures (ResNet-18/50, ViT, ConvNeXt) — not toy 2-layer MLPs\n"
        "- CIFAR INPUT SIZE (IMPORTANT): CIFAR images are 32×32. Two valid approaches:\n"
        "  1. PRETRAINED models (ImageNet weights): Use `transforms.Resize(224)` — "
        "pretrained models require 224×224 inputs.\n"
        "  2. TRAINING FROM SCRATCH (most experiments): Modify the model for 32×32 "
        "inputs instead of resizing. For ResNet: use `nn.Conv2d(3,64,3,1,1)` as "
        "first conv (not 7×7/stride-2) and REMOVE the initial MaxPool. This is 49× "
        "more memory-efficient and trains faster than Resize(224). Use the `timm` "
        "library's CIFAR variants or build a custom `get_resnet18_cifar()` helper.\n"
        "- Report standard metrics (top-1 accuracy for classification tasks)\n"
        "- Compare against published baselines where available\n"
        "- BASELINES MUST BE CURRENT: Use baselines from recent top-venue papers "
        "(2023-2026). Do NOT use outdated methods as the primary comparison.\n"
        "  * AlexNet, VGG-16 → use ResNet-50, ViT, ConvNeXt instead\n"
        "  * Vanilla SGD → use AdamW, SGD+momentum+cosine LR\n"
        "  * Simple RNN/LSTM for NLP → use Transformer-based models\n"
        "- Include at LEAST one strong, modern baseline (near-SOTA).\n"
        "- BENCHMARKS MUST BE STANDARD and actively used in the community.\n\n"
        "WHEN TO USE SYNTHETIC DATA (required for these domains):\n"
        "- **PDE / Scientific computing**: Generate synthetic PDE data (Burgers "
        "equation, Darcy flow, heat equation, Navier-Stokes). Use numerical solvers "
        "(scipy.integrate, finite differences) to create ground truth.\n"
        "- **Combinatorial optimization** (TSP, graph coloring, scheduling): Generate "
        "random problem instances (random TSP cities, Erdos-Renyi graphs).\n"
        "- **Theoretical analysis**: Synthetic optimization landscapes, toy problems.\n"
        "- **Domain with no standard dataset**: Novel combinatorial or mathematical domains.\n"
        "For these domains, do NOT use CIFAR/MNIST/ImageNet — they are irrelevant. "
        "Generate problem-specific synthetic data in main.py.\n\n"
        "DOMAIN-DATASET MATCHING (CRITICAL):\n"
        "- Image classification → CIFAR-10/100, MNIST, ImageNet variants\n"
        "- NLP → IMDB, AG News, SST-2, WikiText\n"
        "- Graph learning → Cora, CiteSeer, ogbn-arxiv\n"
        "- PDE/Physics → SYNTHETIC (Burgers, Darcy, Navier-Stokes)\n"
        "- Combinatorial optimization → SYNTHETIC (random TSP, graph instances)\n"
        "- RL → Gymnasium environments (CartPole, LunarLander, HalfCheetah)\n"
        "NEVER use image datasets for non-image problems.\n"
    ),
    "setup_script_guidance": (
        "\n## Setup Script (setup.py) — Dataset Download & Preparation\n"
        "If your experiment needs datasets NOT in the pre-cached list, generate "
        "a SEPARATE file called `setup.py` that downloads and prepares them.\n"
        "The setup.py runs WITH NETWORK ACCESS before main.py (which runs WITHOUT network).\n\n"
        "IMPORTANT: All download logic MUST be in setup.py, NOT in main.py.\n"
        "main.py should only load pre-cached data from /opt/datasets (download=False) "
        "or downloaded data from /workspace/data.\n\n"
        "Example setup.py:\n"
        "```python\n"
        "import os\n"
        "DATA_DIR = '/workspace/data'\n"
        "os.makedirs(DATA_DIR, exist_ok=True)\n\n"
        "# Download torchvision datasets\n"
        "import torchvision\n"
        "torchvision.datasets.Caltech101(root=DATA_DIR, download=True)\n\n"
        "# Download HuggingFace datasets\n"
        "from datasets import load_dataset\n"
        "ds = load_dataset('imdb', cache_dir=os.path.join(DATA_DIR, 'hf'))\n\n"
        "# Download OGB benchmarks\n"
        "# from ogb.graphproppred import PygGraphPropPredDataset\n"
        "# dataset = PygGraphPropPredDataset(name='ogbg-molhiv', root=DATA_DIR)\n\n"
        "print('[setup] Dataset download complete.')\n"
        "```\n\n"
        "IMPORT ANTI-PATTERN (NEVER DO THIS):\n"
        "```python\n"
        "from datasets import load_dataset\n"
        "datasets.load_dataset('imdb', ...)  # WRONG — NameError!\n"
        "```\n"
        "If you write `from datasets import load_dataset`, call `load_dataset(...)` directly.\n"
        "If you write `import datasets`, call `datasets.load_dataset(...)` with module prefix.\n"
        "NEVER mix the two styles.\n\n"
        "If ALL your datasets are pre-cached (CIFAR-10/100, MNIST, FashionMNIST, "
        "STL-10, SVHN), you do NOT need setup.py — just use download=False in main.py.\n\n"
        "You may also include a `requirements.txt` file listing any additional "
        "pip packages your experiment needs beyond the pre-installed set.\n"
    ),
    "network_disabled_guidance": (
        "\n## ⚠️ NO NETWORK ACCESS — CRITICAL CONSTRAINT ⚠️\n"
        "This experiment runs with network_policy='none'. There is NO network access\n"
        "at ANY phase (no pip install, no dataset downloads, no HTTP requests).\n\n"
        "### ONLY these pre-cached datasets are available:\n"
        "- `torchvision.datasets.CIFAR10(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.CIFAR100(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.MNIST(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.FashionMNIST(root='/opt/datasets', train=True/False, download=False)`\n"
        "- `torchvision.datasets.STL10(root='/opt/datasets', split='train'/'test', download=False)`\n"
        "- `torchvision.datasets.SVHN(root='/opt/datasets', split='train'/'test', download=False)`\n\n"
        "### FORBIDDEN (will cause runtime failure):\n"
        "- Do NOT create setup.py (it cannot run without network)\n"
        "- Do NOT create requirements.txt (pip install is unavailable)\n"
        "- Do NOT use `download=True` on any dataset\n"
        "- Do NOT use `urllib`, `requests`, `httpx`, or any HTTP library\n"
        "- Do NOT use `datasets.load_dataset()` from HuggingFace (requires download)\n"
        "- Do NOT import packages not pre-installed in the Docker image\n\n"
        "### Available pre-installed packages:\n"
        "torch, torchvision, torchaudio, numpy, scipy, sklearn, matplotlib, seaborn,\n"
        "pandas, tqdm, gymnasium, networkx, PyYAML, Pillow, timm, einops, torchmetrics,\n"
        "h5py, transformers, datasets, accelerate, peft, bitsandbytes.\n\n"
        "If your research topic requires a dataset NOT in the pre-cached list,\n"
        "you MUST adapt to use one of the 6 pre-cached datasets instead.\n"
    ),
    "network_full_guidance": (
        "\n## Network Access: Full\n"
        "This experiment runs with network_policy='full'. Network access is available\n"
        "throughout ALL execution phases (setup, pip install, and main experiment).\n"
        "You may download datasets, install packages, and make HTTP requests at any time.\n"
    ),
    "hp_reporting": (
        "\n## Hyperparameter Reporting (MANDATORY)\n"
        "At the TOP of main.py, define a HYPERPARAMETERS dictionary containing ALL "
        "tunable hyperparameters used in your experiment:\n"
        "```python\n"
        "HYPERPARAMETERS = {\n"
        "    'learning_rate': 0.001,\n"
        "    'batch_size': 64,\n"
        "    'num_epochs': 50,\n"
        "    'hidden_dim': 256,\n"
        "    # ... all other hyperparameters\n"
        "}\n"
        "```\n"
        "At the end of main.py, save hyperparameters to results.json:\n"
        "```python\n"
        "import json\n"
        "results = {'hyperparameters': HYPERPARAMETERS, 'metrics': collected_metrics}\n"
        "with open('results.json', 'w') as f:\n"
        "    json.dump(results, f, indent=2)\n"
        "```\n"
        "EVERY hyperparameter must be used in the code — no dead parameters.\n"
        "The paper MUST include a hyperparameter table — this data feeds into it.\n"
    ),
    "rl_step_guidance": (
        "\n## RL Training Step Budget (MANDATORY for RL experiments)\n"
        "Reinforcement learning requires MANY more training steps than supervised learning.\n"
        "Under-trained RL agents produce random-chance performance, making ALL comparisons\n"
        "meaningless and the paper unpublishable.\n\n"
        "### Environment Availability:\n"
        "#### Always available (classic control — no extra dependencies):\n"
        "- CartPole-v1, Pendulum-v1, MountainCar-v0, MountainCarContinuous-v0,\n"
        "  Acrobot-v1, LunarLander-v3\n"
        "- These are lightweight and fast — PREFER these unless MuJoCo is specifically required.\n\n"
        "#### MuJoCo environments (pre-installed in Docker image):\n"
        "- HalfCheetah-v5, Hopper-v5, Walker2d-v5, Ant-v5, Humanoid-v5,\n"
        "  Swimmer-v5, Reacher-v5, InvertedPendulum-v5, InvertedDoublePendulum-v5\n"
        "- Require MuJoCo runtime — available in Docker but NOT in basic sandbox mode.\n\n"
        "#### RULE: If the research topic says 'MuJoCo-free', 'without MuJoCo',\n"
        "  or 'classic control only' → you MUST use classic control environments ONLY.\n"
        "  Do NOT import or reference MuJoCo in any way.\n\n"
        "#### DEFAULT RECOMMENDATION: Prefer classic control environments unless the\n"
        "  research topic specifically requires MuJoCo locomotion tasks.\n\n"
        "### ALGORITHM-ENVIRONMENT COMPATIBILITY (HARD RULE — violation = crash):\n"
        "- DQN is ONLY for DISCRETE action spaces (CartPole, LunarLander, Acrobot, Atari).\n"
        "  DQN will CRASH on Pendulum, HalfCheetah, Hopper, Walker2d, etc.\n"
        "- For CONTINUOUS action spaces: use SAC, TD3, or PPO.\n"
        "- PPO works for both discrete and continuous.\n"
        "- NEVER combine DQN + any continuous environment.\n\n"
        "### TIME BUDGET RULES FOR RL:\n"
        "- If time_budget ≤ 3600s → ONLY classic control "
        "(CartPole, Pendulum, MountainCar, Acrobot, LunarLander)\n"
        "- If time_budget ≤ 1800s → ONLY CartPole or Pendulum (simplest)\n"
        "- MuJoCo requires >5000s for meaningful results.\n\n"
        "### Minimum Steps by Algorithm Family:\n"
        "| Algorithm | Environment | Min Steps | Recommended |\n"
        "|-----------|-------------|-----------|-------------|\n"
        "| PPO       | MuJoCo (Ant, HalfCheetah, Humanoid) | 500K | 1M-3M |\n"
        "| PPO       | Simple control (CartPole, Pendulum) | 100K | 500K |\n"
        "| SAC/TD3   | MuJoCo locomotion | 300K | 1M |\n"
        "| SAC/TD3   | Simple control | 50K  | 200K |\n"
        "| DQN/Rainbow | Atari | 1M | 10M |\n"
        "| A2C/A3C   | Any continuous | 500K | 2M |\n"
        "| REINFORCE | Any | 200K | 1M |\n\n"
        "### Step Budget Allocation Strategy:\n"
        "1. Compute pilot_time = time for 1000 steps of 1 condition.\n"
        "2. steps_per_sec = 1000 / pilot_time.\n"
        "3. max_steps_per_condition = (time_budget * 0.7) / num_conditions * steps_per_sec.\n"
        "4. If max_steps < min_steps for the algorithm, REDUCE num_seeds to 3 (not steps).\n"
        "5. If STILL under min_steps, use a simpler environment (e.g., Pendulum instead of Ant).\n"
        "6. NEVER reduce steps below the minimum — it wastes compute on meaningless results.\n\n"
        "### Evaluation Protocol for RL:\n"
        "- Evaluate every N_eval steps (e.g., every 10K steps) using deterministic policy.\n"
        "- Run 10 evaluation episodes per checkpoint.\n"
        "- Report: mean return, std return, success rate (if applicable).\n"
        "- Plot learning curves (return vs steps) — this is EXPECTED by reviewers.\n"
        "- Final metric = mean over last 10 evaluation checkpoints (NOT last episode).\n\n"
        "### Gymnasium Environment Version (CRITICAL):\n"
        "- Use v5 environments (NOT v4): `gym.make('HalfCheetah-v5')`, `gym.make('Hopper-v5')`\n"
        "- v4 environments are deprecated and will produce warnings.\n"
        "- Available MuJoCo v5 envs: HalfCheetah-v5, Hopper-v5, Walker2d-v5, Ant-v5,\n"
        "  Humanoid-v5, Swimmer-v5, Reacher-v5, InvertedPendulum-v5, InvertedDoublePendulum-v5\n"
        "- For simple/fast experiments: use Pendulum-v1, CartPole-v1, MountainCarContinuous-v0\n\n"
        "### Gymnasium API (CRITICAL — common crash source):\n"
        "- `env.reset()` returns `(obs, info)` — ALWAYS unpack both:\n"
        "  `obs, info = env.reset(seed=seed)`\n"
        "- `env.step(action)` returns `(obs, reward, terminated, truncated, info)` — 5 values:\n"
        "  `obs, reward, terminated, truncated, info = env.step(action)`\n"
        "  `done = terminated or truncated`\n"
        "- DO NOT use old `done = env.step(action)[2]` — this is the Gym (v0.26-) API.\n"
        "- `reward` is a scalar float, NOT an array. Do NOT index it: use `reward` directly.\n"
        "- `obs` shape depends on env: discrete envs give 1D array, image envs give 3D.\n"
        "  Always check `env.observation_space.shape` and handle accordingly.\n\n"
        "### Learning Curve Logging (MANDATORY for RL papers):\n"
        "- Print evaluation metrics at regular intervals: every N_eval steps\n"
        "  `EVAL: step=<S> condition=<C> seed=<seed> return=<R>`\n"
        "- This enables plotting learning curves (return vs training steps)\n"
        "- Learning curves are EXPECTED by RL reviewers — a paper without them\n"
        "  will be rejected regardless of final performance.\n"
        "- At the end, print the full curve:\n"
        "  `LEARNING_CURVE: condition=<C> seed=<seed> steps=[...] returns=[...]`\n"
    ),
    "multi_seed_enforcement": (
        "\n## Multi-Seed Experiment Requirement (MANDATORY — NO EXCEPTIONS)\n"
        "Running each condition with only 1 seed is NEVER acceptable. Results from\n"
        "a single seed cannot distinguish signal from noise and reviewers will reject.\n\n"
        "### HARD REQUIREMENT:\n"
        "- You MUST use exactly seeds = [0, 1, 2] (3 seeds minimum).\n"
        "- Each condition MUST loop over ALL seeds.\n"
        "- Print per-seed: `condition=X seed=S {metric_key}: V`\n"
        "- Print aggregated: `condition=X {metric_key}_mean: M {metric_key}_std: S`\n"
        "- Tables MUST show mean ± std, NEVER single-run values.\n\n"
        "### Implementation Pattern (copy this structure):\n"
        "```python\n"
        "SEEDS = [0, 1, 2]  # EXACTLY 3 seeds — mandatory minimum\n"
        "all_results = {}  # {condition_name: {seed: metric_value}}\n\n"
        "for condition_name, ConditionClass in conditions.items():\n"
        "    all_results[condition_name] = {}\n"
        "    for seed in SEEDS:\n"
        "        set_all_seeds(seed)  # torch, numpy, random\n"
        "        result = run_single(ConditionClass, seed=seed)\n"
        "        all_results[condition_name][seed] = result\n"
        "        print(f'condition={condition_name} seed={seed} metric: {result}')\n"
        "    values = list(all_results[condition_name].values())\n"
        "    print(f'condition={condition_name} metric_mean: {np.mean(values):.4f} '\n"
        "          f'metric_std: {np.std(values):.4f}')\n"
        "```\n\n"
        "### Reporting Requirements:\n"
        "- Print per-seed results: `condition=X seed=S metric: V`\n"
        "- Print aggregated: `condition=X metric_mean: M metric_std: S`\n"
        "- Tables in the paper MUST show mean ± std, NEVER single-run values.\n"
        "- If time budget forces < 5 seeds, use EXACTLY 3 seeds (minimum).\n"
        "  Print: `SEED_WARNING: only 3 seeds used due to time budget`.\n"
    ),
    "writing_structure": (
        "\n## Paper Section Writing Rules\n"
        "MARKDOWN FORMATTING (CRITICAL):\n"
        "- Use `# Title` (H1) for the paper title\n"
        "- Use `# Abstract`, `# Introduction`, `# Method`, etc. (H1) for MAIN sections\n"
        "- Use `## Subsection Name` (H2) for subsections WITHIN a main section\n"
        "- NEVER use `##` for main sections — that produces wrong LaTeX heading levels\n"
        "- Each main section (H1) MUST contain subsections (H2) when it exceeds 3 paragraphs\n"
        "- NEVER place sub-topics (e.g., 'Knowledge Distillation for Compact Models') "
        "at the same heading level as main sections (e.g., 'Related Work')\n"
        "- NEVER wrap the paper in ```markdown fences\n"
        "- NEVER use raw variable names (e.g., `method_name/metric_key = 0.85`) — "
        "always use human-readable text\n\n"
        "ABSTRACT (150-200 words, 5-sentence structure):\n"
        "- (1) Problem and significance (2) Prior approaches and gaps\n"
        "- (3) Your approach and novelty (4) Key results with 2-3 specific numbers\n"
        "- (5) Implication/takeaway\n"
        "- Do NOT list per-seed ranges (e.g., '0.71-0.73 across seeds') — use mean +/- std\n"
        "- Do NOT repeat numbers that appear in the Results section — pick the 2-3 most impactful\n\n"
        "INTRODUCTION (4 paragraphs, 800-1000 words, cite 8-12 references):\n"
        "Paragraph 1: Problem motivation (why this matters). "
        "Paragraph 2: What exists and why it falls short. "
        "Paragraph 3: Your approach and key insight. "
        "Paragraph 4: Contributions (2-3 bullet points allowed here ONLY).\n\n"
        "RELATED WORK:\n"
        "Organize by sub-topic, not chronologically. "
        "End each paragraph with how YOUR work differs from the cited work. "
        "Cite at least 15 references, all directly relevant.\n\n"
        "METHOD:\n"
        "Write as flowing narrative prose (NOT bullet points). "
        "Include full algorithm description with pseudocode or step-by-step. "
        "State all hyperparameters with values and justification. "
        "Provide architecture details sufficient for reproduction.\n\n"
        "RESULTS:\n"
        "- Do NOT repeat the same number more than twice across the paper\n"
        "- Each number in a table should be discussed AT MOST once in text\n"
        "- Tables: mean +/- std with 95% CI in parentheses\n"
        "- Bold the best result in each column\n"
        "- Every comparison claim must cite a p-value or note multiple seeds\n"
        "- Report the number of random seeds/runs used\n\n"
        "FIGURES AND TABLES:\n"
        "- Every figure MUST be referenced in the text (e.g., 'As shown in Figure 1')\n"
        "- Every table MUST be referenced in the text (e.g., 'Table 2 summarizes')\n"
        "- Figure captions: 1-2 descriptive sentences (not just 'Results comparison')\n"
        "- Table captions go ABOVE the table; figure captions go BELOW the figure\n"
        "- Axis labels must include units where applicable\n"
        "- Use consistent font sizes across all figures\n\n"
        "DISCUSSION (if applicable, can be merged into Results):\n"
        "- Paragraph 1: Summarize key findings and their significance\n"
        "- Paragraph 2: Compare with prior work — explain WHY results differ\n"
        "- Paragraph 3: Discuss unexpected or negative results honestly\n"
        "- Paragraph 4: Broader implications and practical applications\n\n"
        "LIMITATIONS (3-5 points):\n"
        "- State each limitation ONCE, here only — not scattered throughout\n"
        "- No disclaimers like 'due to computational constraints'\n"
        "- Include compute resources used (GPU type, training time)\n\n"
        "CONCLUSION:\n"
        "- Summarize findings (match actual results, no aspirational claims)\n"
        "- 2-3 sentences of future work\n\n"
        "PROSE QUALITY (CRITICAL — violation = desk reject):\n"
        "- Write FLOWING ACADEMIC PARAGRAPHS, not bullet-point lists.\n"
        "- Each paragraph must have 4-8 sentences with smooth transitions.\n"
        "- Introduction, Related Work, and Method must each be >=3 paragraphs.\n"
        "- FORBIDDEN: starting 3+ consecutive paragraphs with the same word.\n"
        "- FORBIDDEN: bullet-point lists in Introduction or Related Work sections.\n"
        "- Use varied sentence structures: mix simple, compound, and complex sentences.\n"
        "- Connect paragraphs with transition phrases: 'Building on this insight...', "
        "'In contrast to prior work...', 'To address this limitation...'.\n"
        "- Each Related Work paragraph must COMPARE your approach to cited work, "
        "not merely summarize what each paper does.\n"
        "- FORBIDDEN AI-BOILERPLATE phrases (instant credibility loss):\n"
        "  'delves into', 'it is worth noting', 'plays a crucial role',\n"
        "  'leverages the power of', 'paves the way', 'a myriad of',\n"
        "  'paradigm shift', 'groundbreaking', 'in the realm of',\n"
        "  'holistic approach', 'multifaceted', 'navigate the complexities'.\n"
        "  Replace ALL such phrases with precise, specific academic language.\n"
    ),
    "llm_training_guidance": (
        "\n## LLM Fine-Tuning Guidance (when topic involves language model training)\n"
        "AVAILABLE FRAMEWORKS (pre-installed in Docker):\n"
        "- transformers (AutoModelForCausalLM, AutoTokenizer, Trainer)\n"
        "- peft (LoraConfig, get_peft_model, PeftModel)\n"
        "- trl (SFTTrainer, DPOTrainer, GRPOTrainer)\n"
        "- datasets (load_dataset, Dataset)\n"
        "- accelerate (Accelerator)\n"
        "- bitsandbytes (4-bit/8-bit quantization)\n\n"
        "GPU MEMORY GUIDELINES (RTX 6000 Ada, 49GB VRAM):\n"
        "- Full fine-tune: <=3B parameters\n"
        "- LoRA (16-bit): <=14B parameters\n"
        "- QLoRA (4-bit): <=72B parameters (practical limit ~14B for training)\n"
        "- Optimal: 7B-14B model with QLoRA (rank 16-64)\n\n"
        "RECOMMENDED TRAINING PATTERN:\n"
        "```python\n"
        "from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig\n"
        "from peft import LoraConfig, get_peft_model, TaskType\n"
        "from trl import SFTTrainer, SFTConfig\n"
        "from datasets import load_dataset\n\n"
        "# 4-bit quantization for memory efficiency\n"
        "bnb_config = BitsAndBytesConfig(\n"
        "    load_in_4bit=True,\n"
        "    bnb_4bit_quant_type='nf4',\n"
        "    bnb_4bit_compute_dtype=torch.bfloat16,\n"
        ")\n"
        "model = AutoModelForCausalLM.from_pretrained(\n"
        "    model_name, quantization_config=bnb_config, device_map='auto'\n"
        ")\n"
        "lora_config = LoraConfig(\n"
        "    r=16, lora_alpha=32, target_modules='all-linear',\n"
        "    lora_dropout=0.05, task_type=TaskType.CAUSAL_LM,\n"
        ")\n"
        "model = get_peft_model(model, lora_config)\n"
        "```\n\n"
        "KEY HYPERPARAMETERS:\n"
        "- learning_rate: 1e-4 to 2e-4 (LoRA), 5e-5 to 1e-4 (full FT)\n"
        "- lora_r: 8 (minimal) to 64 (high-capacity)\n"
        "- lora_alpha: typically 2x lora_r\n"
        "- batch_size: 1-4 per device (use gradient_accumulation_steps for effective batch)\n"
        "- gradient_accumulation_steps: 4-16 (effective_batch = per_device * accum)\n"
        "- max_seq_length: 512 (short), 1024-2048 (standard), 4096 (long)\n"
        "- warmup_ratio: 0.03-0.1\n"
        "- weight_decay: 0.01-0.1\n\n"
        "DATA FORMAT (use datasets library):\n"
        "- Instruction tuning: {'instruction': '...', 'output': '...'}\n"
        "- Chat format: {'messages': [{'role': 'user', 'content': '...'}, ...]}\n"
        "- DPO: {'prompt': '...', 'chosen': '...', 'rejected': '...'}\n"
        "- Use load_dataset('json', data_files='train.json') for local data\n"
        "- Use load_dataset('HuggingFace/dataset_name') for HF Hub datasets\n\n"
        "EVALUATION:\n"
        "- Use evaluate library for standard metrics\n"
        "- Common: perplexity, ROUGE (summarization), BLEU (translation), accuracy\n"
        "- LLM benchmarks: MMLU, ARC, HellaSwag, TruthfulQA\n"
        "- Generate sample outputs for qualitative comparison\n\n"
        "MODEL DOWNLOAD:\n"
        "- Models will be downloaded from HuggingFace Hub at runtime\n"
        "- Use 'trust_remote_code=True' for custom model architectures\n"
        "- Cache directory: default HF cache (~/.cache/huggingface)\n"
        "- Common models: Qwen/Qwen2.5-7B, meta-llama/Llama-3.1-8B, "
        "microsoft/Phi-4, google/gemma-2-9b\n\n"
        "CRITICAL — NO SIMULATION:\n"
        "- You MUST load and train a REAL model from HuggingFace Hub.\n"
        "- NEVER simulate training with synthetic utility functions or random scores.\n"
        "- NEVER replace model training with np.random/torch.randn mock results.\n"
        "- A real experiment loads a model, tokenizes data, runs optimizer steps, "
        "and measures real loss/perplexity/accuracy on held-out data.\n"
        "- If compute budget is tight, use a SMALLER model (Qwen2.5-0.5B or 1.5B) "
        "with fewer training steps rather than simulating.\n"
    ),
    "llm_eval_guidance": (
        "\n## LLM Evaluation Guidance\n"
        "STANDARD BENCHMARKS:\n"
        "- Reasoning: MMLU, ARC-Challenge, HellaSwag, WinoGrande\n"
        "- Math: GSM8K, MATH, MathVista\n"
        "- Coding: HumanEval, MBPP, LiveCodeBench\n"
        "- Safety: TruthfulQA, BBQ, CrowS-Pairs\n"
        "- Instruction following: MT-Bench, AlpacaEval, IFEval\n"
        "- Multimodal: MMBench, POPE, MathVista, MMMU\n\n"
        "EVALUATION FRAMEWORKS:\n"
        "- lm-eval-harness: Standard eval framework, run via CLI or Python API\n"
        "- vllm: Fast inference engine for throughput-focused evaluation\n"
        "- lighteval: HuggingFace's lightweight eval framework\n\n"
        "EVALUATION PROTOCOL:\n"
        "- Report on at least 3 benchmarks relevant to the task\n"
        "- Compare with published baselines from model cards/leaderboards\n"
        "- Report both zero-shot and few-shot results where applicable\n"
        "- Include perplexity on held-out test set\n"
    ),
    # IMP-20: Academic writing style guide (from NeurIPS/ICLR/ICML 2024-2025 best papers)
    "academic_style_guide": (
        "\n## ACADEMIC WRITING STANDARDS (from NeurIPS/ICLR/ICML 2024-2025 best papers)\n\n"
        "### Title Standards\n"
        "- Target 8-14 words. Median of award-winning papers: ~10 words.\n"
        "- Preferred format: 'SystemName: Descriptive Subtitle' (35% of best papers)\n"
        "  e.g., 'AlphaEdit: Null-Space Constrained Knowledge Editing for Language Models'\n"
        "- Alternative: Declarative statement that surprises\n"
        "  e.g., 'Not All Tokens Are What You Need for Pretraining'\n"
        "- Give your method a memorable, catchy name (VAR, Genie, PRISM, SEDD).\n"
        "- NEVER exceed 18 words. NEVER use 'A Novel Approach to...' or 'Investigating...'\n\n"
        "### Abstract Standards (PMR+ Structure, 180-220 words)\n"
        "S1-S2: PROBLEM — State the gap. Open with a challenge or status-quo critique.\n"
        "S3-S4: METHOD — Name your system by sentence 3. Describe the key insight.\n"
        "S5-S6: RESULTS — At least 2-3 concrete quantitative claims:\n"
        "  - One relative improvement ('36.7% boost over baseline')\n"
        "  - One absolute benchmark score ('FID of 1.01 on ImageNet')\n"
        "AVOID: Per-seed ranges, excessive texttt, defensive hedging.\n\n"
        "### Section Writing Standards\n"
        "INTRODUCTION (800-1000 words, 4 paragraphs):\n"
        "  - Para 1: Motivation; Para 2: Gap (cite 3-5 papers); Para 3: Your approach;\n"
        "    Para 4: Contributions (bullet list of 3-4 specific contributions)\n"
        "  - MUST cite 8-12 references throughout Introduction\n\n"
        "RELATED WORK (600-800 words):\n"
        "  - Organize by sub-topic (2-3 subsections), NOT as a flat list\n"
        "  - End each subsection with how YOUR work differs\n"
        "  - Target >= 15 unique references in this section alone\n\n"
        "METHOD (1000-1500 words):\n"
        "  - Start with problem formulation (notation, objective function)\n"
        "  - Use algorithm environment for pseudocode (not verbatim)\n"
        "  - Write as a flowing narrative, NOT bullet points\n\n"
        "EXPERIMENTS (800-1200 words):\n"
        "  - Experimental setup as subsection (datasets, baselines, metrics, hardware)\n"
        "  - Hyperparameter table (Table 1 always)\n"
        "  - MUST reference figures: 'As shown in Figure 1, our method...'\n"
        "  - MUST cite baseline method papers (not just name them)\n\n"
        "RESULTS (600-800 words):\n"
        "  - Main results table with descriptive caption\n"
        "  - Ablation study table\n"
        "  - Analysis paragraphs connecting numbers to insights\n"
        "  - DO NOT repeat the same numbers from Experiments section\n"
        "  - Reference figures for visual evidence\n\n"
        "DISCUSSION (400-600 words):\n"
        "  - Compare findings with prior work (cite papers here!)\n"
        "  - Explain surprising results; broader implications\n\n"
        "LIMITATIONS (200-300 words): 3-5 specific, concrete limitations. ALL caveats go HERE.\n\n"
        "CONCLUSION: Summarize in 2-3 sentences, future work in 2-3 sentences.\n\n"
        "### Writing Quality Rules\n"
        "- Write as FLOWING PROSE, not bullet points or enumerated lists\n"
        "- Each paragraph: topic sentence, evidence, analysis, transition\n"
        "- Use transitions: 'Building on this insight...', 'In contrast to...'\n"
        "- Academic tone: confident but precise\n"
        "- Vary sentence structure: mix short declarative with longer analytical\n"
        "- AVOID: Starting 3+ consecutive sentences with 'We', 'The', 'Our'\n"
        "- AVOID: 'It is worth noting that', 'It should be mentioned that' (filler)\n"
        "- Citations belong in EVERY section, not just Introduction and Related Work\n"
    ),
    # IMP-25: Narrative writing requirements
    "narrative_writing_rules": (
        "\n## NARRATIVE WRITING REQUIREMENTS\n\n"
        "You are writing a paper for human reviewers at a top AI conference. The paper\n"
        "must read like a cohesive academic story, NOT a technical report or bullet list.\n\n"
        "### Structure of Each Paragraph\n"
        "Every paragraph MUST follow this pattern:\n"
        "1. TOPIC SENTENCE — states the main claim or finding\n"
        "2. EVIDENCE — data, citations, or reasoning that supports the claim\n"
        "3. ANALYSIS — what the evidence means, why it matters\n"
        "4. TRANSITION — connects to the next paragraph's topic\n\n"
        "### FORBIDDEN Writing Patterns\n"
        "- Bullet-point lists in the main body (ONLY allowed in Contributions paragraph\n"
        "  of Introduction and Limitations section)\n"
        "- Numbered lists of findings or results\n"
        "- Starting a paragraph with 'Table X shows...' without context first\n"
        "- Consecutive short sentences without analysis between them\n"
        "- Repeating the same sentence structure 3+ times in a row\n\n"
        "### REQUIRED Writing Patterns\n"
        "- Transition phrases: 'Building on this observation...', 'In contrast to prior work...'\n"
        "- Vary sentence length: alternate between short impactful and longer analytical\n"
        "- Ground every claim in evidence: '[Result] because [mechanism] (cite)'\n"
        "- Discuss implications: 'This X% improvement indicates that [mechanism Y]\n"
        "  is more effective than [mechanism Z] for [context]'\n"
        "- For temporal data: describe trends in prose rather than bullet-point lists\n\n"
        "### Example: BAD vs GOOD Method Description\n"
        "BAD (bullet-list style):\n"
        "  'Our method has three components:\n"
        "   - Component A\n"
        "   - Component B\n"
        "   - Component C'\n\n"
        "GOOD (narrative style):\n"
        "  'Our method builds on the insight that [core problem] stems from\n"
        "   [root cause identified in Section 2]. To address this, we introduce\n"
        "   [MethodName], a [N]-stage framework. First, [Stage 1] maps inputs\n"
        "   to [representation]. These representations feed into [Stage 2],\n"
        "   enabling [benefit] without [drawback of prior approaches].\n"
        "   Crucially, we augment this with [Stage 3] based on [technical\n"
        "   foundation] (cite original paper), triggering [mechanism] when\n"
        "   [condition is met].'\n"
        "  NOTE: Replace all [placeholders] with YOUR actual method details.\n"
        "  Do NOT copy this template verbatim.\n"
    ),
    # IMP-31: Anti-hedging rules
    "anti_hedging_rules": (
        "\n## ANTI-HEDGING RULES (MANDATORY)\n"
        "1. The following phrases are BANNED from the paper body:\n"
        "   - 'we do not claim' / 'we cannot claim'\n"
        "   - 'we intentionally frame this conservatively'\n"
        "   - 'the evidence does not support' (unless followed by what it DOES support)\n"
        "   - 'only N seeds/runs' (belongs ONLY in Limitations, stated ONCE)\n"
        "   - 'this paper is not' / 'we do not' as paragraph openers\n"
        "2. Limitations and caveats MUST be consolidated in the Limitations section.\n"
        "   They may NOT appear in Introduction, Method, Results, or Conclusion.\n"
        "3. Confidence framing: Instead of 'we cannot prove X', write 'our results\n"
        "   provide evidence for X' or 'X is supported by [metrics]'.\n"
        "4. If you have a negative result, frame it as an INSIGHT:\n"
        "   BAD: 'Our method failed to outperform the baseline, we do not claim...'\n"
        "   GOOD: 'Surprisingly, the standard baseline proved competitive, suggesting\n"
        "   that [insight about why] — an observation with practical implications for...'\n"
    ),
    # IMP-24: Anti-repetition rules
    "anti_repetition_rules": (
        "\n## ANTI-REPETITION RULE\n"
        "Each specific number (e.g., '0.7667', '36.7%') may appear in AT MOST 2 sections:\n"
        "  - Once in Results/Experiments (where it is first reported)\n"
        "  - Once in Abstract (as a summary highlight)\n"
        "The Introduction, Discussion, and Conclusion MUST refer to results qualitatively\n"
        "('significantly outperformed', 'X% improvement') WITHOUT repeating exact numbers\n"
        "from the Results section. Violation of this rule will result in desk rejection.\n"
    ),
}

# -- Sub-prompts (secondary LLM calls within a stage) --------------------

_DEFAULT_SUB_PROMPTS: dict[str, dict[str, Any]] = {
    "hypothesis_synthesize": {
        "system": (
            "You are a senior research director synthesizing multiple perspectives "
            "into a decisive research proposal. The best synthesis is not a "
            "compromise but takes the strongest elements from each viewpoint. "
            "Preserve genuine disagreements — do not flatten controversy."
        ),
        "user": (
            "Below are hypotheses generated from three different research perspectives.\n"
            "Synthesize them into a final set of 2-4 hypotheses that:\n"
            "1. Take the strongest, most novel ideas\n"
            "2. Address critical concerns raised by the contrarian\n"
            "3. Ensure feasibility (pragmatist's input)\n"
            "4. Note unresolved disagreements between perspectives\n"
            "5. For each final hypothesis: rationale, measurable prediction, "
            "failure condition\n\n"
            "{perspectives}"
        ),
    },
    "analysis_synthesize": {
        "system": (
            "You are a senior research director synthesizing multiple analytical "
            "perspectives into a comprehensive assessment. Find the truth — if "
            "the skeptic or methodologist raise valid concerns, acknowledge them. "
            "Do not suppress criticism."
        ),
        "user": (
            "Below are analyses from three different perspectives (optimist, "
            "skeptic, methodologist).\n"
            "Produce a unified analysis that:\n"
            "1. Identifies consensus points (high-confidence conclusions)\n"
            "2. Resolves conflicts with evidence-based judgment\n"
            "3. Rates result quality (1-10 with justification)\n"
            "4. Lists 3-5 key findings\n"
            "5. Notes methodology gaps that need addressing\n"
            "6. Gives a clear PROCEED/PIVOT/REFINE recommendation\n\n"
            "Required sections: Metrics Summary, Consensus Findings, "
            "Contested Points, Statistical Checks, Methodology Audit, "
            "Limitations, Conclusion.\n\n"
            "{perspectives}"
        ),
        "max_tokens": 8192,
    },
    "review_synthesize": {
        "system": (
            "You are the area chair synthesizing several independent peer "
            "reviews into one decision-oriented review report. Do not flatten "
            "disagreement — surface the most serious concerns prominently and "
            "do not soften them."
        ),
        "user": (
            "Below are independent reviews of the paper from different "
            "reviewers.\n"
            "Synthesize them into a final review report with these sections:\n"
            "## Summary\n## Strengths\n## Weaknesses (most serious first)\n"
            "## Actionable Revisions (numbered, specific)\n"
            "## Recommendation (ACCEPT / MINOR REVISION / MAJOR REVISION / "
            "REJECT)\n\n"
            "{perspectives}"
        ),
        "max_tokens": 6144,
    },
    "tournament_rank": {
        "system": (
            "You score and rank competing research artifacts, distinct from the "
            "authors. Score each candidate 1-10 on novelty, feasibility, and "
            "rigor, then pick the SINGLE best. Be decisive and critical — do not "
            "average or hedge."
        ),
        "user": (
            "Below are {n} candidate research artifacts. Score and rank them, "
            "then choose the best.\n"
            "Return ONLY JSON (no prose, no markdown fences):\n"
            '{"rankings": [{"id": <int>, "score": <1-10>, "reason": <str>}], '
            '"winner": <int>}\n\n'
            "{candidates}"
        ),
    },
    "debate_rebuttal": {
        "system": (
            "You are participating in a structured research debate as the "
            "{role} perspective. You have seen the other perspectives. Push back "
            "on their weak points, defend or REVISE your own position with "
            "evidence, and concede where they are right. Be rigorous, not "
            "stubborn."
        ),
        "user": (
            "Your previous position ({role}):\n{own_position}\n\n"
            "Other perspectives this round:\n{others}\n\n"
            "Write your rebuttal and updated position."
        ),
    },
    "code_repair": {
        "system": "You fix Python code validation errors while preserving functionality.",
        "user": (
            "The file `{fname}` in the experiment project has validation errors. "
            "Fix ALL issues and return ONLY the corrected file.\n\n"
            "## Validation Issues in {fname}\n{issues_text}\n\n"
            "## All Project Files\n{all_files_ctx}\n\n"
            "IMPORTANT: Do NOT use subprocess, os.system, eval, exec, or any "
            "network/shell calls.\n"
            "NUMPY 2.x: np.trapz→np.trapezoid, np.erfinv→scipy.special.erfinv, "
            "np.bool/int/float→Python builtins.\n"
            "Return ONLY the corrected code for `{fname}`."
        ),
    },
    "iterative_improve": {
        "system": (
            "You improve experiment projects and return valid executable Python code. "
            "Use ```filename:xxx.py format for each file."
        ),
        "user": (
            "Improve the experiment code based on prior run results.\n"
            "Return the improved files using ```filename:xxx.py format for each file.\n"
            "Primary metric key: {metric_key}\n"
            "Metric direction: {metric_direction}\n"
            "Do not use subprocess, os.system, eval, exec, or any network/shell calls.\n"
            "NUMPY 2.x: np.trapz→np.trapezoid, np.erfinv→scipy.special.erfinv, "
            "np.bool/int/float→Python builtins, np.math→math.\n\n"
            "EXPERIMENT PLAN ANCHOR (CRITICAL — read before making changes):\n"
            "The research topic is: {topic}\n"
            "{exp_plan_anchor}"
            "RULES FOR REFINEMENT:\n"
            "- NEVER rename, remove, or replace existing condition names. "
            "The condition names in the code MUST match the experiment plan.\n"
            "- NEVER add new conditions that are not in the experiment plan.\n"
            "- ONLY improve the IMPLEMENTATION of existing conditions "
            "(fix bugs, tune hyperparameters, improve training loops).\n"
            "- If the code has fundamental issues (wrong algorithm, missing "
            "components), fix the implementation but keep the same condition "
            "names and class hierarchy.\n\n"
            "{condition_coverage_hint}"
            "SEED ENFORCEMENT (MANDATORY — BUG-183):\n"
            "- You MUST use exactly seeds = [0, 1, 2] (3 seeds minimum).\n"
            "- Each condition MUST loop over ALL seeds.\n"
            "- Print per-seed: condition=X seed=S {metric_key}: V\n"
            "- Print aggregated: condition=X {metric_key}_mean: M {metric_key}_std: S\n"
            "- If 3 seeds × all conditions exceeds the time budget, REDUCE training "
            "epochs or conditions — NEVER reduce seed count below 3.\n\n"
            "CONDITION COUNT LIMIT (HARD RULE):\n"
            "- MAXIMUM 8 total conditions (baselines + methods + ablations).\n"
            "- If the previous code had >8 conditions, consolidate ablations to 2-3 values.\n\n"
            "DOCKER MOUNT TOPOLOGY (for fixing PermissionError/path issues):\n"
            "- WRITABLE: /workspace/ (project files), /tmp/, /workspace/data/\n"
            "- READ-ONLY: /opt/datasets/ (pre-cached CIFAR-10/100, MNIST, etc)\n"
            "- If you see PermissionError on /opt/datasets, do NOT call "
            "os.makedirs() there. Use root='/opt/datasets' with download=False.\n"
            "- For new data downloads, use /workspace/data/ as root.\n\n"
            "Current project files:\n{files_context}\n"
            "Run summaries (JSON):\n{run_summaries}"
        ),
        "max_tokens": 8192,
    },
    "iterative_repair": {
        "system": "You fix Python validation issues without adding unsafe behavior.",
        "user": (
            "Fix all validation issues in main.py and return corrected Python code only.\n\n"
            "## Validation Issues\n{issue_text}\n\n"
            "## Common RL Stability Fixes (apply if NaN/divergence detected):\n"
            "- Add gradient clipping: `torch.nn.utils.clip_grad_norm_(params, 1.0)`\n"
            "- Lower learning rate to 1e-4 or 3e-4\n"
            "- Add reward normalization/clipping: `reward = np.clip(reward, -10, 10)`\n"
            "- Add NaN guard: `if torch.isnan(loss): continue`\n"
            "- Use float32 (not float16) for RL value functions\n"
            "- NUMPY 2.x: np.trapz→np.trapezoid, np.erfinv→scipy.special.erfinv, "
            "np.bool/int/float→Python builtins\n\n"
            "## All Project Files\n{all_files_ctx}"
        ),
    },
    # ── Advanced Code Agent sub-prompts ──────────────────────────────────
    "architecture_planning": {
        "system": (
            "You are a senior software architect who designs implementation "
            "blueprints for scientific experiment codebases. You produce detailed, "
            "directly-implementable specifications with pseudocode for every "
            "class method and explicit tensor shape annotations. You emphasize "
            "separation of concerns: data loading, model definition, training "
            "loop, and evaluation are distinct components. You understand ML "
            "training deeply and design for correctness: proper .detach(), "
            "consistent tensor shapes, and correct gradient flow.\n\n"
            "NUMPY 2.x COMPATIBILITY (CRITICAL):\n"
            "- np.trapz is REMOVED → use np.trapezoid\n"
            "- np.erfinv does NOT exist → use scipy.special.erfinv\n"
            "- np.bool, np.int, np.float, np.complex are REMOVED → use Python builtins\n"
            "- np.str, np.object are REMOVED → use str, object\n"
            "- np.math is REMOVED → use math module"
        ),
        "user": (
            "Create a detailed IMPLEMENTATION BLUEPRINT for an experiment codebase.\n\n"
            "## Research Context\n"
            "TOPIC: {topic}\n"
            "PRIMARY METRIC: {metric}\n\n"
            "## Experiment Plan\n{exp_plan}\n\n"
            "## Requirements\n"
            "1. `main.py` MUST be the entry point — runs ALL conditions sequentially.\n"
            "2. Each condition MUST be a SEPARATE class with DISTINCT implementation.\n"
            "3. Data loading and model definitions in separate modules.\n"
            "4. No more than 5 Python files total.\n"
            "5. Every class must have at least 20 lines of effective code.\n"
            "6. Child classes MUST override at least one core method with DIFFERENT logic.\n"
            "7. NEVER override nn.Module.train/eval with different signatures.\n"
            "8. Design child classes as STRATEGY variants, not PARAMETER variants.\n\n"
            "## Blueprint Format (YAML)\n"
            "The blueprint MUST include ALL of the following for EACH file:\n"
            "- `generation_order`: integer (1=first to generate, higher=later)\n"
            "- `dependencies`: list of other files this file imports from\n"
            "- `classes` or `functions`: with pseudocode for each method\n"
            "- For neural network classes: input/output tensor shapes\n\n"
            "```yaml\n"
            "files:\n"
            "  - name: config.py\n"
            "    generation_order: 1\n"
            "    dependencies: []\n"
            "    purpose: Hyperparameter configuration\n"
            "    classes:\n"
            "      - name: Config\n"
            "        fields:\n"
            "          - lr: 0.01\n"
            "          - batch_size: 128\n"
            "          - epochs: 20\n"
            "          - hidden_dim: 128\n\n"
            "  - name: data.py\n"
            "    generation_order: 2\n"
            "    dependencies: [config.py]\n"
            "    purpose: Dataset loading and preprocessing\n"
            "    functions:\n"
            "      - name: get_dataloaders\n"
            "        signature: (config) -> (train_loader, val_loader, test_loader)\n"
            "        pseudocode: |\n"
            "          1. Load dataset from torchvision/disk\n"
            "          2. Apply standard transforms (normalize, augment)\n"
            "          3. Split train into train/val (90/10)\n"
            "          4. Return DataLoaders with config.batch_size\n\n"
            "  - name: models.py\n"
            "    generation_order: 3\n"
            "    dependencies: [config.py]\n"
            "    purpose: All model implementations\n"
            "    classes:\n"
            "      - name: BaseModel(nn.Module)\n"
            "        input_shape: [B, 3, 32, 32]\n"
            "        output_shape: [B, 10]\n"
            "        methods:\n"
            "          - name: __init__\n"
            "            pseudocode: Define layers (conv/linear/attention)\n"
            "          - name: forward\n"
            "            pseudocode: |\n"
            "              1. x = self.encoder(x)  # [B,3,32,32] -> [B, hidden]\n"
            "              2. logits = self.classifier(x)  # [B, hidden] -> [B, 10]\n"
            "              3. return logits\n"
            "      - name: ProposedMethod(BaseModel)\n"
            "        differentiator: Uses novel component X\n"
            "        overrides: [forward]\n"
            "        methods:\n"
            "          - name: forward\n"
            "            pseudocode: |\n"
            "              1. x = self.encoder(x)\n"
            "              2. x = self.novel_component(x)  # KEY DIFFERENCE\n"
            "              3. logits = self.classifier(x)\n"
            "              4. return logits\n"
            "          - name: compute_special_loss\n"
            "            pseudocode: |\n"
            "              1. Compute task loss: CE(logits, labels)\n"
            "              2. Compute novel regularizer\n"
            "              3. return task_loss + lambda * reg\n\n"
            "  - name: training.py\n"
            "    generation_order: 4\n"
            "    dependencies: [config.py, data.py, models.py]\n"
            "    purpose: Training loop and evaluation\n"
            "    functions:\n"
            "      - name: train_one_epoch\n"
            "        signature: (model, loader, optimizer, device) -> float\n"
            "        pseudocode: |\n"
            "          1. model.train()\n"
            "          2. For each batch: forward, loss, backward, step\n"
            "          3. Return average loss\n"
            "      - name: evaluate\n"
            "        signature: (model, loader, device) -> dict\n"
            "        pseudocode: |\n"
            "          1. model.eval() with torch.no_grad()\n"
            "          2. For each batch: forward, argmax predictions\n"
            "          3. Return {accuracy, loss}\n\n"
            "  - name: main.py\n"
            "    generation_order: 5\n"
            "    dependencies: [config.py, data.py, models.py, training.py]\n"
            "    purpose: Entry point — runs ALL conditions\n"
            "    contract:\n"
            "      prints_metric_def: true\n"
            "      prints_registered_conditions: true\n"
            "      runs_all_conditions: true\n"
            "      per_seed_reporting: true\n"
            "      time_budget_guard: true\n"
            "    functions:\n"
            "      - name: main\n"
            "        pseudocode: |\n"
            "          1. Print METRIC_DEF line\n"
            "          2. Print REGISTERED_CONDITIONS\n"
            "          3. Setup time budget guard\n"
            "          4. For each condition:\n"
            "             a. Create model instance\n"
            "             b. For each seed:\n"
            "                - Set random seed\n"
            "                - Train model\n"
            "                - Evaluate and print per-seed metrics\n"
            "             c. Print mean/std across seeds\n"
            "          5. Print SUMMARY comparison\n\n"
            "verification_criteria:\n"
            "  - All condition classes have DIFFERENT forward/step implementations\n"
            "  - Input/output tensor shapes are consistent across data->model->loss\n"
            "  - Time budget guard exists in main training loop\n"
            "  - Per-seed random state isolation\n"
            "  - All .detach() calls present for values used across iterations\n\n"
            "conditions:\n"
            "  - name: ConditionName\n"
            "    class: ClassName\n"
            "    description: What makes it different\n"
            "```\n\n"
            "Output ONLY the YAML specification wrapped in ```yaml``` fences.\n"
            "Be SPECIFIC in pseudocode — include tensor shapes, loss formulas, "
            "and algorithmic details from the experiment plan.\n"
            "Every class must have detailed pseudocode showing HOW it differs "
            "from others, not just THAT it differs."
        ),
        "max_tokens": 8192,
    },
    "generate_single_file": {
        "system": (
            "You are an expert ML engineer who writes production-quality Python code "
            "for scientific experiments. You follow implementation blueprints precisely, "
            "ensuring tensor shapes match, gradients flow correctly, and all imports "
            "resolve. You write complete, runnable code — never stubs or placeholders."
        ),
        "user": (
            "Generate the Python file `{file_name}` for an ML experiment project.\n\n"
            "## File Specification\n{file_spec}\n\n"
            "## Full Project Blueprint\n{blueprint}\n\n"
            "## Already Generated Files (summaries)\n{dependency_summaries}\n\n"
            "## Already Generated Files (full code of direct dependencies)\n"
            "{dependency_code}\n\n"
            "## Research Topic\n{topic}\n\n"
            "## Experiment Plan\n{exp_plan}\n\n"
            "## Environment\n{pkg_hint}\n\n"
            "## CRITICAL Rules\n"
            "1. Follow the blueprint specification EXACTLY — implement every class "
            "and function listed for this file.\n"
            "2. Tensor shapes MUST match the blueprint annotations.\n"
            "3. Imports from dependency files MUST use the exact class/function names "
            "from the already-generated code.\n"
            "4. Every method must have a REAL implementation — no `pass`, no `...`, "
            "no `raise NotImplementedError`.\n"
            "5. NEVER use random numbers as fake metrics.\n"
            "6. For RL code: .detach() ALL values from previous iterations before "
            "using in current loss.\n"
            "7. For neural networks: create layers in __init__, not in forward().\n"
            "8. METHOD RICHNESS: Every non-trivial method should be >=5 lines of "
            "real logic. If a method only calls super() or returns a constant, "
            "add the actual computation it should perform. Training methods should "
            "include proper gradient handling, metric logging, and error checks.\n"
            "9. ABLATION DIFFERENTIATION: If this file contains ablation/variant "
            "classes, each MUST differ in actual algorithm logic — not just in "
            "parameter values or by removing a line. Ablations should clearly "
            "implement a different computational path.\n"
            "10. NO CLI CONDITION ARGS: If this is main.py, NEVER add argparse "
            "arguments like --condition or --method. All conditions must be "
            "iterated inside main.py with a for-loop. The harness runs "
            "`python main.py` with no arguments.\n"
            "11. NUMPY 2.x COMPATIBILITY: np.trapz→np.trapezoid, "
            "np.erfinv→scipy.special.erfinv, np.bool/np.int/np.float→Python builtins, "
            "np.str/np.object→str/object, np.math→math.\n\n"
            "Output ONLY the Python code for `{file_name}` — no markdown fences, "
            "no explanations, just the code."
        ),
        "max_tokens": 8192,
    },
    "code_exec_fix": {
        "system": (
            "You are a debugging expert who fixes runtime errors in Python "
            "experiment code. You preserve the original experiment design and "
            "scientific methodology while fixing the specific error. You fix "
            "the ROOT CAUSE, not just the symptom."
        ),
        "user": (
            "The following experiment code crashed during execution.\n\n"
            "## Error Output (stderr, last 3000 chars)\n"
            "```\n{stderr}\n```\n\n"
            "## Standard Output (last 50 lines)\n"
            "```\n{stdout_tail}\n```\n\n"
            "## Return Code: {returncode}\n\n"
            "## Current Code Files\n{files_context}\n\n"
            "## Instructions\n"
            "1. Identify the ROOT CAUSE of the error.\n"
            "2. Fix it while preserving the experiment design.\n"
            "3. Check for similar potential issues in ALL files.\n"
            "4. Do NOT simplify or remove experiment logic — fix the bug.\n"
            "5. Do NOT add subprocess, os.system, eval, exec, or network calls.\n"
            "6. COMMON BUG: If error is about `train()` missing arguments, it means "
            "a class overrode nn.Module.train() with a custom signature. Fix by "
            "renaming the custom method to `fit()` or `run_training()` and updating "
            "all callers. Never override nn.Module.train/eval with extra args.\n"
            "7. NUMPY 2.x: np.trapz→np.trapezoid, np.erfinv→scipy.special.erfinv, "
            "np.bool/int/float/complex→Python builtins, np.str/object→str/object.\n\n"
            "Output ALL files in ```filename:xxx.py``` format, including files "
            "that don't need changes."
        ),
        "max_tokens": 16384,
    },
    "code_reviewer": {
        "system": (
            "You are a meticulous experiment code reviewer focused on "
            "scientific correctness, statistical rigor, and code quality. "
            "You catch bugs that static analysis cannot: incorrect algorithm "
            "implementations, missing controls, wrong metric computation, "
            "and experimental design flaws."
        ),
        "user": (
            "Review this experiment code for correctness and quality.\n\n"
            "## Research Context\n"
            "TOPIC: {topic}\n"
            "PRIMARY METRIC: {metric}\n\n"
            "## Experiment Plan\n{exp_plan}\n\n"
            "## Code Files\n{files_context}\n\n"
            "## Review Criteria\n"
            "1. **CORRECTNESS**: Does the code correctly implement the "
            "experiment plan? Are algorithms implemented properly?\n"
            "2. **COMPLETENESS**: Are all conditions/ablations implemented "
            "with DISTINCT logic? (Not just renamed copies of baseline.)\n"
            "3. **STATISTICAL RIGOR**: Multiple seeds? Results averaged and "
            "reported with std? Paired comparisons?\n"
            "4. **METRIC REPORTING**: Is {metric} correctly computed and "
            "printed in the required format?\n"
            "5. **ROBUSTNESS**: Shape mismatches? Missing imports? Type "
            "errors? Division by zero? GPU/CPU device conflicts?\n"
            "6. **CLASS DEPTH**: Each experimental condition class must have "
            "at least 20 lines of effective code with distinct logic. Classes "
            "that only override __init__ to change parameters are CRITICAL "
            "issues — they indicate the condition is not truly different.\n\n"
            "## Output Format (JSON)\n"
            "```json\n"
            '{{\n'
            '  "verdict": "APPROVE or REVISE",\n'
            '  "score": 1-10,\n'
            '  "critical_issues": ["issue1", "issue2"],\n'
            '  "suggestions": ["suggestion1", "suggestion2"]\n'
            '}}\n'
            "```\n\n"
            "Only use verdict REVISE if there are critical issues that would "
            "cause the code to crash or produce scientifically invalid results."
        ),
        "json_mode": True,
        "max_tokens": 4096,
    },
}