mudgym 0.3.0__py3-none-any.whl

mudgym/__init__.py

@@ -0,0 +1,24 @@
+"""
+MudGym: a reinforcement learning environment for MUD2.
+
+Importing this package registers the Gymnasium env IDs.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from mudgym.envs.factory import make_env, make_parallel_env, make_vector_env
+from mudgym.envs.registration import register_envs as _register_envs
+
+try:
+    __version__ = version("mudgym")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0.dev0"
+
+_register_envs()
+
+__all__ = [
+    "__version__",
+    "make_env",
+    "make_parallel_env",
+    "make_vector_env",
+]

mudgym/actions.py

@@ -0,0 +1,11 @@
+"""Public action vocabulary helpers."""
+
+from mudgym.db.directions import DIRECTION_INDEX_BY_NAME, DIRECTIONS
+
+
+def direction_index(direction: str) -> int:
+    """Return the zero-based action and exit-mask index for a direction."""
+    return DIRECTION_INDEX_BY_NAME[direction]
+
+
+__all__ = ["DIRECTIONS", "direction_index"]

mudgym/connections/config.py

@@ -0,0 +1,17 @@
+import os
+
+DOCKER_IMAGE = os.getenv("DOCKER_IMAGE", "ghcr.io/rolo/mudgym:v0.2.3")
+CONTAINER_PREFIX = "mudgym"
+DEFAULT_DOCKER_EXEC_CONTAINER_NAME = "mud2-boot"
+
+# connection defaults
+DEFAULT_ACCOUNT_ID = "W00000001"
+DEFAULT_PASSWORD = "password"
+
+# first listed in AVAILABLE_CONNECTIONS is default
+AVAILABLE_CONNECTIONS = os.getenv("AVAILABLE_CONNECTIONS", "docker_run,docker_exec")
+
+
+def configured_docker_exec_container_name() -> str:
+    """Return the shared-container name configured for this process."""
+    return os.getenv("MUDGYM_DOCKER_EXEC_CONTAINER_NAME", DEFAULT_DOCKER_EXEC_CONTAINER_NAME)

mudgym/connections/connection.py

@@ -0,0 +1,150 @@
+import re
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import pexpect
+
+from mudgym.connections.prompts import FINAL_COMMAND_MARKER, PromptSpec, State
+from mudgym.connections.state_machine import ConnectionState
+from mudgym.logs import get_logger
+
+logger = get_logger(__name__)
+
+
+class MudConnection:
+    """
+    Base class for managing connections to MUD2 instances.
+
+    The connection lifecycle is managed by the state machine, this class wraps the state machine and allows for
+    different types of transport whilst exposing a (hopefully) easier to deal with API.
+
+    Lifecycle:
+    - reset() -> Get us to the TEA_SIPPED state, ready for an episode to begin.
+    - send_command(command: str) -> tuple[bytes, bool, bool, dict] -> Send a command to the game, receiving the
+      raw response bytes, terminated and incomplete flags and some debug info.
+    - close() -> Close the connection, terminating the child process. Typically you would use reset() instead if you
+      are going to want to reuse the connection to start a new episode (for connections that support it).
+    """
+
+    # initial prompt we expect to see - subclasses can override
+    initial_prompt: PromptSpec | None = None
+
+    # the end of turn marker closing each step's read window: the pattern identifying the response of the batch's
+    # final command. This class attribute is the protocol's one declared default (fei's ======== divider), which
+    # keeps a bare connection usable on its own; the session overrides it per instance with whatever marker the
+    # env's batch actually ends with.
+    end_of_turn_marker: re.Pattern = FINAL_COMMAND_MARKER
+
+    def __init__(
+        self,
+        *,
+        account_id: str = "",
+        password: str = "",
+        persona_slot: int | None = None,
+        db_slot: int | None = None,
+        name_generator: Callable[[], str] | None = None,
+    ):
+        # I'm not convinced we actually need many of these anymore, but they're here for now.
+        self.account_id = account_id
+        self.password = password
+        self.persona_slot = persona_slot
+        self.db_slot = db_slot
+        self.name_generator = name_generator
+
+        # our state machine instance, that does most of the heavy lifting
+        self.sm: ConnectionState | None = None
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """
+        Check if the connection is available to use in the current environment. Subclasses can override this method to
+        perform a check specific to the connection type. This is to help with experimenting with different connections
+        types.
+        """
+        logger.debug("connection.is_available.default", connection_class=cls.__name__)
+        return True
+
+    def spawn(self) -> pexpect.spawn:
+        """
+        The method that does the actual connecting by spawning and returning our child process.
+        """
+        return pexpect.spawn(
+            self.command[0],
+            self.command[1:] if len(self.command) > 1 else [],
+            encoding=None,
+            use_poll=True,  # poll() instead of select() to avoid FD_SETSIZE limit
+        )
+
+    def reset(self) -> None:
+        """
+        Resets the connection to be ready to start a new episode (TEA_SIPPED state).
+
+        This tells us the `MudConnection` is ready but the `MudEnv` has its own `reset()` steps afterwards that does
+        episode related things that don't make sense here, like issuing commands to set up the initial environment state
+        (eg, score) and running start of episode autocommands and taking the northwards step outside of the tearoom.
+
+        I can imagine a situation with multiple `MudConnection`s waiting on each other after `reset()` to be ready so it
+        seemed negligent to leave agents hanging around outside of the sanctity of the Tearoom where they might get
+        attacked by mobiles or something.
+        """
+
+        # do we need to respawn the process or can we reuse via some menu choices?
+        needs_respawn = self.sm is None or not self.sm.isalive()
+        logger.debug(
+            "connection.reset.start",
+            sm_state=self.sm.state.name if self.sm is not None else None,
+            needs_respawn=needs_respawn,
+        )
+
+        if self.sm is not None and self.sm.isalive():
+            # reset-quit: leave The Land but stay in the mudlogin menu if our connection type
+            # supports that (ie, not a quicklogin, which exits to DEAD)
+            self.sm.quit()
+
+            if self.sm.state == State.DEAD:
+                needs_respawn = True
+
+        if needs_respawn:
+            logger.debug("connection.reset.spawn")
+            child = self.spawn()
+            self.sm = ConnectionState(
+                child=child,
+                account_id=self.account_id,
+                password=self.password,
+                persona_slot=self.persona_slot,
+                db_slot=self.db_slot,
+                name_generator=self.name_generator,
+                initial_prompt=self.initial_prompt,
+                end_of_turn_marker=self.end_of_turn_marker,
+            )
+
+        # OPTION -> persona selection/creation -> TEAROOM -> sip tea -> TEA_SIPPED
+        logger.debug("connection.reset.continue_until_tea", sm_state=self.sm.state.name)
+        self.sm.continue_until(State.TEA_SIPPED)
+        logger.debug(
+            "connection.reset.complete",
+            sm_state=self.sm.state.name,
+            last_prompt=self.sm.last_prompt.name if self.sm.last_prompt else None,
+        )
+
+    def send_command(self, command: str | Sequence[str]) -> tuple[bytes, bool, bool, dict[str, Any]]:
+        """
+        Send a command batch (one wire line, or several when the caller split it) and return the
+        raw response bytes, terminated/incomplete flags, and debug info.
+        """
+        if self.sm is None:
+            raise RuntimeError("Connection has not been reset, call reset() first.")
+        lines = [command] if isinstance(command, str) else list(command)
+        if not lines:
+            raise ValueError("send_command requires at least one command line; got an empty batch")
+        return self.sm.send_command(lines)
+
+    def close(self):
+        if self.sm is None:
+            return
+        try:
+            if self.sm.isalive():
+                self.sm.quit()
+        finally:
+            self.sm.close()
+            self.sm = None

mudgym/connections/docker_exec.py

@@ -0,0 +1,152 @@
+import subprocess
+from collections.abc import Callable
+
+from mudgym.connections.config import (
+    DEFAULT_ACCOUNT_ID,
+    DEFAULT_PASSWORD,
+    DOCKER_IMAGE,
+    configured_docker_exec_container_name,
+)
+from mudgym.connections.connection import MudConnection
+from mudgym.connections.docker_image import ensure_docker_image
+from mudgym.connections.prompts import Prompt, PromptSpec
+from mudgym.logs import get_logger
+
+logger = get_logger(__name__)
+
+
+class DockerExecConnection(MudConnection):
+    """
+    MUD2 connection that execs into an existing Docker container.
+
+    Typically for using a single container running with multiple game slots, or when connecting
+    multiple clients to the same game slot.
+    """
+
+    initial_prompt: PromptSpec = [
+        Prompt.OPTION,
+        Prompt.SUPERSEDE,
+        Prompt.SESSION_DYING,
+    ]
+
+    def __init__(
+        self,
+        container_name: str | None = None,
+        container_id: str | None = None,
+        start_if_missing: bool = True,
+        container_image: str = DOCKER_IMAGE,
+        *,
+        use_tty: bool = True,
+        account_id: str = DEFAULT_ACCOUNT_ID,
+        password: str = DEFAULT_PASSWORD,
+        persona_slot: int | None = None,
+        db_slot: int | None = None,
+        name_generator: Callable[[], str] | None = None,
+    ):
+        container_name = container_name if container_name is not None else configured_docker_exec_container_name()
+        # if container_id is not provided, find the first container with the given prefix
+        self.container_image = container_image
+        self.container_name = container_name
+        # track whether we started the container and own the lifecycle
+        self._started_container = False
+        self.container_id = container_id or self.find_container_id(container_name, start_if_missing)
+        self.use_tty = use_tty
+
+        super().__init__(
+            account_id=account_id,
+            password=password,
+            persona_slot=persona_slot,
+            db_slot=db_slot,
+            name_generator=name_generator,
+        )
+        self.command = self.build_command()
+
+    def find_container_id(self, name: str, start_if_missing: bool = True) -> str:
+        """Find container ID by name."""
+        out = subprocess.check_output(["docker", "ps", "-qf", f"name={name}"], text=True).strip()
+        if out:
+            # if multiple lines, pick first:
+            return out.splitlines()[0]
+        if start_if_missing:
+            logger.debug("docker.container.not_found", name=name, start_if_missing=start_if_missing)
+            return self.start_container()
+        raise RuntimeError(f"No running container matches name={name}; start_if_missing={start_if_missing}")
+
+    def start_container(self, slots: int = 1) -> str:
+        """Start a new container and return the container ID."""
+        ensure_docker_image(self.container_image)
+        output = subprocess.check_output(
+            [
+                "docker",
+                "run",
+                "--init",
+                "--rm",
+                "-d",
+                #'--ipc="private"',
+                "--name",
+                self.container_name,
+                self.container_image,
+                "/bin/sh",
+                "-lc",
+                f"/app/bin/boot -n {slots} -f -k",
+            ],
+            text=True,
+        ).strip()
+
+        # docker run -d prints the container ID on stdout
+        container_id = output.splitlines()[-1] if output else ""
+        if not container_id:
+            raise RuntimeError(f"docker run did not return a container id for {self.container_name}")
+
+        logger.debug("docker.container.started", container_id=container_id)
+        self.container_id = container_id
+        self._started_container = True
+        return self.container_id
+
+    def build_command(self) -> list[str]:
+        cmd = [
+            "docker",
+            "exec",
+        ]
+
+        # only add TTY flag if we have a TTY (needed for GitHub Actions)
+        if self.use_tty:
+            cmd.append("-it")
+        else:
+            cmd.append("-i")
+
+        cmd.extend(
+            [
+                "-e",
+                f"L0={self.account_id}",
+                "-e",
+                f"L1={self.password}",
+            ]
+        )
+
+        cmd.extend([self.container_id, "/app/bin/mudlogin", "-n"])
+
+        return cmd
+
+    def close(self):
+        """Close the exec session, and remove the container if this connection started it.
+
+        We only tear down the container we own (one we started because none was running). A
+        pre-existing, shared container is left alone so other clients exec'd into it survive.
+        """
+        super().close()
+
+        if not self._started_container:
+            return
+
+        try:
+            subprocess.run(
+                ["docker", "rm", "-f", self.container_name],
+                capture_output=True,
+                check=False,  # Don't raise if the container is already gone
+            )
+            logger.debug("docker.container.removed", container_name=self.container_name)
+        except Exception as e:
+            logger.debug("docker.container.remove.failed", container_name=self.container_name, error=str(e))
+        finally:
+            self._started_container = False

mudgym/connections/docker_image.py

@@ -0,0 +1,98 @@
+"""Fail-fast Docker preflight shared by the Docker-backed connections.
+
+An uncached image pull can never fit inside the game's first-prompt timeout,
+so the image must be present before any container spawns. This module makes
+each failure mode explicit instead of surfacing a raw pexpect timeout: no
+Docker binary, an unreachable daemon, a registry that refuses access, and a
+tag that does not exist.
+"""
+
+import shutil
+import subprocess
+
+from mudgym.logs import get_logger
+
+logger = get_logger(__name__)
+
+INSPECT_TIMEOUT_SECONDS = 30
+PULL_TIMEOUT_SECONDS = 600
+
+# Images verified once per process; repeated spawns skip the inspect subprocess.
+_verified_images: set[str] = set()
+
+
+class DockerSetupError(RuntimeError):
+    """Docker or the game image is unusable; the message says how to fix it."""
+
+
+def ensure_docker_image(image_name: str) -> None:
+    """Make sure ``image_name`` is usable locally, pulling it on first use."""
+    if image_name in _verified_images:
+        return
+
+    docker = shutil.which("docker")
+    if docker is None:
+        raise DockerSetupError(
+            "Docker is required to run the MudGym game but no `docker` executable was found on PATH. "
+            "Install Docker (https://docs.docker.com/get-docker/) and try again."
+        )
+
+    try:
+        inspect = subprocess.run(
+            [docker, "image", "inspect", image_name],
+            capture_output=True,
+            text=True,
+            timeout=INSPECT_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired as error:
+        raise DockerSetupError(
+            f"Docker did not answer `docker image inspect` within {INSPECT_TIMEOUT_SECONDS}s. "
+            "Check that the Docker daemon is healthy and try again."
+        ) from error
+
+    if inspect.returncode != 0:
+        inspect_error = inspect.stderr.strip()
+        lowered = inspect_error.lower()
+        # A missing image also mentions the daemon ("Error response from daemon:
+        # No such image"), so only treat connection failures as daemon-down.
+        if "cannot connect" in lowered or "is the docker daemon running" in lowered:
+            raise DockerSetupError(
+                f"Docker is installed but its daemon is not reachable: {inspect_error} Start Docker and try again."
+            )
+        _pull_image(docker, image_name)
+
+    _verified_images.add(image_name)
+
+
+def _pull_image(docker: str, image_name: str) -> None:
+    logger.info("docker.image.pull.start", image=image_name)
+    try:
+        pull = subprocess.run(
+            [docker, "pull", image_name],
+            capture_output=True,
+            text=True,
+            timeout=PULL_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired as error:
+        raise DockerSetupError(
+            f"Pulling the MudGym game image {image_name!r} did not finish within "
+            f"{PULL_TIMEOUT_SECONDS}s. Check your network connection and try again, or run "
+            f"`docker pull {image_name}` yourself to watch its progress."
+        ) from error
+
+    if pull.returncode == 0:
+        logger.info("docker.image.pull.done", image=image_name)
+        return
+
+    pull_error = pull.stderr.strip()
+    lowered = pull_error.lower()
+    if "denied" in lowered or "unauthorized" in lowered or "authentication" in lowered:
+        detail = (
+            "The registry refused access to it. If this is a released MudGym version the image is "
+            "public and no login is needed, so check for a stale `docker login ghcr.io` credential."
+        )
+    elif "manifest unknown" in lowered or "not found" in lowered:
+        detail = "That tag does not exist on the registry, so check the image name and tag."
+    else:
+        detail = "Check your network connection and the Docker daemon logs."
+    raise DockerSetupError(f"Could not pull the MudGym game image {image_name!r}. {detail}\nDocker said: {pull_error}")

mudgym/connections/docker_run.py

@@ -0,0 +1,95 @@
+import subprocess
+import uuid
+from collections.abc import Callable
+
+import pexpect
+
+from mudgym.connections.config import (
+    CONTAINER_PREFIX,
+    DEFAULT_ACCOUNT_ID,
+    DEFAULT_PASSWORD,
+    DOCKER_IMAGE,
+)
+from mudgym.connections.connection import MudConnection
+from mudgym.connections.docker_image import ensure_docker_image
+from mudgym.connections.prompts import Prompt, PromptSpec
+from mudgym.logs import get_logger
+
+logger = get_logger(__name__)
+
+
+class DockerRunConnection(MudConnection):
+    """
+    Docker run connection.
+
+    Spins up a new container via `docker run` for each connection.
+    """
+
+    initial_prompt: PromptSpec = Prompt.OPTION
+
+    def __init__(
+        self,
+        container_name: str | None = None,
+        image_name: str | None = DOCKER_IMAGE,
+        use_tty: bool = True,
+        *,
+        account_id: str = DEFAULT_ACCOUNT_ID,
+        password: str = DEFAULT_PASSWORD,
+        persona_slot: int | None = None,
+        db_slot: int | None = None,
+        name_generator: Callable[[], str] | None = None,
+    ):
+        super().__init__(
+            account_id=account_id,
+            password=password,
+            persona_slot=persona_slot,
+            db_slot=db_slot,
+            name_generator=name_generator,
+        )
+
+        # generate unique container name if not provided
+        self.container_name = container_name or f"{CONTAINER_PREFIX}_{uuid.uuid4().hex}"
+        self.image_name = image_name
+        self.use_tty = use_tty
+
+        self.command = self.build_command()
+
+    def build_command(self) -> list[str]:
+        return [
+            "docker",
+            "run",
+            "--name",
+            self.container_name,
+            "--init",
+            "--rm",
+            "-it" if self.use_tty else "-i",
+            "--ipc=private",
+            "--shm-size=100mb",
+            "-e",
+            f"L0={self.account_id}",
+            "-e",
+            f"L1={self.password}",
+            self.image_name,
+        ]
+
+    def cleanup_container(self) -> None:
+        """Remove any existing container with our name to avoid conflicts.
+
+        This handles the case where a previous container wasn't properly cleaned up,
+        e.g., if the process was killed abruptly or marimo re-ran a cell.
+        """
+        try:
+            subprocess.run(
+                ["docker", "rm", "-f", self.container_name],
+                capture_output=True,
+                check=False,  # Don't raise if container doesn't exist
+            )
+            logger.debug("docker.container.cleanup", container_name=self.container_name)
+        except Exception as e:
+            logger.debug("docker.container.cleanup.failed", container_name=self.container_name, error=str(e))
+
+    def spawn(self) -> pexpect.spawn:
+        """Spawn the Docker container, ensuring any stale container is cleaned up first."""
+        ensure_docker_image(self.image_name)
+        self.cleanup_container()
+        return super().spawn()

mudgym/connections/persona.py

@@ -0,0 +1,47 @@
+"""
+Handles persona selection and creation logic.
+"""
+
+import re
+
+from faker import Faker
+
+from mudgym.featurizers.strings import decode_text_bytes
+from mudgym.logs import get_logger
+
+logger = get_logger(__name__)
+
+faker = Faker()
+
+# the game rejects persona names longer than this or containing anything non-alphabetic
+# ("Use names of 10 characters at most, please")
+PERSONA_NAME_MAX_LENGTH = 10
+
+PERSONA_NAME_BLACKLIST = [
+    "richard",
+]
+
+
+def parse_persona_screen(text: bytes) -> dict[int, str]:
+    """Extract persona names from persona selection text."""
+    text_str = decode_text_bytes(text)
+    # names are only ever max 10 characters and dont include punctuation, whitespace or non alpha chars
+    # TODO: tighten up this regex to only include valid persona names and make it operate on bytestrings
+    pattern = r"\((\d+)\)\s+([A-Za-z][\w'-]{0,9}|\*\*Unused\*\*)(?:,|\.|$)"
+    matches = re.findall(pattern, text_str)
+    return {int(num): name for num, name in matches}
+
+
+def generate_persona_name() -> str:
+    # the game rejects names longer than PERSONA_NAME_MAX_LENGTH or containing anything
+    # non-alphabetic, and faker first names can be hyphenated or accented ("Anne-Marie",
+    # "Renée"), which would wedge persona creation at the name prompt
+    name = ""
+    while (
+        not name.isascii()
+        or not name.isalpha()
+        or len(name) > PERSONA_NAME_MAX_LENGTH
+        or name.lower() in PERSONA_NAME_BLACKLIST
+    ):
+        name = faker.first_name()
+    return name