Core API¶

Core enums and data structures used throughout MOSAIC.

Enums¶

SteppingParadigm¶

class gym_gui.core.enums.SteppingParadigm(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Defines how RL agents interact with the environment.

This enum describes the stepping model - how actions are collected and applied. It is orthogonal to ControlMode (who controls) and EnvironmentFamily (library).

NOTE: This enum is for RL training paradigms ONLY. Non-RL systems like MuJoCo MPC (optimal control) are managed separately by gym_gui/services/mujoco_mpc_controller/.

WorkerCapabilities¶

class gym_gui.core.adapters.base.WorkerCapabilities(stepping_paradigm: SteppingParadigm, supported_paradigms: tuple[SteppingParadigm, ...] = (), env_types: tuple[str, ...] = ('gymnasium',), action_spaces: tuple[str, ...] = ('discrete',), observation_spaces: tuple[str, ...] = ('box',), max_agents: int = 1, supports_self_play: bool = False, supports_population: bool = False, supports_record: bool = False, supports_fast_reset: bool = False, max_fps: float | None = None, requires_gpu: bool = False, gpu_memory_mb: int | None = None, cpu_cores: int = 1)[source]

Declares what stepping paradigms and features a worker/adapter supports.

This dataclass is used by the WorkerOrchestrator to: 1. Match environments to compatible workers 2. Configure paradigm-specific stepping behavior 3. Validate worker compatibility before launching runs

stepping_paradigm

Primary stepping model (SINGLE_AGENT, SEQUENTIAL, etc.)

Type:: gym_gui.core.enums.SteppingParadigm

supported_paradigms

All paradigms this worker can handle.

Type:: tuple[gym_gui.core.enums.SteppingParadigm, …]

env_types

Environment types supported (e.g., [“gymnasium”, “pettingzoo”]).

Type:: tuple[str, …]

action_spaces

Action space types supported (e.g., [“discrete”, “continuous”]).

Type:: tuple[str, …]

observation_spaces

Observation space types supported (e.g., [“box”, “dict”]).

Type:: tuple[str, …]

max_agents

Maximum number of agents (1 for single-agent).

Type:: int

supports_self_play

Whether worker can train via self-play.

Type:: bool

supports_population

Whether worker supports population-based training.

Type:: bool

supports_record

Whether worker supports recording episodes.

Type:: bool

supports_fast_reset

Whether worker supports fast environment reset.

Type:: bool

max_fps

Target frame rate for continuous paradigms (None for turn-based).

Type:: float | None

requires_gpu

Whether GPU is required.

Type:: bool

gpu_memory_mb

Estimated GPU memory requirement in MB.

Type:: int | None

cpu_cores

Recommended CPU cores.

Type:: int

Example

>>> caps = WorkerCapabilities(
...     stepping_paradigm=SteppingParadigm.SINGLE_AGENT,
...     env_types=["gymnasium"],
...     action_spaces=["discrete", "continuous"],
...     max_agents=1,
... )

action_spaces: tuple[str, ...] = ('discrete',)

cpu_cores: int = 1

env_types: tuple[str, ...] = ('gymnasium',)

gpu_memory_mb: int | None = None

is_multi_agent() → bool[source]: Check if this worker supports multi-agent environments.

max_agents: int = 1

max_fps: float | None = None

observation_spaces: tuple[str, ...] = ('box',)

requires_gpu: bool = False

stepping_paradigm: SteppingParadigm

supported_paradigms: tuple[SteppingParadigm, ...] = ()

supports_action_space(space_type: str) → bool[source]: Check if this worker supports the given action space type.

supports_env_type(env_type: str) → bool[source]: Check if this worker supports the given environment type.

supports_fast_reset: bool = False

supports_paradigm(paradigm: SteppingParadigm) → bool[source]: Check if this worker supports the given stepping paradigm.

supports_population: bool = False

supports_record: bool = False

supports_self_play: bool = False

UI Widgets¶

Note

Qt widget classes cannot be auto-documented by Sphinx in a headless environment. The API signatures below are maintained manually.

PlayerAssignmentPanel¶

class gym_gui.ui.widgets.operator_config_widget.PlayerAssignmentPanel(env_family, env_id, num_agents, agent_ids=None, agent_labels=None, parent=None)¶

Panel showing all agent/player assignments for a multi-agent environment. Contains one PlayerAssignmentRow per agent slot.

assignments_changed: pyqtSignal¶: Emitted when any player assignment row changes (type, worker, or settings).

get_worker_assignments() → Dict[str, WorkerAssignment]¶: Return a dict mapping each player_id to its WorkerAssignment.

has_llm_agent() → bool¶: Return True if at least one agent row has Type set to LLM.

set_vllm_servers(servers)¶: Propagate the current list of vLLM servers to every row.

PlayerAssignmentRow¶

class gym_gui.ui.widgets.operator_config_widget.PlayerAssignmentRow(player_id, player_label, parent=None)¶

Single row inside a PlayerAssignmentPanel. Exposes a Type dropdown (LLM / RL / Human / Random), a Worker dropdown, and type-specific settings (LLM provider/model, RL policy path, etc.).

assignment_changed: pyqtSignal¶: Emitted when the user changes any field in this row.

get_assignment() → WorkerAssignment¶: Build and return a WorkerAssignment from the current UI state. The Random type is mapped to worker_type="baseline" with behavior="random".

OperatorConfigWidget¶

class gym_gui.ui.widgets.operator_config_widget.OperatorConfigWidget(operator_id, parent=None)¶

Per-operator configuration widget. For multi-agent environments it creates a PlayerAssignmentPanel and an environment-specific settings section (observation mode, coordination strategy for MultiGrid / MeltingPot).

get_config() → OperatorConfig¶: Build an OperatorConfig from the current UI state (single-agent or multi-agent depending on the selected environment).