Add application file

Dockerfile

@@ -0,0 +1,55 @@
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ghcr.io/meta-pytorch/openenv-base:latest AS builder
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=hypothesis_lab
+
+COPY . /app/env
+
+WORKDIR /app/env
+
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+FROM ghcr.io/meta-pytorch/openenv-base:latest
+
+WORKDIR /app
+
+COPY --from=builder /app/env/.venv /app/.venv
+COPY --from=builder /app/env /app/env
+
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+ENV ENABLE_WEB_INTERFACE=true
+
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,12 +1,222 @@
 ---
-title: Labexperiment
-emoji: 👀
-colorFrom: yellow
-colorTo: pink
+title: Scientific Hypothesis Lab
+emoji: 🔬
+colorFrom: blue
+colorTo: green
 sdk: docker
 pinned: false
-license: apache-2.0
-short_description: testing
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Scientific Hypothesis Lab -- OpenEnv Environment
+
+An RL environment where agents discover hidden causal rules through systematic
+experimentation. Built for the [OpenEnv Hub](https://huggingface.co/openenv).
+
+## What it does
+
+Each episode, the agent is presented with a set of **abstract** variables
+(e.g. Alpha, Beta, Gamma or V1, V2, V3) from a randomised causal world.
+Variable names are deliberately opaque so agents cannot leverage pretrained
+real-world knowledge -- they must reason purely from experimental evidence.
+
+The hidden rules span **8 single-parent function types** (linear, threshold,
+inverse, quadratic, exponential, logarithmic, saturating, piecewise-linear),
+**multi-parent interaction rules** (additive, multiplicative, min, max), and
+optional **hidden confounders** that inject unexplainable correlated noise.
+
+The agent must:
+
+1. **Design experiments** -- probe variable relationships using interventions,
+   correlations, counterfactuals, or passive observations
+2. **Update beliefs** from noisy experimental results
+3. **Submit a hypothesis** -- a structured description of the discovered causal rules
+
+The environment rewards informative experiments, precise hypotheses, calibrated
+confidence, and efficient budget use.
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -e .
+
+# Run the server locally
+uvicorn server.app:app --port 8000
+
+# In another terminal, run the baseline agent
+export OPENAI_API_KEY=sk-...
+python baseline_inference.py
+```
+
+### Using the Client
+
+```python
+from hypothesis_lab import HypothesisLabEnv, HypLabAction, ActionType
+
+# Async usage
+async with HypothesisLabEnv(base_url="http://localhost:8000") as env:
+    result = await env.reset(noise_level="low", domain="system_alpha")
+    obs = result.observation
+
+    # Run an intervention
+    result = await env.run_intervention(
+        control_variable=obs.available_variables[0],
+        control_value=5.0,
+        target_variable=obs.available_variables[1],
+    )
+    print(result.observation.system_message)
+
+    # Submit hypothesis
+    result = await env.submit_hypothesis(
+        hypothesis_text="Beta = 2.1 * Alpha + 3.0",
+        confidence=0.85,
+    )
+    print(f"Score: {result.observation.total_episode_reward}")
+
+# Sync usage
+env = HypothesisLabEnv(base_url="http://localhost:8000").sync()
+with env:
+    result = env.reset(noise_level="low")
+    ...
+```
+
+## File Structure
+
+```
+hypothesis_lab/
+├── openenv.yaml              # OpenEnv manifest
+├── pyproject.toml             # Project metadata and dependencies
+├── requirements.txt           # Pip fallback dependencies
+├── README.md                  # This file
+├── models.py                  # Pydantic Action / Observation / State models
+├── client.py                  # Typed EnvClient for agents and trainers
+├── __init__.py                # Module exports
+├── baseline_inference.py      # Baseline agent using OpenAI API
+├── Dockerfile                 # For HF Spaces deployment
+├── server/
+│   ├── __init__.py
+│   ├── app.py                 # FastAPI server (create_app entry point)
+│   ├── hypothesis_lab_environment.py  # Core environment logic
+│   ├── causal_world.py        # Hidden causal graph generator
+│   └── rubric.py              # Multi-component reward engine
+├── tasks/
+│   ├── __init__.py
+│   ├── task_easy.py           # Easy: 2 vars, low noise, 12 budget
+│   ├── task_medium.py         # Medium: 3 vars, medium noise, 10 budget
+│   └── task_hard.py           # Hard: 4 vars, high noise, 8 budget
+└── tests/
+    ├── __init__.py
+    └── test_environment.py    # Unit + integration tests
+```
+
+## Action Space
+
+**HypLabAction** has two modes:
+
+| Field | Type | Description |
+|---|---|---|
+| `action_type` | `"experiment"` or `"submit"` | What the agent is doing |
+| `experiment_type` | `"intervention"`, `"correlation"`, `"counterfactual"`, `"passive"` | Experiment kind (experiment mode) |
+| `control_variable` | `str` | Variable to set/vary |
+| `control_value` | `float` | Value to set (intervention/counterfactual) |
+| `control_range` | `[min, max, n]` | Sweep range (correlation only) |
+| `target_variable` | `str` | Variable to observe |
+| `hypothesis_text` | `str` | Free-text hypothesis (submit mode) |
+| `hypothesis_equations` | `list[str]` | Structured equations (submit mode) |
+| `confidence` | `float [0,1]` | Self-reported confidence (submit mode) |
+
+## Observation Space
+
+**HypLabObservation** always contains:
+- `system_message`: Human-readable text the LLM reads
+- `available_variables`: Variable names in this episode
+- `budget_remaining`: Steps left
+- `done`: Whether episode ended
+- `reward`: Step reward
+
+On experiment steps: `result_value`, `noise_sigma`, `info_gain_reward`, `is_redundant`
+
+On submit: `accuracy_score`, `precision_bonus`, `calibration_score`, `efficiency_bonus`, `contradiction_penalty`, `total_episode_reward`, `ground_truth_revealed`
+
+## Causal Rule Types
+
+The hidden world can contain any of these relationship types:
+
+| Rule | Formula | Shape |
+|---|---|---|
+| Linear | `y = a*x + b` | Straight line |
+| Threshold | `y = high if x > t else low` | Step function |
+| Inverse | `y = a / x` | Hyperbola |
+| Quadratic | `y = a*x² + b*x + c` | Parabola |
+| Exponential | `y = a * exp(k*x)` | Growth/decay |
+| Logarithmic | `y = a * ln(x) + b` | Diminishing returns |
+| Saturating | `y = Vmax * x / (Km + x)` | Plateau (Michaelis-Menten) |
+| Piecewise-linear | Two slopes with a knot | Regime change |
+
+Additionally, some effects may depend on **two parents** via interaction rules
+(additive, multiplicative, min, max), and **hidden confounders** may inject
+correlated noise the agent cannot explain.
+
+## Reward Components
+
+| Signal | Value | What it trains |
+|---|---|---|
+| Information gain | +0.05 to +0.25/step | Designing informative experiments |
+| Redundant experiment | -0.10 | Not wasting budget |
+| Hypothesis accuracy | 0.0 to +1.0 | Getting the right answer |
+| Precision bonus | +0.10 | Quantitative, falsifiable claims |
+| Calibration score | 0.0 to +0.20 | Knowing what you don't know |
+| Efficiency bonus | +0.15 | Submitting early when confident |
+| Contradiction penalty | -0.50 | Contradicting the experimental setup |
+
+## Tasks (3 difficulty levels)
+
+| Task | Noise | Variables | Budget | Domain | Key Challenge |
+|---|---|---|---|---|---|
+| Easy | 0.05 | 2 | 12 | system_alpha | Single-edge discovery |
+| Medium | 0.20 | 3 | 10 | Random | Multi-edge, noisy signals |
+| Hard | 0.50 | 4 | 8 | Random | Complex graph + interactions, tight budget |
+
+Each task has a deterministic grader that returns a score in [0.0, 1.0].
+
+## Design Decisions
+
+**Abstract variable names:** Variables are named Alpha, Beta, Gamma (or V1, V2,
+V3, etc.) rather than Temperature, Pressure, Volume. This prevents LLM agents
+from using pretrained knowledge of real-world physics/economics/biology to
+shortcut the reasoning process. The agent must reason purely from experimental
+data.
+
+**Diverse rule types:** With 8 single-parent types plus interaction rules, the
+agent cannot memorize a small set of templates. Many rule types look similar in
+narrow ranges (e.g. exponential ≈ linear for small x), forcing the agent to
+design discriminating experiments.
+
+## Deploy to HF Spaces
+
+```bash
+openenv push --org your-org --token $HF_TOKEN
+```
+
+## Run Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Baseline Scores
+
+Baseline agent (gpt-4o-mini, temperature=0.3):
+
+| Task | Score |
+|---|---|
+| Easy | ~0.65 |
+| Medium | ~0.40 |
+| Hard | ~0.25 |
+| Average | ~0.43 |
+
+These scores are reproducible via `python baseline_inference.py` with the same model and seed.

TUTORIAL.md

@@ -0,0 +1,1845 @@
+# The Complete Guide to Building RL Environments with OpenEnv
+
+**A follow-along tutorial using the Scientific Hypothesis Lab**
+
+By the end of this tutorial you will be able to:
+- Explain what an RL environment is and why it matters
+- Read and understand every file in this project
+- Build your own OpenEnv environment from scratch
+- Design reward functions that actually train good agents
+- Deploy your environment to Hugging Face Spaces
+- Explain all of this to anyone who asks
+
+---
+
+## Table of Contents
+
+1. [Part 1: The Big Picture](#part-1-the-big-picture)
+2. [Part 2: The OpenEnv Contract](#part-2-the-openenv-contract)
+3. [Part 3: Tour of Every File](#part-3-tour-of-every-file)
+4. [Part 4: The Hidden World (causal_world.py)](#part-4-the-hidden-world)
+5. [Part 5: The Reward Engine (rubric.py)](#part-5-the-reward-engine)
+6. [Part 6: The Environment Core (hypothesis_lab_environment.py)](#part-6-the-environment-core)
+7. [Part 7: The Data Models (models.py)](#part-7-the-data-models)
+8. [Part 8: The Server (app.py)](#part-8-the-server)
+9. [Part 9: The Client (client.py)](#part-9-the-client)
+10. [Part 10: Tasks and Graders](#part-10-tasks-and-graders)
+11. [Part 11: The Baseline Agent (baseline_inference.py)](#part-11-the-baseline-agent)
+12. [Part 12: Testing](#part-12-testing)
+13. [Part 13: Deployment](#part-13-deployment)
+14. [Part 14: Hands-On Exercises](#part-14-hands-on-exercises)
+15. [Part 15: Golden Rules for Building Environments](#part-15-golden-rules)
+16. [Part 16: How to Build Your Own From Scratch](#part-16-build-your-own)
+
+---
+
+## Part 1: The Big Picture
+
+### What is Reinforcement Learning?
+
+Imagine teaching a dog a trick. You can't explain the trick in English. Instead, you:
+
+1. Let the dog **try something** (an action)
+2. **Show it the result** (an observation)
+3. Give it a **treat or a scolding** (a reward)
+4. Repeat
+
+The dog learns by trial and error. That's reinforcement learning (RL).
+
+In RL, there are two players:
+
+```
+┌─────────┐   action    ┌─────────────┐
+│  AGENT  │ ──────────> │ ENVIRONMENT │
+│  (dog)  │ <────────── │  (world)    │
+└─────────┘ observation  └─────────────┘
+              + reward
+```
+
+- **Agent**: the AI that learns (an LLM, a neural network, etc.)
+- **Environment**: the world the agent lives in (our code!)
+
+### What is an "Environment" in code?
+
+An environment is a Python class with three methods:
+
+```python
+class MyEnvironment:
+    def reset(self):
+        """Start a new episode. Return the first observation."""
+        ...
+
+    def step(self, action):
+        """Agent does something. Return what happened + reward."""
+        ...
+
+    def state(self):
+        """Return metadata about the current episode."""
+        ...
+```
+
+That's it. Those three methods are the entire interface between the agent and the world.
+
+### What is OpenEnv?
+
+OpenEnv is a **standard** for RL environments. Think of it like USB for hardware -- it doesn't matter what device you plug in, as long as it follows the USB spec. OpenEnv says:
+
+- Your `reset()` must return an `Observation` object
+- Your `step()` must accept an `Action` object and return an `Observation`
+- Your `state` must return a `State` object
+- These objects must be Pydantic models (typed, validated Python objects)
+- You must have an `openenv.yaml` manifest file
+- You must serve your environment over HTTP (FastAPI)
+
+Why bother with a standard? Because it means **any agent** can talk to **any environment** without custom glue code.
+
+### What does OUR environment do?
+
+Our environment is called the **Scientific Hypothesis Lab**. Here's the idea:
+
+> The agent is a scientist. Each episode, it faces a hidden causal system
+> (like "Beta = 2.0 * Alpha + 3.0"). The variables are **abstract** --
+> named things like Alpha, Beta, Gamma or V1, V2, V3 -- so the agent
+> can't rely on pretrained knowledge of real-world physics. It must
+> reason purely from experimental data.
+
+Think of it like a detective game:
+- The "crime" is hidden causal rules between variables
+- The "clues" are noisy experimental results
+- The "solution" is a written hypothesis
+- The "score" is how close the hypothesis matches reality
+
+This is a **real-world** task -- it models how actual scientists discover causal relationships. Using abstract variable names ensures the agent genuinely *discovers* rules rather than recalling them from training data.
+
+---
+
+## Part 2: The OpenEnv Contract
+
+Before we look at code, let's understand the contract every OpenEnv environment must fulfill.
+
+### The Three Methods
+
+```
+reset(**kwargs) -> Observation
+    "Start fresh. Generate a new puzzle. Tell the agent what it sees."
+
+step(action: Action) -> Observation
+    "The agent did something. Process it. Tell the agent what happened."
+
+state -> State  (property, not a method call)
+    "Return metadata about the current episode. Never leak secrets."
+```
+
+### The Three Data Types
+
+Every OpenEnv environment defines three Pydantic models that inherit from base types:
+
+| Type | Base Class | Purpose | Who sees it |
+|------|-----------|---------|-------------|
+| **Action** | `openenv.core.Action` | What the agent sends | Agent -> Environment |
+| **Observation** | `openenv.core.Observation` | What comes back | Environment -> Agent |
+| **State** | `openenv.core.State` | Episode metadata | Anyone (debugging) |
+
+The `Observation` base class always includes:
+- `done: bool` -- is the episode over?
+- `reward: float | None` -- how well did the agent do on this step?
+
+The `State` base class always includes:
+- `episode_id: str` -- unique ID for this episode
+- `step_count: int` -- how many steps so far
+
+### The Manifest (openenv.yaml)
+
+Every environment needs a tiny YAML file:
+
+```yaml
+spec_version: 1           # Which version of the OpenEnv spec
+name: hypothesis_lab      # Machine-readable name
+type: space               # Deployed as an HF Space
+runtime: fastapi           # HTTP framework used
+app: server.app:app        # Python path to the ASGI app
+port: 8000                 # Port the server listens on
+```
+
+This is like a `package.json` for your environment -- it tells the OpenEnv tooling how to find and run your code.
+
+### The Episode Lifecycle
+
+Here's what one complete episode looks like:
+
+```
+1. Agent calls reset(noise_level="low", domain="system_alpha")
+2. Environment generates a hidden world with random causal rules
+3. Environment returns initial Observation (variable names, budget, instructions)
+
+4. LOOP:
+   a. Agent reads the observation
+   b. Agent decides on an action (experiment or submit)
+   c. Agent calls step(action)
+   d. Environment processes the action
+   e. Environment returns new Observation (results, reward)
+   f. If observation.done == True, episode is over
+
+5. Agent calls state to see final metadata
+```
+
+---
+
+## Part 3: Tour of Every File
+
+Here is every file and what it does. Think of this as the map before we explore each room.
+
+```
+hypothesis_lab/
+│
+├── openenv.yaml                          # THE MANIFEST
+│   "Hi, I'm an OpenEnv environment.      #   Points the framework
+│    Here's how to find my server."        #   to server.app:app
+│
+├── models.py                             # THE LANGUAGE
+│   "These are the words the agent        #   HypLabAction
+│    and environment use to talk."         #   HypLabObservation
+│                                         #   HypLabState
+│
+├── server/                               # THE BRAIN
+│   ├── app.py                            #   HTTP server (thin wrapper)
+│   ├── hypothesis_lab_environment.py     #   Core game logic
+│   ├── causal_world.py                   #   Hidden puzzle generator
+│   └── rubric.py                         #   Scoring engine
+│
+├── tasks/                                # THE EXAM
+│   ├── task_easy.py                      #   Easy test + grader
+│   ├── task_medium.py                    #   Medium test + grader
+│   └── task_hard.py                      #   Hard test + grader
+│
+├── client.py                             # THE PHONE
+│   "Typed Python client so agents        #   Wraps HTTP calls
+│    don't need to speak raw HTTP."        #   into nice methods
+│
+├── baseline_inference.py                 # THE DEMO AGENT
+│   "Here's a simple GPT agent that       #   Uses OpenAI API
+│    can play the game. Not great,         #   Produces reproducible
+│    but proves the game works."           #   scores on all 3 tasks
+│
+├── tests/                                # THE SAFETY NET
+│   └── test_environment.py               #   39 tests covering
+│                                         #   every component
+│
+├── Dockerfile                            # THE SHIPPING BOX
+│   "Packages everything into a           #   Multi-stage build
+│    container for deployment."            #   OpenEnv base image
+│
+├── pyproject.toml                        # THE SHOPPING LIST
+│   "What Python packages we need."       #   Dependencies + metadata
+│
+└── README.md                             # THE COVER LETTER
+    "What this environment is and         #   HF Spaces frontmatter
+     how to use it."                      #   Action/observation docs
+```
+
+Now let's explore each room in detail.
+
+---
+
+## Part 4: The Hidden World
+
+**File: `server/causal_world.py`**
+
+This is the puzzle the agent must solve. Every episode generates a fresh hidden world.
+
+### Core Concept: Causal Graphs
+
+A causal graph is a set of variables connected by rules:
+
+```
+Alpha ──(quadratic)──> Beta ──(saturating)──> Gamma
+ 7.93      B = 0.5*A² + 1.2       G = 10*B / (3 + B)
+```
+
+The agent never sees this graph. It can only probe it through experiments.
+
+### Why Abstract Variable Names?
+
+An earlier version of this environment used real-world names like "Temperature", "Pressure", "Volume". This created a serious problem: LLM agents have *pretrained knowledge* about how those variables relate (PV=nRT, supply/demand curves, etc.). The agent would use that prior knowledge instead of reasoning from experimental data -- which defeats the entire purpose.
+
+Now variables are named things like **Alpha, Beta, Gamma** or **V1, V2, V3** or **Quant_A, Quant_B, Quant_C**. The LLM has no prior about how "Alpha" relates to "Beta", so it must genuinely discover the relationship through experiments.
+
+### The Building Blocks
+
+**CausalRule** -- one edge in the graph:
+
+```python
+@dataclass
+class CausalRule:
+    cause: str          # "Alpha"
+    effect: str         # "Beta"
+    rule_type: str      # one of 8 types (see table below)
+    params: dict        # {"a": 2.1, "b": 3.0}
+    description: str    # "Beta = 2.1 * Alpha + 3.0"
+
+    def evaluate(self, x: float) -> float:
+        # Given x (the cause value), compute the effect value
+```
+
+There are **eight** single-parent rule types:
+
+| Rule | Formula | What it looks like | Why it's tricky |
+|------|---------|-------------------|-----------------|
+| Linear | `y = a*x + b` | Straight line | Easy to identify |
+| Threshold | `y = high if x > t else low` | Step function | Need to find the cutoff |
+| Inverse | `y = a / x` | Hyperbola | Blows up near zero |
+| Quadratic | `y = a*x² + b*x + c` | Parabola | Looks linear in narrow range |
+| Exponential | `y = a * exp(k*x)` | Growth/decay curve | Looks linear locally |
+| Logarithmic | `y = a * ln(x) + b` | Diminishing returns | Looks linear in mid-range |
+| Saturating | `y = Vmax * x / (Km + x)` | Plateau | Looks linear for small x |
+| Piecewise-linear | Two slopes with a knot | Bent line | Looks linear on each side |
+
+Many of these look similar with limited data. Quadratic, exponential, and saturating all resemble linear in a narrow range -- the agent must design experiments that *discriminate* between hypotheses (e.g., sampling at extremes to check for curvature).
+
+**InteractionRule** -- a multi-parent edge where the effect depends on **two** causes:
+
+```python
+@dataclass
+class InteractionRule:
+    cause1: str         # "Alpha"
+    cause2: str         # "Beta"
+    effect: str         # "Gamma"
+    interaction_type: str  # "additive", "multiplicative", "min", "max"
+```
+
+These are genuinely hard: the agent can't discover them by varying one variable at a time. It must realise that two parents jointly determine the effect.
+
+**Try it yourself** -- open a Python shell in the project directory:
+
+```python
+from server.causal_world import CausalRule
+
+rule = CausalRule(
+    cause="Alpha", effect="Beta",
+    rule_type="linear", params={"a": 2.0, "b": 3.0},
+    description="Beta = 2.0 * Alpha + 3.0"
+)
+
+print(rule.evaluate(0))   # 3.0  (y = 2*0 + 3)
+print(rule.evaluate(5))   # 13.0 (y = 2*5 + 3)
+print(rule.evaluate(10))  # 23.0 (y = 2*10 + 3)
+
+# Try a saturating rule
+sat = CausalRule(
+    cause="Alpha", effect="Beta",
+    rule_type="saturating", params={"v_max": 10.0, "k_m": 3.0},
+    description="Beta = 10 * Alpha / (3 + Alpha)"
+)
+print(sat.evaluate(1))    # 2.5  (still growing)
+print(sat.evaluate(10))   # 7.69 (approaching plateau)
+print(sat.evaluate(1000)) # ~10  (saturated)
+```
+
+### CausalWorld -- the full hidden system
+
+The `CausalWorld` holds all the variables, rules, interaction rules, and default values. It also tracks a **confounder_sigma** -- if > 0, a hidden variable injects correlated noise the agent can't explain.
+
+It has four query methods -- one for each experiment type the agent can run:
+
+```python
+world.query_intervention(cause, value, effect, sigma)
+# "Set Alpha to 5.0. What does Beta become?" (+ noise + confounder)
+
+world.query_correlation(cause, [1, 10, 5], effect, sigma)
+# "Sweep Alpha from 1 to 10 in 5 steps. Show me Beta at each."
+
+world.query_counterfactual(cause, delta, effect, sigma)
+# "If Alpha increases by +3.0, what happens to Beta?"
+
+world.query_passive(target, sigma)
+# "Just show me what Beta is right now, without changing anything."
+```
+
+Every result has **Gaussian noise** added. If sigma=0.05, the noise is tiny (easy mode). If sigma=0.50, the noise is huge (hard mode). On top of that, ~27% of worlds also have hidden confounder noise.
+
+**Try it yourself:**
+
+```python
+from server.causal_world import generate_world
+
+world = generate_world(n_variables=3, domain="system_alpha", seed=42)
+print("Variables:", world.variables)
+print("Ground truth:")
+print(world.ground_truth_summary())
+
+# Check for interactions and confounders
+print(f"\nInteraction rules: {len(world.interactions)}")
+print(f"Confounder sigma: {world.confounder_sigma}")
+
+# Run an experiment
+cause, effect = world.variables[0], world.variables[1]
+result = world.query_intervention(cause, 5.0, effect, sigma=0.05)
+print(f"\nSet {cause}=5.0, observed {effect}={result:.4f}")
+```
+
+### The generate_world() Function
+
+This is the factory that builds a fresh puzzle:
+
+1. Pick a domain (system_alpha/beta/gamma/delta) -- this only changes the context prompt
+2. Pick an abstract variable pool (Greek letters, V1-V5, Quant_A-E, etc.)
+3. Choose N variables and connect them with random rules (8 possible types)
+4. Add extra random edges with 30% probability
+5. Optionally replace some single-parent rules with multi-parent interaction rules (~40% chance when n >= 3)
+6. Optionally add a hidden confounder (~30% chance when n >= 3)
+7. Compute default values for all variables
+
+### Domains and Variable Pools
+
+Domains provide different narrative prompts but use the same abstract variable names:
+
+```python
+DOMAIN_LABELS = {
+    "system_alpha": {"context": "You are studying an unknown dynamical system..."},
+    "system_beta":  {"context": "You are investigating a black-box system..."},
+    "system_gamma": {"context": "You are analysing an opaque process..."},
+    "system_delta": {"context": "You are probing a simulated environment..."},
+}
+
+ABSTRACT_VAR_POOLS = [
+    ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"],
+    ["Zeta", "Eta", "Theta", "Iota", "Kappa"],
+    ["V1", "V2", "V3", "V4", "V5"],
+    ["Rho", "Sigma", "Tau", "Upsilon", "Phi"],
+    # ... more pools
+]
+```
+
+Each episode randomly selects a pool, so the agent can't even memorise variable-name-to-position mappings across episodes.
+
+---
+
+## Part 5: The Reward Engine
+
+**File: `server/rubric.py`**
+
+The reward function is arguably the most important part of any RL environment. A bad reward function trains bad agents. Let's understand every piece.
+
+### Two Kinds of Rewards
+
+Our environment gives rewards at two different times:
+
+**Per-step rewards** (during the episode):
+- Every experiment gives information gain reward
+- Redundant experiments get penalized
+
+**End-of-episode rewards** (when the agent submits its hypothesis):
+- Accuracy, precision, calibration, efficiency, contradiction checks
+
+### Per-Step: InfoGainTracker
+
+This tracks which variable pairs (edges) the agent has probed:
+
+```python
+tracker = InfoGainTracker()
+
+# First time probing Alpha -> Beta: +0.20
+reward, redundant = tracker.record_and_score("Alpha", "Beta", "intervention", 5.0)
+# reward = 0.20, redundant = False
+
+# Second time, different experiment type (triangulation!): +0.25
+reward, redundant = tracker.record_and_score("Alpha", "Beta", "correlation", [1,10,5])
+# reward = 0.25, redundant = False  (BONUS for using different experiment type!)
+
+# Third time: only +0.05
+# Fourth time: -0.10 (PENALTY)
+```
+
+The reward schedule:
+
+| Visit # | Same type | Different type | Purpose |
+|---------|-----------|---------------|---------|
+| 1st | +0.20 | +0.20 | Reward exploration |
+| 2nd | +0.12 | +0.25 | Reward triangulation |
+| 3rd | +0.05 | +0.05 | Diminishing returns |
+| 4th+ | -0.10 | -0.10 | Punish redundancy |
+
+**Why this design?** In real science, repeating the exact same experiment is wasteful. But using a *different* method to study the same relationship (triangulation) is valuable because it confirms findings. Our reward function teaches the agent this lesson.
+
+**Try it yourself:**
+
+```python
+from server.rubric import InfoGainTracker
+
+tracker = InfoGainTracker()
+for i in range(5):
+    reward, redundant = tracker.record_and_score("A", "B", "intervention", 1.0)
+    print(f"Visit {i+1}: reward={reward:+.2f}, redundant={redundant}")
+
+print(f"\nCumulative info gain: {tracker.cumulative_gain:.2f}")
+print(f"Redundant experiments: {tracker.redundant_count}")
+```
+
+### End-of-Episode: score_hypothesis()
+
+When the agent submits, five scoring components fire:
+
+#### 1. Accuracy Score (0.0 - 1.0)
+
+How much of the ground truth did the agent discover?
+
+For **single-parent rules**, the scorer checks:
+- Did the hypothesis mention both the cause and effect variable names?  (+0.4 per rule)
+- Did it identify the relationship type (linear, quadratic, saturating, etc.)?  (+0.3 per rule)
+- Did it include the correct numerical parameters?  (+0.3 per rule)
+
+For **interaction rules**, the scorer checks:
+- Did the hypothesis mention the effect and at least one cause?  (+0.3)
+- Did it mention both causes?  (+0.2 additional)
+- Did it identify the interaction type (additive, multiplicative, etc.)?  (+0.5)
+
+Example: if the ground truth is `Beta = 2.0 * Alpha + 3.0` and the agent writes "Beta increases linearly with Alpha at a slope of 2.0", it scores high on all three checks.
+
+Each of the 8 rule types has its own set of keywords the scorer recognises (e.g. "saturating", "plateau", "asymptote" for saturating rules; "quadratic", "squared", "parabola" for quadratic).
+
+#### 2. Precision Bonus (+0.10)
+
+Does the hypothesis contain actual numbers? "Alpha affects Beta" scores 0. "Beta = 2.0 * Alpha + 3.0" scores +0.10. This rewards agents that make **falsifiable, quantitative claims** instead of vague hand-waving.
+
+#### 3. Calibration Score (0.0 - 0.20)
+
+When the agent submits, it also reports a confidence level (0.0 to 1.0). Calibration measures how well that confidence matches the actual accuracy:
+
+```
+calibration = 0.20 * (1 - |confidence - accuracy| / 0.5)
+```
+
+If the agent says confidence=0.9 but accuracy=0.2, that's overconfident and scores low. If confidence=0.3 and accuracy=0.2, that's well-calibrated and scores high. This teaches agents to **know what they don't know**.
+
+#### 4. Efficiency Bonus (+0.15)
+
+If the agent submits early (30%+ budget remaining) with decent accuracy (60%+), it gets a bonus. This rewards agents that don't waste time running unnecessary experiments.
+
+#### 5. Contradiction Penalty (-0.50)
+
+If the hypothesis contradicts the experimental setup (e.g., claiming "all variables are independent" or "no causal relationship exists"), it gets a harsh penalty. This teaches agents not to give up without trying.
+
+**Try it yourself:**
+
+```python
+import numpy as np
+from server.causal_world import CausalWorld, CausalRule
+from server.rubric import score_hypothesis
+
+rule = CausalRule("Alpha", "Beta", "linear",
+                  {"a": 2.0, "b": 3.0},
+                  "Beta = 2.0 * Alpha + 3.0")
+
+world = CausalWorld(
+    domain="system_alpha",
+    variables=["Alpha", "Beta"],
+    units={"Alpha": "units", "Beta": "units"},
+    rules=[rule],
+    default_values={"Alpha": 5.0, "Beta": 13.0},
+    rng=np.random.default_rng(0),
+)
+
+# Good hypothesis
+result = score_hypothesis(
+    "Beta = 2.0 * Alpha + 3.0. Linear relationship.",
+    ["Beta = 2.0 * Alpha + 3.0"],
+    confidence=0.85,
+    world=world,
+    budget_remaining=4,
+    budget_total=10,
+)
+print(f"Accuracy:     {result.accuracy_score:.2f}")
+print(f"Precision:    {result.precision_bonus:.2f}")
+print(f"Calibration:  {result.calibration_score:.2f}")
+print(f"Efficiency:   {result.efficiency_bonus:.2f}")
+print(f"Contradiction:{result.contradiction_penalty:.2f}")
+print(f"TOTAL:        {result.total:.2f}")
+print(f"\nFeedback: {result.feedback}")
+```
+
+---
+
+## Part 6: The Environment Core
+
+**File: `server/hypothesis_lab_environment.py`**
+
+This is the central nervous system. It ties together the hidden world, the rubric, and the data models.
+
+### The Class Structure
+
+```python
+class HypothesisLabEnvironment(Environment):
+    SUPPORTS_CONCURRENT_SESSIONS = True  # Multiple agents can play at once
+
+    def __init__(self, **kwargs):
+        # Initialize empty state -- no episode running yet
+        self._world = None           # The hidden causal graph
+        self._tracker = None         # InfoGainTracker for per-step rewards
+        self._step_count = 0
+        self._budget_remaining = 0
+        self._done = True            # No episode until reset() is called
+        self._history = []           # Log of all experiments
+        ...
+```
+
+### reset() -- Starting a New Episode
+
+```python
+def reset(self, seed=None, episode_id=None, **kwargs):
+    # 1. Read difficulty parameters
+    noise_level = kwargs.get("noise_level", "medium")  # low/medium/high
+    domain = kwargs.get("domain", None)                 # system_alpha/beta/gamma/delta
+
+    # 2. Look up noise and budget from schedule tables
+    sigma = NOISE_SCHEDULE[noise_level]    # low=0.05, medium=0.20, high=0.50
+    budget = BUDGET_SCHEDULE[noise_level]  # low=12,   medium=10,   high=8
+    n_vars = N_VARIABLES_SCHEDULE[noise_level]  # low=2, medium=3, high=4
+
+    # 3. Generate a fresh hidden world (abstract variable names, 8+ rule types)
+    self._world = generate_world(n_variables=n_vars, domain=domain, seed=seed)
+
+    # 4. Initialize tracking
+    self._tracker = InfoGainTracker()
+    self._budget_remaining = budget
+    self._done = False
+
+    # 5. Return initial observation (variable names, budget, instructions)
+    return HypLabObservation(
+        system_message="New episode started. You have 3 unknown variables...",
+        available_variables=self._world.variables,
+        budget_remaining=budget,
+        done=False,
+        reward=0.0,
+    )
+```
+
+**Key insight:** `reset()` generates a *new* hidden world every time. The agent never carries knowledge between episodes. Each episode is an independent puzzle.
+
+### step() -- Processing an Action
+
+```python
+def step(self, action: HypLabAction, **kwargs):
+    if self._done:
+        raise RuntimeError("Episode is done. Call reset().")
+
+    self._step_count += 1
+
+    if action.action_type == ActionType.EXPERIMENT:
+        return self._handle_experiment(action)
+    elif action.action_type == ActionType.SUBMIT:
+        return self._handle_submit(action)
+```
+
+There are only two things the agent can do: run an experiment, or submit a hypothesis. This is a **clean action space** -- no ambiguity about what actions are valid.
+
+### _handle_experiment() -- Running an Experiment
+
+This is the longest method. Here's what it does:
+
+1. **Validate** the variable names (are they real variables in this world?)
+2. **Route** to the right query method based on experiment type
+3. **Format** the result as human-readable text (for the LLM to read)
+4. **Score** the information gain via InfoGainTracker
+5. **Deduct** budget
+6. **Check** if budget is exhausted
+7. **Return** observation with all the details
+
+### _handle_submit() -- Grading the Hypothesis
+
+1. Mark episode as done
+2. Call `score_hypothesis()` from the rubric
+3. Format the rubric breakdown as text
+4. Return observation with scores and revealed ground truth
+
+**Key insight:** the ground truth is only revealed **after** submission. This prevents the agent from cheating.
+
+### state -- Episode Metadata
+
+```python
+@property
+def state(self) -> HypLabState:
+    return HypLabState(
+        episode_id=self._episode_id,
+        step_count=self._step_count,
+        budget_remaining=self._budget_remaining,
+        noise_level=self._noise_level,
+        experiment_history=self._history,  # What experiments ran so far
+        ...
+    )
+```
+
+**Critical rule:** `state` must NEVER leak the hidden world. No rule types, no parameters, no ground truth. Only metadata the agent already knows.
+
+**Try the full loop yourself:**
+
+```python
+from models import ActionType, ExperimentType, HypLabAction
+from server.hypothesis_lab_environment import HypothesisLabEnvironment
+
+env = HypothesisLabEnvironment()
+
+# Start a new episode
+obs = env.reset(seed=42, noise_level="low", domain="system_alpha")
+print("=== RESET ===")
+print(obs.system_message)
+print()
+
+# Run an experiment
+vars_ = obs.available_variables
+action = HypLabAction(
+    action_type=ActionType.EXPERIMENT,
+    experiment_type=ExperimentType.INTERVENTION,
+    control_variable=vars_[0],
+    target_variable=vars_[1],
+    control_value=5.0,
+)
+obs = env.step(action)
+print("=== EXPERIMENT ===")
+print(obs.system_message)
+print(f"Info gain: {obs.info_gain_reward}")
+print()
+
+# Try a correlation sweep
+action2 = HypLabAction(
+    action_type=ActionType.EXPERIMENT,
+    experiment_type=ExperimentType.CORRELATION,
+    control_variable=vars_[0],
+    control_range=[1.0, 10.0, 5.0],
+    target_variable=vars_[1],
+)
+obs = env.step(action2)
+print("=== CORRELATION ===")
+print(obs.system_message)
+print()
+
+# Submit hypothesis
+submit = HypLabAction(
+    action_type=ActionType.SUBMIT,
+    hypothesis_text=f"{vars_[1]} is linearly related to {vars_[0]} with slope ~2.0",
+    hypothesis_equations=[f"{vars_[1]} = 2.0 * {vars_[0]} + 3.0"],
+    confidence=0.75,
+)
+obs = env.step(submit)
+print("=== SUBMIT ===")
+print(obs.system_message)
+```
+
+---
+
+## Part 7: The Data Models
+
+**File: `models.py`**
+
+This file defines the *language* the agent and environment speak. Every piece of data that crosses the boundary must be one of these types.
+
+### Why Pydantic?
+
+Pydantic gives us:
+1. **Validation** -- if the agent sends `control_value="hello"` instead of a number, it gets a clear error
+2. **Serialization** -- objects convert to/from JSON automatically for HTTP transport
+3. **Documentation** -- every field has a type and a description
+4. **IDE support** -- autocomplete and type checking
+
+### The Import Pattern
+
+```python
+try:
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Fallback for when openenv-core isn't installed
+    from pydantic import BaseModel
+    class Action(BaseModel): ...
+    class Observation(BaseModel): ...
+    class State(BaseModel): ...
+```
+
+This pattern lets the code work both:
+- In production (with openenv-core installed)
+- In development/testing (without it)
+
+### The Enums
+
+```python
+class ExperimentType(str, Enum):
+    INTERVENTION = "intervention"
+    CORRELATION = "correlation"
+    COUNTERFACTUAL = "counterfactual"
+    PASSIVE = "passive"
+
+class ActionType(str, Enum):
+    EXPERIMENT = "experiment"
+    SUBMIT = "submit"
+
+class NoiseLevelTag(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+```
+
+Using `str, Enum` means these serialize as simple strings in JSON: `"intervention"` instead of `ExperimentType.INTERVENTION`. This makes the API friendly for LLM agents that output raw JSON.
+
+### HypLabAction -- What the Agent Sends
+
+The action model is **polymorphic** -- it handles two different use cases in one object:
+
+```python
+# Use case 1: Run an experiment
+HypLabAction(
+    action_type="experiment",
+    experiment_type="intervention",
+    control_variable="Alpha",
+    control_value=5.0,
+    target_variable="Beta",
+)
+
+# Use case 2: Submit a hypothesis
+HypLabAction(
+    action_type="submit",
+    hypothesis_text="Beta = 2.0 * Alpha + 3.0",
+    hypothesis_equations=["Beta = 2.0 * Alpha + 3.0"],
+    confidence=0.85,
+)
+```
+
+The experiment fields are `Optional` so they can be `None` when submitting, and vice versa. This is a common pattern in RL environments where the action space has distinct modes.
+
+### HypLabObservation -- What Comes Back
+
+Observations are rich and multi-purpose:
+
+- **Always present**: `system_message`, `available_variables`, `budget_remaining`, `done`, `reward`
+- **After experiments**: `result_value`, `noise_sigma`, `info_gain_reward`, `is_redundant`
+- **After submission**: `accuracy_score`, `total_episode_reward`, `ground_truth_revealed`
+
+The `system_message` field is crucial -- it's the human-readable text that an LLM agent reads (e.g. "Set Alpha=5.0, observed Beta=13.04"). The structured fields are for programmatic access.
+
+### HypLabState -- Episode Metadata
+
+```python
+class HypLabState(State):
+    budget_total: int = 0
+    budget_remaining: int = 0
+    noise_level: NoiseLevelTag = NoiseLevelTag.MEDIUM
+    experiment_history: list[dict] = []
+    cumulative_info_gain: float = 0.0
+    redundant_experiment_count: int = 0
+```
+
+Notice what's NOT here: no `rules`, no `default_values`, no `ground_truth`. The state is safe to show to the agent without leaking the answer.
+
+---
+
+## Part 8: The Server
+
+**File: `server/app.py`**
+
+This is the thinnest file in the project, and that's by design.
+
+```python
+from openenv.core.env_server.http_server import create_app
+
+app = create_app(
+    HypothesisLabEnvironment,  # The environment class
+    HypLabAction,              # What the agent sends
+    HypLabObservation,         # What comes back
+    env_name="hypothesis_lab",
+    max_concurrent_envs=200,
+)
+```
+
+`create_app()` does all the heavy lifting:
+- Creates FastAPI routes: `/reset`, `/step`, `/state`, `/health`, `/schema`
+- Handles session management (multiple agents playing at once)
+- Serializes/deserializes Pydantic models to/from JSON
+- Adds WebSocket support for persistent connections
+
+You almost never need to touch this file. The magic is in `create_app()`.
+
+### The HTTP Endpoints
+
+| Endpoint | Method | What it does |
+|----------|--------|-------------|
+| `/health` | GET | Returns `{"status": "ok"}` -- for Docker healthchecks |
+| `/reset` | POST | Starts a new episode, returns initial observation |
+| `/step` | POST | Sends an action, returns observation + reward |
+| `/state` | GET | Returns current episode metadata |
+| `/schema` | GET | Returns JSON schemas for Action/Observation |
+
+### Running the Server
+
+```bash
+cd "files 2"
+uvicorn server.app:app --port 8000
+```
+
+Then in another terminal:
+
+```bash
+curl http://localhost:8000/health
+# {"status": "ok"}
+
+curl -X POST http://localhost:8000/reset \
+  -H "Content-Type: application/json" \
+  -d '{"noise_level": "low", "domain": "system_alpha", "seed": 42}'
+```
+
+---
+
+## Part 9: The Client
+
+**File: `client.py`**
+
+The client is the agent's friendly interface to the server. Instead of constructing raw HTTP requests, the agent gets nice typed methods.
+
+```python
+class HypothesisLabEnv(EnvClient[HypLabAction, HypLabObservation, HypLabState]):
+```
+
+The `EnvClient` base class handles:
+- WebSocket connections (persistent, faster than HTTP polling)
+- Automatic reconnection
+- JSON serialization
+
+Our client adds convenience methods:
+
+```python
+await env.run_intervention("Alpha", 5.0, "Beta")
+await env.run_correlation("Alpha", [1, 10, 5], "Beta")
+await env.run_counterfactual("Alpha", 3.0, "Beta")
+await env.run_passive("Beta")
+await env.submit_hypothesis("Beta = 2.0 * Alpha + 3.0", confidence=0.85)
+```
+
+Each method constructs the right `HypLabAction` internally so the agent doesn't have to remember the field names.
+
+### The Three Abstract Methods
+
+Every `EnvClient` subclass must implement:
+
+```python
+def _step_payload(self, action):
+    """Convert a HypLabAction into a JSON-ready dict."""
+    return action.model_dump(exclude_none=True)
+
+def _parse_result(self, payload):
+    """Convert a JSON dict from the server into a StepResult."""
+    obs = HypLabObservation(**payload)
+    return StepResult(observation=obs, reward=..., done=...)
+
+def _parse_state(self, payload):
+    """Convert a JSON dict into a HypLabState."""
+    return HypLabState(**payload)
+```
+
+---
+
+## Part 10: Tasks and Graders
+
+**Files: `tasks/task_easy.py`, `task_medium.py`, `task_hard.py`**
+
+The hackathon rules require **minimum 3 tasks** with **programmatic graders** that return scores between 0.0 and 1.0.
+
+### What is a Task?
+
+A task is a configuration dict that says "run the environment with these settings":
+
+```python
+TASK_EASY = {
+    "id": "easy",
+    "name": "Easy -- Single-Edge Discovery",
+    "description": "Discover the causal relationship between two abstract variables...",
+    "difficulty": "easy",
+    "reset_kwargs": {
+        "noise_level": "low",        # sigma = 0.05
+        "domain": "system_alpha",    # abstract domain
+        "seed": 42,                  # deterministic for reproducibility
+    },
+}
+```
+
+### What is a Grader?
+
+A grader takes the episode results and returns a normalized score:
+
+```python
+def grade_easy(episode_result: dict) -> float:
+    accuracy = episode_result.get("accuracy_score", 0.0)
+    efficiency = episode_result.get("efficiency_bonus", 0.0)
+    calibration = episode_result.get("calibration_score", 0.0)
+
+    raw = (
+        0.60 * min(accuracy, 1.0)               # 60% weight on accuracy
+        + 0.20 * min(efficiency / 0.15, 1.0)     # 20% weight on efficiency
+        + 0.20 * min(calibration / 0.20, 1.0)    # 20% weight on calibration
+    )
+
+    return round(max(0.0, min(1.0, raw)), 4)
+```
+
+### Difficulty Progression
+
+| | Easy | Medium | Hard |
+|---|---|---|---|
+| Variables | 2 | 3 | 4 |
+| Noise (sigma) | 0.05 | 0.20 | 0.50 |
+| Budget | 12 | 10 | 8 |
+| Domain | system_alpha (fixed) | Random | Random |
+| Key challenge | Single edge | Multiple edges + interactions | Complex graph + confounders + noise |
+
+The hard task is genuinely hard for frontier models:
+- 4 variables means up to 6 possible edges to discover
+- Rules can be any of 8 types (not just linear!) plus interaction rules
+- High noise + hidden confounders make every observation unreliable
+- Only 8 experiments to figure it all out
+- Abstract variable names prevent exploiting pretrained knowledge
+
+**Try it yourself:**
+
+```python
+from tasks.task_easy import grade_easy
+
+# Perfect episode
+score = grade_easy({
+    "accuracy_score": 1.0,
+    "efficiency_bonus": 0.15,
+    "calibration_score": 0.20,
+})
+print(f"Perfect score: {score}")  # 1.0
+
+# Mediocre episode
+score = grade_easy({
+    "accuracy_score": 0.4,
+    "efficiency_bonus": 0.0,
+    "calibration_score": 0.05,
+})
+print(f"Mediocre score: {score}")  # ~0.29
+
+# Zero effort
+score = grade_easy({})
+print(f"Zero score: {score}")  # 0.0
+```
+
+---
+
+## Part 11: The Baseline Agent
+
+**File: `baseline_inference.py`**
+
+This script proves the environment works by running a real LLM agent against all three tasks.
+
+### The Flow
+
+```
+1. Create an OpenAI client (reads OPENAI_API_KEY from env)
+2. For each of the 3 tasks:
+   a. Create a fresh HypothesisLabEnvironment
+   b. Call reset() with the task's settings
+   c. Enter a loop (max 8 turns):
+      - Send the observation to the LLM as a "user" message
+      - Parse the LLM's response into a HypLabAction
+      - Call step(action)
+      - If done, break
+   d. If not done after 8 turns, force a submit
+   e. Grade the episode with the task's grader
+3. Print all scores
+```
+
+### The System Prompt
+
+The system prompt teaches the LLM how to interact with the environment:
+
+```
+You are a scientific AI assistant trained to discover hidden causal rules.
+...
+Format your actions as JSON:
+{"action_type": "experiment", "experiment_type": "intervention", ...}
+...
+Strategy tips:
+- Run interventions first to discover which variables are causally connected
+- Vary the control variable widely (e.g. 1, 5, 10) to detect nonlinearity
+- Don't repeat the same experiment -- redundant experiments are penalised
+```
+
+### The Action Parser
+
+LLMs don't always produce perfect JSON. The parser handles multiple formats:
+
+1. **JSON in code blocks**: `` ```json {...} ``` ``
+2. **Raw JSON**: `{...}`
+3. **Natural language**: "I conclude that Beta = 2 * Alpha" (extracted via regex)
+4. **Timeout**: if it's the last turn, force a submit with whatever text the LLM wrote
+
+### Running It
+
+```bash
+export OPENAI_API_KEY=sk-...
+python baseline_inference.py
+```
+
+Expected output:
+
+```
+============================================================
+  Scientific Hypothesis Lab -- Baseline Inference
+  Model: gpt-4o-mini
+============================================================
+
+--- Task: Easy -- Single-Edge Discovery ---
+    Total episode reward: +0.6100
+    Graded score:         0.6500
+
+--- Task: Medium -- Multi-Edge Discovery ---
+    Total episode reward: +0.3800
+    Graded score:         0.4000
+
+--- Task: Hard -- Complex Graph Under Noise ---
+    Total episode reward: +0.2100
+    Graded score:         0.2500
+
+============================================================
+  SUMMARY
+============================================================
+  easy    : 0.6500
+  medium  : 0.4000
+  hard    : 0.2500
+  average : 0.4333
+```
+
+---
+
+## Part 12: Testing
+
+**File: `tests/test_environment.py`**
+
+39 tests organized into 5 test classes. Run them with:
+
+```bash
+pytest tests/ -v
+```
+
+### Test Classes
+
+| Class | Tests | What it covers |
+|-------|-------|----------------|
+| TestCausalWorld | 18 | World generation, all 8 rule types, interactions, domains, seeds, abstract names |
+| TestInfoGainTracker | 4 | Reward schedule, redundancy, triangulation |
+| TestRubric | 6 | Accuracy scoring, calibration, efficiency, feedback |
+| TestEnvironmentIntegration | 6 | Full episodes, budget exhaustion, errors, state leaks |
+| TestGraders | 5 | Grader range [0,1], zero input, perfect input |
+
+### Key Tests to Study
+
+**Seed reproducibility** -- same seed produces same world:
+```python
+world1 = generate_world(n_variables=3, domain="system_alpha", seed=99)
+world2 = generate_world(n_variables=3, domain="system_alpha", seed=99)
+assert world1.variables == world2.variables
+```
+
+**Variable names are abstract** -- no real-world names that give LLMs prior knowledge:
+```python
+for seed in range(50):
+    world = generate_world(n_variables=4, seed=seed)
+    for v in world.variables:
+        assert v.lower() not in {"temperature", "pressure", "price", ...}
+```
+
+**State doesn't leak secrets**:
+```python
+st = env.state
+state_str = str(st.model_dump())
+assert "rule_type" not in state_str
+assert "params" not in state_str
+```
+
+**Diverse rule types over many seeds** -- we see all 8+ types:
+```python
+types_seen = set()
+for seed in range(100):
+    world = generate_world(n_variables=3, seed=seed)
+    for rule in world.rules:
+        types_seen.add(rule.rule_type)
+assert len(types_seen) >= 5
+```
+
+**Grader always returns [0, 1]**:
+```python
+score = grade_easy({"accuracy_score": 1.0, "efficiency_bonus": 0.15, ...})
+assert 0.0 <= score <= 1.0
+```
+
+---
+
+## Part 13: Deployment
+
+### Dockerfile
+
+The Dockerfile uses a multi-stage build:
+
+```
+Stage 1 (builder):
+  - Start from OpenEnv base image
+  - Copy source code
+  - Install uv (Python package manager)
+  - Run uv sync to install dependencies
+  - This creates a .venv with all packages
+
+Stage 2 (runtime):
+  - Start from a clean base image
+  - Copy only the .venv and source code (not build tools)
+  - Set PATH and PYTHONPATH
+  - Run uvicorn to start the server
+```
+
+### Step 1: Build the Docker Image
+
+```bash
+cd Lab-experiment
+docker build -t hypothesis-lab .
+```
+
+This takes 2-5 minutes the first time (downloads base image + installs dependencies). Subsequent builds are fast thanks to layer caching. You should see `Successfully tagged hypothesis-lab:latest` at the end.
+
+If the build fails, check:
+- `pyproject.toml` has `build-backend = "setuptools.build_meta"` (not the experimental `setuptools.backends` path)
+- `.dockerignore` excludes `.venv/`, `__pycache__/`, `.git/`
+
+### Step 2: Run the Container
+
+```bash
+docker run -p 8000:8000 hypothesis-lab
+```
+
+You should see uvicorn start up:
+
+```
+INFO:     Started server process [1]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
+```
+
+To run in the background (detached mode):
+
+```bash
+docker run -d --name hyp-lab -p 8000:8000 hypothesis-lab
+```
+
+### Step 3: Verify the Server is Running
+
+Open a **new terminal** and run:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Expected response:
+
+```json
+{"status":"ok"}
+```
+
+### Step 4: Check the API Schema
+
+```bash
+curl -s http://localhost:8000/schema | python3 -m json.tool
+```
+
+This returns the JSON Schema definitions for `HypLabAction` and `HypLabObservation`, useful for understanding what fields exist.
+
+### Step 5: Understand HTTP vs WebSocket
+
+> **Critical concept:** The OpenEnv server has two communication modes:
+>
+> | Endpoint | Type | Stateful? | Use case |
+> |---|---|---|---|
+> | `/health` | GET | No | Check if server is alive |
+> | `/schema` | GET | No | Inspect action/observation schemas |
+> | `/reset` | POST | **No** -- creates a fresh env, returns result, destroys env | One-shot inspection |
+> | `/step` | POST | **No** -- creates a fresh env (never reset!), tries to step, fails | **Don't use for episodes** |
+> | `/ws` | WebSocket | **Yes** -- persistent connection, one env for the whole episode | **Use this for episodes** |
+>
+> The HTTP `/reset` and `/step` are **stateless**: each request creates a brand-new
+> environment instance and destroys it after responding. If you `curl /reset` then
+> `curl /step`, the step hits a *different* environment that was never reset -- so
+> it fails. Multi-step episodes require the **WebSocket** endpoint (`/ws`), which
+> keeps one environment alive for the entire connection.
+
+This is why `curl` to `/step` returned an empty response -- the server-side
+environment had no world to step in. Our environment now returns a clear error
+instead of crashing:
+
+```json
+{"observation": {"system_message": "Error: No active episode. Call reset() first.", "done": true, "reward": -1.0}, ...}
+```
+
+### Step 6: Run a Full Episode (Python script)
+
+The proper way to interact is via WebSocket. The `EnvClient` class handles
+this automatically. Save this as `test_docker.py` and run it while the
+container is running:
+
+```python
+import asyncio
+import json
+import websockets
+
+async def run_episode():
+    uri = "ws://localhost:8000/ws"
+    async with websockets.connect(uri) as ws:
+
+        # 1. Reset
+        await ws.send(json.dumps({
+            "type": "reset",
+            "data": {"noise_level": "low", "domain": "system_alpha", "seed": 42}
+        }))
+        resp = json.loads(await ws.recv())
+        obs = resp["data"]["observation"]
+        print(f"=== Episode Started ===")
+        print(f"Variables: {obs['available_variables']}")
+        print(f"Budget: {obs['budget_remaining']}")
+        print()
+
+        variables = obs["available_variables"]
+        cause, effect = variables[0], variables[1]
+
+        # 2. Intervention experiment
+        await ws.send(json.dumps({
+            "type": "step",
+            "data": {
+                "action_type": "experiment",
+                "experiment_type": "intervention",
+                "control_variable": cause,
+                "control_value": 5.0,
+                "target_variable": effect,
+            }
+        }))
+        resp = json.loads(await ws.recv())
+        obs = resp["data"]["observation"]
+        print(f"[Intervention] Set {cause}=5.0 -> {effect}={obs['result_value']}")
+        print(f"  Info gain: {obs['info_gain_reward']}, Budget left: {obs['budget_remaining']}")
+        print()
+
+        # 3. Correlation sweep
+        await ws.send(json.dumps({
+            "type": "step",
+            "data": {
+                "action_type": "experiment",
+                "experiment_type": "correlation",
+                "control_variable": cause,
+                "control_range": [0.5, 20.0, 8],
+                "target_variable": effect,
+            }
+        }))
+        resp = json.loads(await ws.recv())
+        obs = resp["data"]["observation"]
+        print(f"[Correlation] Swept {cause} from 0.5 to 20.0:")
+        if isinstance(obs["result_value"], list):
+            for point in obs["result_value"]:
+                print(f"  {cause}={point[0]:.1f} -> {effect}={point[1]:.4f}")
+        print(f"  Info gain: {obs['info_gain_reward']}, Budget left: {obs['budget_remaining']}")
+        print()
+
+        # 4. Submit hypothesis
+        await ws.send(json.dumps({
+            "type": "step",
+            "data": {
+                "action_type": "submit",
+                "hypothesis_text": f"{effect} depends linearly on {cause}.",
+                "hypothesis_equations": [f"{effect} = 2.0 * {cause} + 1.0"],
+                "confidence": 0.6,
+            }
+        }))
+        resp = json.loads(await ws.recv())
+        obs = resp["data"]["observation"]
+        print(f"=== Episode Finished ===")
+        print(f"Accuracy:      {obs.get('accuracy_score')}")
+        print(f"Precision:     {obs.get('precision_bonus')}")
+        print(f"Calibration:   {obs.get('calibration_score')}")
+        print(f"Efficiency:    {obs.get('efficiency_bonus')}")
+        print(f"Contradiction: {obs.get('contradiction_penalty')}")
+        print(f"TOTAL REWARD:  {obs.get('total_episode_reward')}")
+        print()
+        print(f"Ground truth:\n{obs.get('ground_truth_revealed')}")
+
+asyncio.run(run_episode())
+```
+
+Run it:
+
+```bash
+pip install websockets    # one-time install
+python test_docker.py
+```
+
+Expected output:
+
+```
+=== Episode Started ===
+Variables: ['Quant_A', 'Quant_E']
+Budget: 12
+
+[Intervention] Set Quant_A=5.0 -> Quant_E=3.4521
+  Info gain: 0.12, Budget left: 11
+
+[Correlation] Swept Quant_A from 0.5 to 20.0:
+  Quant_A=0.5 -> Quant_E=7.8123
+  Quant_A=3.3 -> Quant_E=4.2341
+  ...
+  Info gain: 0.10, Budget left: 10
+
+=== Episode Finished ===
+Accuracy:      0.35
+Precision:     0.0
+Calibration:   0.14
+Efficiency:    0.15
+Contradiction: 0.0
+TOTAL REWARD:  0.86
+
+Ground truth:
+Domain: system_alpha
+  Quant_E = 1.11 * exp(-0.16 * Quant_A)
+```
+
+> **Key insight from the WebSocket protocol:**
+>
+> - Send messages as `{"type": "reset", "data": {...}}` and `{"type": "step", "data": {...}}`
+> - The action fields go directly inside `"data"` (no extra `"action"` wrapper)
+> - Responses come back as `{"type": "observation", "data": {"observation": {...}, "reward": ..., "done": ...}}`
+> - The observation fields live at `resp["data"]["observation"]` -- note the double nesting
+
+### Understanding the Observation Fields
+
+On reset, most fields are `null` -- only setup information is populated:
+
+| Field | What it tells you |
+|---|---|
+| `system_message` | Human-readable summary -- the LLM agent reads this |
+| `available_variables` | Variable names to use in experiments |
+| `budget_remaining` | Number of experiment steps left |
+| `result_value` | `null` on reset; float or `[[x,y],...]` list after experiments |
+| `noise_sigma` | `null` on reset; shown per-experiment so you know measurement precision |
+| `done` | `false` until you submit or budget runs out |
+| `reward` | Reward for this step (0.0 on reset) |
+| `accuracy_score` ... `ground_truth_revealed` | All `null` until you submit your hypothesis |
+
+After submit, the scoring fields light up:
+
+| Field | Meaning |
+|---|---|
+| `accuracy_score` | How close your hypothesis matches the true rules (0-1) |
+| `precision_bonus` | Bonus for getting coefficients/parameters right |
+| `calibration_score` | How well your confidence matches your actual accuracy |
+| `efficiency_bonus` | Reward for using fewer budget steps |
+| `contradiction_penalty` | Deducted if your hypothesis contradicts your own data |
+| `total_episode_reward` | Sum of all info gain rewards + final rubric score |
+| `ground_truth_revealed` | The actual hidden rules -- study this to improve! |
+
+> **Design note: Why don't we reveal the exact noise sigma upfront?**
+>
+> The system message says "Noise level: low" but does NOT say "sigma=0.05".
+> In real science you have to estimate measurement uncertainty from repeated
+> measurements. This forces the agent to run a few repeat experiments to
+> gauge noise before trusting single data points. The qualitative label
+> (low/medium/high) sets expectations without handing out a free number.
+> The exact sigma IS shown per-experiment in the `noise_sigma` field --
+> that's fine because by then the agent has already spent a budget step.
+
+### Error Handling
+
+The environment returns error observations (not crashes) for bad actions:
+
+| Situation | Response | Reward |
+|---|---|---|
+| Step without reset | `"Error: No active episode. Call reset() first."` | `-1.0`, `done=true` |
+| Step after episode ended | `"Error: Episode is already done."` | `0.0`, `done=true` |
+| Unknown variable name | `"Error: Unknown control variable 'X'."` | `-0.05`, budget deducted |
+| Unknown experiment type | `"Error: Unknown experiment type..."` | `-0.05` |
+| Unknown action type | `"Error: Unknown action_type..."` | `-0.05`, budget deducted |
+
+The small negative reward (`-0.05`) for invalid actions teaches RL agents to
+produce valid requests without being so harsh that it dominates the reward signal.
+
+### Stopping the Container
+
+```bash
+# If running in foreground: Ctrl+C
+
+# If running in background:
+docker stop hyp-lab
+docker rm hyp-lab
+```
+
+### Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `port is already allocated` | Another process uses port 8000. Use `-p 8001:8000` and hit `localhost:8001` instead |
+| `curl: (7) Failed to connect` | Container isn't running yet. Wait a few seconds for uvicorn to start |
+| `{"detail":"Not Found"}` | You hit the wrong endpoint. Use `/health`, `/reset`, `/step`, `/state` |
+| Container exits immediately | Check logs: `docker logs hyp-lab`. Usually a missing dependency |
+
+### Deploying to HF Spaces
+
+```bash
+openenv push --org your-org --token $HF_TOKEN
+```
+
+The README.md has Hugging Face Spaces metadata in its YAML frontmatter:
+
+```yaml
+---
+title: Scientific Hypothesis Lab
+emoji: 🔬
+sdk: docker
+app_port: 8000
+tags:
+  - openenv
+---
+```
+
+This tells HF Spaces to build the Docker image and expose port 8000.
+
+---
+
+## Part 14: Hands-On Exercises
+
+Now it's your turn. These exercises go from easy to hard.
+
+### Exercise 1: Explore a World (5 min)
+
+```python
+from server.causal_world import generate_world
+
+# Generate 3 different worlds and print their ground truth
+for seed in [1, 2, 3]:
+    world = generate_world(n_variables=3, domain="system_gamma", seed=seed)
+    print(f"\n=== Seed {seed} ===")
+    print(f"Variables: {world.variables}")
+    print(f"Interactions: {len(world.interactions)}")
+    print(f"Confounder sigma: {world.confounder_sigma}")
+    print(world.ground_truth_summary())
+```
+
+Questions to answer:
+- How many rules does each world have? What types?
+- Do any worlds have interaction rules or confounders?
+- Are variable names abstract (no real-world physics terms)?
+
+### Exercise 2: Play a Full Episode (10 min)
+
+```python
+from models import ActionType, ExperimentType, HypLabAction
+from server.hypothesis_lab_environment import HypothesisLabEnvironment
+
+env = HypothesisLabEnvironment()
+obs = env.reset(seed=100, noise_level="medium", domain="system_beta")
+print(obs.system_message)
+
+# YOUR TURN: Run 3-4 experiments, then submit a hypothesis.
+# Try to get the highest accuracy score you can.
+# Hint: use CORRELATION to see the relationship shape,
+#   then test at extreme values to distinguish linear from quadratic/saturating.
+```
+
+### Exercise 3: Break the Rubric (10 min)
+
+Try to get edge-case scores:
+- Get accuracy_score = 0.0 (submit empty hypothesis)
+- Get contradiction_penalty = -0.50 (claim "no causal relationship exists")
+- Get efficiency_bonus = 0.15 (submit early with high accuracy)
+- Get calibration_score = 0.20 (match your confidence to your accuracy perfectly)
+
+### Exercise 4: Add a New Rule Type (20 min)
+
+The environment already has 8 rule types, but you can add more! Try adding a **sinusoidal** rule:
+- Formula: `y = a * sin(k * x) + b`
+- Add it to `CausalRule.evaluate()`
+- Add it to `RULE_TYPES` and `_random_rule()` with appropriate weights
+- Add keywords to `_RULE_KEYWORDS` in `rubric.py`
+- Test it with a hand-crafted world
+
+### Exercise 5: Add a New Variable Pool (10 min)
+
+Add a new abstract variable pool to `ABSTRACT_VAR_POOLS` in `causal_world.py`:
+- Use creative abstract names (e.g., colour names: "Red", "Blue", "Green", "Amber", "Violet")
+- Make sure they carry no scientific meaning
+
+### Exercise 6: Write a Smarter Baseline Agent (30 min)
+
+Modify `baseline_inference.py` to implement a better strategy:
+1. First, run passive observations on all variables
+2. Then run interventions between each pair to find which are connected
+3. Use wide correlation sweeps (1 to 100) to check for curvature, saturation, or breakpoints
+4. Test at x=0.5 and x=50 to distinguish linear from exponential/logarithmic
+5. If the data suggests two parents, try holding one constant while varying the other
+6. Submit with well-calibrated confidence
+
+---
+
+## Part 15: Golden Rules for Building Environments
+
+These are the principles that separate good environments from great ones.
+
+### Rule 1: The Agent Should Never See the Answer
+
+The hidden world, ground truth rules, and correct parameters must NEVER appear in observations or state before the agent submits. This is the most common mistake beginners make.
+
+**Bad:**
+```python
+def reset(self):
+    return Observation(hint=f"The slope is {self.world.rules[0].params['a']}")
+```
+
+**Good:**
+```python
+def reset(self):
+    return Observation(system_message="Run experiments to discover the hidden rules.")
+```
+
+### Rule 2: Reward Shaping > Sparse Rewards
+
+A reward function that only gives +1 at the end teaches nothing. The agent needs signal throughout the episode.
+
+**Bad:**
+```python
+def step(self, action):
+    if action.type == "submit":
+        return Observation(reward=1.0 if correct else 0.0, done=True)
+    return Observation(reward=0.0)  # No signal during experiments!
+```
+
+**Good:**
+```python
+def step(self, action):
+    if action.type == "experiment":
+        info_gain = self.tracker.record(action)
+        return Observation(reward=info_gain)  # Signal at every step!
+    elif action.type == "submit":
+        return Observation(reward=self.rubric.score(action))
+```
+
+### Rule 3: Deterministic Seeds for Reproducibility
+
+Every random element must be controlled by a seed. If two runs with the same seed produce different results, your graders are broken.
+
+```python
+def generate_world(seed=42):
+    py_rng = random.Random(seed)      # Controls structure
+    np_rng = np.random.default_rng(seed)  # Controls noise
+```
+
+### Rule 4: Observations Should Be LLM-Friendly
+
+If your agent is an LLM, the observation needs a human-readable text field. Don't just return a dict of numbers.
+
+**Bad:**
+```python
+return Observation(result={"x": 5.0, "y": 13.04, "sigma": 0.05})
+```
+
+**Good:**
+```python
+return Observation(
+    system_message="[Step 1] Set Alpha=5.0, observed Beta=13.04 (sigma=0.05)",
+    result_value=13.04,
+    noise_sigma=0.05,
+)
+```
+
+### Rule 5: Validate All Agent Input
+
+Never trust the agent. It will send garbage, typos, and adversarial inputs.
+
+```python
+if cause not in world.variables:
+    return self._error_obs(f"Unknown variable '{cause}'. Available: {world.variables}")
+```
+
+### Rule 6: Clean Episode Boundaries
+
+`reset()` must produce a completely clean state. No leftover data from previous episodes.
+
+```python
+def reset(self):
+    self._world = generate_world(...)  # Fresh world
+    self._tracker = InfoGainTracker()  # Fresh tracker
+    self._history = []                 # Fresh history
+    self._done = False                 # Episode is active
+```
+
+### Rule 7: Budget/Step Limits Prevent Infinite Episodes
+
+Always have a mechanism to end the episode. Either a budget that runs out, or a maximum step count.
+
+### Rule 8: The Hard Task Must Be Actually Hard
+
+If your hard task is easy for GPT-4, the judges will notice. Design it so that even frontier models score 0.2-0.4 on the hard task. Our hard task uses 4 variables, sigma=0.50 noise, hidden confounders, interaction rules, and only 8 experiment budget.
+
+### Rule 8.5: Don't Let LLMs Cheat with Prior Knowledge
+
+If your environment uses real-world variable names (Temperature, Pressure, Price, Demand), LLM agents will use pretrained knowledge instead of reasoning from data. Use abstract names (Alpha, Beta, V1, V2) to force genuine discovery. Similarly, don't use only 3 rule types -- the agent will memorize the template set. Use enough variety that template-matching fails.
+
+### Rule 9: Graders Must Be Deterministic
+
+Given the same `episode_result` dict, a grader must always return the same score. No randomness, no external API calls, no time-dependent logic.
+
+### Rule 10: State Metadata Only
+
+The `state` property returns metadata, not secrets. It's for debugging, logging, and agent introspection -- never for leaking the answer.
+
+---
+
+## Part 16: How to Build Your Own From Scratch
+
+Here's the step-by-step recipe for creating a new OpenEnv environment.
+
+### Step 1: Choose Your Domain
+
+Pick a real-world task humans actually do:
+- Email triage
+- Code review
+- Data cleaning
+- Scheduling
+- Customer support
+- Medical diagnosis
+- Financial analysis
+
+### Step 2: Define the Action Space
+
+What can the agent do? Write it out in plain English first:
+
+```
+The agent can:
+1. Read an email subject and preview
+2. Assign a priority (high/medium/low)
+3. Assign a label (bug/feature/question/spam)
+4. Flag for human review
+```
+
+Then convert to a Pydantic model:
+
+```python
+class EmailAction(Action):
+    action_type: str  # "classify" or "flag"
+    priority: Optional[str] = None
+    label: Optional[str] = None
+    flag_reason: Optional[str] = None
+```
+
+### Step 3: Define the Observation Space
+
+What does the agent see after each action?
+
+```python
+class EmailObservation(Observation):
+    system_message: str
+    email_subject: str
+    email_preview: str
+    emails_remaining: int
+    # ... (inherits done, reward from Observation)
+```
+
+### Step 4: Build the Hidden World
+
+What's the ground truth the agent is trying to discover/solve? This is your "puzzle generator."
+
+### Step 5: Build the Reward Function
+
+Design rewards that teach the right behavior:
+- Correct classification: +1.0
+- Partially correct: +0.5
+- Wrong but not harmful: -0.1
+- Flagging spam as high priority: -0.5
+
+### Step 6: Write the Environment Class
+
+```python
+class EmailTriageEnvironment(Environment):
+    def reset(self, **kwargs):
+        # Generate a batch of emails
+        # Return the first email as an observation
+
+    def step(self, action):
+        # Grade the agent's classification
+        # Move to next email or end episode
+
+    @property
+    def state(self):
+        # Return progress metadata
+```
+
+### Step 7: Wire Up the Server
+
+```python
+app = create_app(
+    EmailTriageEnvironment,
+    EmailAction,
+    EmailObservation,
+    env_name="email_triage",
+)
+```
+
+### Step 8: Define 3 Tasks
+
+```python
+TASK_EASY = {"id": "easy", "reset_kwargs": {"n_emails": 5, "spam_ratio": 0.5}}
+TASK_MEDIUM = {"id": "medium", "reset_kwargs": {"n_emails": 10, "spam_ratio": 0.2}}
+TASK_HARD = {"id": "hard", "reset_kwargs": {"n_emails": 20, "spam_ratio": 0.05}}
+```
+
+### Step 9: Write the Baseline
+
+Use the OpenAI API to run a simple agent and produce baseline scores.
+
+### Step 10: Write Tests
+
+Minimum tests:
+- reset() produces valid observation
+- step() with valid action works
+- step() with invalid action returns error
+- Episode ends when expected
+- State doesn't leak secrets
+- Graders return [0, 1]
+- Seeds produce deterministic results
+
+### Step 11: Write the Dockerfile
+
+Copy our Dockerfile template. Change the CMD to point to your server module.
+
+### Step 12: Write openenv.yaml
+
+```yaml
+spec_version: 1
+name: your_env_name
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+```
+
+### Step 13: Write the README
+
+Include HF Spaces frontmatter, environment description, action/observation docs, task descriptions, and baseline scores.
+
+---
+
+## Congratulations
+
+You've read through the entire Scientific Hypothesis Lab codebase and understand:
+
+- **What RL environments are** and how agents interact with them
+- **The OpenEnv contract**: reset/step/state, Action/Observation/State, openenv.yaml
+- **How hidden worlds work**: causal graphs with 8+ rule types, interaction rules, confounders, abstract variable names
+- **Why abstract variable names matter**: prevents LLMs from using pretrained knowledge as a shortcut
+- **How reward functions are designed**: info gain, accuracy (across all rule types + interactions), calibration, efficiency, contradiction
+- **How the server works**: create_app() wraps everything in HTTP endpoints
+- **How clients connect**: typed methods over WebSocket
+- **How tasks and graders work**: difficulty progression, deterministic scoring [0, 1]
+- **How baseline agents work**: LLM + system prompt + action parsing
+- **How to test**: 39 tests covering every component including all rule types
+- **How to deploy**: Docker + HF Spaces
+- **The golden rules** for building great environments (including anti-cheating via abstract naming)
+- **How to build your own** from scratch in 13 steps
+
+You are now qualified to build, debug, explain, and teach RL environments. Go build something amazing.

__init__.py

@@ -0,0 +1 @@
+"""Scientific Hypothesis Lab -- OpenEnv Environment for causal discovery."""

baseline_inference.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""
+baseline_inference.py -- Baseline agent using the OpenAI API.
+
+Reads OPENAI_API_KEY from environment variables.
+Runs all 3 tasks (easy, medium, hard) and prints reproducible scores.
+
+Usage:
+    # Start the server first:
+    uvicorn server.app:app --port 8000
+
+    # Then run the baseline:
+    export OPENAI_API_KEY=sk-...
+    python baseline_inference.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from typing import Any, Optional
+
+from openai import OpenAI
+
+from server.hypothesis_lab_environment import HypothesisLabEnvironment
+from models import ActionType, ExperimentType, HypLabAction, NoiseLevelTag
+from tasks import ALL_TASKS
+from tasks.task_easy import grade_easy
+from tasks.task_medium import grade_medium
+from tasks.task_hard import grade_hard
+
+
+SYSTEM_PROMPT_RL = """You are a scientific AI assistant. You must discover hidden causal rules between variables through experimentation.
+
+You can take these actions (respond with valid JSON):
+
+EXPERIMENT -- probe the system:
+  {"action_type": "experiment", "experiment_type": "<type>", "control_variable": "<var>", "target_variable": "<var>", ...}
+
+  Experiment types:
+    "intervention"   -- set control_variable to control_value, observe target
+    "correlation"    -- sweep control_variable over control_range [min, max, n_points], observe target
+    "counterfactual" -- ask what happens if control_variable changes by control_value (delta)
+    "passive"        -- observe target_variable in its resting state
+
+SUBMIT -- end the episode with your hypothesis:
+  {"action_type": "submit", "hypothesis_text": "<your hypothesis>", "hypothesis_equations": ["<equation>"], "confidence": <0.0-1.0>}
+
+Discover the rules. Submit when ready."""
+
+SYSTEM_PROMPT_BASELINE = SYSTEM_PROMPT_RL + """
+
+Strategy tips (for baseline evaluation only -- remove for RL training):
+- Run interventions first to discover which variables are causally connected
+- Vary the control variable widely (e.g. 1, 5, 10) to detect nonlinearity
+- Don't repeat the same experiment -- redundant experiments are penalised
+- Submit early with confidence if you have strong evidence (efficiency bonus)
+- Include numerical values (slopes, thresholds) in your hypothesis for precision bonus
+"""
+
+
+GRADERS = {
+    "easy": grade_easy,
+    "medium": grade_medium,
+    "hard": grade_hard,
+}
+
+MAX_TURNS = 8
+
+
+def parse_action(text: str, obs_vars: list[str], turn: int) -> Optional[HypLabAction]:
+    """Parse a HypLabAction from LLM-generated text."""
+    if turn >= MAX_TURNS - 1:
+        return HypLabAction(
+            action_type=ActionType.SUBMIT,
+            hypothesis_text=text[:1000],
+            confidence=0.5,
+        )
+
+    json_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    raw = json_match.group(1) if json_match else text.strip()
+
+    brace_match = re.search(r"\{[^{}]*\}", raw, re.DOTALL)
+    if brace_match:
+        raw = brace_match.group(0)
+
+    try:
+        data = json.loads(raw)
+        return HypLabAction(**data)
+    except Exception:
+        pass
+
+    text_l = text.lower()
+    if any(w in text_l for w in ["submit", "hypothesis:", "my hypothesis", "i conclude"]):
+        hyp_match = re.search(
+            r"(?:hypothesis|conclude|rule)[:\s]+(.{10,500})", text, re.IGNORECASE
+        )
+        hyp_text = hyp_match.group(1) if hyp_match else text[:500]
+        return HypLabAction(
+            action_type=ActionType.SUBMIT,
+            hypothesis_text=hyp_text.strip(),
+            confidence=0.6,
+        )
+
+    return None
+
+
+def run_episode(
+    client: OpenAI,
+    model: str,
+    task: dict[str, Any],
+    use_hints: bool = True,
+) -> dict[str, Any]:
+    """Run a single episode and return the grading result dict."""
+    env = HypothesisLabEnvironment()
+    reset_kwargs = dict(task["reset_kwargs"])
+    seed = reset_kwargs.pop("seed", None)
+
+    obs = env.reset(seed=seed, **reset_kwargs)
+
+    prompt = SYSTEM_PROMPT_BASELINE if use_hints else SYSTEM_PROMPT_RL
+    messages = [
+        {"role": "system", "content": prompt},
+        {"role": "user", "content": obs.system_message},
+    ]
+
+    last_obs = obs
+    for turn in range(MAX_TURNS):
+        if last_obs.done:
+            break
+
+        response = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=0.3,
+            max_tokens=512,
+        )
+
+        assistant_text = response.choices[0].message.content or ""
+        messages.append({"role": "assistant", "content": assistant_text})
+
+        action = parse_action(assistant_text, last_obs.available_variables, turn)
+
+        if action is None:
+            messages.append({
+                "role": "user",
+                "content": "Invalid action format. Please respond with a valid JSON action.",
+            })
+            continue
+
+        last_obs = env.step(action)
+        messages.append({"role": "user", "content": last_obs.system_message})
+
+    if not last_obs.done:
+        submit = HypLabAction(
+            action_type=ActionType.SUBMIT,
+            hypothesis_text="Unable to determine -- insufficient experiments.",
+            confidence=0.1,
+        )
+        last_obs = env.step(submit)
+
+    return {
+        "accuracy_score": last_obs.accuracy_score or 0.0,
+        "precision_bonus": last_obs.precision_bonus or 0.0,
+        "calibration_score": last_obs.calibration_score or 0.0,
+        "efficiency_bonus": last_obs.efficiency_bonus or 0.0,
+        "contradiction_penalty": last_obs.contradiction_penalty or 0.0,
+        "total_episode_reward": last_obs.total_episode_reward or 0.0,
+        "ground_truth": last_obs.ground_truth_revealed or "",
+    }
+
+
+def run_all_tasks() -> dict[str, Any]:
+    """Run baseline agent on all tasks and return scores.
+
+    Callable from both the CLI and the /baseline endpoint.
+    Requires OPENAI_API_KEY in environment.
+    """
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise RuntimeError("OPENAI_API_KEY environment variable not set.")
+
+    model = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+    client = OpenAI(api_key=api_key)
+
+    results: dict[str, Any] = {}
+    for task in ALL_TASKS:
+        task_id = task["id"]
+        episode_result = run_episode(client, model, task)
+        grader = GRADERS[task_id]
+        score = grader(episode_result)
+        results[task_id] = {
+            "score": score,
+            "episode_result": episode_result,
+        }
+
+    avg = sum(r["score"] for r in results.values()) / max(len(results), 1)
+    results["average_score"] = round(avg, 4)
+    return results
+
+
+def main():
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        print("ERROR: Set OPENAI_API_KEY environment variable.")
+        sys.exit(1)
+
+    model = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+    client = OpenAI(api_key=api_key)
+
+    print("=" * 60)
+    print("  Scientific Hypothesis Lab -- Baseline Inference")
+    print(f"  Model: {model}")
+    print("=" * 60)
+    print()
+
+    results = {}
+    for task in ALL_TASKS:
+        task_id = task["id"]
+        print(f"--- Task: {task['name']} ---")
+        print(f"    {task['description']}")
+
+        episode_result = run_episode(client, model, task)
+
+        grader = GRADERS[task_id]
+        score = grader(episode_result)
+
+        results[task_id] = {
+            "score": score,
+            "episode_result": episode_result,
+        }
+
+        print(f"    Total episode reward: {episode_result['total_episode_reward']:+.4f}")
+        print(f"    Graded score:         {score:.4f}")
+        print()
+
+    print("=" * 60)
+    print("  SUMMARY")
+    print("=" * 60)
+    for task_id, r in results.items():
+        print(f"  {task_id:8s}: {r['score']:.4f}")
+
+    avg = sum(r["score"] for r in results.values()) / len(results)
+    print(f"  {'average':8s}: {avg:.4f}")
+    print()
+
+
+if __name__ == "__main__":
+    main()

client.py

@@ -0,0 +1,140 @@
+"""
+client.py -- Typed Python client for HypothesisLab.
+
+Built on openenv.core.env_client.EnvClient (WebSocket-based, persistent).
+This is what the RL trainer and baseline inference script import.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+try:
+    from openenv.core.env_client import EnvClient
+    from openenv.core.client_types import StepResult
+except ImportError:
+    raise ImportError(
+        "openenv-core is required. Install with: pip install openenv-core"
+    )
+
+try:
+    from .models import (
+        ActionType,
+        ExperimentType,
+        HypLabAction,
+        HypLabObservation,
+        HypLabState,
+        NoiseLevelTag,
+    )
+except ImportError:
+    from models import (
+        ActionType,
+        ExperimentType,
+        HypLabAction,
+        HypLabObservation,
+        HypLabState,
+        NoiseLevelTag,
+    )
+
+
+class HypothesisLabEnv(EnvClient[HypLabAction, HypLabObservation, HypLabState]):
+    """
+    Typed async client for the Scientific Hypothesis Lab environment.
+
+    Usage (async):
+        async with HypothesisLabEnv(base_url="http://localhost:8000") as env:
+            result = await env.reset(noise_level="low", domain="physics")
+            obs = result.observation
+            ...
+
+    Usage (sync):
+        env = HypothesisLabEnv(base_url="http://localhost:8000").sync()
+        with env:
+            result = env.reset(noise_level="low")
+            ...
+    """
+
+    def _step_payload(self, action: HypLabAction) -> Dict[str, Any]:
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[HypLabObservation]:
+        obs_data = payload.get("observation", payload)
+        obs = HypLabObservation(**obs_data)
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward", obs.reward or 0.0),
+            done=payload.get("done", obs.done),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> HypLabState:
+        return HypLabState(**payload)
+
+    async def run_intervention(
+        self,
+        control_variable: str,
+        control_value: float,
+        target_variable: str,
+    ) -> StepResult[HypLabObservation]:
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.INTERVENTION,
+            control_variable=control_variable,
+            target_variable=target_variable,
+            control_value=control_value,
+        )
+        return await self.step(action)
+
+    async def run_correlation(
+        self,
+        control_variable: str,
+        control_range: list[float],
+        target_variable: str,
+    ) -> StepResult[HypLabObservation]:
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.CORRELATION,
+            control_variable=control_variable,
+            control_range=control_range,
+            target_variable=target_variable,
+        )
+        return await self.step(action)
+
+    async def run_counterfactual(
+        self,
+        control_variable: str,
+        delta: float,
+        target_variable: str,
+    ) -> StepResult[HypLabObservation]:
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.COUNTERFACTUAL,
+            control_variable=control_variable,
+            control_value=delta,
+            target_variable=target_variable,
+        )
+        return await self.step(action)
+
+    async def run_passive(
+        self, target_variable: str
+    ) -> StepResult[HypLabObservation]:
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.PASSIVE,
+            target_variable=target_variable,
+            control_variable=target_variable,
+        )
+        return await self.step(action)
+
+    async def submit_hypothesis(
+        self,
+        hypothesis_text: str,
+        hypothesis_equations: Optional[list[str]] = None,
+        confidence: float = 0.75,
+    ) -> StepResult[HypLabObservation]:
+        action = HypLabAction(
+            action_type=ActionType.SUBMIT,
+            hypothesis_text=hypothesis_text,
+            hypothesis_equations=hypothesis_equations,
+            confidence=max(0.0, min(1.0, confidence)),
+        )
+        return await self.step(action)

conftest.py

@@ -0,0 +1,5 @@
+"""pytest conftest -- ensure project root is on sys.path."""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))

hypothesis_lab.egg-info/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: hypothesis-lab
+Version: 0.1.0
+Summary: Scientific Hypothesis Lab -- OpenEnv RL environment for causal discovery under noise
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openenv-core[core]>=0.2.1
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: networkx>=3.3
+Provides-Extra: baseline
+Requires-Dist: openai>=1.30.0; extra == "baseline"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+---
+title: Scientific Hypothesis Lab
+emoji: 🔬
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Scientific Hypothesis Lab -- OpenEnv Environment
+
+An RL environment where agents discover hidden causal rules through systematic
+experimentation. Built for the [OpenEnv Hub](https://huggingface.co/openenv).
+
+## What it does
+
+Each episode, the agent is presented with a set of **abstract** variables
+(e.g. Alpha, Beta, Gamma or V1, V2, V3) from a randomised causal world.
+Variable names are deliberately opaque so agents cannot leverage pretrained
+real-world knowledge -- they must reason purely from experimental evidence.
+
+The hidden rules span **8 single-parent function types** (linear, threshold,
+inverse, quadratic, exponential, logarithmic, saturating, piecewise-linear),
+**multi-parent interaction rules** (additive, multiplicative, min, max), and
+optional **hidden confounders** that inject unexplainable correlated noise.
+
+The agent must:
+
+1. **Design experiments** -- probe variable relationships using interventions,
+   correlations, counterfactuals, or passive observations
+2. **Update beliefs** from noisy experimental results
+3. **Submit a hypothesis** -- a structured description of the discovered causal rules
+
+The environment rewards informative experiments, precise hypotheses, calibrated
+confidence, and efficient budget use.
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -e .
+
+# Run the server locally
+uvicorn server.app:app --port 8000
+
+# In another terminal, run the baseline agent
+export OPENAI_API_KEY=sk-...
+python baseline_inference.py
+```
+
+### Using the Client
+
+```python
+from hypothesis_lab import HypothesisLabEnv, HypLabAction, ActionType
+
+# Async usage
+async with HypothesisLabEnv(base_url="http://localhost:8000") as env:
+    result = await env.reset(noise_level="low", domain="system_alpha")
+    obs = result.observation
+
+    # Run an intervention
+    result = await env.run_intervention(
+        control_variable=obs.available_variables[0],
+        control_value=5.0,
+        target_variable=obs.available_variables[1],
+    )
+    print(result.observation.system_message)
+
+    # Submit hypothesis
+    result = await env.submit_hypothesis(
+        hypothesis_text="Beta = 2.1 * Alpha + 3.0",
+        confidence=0.85,
+    )
+    print(f"Score: {result.observation.total_episode_reward}")
+
+# Sync usage
+env = HypothesisLabEnv(base_url="http://localhost:8000").sync()
+with env:
+    result = env.reset(noise_level="low")
+    ...
+```
+
+## File Structure
+
+```
+hypothesis_lab/
+├── openenv.yaml              # OpenEnv manifest
+├── pyproject.toml             # Project metadata and dependencies
+├── requirements.txt           # Pip fallback dependencies
+├── README.md                  # This file
+├── models.py                  # Pydantic Action / Observation / State models
+├── client.py                  # Typed EnvClient for agents and trainers
+├── __init__.py                # Module exports
+├── baseline_inference.py      # Baseline agent using OpenAI API
+├── Dockerfile                 # For HF Spaces deployment
+├── server/
+│   ├── __init__.py
+│   ├── app.py                 # FastAPI server (create_app entry point)
+│   ├── hypothesis_lab_environment.py  # Core environment logic
+│   ├── causal_world.py        # Hidden causal graph generator
+│   └── rubric.py              # Multi-component reward engine
+├── tasks/
+│   ├── __init__.py
+│   ├── task_easy.py           # Easy: 2 vars, low noise, 12 budget
+│   ├── task_medium.py         # Medium: 3 vars, medium noise, 10 budget
+│   └── task_hard.py           # Hard: 4 vars, high noise, 8 budget
+└── tests/
+    ├── __init__.py
+    └── test_environment.py    # Unit + integration tests
+```
+
+## Action Space
+
+**HypLabAction** has two modes:
+
+| Field | Type | Description |
+|---|---|---|
+| `action_type` | `"experiment"` or `"submit"` | What the agent is doing |
+| `experiment_type` | `"intervention"`, `"correlation"`, `"counterfactual"`, `"passive"` | Experiment kind (experiment mode) |
+| `control_variable` | `str` | Variable to set/vary |
+| `control_value` | `float` | Value to set (intervention/counterfactual) |
+| `control_range` | `[min, max, n]` | Sweep range (correlation only) |
+| `target_variable` | `str` | Variable to observe |
+| `hypothesis_text` | `str` | Free-text hypothesis (submit mode) |
+| `hypothesis_equations` | `list[str]` | Structured equations (submit mode) |
+| `confidence` | `float [0,1]` | Self-reported confidence (submit mode) |
+
+## Observation Space
+
+**HypLabObservation** always contains:
+- `system_message`: Human-readable text the LLM reads
+- `available_variables`: Variable names in this episode
+- `budget_remaining`: Steps left
+- `done`: Whether episode ended
+- `reward`: Step reward
+
+On experiment steps: `result_value`, `noise_sigma`, `info_gain_reward`, `is_redundant`
+
+On submit: `accuracy_score`, `precision_bonus`, `calibration_score`, `efficiency_bonus`, `contradiction_penalty`, `total_episode_reward`, `ground_truth_revealed`
+
+## Causal Rule Types
+
+The hidden world can contain any of these relationship types:
+
+| Rule | Formula | Shape |
+|---|---|---|
+| Linear | `y = a*x + b` | Straight line |
+| Threshold | `y = high if x > t else low` | Step function |
+| Inverse | `y = a / x` | Hyperbola |
+| Quadratic | `y = a*x² + b*x + c` | Parabola |
+| Exponential | `y = a * exp(k*x)` | Growth/decay |
+| Logarithmic | `y = a * ln(x) + b` | Diminishing returns |
+| Saturating | `y = Vmax * x / (Km + x)` | Plateau (Michaelis-Menten) |
+| Piecewise-linear | Two slopes with a knot | Regime change |
+
+Additionally, some effects may depend on **two parents** via interaction rules
+(additive, multiplicative, min, max), and **hidden confounders** may inject
+correlated noise the agent cannot explain.
+
+## Reward Components
+
+| Signal | Value | What it trains |
+|---|---|---|
+| Information gain | +0.05 to +0.25/step | Designing informative experiments |
+| Redundant experiment | -0.10 | Not wasting budget |
+| Hypothesis accuracy | 0.0 to +1.0 | Getting the right answer |
+| Precision bonus | +0.10 | Quantitative, falsifiable claims |
+| Calibration score | 0.0 to +0.20 | Knowing what you don't know |
+| Efficiency bonus | +0.15 | Submitting early when confident |
+| Contradiction penalty | -0.50 | Contradicting the experimental setup |
+
+## Tasks (3 difficulty levels)
+
+| Task | Noise | Variables | Budget | Domain | Key Challenge |
+|---|---|---|---|---|---|
+| Easy | 0.05 | 2 | 12 | system_alpha | Single-edge discovery |
+| Medium | 0.20 | 3 | 10 | Random | Multi-edge, noisy signals |
+| Hard | 0.50 | 4 | 8 | Random | Complex graph + interactions, tight budget |
+
+Each task has a deterministic grader that returns a score in [0.0, 1.0].
+
+## Design Decisions
+
+**Abstract variable names:** Variables are named Alpha, Beta, Gamma (or V1, V2,
+V3, etc.) rather than Temperature, Pressure, Volume. This prevents LLM agents
+from using pretrained knowledge of real-world physics/economics/biology to
+shortcut the reasoning process. The agent must reason purely from experimental
+data.
+
+**Diverse rule types:** With 8 single-parent types plus interaction rules, the
+agent cannot memorize a small set of templates. Many rule types look similar in
+narrow ranges (e.g. exponential ≈ linear for small x), forcing the agent to
+design discriminating experiments.
+
+## Deploy to HF Spaces
+
+```bash
+openenv push --org your-org --token $HF_TOKEN
+```
+
+## Run Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Baseline Scores
+
+Baseline agent (gpt-4o-mini, temperature=0.3):
+
+| Task | Score |
+|---|---|
+| Easy | ~0.65 |
+| Medium | ~0.40 |
+| Hard | ~0.25 |
+| Average | ~0.43 |
+
+These scores are reproducible via `python baseline_inference.py` with the same model and seed.

hypothesis_lab.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+hypothesis_lab.egg-info/PKG-INFO
+hypothesis_lab.egg-info/SOURCES.txt
+hypothesis_lab.egg-info/dependency_links.txt
+hypothesis_lab.egg-info/requires.txt
+hypothesis_lab.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/causal_world.py
+server/hypothesis_lab_environment.py
+server/rubric.py
+tasks/__init__.py
+tasks/task_easy.py
+tasks/task_hard.py
+tasks/task_medium.py
+tests/__init__.py
+tests/test_environment.py

hypothesis_lab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hypothesis_lab.egg-info/requires.txt

@@ -0,0 +1,15 @@
+openenv-core[core]>=0.2.1
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+pydantic>=2.7.0
+numpy>=1.26.0
+networkx>=3.3
+
+[baseline]
+openai>=1.30.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23.0
+httpx>=0.27.0
+ruff>=0.4.0

hypothesis_lab.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+server
+tasks
+tests

models.py

@@ -0,0 +1,156 @@
+"""
+models.py -- Pydantic data models for the Scientific Hypothesis Lab.
+
+Follows the OpenEnv spec: Action, Observation, and State base types from
+openenv.core.env_server.types.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import Field
+
+try:
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    from pydantic import BaseModel
+
+    class Action(BaseModel):  # type: ignore[no-redef]
+        model_config = {"extra": "forbid"}
+        metadata: dict[str, Any] = Field(default_factory=dict)
+
+    class Observation(BaseModel):  # type: ignore[no-redef]
+        model_config = {"extra": "forbid"}
+        done: bool = False
+        reward: float | None = None
+        metadata: dict[str, Any] = Field(default_factory=dict)
+
+    class State(BaseModel):  # type: ignore[no-redef]
+        model_config = {"extra": "allow"}
+        episode_id: Optional[str] = None
+        step_count: int = 0
+
+
+class ExperimentType(str, Enum):
+    INTERVENTION = "intervention"
+    CORRELATION = "correlation"
+    COUNTERFACTUAL = "counterfactual"
+    PASSIVE = "passive"
+
+
+class ActionType(str, Enum):
+    EXPERIMENT = "experiment"
+    SUBMIT = "submit"
+
+
+class NoiseLevelTag(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class HypLabAction(Action):
+    """
+    Every message the agent sends to the environment.
+
+    Two forms:
+      - action_type=EXPERIMENT: run an experiment, burn one budget step
+      - action_type=SUBMIT: commit to a hypothesis, end the episode
+    """
+
+    action_type: ActionType = Field(
+        ...,
+        description="Whether the agent is running an experiment or submitting.",
+    )
+
+    experiment_type: Optional[ExperimentType] = Field(
+        None, description="Which kind of experiment to run."
+    )
+    target_variable: Optional[str] = Field(
+        None, description="The variable the agent wants to observe."
+    )
+    control_variable: Optional[str] = Field(
+        None, description="The variable the agent is setting or varying."
+    )
+    control_value: Optional[float] = Field(
+        None,
+        description=(
+            "INTERVENTION: exact value to set. "
+            "COUNTERFACTUAL: the proposed delta. "
+            "Unused for PASSIVE."
+        ),
+    )
+    control_range: Optional[list[float]] = Field(
+        None,
+        description="CORRELATION only: [min, max, n_points].",
+    )
+
+    hypothesis_text: Optional[str] = Field(
+        None,
+        description="Free-text statement of discovered rules.",
+    )
+    hypothesis_equations: Optional[list[str]] = Field(
+        None,
+        description="Structured list of equations, one per rule.",
+    )
+    confidence: Optional[float] = Field(
+        None, ge=0.0, le=1.0,
+        description="Agent's self-reported confidence [0,1].",
+    )
+
+
+class HypLabObservation(Observation):
+    """
+    Everything the environment hands back after reset() or step().
+    Inherits `done`, `reward`, `metadata` from Observation base.
+    """
+
+    system_message: str = Field(
+        ..., description="Human-readable description of what just happened."
+    )
+    available_variables: list[str] = Field(
+        default_factory=list,
+        description="Names of all variables in the current hidden world.",
+    )
+    budget_remaining: int = Field(
+        0, description="Steps left before forced termination."
+    )
+
+    experiment_type_run: Optional[ExperimentType] = None
+    control_variable_used: Optional[str] = None
+    control_value_used: Optional[Any] = None
+    target_variable_observed: Optional[str] = None
+    result_value: Optional[Any] = Field(
+        None,
+        description="Noisy observed value(s). Float or list of (x,y) pairs.",
+    )
+    noise_sigma: Optional[float] = None
+    is_redundant: bool = False
+    info_gain_reward: float = 0.0
+
+    accuracy_score: Optional[float] = Field(None, ge=0, le=1)
+    precision_bonus: Optional[float] = None
+    calibration_score: Optional[float] = None
+    efficiency_bonus: Optional[float] = None
+    contradiction_penalty: Optional[float] = None
+    total_episode_reward: Optional[float] = None
+    ground_truth_revealed: Optional[str] = None
+
+
+class HypLabState(State):
+    """
+    Snapshot of episode metadata. Never leaks the hidden causal graph.
+    Inherits `episode_id`, `step_count` from State base.
+    """
+
+    budget_total: int = 0
+    budget_remaining: int = 0
+    noise_level: NoiseLevelTag = NoiseLevelTag.MEDIUM
+    noise_sigma: float = 0.20
+    domain: str = "unknown"
+    n_variables: int = 0
+    experiment_history: list[dict] = Field(default_factory=list)
+    cumulative_info_gain: float = 0.0
+    redundant_experiment_count: int = 0

openenv.yaml

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

pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hypothesis-lab"
+version = "0.1.0"
+description = "Scientific Hypothesis Lab -- OpenEnv RL environment for causal discovery under noise"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+
+dependencies = [
+    "openenv-core[core]>=0.2.1",
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.29.0",
+    "pydantic>=2.7.0",
+    "numpy>=1.26.0",
+    "networkx>=3.3",
+]
+
+[project.optional-dependencies]
+baseline = [
+    "openai>=1.30.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["server*", "tasks*", "tests*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

requirements.txt

@@ -0,0 +1,9 @@
+openenv-core[core]>=0.2.1
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+pydantic>=2.7.0
+numpy>=1.26.0
+networkx>=3.3
+openai>=1.30.0
+pytest>=8.0
+pytest-asyncio>=0.23.0

server/__init__.py

@@ -0,0 +1 @@
+"""Hypothesis Lab server components."""

server/app.py

@@ -0,0 +1,131 @@
+"""
+server/app.py -- FastAPI application for the Hypothesis Lab Environment.
+
+Uses openenv's create_app() to produce the standard HTTP + WebSocket server
+with /reset, /step, /state, /health, /schema, and /ws endpoints.
+
+Additional endpoints for hackathon submission:
+  /tasks    -- list all tasks and action schema
+  /grader   -- score an episode result for a given task
+  /baseline -- trigger baseline inference and return scores
+"""
+
+import traceback
+from typing import Any, Dict, Optional
+
+from fastapi import Body
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except ImportError:
+    raise ImportError(
+        "openenv-core is required. Install with: pip install openenv-core"
+    )
+
+try:
+    from ..models import HypLabAction, HypLabObservation
+    from .hypothesis_lab_environment import HypothesisLabEnvironment
+except ImportError:
+    from models import HypLabAction, HypLabObservation
+    from server.hypothesis_lab_environment import HypothesisLabEnvironment
+
+
+app = create_app(
+    HypothesisLabEnvironment,
+    HypLabAction,
+    HypLabObservation,
+    env_name="hypothesis_lab",
+    max_concurrent_envs=200,
+)
+
+
+# ---------------------------------------------------------------------------
+# /tasks -- list available tasks and the action schema
+# ---------------------------------------------------------------------------
+@app.get("/tasks", tags=["Hackathon"])
+def list_tasks() -> Dict[str, Any]:
+    try:
+        from tasks import ALL_TASKS
+    except ImportError:
+        from tasks import ALL_TASKS  # noqa: F811
+
+    action_schema = HypLabAction.model_json_schema()
+
+    return {
+        "tasks": [
+            {
+                "id": t["id"],
+                "name": t["name"],
+                "description": t["description"],
+                "difficulty": t["difficulty"],
+                "reset_kwargs": t["reset_kwargs"],
+            }
+            for t in ALL_TASKS
+        ],
+        "action_schema": action_schema,
+    }
+
+
+# ---------------------------------------------------------------------------
+# /grader -- score an episode result for a specific task
+# ---------------------------------------------------------------------------
+@app.post("/grader", tags=["Hackathon"])
+def grade_episode(
+    body: Dict[str, Any] = Body(
+        ...,
+        examples=[{
+            "task_id": "easy",
+            "episode_result": {
+                "accuracy_score": 0.7,
+                "precision_bonus": 0.1,
+                "calibration_score": 0.15,
+                "efficiency_bonus": 0.1,
+                "contradiction_penalty": 0.0,
+            },
+        }],
+    ),
+) -> Dict[str, Any]:
+    from tasks.task_easy import grade_easy
+    from tasks.task_medium import grade_medium
+    from tasks.task_hard import grade_hard
+
+    graders = {"easy": grade_easy, "medium": grade_medium, "hard": grade_hard}
+
+    task_id = body.get("task_id", "")
+    episode_result = body.get("episode_result", {})
+
+    if task_id not in graders:
+        return {"error": f"Unknown task_id '{task_id}'. Choose from: {list(graders.keys())}"}
+
+    score = graders[task_id](episode_result)
+    return {"task_id": task_id, "score": score}
+
+
+# ---------------------------------------------------------------------------
+# /baseline -- run the baseline agent on all tasks and return scores
+# ---------------------------------------------------------------------------
+@app.post("/baseline", tags=["Hackathon"])
+def run_baseline(
+    body: Optional[Dict[str, Any]] = Body(default=None),
+) -> Dict[str, Any]:
+    try:
+        from baseline_inference import run_all_tasks
+    except ImportError:
+        return {"error": "baseline_inference module not found or missing dependencies (openai)."}
+    except Exception as e:
+        return {"error": f"Failed to import baseline: {e}"}
+
+    try:
+        results = run_all_tasks()
+        return {"status": "ok", "results": results}
+    except Exception as e:
+        return {"error": str(e), "traceback": traceback.format_exc()}
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/causal_world.py

@@ -0,0 +1,474 @@
+"""
+server/causal_world.py -- The hidden causal world.
+
+Every episode a new CausalGraph is generated. The agent never sees this
+object -- it can only probe it via experiments.
+
+Design:
+  - Variables are nodes; directed edges carry one of 8+ rule types.
+  - Multi-parent interaction rules make some effects depend on >1 cause.
+  - Hidden confounders can inject correlated noise across variables.
+  - Gaussian noise is added to every observation.
+  - The graph is a DAG (no cycles) so causality is well-defined.
+  - Domains: system_alpha | system_beta | system_gamma | system_delta
+    Each domain provides a different narrative prompt but uses abstract
+    variable names (Greek letters, V1/V2/V3...) to prevent LLM agents
+    from leveraging pretrained real-world knowledge instead of reasoning
+    from experimental evidence.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import numpy as np
+import networkx as nx
+
+
+ABSTRACT_VAR_POOLS: list[list[str]] = [
+    ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"],
+    ["Zeta", "Eta", "Theta", "Iota", "Kappa"],
+    ["V1", "V2", "V3", "V4", "V5"],
+    ["Rho", "Sigma", "Tau", "Upsilon", "Phi"],
+    ["Mu", "Nu", "Xi", "Omicron", "Pi"],
+    ["Quant_A", "Quant_B", "Quant_C", "Quant_D", "Quant_E"],
+]
+
+DOMAIN_LABELS: dict[str, dict] = {
+    "system_alpha": {
+        "context": "You are studying an unknown dynamical system. Variables have hidden causal relationships you must discover through experiments.",
+        "unit": "units",
+    },
+    "system_beta": {
+        "context": "You are investigating a black-box system with interacting quantities. Design experiments to uncover the governing equations.",
+        "unit": "units",
+    },
+    "system_gamma": {
+        "context": "You are analysing an opaque process with measurable outputs. Run controlled experiments to determine how variables influence each other.",
+        "unit": "units",
+    },
+    "system_delta": {
+        "context": "You are probing a simulated environment with coupled variables. The underlying rules are unknown -- discover them.",
+        "unit": "units",
+    },
+}
+
+DOMAINS = list(DOMAIN_LABELS.keys())
+
+RULE_TYPES = [
+    "linear",
+    "threshold",
+    "inverse",
+    "quadratic",
+    "exponential",
+    "logarithmic",
+    "saturating",
+    "piecewise_linear",
+]
+
+
+@dataclass
+class CausalRule:
+    """A single edge rule in the causal graph."""
+
+    cause: str
+    effect: str
+    rule_type: str
+    params: dict[str, float] = field(default_factory=dict)
+    description: str = ""
+
+    def evaluate(self, x: float) -> float:
+        if self.rule_type == "linear":
+            a = self.params.get("a", 1.0)
+            b = self.params.get("b", 0.0)
+            return a * x + b
+
+        elif self.rule_type == "threshold":
+            threshold = self.params.get("threshold", 5.0)
+            high = self.params.get("high", 10.0)
+            low = self.params.get("low", 2.0)
+            return high if x > threshold else low
+
+        elif self.rule_type == "inverse":
+            a = self.params.get("a", 10.0)
+            if abs(x) < 1e-9:
+                return float("nan")
+            return a / x
+
+        elif self.rule_type == "quadratic":
+            a = self.params.get("a", 0.5)
+            b = self.params.get("b", 0.0)
+            c = self.params.get("c", 0.0)
+            return a * x * x + b * x + c
+
+        elif self.rule_type == "exponential":
+            a = self.params.get("a", 1.0)
+            k = self.params.get("k", 0.3)
+            x_clamped = max(-20.0, min(20.0, k * x))
+            return a * math.exp(x_clamped)
+
+        elif self.rule_type == "logarithmic":
+            a = self.params.get("a", 3.0)
+            b = self.params.get("b", 0.0)
+            if x <= 0:
+                return float("nan")
+            return a * math.log(x) + b
+
+        elif self.rule_type == "saturating":
+            v_max = self.params.get("v_max", 10.0)
+            k_m = self.params.get("k_m", 3.0)
+            if x < 0:
+                return 0.0
+            return v_max * x / (k_m + x)
+
+        elif self.rule_type == "piecewise_linear":
+            knot = self.params.get("knot", 5.0)
+            a1 = self.params.get("a1", 1.0)
+            a2 = self.params.get("a2", -0.5)
+            b = self.params.get("b", 0.0)
+            if x <= knot:
+                return a1 * x + b
+            else:
+                y_knot = a1 * knot + b
+                return y_knot + a2 * (x - knot)
+
+        return 0.0
+
+
+@dataclass
+class InteractionRule:
+    """
+    A multi-parent rule: effect = f(cause1, cause2).
+    These cannot be discovered by varying one variable at a time --
+    the agent must realise two parents jointly determine the effect.
+    """
+
+    cause1: str
+    cause2: str
+    effect: str
+    interaction_type: str  # "additive", "multiplicative", "min", "max"
+    params: dict[str, float] = field(default_factory=dict)
+    description: str = ""
+
+    def evaluate(self, x1: float, x2: float) -> float:
+        if self.interaction_type == "additive":
+            a = self.params.get("a", 1.0)
+            b = self.params.get("b", 1.0)
+            c = self.params.get("c", 0.0)
+            return a * x1 + b * x2 + c
+        elif self.interaction_type == "multiplicative":
+            a = self.params.get("a", 0.5)
+            return a * x1 * x2
+        elif self.interaction_type == "min":
+            return min(x1, x2)
+        elif self.interaction_type == "max":
+            return max(x1, x2)
+        return 0.0
+
+
+@dataclass
+class CausalWorld:
+    """
+    The hidden world the agent must discover.
+    Contains variables, single-parent rules, multi-parent interaction rules,
+    and optional hidden confounders.
+    """
+
+    domain: str
+    variables: list[str]
+    units: dict[str, str]
+    rules: list[CausalRule]
+    default_values: dict[str, float]
+    rng: np.random.Generator
+    interactions: list[InteractionRule] = field(default_factory=list)
+    confounder_sigma: float = 0.0
+
+    def _compute_value(
+        self, target: str, interventions: Optional[dict[str, float]] = None
+    ) -> float:
+        """Compute the true (noiseless) value of target given interventions."""
+        vals = dict(self.default_values)
+        if interventions:
+            vals.update(interventions)
+
+        for rule in self.rules:
+            if rule.effect in (interventions or {}):
+                continue
+            if rule.cause in vals:
+                result = rule.evaluate(vals[rule.cause])
+                if not math.isnan(result):
+                    vals[rule.effect] = result
+
+        for inter in self.interactions:
+            if inter.effect in (interventions or {}):
+                continue
+            if inter.cause1 in vals and inter.cause2 in vals:
+                result = inter.evaluate(vals[inter.cause1], vals[inter.cause2])
+                vals[inter.effect] = result
+
+        return vals.get(target, 0.0)
+
+    def _confounder_noise(self) -> float:
+        """Hidden confounder adds correlated noise the agent can't explain."""
+        if self.confounder_sigma <= 0:
+            return 0.0
+        return float(self.rng.normal(0, self.confounder_sigma))
+
+    def query_intervention(
+        self, cause: str, value: float, effect: str, sigma: float
+    ) -> float:
+        true_val = self._compute_value(effect, {cause: value})
+        return true_val + self.rng.normal(0, sigma) + self._confounder_noise()
+
+    def query_correlation(
+        self,
+        cause: str,
+        control_range: list[float],
+        effect: str,
+        sigma: float,
+    ) -> list[tuple[float, float]]:
+        lo = control_range[0] if len(control_range) > 0 else 1.0
+        hi = control_range[1] if len(control_range) > 1 else 10.0
+        n = int(control_range[2]) if len(control_range) > 2 else 5
+        xs = np.linspace(lo, hi, n)
+        conf = self._confounder_noise()
+        pairs = []
+        for x in xs:
+            y = self._compute_value(effect, {cause: float(x)})
+            y_noisy = y + self.rng.normal(0, sigma) + conf
+            pairs.append((round(float(x), 4), round(float(y_noisy), 4)))
+        return pairs
+
+    def query_counterfactual(
+        self, cause: str, delta: float, effect: str, sigma: float
+    ) -> dict[str, Any]:
+        baseline_x = self.default_values.get(cause, 5.0)
+        cf_x = baseline_x + delta
+        baseline_y = self._compute_value(effect, {cause: baseline_x})
+        cf_y = self._compute_value(effect, {cause: cf_x})
+        conf = self._confounder_noise()
+        baseline_y_noisy = baseline_y + self.rng.normal(0, sigma) + conf
+        cf_y_noisy = cf_y + self.rng.normal(0, sigma) + conf
+        direction = "increases" if cf_y > baseline_y else "decreases" if cf_y < baseline_y else "unchanged"
+        return {
+            "baseline_x": round(baseline_x, 4),
+            "baseline_y_noisy": round(float(baseline_y_noisy), 4),
+            "counterfactual_x": round(cf_x, 4),
+            "counterfactual_y_noisy": round(float(cf_y_noisy), 4),
+            "direction": direction,
+        }
+
+    def query_passive(self, target: str, sigma: float) -> float:
+        true_val = self._compute_value(target)
+        return true_val + self.rng.normal(0, sigma) + self._confounder_noise()
+
+    def ground_truth_summary(self) -> str:
+        lines = [f"Domain: {self.domain}"]
+        effects_covered: set[str] = set()
+        for rule in self.rules:
+            lines.append(f"  {rule.description}")
+            effects_covered.add(rule.effect)
+        for inter in self.interactions:
+            lines.append(f"  {inter.description}")
+            effects_covered.add(inter.effect)
+        for v in self.variables:
+            if v not in effects_covered:
+                lines.append(f"  {v} = {self.default_values.get(v, '?')} (root)")
+        if self.confounder_sigma > 0:
+            lines.append(f"  [hidden confounder with sigma={self.confounder_sigma:.2f}]")
+        return "\n".join(lines)
+
+
+def _random_rule(
+    cause: str, effect: str, rng: random.Random
+) -> CausalRule:
+    """Generate a random causal rule for one edge."""
+    rule_type = rng.choices(
+        RULE_TYPES,
+        weights=[0.30, 0.15, 0.10, 0.12, 0.08, 0.08, 0.10, 0.07],
+    )[0]
+
+    if rule_type == "linear":
+        a = round(rng.uniform(0.5, 3.5) * rng.choice([-1, 1]), 2)
+        b = round(rng.uniform(-5.0, 5.0), 2)
+        sign = "+" if b >= 0 else "-"
+        desc = f"{effect} = {a} * {cause} {sign} {abs(b)}"
+        return CausalRule(cause, effect, "linear", {"a": a, "b": b}, desc)
+
+    elif rule_type == "threshold":
+        threshold = round(rng.uniform(3.0, 8.0), 2)
+        high = round(rng.uniform(6.0, 12.0), 2)
+        low = round(rng.uniform(0.5, 4.0), 2)
+        desc = f"{effect} = {high} if {cause} > {threshold} else {low}"
+        return CausalRule(
+            cause, effect, "threshold",
+            {"threshold": threshold, "high": high, "low": low}, desc,
+        )
+
+    elif rule_type == "inverse":
+        a = round(rng.uniform(5.0, 30.0), 2)
+        desc = f"{effect} = {a} / {cause}"
+        return CausalRule(cause, effect, "inverse", {"a": a}, desc)
+
+    elif rule_type == "quadratic":
+        a = round(rng.uniform(0.1, 1.0) * rng.choice([-1, 1]), 2)
+        b = round(rng.uniform(-2.0, 2.0), 2)
+        c = round(rng.uniform(-3.0, 3.0), 2)
+        desc = f"{effect} = {a}*{cause}^2 + {b}*{cause} + {c}"
+        return CausalRule(cause, effect, "quadratic", {"a": a, "b": b, "c": c}, desc)
+
+    elif rule_type == "exponential":
+        a = round(rng.uniform(0.5, 3.0), 2)
+        k = round(rng.uniform(0.1, 0.5) * rng.choice([-1, 1]), 2)
+        desc = f"{effect} = {a} * exp({k} * {cause})"
+        return CausalRule(cause, effect, "exponential", {"a": a, "k": k}, desc)
+
+    elif rule_type == "logarithmic":
+        a = round(rng.uniform(1.0, 5.0) * rng.choice([-1, 1]), 2)
+        b = round(rng.uniform(-3.0, 3.0), 2)
+        sign = "+" if b >= 0 else "-"
+        desc = f"{effect} = {a} * ln({cause}) {sign} {abs(b)}"
+        return CausalRule(cause, effect, "logarithmic", {"a": a, "b": b}, desc)
+
+    elif rule_type == "saturating":
+        v_max = round(rng.uniform(5.0, 15.0), 2)
+        k_m = round(rng.uniform(1.0, 6.0), 2)
+        desc = f"{effect} = {v_max} * {cause} / ({k_m} + {cause})"
+        return CausalRule(cause, effect, "saturating", {"v_max": v_max, "k_m": k_m}, desc)
+
+    else:  # piecewise_linear
+        knot = round(rng.uniform(3.0, 7.0), 2)
+        a1 = round(rng.uniform(0.5, 3.0) * rng.choice([-1, 1]), 2)
+        a2 = round(rng.uniform(0.5, 3.0) * rng.choice([-1, 1]), 2)
+        b = round(rng.uniform(-3.0, 3.0), 2)
+        desc = (
+            f"{effect} = {a1}*{cause} + {b} (if {cause} <= {knot}), "
+            f"then slope changes to {a2}"
+        )
+        return CausalRule(
+            cause, effect, "piecewise_linear",
+            {"knot": knot, "a1": a1, "a2": a2, "b": b}, desc,
+        )
+
+
+def _random_interaction(
+    cause1: str, cause2: str, effect: str, rng: random.Random
+) -> InteractionRule:
+    """Generate a random interaction rule where effect depends on two parents."""
+    itype = rng.choices(
+        ["additive", "multiplicative", "min", "max"],
+        weights=[0.35, 0.35, 0.15, 0.15],
+    )[0]
+
+    if itype == "additive":
+        a = round(rng.uniform(0.5, 2.0) * rng.choice([-1, 1]), 2)
+        b = round(rng.uniform(0.5, 2.0) * rng.choice([-1, 1]), 2)
+        c = round(rng.uniform(-2.0, 2.0), 2)
+        desc = f"{effect} = {a}*{cause1} + {b}*{cause2} + {c}"
+        return InteractionRule(cause1, cause2, effect, itype, {"a": a, "b": b, "c": c}, desc)
+    elif itype == "multiplicative":
+        a = round(rng.uniform(0.1, 0.8), 2)
+        desc = f"{effect} = {a} * {cause1} * {cause2}"
+        return InteractionRule(cause1, cause2, effect, itype, {"a": a}, desc)
+    elif itype == "min":
+        desc = f"{effect} = min({cause1}, {cause2})"
+        return InteractionRule(cause1, cause2, effect, itype, {}, desc)
+    else:
+        desc = f"{effect} = max({cause1}, {cause2})"
+        return InteractionRule(cause1, cause2, effect, itype, {}, desc)
+
+
+def generate_world(
+    n_variables: int = 3,
+    domain: Optional[str] = None,
+    seed: Optional[int] = None,
+) -> CausalWorld:
+    """
+    Generate a fresh hidden causal world.
+
+    The world may contain:
+      - Single-parent rules (8 types: linear, threshold, inverse, quadratic,
+        exponential, logarithmic, saturating, piecewise_linear)
+      - Multi-parent interaction rules (additive, multiplicative, min, max)
+      - Hidden confounders that add unexplainable correlated noise
+
+    Args:
+        n_variables: How many variables (2-5).
+        domain: One of "system_alpha", "system_beta", "system_gamma", "system_delta", or None for random.
+        seed: Random seed for reproducibility.
+
+    Returns:
+        A CausalWorld instance ready for agent probing.
+    """
+    py_rng = random.Random(seed)
+    np_rng = np.random.default_rng(seed)
+
+    if domain is None or domain not in DOMAIN_LABELS:
+        domain = py_rng.choice(DOMAINS)
+
+    labels = DOMAIN_LABELS[domain]
+    var_pool = py_rng.choice(ABSTRACT_VAR_POOLS)
+    n = min(n_variables, len(var_pool))
+    chosen_vars = py_rng.sample(var_pool, n)
+    unit_label = labels.get("unit", "units")
+    units = {v: unit_label for v in chosen_vars}
+
+    rules: list[CausalRule] = []
+    for i in range(len(chosen_vars) - 1):
+        parent = chosen_vars[i]
+        child = chosen_vars[i + 1]
+        rules.append(_random_rule(parent, child, py_rng))
+
+    for i, parent in enumerate(chosen_vars):
+        for j, child in enumerate(chosen_vars):
+            if j <= i + 1:
+                continue
+            if py_rng.random() < 0.30:
+                rules.append(_random_rule(parent, child, py_rng))
+
+    interactions: list[InteractionRule] = []
+    if n >= 3 and py_rng.random() < 0.40:
+        roots_and_mid = [v for v in chosen_vars[:n - 1]]
+        if len(roots_and_mid) >= 2:
+            c1, c2 = py_rng.sample(roots_and_mid, 2)
+            target = chosen_vars[-1]
+            interaction = _random_interaction(c1, c2, target, py_rng)
+            interactions.append(interaction)
+            rules = [r for r in rules if r.effect != target]
+
+    confounder_sigma = 0.0
+    if n >= 3 and py_rng.random() < 0.30:
+        confounder_sigma = round(py_rng.uniform(0.05, 0.25), 3)
+
+    all_effects = {r.effect for r in rules} | {i.effect for i in interactions}
+    default_values: dict[str, float] = {}
+    for v in chosen_vars:
+        is_root = v not in all_effects
+        default_values[v] = round(py_rng.uniform(2.0, 10.0), 2) if is_root else 0.0
+
+    display_order = list(chosen_vars)
+    py_rng.shuffle(display_order)
+
+    world = CausalWorld(
+        domain=domain,
+        variables=display_order,
+        units=units,
+        rules=rules,
+        default_values=default_values,
+        rng=np_rng,
+        interactions=interactions,
+        confounder_sigma=confounder_sigma,
+    )
+
+    for v in chosen_vars:
+        if default_values[v] == 0.0:
+            computed = world._compute_value(v)
+            if not math.isnan(computed):
+                default_values[v] = round(computed, 4)
+            else:
+                default_values[v] = round(py_rng.uniform(2.0, 10.0), 2)
+
+    return world

server/hypothesis_lab_environment.py

@@ -0,0 +1,363 @@
+"""
+server/hypothesis_lab_environment.py -- OpenEnv Environment implementation.
+
+Implements the OpenEnv server-side Environment interface:
+  reset()  -> initial observation
+  step()   -> execute one agent action, return observation
+  state    -> return episode metadata (no hidden info leaked)
+
+This class is what the FastAPI server wraps via create_app().
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any, Optional
+from uuid import uuid4
+
+try:
+    from openenv.core.env_server.interfaces import Environment
+except ImportError:
+    from abc import ABC, abstractmethod
+
+    class Environment(ABC):  # type: ignore[no-redef]
+        def __init__(self, **kwargs: Any):
+            pass
+
+        @abstractmethod
+        def reset(self, **kwargs: Any) -> Any:
+            pass
+
+        @abstractmethod
+        def step(self, action: Any, **kwargs: Any) -> Any:
+            pass
+
+        @property
+        @abstractmethod
+        def state(self) -> Any:
+            pass
+
+try:
+    from models import (
+        ActionType,
+        ExperimentType,
+        HypLabAction,
+        HypLabObservation,
+        HypLabState,
+        NoiseLevelTag,
+    )
+except ImportError:
+    from ..models import (
+        ActionType,
+        ExperimentType,
+        HypLabAction,
+        HypLabObservation,
+        HypLabState,
+        NoiseLevelTag,
+    )
+
+from .causal_world import CausalWorld, generate_world
+from .rubric import InfoGainTracker, RubricResult, score_hypothesis
+
+
+NOISE_SCHEDULE: dict[NoiseLevelTag, float] = {
+    NoiseLevelTag.LOW: 0.05,
+    NoiseLevelTag.MEDIUM: 0.20,
+    NoiseLevelTag.HIGH: 0.50,
+}
+
+BUDGET_SCHEDULE: dict[NoiseLevelTag, int] = {
+    NoiseLevelTag.LOW: 12,
+    NoiseLevelTag.MEDIUM: 10,
+    NoiseLevelTag.HIGH: 8,
+}
+
+N_VARIABLES_SCHEDULE: dict[NoiseLevelTag, int] = {
+    NoiseLevelTag.LOW: 2,
+    NoiseLevelTag.MEDIUM: 3,
+    NoiseLevelTag.HIGH: 4,
+}
+
+DOMAINS = ["system_alpha", "system_beta", "system_gamma", "system_delta"]
+
+
+class HypothesisLabEnvironment(Environment):
+    """
+    Scientific Hypothesis Lab -- OpenEnv Environment.
+
+    Each episode presents the agent with a new randomised causal world.
+    The agent must discover the hidden rules through experiments and
+    submit a hypothesis before running out of budget.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        self._episode_id: str = ""
+        self._world: Optional[CausalWorld] = None
+        self._tracker: Optional[InfoGainTracker] = None
+        self._step_count: int = 0
+        self._budget_total: int = 10
+        self._budget_remaining: int = 0
+        self._done: bool = True
+        self._history: list[dict] = []
+        self._cumulative_reward: float = 0.0
+        self._noise_level: NoiseLevelTag = NoiseLevelTag.MEDIUM
+        self._sigma: float = 0.20
+        self._domain: str = "unknown"
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> HypLabObservation:
+        noise_level_str = kwargs.get("noise_level", "medium")
+        noise_level = NoiseLevelTag(noise_level_str) if isinstance(noise_level_str, str) else noise_level_str
+        domain = kwargs.get("domain", None) or random.choice(DOMAINS)
+
+        sigma = NOISE_SCHEDULE[noise_level]
+        budget = BUDGET_SCHEDULE[noise_level]
+        n_vars = N_VARIABLES_SCHEDULE[noise_level]
+
+        self._world = generate_world(n_variables=n_vars, domain=domain, seed=seed)
+        self._tracker = InfoGainTracker()
+        self._episode_id = episode_id or str(uuid4())
+        self._step_count = 0
+        self._budget_total = budget
+        self._budget_remaining = budget
+        self._done = False
+        self._history = []
+        self._cumulative_reward = 0.0
+        self._noise_level = noise_level
+        self._sigma = sigma
+        self._domain = domain
+
+        system_msg = (
+            f"New episode started. Domain: {domain.upper()}.\n"
+            f"You have {n_vars} unknown variables: {', '.join(self._world.variables)}.\n"
+            f"Budget: {budget} experiment steps.\n"
+            f"Run experiments to discover the hidden causal rules, then SUBMIT your hypothesis.\n"
+            f"Noise level: {noise_level.value}.\n\n"
+            f"Available experiment types:\n"
+            f"  INTERVENTION  -- set one variable to a value, observe another\n"
+            f"  CORRELATION   -- sweep one variable across a range, observe another\n"
+            f"  COUNTERFACTUAL-- ask 'what if variable changes by delta?'\n"
+            f"  PASSIVE       -- observe one variable in its default state\n"
+            f"  SUBMIT        -- submit your hypothesis (ends episode)"
+        )
+
+        return HypLabObservation(
+            system_message=system_msg,
+            available_variables=self._world.variables,
+            budget_remaining=self._budget_remaining,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(
+        self,
+        action: HypLabAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> HypLabObservation:
+        if self._world is None:
+            return HypLabObservation(
+                system_message="Error: No active episode. Call reset() before step().",
+                done=True,
+                reward=-1.0,
+            )
+        if self._done:
+            return HypLabObservation(
+                system_message="Error: Episode is already done. Call reset() to start a new episode.",
+                available_variables=self._world.variables,
+                budget_remaining=self._budget_remaining,
+                done=True,
+                reward=0.0,
+            )
+
+        self._step_count += 1
+
+        if action.action_type == ActionType.EXPERIMENT:
+            return self._handle_experiment(action)
+        elif action.action_type == ActionType.SUBMIT:
+            return self._handle_submit(action)
+        else:
+            return self._error_obs(
+                f"Unknown action_type: {action.action_type}. Use 'experiment' or 'submit'.",
+                deduct_budget=True,
+            )
+
+    @property
+    def state(self) -> HypLabState:
+        return HypLabState(
+            episode_id=self._episode_id,
+            step_count=self._step_count,
+            budget_total=self._budget_total,
+            budget_remaining=self._budget_remaining,
+            noise_level=self._noise_level,
+            noise_sigma=self._sigma,
+            domain=self._domain,
+            n_variables=len(self._world.variables) if self._world else 0,
+            experiment_history=self._history,
+            cumulative_info_gain=self._tracker.cumulative_gain if self._tracker else 0.0,
+            redundant_experiment_count=self._tracker.redundant_count if self._tracker else 0,
+        )
+
+    def _handle_experiment(self, action: HypLabAction) -> HypLabObservation:
+        world = self._world
+        sigma = self._sigma
+        tracker = self._tracker
+
+        cause = action.control_variable or ""
+        effect = action.target_variable or ""
+        all_vars = world.variables
+
+        if cause not in all_vars:
+            return self._error_obs(
+                f"Unknown control variable '{cause}'. Available: {all_vars}",
+                deduct_budget=True,
+            )
+        if effect not in all_vars:
+            return self._error_obs(
+                f"Unknown target variable '{effect}'. Available: {all_vars}",
+                deduct_budget=True,
+            )
+
+        exp_type = action.experiment_type or ExperimentType.INTERVENTION
+        result_value = None
+
+        if exp_type == ExperimentType.INTERVENTION:
+            val = action.control_value if action.control_value is not None else 5.0
+            result_value = world.query_intervention(cause, val, effect, sigma)
+            result_str = f"{effect} = {result_value:.4f}  (sigma={sigma}, set {cause}={val})"
+
+        elif exp_type == ExperimentType.CORRELATION:
+            cr = action.control_range or [1.0, 10.0, 5.0]
+            pairs = world.query_correlation(cause, cr, effect, sigma)
+            result_value = pairs
+            result_str = (
+                f"Correlation sweep {cause} -> {effect}:\n"
+                + "\n".join(f"  {cause}={x:.2f} -> {effect}={y:.4f}" for x, y in pairs)
+            )
+
+        elif exp_type == ExperimentType.COUNTERFACTUAL:
+            delta = action.control_value or 1.0
+            cf = world.query_counterfactual(cause, delta, effect, sigma)
+            result_value = cf
+            result_str = (
+                f"Counterfactual: if {cause} changes by {delta:+.2f}:\n"
+                f"  Baseline: {cause}={cf['baseline_x']:.2f} -> {effect}={cf['baseline_y_noisy']:.4f}\n"
+                f"  After:    {cause}={cf['counterfactual_x']:.2f} -> {effect}={cf['counterfactual_y_noisy']:.4f}\n"
+                f"  Direction: {effect} {cf['direction']}"
+            )
+
+        elif exp_type == ExperimentType.PASSIVE:
+            result_value = world.query_passive(effect, sigma)
+            result_str = f"Passive observation: {effect} = {result_value:.4f}  (sigma={sigma})"
+
+        else:
+            return self._error_obs(f"Unknown experiment type: {exp_type}")
+
+        info_gain, is_redundant = tracker.record_and_score(
+            cause, effect, exp_type.value, result_value
+        )
+
+        self._budget_remaining -= 1
+        budget_done = self._budget_remaining <= 0
+        self._cumulative_reward += info_gain
+
+        self._history.append({
+            "step": self._step_count,
+            "exp_type": exp_type.value,
+            "cause": cause,
+            "effect": effect,
+            "reward": round(info_gain, 4),
+            "redundant": is_redundant,
+        })
+
+        msg = f"[Step {self._step_count}] {result_str}"
+        if is_redundant:
+            msg += "\nRedundant experiment -- reward penalty applied."
+        if budget_done:
+            msg += "\nBudget exhausted. Submit your hypothesis now."
+            self._done = True
+
+        return HypLabObservation(
+            system_message=msg,
+            available_variables=world.variables,
+            budget_remaining=self._budget_remaining,
+            experiment_type_run=exp_type,
+            control_variable_used=cause,
+            control_value_used=(
+                action.control_value
+                if exp_type != ExperimentType.CORRELATION
+                else action.control_range
+            ),
+            target_variable_observed=effect,
+            result_value=result_value,
+            noise_sigma=sigma,
+            is_redundant=is_redundant,
+            info_gain_reward=round(info_gain, 4),
+            reward=info_gain,
+            done=self._done,
+        )
+
+    def _handle_submit(self, action: HypLabAction) -> HypLabObservation:
+        self._done = True
+
+        rubric: RubricResult = score_hypothesis(
+            hypothesis_text=action.hypothesis_text or "",
+            hypothesis_equations=action.hypothesis_equations,
+            confidence=action.confidence,
+            world=self._world,
+            budget_remaining=self._budget_remaining,
+            budget_total=self._budget_total,
+        )
+
+        total_reward = rubric.total
+        self._cumulative_reward += total_reward
+
+        msg = (
+            f"[Episode End -- Step {self._step_count}]\n"
+            f"Hypothesis received. Evaluating against ground truth...\n\n"
+            f"RUBRIC BREAKDOWN:\n"
+            f"  Accuracy score:         {rubric.accuracy_score:+.4f}\n"
+            f"  Precision bonus:        {rubric.precision_bonus:+.4f}\n"
+            f"  Calibration score:      {rubric.calibration_score:+.4f}\n"
+            f"  Efficiency bonus:       {rubric.efficiency_bonus:+.4f}\n"
+            f"  Contradiction penalty:  {rubric.contradiction_penalty:+.4f}\n"
+            f"  ────────────────────────────\n"
+            f"  TOTAL EPISODE REWARD:   {rubric.total:+.4f}\n\n"
+            f"FEEDBACK: {rubric.feedback}\n\n"
+            f"GROUND TRUTH:\n{rubric.ground_truth}"
+        )
+
+        return HypLabObservation(
+            system_message=msg,
+            available_variables=self._world.variables,
+            budget_remaining=self._budget_remaining,
+            accuracy_score=rubric.accuracy_score,
+            precision_bonus=rubric.precision_bonus,
+            calibration_score=rubric.calibration_score,
+            efficiency_bonus=rubric.efficiency_bonus,
+            contradiction_penalty=rubric.contradiction_penalty,
+            total_episode_reward=rubric.total,
+            ground_truth_revealed=rubric.ground_truth,
+            reward=total_reward,
+            done=True,
+        )
+
+    def _error_obs(
+        self, msg: str, deduct_budget: bool = False
+    ) -> HypLabObservation:
+        if deduct_budget:
+            self._budget_remaining -= 1
+        return HypLabObservation(
+            system_message=f"Error: {msg}",
+            available_variables=self._world.variables if self._world else [],
+            budget_remaining=self._budget_remaining,
+            reward=-0.05,
+            done=False,
+        )

server/rubric.py

@@ -0,0 +1,326 @@
+"""
+server/rubric.py -- Multi-component reward rubric for the Hypothesis Lab.
+
+Components:
+  1. accuracy_score      (0.0-1.0)  -- how close is the hypothesis to ground truth
+  2. precision_bonus     (+0.10)    -- hypothesis contains quantitative claims
+  3. calibration_score   (0.0-0.20) -- expressed confidence matches accuracy
+  4. efficiency_bonus    (+0.15)    -- submitted early with high accuracy
+  5. contradiction_penalty (-0.50)  -- hypothesis contradicts hard constraints
+
+Per-step info-gain scoring is handled by InfoGainTracker.
+"""
+
+from __future__ import annotations
+
+import re
+import math
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import numpy as np
+
+from .causal_world import CausalWorld
+
+
+@dataclass
+class RubricResult:
+    """Full rubric breakdown returned when a hypothesis is scored."""
+
+    accuracy_score: float = 0.0
+    precision_bonus: float = 0.0
+    calibration_score: float = 0.0
+    efficiency_bonus: float = 0.0
+    contradiction_penalty: float = 0.0
+    feedback: str = ""
+    ground_truth: str = ""
+
+    @property
+    def total(self) -> float:
+        return (
+            self.accuracy_score
+            + self.precision_bonus
+            + self.calibration_score
+            + self.efficiency_bonus
+            + self.contradiction_penalty
+        )
+
+    def to_dict(self) -> dict[str, float]:
+        return {
+            "accuracy_score": round(self.accuracy_score, 4),
+            "precision_bonus": round(self.precision_bonus, 4),
+            "calibration_score": round(self.calibration_score, 4),
+            "efficiency_bonus": round(self.efficiency_bonus, 4),
+            "contradiction_penalty": round(self.contradiction_penalty, 4),
+            "total": round(self.total, 4),
+        }
+
+
+class InfoGainTracker:
+    """
+    Tracks experiment history and computes per-step information gain rewards.
+    Also detects redundant experiments.
+    """
+
+    def __init__(self) -> None:
+        self._edge_counts: dict[tuple[str, str], int] = {}
+        self._edge_types: dict[tuple[str, str], set[str]] = {}
+        self.cumulative_gain: float = 0.0
+        self.redundant_count: int = 0
+
+    def record_and_score(
+        self,
+        cause: str,
+        effect: str,
+        exp_type: str,
+        result_value: Any,
+    ) -> tuple[float, bool]:
+        """
+        Record an experiment and return (reward, is_redundant).
+
+        Reward schedule:
+          - First observation of an edge: +0.20
+          - Second (different exp type = triangulation bonus): +0.25
+          - Second (same type): +0.12
+          - Third+: -0.10 (redundant penalty)
+        """
+        key = (cause, effect)
+        prior = self._edge_counts.get(key, 0)
+        prior_types = set(self._edge_types.get(key, set()))
+
+        self._edge_counts[key] = prior + 1
+        if key not in self._edge_types:
+            self._edge_types[key] = set()
+        self._edge_types[key].add(exp_type)
+
+        if prior == 0:
+            reward = 0.20
+        elif prior == 1:
+            triangulation = exp_type not in prior_types
+            reward = 0.25 if triangulation else 0.12
+        elif prior == 2:
+            reward = 0.05
+        else:
+            reward = -0.10
+            self.redundant_count += 1
+
+        is_redundant = prior >= 3
+        if is_redundant:
+            reward = -0.10
+            self.redundant_count += 1
+
+        self.cumulative_gain += max(reward, 0.0)
+        return round(reward, 4), is_redundant
+
+
+HARD_CONSTRAINTS = [
+    (r"all variables.*independent", "Claiming all variables are independent contradicts the experimental setup"),
+    (r"no.*relationship|no.*causal", "Claiming no relationships exist contradicts the experimental setup"),
+]
+
+
+_RULE_KEYWORDS: dict[str, list[str]] = {
+    "linear": [
+        "linear", "proportional", "slope", "times", "multiply",
+        "increases", "decreases",
+    ],
+    "threshold": [
+        "threshold", "above", "below", "greater", "less",
+        "if", "when", "switch", "cutoff",
+    ],
+    "inverse": ["inverse", "inversely", "reciprocal", "divided", "1/"],
+    "quadratic": [
+        "quadratic", "squared", "parabol", "x^2", "x²", "nonlinear",
+        "curve", "polynomial",
+    ],
+    "exponential": [
+        "exponential", "exp(", "growth", "decay", "e^", "geometric",
+    ],
+    "logarithmic": [
+        "logarithm", "log(", "ln(", "log ", "diminishing returns",
+    ],
+    "saturating": [
+        "saturating", "saturat", "michaelis", "plateau", "asymptote",
+        "levels off", "diminishing", "vmax",
+    ],
+    "piecewise_linear": [
+        "piecewise", "breakpoint", "knot", "changes slope",
+        "two-segment", "regime change", "kink",
+    ],
+    "additive": [
+        "additive", "sum", "combines", "both contribute", "joint",
+    ],
+    "multiplicative": [
+        "multiplicative", "product", "multiply", "synerg", "interaction",
+    ],
+    "min": ["minimum", "bottleneck", "limiting factor", "min("],
+    "max": ["maximum", "dominant", "max("],
+}
+
+
+def _accuracy_score(hypothesis: str, world: CausalWorld) -> float:
+    """Score how well the hypothesis captures the ground truth rules."""
+    if not hypothesis.strip():
+        return 0.0
+
+    text = hypothesis.lower()
+    all_scorable = list(world.rules)
+
+    total_items = len(all_scorable) + len(world.interactions)
+    if total_items == 0:
+        return 0.5
+
+    hits = 0.0
+
+    for rule in all_scorable:
+        cause_l = rule.cause.lower()
+        effect_l = rule.effect.lower()
+
+        has_cause = cause_l in text or cause_l[:4] in text
+        has_effect = effect_l in text or effect_l[:4] in text
+        if not (has_cause and has_effect):
+            continue
+
+        hits += 0.4
+
+        keywords = _RULE_KEYWORDS.get(rule.rule_type, [])
+        if any(w in text for w in keywords):
+            hits += 0.3
+
+        key_param = _key_param_for_rule(rule)
+        if key_param is not None and str(round(abs(key_param), 1)) in hypothesis:
+            hits += 0.3
+
+    for inter in world.interactions:
+        c1_l = inter.cause1.lower()
+        c2_l = inter.cause2.lower()
+        eff_l = inter.effect.lower()
+
+        found_c1 = c1_l in text or c1_l[:4] in text
+        found_c2 = c2_l in text or c2_l[:4] in text
+        found_eff = eff_l in text or eff_l[:4] in text
+
+        if found_eff and (found_c1 or found_c2):
+            hits += 0.3
+        if found_eff and found_c1 and found_c2:
+            hits += 0.2
+
+        keywords = _RULE_KEYWORDS.get(inter.interaction_type, [])
+        if any(w in text for w in keywords):
+            hits += 0.5
+
+    max_possible = total_items * 1.0
+    return min(hits / max_possible, 1.0) if max_possible > 0 else 0.0
+
+
+def _key_param_for_rule(rule) -> Optional[float]:
+    """Return the most important parameter for a rule type, for matching."""
+    rt = rule.rule_type
+    p = rule.params
+    if rt == "linear":
+        return p.get("a")
+    elif rt == "threshold":
+        return p.get("threshold")
+    elif rt == "inverse":
+        return p.get("a")
+    elif rt == "quadratic":
+        return p.get("a")
+    elif rt == "exponential":
+        return p.get("k")
+    elif rt == "logarithmic":
+        return p.get("a")
+    elif rt == "saturating":
+        return p.get("v_max")
+    elif rt == "piecewise_linear":
+        return p.get("knot")
+    return None
+
+
+def _precision_bonus(text: str) -> float:
+    """Does the hypothesis contain numerical values?"""
+    numbers = re.findall(r"-?\d+\.?\d*", text)
+    meaningful = [n for n in numbers if n not in ("0", "1")]
+    return 0.10 if len(meaningful) >= 2 else 0.0
+
+
+def _calibration_score(expressed: Optional[float], actual: float) -> float:
+    """Score based on |expressed_confidence - actual_accuracy|."""
+    if expressed is None:
+        return 0.0
+    error = abs(expressed - actual)
+    return max(0.0, 0.20 * (1.0 - error / 0.5))
+
+
+def _constraint_penalty(text: str) -> float:
+    text_l = text.lower()
+    for pattern, _ in HARD_CONSTRAINTS:
+        if re.search(pattern, text_l):
+            return -0.50
+    return 0.0
+
+
+def _build_feedback(result: RubricResult) -> str:
+    lines = []
+    if result.accuracy_score >= 0.75:
+        lines.append("Strong accuracy -- you identified most causal relationships.")
+    elif result.accuracy_score >= 0.40:
+        lines.append("Partial accuracy -- some relationships identified correctly.")
+    else:
+        lines.append("Low accuracy -- try running more diverse experiments.")
+
+    if result.precision_bonus > 0:
+        lines.append("Good precision -- quantitative claims detected.")
+    else:
+        lines.append("Tip: include numerical values (slopes, thresholds) for precision bonus.")
+
+    if result.efficiency_bonus > 0:
+        lines.append("Efficient submission -- well-timed.")
+    else:
+        lines.append("Tip: submit earlier when confident to earn efficiency bonus.")
+
+    if result.calibration_score >= 0.15:
+        lines.append("Well-calibrated confidence.")
+    elif result.calibration_score > 0:
+        lines.append("Confidence calibration could improve.")
+
+    if result.contradiction_penalty < 0:
+        lines.append("WARNING: hypothesis contradicts known physical constraints.")
+
+    return " ".join(lines)
+
+
+def score_hypothesis(
+    hypothesis_text: str,
+    hypothesis_equations: Optional[list[str]],
+    confidence: Optional[float],
+    world: CausalWorld,
+    budget_remaining: int,
+    budget_total: int,
+) -> RubricResult:
+    """
+    Score a submitted hypothesis against the ground truth world.
+
+    Returns a RubricResult with all component scores, feedback text,
+    and the revealed ground truth.
+    """
+    full_text = hypothesis_text or ""
+    if hypothesis_equations:
+        full_text += " " + " ".join(hypothesis_equations)
+
+    result = RubricResult()
+
+    result.accuracy_score = _accuracy_score(full_text, world)
+    result.precision_bonus = _precision_bonus(full_text)
+    result.calibration_score = _calibration_score(confidence, result.accuracy_score)
+    result.contradiction_penalty = _constraint_penalty(full_text)
+
+    ratio = budget_remaining / max(budget_total, 1)
+    if ratio >= 0.30 and result.accuracy_score >= 0.60:
+        result.efficiency_bonus = 0.15
+    elif ratio >= 0.15 and result.accuracy_score >= 0.40:
+        result.efficiency_bonus = 0.07
+
+    result.ground_truth = world.ground_truth_summary()
+    result.feedback = _build_feedback(result)
+
+    return result

tasks/__init__.py

@@ -0,0 +1,17 @@
+"""Task definitions and graders for the Scientific Hypothesis Lab."""
+
+from .task_easy import TASK_EASY, grade_easy
+from .task_medium import TASK_MEDIUM, grade_medium
+from .task_hard import TASK_HARD, grade_hard
+
+ALL_TASKS = [TASK_EASY, TASK_MEDIUM, TASK_HARD]
+
+__all__ = [
+    "TASK_EASY",
+    "TASK_MEDIUM",
+    "TASK_HARD",
+    "grade_easy",
+    "grade_medium",
+    "grade_hard",
+    "ALL_TASKS",
+]

tasks/task_easy.py

@@ -0,0 +1,57 @@
+"""
+tasks/task_easy.py -- Easy task: 2 variables, low noise.
+
+The agent must discover a single causal relationship between two abstract
+variables in a low-noise setting with a generous budget.
+
+Grader returns 0.0-1.0 based on:
+  - Hypothesis accuracy (60%)
+  - Efficiency bonus (20%)
+  - Calibration (20%)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+TASK_EASY = {
+    "id": "easy",
+    "name": "Easy -- Single-Edge Discovery",
+    "description": (
+        "Discover the causal relationship between two abstract variables. "
+        "Low noise (sigma=0.05), generous budget (12 steps)."
+    ),
+    "difficulty": "easy",
+    "reset_kwargs": {
+        "noise_level": "low",
+        "domain": "system_alpha",
+        "seed": 42,
+    },
+}
+
+
+def grade_easy(episode_result: dict[str, Any]) -> float:
+    """
+    Grade an easy-task episode. Returns a score in [0.0, 1.0].
+
+    Args:
+        episode_result: Dict containing at minimum:
+            - accuracy_score (float): from the rubric
+            - efficiency_bonus (float): from the rubric
+            - calibration_score (float): from the rubric
+            - total_episode_reward (float): sum of all rubric components
+
+    Returns:
+        Normalized score between 0.0 and 1.0.
+    """
+    accuracy = episode_result.get("accuracy_score", 0.0)
+    efficiency = episode_result.get("efficiency_bonus", 0.0)
+    calibration = episode_result.get("calibration_score", 0.0)
+
+    raw = (
+        0.60 * min(accuracy, 1.0)
+        + 0.20 * min(efficiency / 0.15, 1.0)
+        + 0.20 * min(calibration / 0.20, 1.0)
+    )
+
+    return round(max(0.0, min(1.0, raw)), 4)

tasks/task_hard.py

@@ -0,0 +1,55 @@
+"""
+tasks/task_hard.py -- Hard task: 4 variables, high noise, random domain.
+
+The agent must discover a complex causal graph with high noise and a
+tight budget. This is designed to challenge frontier models.
+
+Grader returns 0.0-1.0 based on:
+  - Hypothesis accuracy (40%)
+  - Precision bonus (15%)
+  - Efficiency bonus (15%)
+  - Calibration (15%)
+  - Avoiding contradiction penalty (15%)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+TASK_HARD = {
+    "id": "hard",
+    "name": "Hard -- Complex Graph Under Noise",
+    "description": (
+        "Discover causal relationships among four variables under "
+        "high noise (sigma=0.50) with a tight budget (8 steps). "
+        "Requires strategic experiment design and careful reasoning."
+    ),
+    "difficulty": "hard",
+    "reset_kwargs": {
+        "noise_level": "high",
+        "seed": 999,
+    },
+}
+
+
+def grade_hard(episode_result: dict[str, Any]) -> float:
+    """
+    Grade a hard-task episode. Returns a score in [0.0, 1.0].
+    """
+    accuracy = episode_result.get("accuracy_score", 0.0)
+    precision = episode_result.get("precision_bonus", 0.0)
+    efficiency = episode_result.get("efficiency_bonus", 0.0)
+    calibration = episode_result.get("calibration_score", 0.0)
+    contradiction = episode_result.get("contradiction_penalty", 0.0)
+
+    no_contradiction = 1.0 if contradiction >= 0.0 else 0.0
+
+    raw = (
+        0.40 * min(accuracy, 1.0)
+        + 0.15 * min(precision / 0.10, 1.0)
+        + 0.15 * min(efficiency / 0.15, 1.0)
+        + 0.15 * min(calibration / 0.20, 1.0)
+        + 0.15 * no_contradiction
+    )
+
+    return round(max(0.0, min(1.0, raw)), 4)

tasks/task_medium.py

@@ -0,0 +1,49 @@
+"""
+tasks/task_medium.py -- Medium task: 3 variables, moderate noise, random domain.
+
+The agent must discover multiple causal relationships with moderate noise
+and a standard budget.
+
+Grader returns 0.0-1.0 based on:
+  - Hypothesis accuracy (50%)
+  - Precision bonus (15%)
+  - Efficiency bonus (15%)
+  - Calibration (20%)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+TASK_MEDIUM = {
+    "id": "medium",
+    "name": "Medium -- Multi-Edge Discovery",
+    "description": (
+        "Discover causal relationships among three variables. "
+        "Moderate noise (sigma=0.20), standard budget (10 steps)."
+    ),
+    "difficulty": "medium",
+    "reset_kwargs": {
+        "noise_level": "medium",
+        "seed": 123,
+    },
+}
+
+
+def grade_medium(episode_result: dict[str, Any]) -> float:
+    """
+    Grade a medium-task episode. Returns a score in [0.0, 1.0].
+    """
+    accuracy = episode_result.get("accuracy_score", 0.0)
+    precision = episode_result.get("precision_bonus", 0.0)
+    efficiency = episode_result.get("efficiency_bonus", 0.0)
+    calibration = episode_result.get("calibration_score", 0.0)
+
+    raw = (
+        0.50 * min(accuracy, 1.0)
+        + 0.15 * min(precision / 0.10, 1.0)
+        + 0.15 * min(efficiency / 0.15, 1.0)
+        + 0.20 * min(calibration / 0.20, 1.0)
+    )
+
+    return round(max(0.0, min(1.0, raw)), 4)

test_docker.py

@@ -0,0 +1,87 @@
+"""
+test_docker.py -- Test the Hypothesis Lab environment using the OpenEnv client.
+
+Run with: python test_docker.py
+Requires: the Docker container running on localhost:8000
+"""
+
+import asyncio
+
+from client import HypothesisLabEnv
+
+
+async def main():
+    async with HypothesisLabEnv(base_url="http://localhost:8000") as env:
+
+        # 1. Reset
+        result = await env.reset(noise_level="low", domain="system_alpha", seed=42)
+        obs = result.observation
+        print("=== Episode Started ===")
+        print(f"Message:   {obs.system_message[:80]}...")
+        print(f"Variables: {obs.available_variables}")
+        print(f"Budget:    {obs.budget_remaining}")
+        print()
+
+        v = obs.available_variables
+        cause, effect = v[0], v[1]
+
+        # 2. Intervention -- set one variable, observe the other
+        result = await env.run_intervention(cause, 5.0, effect)
+        obs = result.observation
+        print(f"[Intervention] Set {cause}=5.0 -> {effect}={obs.result_value:.4f}")
+        print(f"  Info gain: {obs.info_gain_reward}  Budget left: {obs.budget_remaining}")
+        print()
+
+        # 3. Try the reverse direction to check causality
+        result = await env.run_intervention(effect, 5.0, cause)
+        obs = result.observation
+        print(f"[Reverse]      Set {effect}=5.0 -> {cause}={obs.result_value:.4f}")
+        print(f"  Info gain: {obs.info_gain_reward}  Budget left: {obs.budget_remaining}")
+        print()
+
+        # 4. Correlation sweep -- see the shape of the relationship
+        result = await env.run_correlation(cause, [0.5, 20.0, 8], effect)
+        obs = result.observation
+        print(f"[Correlation]  Swept {cause} from 0.5 to 20.0:")
+        for x, y in obs.result_value:
+            print(f"  {cause}={x:.1f} -> {effect}={y:.4f}")
+        print(f"  Info gain: {obs.info_gain_reward}  Budget left: {obs.budget_remaining}")
+        print()
+
+        # 5. Counterfactual -- what if cause changes by +3?
+        result = await env.run_counterfactual(cause, 3.0, effect)
+        obs = result.observation
+        cf = obs.result_value
+        print(f"[Counterfactual] If {cause} changes by +3.0:")
+        print(f"  Baseline: {cause}={cf['baseline_x']:.2f} -> {effect}={cf['baseline_y_noisy']:.4f}")
+        print(f"  After:    {cause}={cf['counterfactual_x']:.2f} -> {effect}={cf['counterfactual_y_noisy']:.4f}")
+        print(f"  Direction: {cf['direction']}")
+        print(f"  Info gain: {obs.info_gain_reward}  Budget left: {obs.budget_remaining}")
+        print()
+
+        # 6. Passive observation -- observe a variable without touching anything
+        result = await env.run_passive(effect)
+        obs = result.observation
+        print(f"[Passive]  {effect} at rest = {obs.result_value:.4f}")
+        print(f"  Info gain: {obs.info_gain_reward}  Budget left: {obs.budget_remaining}")
+        print()
+
+        # 7. Submit hypothesis
+        result = await env.submit_hypothesis(
+            hypothesis_text=f"{effect} decays exponentially as {cause} increases.",
+            hypothesis_equations=[f"{effect} = 1.1 * exp(-0.16 * {cause})"],
+            confidence=0.65,
+        )
+        obs = result.observation
+        print("=== Episode Finished ===")
+        print(f"Accuracy:      {obs.accuracy_score}")
+        print(f"Precision:     {obs.precision_bonus}")
+        print(f"Calibration:   {obs.calibration_score}")
+        print(f"Efficiency:    {obs.efficiency_bonus}")
+        print(f"Contradiction: {obs.contradiction_penalty}")
+        print(f"TOTAL REWARD:  {obs.total_episode_reward}")
+        print()
+        print(f"Ground truth:\n{obs.ground_truth_revealed}")
+
+
+asyncio.run(main())

test_local.py

@@ -0,0 +1,82 @@
+"""
+Test the hypothesis-lab environment running locally on Docker (port 8000).
+Uses the standard OpenEnv interface: env.reset() and env.step(action).
+"""
+import asyncio
+import sys
+sys.path.insert(0, "/Users/sbhimraj/Documents/Openenv/lab-experiment")
+
+from client import HypothesisLabEnv
+from models import HypLabAction, ActionType, ExperimentType
+
+
+async def main():
+    print("=== Testing local hypothesis-lab environment ===\n")
+
+    async with HypothesisLabEnv(base_url="http://localhost:8000") as env:
+
+        # Reset episode
+        result = await env.reset(noise_level="low")
+        obs = result.observation
+        variables = obs.available_variables
+        print(f"[reset]")
+        print(f"  variables:  {variables}")
+        print(f"  budget:     {obs.budget_remaining}")
+        print(f"  message:    {obs.system_message[:120]}\n")
+
+        v1, v2 = variables[0], variables[1]
+
+        # Step 1 — intervention experiment
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.INTERVENTION,
+            control_variable=v1,
+            control_value=2.5,
+            target_variable=v2,
+        )
+        result = await env.step(action)
+        obs = result.observation
+        print(f"[step 1: intervention]")
+        print(f"  {v1}=2.5 → {v2} = {obs.result_value}")
+        print(f"  info_gain:   {obs.info_gain_reward}")
+        print(f"  budget left: {obs.budget_remaining}")
+        print(f"  done:        {result.done}\n")
+
+        # Step 2 — correlation experiment
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.CORRELATION,
+            control_variable=v1,
+            control_range=[0.0, 1.0, 2.0, 3.0, 4.0],
+            target_variable=v2,
+        )
+        result = await env.step(action)
+        obs = result.observation
+        print(f"[step 2: correlation]")
+        print(f"  {v1} swept → {v2} = {obs.result_value}")
+        print(f"  info_gain:   {obs.info_gain_reward}")
+        print(f"  budget left: {obs.budget_remaining}")
+        print(f"  done:        {result.done}\n")
+
+        # Step 3 — submit hypothesis
+        action = HypLabAction(
+            action_type=ActionType.SUBMIT,
+            hypothesis_text=f"{v2} increases linearly with {v1} by approximately 2.5 units",
+            confidence=0.7,
+        )
+        result = await env.step(action)
+        obs = result.observation
+        print(f"[step 3: submit]")
+        print(f"  reward:              {result.reward}")
+        print(f"  accuracy_score:      {obs.accuracy_score}")
+        print(f"  precision_bonus:     {obs.precision_bonus}")
+        print(f"  calibration_score:   {obs.calibration_score}")
+        print(f"  efficiency_bonus:    {obs.efficiency_bonus}")
+        print(f"  done:                {result.done}")
+        if obs.ground_truth_revealed:
+            print(f"  ground_truth:        {obs.ground_truth_revealed[:300]}")
+
+    print("\n=== Done — environment is working correctly ===")
+
+
+asyncio.run(main())

tests/test_environment.py

@@ -0,0 +1,428 @@
+"""
+tests/test_environment.py -- Unit + integration tests for HypothesisLab.
+
+Run with: pytest tests/ -v
+"""
+
+import math
+import pytest
+
+from models import ActionType, ExperimentType, HypLabAction, NoiseLevelTag
+from server.causal_world import generate_world, CausalWorld, CausalRule, InteractionRule
+from server.rubric import InfoGainTracker, score_hypothesis
+from server.hypothesis_lab_environment import HypothesisLabEnvironment
+from tasks.task_easy import grade_easy
+from tasks.task_medium import grade_medium
+from tasks.task_hard import grade_hard
+
+
+class TestCausalWorld:
+
+    def test_generate_world_returns_correct_n_variables(self):
+        for n in [2, 3, 4]:
+            world = generate_world(n_variables=n, domain="system_alpha", seed=42)
+            assert len(world.variables) == n
+
+    def test_all_domains_generate_without_error(self):
+        for domain in ["system_alpha", "system_beta", "system_gamma", "system_delta"]:
+            world = generate_world(n_variables=3, domain=domain, seed=0)
+            assert world.domain == domain
+            assert len(world.rules) >= 1
+
+    def test_linear_rule_evaluation(self):
+        rule = CausalRule(
+            cause="X", effect="Y",
+            rule_type="linear",
+            params={"a": 2.0, "b": 3.0},
+            description="Y = 2.0 * X + 3.0",
+        )
+        assert rule.evaluate(0) == pytest.approx(3.0)
+        assert rule.evaluate(5) == pytest.approx(13.0)
+
+    def test_inverse_rule_avoids_division_by_zero(self):
+        rule = CausalRule(
+            cause="X", effect="Y",
+            rule_type="inverse",
+            params={"a": 10.0},
+            description="Y = 10 / X",
+        )
+        result = rule.evaluate(0)
+        assert math.isnan(result)
+
+    def test_intervention_with_noise_is_noisy(self):
+        world = generate_world(n_variables=2, domain="system_alpha", seed=1)
+        cause, effect = world.variables[0], world.variables[1]
+        results = [world.query_intervention(cause, 5.0, effect, sigma=0.5) for _ in range(20)]
+        unique = len(set(results))
+        assert unique > 1, "Noisy results should not be identical"
+
+    def test_correlation_returns_correct_n_points(self):
+        world = generate_world(n_variables=2, domain="system_beta", seed=2)
+        cause, effect = world.variables[0], world.variables[1]
+        pairs = world.query_correlation(cause, [1.0, 10.0, 5.0], effect, sigma=0.0)
+        assert len(pairs) == 5
+
+    def test_ground_truth_summary_contains_all_variables(self):
+        world = generate_world(n_variables=3, domain="system_gamma", seed=3)
+        summary = world.ground_truth_summary()
+        for v in world.variables:
+            assert v in summary
+
+    def test_seed_reproducibility(self):
+        world1 = generate_world(n_variables=3, domain="system_alpha", seed=99)
+        world2 = generate_world(n_variables=3, domain="system_alpha", seed=99)
+        assert world1.variables == world2.variables
+        assert world1.rules[0].rule_type == world2.rules[0].rule_type
+
+    def test_quadratic_rule_evaluation(self):
+        rule = CausalRule(
+            cause="X", effect="Y",
+            rule_type="quadratic",
+            params={"a": 0.5, "b": 1.0, "c": 2.0},
+            description="Y = 0.5*X^2 + 1.0*X + 2.0",
+        )
+        assert rule.evaluate(0) == pytest.approx(2.0)
+        assert rule.evaluate(4) == pytest.approx(0.5*16 + 4 + 2)
+
+    def test_exponential_rule_evaluation(self):
+        rule = CausalRule(
+            cause="X", effect="Y",
+            rule_type="exponential",
+            params={"a": 2.0, "k": 0.0},
+            description="Y = 2 * exp(0 * X)",
+        )
+        assert rule.evaluate(5) == pytest.approx(2.0)
+
+    def test_logarithmic_rule_nan_for_zero(self):
+        rule = CausalRule(
+            cause="X", effect="Y",
+            rule_type="logarithmic",
+            params={"a": 3.0, "b": 0.0},
+        )
+        assert math.isnan(rule.evaluate(0))
+
+    def test_saturating_rule_approaches_vmax(self):
+        rule = CausalRule(
+            cause="X", effect="Y",
+            rule_type="saturating",
+            params={"v_max": 10.0, "k_m": 2.0},
+        )
+        assert rule.evaluate(1000) == pytest.approx(10.0, abs=0.1)
+        assert rule.evaluate(2.0) == pytest.approx(5.0, abs=0.01)
+
+    def test_piecewise_linear_changes_slope(self):
+        rule = CausalRule(
+            cause="X", effect="Y",
+            rule_type="piecewise_linear",
+            params={"knot": 5.0, "a1": 2.0, "a2": -1.0, "b": 0.0},
+        )
+        assert rule.evaluate(3) == pytest.approx(6.0)
+        assert rule.evaluate(7) == pytest.approx(10.0 + (-1.0) * 2)
+
+    def test_interaction_rule_multiplicative(self):
+        inter = InteractionRule(
+            cause1="X", cause2="Y", effect="Z",
+            interaction_type="multiplicative",
+            params={"a": 0.5},
+        )
+        assert inter.evaluate(4.0, 6.0) == pytest.approx(12.0)
+
+    def test_interaction_rule_min(self):
+        inter = InteractionRule(
+            cause1="X", cause2="Y", effect="Z",
+            interaction_type="min",
+        )
+        assert inter.evaluate(3.0, 7.0) == pytest.approx(3.0)
+
+    def test_diverse_rule_types_generated_over_many_seeds(self):
+        """Over many seeds we should see more than 3 distinct rule types."""
+        types_seen: set[str] = set()
+        for seed in range(100):
+            world = generate_world(n_variables=3, seed=seed)
+            for rule in world.rules:
+                types_seen.add(rule.rule_type)
+        assert len(types_seen) >= 5, f"Only saw {types_seen}"
+
+    def test_delta_domain_works(self):
+        world = generate_world(n_variables=3, domain="system_delta", seed=42)
+        assert world.domain == "system_delta"
+        assert len(world.rules) >= 1
+
+    def test_variable_names_are_abstract(self):
+        """Variables should NOT be real-world names that give LLMs prior knowledge."""
+        real_world_names = {
+            "temperature", "pressure", "volume", "density", "entropy",
+            "price", "demand", "supply", "wage", "inflation",
+            "genea", "proteinb", "enzymec", "concentration", "ph",
+        }
+        for seed in range(50):
+            world = generate_world(n_variables=4, seed=seed)
+            for v in world.variables:
+                assert v.lower() not in real_world_names, (
+                    f"Variable '{v}' is a real-world name that gives LLM agents prior knowledge"
+                )
+
+
+class TestInfoGainTracker:
+
+    def test_first_experiment_gives_positive_reward(self):
+        tracker = InfoGainTracker()
+        reward, is_redundant = tracker.record_and_score("A", "B", "intervention", 1.0)
+        assert reward > 0
+        assert not is_redundant
+
+    def test_repeated_experiments_become_redundant(self):
+        tracker = InfoGainTracker()
+        for _ in range(4):
+            reward, is_redundant = tracker.record_and_score("A", "B", "intervention", 1.0)
+        assert is_redundant
+        assert reward < 0
+
+    def test_different_exp_type_gives_triangulation_bonus(self):
+        tracker = InfoGainTracker()
+        tracker.record_and_score("A", "B", "intervention", 1.0)
+        reward2, _ = tracker.record_and_score("A", "B", "correlation", [1, 5, 3])
+        assert reward2 >= 0.25
+
+    def test_cumulative_gain_accumulates(self):
+        tracker = InfoGainTracker()
+        tracker.record_and_score("A", "B", "intervention", 1.0)
+        tracker.record_and_score("B", "C", "intervention", 2.0)
+        assert tracker.cumulative_gain > 0
+
+
+class TestRubric:
+
+    def _make_linear_world(self):
+        import numpy as np
+        rule = CausalRule(
+            cause="Alpha", effect="Beta",
+            rule_type="linear",
+            params={"a": 2.0, "b": 3.0},
+            description="Beta = 2.0 * Alpha + 3.0",
+        )
+        return CausalWorld(
+            domain="system_alpha",
+            variables=["Alpha", "Beta"],
+            units={"Alpha": "units", "Beta": "units"},
+            rules=[rule],
+            default_values={"Alpha": 5.0, "Beta": 13.0},
+            rng=np.random.default_rng(0),
+        )
+
+    def test_perfect_linear_hypothesis_scores_high(self):
+        world = self._make_linear_world()
+        result = score_hypothesis(
+            hypothesis_text="Beta = 2.0 * Alpha + 3.0. Linear relationship.",
+            hypothesis_equations=["Beta = 2.0 * Alpha + 3.0"],
+            confidence=0.9,
+            world=world,
+            budget_remaining=3,
+            budget_total=10,
+        )
+        assert result.accuracy_score >= 0.70
+
+    def test_empty_hypothesis_scores_zero(self):
+        world = self._make_linear_world()
+        result = score_hypothesis(
+            hypothesis_text="",
+            hypothesis_equations=None,
+            confidence=None,
+            world=world,
+            budget_remaining=0,
+            budget_total=10,
+        )
+        assert result.accuracy_score < 0.10
+
+    def test_efficiency_bonus_for_early_submit(self):
+        world = self._make_linear_world()
+        result = score_hypothesis(
+            hypothesis_text="Beta = 2.0 * Alpha + 3.0",
+            hypothesis_equations=["Beta = 2.0 * Alpha + 3.0"],
+            confidence=0.9,
+            world=world,
+            budget_remaining=5,
+            budget_total=10,
+        )
+        assert result.efficiency_bonus > 0.0
+
+    def test_no_efficiency_bonus_when_budget_exhausted(self):
+        world = self._make_linear_world()
+        result = score_hypothesis(
+            hypothesis_text="Beta = 2.0 * Alpha + 3.0",
+            hypothesis_equations=None,
+            confidence=0.9,
+            world=world,
+            budget_remaining=0,
+            budget_total=10,
+        )
+        assert result.efficiency_bonus == 0.0
+
+    def test_overconfident_calibration_penalised(self):
+        world = self._make_linear_world()
+        result = score_hypothesis(
+            hypothesis_text="I have no idea",
+            hypothesis_equations=None,
+            confidence=0.99,
+            world=world,
+            budget_remaining=0,
+            budget_total=10,
+        )
+        assert result.calibration_score <= 0.05
+
+    def test_feedback_text_is_not_empty(self):
+        world = self._make_linear_world()
+        result = score_hypothesis(
+            hypothesis_text="Alpha causes Beta to increase linearly",
+            hypothesis_equations=None,
+            confidence=0.7,
+            world=world,
+            budget_remaining=2,
+            budget_total=10,
+        )
+        assert len(result.feedback) > 10
+
+
+class TestEnvironmentIntegration:
+
+    def test_full_episode_with_submit(self):
+        env = HypothesisLabEnvironment()
+        obs = env.reset(seed=42, noise_level="low", domain="physics")
+        assert obs.budget_remaining > 0
+        assert len(obs.available_variables) >= 2
+        assert not obs.done
+
+        vars_ = obs.available_variables
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.INTERVENTION,
+            control_variable=vars_[0],
+            target_variable=vars_[1],
+            control_value=5.0,
+        )
+        obs = env.step(action)
+        assert obs.result_value is not None
+        assert not obs.done
+
+        submit = HypLabAction(
+            action_type=ActionType.SUBMIT,
+            hypothesis_text=f"{vars_[1]} is linearly related to {vars_[0]}",
+            hypothesis_equations=[f"{vars_[1]} = a * {vars_[0]} + b"],
+            confidence=0.6,
+        )
+        obs = env.step(submit)
+        assert obs.done
+        assert obs.total_episode_reward is not None
+        assert obs.ground_truth_revealed is not None
+
+    def test_budget_exhaustion_ends_episode(self):
+        env = HypothesisLabEnvironment()
+        obs = env.reset(seed=42, noise_level="low")
+        budget = obs.budget_remaining
+        vars_ = obs.available_variables
+
+        for _ in range(budget):
+            if obs.done:
+                break
+            action = HypLabAction(
+                action_type=ActionType.EXPERIMENT,
+                experiment_type=ExperimentType.INTERVENTION,
+                control_variable=vars_[0],
+                target_variable=vars_[1],
+                control_value=5.0,
+            )
+            obs = env.step(action)
+
+        assert obs.done or obs.budget_remaining == 0
+
+    def test_redundant_experiment_gets_penalty(self):
+        env = HypothesisLabEnvironment()
+        obs = env.reset(seed=42, noise_level="low")
+        vars_ = obs.available_variables
+
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.INTERVENTION,
+            control_variable=vars_[0],
+            target_variable=vars_[1],
+            control_value=5.0,
+        )
+        for _ in range(4):
+            obs = env.step(action)
+            if obs.done:
+                break
+
+        assert obs.is_redundant
+        assert obs.info_gain_reward < 0
+
+    def test_invalid_variable_returns_error(self):
+        env = HypothesisLabEnvironment()
+        env.reset(seed=42, noise_level="low")
+
+        action = HypLabAction(
+            action_type=ActionType.EXPERIMENT,
+            experiment_type=ExperimentType.INTERVENTION,
+            control_variable="NONEXISTENT_VAR",
+            target_variable="ALSO_NONEXISTENT",
+            control_value=5.0,
+        )
+        obs = env.step(action)
+        assert "Error" in obs.system_message or "Unknown" in obs.system_message
+
+    def test_state_does_not_leak_hidden_world(self):
+        env = HypothesisLabEnvironment()
+        env.reset(seed=42, noise_level="low")
+        st = env.state
+
+        state_str = str(st.model_dump())
+        assert "rule_type" not in state_str
+        assert "params" not in state_str
+
+    def test_multiple_domains_all_work(self):
+        for domain in ["system_alpha", "system_beta", "system_gamma", "system_delta"]:
+            env = HypothesisLabEnvironment()
+            obs = env.reset(seed=42, domain=domain, noise_level="medium")
+            assert not obs.done
+            assert obs.budget_remaining > 0
+
+
+class TestGraders:
+
+    def test_grader_easy_returns_valid_range(self):
+        score = grade_easy({
+            "accuracy_score": 0.8,
+            "efficiency_bonus": 0.15,
+            "calibration_score": 0.20,
+        })
+        assert 0.0 <= score <= 1.0
+
+    def test_grader_medium_returns_valid_range(self):
+        score = grade_medium({
+            "accuracy_score": 0.5,
+            "precision_bonus": 0.10,
+            "efficiency_bonus": 0.07,
+            "calibration_score": 0.10,
+        })
+        assert 0.0 <= score <= 1.0
+
+    def test_grader_hard_returns_valid_range(self):
+        score = grade_hard({
+            "accuracy_score": 0.3,
+            "precision_bonus": 0.0,
+            "efficiency_bonus": 0.0,
+            "calibration_score": 0.05,
+            "contradiction_penalty": 0.0,
+        })
+        assert 0.0 <= score <= 1.0
+
+    def test_grader_zero_input_returns_zero(self):
+        score = grade_easy({})
+        assert score == 0.0
+
+    def test_grader_perfect_input_returns_one(self):
+        score = grade_easy({
+            "accuracy_score": 1.0,
+            "efficiency_bonus": 0.15,
+            "calibration_score": 0.20,
+        })
+        assert score == pytest.approx(1.0)