pytpg 0.5.0__py3-none-any.whl

pytpg/__init__.py

@@ -0,0 +1,7 @@
+"""Public package namespace for the pyTPG research framework."""
+
+from importlib.metadata import version as _version
+
+__version__ = _version("pytpg")
+
+__all__ = ["__version__"]

pytpg/adapters/__init__.py

@@ -0,0 +1,43 @@
+"""Optional environment adapters kept outside the TPG core."""
+
+from pytpg.adapters.errors import (
+    GymnasiumDependencyError,
+    GymnasiumEpisodeStateError,
+    GymnasiumEvaluationError,
+    GymnasiumIntegrationError,
+    InvalidGymnasiumActionError,
+    InvalidGymnasiumTransitionError,
+    UnsupportedGymnasiumSpaceError,
+)
+from pytpg.adapters.gymnasium import (
+    GymnasiumAdapter,
+    GymnasiumEnvironment,
+    GymnasiumEnvironmentFactory,
+    GymnasiumReset,
+    GymnasiumStep,
+    make_gymnasium_environment,
+)
+from pytpg.adapters.gymnasium_evaluation import (
+    GymnasiumEpisodeResult,
+    GymnasiumEvaluationConfig,
+    GymnasiumFitness,
+)
+
+__all__ = [
+    "GymnasiumAdapter",
+    "GymnasiumDependencyError",
+    "GymnasiumEnvironment",
+    "GymnasiumEnvironmentFactory",
+    "GymnasiumEpisodeResult",
+    "GymnasiumEpisodeStateError",
+    "GymnasiumEvaluationConfig",
+    "GymnasiumEvaluationError",
+    "GymnasiumFitness",
+    "GymnasiumIntegrationError",
+    "GymnasiumReset",
+    "GymnasiumStep",
+    "InvalidGymnasiumActionError",
+    "InvalidGymnasiumTransitionError",
+    "UnsupportedGymnasiumSpaceError",
+    "make_gymnasium_environment",
+]

pytpg/adapters/errors.py

@@ -0,0 +1,40 @@
+"""Failures raised at the optional Gymnasium integration boundary."""
+
+
+class GymnasiumIntegrationError(Exception):
+    """Base class for Gymnasium adapter and evaluation failures."""
+
+
+class GymnasiumDependencyError(GymnasiumIntegrationError):
+    """The optional Gymnasium dependency is unavailable."""
+
+
+class UnsupportedGymnasiumSpaceError(GymnasiumIntegrationError):
+    """An environment space cannot be represented by the current adapter."""
+
+
+class InvalidGymnasiumTransitionError(GymnasiumIntegrationError):
+    """An environment returned a value outside the modern Gymnasium API."""
+
+
+class GymnasiumEpisodeStateError(GymnasiumIntegrationError):
+    """An operation conflicts with the adapter's episode lifecycle."""
+
+
+class InvalidGymnasiumActionError(GymnasiumIntegrationError):
+    """A TPG action ID cannot be mapped into the environment action space."""
+
+
+class GymnasiumEvaluationError(GymnasiumIntegrationError):
+    """A Gymnasium fitness-evaluation configuration or result is invalid."""
+
+
+__all__ = [
+    "GymnasiumDependencyError",
+    "GymnasiumEpisodeStateError",
+    "GymnasiumEvaluationError",
+    "GymnasiumIntegrationError",
+    "InvalidGymnasiumActionError",
+    "InvalidGymnasiumTransitionError",
+    "UnsupportedGymnasiumSpaceError",
+]

pytpg/adapters/gymnasium.py

@@ -0,0 +1,360 @@
+"""Strict, optional boundary for modern Gymnasium environments."""
+
+from __future__ import annotations
+
+import importlib
+import math
+import operator
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from numbers import Real
+from types import MappingProxyType
+from typing import Any, Protocol, cast
+
+from pytpg.adapters.errors import (
+    GymnasiumDependencyError,
+    GymnasiumEpisodeStateError,
+    InvalidGymnasiumActionError,
+    InvalidGymnasiumTransitionError,
+    UnsupportedGymnasiumSpaceError,
+)
+
+
+class GymnasiumEnvironment(Protocol):
+    """Structural surface used without importing the optional package."""
+
+    action_space: object
+    observation_space: object
+
+    def reset(
+        self,
+        *,
+        seed: int | None = None,
+        options: Mapping[str, object] | None = None,
+    ) -> object: ...
+
+    def step(self, action: object) -> object: ...
+
+    def close(self) -> None: ...
+
+
+class GymnasiumEnvironmentFactory(Protocol):
+    """Create a fresh environment for one graph fitness evaluation."""
+
+    def __call__(self) -> GymnasiumEnvironment: ...
+
+
+@dataclass(frozen=True, slots=True)
+class GymnasiumReset:
+    """Normalized result of one Gymnasium reset."""
+
+    observation: tuple[float, ...]
+    info: Mapping[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class GymnasiumStep:
+    """Normalized result of one Gymnasium step."""
+
+    observation: tuple[float, ...]
+    reward: float
+    terminated: bool
+    truncated: bool
+    info: Mapping[str, object]
+    environment_action: int
+
+    @property
+    def done(self) -> bool:
+        """Whether reset is required before another step."""
+
+        return self.terminated or self.truncated
+
+
+class GymnasiumAdapter:
+    """Map flat numeric observations and zero-based TPG actions to Gymnasium."""
+
+    __slots__ = (
+        "_action_start",
+        "_closed",
+        "_needs_reset",
+        "_observation_shape",
+        "environment",
+        "input_size",
+        "n_actions",
+    )
+
+    def __init__(self, environment: GymnasiumEnvironment) -> None:
+        self.environment = environment
+        self.n_actions, self._action_start = self._validate_action_space(
+            environment.action_space
+        )
+        self._observation_shape, self.input_size = self._validate_observation_space(
+            environment.observation_space
+        )
+        self._closed = False
+        self._needs_reset = True
+
+    def reset(
+        self,
+        *,
+        seed: int | None = None,
+        options: Mapping[str, object] | None = None,
+    ) -> GymnasiumReset:
+        """Reset explicitly and normalize the `(observation, info)` result."""
+
+        self._require_open()
+        if seed is not None and (
+            isinstance(seed, bool) or not isinstance(seed, int) or seed < 0
+        ):
+            raise InvalidGymnasiumTransitionError(
+                "reset seed must be a non-negative integer or None"
+            )
+        if options is not None and not isinstance(options, Mapping):
+            raise InvalidGymnasiumTransitionError(
+                "reset options must be a mapping or None"
+            )
+        normalized_options: dict[str, object] | None = None
+        if options is not None:
+            untyped_options = cast(Mapping[object, object], options)
+            if not all(isinstance(key, str) for key in untyped_options):
+                raise InvalidGymnasiumTransitionError(
+                    "reset option keys must all be strings"
+                )
+            normalized_options = cast(dict[str, object], dict(untyped_options))
+        self._needs_reset = True
+        result = self.environment.reset(seed=seed, options=normalized_options)
+        values = self._require_result_tuple(result, 2, "reset")
+        observation = self._normalize_observation(values[0])
+        info = self._normalize_info(values[1], "reset info")
+        self._needs_reset = False
+        return GymnasiumReset(observation, info)
+
+    def step(self, action_id: int) -> GymnasiumStep:
+        """Map one action ID and normalize the five-value Gymnasium result."""
+
+        self._require_open()
+        if self._needs_reset:
+            raise GymnasiumEpisodeStateError(
+                "reset is required before stepping the environment"
+            )
+        environment_action = self.environment_action(action_id)
+        self._needs_reset = True
+        result = self.environment.step(environment_action)
+        values = self._require_result_tuple(result, 5, "step")
+        observation = self._normalize_observation(values[0])
+        reward = self._normalize_reward(values[1])
+        terminated = self._normalize_flag(values[2], "terminated")
+        truncated = self._normalize_flag(values[3], "truncated")
+        info = self._normalize_info(values[4], "step info")
+        self._needs_reset = terminated or truncated
+        return GymnasiumStep(
+            observation,
+            reward,
+            terminated,
+            truncated,
+            info,
+            environment_action,
+        )
+
+    def environment_action(self, action_id: int) -> int:
+        """Translate a zero-based TPG action ID into `Discrete.start` space."""
+
+        if isinstance(action_id, bool) or not isinstance(action_id, int):
+            raise InvalidGymnasiumActionError(
+                f"TPG action ID must be an integer, got {action_id!r}"
+            )
+        if not 0 <= action_id < self.n_actions:
+            raise InvalidGymnasiumActionError(
+                f"TPG action ID {action_id} is outside [0, {self.n_actions})"
+            )
+        environment_action = self._action_start + action_id
+        contains = getattr(self.environment.action_space, "contains", None)
+        if callable(contains):
+            contains_action = cast(Callable[[object], object], contains)
+            if not bool(contains_action(environment_action)):
+                raise InvalidGymnasiumActionError(
+                    f"mapped action {environment_action} is rejected by action_space"
+                )
+        return environment_action
+
+    def close(self) -> None:
+        """Close the owned environment exactly once."""
+
+        if not self._closed:
+            self.environment.close()
+            self._closed = True
+            self._needs_reset = True
+
+    def __enter__(self) -> GymnasiumAdapter:
+        self._require_open()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise GymnasiumEpisodeStateError("the environment adapter is closed")
+
+    @staticmethod
+    def _validate_action_space(space: object) -> tuple[int, int]:
+        if getattr(space, "shape", None) != ():
+            raise UnsupportedGymnasiumSpaceError(
+                "action_space must be a scalar Discrete-like space"
+            )
+        try:
+            n_actions = _index(cast(Any, space).n, "action_space.n")
+        except AttributeError as error:
+            raise UnsupportedGymnasiumSpaceError(
+                "action_space must be a scalar Discrete-like space"
+            ) from error
+        if n_actions < 1:
+            raise UnsupportedGymnasiumSpaceError(
+                "action_space.n must be a positive integer"
+            )
+        start = _index(getattr(space, "start", 0), "action_space.start")
+        return n_actions, start
+
+    @staticmethod
+    def _validate_observation_space(space: object) -> tuple[tuple[int, ...], int]:
+        shape = getattr(space, "shape", None)
+        if not isinstance(shape, tuple):
+            raise UnsupportedGymnasiumSpaceError(
+                "observation_space must have one fixed numeric shape; "
+                "composite spaces are not supported"
+            )
+        untyped_shape = cast(tuple[object, ...], shape)
+        dimensions = tuple(
+            _index(value, f"observation_space.shape[{index}]")
+            for index, value in enumerate(untyped_shape)
+        )
+        if any(value < 0 for value in dimensions):
+            raise UnsupportedGymnasiumSpaceError(
+                "observation_space dimensions must be non-negative"
+            )
+        input_size = math.prod(dimensions) if dimensions else 1
+        if input_size < 1:
+            raise UnsupportedGymnasiumSpaceError(
+                "observation_space must contain at least one scalar"
+            )
+        dtype = getattr(space, "dtype", None)
+        if getattr(dtype, "kind", None) not in {"i", "u", "f"}:
+            raise UnsupportedGymnasiumSpaceError(
+                "observation_space dtype must be integer or floating point"
+            )
+        return dimensions, input_size
+
+    def _normalize_observation(self, value: object) -> tuple[float, ...]:
+        numpy: Any = importlib.import_module("numpy")
+        try:
+            array: Any = numpy.asarray(value)
+        except (TypeError, ValueError) as error:
+            raise InvalidGymnasiumTransitionError(
+                "observation cannot be converted to a numeric array"
+            ) from error
+        if tuple(array.shape) != self._observation_shape:
+            raise InvalidGymnasiumTransitionError(
+                f"observation shape {tuple(array.shape)!r} does not match "
+                f"observation_space shape {self._observation_shape!r}"
+            )
+        if array.dtype.kind not in {"i", "u", "f"}:
+            raise InvalidGymnasiumTransitionError(
+                "observation values must be integer or floating point"
+            )
+        flattened: list[Any] = array.reshape(-1, order="C").tolist()
+        normalized = tuple(float(item) for item in flattened)
+        if len(normalized) != self.input_size or not all(
+            math.isfinite(item) for item in normalized
+        ):
+            raise InvalidGymnasiumTransitionError(
+                "observation must contain only finite numeric values"
+            )
+        return normalized
+
+    @staticmethod
+    def _normalize_reward(value: object) -> float:
+        if isinstance(value, bool) or not isinstance(value, Real):
+            raise InvalidGymnasiumTransitionError(
+                f"reward must be a finite real number, got {value!r}"
+            )
+        normalized = float(value)
+        if not math.isfinite(normalized):
+            raise InvalidGymnasiumTransitionError(
+                f"reward must be finite, got {value!r}"
+            )
+        return normalized
+
+    @staticmethod
+    def _normalize_flag(value: object, name: str) -> bool:
+        if not isinstance(value, bool):
+            raise InvalidGymnasiumTransitionError(
+                f"{name} must be a bool, got {value!r}"
+            )
+        return value
+
+    @staticmethod
+    def _normalize_info(value: object, name: str) -> Mapping[str, object]:
+        if not isinstance(value, Mapping):
+            raise InvalidGymnasiumTransitionError(f"{name} must be a mapping")
+        untyped = cast(Mapping[object, object], value)
+        if not all(isinstance(key, str) for key in untyped):
+            raise InvalidGymnasiumTransitionError(f"{name} keys must all be strings")
+        return MappingProxyType(cast(dict[str, object], dict(untyped)))
+
+    @staticmethod
+    def _require_result_tuple(
+        value: object,
+        length: int,
+        operation: str,
+    ) -> tuple[object, ...]:
+        if not isinstance(value, tuple):
+            raise InvalidGymnasiumTransitionError(
+                f"{operation} must return a {length}-item tuple"
+            )
+        values = cast(tuple[object, ...], value)
+        if len(values) != length:
+            raise InvalidGymnasiumTransitionError(
+                f"{operation} must return a {length}-item tuple"
+            )
+        return values
+
+
+def make_gymnasium_environment(
+    environment_id: str,
+    **keyword_arguments: object,
+) -> GymnasiumEnvironment:
+    """Create an environment while keeping Gymnasium an optional dependency."""
+
+    if not isinstance(environment_id, str) or not environment_id.strip():
+        raise GymnasiumDependencyError("environment_id must be a non-empty string")
+    try:
+        gymnasium: Any = importlib.import_module("gymnasium")
+    except ModuleNotFoundError as error:
+        if error.name != "gymnasium":
+            raise
+        raise GymnasiumDependencyError(
+            'Gymnasium is not installed; install pyTPG with the "gymnasium" extra'
+        ) from error
+    return cast(
+        GymnasiumEnvironment,
+        gymnasium.make(environment_id, **keyword_arguments),
+    )
+
+
+def _index(value: object, name: str) -> int:
+    if isinstance(value, bool):
+        raise UnsupportedGymnasiumSpaceError(f"{name} must be an integer")
+    try:
+        return operator.index(cast(Any, value))
+    except TypeError as error:
+        raise UnsupportedGymnasiumSpaceError(f"{name} must be an integer") from error
+
+
+__all__ = [
+    "GymnasiumAdapter",
+    "GymnasiumEnvironment",
+    "GymnasiumEnvironmentFactory",
+    "GymnasiumReset",
+    "GymnasiumStep",
+    "make_gymnasium_environment",
+]

pytpg/adapters/gymnasium_evaluation.py

@@ -0,0 +1,231 @@
+"""Reproducible episodic Gymnasium fitness evaluation."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from pytpg.adapters.errors import GymnasiumEvaluationError
+from pytpg.adapters.gymnasium import (
+    GymnasiumAdapter,
+    GymnasiumEnvironmentFactory,
+)
+from pytpg.core import TPGGraph
+from pytpg.memory import (
+    Memory,
+    MemoryFactory,
+    NullMemory,
+    StatefulGraphRuntime,
+)
+from pytpg.runtime import GraphRuntime
+from pytpg.seed import SeedManager
+
+
+@dataclass(frozen=True, slots=True)
+class GymnasiumEvaluationConfig:
+    """Episode seeds and hard rollout bound shared by every graph."""
+
+    episode_seeds: tuple[int, ...]
+    max_episode_steps: int = 1_000
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.episode_seeds, tuple) or not self.episode_seeds:
+            raise GymnasiumEvaluationError("episode_seeds must be a non-empty tuple")
+        if any(
+            isinstance(seed, bool) or not isinstance(seed, int) or seed < 0
+            for seed in self.episode_seeds
+        ):
+            raise GymnasiumEvaluationError(
+                "episode seeds must be non-negative integers"
+            )
+        if (
+            isinstance(self.max_episode_steps, bool)
+            or not isinstance(self.max_episode_steps, int)
+            or self.max_episode_steps < 1
+        ):
+            raise GymnasiumEvaluationError(
+                "max_episode_steps must be a positive integer"
+            )
+
+    @classmethod
+    def from_seed(
+        cls,
+        master_seed: int,
+        episodes: int,
+        *,
+        max_episode_steps: int = 1_000,
+    ) -> GymnasiumEvaluationConfig:
+        """Derive call-order-independent common episode seeds."""
+
+        if isinstance(episodes, bool) or not isinstance(episodes, int) or episodes < 1:
+            raise GymnasiumEvaluationError("episodes must be a positive integer")
+        if (
+            isinstance(master_seed, bool)
+            or not isinstance(master_seed, int)
+            or master_seed < 0
+        ):
+            raise GymnasiumEvaluationError("master_seed must be a non-negative integer")
+        seed_manager = SeedManager(master_seed)
+        return cls(
+            tuple(
+                seed_manager.derive_seed("gymnasium_episode", index)
+                for index in range(episodes)
+            ),
+            max_episode_steps,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class GymnasiumEpisodeResult:
+    """Inspectable return and termination reason for one rollout."""
+
+    seed: int
+    total_reward: float
+    steps: int
+    terminated: bool
+    truncated: bool
+    step_limit_reached: bool
+
+    def __post_init__(self) -> None:
+        if (
+            isinstance(self.seed, bool)
+            or not isinstance(self.seed, int)
+            or self.seed < 0
+        ):
+            raise GymnasiumEvaluationError("episode seed must be non-negative")
+        if (
+            isinstance(self.total_reward, bool)
+            or not isinstance(self.total_reward, (int, float))
+            or not math.isfinite(float(self.total_reward))
+        ):
+            raise GymnasiumEvaluationError("episode total_reward must be finite")
+        object.__setattr__(self, "total_reward", float(self.total_reward))
+        if (
+            isinstance(self.steps, bool)
+            or not isinstance(self.steps, int)
+            or self.steps < 1
+        ):
+            raise GymnasiumEvaluationError("episode steps must be positive")
+        if not all(
+            isinstance(value, bool)
+            for value in (self.terminated, self.truncated, self.step_limit_reached)
+        ):
+            raise GymnasiumEvaluationError("episode termination flags must be bools")
+        if self.step_limit_reached == (self.terminated or self.truncated):
+            raise GymnasiumEvaluationError(
+                "step_limit_reached must be the complement of environment completion"
+            )
+
+
+class GymnasiumFitness:
+    """Mean episodic return with common random seeds across all graphs."""
+
+    __slots__ = ("config", "environment_factory", "memory_factory")
+
+    def __init__(
+        self,
+        environment_factory: GymnasiumEnvironmentFactory,
+        config: GymnasiumEvaluationConfig,
+        *,
+        memory_factory: MemoryFactory | None = None,
+    ) -> None:
+        if not callable(environment_factory):
+            raise GymnasiumEvaluationError("environment_factory must be callable")
+        if not isinstance(config, GymnasiumEvaluationConfig):
+            raise GymnasiumEvaluationError("config must be a GymnasiumEvaluationConfig")
+        if memory_factory is not None and not callable(memory_factory):
+            raise GymnasiumEvaluationError("memory_factory must be callable or None")
+        self.environment_factory = environment_factory
+        self.config = config
+        self.memory_factory = memory_factory
+
+    def __call__(self, graph: TPGGraph) -> float:
+        """Return mean total reward, suitable for `SequentialEvaluator`."""
+
+        results = self.evaluate(graph)
+        return math.fsum(result.total_reward for result in results) / len(results)
+
+    def evaluate(self, graph: TPGGraph) -> tuple[GymnasiumEpisodeResult, ...]:
+        """Evaluate all configured episodes in one fresh, always-closed env."""
+
+        if not isinstance(graph, TPGGraph):
+            raise GymnasiumEvaluationError("graph must be a TPGGraph")
+        adapter = GymnasiumAdapter(self.environment_factory())
+        with adapter:
+            self._validate_graph_actions(graph, adapter.n_actions)
+            memory: Memory = (
+                NullMemory() if self.memory_factory is None else self.memory_factory()
+            )
+            controller: StatefulGraphRuntime | None = None
+            results: list[GymnasiumEpisodeResult] = []
+            for seed in self.config.episode_seeds:
+                reset = adapter.reset(seed=seed)
+                if controller is None:
+                    initial_memory = memory.reset()
+                    runtime = GraphRuntime.infer_for_graph(
+                        graph,
+                        reset.observation + initial_memory.values,
+                        validate_before_execution=False,
+                    )
+                    runtime.validate(graph).require_valid()
+                    controller = StatefulGraphRuntime(
+                        runtime,
+                        memory,
+                        adapter.input_size,
+                    )
+                controller.reset_episode()
+                total_reward = 0.0
+                observation = reset.observation
+                terminated = False
+                truncated = False
+                steps = 0
+                try:
+                    for _ in range(self.config.max_episode_steps):
+                        action_id = controller.act(graph, observation)
+                        transition = adapter.step(action_id)
+                        steps += 1
+                        total_reward += transition.reward
+                        if not math.isfinite(total_reward):
+                            raise GymnasiumEvaluationError(
+                                "accumulated episode reward is not finite"
+                            )
+                        observation = transition.observation
+                        terminated = transition.terminated
+                        truncated = transition.truncated
+                        if transition.done:
+                            break
+                finally:
+                    if controller.episode_active:
+                        controller.end_episode()
+                step_limit_reached = not (terminated or truncated)
+                results.append(
+                    GymnasiumEpisodeResult(
+                        seed,
+                        total_reward,
+                        steps,
+                        terminated,
+                        truncated,
+                        step_limit_reached,
+                    )
+                )
+        return tuple(results)
+
+    @staticmethod
+    def _validate_graph_actions(graph: TPGGraph, n_actions: int) -> None:
+        for team in graph.teams:
+            for learner in team.learners:
+                if learner.action.kind != "atomic":
+                    continue
+                action_id = int(learner.action.action_id)
+                if not 0 <= action_id < n_actions:
+                    raise GymnasiumEvaluationError(
+                        f"graph atomic action ID {action_id} is outside "
+                        f"the environment range [0, {n_actions})"
+                    )
+
+
+__all__ = [
+    "GymnasiumEpisodeResult",
+    "GymnasiumEvaluationConfig",
+    "GymnasiumFitness",
+]

pytpg/callbacks/__init__.py

@@ -0,0 +1,16 @@
+"""Structured, optional evolution lifecycle callbacks."""
+
+from pytpg.callbacks.base import (
+    EvolutionCallback,
+    EvolutionEvent,
+    EvolutionEventKind,
+)
+from pytpg.callbacks.logging import EventRecorder, LoggingCallback
+
+__all__ = [
+    "EventRecorder",
+    "EvolutionCallback",
+    "EvolutionEvent",
+    "EvolutionEventKind",
+    "LoggingCallback",
+]