Spaces:

anugrahhu
/

cernenv

Sleeping

File size: 7,334 Bytes

"""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 style="margin: 1rem 0">

    <a href="/demo/" target="_top" style="display:inline-block; background:#1d4ed8; color:white;

       padding:.6rem 1.1rem; border-radius:6px; text-decoration:none;

       font-weight:600; box-shadow:0 1px 3px rgba(0,0,0,.1)">

      ▶ Try the interactive demo at /demo

    </a>

  </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,

    and an interactive Gradio demo at ``/demo`` so non-technical visitors

    can play with the env in the browser without writing any code.

    """
    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)

    # Best-effort mount of the Gradio interactive demo at /demo. We only
    # *add* a route here — the OpenEnv HTTP API at /health, /reset, /step,
    # /state, /schema, /mcp, /docs is unchanged. If gradio isn't installed
    # in the runtime environment (e.g. during minimal CI), we log and skip.
    try:
        import gradio as gr  # noqa: F401  (presence check)
        from space.env.gradio_demo import build_gradio_demo

        demo = build_gradio_demo()
        fa_app = gr.mount_gradio_app(fa_app, demo, path="/demo")
    except Exception as exc:  # pragma: no cover - optional dep
        import logging
        logging.getLogger(__name__).warning(
            "Gradio demo not mounted at /demo: %s", exc
        )

    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()