mettagrid 0.2.0.12__tar.gz → 0.2.0.16__tar.gz

mettagrid-0.2.0.16/.gitignore

@@ -0,0 +1,7 @@
+# ignore build artifacts
+/build-debug
+/build-release
+/benchmark_output
+/Testing
+
+MODULE.bazel.lock

mettagrid-0.2.0.16/MODULE.bazel

@@ -0,0 +1,39 @@
+# MODULE.bazel for mettagrid - using Bzlmod (modern Bazel module system)
+module(name = "mettagrid", version = "0.1.6")
+
+# Basic Bazel dependencies
+bazel_dep(name = "platforms", version = "1.0.0")
+bazel_dep(name = "bazel_skylib", version = "1.8.1")
+
+# C++ rules and toolchain
+bazel_dep(name = "rules_cc", version = "0.2.0")
+
+# Python toolchain - use latest compatible version
+bazel_dep(name = "rules_python", version = "1.5.3")
+
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(
+    python_version = "3.11",
+    python_version_env = "METTAGRID_BAZEL_PYTHON_VERSION",
+)
+python.toolchain(
+    python_version = "3.11",
+)
+python.toolchain(
+    python_version = "3.12",
+)
+python.toolchain(
+    python_version = "3.13",
+)
+
+# pybind11 for Python bindings
+bazel_dep(name = "pybind11_bazel", version = "2.13.6")
+
+# Google Test for testing
+bazel_dep(name = "googletest", version = "1.17.0")
+
+# Google Benchmark for benchmarking
+bazel_dep(name = "google_benchmark", version = "1.9.4")
+
+# Abseil (dependency of some Google libraries)
+bazel_dep(name = "abseil-cpp", version = "20250814.0")

mettagrid-0.2.0.16/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: mettagrid
+Version: 0.2.0.16
+Summary: A fast grid-based open-ended MARL environment
+Author-email: David Bloomin <daveey@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://daveey.github.io
+Project-URL: Repository, https://github.com/Metta-AI/mettagrid
+Keywords: gridworld,minigrid,rl,reinforcement-learning,environment,gym
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.38.32
+Requires-Dist: botocore>=1.38.29
+Requires-Dist: gymnasium>=1.1.1
+Requires-Dist: pettingzoo>=1.25
+Requires-Dist: pufferlib-core
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pyyaml>=6.0.2
+Dynamic: license-file
+
+# MettaGrid Environment
+
+MettaGrid is a multi-agent gridworld environment for studying the emergence of cooperation and social behaviors in
+reinforcement learning agents. The environment features a variety of objects and actions that agents can interact with
+to manage resources, engage in combat, share with others, and optimize their rewards.
+
+## Overview
+
+In MettaGrid, agents navigate a gridworld and interact with various objects to manage their energy, harvest resources,
+engage in combat, and cooperate with other agents. The key dynamics include:
+
+- **Energy Management**: Agents must efficiently manage their energy, which is required for all actions. They can
+  harvest resources and convert them to energy at charger stations.
+- **Resource Gathering**: Agents can gather resources from generator objects scattered throughout the environment.
+- **Cooperation and Sharing**: Agents have the ability to share resources with other agents and use energy to power the
+  heart altar, which provides rewards.
+- **Combat**: Agents can attack other agents to temporarily freeze them and steal their resources. They can also use
+  shields to defend against attacks.
+
+The environment is highly configurable, allowing for experimentation with different world layouts, object placements,
+and agent capabilities.
+
+## Objects
+
+### Agent
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_monsters/tg_monsters_astronaut_u1.png?raw=true" width="32"/>
+
+The `Agent` object represents an individual agent in the environment. Agents can move, rotate, attack, and interact with
+other objects. Each agent has energy, resources, and shield properties that govern its abilities and interactions.
+
+### Altar
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_items/tg_items_heart_full.png?raw=true" width="32"/>
+
+The `Altar` object allows agents to spend energy to gain rewards. Agents can power the altar by using the `use` action
+when near it. The altar has a cooldown period between uses.
+
+- Using the heart altar costs `altar.use_cost energy`. So, no matter how much energy you have, you are always dumping
+  the same amount of energy in it and getting the same amount of reward.
+- After the heart altar is used, it is unable to be used for altar.cooldown timesteps.
+- A single use of the heart altar gives you a single unit of reward: if
+  `target._type_id == ObjectType.AltarT: self.env._rewards[actor_id] += 1`
+
+### Converter
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_items/tg_items_pda_A.png?raw=true" width="32"/>
+
+The `Converter` object allows agents to convert their harvested resources into energy. Agents can use converters by
+moving to them and taking the `use` action. Each use of a converter provides a specified amount of energy and has a
+cooldown period.
+
+- Using the converter does not cost any energy.
+- Using the converter outputs `converter.energy_output.r1` energy
+  - see `this.output_energy = cfg[b"energy_output.r1"]` in the Converter cppclass
+- Using the converter increments resource 2 by one and decrements resource 1 by 1
+- There is currently no use for `converter.energy_output.r2` and `converter.energy_output.r3`
+- After the converter is used, it is unable to be used for `converter.cooldown` timesteps
+
+### Generator
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_fantasy/ore-0.png?raw=true" width="32"/>
+
+The `Generator` object produces resources that agents can harvest. Agents can gather resources from generators by moving
+to them and taking the `use` action. Generators have a specified capacity and replenish resources over time.
+
+- Using the generator once gives one resource 1
+- After the generator is used, it is unable to be used for `generator.cooldown` timesteps
+
+### Wall
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_fantasy/wall2-0.png?raw=true" width="32"/>
+
+The `Wall` object acts as an impassable barrier in the environment, restricting agent movement.
+
+### Cooldown
+
+The `cooldown` property determines how long before objects can be used again.
+
+## Actions
+
+### Move / Rotate
+
+The `move` action allows agents to move to an adjacent cell in the gridworld. The action has two modes: moving forward
+and moving backward relative to the agent's current orientation.
+
+The `rotate` action enables agents to change their orientation within the gridworld. Agents can rotate to face in four
+directions: down, left, right, and up.
+
+### Attack
+
+The `attack` action allows agents to attack other agents or objects within their attack range. Successful attacks freeze
+the target for `freeze_duration` timesteps and allow the attacker to steal resources. Further, the attacked agent's
+energy is set to `0`. Attacks have a cost and inflict a damage value. The agent selects from one of nine coordinates
+within its attack range.
+
+### Shield (Toggle)
+
+The `shield` action turns on a shield. When the shield is active, the agent is protected from attacks by other agents.
+The shield consumes energy defined by `upkeep.shield` while active. Attack damage is subtracted from the agent's energy,
+rather than freezing the agent.
+
+### Transfer
+
+The `transfer` action enables agents to share resources with other agents. Agents can choose to transfer specific
+resources to another agent in an adjacent cell. It is currently not implemented.
+
+### Use
+
+The `use` action allows agents to interact with objects such as altars, converters, and generators. The specific effects
+of the `use` action depend on the target object and can include converting resources to energy, powering the altar for
+rewards, or harvesting resources from generators.
+
+### Swap
+
+The `swap` action allows agents to swap positions with other agents. It is currently not implemented.
+
+## Configuration
+
+The MettaGrid environment is highly configurable through the use of YAML configuration files. These files specify the
+layout of the gridworld, the placement of objects, and various properties of the objects and agents.
+
+**Current settings:**
+
+1. Ore   - Base resource obtained from mines. Mines produce one ore when used. No resource requirements for use.   -
+   Reward value: 0.005 per unit (max 2)   - Used to create batteries and lasers
+2. Battery   - Intermediate resource created from ore at a generator. Generator turns one ore into one battery.   -
+   Reward value: 0.01 per unit (max 2)   - Used to create hearts and lasers
+3. Heart / heart altar   - High value reward, requires 3 batteries to be converted into a heart at a heart altar.
+4. Laser   - Weapon resource created from ore and batteries. Requires 1 ore and 2 batteries. Created at the lasery.
+
+- Consumed on use. When hitting an unarmored agent: freezes them and steals their whole inventory. When hitting an
+  armoured agent, destroys their armor. **Inventory System**
+- Agents have limited inventory space (default max: 50 items)
+- Resources provide rewards just by being in inventory (up to their max reward value)
+- Resources can be stolen through attacks Objects Various buildings: Mine, Generator, Armory, Lasery, Altar, Lab,
+  Factory, Temple.
+- HP — hitpoints, the number of times something can be hit before destruction.
+- Cooldown between uses (varies by building)
+- Can be damaged and destroyed by attacks
+
+## Environment Architecture
+
+MettaGrid uses a modular architecture designed primarily for the Softmax Studio ML project, with lightweight adapters to
+maintain compatibility with external RL frameworks:
+
+### Primary Training Environment
+
+**`MettaGridEnv`** - The main environment actively developed for Softmax Studio training systems
+
+- Full-featured environment with comprehensive stats collection, replay recording, and curriculum support
+- Inherits from `MettaGridCore` for C++ environment implementation
+- **Exclusively used** by `metta.rl.trainer` and `metta.sim.simulation`
+- Continuously developed and optimized for Softmax Studio use cases
+- Backward compatible with existing training code
+
+### Core Infrastructure
+
+**`MettaGridCore`** - Low-level C++ environment wrapper
+
+- Foundation that provides the core game mechanics and performance
+- **Not used directly** for training - serves as implementation detail for `MettaGridEnv`
+- Provides the base functionality that external adapters wrap
+
+### External Framework Compatibility Adapters
+
+Lightweight wrappers around `MettaGridCore` to maintain compatibility with other training systems:
+
+- **`MettaGridGymEnv`** - Gymnasium compatibility for research workflows
+- **`MettaGridPettingZooEnv`** - PettingZoo compatibility for multi-agent research
+- **`MettaGridPufferEnv`** - PufferLib compatibility for high-performance external training
+
+**Important**: These adapters are **only used with their respective training systems**, not with the Metta trainer.
+
+### Design Philosophy
+
+- **Primary Focus**: `MettaGridEnv` receives active development and new features for Softmax Studio
+- **Compatibility Maintenance**: External adapters ensure other frameworks continue working as the core evolves
+- **Testing for Compatibility**: Demos verify external frameworks remain functional during core development
+- **Clear Separation**: Each environment type serves its specific training system - no mixing between systems
+
+### Compatibility Testing Demos
+
+These demos ensure external framework adapters remain functional as the core environment evolves:
+
+```bash
+# Verify PettingZoo compatibility
+python -m mettagrid.demos.demo_train_pettingzoo
+
+# Verify PufferLib compatibility
+python -m mettagrid.demos.demo_train_puffer
+
+# Verify Gymnasium compatibility
+python -m mettagrid.demos.demo_train_gym
+```
+
+The demos serve as regression tests to catch compatibility issues during core development, ensuring external users can
+continue using their preferred frameworks.
+
+## Building and testing
+
+For local development, refer to the top-level [README.md](../README.md) in this repository.
+
+### Bazel
+
+By default, `uv sync` will run the Bazel build automatically via the custom build backend. If you need to run C++ tests
+and benchmarks directly, you'll need to invoke `bazel` directly.
+
+Build C++ tests and benchmarks in debug mode:
+
+```sh
+# Build with debug flags
+bazel build --config=dbg //:mettagrid_c
+# Run all tests
+bazel test //...
+```
+
+For benchmarks you might prefer to use the optimized build:
+
+```sh
+# Build with optimizations
+bazel build --config=opt //:mettagrid_c
+
+# Run benchmarks
+./build-release/benchmarks/grid_object_benchmark
+```

mettagrid-0.2.0.16/bazel_build.py

@@ -0,0 +1,229 @@
+# Custom build backend for building mettagrid with Bazel
+# This backend compiles the C++ extension using Bazel during package installation
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from setuptools.build_meta import (
+    build_editable as _build_editable,
+)
+from setuptools.build_meta import (
+    build_sdist as _build_sdist,
+)
+from setuptools.build_meta import (
+    build_wheel as _build_wheel,
+)
+from setuptools.build_meta import (
+    get_requires_for_build_editable,
+    get_requires_for_build_sdist,
+    get_requires_for_build_wheel,
+    prepare_metadata_for_build_editable,
+    prepare_metadata_for_build_wheel,
+)
+from setuptools.dist import Distribution
+
+PROJECT_ROOT = Path(__file__).resolve().parent
+METTASCOPE_DIR = PROJECT_ROOT / "nim" / "mettascope"
+
+
+def _run_bazel_build() -> None:
+    """Run Bazel build to compile the C++ extension."""
+    # Check if bazel is available
+    if shutil.which("bazel") is None:
+        raise RuntimeError("Bazel is required to build mettagrid. Please install Bazel: https://bazel.build/install")
+
+    # Determine build configuration from environment
+    debug = os.environ.get("DEBUG", "").lower() in ("1", "true", "yes")
+
+    # Check if running in CI environment (GitHub Actions sets CI=true)
+    is_ci = os.environ.get("CI", "").lower() == "true" or os.environ.get("GITHUB_ACTIONS", "") == "true"
+
+    if is_ci:
+        # Use CI configuration to avoid root user issues with hermetic Python
+        config = "ci"
+    else:
+        config = "dbg" if debug else "opt"
+
+    # Align Bazel's registered Python toolchain with the active interpreter.
+    py_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+
+    env = os.environ.copy()
+    env.setdefault("METTAGRID_BAZEL_PYTHON_VERSION", py_version)
+
+    # Provide a writable output root for environments with restricted /var/tmp access.
+    output_user_root = env.get(
+        "METTAGRID_BAZEL_OUTPUT_ROOT",
+        str(PROJECT_ROOT / ".bazel_output"),
+    )
+
+    # Ensure the output root exists before invoking Bazel.
+    Path(output_user_root).mkdir(parents=True, exist_ok=True)
+
+    # Build the Python extension with auto-detected parallelism
+    cmd = [
+        "bazel",
+        "--batch",
+        f"--output_user_root={output_user_root}",
+        "build",
+        f"--config={config}",
+        "--jobs=auto",
+        "--verbose_failures",
+        "//cpp:mettagrid_c",  # Build from new cpp location
+    ]
+
+    print(f"Running Bazel build: {' '.join(cmd)}")
+    result = subprocess.run(cmd, cwd=PROJECT_ROOT, capture_output=True, text=True, env=env)
+
+    if result.returncode != 0:
+        print("Bazel build failed. STDERR:", file=sys.stderr)
+        print(result.stderr, file=sys.stderr)
+        print("Bazel build STDOUT:", file=sys.stderr)
+        print(result.stdout, file=sys.stderr)
+        raise RuntimeError("Bazel build failed")
+
+    # Copy the built extension to the package directory
+    bazel_bin = PROJECT_ROOT / "bazel-bin"
+    # Try both old and new locations for backward compatibility
+    src_dirs = [
+        PROJECT_ROOT / "python/src/mettagrid",  # New location
+        PROJECT_ROOT / "src/mettagrid",  # Old location (compatibility)
+    ]
+
+    # Find the built extension file
+    # Bazel outputs the extension at bazel-bin/cpp/mettagrid_c.so or bazel-bin/mettagrid_c.so
+    extension_patterns = [
+        "cpp/mettagrid_c.so",
+        "cpp/mettagrid_c.pyd",
+        "cpp/mettagrid_c.dylib",  # New location
+        "mettagrid_c.so",
+        "mettagrid_c.pyd",
+        "mettagrid_c.dylib",  # Old location
+    ]
+    extension_file = None
+    for pattern in extension_patterns:
+        file_path = bazel_bin / pattern
+        if file_path.exists():
+            extension_file = file_path
+            break
+    if not extension_file:
+        raise RuntimeError("mettagrid_c.{so,pyd,dylib} not found in bazel-bin/cpp/ or bazel-bin/")
+
+    # Copy to all source directories that exist
+    for src_dir in src_dirs:
+        if src_dir.parent.exists():
+            # Ensure destination directory exists
+            src_dir.mkdir(parents=True, exist_ok=True)
+            # Copy the extension to the source directory
+            dest = src_dir / extension_file.name
+            # Remove existing file if it exists (it might be read-only from previous build)
+            if dest.exists():
+                dest.unlink()
+            shutil.copy2(extension_file, dest)
+            print(f"Copied {extension_file} to {dest}")
+
+
+def _nim_artifacts_up_to_date() -> bool:
+    """Check whether Nim outputs are still current."""
+
+    force_rebuild = os.environ.get("METTAGRID_FORCE_NIM_BUILD", "").lower() in {"1", "true", "yes"}
+    if force_rebuild:
+        return False
+
+    generated_dir = METTASCOPE_DIR / "bindings" / "generated"
+    if not generated_dir.exists():
+        return False
+
+    existing_outputs = {
+        generated_dir / name
+        for name in (
+            "mettascope2.py",
+            "libmettascope2.dylib",
+            "libmettascope2.so",
+            "libmettascope2.dll",
+        )
+        if (generated_dir / name).exists()
+    }
+    if not existing_outputs:
+        return False
+
+    source_files = [path for pattern in ("*.nim", "*.nims") for path in METTASCOPE_DIR.rglob(pattern) if path.is_file()]
+    if not source_files:
+        return False
+
+    latest_source_mtime = max(path.stat().st_mtime for path in source_files)
+    oldest_output_mtime = min(path.stat().st_mtime for path in existing_outputs)
+
+    return oldest_output_mtime >= latest_source_mtime
+
+
+def _run_mettascope_build() -> None:
+    """Build Nim artifacts when cache misses."""
+
+    if _nim_artifacts_up_to_date():
+        print("Skipping Nim build; artifacts up to date.")
+        return
+
+    # Check if nim and nimble are available
+    if shutil.which("nim") is None:
+        print("Warning: Nim compiler not found. Skipping mettascope build.")
+        print("To build mettascope, install Nim: https://nim-lang.org/install.html")
+        raise RuntimeError("Nim compiler not found")
+
+    if shutil.which("nimble") is None:
+        print("Warning: Nimble package manager not found. Skipping mettascope build.")
+        print("To build mettascope, install Nim: https://nim-lang.org/install.html")
+        raise RuntimeError("Nimble package manager not found")
+
+    print(f"Building mettascope from {METTASCOPE_DIR}")
+
+    # Run the build script
+    for cmd in ["update", "install", "bindings"]:
+        result = subprocess.run(["nimble", cmd, "-y"], cwd=METTASCOPE_DIR, capture_output=True, text=True)
+        print(result.stderr, file=sys.stderr)
+        print(result.stdout, file=sys.stderr)
+        if result.returncode != 0:
+            print(f"Warning: Mettascope build failed. {cmd} failed. STDERR:", file=sys.stderr)
+            print(f"Mettascope build {cmd} STDOUT:", file=sys.stderr)
+            raise RuntimeError("Mettascope build failed")
+    print("Successfully built mettascope")
+
+
+def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+    """Build a wheel, compiling the C++ extension with Bazel first, then mettascope."""
+    _run_bazel_build()
+    _run_mettascope_build()
+    # Ensure wheel is tagged as non-pure (platform-specific) since we bundle a native extension
+    # Setuptools/wheel derive purity from Distribution.has_ext_modules(). Monkeypatch to force True.
+    original_has_ext_modules = Distribution.has_ext_modules
+    try:
+        Distribution.has_ext_modules = lambda self: True  # type: ignore[assignment]
+        return _build_wheel(wheel_directory, config_settings, metadata_directory)
+    finally:
+        Distribution.has_ext_modules = original_has_ext_modules
+
+
+def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
+    """Build an editable install, compiling the C++ extension with Bazel first, then mettascope."""
+    _run_bazel_build()
+    _run_mettascope_build()
+    return _build_editable(wheel_directory, config_settings, metadata_directory)
+
+
+def build_sdist(sdist_directory, config_settings=None):
+    """Build a source distribution without compiling the extension."""
+    return _build_sdist(sdist_directory, config_settings)
+
+
+__all__ = [
+    "build_wheel",
+    "build_editable",
+    "build_sdist",
+    "get_requires_for_build_wheel",
+    "get_requires_for_build_editable",
+    "get_requires_for_build_sdist",
+    "prepare_metadata_for_build_wheel",
+    "prepare_metadata_for_build_editable",
+]