mudgym 0.3.0b1__tar.gz

mudgym-0.3.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rolo Mawlabaux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mudgym-0.3.0b1/NOTICE

@@ -0,0 +1,13 @@
+MudGym
+Copyright (c) 2026 Rolo Mawlabaux
+
+The Python code and tooling are made available under the MIT License (see
+LICENSE).
+
+Permission to use the MUD2 game for research purposes has been provided by
+Richard Bartle, with kind thanks. The MUD2 game, name, source code, and
+associated story remain the intellectual property of Richard Bartle and
+Roy Trubshaw and may not be used for commercial purposes.
+
+MudGym runs the MUD2 game inside the ghcr.io/rolo/mudgym Docker image; the
+image is pulled at runtime and is not part of this distribution.

mudgym-0.3.0b1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: mudgym
+Version: 0.3.0b1
+Summary: Reinforcement learning environment for MUD2.
+Keywords: reinforcement-learning,gymnasium,pettingzoo,multi-agent,mud,mud2,text-adventure,llm-agents
+Author: Rolo Mawlabaux
+Author-email: Rolo Mawlabaux <rolo@kingrolo.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: POSIX
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Games/Entertainment :: Multi-User Dungeons (MUD)
+Requires-Dist: ansi2html>=1.9.2
+Requires-Dist: faker>=37.12.0
+Requires-Dist: gymnasium>=1.2.2
+Requires-Dist: pexpect>=4.9.0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: pettingzoo>=1.25.0
+Requires-Python: >=3.13
+Project-URL: Documentation, https://rolo.github.io/mudgym/
+Project-URL: Homepage, https://rolo.github.io/mudgym/
+Project-URL: Issues, https://github.com/rolo/mudgym/issues
+Project-URL: Repository, https://github.com/rolo/mudgym
+Description-Content-Type: text/markdown
+
+# MudGym
+
+A Gymnasium reinforcement learning environment for MUD2. One of the first online multiplayer text adventure games.
+
+## Setup 
+
+A Docker engine is required to run the game. The image `ghcr.io/rolo/mudgym` is pulled automatically on first use.
+
+Install MudGym from PyPI:
+
+```bash
+uv add mudgym
+```
+
+## Quickstart
+
+```python
+from mudgym import make_env
+
+env = make_env(observation="parsed")
+observation, info = env.reset()
+observation, reward, terminated, truncated, info = env.step("howl")
+print(observation["room_name"], reward)
+env.close()
+```
+
+## Docs
+
+See the [docs](https://rolo.github.io/mudgym/) for more examples.
+
+## License
+
+The Python code and tooling in this repository are made available under the MIT License.
+
+Permission to use the MUD2 game for research purposes has been provided by Richard Bartle, with kind thanks. The MUD2 game, name, source code, and associated story remain the intellectual property of Richard Bartle and Roy Trubshaw and may not be used for commercial purposes.

mudgym-0.3.0b1/README.md

@@ -0,0 +1,35 @@
+# MudGym
+
+A Gymnasium reinforcement learning environment for MUD2. One of the first online multiplayer text adventure games.
+
+## Setup 
+
+A Docker engine is required to run the game. The image `ghcr.io/rolo/mudgym` is pulled automatically on first use.
+
+Install MudGym from PyPI:
+
+```bash
+uv add mudgym
+```
+
+## Quickstart
+
+```python
+from mudgym import make_env
+
+env = make_env(observation="parsed")
+observation, info = env.reset()
+observation, reward, terminated, truncated, info = env.step("howl")
+print(observation["room_name"], reward)
+env.close()
+```
+
+## Docs
+
+See the [docs](https://rolo.github.io/mudgym/) for more examples.
+
+## License
+
+The Python code and tooling in this repository are made available under the MIT License.
+
+Permission to use the MUD2 game for research purposes has been provided by Richard Bartle, with kind thanks. The MUD2 game, name, source code, and associated story remain the intellectual property of Richard Bartle and Roy Trubshaw and may not be used for commercial purposes.

mudgym-0.3.0b1/pyproject.toml

@@ -0,0 +1,98 @@
+[project]
+name = "mudgym"
+version = "0.3.0b1"
+description = "Reinforcement learning environment for MUD2."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+authors = [
+    { name = "Rolo Mawlabaux", email = "rolo@kingrolo.com" }
+]
+requires-python = ">=3.13"
+keywords = [
+    "reinforcement-learning",
+    "gymnasium",
+    "pettingzoo",
+    "multi-agent",
+    "mud",
+    "mud2",
+    "text-adventure",
+    "llm-agents",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    # pexpect is POSIX-only, so the game connection does not work on Windows.
+    "Operating System :: POSIX",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Games/Entertainment :: Multi-User Dungeons (MUD)",
+]
+dependencies = [
+    "ansi2html>=1.9.2",
+    "faker>=37.12.0",
+    "gymnasium>=1.2.2",
+    "pexpect>=4.9.0",
+    "structlog>=25.5.0",
+    "numpy>=2.3.4",
+    "pettingzoo>=1.25.0",
+]
+
+[project.urls]
+Homepage = "https://rolo.github.io/mudgym/"
+Documentation = "https://rolo.github.io/mudgym/"
+Repository = "https://github.com/rolo/mudgym"
+Issues = "https://github.com/rolo/mudgym/issues"
+
+[dependency-groups]
+docs = [
+  "zensical>=0.0.44",
+  "mkdocstrings-python>=2.0.4",
+]
+dev = [
+  "ruff>=0.14.3",
+  "pytest>=8.0.0",
+  "pytest-cov>=6.0.0",
+  "pytest-subtests>=0.15.0",
+  "ipdb>=0.13.13",
+  "tabulate>=0.10.0",
+  {include-group = "docs"},
+]
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# leave test modules out of the published artifacts
+source-exclude = ["**/tests", "**/tests/**"]
+wheel-exclude = ["**/tests", "**/tests/**"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = ["PLC0415", "I", "UP", "SIM", "C4", "PIE", "RET"]
+# assertions read better as expected-then-actual, which SIM300 calls a Yoda condition
+ignore = ["SIM300"]
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+relative_files = true
+omit = [
+    "*/tests/*",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src/mudgym"]
+log_cli_format = "%(asctime)s %(levelname)-7s %(message)s"
+log_cli_date_format = "%H:%M:%S"
+markers = [
+  "soak: long-running live-game soak tests; excluded by default, run with -m soak",
+]
+addopts = "-m 'not soak'"

mudgym-0.3.0b1/src/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-0.3.0b1/src/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-0.3.0b1/src/mudgym/connections/config.py

@@ -0,0 +1,17 @@
+import os
+
+DOCKER_IMAGE = os.getenv("DOCKER_IMAGE", "ghcr.io/rolo/mudgym:v0.1")
+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-0.3.0b1/src/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-0.3.0b1/src/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