File size: 6,118 Bytes
7103888 2b0bffa 7103888 2b0bffa 7103888 2b0bffa 7103888 2b0bffa 7103888 2b0bffa | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 | """FastAPI app exposing ``CERNCollisionEnvironment`` over the OpenEnv HTTP API.
We delegate the standard OpenEnv routes (``/reset``, ``/step``, ``/state``,
``/schema``, ``/health``, ``/mcp``) to ``create_fastapi_app`` and add a
human-friendly landing page at ``/`` so the Hugging Face Space preview
shows the project description instead of a 404.
"""
from __future__ import annotations
import os
from typing import Optional
from fastapi.responses import HTMLResponse
from openenv.core.env_server import create_fastapi_app
from models import CollisionObservation, ExperimentAction
from server.environment import CERNCollisionEnvironment
_LANDING_PAGE = """\
<!doctype html>
<html lang=en>
<head>
<meta charset=utf-8>
<title>CERNenv — LHC Discovery RL Environment</title>
<meta name=viewport content="width=device-width,initial-scale=1">
<style>
body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
margin: 2rem auto; max-width: 780px; color:#111; padding: 0 1rem; line-height:1.5 }
h1 { margin-bottom: .25rem }
h2 { margin-top: 2rem; border-bottom: 1px solid #eee; padding-bottom: .25rem }
code { background:#f4f4f4; padding:.05rem .35rem; border-radius:4px; font-size:.95em }
pre { background:#0e1116; color:#e6edf3; padding:1rem; border-radius:6px; overflow-x:auto }
pre code { background:transparent; color:inherit; padding:0 }
.pill { display:inline-block; padding:.1rem .55rem; border-radius:999px;
background:#e8f0ff; color:#1d4ed8; font-size:.85em; margin-right:.25rem }
.muted { color:#666 }
a { color:#1d4ed8 }
table { border-collapse:collapse; margin: .5rem 0 }
th,td { text-align:left; padding:.25rem .9rem .25rem 0; vertical-align: top }
th { color:#444; font-weight:600 }
</style>
</head>
<body>
<h1>⚛️ CERNenv</h1>
<p class=muted>An LHC (Large Hadron Collider) particle-discovery RL environment for autonomous physicist agents — built for the Meta OpenEnv Hackathon.</p>
<p>
<span class=pill>OpenEnv</span>
<span class=pill>POMDP</span>
<span class=pill>16 action types</span>
<span class=pill>3 difficulty levels</span>
<span class=pill>HTTP + WebSocket</span>
</p>
<h2>What this is</h2>
<p>
A Large Language Model (LLM) agent plays a high-energy physicist running an
analysis at the LHC. Each step it picks one structured action — configure
the beam, allocate luminosity, set a trigger, collect collisions, fit a
resonance, estimate significance, submit a discovery claim, and so on —
and receives a noisy detector-style observation. The latent particle
(mass, decay channel, branching ratios, width) is hidden ground truth.
Reward decomposes into per-step shaping + a dominant terminal calibration
against the truth particle.
</p>
<h2>API</h2>
<table>
<tr><th><code>GET /health</code></th><td>liveness probe</td></tr>
<tr><th><code>GET /schema</code></th><td>JSON schemas for actions, observations, state</td></tr>
<tr><th><code>POST /reset</code></th><td>start a new episode (e.g. <code>{"seed": 7, "scenario": "easy_diphoton_160"}</code>)</td></tr>
<tr><th><code>POST /step</code></th><td>execute one action (<code>{"action": {"action_type": ..., "parameters": {...}, "justification": "..."}}</code>)</td></tr>
<tr><th><code>GET /state</code></th><td>current public state snapshot</td></tr>
<tr><th><code>GET /docs</code></th><td>interactive Swagger UI</td></tr>
<tr><th><code>GET /metadata</code></th><td>environment metadata</td></tr>
</table>
<h2>Quickstart</h2>
<pre><code># reset
curl -X POST $URL/reset \\
-H 'Content-Type: application/json' \\
-d '{"seed": 7, "scenario": "easy_diphoton_160"}'
# step
curl -X POST $URL/step \\
-H 'Content-Type: application/json' \\
-d '{"action": {"action_type": "configure_beam",
"parameters": {"sqrt_s_tev": 13.0},
"justification": "set 13 TeV"}}'</code></pre>
<h2>Companion Spaces</h2>
<ul>
<li>📓 Trainer (Unsloth + LoRA + GRPO on A100): <a href="https://huggingface.co/spaces/anugrah55/cernenv-trainer">anugrah55/cernenv-trainer</a></li>
<li>🎯 Trained adapters (LoRA): <a href="https://huggingface.co/anugrah55/cernenv-grpo-qwen2.5-3b">anugrah55/cernenv-grpo-qwen2.5-3b</a></li>
</ul>
<p class=muted style="margin-top:2rem">CERNenv · OpenEnv-compatible · BSD-3-Clause</p>
</body>
</html>
"""
def make_env_factory(
max_steps: int,
default_difficulty: Optional[str],
):
def factory() -> CERNCollisionEnvironment:
return CERNCollisionEnvironment(
max_steps=max_steps,
default_difficulty=default_difficulty,
)
return factory
def build_app(
*,
max_steps: int = 40,
default_difficulty: Optional[str] = None,
):
"""Construct the FastAPI app with a per-session environment factory.
The OpenEnv-provided routes (`/reset`, `/step`, `/state`, `/schema`,
`/health`, `/mcp`) come from ``create_fastapi_app``. We then mount a
friendly landing page at ``/`` so the Space preview is informative.
"""
factory = make_env_factory(max_steps=max_steps, default_difficulty=default_difficulty)
fa_app = create_fastapi_app(factory, ExperimentAction, CollisionObservation)
@fa_app.get("/", response_class=HTMLResponse, include_in_schema=False)
def landing() -> HTMLResponse: # pragma: no cover - trivial
return HTMLResponse(_LANDING_PAGE)
return fa_app
app = build_app(
max_steps=int(os.getenv("CERNENV_MAX_STEPS", "40")),
default_difficulty=os.getenv("CERNENV_DEFAULT_DIFFICULTY") or None,
)
def main() -> None: # pragma: no cover - CLI entrypoint
import uvicorn
host = os.getenv("HOST", "0.0.0.0")
port = int(os.getenv("PORT", "8000"))
uvicorn.run("server.app:app", host=host, port=port, log_level="info")
if __name__ == "__main__": # pragma: no cover
main()
|