README.md

---
title: CERNenv
emoji: ⚛️
colorFrom: blue
colorTo: indigo
sdk: docker
suggested_hardware: cpu-basic
pinned: false
license: bsd-3-clause
short_description: LHC particle-discovery RL environment
---

# CERNenv — LHC Discovery RL Environment

OpenEnv-compatible reinforcement-learning environment that simulates an
LHC (Large Hadron Collider) analysis. An LLM (Large Language Model) agent
configures the beam, allocates luminosity, picks a decay channel and
trigger, runs reconstruction, fits an invariant-mass spectrum, estimates
significance, and finally submits a structured discovery claim that is
graded against a hidden ground-truth particle.

The Space exposes the standard OpenEnv HTTP + WebSocket API:

* `GET  /health` — liveness
* `GET  /schema` — action / observation / state JSON schemas
* `POST /reset`  — start a new episode (`{ "seed": 7, "scenario": "easy_diphoton_160" }`)
* `POST /step`   — execute one action
* `GET  /state`  — current `CernState`
* `WS   /ws`     — persistent session (recommended for multi-step rollouts)

## Quickstart (Python client)

```python
import asyncio
from openenv.core import EnvClient
from huggingface_hub import constants

# replace with your space id
SPACE = "YOUR_HF_USERNAME/cernenv"

# (option A) connect to the running Space directly
import websockets
async def main():
    async with EnvClient.from_env(SPACE) as env:  # uses websockets under the hood
        result = await env.reset(seed=7, scenario="easy_diphoton_160")
        ...

asyncio.run(main())
```

For training, see the companion **CERNenv Trainer** Space.