valanga 0.1.3__py3-none-any.whl

valanga/__init__.py

@@ -0,0 +1,42 @@
+"""Common types and utilities shared by multiple libraries."""
+
+from .evaluations import EvalItem, FloatyStateEvaluation, ForcedOutcome, StateEvaluation
+from .game import (
+    BLACK,
+    WHITE,
+    BranchKey,
+    BranchKeyGeneratorP,
+    Color,
+    ColorIndex,
+    HasTurn,
+    State,
+    StateModifications,
+    StateTag,
+    TurnState,
+)
+from .over_event import OverEvent
+from .progress_messsage import PlayerProgressMessage
+from .representation_factory import RepresentationFactory
+from .represention_for_evaluation import ContentRepresentation
+
+__all__ = [
+    "ForcedOutcome",
+    "FloatyStateEvaluation",
+    "StateEvaluation",
+    "EvalItem",
+    "OverEvent",
+    "Color",
+    "WHITE",
+    "BLACK",
+    "ColorIndex",
+    "HasTurn",
+    "TurnState",
+    "ContentRepresentation",
+    "RepresentationFactory",
+    "State",
+    "StateModifications",
+    "BranchKeyGeneratorP",
+    "BranchKey",
+    "PlayerProgressMessage",
+    "StateTag",
+]

valanga/evaluations.py

@@ -0,0 +1,58 @@
+"""
+Evaluation-related classes and types.
+"""
+
+from collections.abc import Hashable
+from dataclasses import dataclass
+from typing import Annotated, Protocol
+
+from .game import BranchKey, State
+from .over_event import OverEvent
+from .represention_for_evaluation import ContentRepresentation
+
+type ActionKey = Annotated[Hashable, "A label or identifier for an action"]
+
+
+class EvalItem[StateT: State](Protocol):
+    """
+    The protocol for an evaluation item.
+    An evaluation item is something that has a state and optionally a representation of that state.
+    """
+
+    @property
+    def state(self) -> StateT:
+        """The state associated with this evaluation item."""
+        ...
+
+    @property
+    def state_representation(self) -> ContentRepresentation | None:
+        """The representation of the state associated with this evaluation item, if available."""
+        ...
+
+
+@dataclass
+class ForcedOutcome:
+    """
+    The class
+    """
+
+    # The forced outcome with optimal play by both sides.
+    outcome: OverEvent
+
+    # the line
+    line: list[BranchKey]
+
+
+@dataclass
+class FloatyStateEvaluation:
+    """
+    The class to defines what is an evaluation of a board.
+    By convention is it always evaluated from the view point of the white side.
+    """
+
+    # The evaluation value for the white side when the outcome is not certain. Typically, a float.
+    # todo can we remove the None option?
+    value_white: float | None
+
+
+StateEvaluation = FloatyStateEvaluation | ForcedOutcome

valanga/evaluator_types.py

@@ -0,0 +1,13 @@
+"""Small shared types used by evaluators and representations.
+
+This module exists to avoid runtime circular imports between `evaluations` and
+`represention_for_evaluation`.
+"""
+
+from typing import Annotated
+
+EvaluatorInput = Annotated[
+    object, "The input type for the evaluator, typically a tensor or array"
+]
+
+__all__ = ["EvaluatorInput"]

valanga/game.py

@@ -0,0 +1,158 @@
+"""
+Common types and utilities representing game objects shared by multiple libraries.
+"""
+
+from collections.abc import Hashable
+from enum import Enum
+from typing import Annotated, Iterator, Protocol, Self, Sequence, TypeVar
+
+type Seed = Annotated[int, "seed"]
+
+type StateTag = Annotated[Hashable, "A label or identifier for a state in a game"]
+
+type StateModifications = Annotated[
+    object, "Modifications to the state between to time steps of the game"
+]  # used for time and memory optimisation
+
+
+type BranchKey = Annotated[Hashable, "A label or identifier for a branch in a tree"]
+
+
+T_co = TypeVar("T_co", bound=BranchKey, covariant=True, default=BranchKey)
+
+
+class BranchKeyGeneratorP(Protocol[T_co]):
+    """Protocol for a branch key generator that yields branch keys."""
+
+    # whether to sort the branch keys by their respective uci for easy comparison of various implementations
+    sort_branch_keys: bool = False
+
+    @property
+    def all_generated_keys(self) -> Sequence[T_co] | None:
+        """Returns all generated branch keys if available, otherwise None."""
+        ...
+
+    def __iter__(self) -> Iterator[T_co]:
+        """Returns an iterator over the branch keys."""
+        ...
+
+    def __next__(self) -> T_co:
+        """Returns the next branch key."""
+        ...
+
+    def more_than_one(self) -> bool:
+        """Checks if there is more than one branch available.
+
+        Returns:
+            bool: True if there is more than one branch, False otherwise.
+        """
+        ...
+
+    def get_all(self) -> Sequence[T_co]:
+        """Returns a list of all branch keys."""
+        ...
+
+    def copy_with_reset(self) -> Self:
+        """Creates a copy of the legal move generator with an optional reset of generated moves.
+
+        Returns:
+            Self: A new instance of the legal move generator with the specified generated moves.
+        """
+        ...
+
+
+class State(Protocol):
+    """Protocol for a content object that has a tag."""
+
+    @property
+    def tag(self) -> StateTag:
+        """Returns the tag of the content.
+
+        Returns:
+            StateTag: The tag of the content.
+        """
+        ...
+
+    @property
+    def branch_keys(self) -> BranchKeyGeneratorP[BranchKey]:
+        """Returns the branch keys associated with the content.
+
+        Returns:
+            BranchKeyGeneratorP: The branch keys associated with the content.
+        """
+        ...
+
+    def branch_name_from_key(self, key: BranchKey) -> str:
+        """Returns the branch name corresponding to the given branch key.
+
+        Args:
+            key (BranchKey): The branch key.
+
+        Returns:
+            str: The branch name corresponding to the given branch key.
+        """
+        ...
+
+    def is_game_over(self) -> bool:
+        """Checks if the game represented by the content is over.
+
+        Returns:
+            bool: True if the game is over, False otherwise.
+        """
+        ...
+
+    def copy(self, stack: bool, deep_copy_legal_moves: bool = True) -> Self:
+        """
+        Create a copy of the current board.
+
+        Args:
+            stack (bool): Whether to copy the previous action stack as well. Important in some games.
+            deep_copy_legal_moves (bool): Whether to deep copy the legal moves generator.
+
+        Returns:
+            BoardChi: A new instance of the BoardChi class with the copied board.
+        """
+        ...
+
+    def step(self, branch_key: BranchKey) -> StateModifications | None:
+        """Advances the state by applying the action corresponding to the given branch key.
+
+        Args:
+            branch_key (BranchKey): The branch key representing the action to be applied.
+
+        Returns:
+            StateModifications | None: The modifications to the state after applying the action, or None if the action is invalid.
+        """
+        ...
+
+
+type ColorIndex = Annotated[int, "1 for white, 0 for black"]
+
+WHITE: ColorIndex = 1
+BLACK: ColorIndex = 0
+
+
+class Color(int, Enum):
+    """Represents the color of a player in a game."""
+
+    WHITE = WHITE
+    BLACK = BLACK
+
+
+class HasTurn(Protocol):
+    """Protocol for a content object that has a tag."""
+
+    @property
+    def turn(self) -> Color:
+        """Returns the tag of the content.
+
+        Returns:
+            ContentTag: The tag of the content.
+        """
+        ...
+
+
+class TurnState(State, HasTurn, Protocol):
+    """A State that also supports turn()."""
+
+    ...

valanga/over_event.py

@@ -0,0 +1,254 @@
+"""
+Module for handling game over events.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+from .game import Color
+
+
+class HowOver(Enum):
+    """Represents the possible outcomes of a game.
+
+    Attributes:
+        WIN (int): Indicates a win.
+        DRAW (int): Indicates a draw.
+        DO_NOT_KNOW_OVER (int): Indicates that the outcome is unknown.
+    """
+
+    WIN = 1
+    DRAW = 2
+    DO_NOT_KNOW_OVER = 3
+
+
+class Winner(Enum):
+    """Represents the winner of a chess game.
+
+    Args:
+        Enum: The base class for enumeration types.
+
+    Attributes:
+        WHITE (Winner): Represents the winner as white.
+        BLACK (Winner): Represents the winner as black.
+        NO_KNOWN_WINNER (Winner): Represents the absence of a known winner.
+
+    Methods:
+        is_none() -> bool: Checks if the winner is None.
+        is_white() -> bool: Checks if the winner is white.
+        is_black() -> bool: Checks if the winner is black.
+    """
+
+    WHITE = Color.WHITE
+    BLACK = Color.BLACK
+    NO_KNOWN_WINNER = None
+
+    def is_none(self) -> bool:
+        """Check if the winner is NO_KNOWN_WINNER.
+
+        Returns:
+            bool: True if the winner is NO_KNOWN_WINNER, False otherwise.
+        """
+        return self is Winner.NO_KNOWN_WINNER
+
+    def is_white(self) -> bool:
+        """Check if the winner is white.
+
+        Returns:
+            bool: True if the winner is white, False otherwise.
+        """
+        is_white_bool: bool
+        if not self.is_none():
+            is_white_bool = self is Winner.WHITE
+        else:
+            is_white_bool = False
+        return is_white_bool
+
+    def is_black(self) -> bool:
+        """Check if the winner is black.
+
+        Returns:
+            bool: True if the winner is black, False otherwise.
+        """
+        is_black_bool: bool
+
+        if not self.is_none():
+            is_black_bool = self is Winner.BLACK
+        else:
+            is_black_bool = False
+        return is_black_bool
+
+
+class OverTags(str, Enum):
+    """Represents the possible tags for game over events.
+
+    Attributes:
+        TAG_WIN_WHITE (str): Tag indicating a win for the white player.
+        TAG_WIN_BLACK (str): Tag indicating a win for the black player.
+        TAG_DRAW (str): Tag indicating a draw.
+        TAG_DO_NOT_KNOW (str): Tag indicating an unknown outcome.
+    """
+
+    TAG_WIN_WHITE = "Win-Wh"
+    TAG_WIN_BLACK = "Win-Bl"
+    TAG_DRAW = "Draw"
+    TAG_DO_NOT_KNOW = "?"
+
+
+@dataclass(slots=True)
+class OverEvent:
+    """Represents an event that indicates the end of a game.
+
+    Attributes:
+        how_over (HowOver): The way the game ended.
+        who_is_winner (Winner): The winner of the game.
+
+    Raises:
+        AssertionError: If the `how_over` attribute is not a valid value from the `HowOver` enum.
+        AssertionError: If the `who_is_winner` attribute is not a valid value from the `Winner` enum.
+        Exception: If the winner is not properly defined.
+
+    Methods:
+        __post_init__: Performs additional initialization after the object is created.
+        becomes_over: Sets the `how_over` and `who_is_winner` attributes.
+        get_over_tag: Returns a tag string used in databases.
+        __bool__: Raises an exception.
+        is_over: Checks if the game is over.
+        is_win: Checks if the game ended with a win.
+        is_draw: Checks if the game ended with a draw.
+        is_winner: Checks if the specified player is the winner.
+        print_info: Prints information about the `OverEvent` object.
+        test: Performs tests on the `OverEvent` object.
+    """
+
+    how_over: HowOver = HowOver.DO_NOT_KNOW_OVER
+    who_is_winner: Winner = Winner.NO_KNOWN_WINNER
+    termination: Enum | None = None  # Optional termination reason
+
+    def __post_init__(self) -> None:
+        assert self.how_over in HowOver
+        assert self.who_is_winner in Winner
+
+        if self.how_over == HowOver.WIN:
+            assert (
+                self.who_is_winner is Winner.WHITE or self.who_is_winner is Winner.BLACK
+            )
+        elif self.how_over == HowOver.DRAW:
+            assert self.who_is_winner is Winner.NO_KNOWN_WINNER
+
+    def becomes_over(
+        self,
+        how_over: HowOver,
+        termination: Enum | None,
+        who_is_winner: Winner = Winner.NO_KNOWN_WINNER,
+    ) -> None:
+        """Sets the `how_over` and `who_is_winner` attributes.
+
+        Args:
+            how_over (HowOver): The way the game ended.
+            who_is_winner (Winner, optional): The winner of the game. Defaults to `Winner.NO_KNOWN_WINNER`.
+        """
+        self.how_over = how_over
+        self.who_is_winner = who_is_winner
+        self.termination = termination
+
+    def get_over_tag(self) -> OverTags:
+        """Returns a tag string used in databases.
+
+        Returns:
+            OverTags: The tag string representing the game outcome.
+
+        Raises:
+            Exception: If the winner is not properly defined.
+        """
+        over_tag: OverTags
+        if self.how_over == HowOver.WIN:
+            if self.who_is_winner.is_white():
+                over_tag = OverTags.TAG_WIN_WHITE
+            elif self.who_is_winner.is_black():
+                over_tag = OverTags.TAG_WIN_BLACK
+            else:
+                raise ValueError("error: winner is not properly defined.")
+        elif self.how_over == HowOver.DRAW:
+            over_tag = OverTags.TAG_DRAW
+        elif self.how_over == HowOver.DO_NOT_KNOW_OVER:
+            over_tag = OverTags.TAG_DO_NOT_KNOW
+        else:
+            raise ValueError("error: over is not properly defined.")
+        return over_tag
+
+    def __bool__(self) -> None:
+        """Raises an exception.
+
+        Raises:
+            Exception: Always raises an exception.
+        """
+        raise ValueError("Nooooooooooo  in over ebvent.py")
+
+    def is_over(self) -> bool:
+        """Checks if the game is over.
+
+        Returns:
+            bool: True if the game is over, False otherwise.
+        """
+        return self.how_over in {HowOver.WIN, HowOver.DRAW}
+
+    def is_win(self) -> bool:
+        """Checks if the game ended with a win.
+
+        Returns:
+            bool: True if the game ended with a win, False otherwise.
+        """
+        return self.how_over == HowOver.WIN
+
+    def is_draw(self) -> bool:
+        """Checks if the game ended with a draw.
+
+        Returns:
+            bool: True if the game ended with a draw, False otherwise.
+        """
+        return self.how_over == HowOver.DRAW
+
+    def is_winner(self, player: Color) -> bool:
+        """Checks if the specified player is the winner.
+
+        Args:
+            player (chess.Color): The player to check.
+
+        Returns:
+            bool: True if the specified player is the winner, False otherwise.
+
+        Raises:
+            AssertionError: If the `player` argument is not a valid value from the `chess.Color` enum.
+        """
+        assert player in {Color.WHITE, Color.BLACK}
+
+        is_winner: bool
+        if self.how_over == HowOver.WIN:
+            is_winner = bool(
+                self.who_is_winner == Winner.WHITE
+                and player == Color.WHITE
+                or self.who_is_winner == Winner.BLACK
+                and player == Color.BLACK
+            )
+        else:
+            is_winner = False
+        return is_winner
+
+    def print_info(self) -> None:
+        """Prints information about the `OverEvent` object."""
+        print(
+            "over_event:",
+            "how_over:",
+            self.how_over,
+            "who_is_winner:",
+            self.who_is_winner,
+        )
+
+    def test(self) -> None:
+        """Performs tests on the `OverEvent` object."""
+        if self.how_over == HowOver.WIN:
+            assert self.who_is_winner is not None
+            assert self.who_is_winner.is_white() or self.who_is_winner.is_black()
+        if self.how_over == HowOver.DRAW:
+            assert self.who_is_winner is None

valanga/policy.py

@@ -0,0 +1,42 @@
+"""
+Policy-related classes and protocols for branch selection in game trees.
+"""
+
+from dataclasses import dataclass
+from typing import Mapping, Protocol
+
+from valanga.evaluations import StateEvaluation
+from valanga.game import BranchKey, Seed, State
+
+
+@dataclass(frozen=True, slots=True)
+class BranchPolicy:
+    """
+    Represents a probability distribution over branches.
+    """
+
+    probs: Mapping[BranchKey, float]  # should sum to ~1.0
+
+
+@dataclass(frozen=True, slots=True)
+class Recommendation:
+    """A recommendation for a specific branch in a tree node."""
+
+    recommended_key: BranchKey
+    evaluation: StateEvaluation | None = None
+    policy: BranchPolicy | None = None
+    branch_evals: Mapping[BranchKey, StateEvaluation] | None = None
+
+
+class BranchSelector(Protocol):
+    """Protocol for a branch selector."""
+
+    def recommend(self, state: State, seed: Seed) -> Recommendation:
+        """Given a state and a seed, recommends a branch to take.
+        Args:
+            state (State): The current state of the game.
+            seed (Seed): A seed for any randomness involved in the selection.
+        Returns:
+            Recommendation: The recommended branch to take.
+        """
+        ...

valanga/progress_messsage.py

@@ -0,0 +1,20 @@
+"""
+Module for the ProgressMessage class.
+"""
+
+from dataclasses import dataclass
+
+from .game import Color
+
+
+@dataclass
+class PlayerProgressMessage:
+    """
+    Represents a message containing evaluation information.
+
+    Attributes:
+        evaluation_stock (Any): The evaluation for the stock.
+    """
+
+    progress_percent: int | None
+    player_color: Color

valanga/representation_factory.py

@@ -0,0 +1,74 @@
+"""
+Factory class for creating state representations.
+"""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .game import State, StateModifications
+from .represention_for_evaluation import ContentRepresentation
+
+
+class CreateFromState[T: ContentRepresentation](Protocol):
+    """
+    Protocol for creating a state representation from a state.
+    """
+
+    def __call__(self, state: State) -> T: ...
+
+
+class CreateFromStateAndModifications[T: ContentRepresentation](Protocol):
+    """
+    Protocol for creating a state representation from a state and modifications.
+    """
+
+    def __call__(
+        self,
+        state: State,
+        state_modifications: StateModifications,
+        previous_state_representation: T,
+    ) -> T: ...
+
+
+@dataclass
+class RepresentationFactory[T: ContentRepresentation = ContentRepresentation]:
+    """
+    Factory class for creating state representations.
+    """
+
+    create_from_state: CreateFromState[T]
+    create_from_state_and_modifications: CreateFromStateAndModifications[T]
+
+    def create_from_transition(
+        self,
+        state: State,
+        previous_state_representation: T | None,
+        modifications: StateModifications | None,
+    ) -> T:
+        """
+        Create a Generic T_StateRepresentation object from a transition.
+
+        Args:
+            state (State): The current state of the game.
+            previous_state_representation (Representation364 | None): The representation of the previous state. None if this is the root node.
+            modifications (StateModifications | None): The modifications from the parent state to the current state. None if this is the root node.
+
+        Returns:
+            T_StateRepresentation: The created (Generic) Representation object
+
+        This version is supposed to be faster as it only modifies the previous state
+        representation with the last modification
+        """
+        if previous_state_representation is None:  # this is the root_node
+            representation = self.create_from_state(state=state)
+        else:
+            if modifications is None:
+                representation = self.create_from_state(state=state)
+            else:
+                representation = self.create_from_state_and_modifications(
+                    state=state,
+                    state_modifications=modifications,
+                    previous_state_representation=previous_state_representation,
+                )
+
+        return representation

valanga/represention_for_evaluation.py

@@ -0,0 +1,26 @@
+"""
+Contains the definition of the ContentRepresentation protocol for content representations used in evaluations.
+"""
+
+from typing import Protocol
+
+from .evaluator_types import EvaluatorInput
+from .game import State
+
+
+class ContentRepresentation(Protocol):
+    """
+    Protocol defining the interface for a content representation.
+    It is a function returning the proper input for evaluation by the content evaluator.
+    """
+
+    def get_evaluator_input(self, state: State) -> EvaluatorInput:
+        """
+        Returns the evaluator input tensor for the content. Content representations have generally a compressed view and complemetary view of state info so to avoid redundancy and have all the necessary info we also give the state as input.
+
+        Args:
+            state: The current state of the game.
+
+        Returns:
+            The evaluator input tensor.
+        """