fix: align package with openenv contract

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        docker.io \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml .
+COPY openenv.yaml .
+COPY server/ server/
+COPY src/ src/
+
+RUN pip install --no-cache-dir -e .
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -31,14 +31,27 @@ Red and Blue operate on the **same infrastructure simultaneously**. Red's stealt
 ## Quick Start
 
 ```bash
-git clone https://github.com/open-cybernauts/open-range.git && cd open-range
-uv sync --all-extras
+# Install
+git clone https://github.com/open-cybernauts/open-range.git
+cd open-range
+uv sync
+
+# Optional: enable the LiteLLM-backed builder pipeline
+uv sync --extra builder
 
 # End-to-end demo (no Docker, no LLM)
 uv run python examples/demo.py
 
-# Run the server
-python -m open_range.server
+# Run the OpenEnv client against a running server
+uv run python examples/remote_client_demo.py --base-url http://localhost:8000
+
+# Run the FastAPI server
+uv run server                                   # default: 127.0.0.1:8000
+uv run server --port 9000                       # custom port
+uv run server --host 0.0.0.0                    # bind all interfaces
+
+# Or via uvicorn directly
+uv run uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload
 
 # Tests
 uv run pytest tests/ -v --tb=short
@@ -50,6 +63,8 @@ uv run pytest tests/ -v --tb=short
 
 **Builder** — Takes a manifest + curriculum context, outputs a `SnapshotSpec`: topology graph, truth graph (planted vulns + exploit chain), evidence graph (what Blue can find), flags, golden path, NPC traffic, and task briefings. Three implementations: `LLMSnapshotBuilder` (production, via litellm), `TemplateOnlyBuilder` (deterministic, for tests), `FileBuilder` (load from disk).
 
+The deployed package exposes the standard OpenEnv `reset()`, `step()`, and `state()` contract through `server.app:app`, which is the entrypoint referenced by `openenv.yaml`.
+
 **Validator** — 10-check admission pipeline. 8 mechanical checks (build/boot, exploitability, patchability, evidence sufficiency, reward grounding, isolation, task feasibility, difficulty calibration) + 2 LLM advisory checks (NPC consistency, realism review). Inverse mutation: patching each planted vuln must break its exploit step.
 
 **Environment** — `RangeEnvironment(Environment)` following the OpenEnv contract. `reset()` picks a frozen snapshot + samples a task. `step(action)` routes commands to the appropriate container — Red runs on the attacker box, Blue runs on the SIEM. No artificial command allowlists; the container's installed tools are the constraint.

docs/openenv-compliance.md

@@ -6,46 +6,35 @@ OpenRange implements the OpenEnv 0.2.x environment contract. This doc maps every
 
 | Requirement | Status | Implementation |
 |-------------|--------|----------------|
-| `Environment` subclass | Done | `RangeEnvironment` extends `Environment[RangeAction, RangeObservation, RangeState]` when openenv is installed; falls back to plain `object` base with the same API surface |
+| `Environment` subclass | Done | `RangeEnvironment` extends `Environment[RangeAction, RangeObservation, RangeState]` |
 | `reset()` returns `ObsT` | Done | Returns `RangeObservation` with episode briefing |
 | `step()` returns `ObsT` | Done | Returns `RangeObservation` with stdout/stderr/reward/done |
 | `state` property returns `StateT` | Done | Returns `RangeState` (episode_id, step_count, mode, flags_found, services_status, tier) |
-| `Action` subclass (Pydantic, extra=forbid) | Done | `RangeAction(Action)` with `command: str`, `mode: Literal["red", "blue"]`. Note: `extra="forbid"` comes from the openenv `Action` base; the fallback stub inherits plain `BaseModel` without it |
+| `Action` subclass (Pydantic, extra=forbid) | Done | `RangeAction(Action)` with `command: str`, `mode: Literal["red", "blue"]` |
 | `Observation` subclass (Pydantic, extra=forbid) | Done | `RangeObservation(Observation)` — inherits `done`, `reward` from base; adds `stdout`, `stderr`, `flags_captured`, `alerts` |
 | `State` subclass (Pydantic, extra=allow) | Done | `RangeState(State)` — inherits `episode_id`, `step_count` from base; adds `mode`, `flags_found`, `services_status`, `tier` |
-| `create_app(Class, ActionType, ObsType)` | Done | `app.py` tries `openenv.core.env_server.create_app(RangeEnvironment, RangeAction, RangeObservation, env_name="open_range")`; falls back to a standalone FastAPI app with equivalent endpoints |
-| `EnvClient` subclass | Done | `OpenRangeEnv(EnvClient[RangeAction, RangeObservation, RangeState])` when openenv is installed; stub client otherwise |
+| `create_app(Class, ActionType, ObsType)` | Done | `open_range.server.app:create_app()` delegates directly to `openenv.core.env_server.create_app(...)` |
+| `EnvClient` subclass | Done | `OpenRangeEnv(EnvClient[RangeAction, RangeObservation, RangeState])` |
 | `_step_payload()` | Done | Returns `{"command": action.command, "mode": action.mode}` |
 | `_parse_result()` | Done | Parses server response to `StepResult[RangeObservation]` |
 | `_parse_state()` | Done | Parses server response to `RangeState` |
-| `/health` endpoint | Done | Returns `{"status": "ok"}` (standalone) or openenv default |
-| `/metadata` endpoint | Done | Returns name, version, description, supports_concurrent_sessions |
-| `/schema` endpoint | Done | Returns JSON schemas for RangeAction, RangeObservation, RangeState |
-| `/ws` WebSocket | Done | Standalone implementation with per-connection `RangeEnvironment` instance; accepts `reset`, `step`, `state` message types |
-| `/reset`, `/step`, `/state` HTTP | Done | POST /reset, POST /step, GET /state — all implemented in standalone fallback and via `create_app` |
+| `/health` endpoint | Done | Provided by `create_app(...)` |
+| `/metadata` endpoint | Done | Provided by `create_app(...)` |
+| `/schema` endpoint | Done | Provided by `create_app(...)` |
+| `/ws` WebSocket | Done | Provided by `create_app(...)` |
+| `/reset`, `/step`, `/state` HTTP | Done | Provided by `create_app(...)` |
 | `Rubric` for rewards | Done | `CompositeRedReward`, `CompositeBlueReward` (lazy-loaded in `RangeEnvironment._apply_rewards`) |
-| `openenv.yaml` manifest | Done | `openenv.yaml` at project root (name: open_range, version: 0.1.0) |
-| `Dockerfile` | Done | `server/Dockerfile` — Python 3.11-slim, docker.io + curl, healthcheck on `/health`, CMD uvicorn |
-| `python -m open_range.server` entry point | Done | `server/__main__.py` — starts uvicorn with `--host`, `--port`, `--reload`, `--log-level` flags |
+| `openenv.yaml` manifest | Done | Root `openenv.yaml` with `spec_version`, `type`, `runtime`, `app`, and `port` |
+| `Dockerfile` | Done | Root `Dockerfile` plus `server/Dockerfile`, both launching `uvicorn server.app:app` |
+| `python -m open_range.server` entry point | Done | `open_range.server.__main__` plus `server` console script |
 
-## Dual-Mode Server
+## Server Mode
 
-The server (`app.py`) operates in two modes:
+The server entrypoint is the standard OpenEnv app factory:
 
-1. **OpenEnv mode** — when `openenv` is installed, delegates to `openenv.core.env_server.create_app` which provides all endpoints automatically.
-2. **Standalone mode** — when `openenv` is not installed, runs a self-contained FastAPI app with equivalent HTTP endpoints (GET /health, GET /metadata, GET /schema, POST /reset, POST /step, GET /state) and a WebSocket endpoint at `/ws` with per-connection environment isolation.
-
-Both modes serve the same contract. The standalone fallback ensures the server works without the openenv package installed.
-
-### WebSocket Protocol
-
-The `/ws` endpoint accepts JSON messages with a `type` field:
-
-- `{"type": "reset"}` or `{"type": "reset", "seed": 42, "episode_id": "ep1"}` — reset the environment
-- `{"type": "step", "command": "nmap -sV 10.0.1.2", "mode": "red"}` — execute an action
-- `{"type": "state"}` — get current episode state
-
-Responses include a `type` field: `"observation"`, `"state"`, or `"error"`.
+- `open_range.server.app:create_app()` returns `create_app(RangeEnvironment, RangeAction, RangeObservation, env_name="open_range")`
+- `server.app:app` is the repository-level wrapper referenced by `openenv.yaml`
+- The OpenEnv-generated HTTP and WebSocket endpoints are the only public runtime contract
 
 ## Deployment
 

examples/remote_client_demo.py

@@ -0,0 +1,31 @@
+"""Minimal OpenEnv client demo for a running OpenRange server."""
+
+from __future__ import annotations
+
+import argparse
+
+from open_range import OpenRangeEnv, RangeAction
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Connect to a running OpenRange server")
+    parser.add_argument(
+        "--base-url",
+        default="http://localhost:8000",
+        help="OpenEnv server base URL",
+    )
+    args = parser.parse_args()
+
+    with OpenRangeEnv(base_url=args.base_url).sync() as env:
+        result = env.reset()
+        print(result.observation.stdout)
+
+        result = env.step(
+            RangeAction(command="nmap -sV 10.0.1.0/24", mode="red")
+        )
+        print(result.observation.stdout)
+        print(f"reward={result.reward} done={result.done}")
+
+
+if __name__ == "__main__":
+    main()

openenv.yaml

@@ -1,5 +1,9 @@
 spec_version: 1
 name: open_range
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
 version: 0.1.0
 type: space
 runtime: fastapi

pyproject.toml

@@ -11,13 +11,13 @@ dependencies = [
     "pyyaml>=6.0",
     "docker>=7.0",
     "jinja2>=3.1",
-    "litellm>=1.30",
-    "uvicorn>=0.24",
+    "uvicorn>=0.27",
 ]
 
 [project.optional-dependencies]
 dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "httpx>=0.27"]
 training = ["trl>=0.8", "unsloth"]
+builder = ["litellm>=1.30"]
 
 [build-system]
 requires = ["hatchling"]

server/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        docker.io \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml .
+COPY openenv.yaml .
+COPY server/ server/
+COPY src/ src/
+
+RUN pip install --no-cache-dir -e .
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

server/__init__.py

@@ -0,0 +1,6 @@
+"""Repository-level OpenEnv server entrypoints."""
+
+from .app import app, create_app
+from .environment import RangeEnvironment
+
+__all__ = ["RangeEnvironment", "app", "create_app"]

server/app.py

@@ -0,0 +1,18 @@
+"""OpenEnv app entrypoint expected by ``openenv.yaml``."""
+
+from __future__ import annotations
+
+from open_range.server.app import app, create_app
+
+__all__ = ["app", "create_app"]
+
+
+def main() -> None:
+    """Run the repository-level server entrypoint via uvicorn."""
+    import uvicorn
+
+    uvicorn.run("server.app:app", host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

server/environment.py

@@ -0,0 +1,5 @@
+"""Repository-level environment wrapper for OpenEnv tooling."""
+
+from open_range.server.environment import RangeEnvironment
+
+__all__ = ["RangeEnvironment"]

src/open_range/__init__.py

@@ -1,11 +1,17 @@
-"""OpenRange: Multi-agent cybersecurity gymnasium built on OpenEnv."""
+"""OpenRange public package surface."""
 
 from open_range.client.client import OpenRangeEnv
-from open_range.server.models import RangeAction, RangeObservation, RangeState
+from open_range.server.environment import RangeEnvironment
+from open_range.server.models import (
+    RangeAction,
+    RangeObservation,
+    RangeState,
+)
 
 __all__ = [
     "OpenRangeEnv",
     "RangeAction",
+    "RangeEnvironment",
     "RangeObservation",
     "RangeState",
 ]

src/open_range/builder/builder.py

@@ -14,7 +14,10 @@ import random
 from pathlib import Path
 from typing import Any
 
-import litellm
+try:
+    import litellm
+except ImportError:  # pragma: no cover - exercised only without builder extra
+    litellm = None
 
 from open_range.protocols import (
     BuildContext,
@@ -66,6 +69,12 @@ class LLMSnapshotBuilder:
         context: BuildContext,
     ) -> SnapshotSpec:
         """Call LLM to generate a candidate snapshot spec."""
+        if litellm is None:
+            raise RuntimeError(
+                "LLMSnapshotBuilder requires the optional builder extra. "
+                "Install with `pip install open-range[builder]`."
+            )
+
         user_payload = json.dumps(
             {
                 "manifest": manifest,

src/open_range/client/__init__.py

@@ -1,4 +1,4 @@
-"""OpenRange client package."""
+"""Typed OpenEnv client exports."""
 
 from open_range.client.client import OpenRangeEnv
 

src/open_range/client/client.py

@@ -1,64 +1,30 @@
-"""OpenEnv client for OpenRange.
-
-Provides OpenRangeEnv which wraps the typed EnvClient with
-OpenRange-specific action/observation/state parsing.
-"""
+"""Typed OpenEnv client for OpenRange."""
 
 from __future__ import annotations
 
-from typing import Any
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
 
 from open_range.server.models import RangeAction, RangeObservation, RangeState
 
-try:
-    from openenv.core.env_client import EnvClient
-    from openenv.core.client_types import StepResult
-
-    class OpenRangeEnv(EnvClient[RangeAction, RangeObservation, RangeState]):
-        """Typed OpenEnv client for OpenRange."""
-
-        def _step_payload(self, action: RangeAction) -> dict:
-            return {"command": action.command, "mode": action.mode}
-
-        def _parse_result(self, payload: dict) -> StepResult[RangeObservation]:
-            obs = RangeObservation(**payload.get("observation", {}))
-            return StepResult(
-                observation=obs,
-                reward=payload.get("reward"),
-                done=bool(payload.get("done", False)),
-            )
-
-        def _parse_state(self, payload: dict) -> RangeState:
-            return RangeState(**payload)
-
-except ImportError:
-    # Stub for development without openenv installed
-    from dataclasses import dataclass
-
-    @dataclass
-    class StepResult:  # type: ignore[no-redef]
-        """Minimal StepResult stub matching openenv.core.client_types."""
-
-        observation: RangeObservation
-        reward: float | None = None
-        done: bool = False
 
-    class OpenRangeEnv:  # type: ignore[no-redef]
-        """Stub client for development without openenv."""
+class OpenRangeEnv(EnvClient[RangeAction, RangeObservation, RangeState]):
+    """Typed OpenEnv client that speaks the standard reset/step/state contract."""
 
-        def __init__(self, base_url: str = "http://localhost:8000"):
-            self.base_url = base_url
+    def sync(self) -> "OpenRangeEnv":
+        """Compatibility wrapper matching the documented OpenEnv sync pattern."""
+        return self
 
-        def _step_payload(self, action: RangeAction) -> dict:
-            return {"command": action.command, "mode": action.mode}
+    def _step_payload(self, action: RangeAction) -> dict:
+        return {"command": action.command, "mode": action.mode}
 
-        def _parse_result(self, payload: dict) -> StepResult:
-            obs = RangeObservation(**payload.get("observation", {}))
-            return StepResult(
-                observation=obs,
-                reward=payload.get("reward"),
-                done=bool(payload.get("done", False)),
-            )
+    def _parse_result(self, payload: dict) -> StepResult[RangeObservation]:
+        obs = RangeObservation(**payload.get("observation", {}))
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward"),
+            done=bool(payload.get("done", False)),
+        )
 
-        def _parse_state(self, payload: dict) -> RangeState:
-            return RangeState(**payload)
+    def _parse_state(self, payload: dict) -> RangeState:
+        return RangeState(**payload)

src/open_range/server/Dockerfile

@@ -31,6 +31,7 @@ COPY --from=builder /app/src /app/src
 COPY --from=builder /app/pyproject.toml /app/pyproject.toml
 COPY --from=builder /app/openenv.yaml /app/openenv.yaml
 COPY --from=builder /app/manifests /app/manifests
+COPY server/ server/
 
 ENV PATH="/app/.venv/bin:$PATH"
 ENV PYTHONPATH="/app/src:$PYTHONPATH"
@@ -40,4 +41,4 @@ 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
 
-CMD ["uvicorn", "open_range.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

src/open_range/server/__init__.py

@@ -0,0 +1,6 @@
+"""Server-side exports for OpenRange."""
+
+from open_range.server.app import app, create_app
+from open_range.server.environment import RangeEnvironment
+
+__all__ = ["RangeEnvironment", "app", "create_app"]

src/open_range/server/app.py

@@ -1,295 +1,32 @@
-"""FastAPI application for the OpenRange cybersecurity gymnasium.
-
-If openenv is installed, delegates to ``openenv.core.env_server.create_app``
-which provides /health, /reset, /step, /state, /ws, /metadata, /schema
-endpoints automatically.
-
-Otherwise falls back to a manual FastAPI app with equivalent HTTP endpoints
-plus a WebSocket endpoint at ``/ws`` for persistent sessions.
-"""
+"""FastAPI application wired through the OpenEnv app factory."""
 
 from __future__ import annotations
 
-import json
-import logging
-from typing import Any
+from fastapi import FastAPI
+from openenv.core.env_server import create_app as create_openenv_app
 
-from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
-from pydantic import BaseModel, ValidationError
-
-from open_range.server.console import clear_history, console_router, record_action
+from open_range.server.console import console_router
 from open_range.server.environment import RangeEnvironment
-from open_range.server.models import RangeAction, RangeObservation, RangeState
-
-logger = logging.getLogger(__name__)
-
-_APP_VERSION = "0.1.0"
-
-# ---------------------------------------------------------------------------
-# Try the OpenEnv app factory first
-# ---------------------------------------------------------------------------
-
-
-def _try_openenv_app() -> FastAPI | None:
-    """Attempt to create the app via openenv.create_app.
-
-    Returns None if openenv is not installed or the import fails.
-    """
-    try:
-        from openenv.core.env_server import create_app
-
-        openenv_app = create_app(
-            RangeEnvironment,
-            RangeAction,
-            RangeObservation,
-            env_name="open_range",
-        )
-        openenv_app.include_router(console_router)
-        return openenv_app
-    except ImportError:
-        logger.info("openenv not installed -- using standalone FastAPI app")
-        return None
-    except Exception as exc:
-        logger.warning("openenv create_app failed (%s) -- falling back", exc)
-        return None
-
-
-# ---------------------------------------------------------------------------
-# Request/Response models matching OpenEnv HTTP protocol
-# ---------------------------------------------------------------------------
-
-
-class ResetRequest(BaseModel):
-    """Matches openenv.core.env_server.types.ResetRequest."""
-
-    seed: int | None = None
-    episode_id: str | None = None
+from open_range.server.models import RangeAction, RangeObservation
 
 
-class StepRequest(BaseModel):
-    """Matches openenv.core.env_server.types.StepRequest."""
-
-    action: dict[str, Any]
-    timeout_s: float | None = None
-    request_id: str | None = None
-
-
-# ---------------------------------------------------------------------------
-# Standalone FastAPI fallback
-# ---------------------------------------------------------------------------
-
-
-def _create_standalone_app() -> FastAPI:
-    """Build a FastAPI app that mirrors the OpenEnv endpoint contract.
-
-    Endpoints
-    ---------
-    GET  /health    -- liveness check
-    GET  /metadata  -- environment metadata
-    GET  /schema    -- JSON schemas for action, observation, state
-    POST /reset     -- reset environment, returns initial observation
-    POST /step      -- execute an action, returns observation + reward + done
-    GET  /state     -- current episode state
-    WS   /ws        -- persistent WebSocket session (JSON messages)
-    """
-
-    fastapi_app = FastAPI(
-        title="OpenRange",
-        description="Multi-agent cybersecurity gymnasium",
-        version=_APP_VERSION,
+def create_app() -> FastAPI:
+    """Create the OpenRange app using the standard OpenEnv contract."""
+    app = create_openenv_app(
+        RangeEnvironment,
+        RangeAction,
+        RangeObservation,
+        env_name="open_range",
     )
+    app.include_router(console_router)
+    return app
 
-    # Shared environment instance for HTTP endpoints.
-    # Each WebSocket session creates its own isolated instance.
-    env = RangeEnvironment()
-
-    # Store env on app.state so the console router can access it
-    fastapi_app.state.env = env
-
-    # Include the operator console router
-    fastapi_app.include_router(console_router)
-
-    # ---------------------------------------------------------------
-    # HTTP endpoints (matches OpenEnv HTTPEnvServer contract)
-    # ---------------------------------------------------------------
-
-    @fastapi_app.get("/health")
-    async def health() -> dict[str, str]:
-        return {"status": "healthy"}
-
-    @fastapi_app.get("/metadata")
-    async def metadata() -> dict[str, Any]:
-        return {
-            "name": "open_range",
-            "version": _APP_VERSION,
-            "description": "Multi-agent cybersecurity gymnasium built on OpenEnv",
-            "supports_concurrent_sessions": False,
-        }
-
-    @fastapi_app.get("/schema")
-    async def schema() -> dict[str, Any]:
-        return {
-            "action": RangeAction.model_json_schema(),
-            "observation": RangeObservation.model_json_schema(),
-            "state": RangeState.model_json_schema(),
-        }
-
-    @fastapi_app.post("/reset")
-    async def reset(req: ResetRequest | None = None) -> dict[str, Any]:
-        req = req or ResetRequest()
-        clear_history()
-        obs = env.reset(seed=req.seed, episode_id=req.episode_id)
-        return {
-            "observation": obs.model_dump(),
-            "reward": obs.reward,
-            "done": obs.done,
-        }
 
-    @fastapi_app.post("/step")
-    async def step(request: Request) -> dict[str, Any]:
-        import time as _time
-
-        body = await request.json()
-        # Accept both StepRequest {"action": {...}} and direct RangeAction {"command": ..., "mode": ...}
-        if "action" in body:
-            action = RangeAction(**body["action"])
-            timeout_s = body.get("timeout_s")
-        else:
-            action = RangeAction(**body)
-            timeout_s = None
-        obs = env.step(action, timeout_s=timeout_s)
-        record_action({
-            "step": env.state.step_count,
-            "command": action.command,
-            "mode": action.mode,
-            "time": _time.time(),
-        })
-        return {
-            "observation": obs.model_dump(),
-            "reward": obs.reward,
-            "done": obs.done,
-        }
-
-    @fastapi_app.get("/state")
-    async def get_state() -> dict[str, Any]:
-        return env.state.model_dump()
-
-    # ---------------------------------------------------------------
-    # WebSocket endpoint (matches OpenEnv WebSocket protocol)
-    # ---------------------------------------------------------------
-
-    @fastapi_app.websocket("/ws")
-    async def ws_endpoint(websocket: WebSocket) -> None:
-        """Persistent WebSocket session with per-connection environment.
-
-        Message protocol (matches OpenEnv WebSocket contract):
-
-        Client sends:
-          {"type": "reset", "data": {"seed": 42, "episode_id": "ep1"}}
-          {"type": "step", "data": {"command": "...", "mode": "red"}}
-          {"type": "state"}
-          {"type": "close"}
-
-        Server responds:
-          {"type": "observation", "data": {...}}
-          {"type": "state", "data": {...}}
-          {"type": "error", "data": {"message": "...", "code": "..."}}
-        """
-        await websocket.accept()
-
-        # Each WebSocket session gets its own environment instance
-        ws_env = RangeEnvironment()
-
-        try:
-            while True:
-                raw = await websocket.receive_text()
-                try:
-                    msg = json.loads(raw)
-                except json.JSONDecodeError:
-                    await websocket.send_json({
-                        "type": "error",
-                        "data": {"message": "Invalid JSON", "code": "parse_error"},
-                    })
-                    continue
-
-                msg_type = msg.get("type", "")
-                msg_data = msg.get("data", {})
-
-                if msg_type == "reset":
-                    seed = msg_data.get("seed") if msg_data else msg.get("seed")
-                    episode_id = msg_data.get("episode_id") if msg_data else msg.get("episode_id")
-                    obs = ws_env.reset(seed=seed, episode_id=episode_id)
-                    await websocket.send_json({
-                        "type": "observation",
-                        "data": obs.model_dump(),
-                    })
-
-                elif msg_type == "step":
-                    try:
-                        action = RangeAction(
-                            command=msg_data.get("command", msg.get("command", "")),
-                            mode=msg_data.get("mode", msg.get("mode", "red")),
-                        )
-                    except ValidationError as ve:
-                        await websocket.send_json({
-                            "type": "error",
-                            "data": {"message": str(ve), "code": "validation_error"},
-                        })
-                        continue
-
-                    obs = ws_env.step(action)
-                    await websocket.send_json({
-                        "type": "observation",
-                        "data": obs.model_dump(),
-                    })
-
-                elif msg_type == "state":
-                    await websocket.send_json({
-                        "type": "state",
-                        "data": ws_env.state.model_dump(),
-                    })
-
-                elif msg_type == "close":
-                    await websocket.close()
-                    break
-
-                else:
-                    await websocket.send_json({
-                        "type": "error",
-                        "data": {
-                            "message": f"Unknown message type: {msg_type!r}",
-                            "code": "unknown_type",
-                        },
-                    })
-
-        except WebSocketDisconnect:
-            ws_env.close()
-            logger.debug("WebSocket client disconnected")
-
-    return fastapi_app
-
-
-# ---------------------------------------------------------------------------
-# Module-level app instance (used by uvicorn)
-# ---------------------------------------------------------------------------
-
-
-def create_app() -> FastAPI:
-    """Create the OpenRange FastAPI application.
+def main() -> None:
+    """Run the installed package entrypoint via uvicorn."""
+    import uvicorn
 
-    Tries openenv's create_app first; falls back to standalone.
-    """
-    openenv_app = _try_openenv_app()
-    if openenv_app is not None:
-        return openenv_app
-    return _create_standalone_app()
+    uvicorn.run("open_range.server.app:app", host="0.0.0.0", port=8000)
 
 
 app = create_app()
-
-
-def main() -> None:
-    """Entry point for ``uv run server`` or ``python -m open_range.server``."""
-    import uvicorn
-
-    uvicorn.run(app, host="0.0.0.0", port=8000)

uv.lock

@@ -1870,7 +1870,6 @@ dependencies = [
     { name = "docker" },
     { name = "fastapi" },
     { name = "jinja2" },
-    { name = "litellm" },
     { name = "openenv-core", extra = ["core"] },
     { name = "pydantic" },
     { name = "pyyaml" },
@@ -1878,6 +1877,9 @@ dependencies = [
 ]
 
 [package.optional-dependencies]
+builder = [
+    { name = "litellm" },
+]
 dev = [
     { name = "httpx" },
     { name = "pytest" },
@@ -1894,7 +1896,7 @@ requires-dist = [
     { name = "fastapi", specifier = ">=0.115" },
     { name = "httpx", marker = "extra == 'dev'", specifier = ">=0.27" },
     { name = "jinja2", specifier = ">=3.1" },
-    { name = "litellm", specifier = ">=1.30" },
+    { name = "litellm", marker = "extra == 'builder'", specifier = ">=1.30" },
     { name = "openenv-core", extras = ["core"], specifier = ">=0.2.1" },
     { name = "pydantic", specifier = ">=2.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0" },
@@ -1902,9 +1904,9 @@ requires-dist = [
     { name = "pyyaml", specifier = ">=6.0" },
     { name = "trl", marker = "extra == 'training'", specifier = ">=0.8" },
     { name = "unsloth", marker = "extra == 'training'" },
-    { name = "uvicorn", specifier = ">=0.24" },
+    { name = "uvicorn", specifier = ">=0.27" },
 ]
-provides-extras = ["dev", "training"]
+provides-extras = ["dev", "training", "builder"]
 
 [[package]]
 name = "openai"