nemo_gym.web.browser_session

Browser-supply leases shared by stateful web environments.

The benchmark owns tasks, actions, observations, and evaluation. A browser session provider owns only the lifecycle of the isolated runtime in which the browser executes. Keeping that boundary asynchronous lets a provider acquire an AgentEnv, container, VM, or remote browser without blocking the resources server event loop, while synchronous Playwright operations remain on their session-affine worker thread.

Remote providers should issue expiring leases and renew them from heartbeat. If the Gym process dies, heartbeats stop and provider-side TTL cleanup becomes the final backstop against orphaned training sessions.

Module Contents

Classes

Name	Description
`BrowserSessionError`	A provider could not supply or maintain a usable browser session.
`BrowserSessionHandle`	Opaque provider handle retained until the rollout is released.
`BrowserSessionProvider`	Acquire and release one isolated browser runtime per rollout.
`BrowserSessionSpec`	Provider-neutral request for one rollout-scoped browser runtime.
`LocalProcessBrowserSessionProvider`	Represent the resources-server process and its DISPLAY as one lease.
`RenewableBrowserSessionProvider`	Optional provider extension for renewing an expiring external lease.

Functions

Name	Description
`_entry_point_providers`	-
`_local_instance_pool`	-
`create_browser_session_provider`	Instantiate a provider from a single-key `{name: kwargs}` mapping.
`list_browser_session_providers`	-
`register_browser_session_provider`	Register an in-process provider implementation by configuration name.

Data

BrowserSessionProviderFactory

ENTRY_POINT_GROUP

_PROVIDER_REGISTRY

API

class nemo_gym.web.browser_session.BrowserSessionError()

Bases: RuntimeError

A provider could not supply or maintain a usable browser session.

class nemo_gym.web.browser_session.BrowserSessionHandle(
    session_id: str | None = None,
    provider_name: str | None = None,
    transport: str = 'local_process',
    endpoint: str | None = None,
    metadata: dict[str, typing.Any] = dict(),
    owner_pid: int | None = None,
    provider_state: typing.Any = None
)

Dataclass

Opaque provider handle retained until the rollout is released.

transport describes how the benchmark driver reaches the runtime. The built-in reference runtime uses local_process. Future providers may return agentenv or remote_cdp and pair that lease with a driver that implements the same WebBrowserDriver contract.

The handle is deliberately transport-neutral. Providers may keep their SDK object in provider_state; benchmark code must use only the declared transport, endpoint, and metadata instead of depending on that object.

endpoint

str | None = None

metadata

dict[str, Any] = field(default_factory=dict)

owner_pid

int | None = None

provider_name

str | None = None

session_id

str | None = None

transport

str = 'local_process'

class nemo_gym.web.browser_session.BrowserSessionProvider()

Protocol

Acquire and release one isolated browser runtime per rollout.

Implementations with synchronous SDKs must offload blocking calls with asyncio.to_thread. release must be idempotent. Metered or remote providers must enforce BrowserSessionSpec.lease_ttl_seconds outside the Gym process so a process crash cannot leak the session indefinitely.

name

str

nemo_gym.web.browser_session.BrowserSessionProvider.acquire(
    spec: nemo_gym.web.browser_session.BrowserSessionSpec
) -> nemo_gym.web.browser_session.BrowserSessionHandle

async

nemo_gym.web.browser_session.BrowserSessionProvider.release(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None

async

class nemo_gym.web.browser_session.BrowserSessionSpec(
    metadata: dict[str, str] = dict(),
    provider_options: dict[str, typing.Any] = dict(),
    lease_ttl_seconds: int = 900
)

Dataclass

Provider-neutral request for one rollout-scoped browser runtime.

lease_ttl_seconds

int = 900

metadata

dict[str, str] = field(default_factory=dict)

provider_options

dict[str, Any] = field(default_factory=dict)

class nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider(
    display_env: str = 'DISPLAY'
)

Represent the resources-server process and its DISPLAY as one lease.

The provider itself does not launch Chromium; the visual-browser driver does that on its dedicated thread. The handle records the owning process so a forked child cannot accidentally operate a parent’s Playwright state.

name

= 'local_process'

nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider._require_owner(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None

staticmethod

nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider.acquire(
    spec: nemo_gym.web.browser_session.BrowserSessionSpec
) -> nemo_gym.web.browser_session.BrowserSessionHandle

async

nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider.heartbeat(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None

async

nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider.release(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None

async

class nemo_gym.web.browser_session.RenewableBrowserSessionProvider()

Protocol

Bases: BrowserSessionProvider

Optional provider extension for renewing an expiring external lease.

nemo_gym.web.browser_session.RenewableBrowserSessionProvider.heartbeat(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None

async

nemo_gym.web.browser_session._entry_point_providers() -> dict[str, type[nemo_gym.web.browser_session.BrowserSessionProvider]]

nemo_gym.web.browser_session._local_instance_pool(
    kwargs: typing.Any = {}
) -> nemo_gym.web.browser_session.BrowserSessionProvider

nemo_gym.web.browser_session.create_browser_session_provider(
    config: collections.abc.Mapping[str, typing.Any]
) -> nemo_gym.web.browser_session.BrowserSessionProvider

Instantiate a provider from a single-key {name: kwargs} mapping.

nemo_gym.web.browser_session.list_browser_session_providers() -> list[str]

nemo_gym.web.browser_session.register_browser_session_provider(
    name: str,
    provider_class: typing.Callable[..., nemo_gym.web.browser_session.BrowserSessionProvider],
    override: bool = False
) -> None

nemo_gym.web.browser_session.BrowserSessionProviderFactory = Callable[[Mapping[str, Any]], BrowserSessionProvider]

nemo_gym.web.browser_session.ENTRY_POINT_GROUP = 'nemo_gym.web_browser_session_providers'

nemo_gym.web.browser_session._PROVIDER_REGISTRY: dict[str, Callable[..., BrowserSessionProvider]] = {LocalProcessBrowserSessionProvider.name: LocalProcessBrowserSessionProvider, 'l...