algorhino-anemone 0.1.1__py3-none-any.whl

anemone/nodes/utils.py

@@ -0,0 +1,146 @@
+"""
+This module contains utility functions for working with tree nodes in the move selector.
+
+Functions:
+- are_all_moves_and_children_opened(tree_node: TreeNode) -> bool: Checks if all moves and children of a tree node are opened.
+- a_move_sequence_from_root(tree_node: ITreeNode) -> list[str]: Returns a list of move sequences from the root node to a given tree node.
+- print_a_move_sequence_from_root(tree_node: TreeNode) -> None: Prints the move sequence from the root node to a given tree node.
+- is_winning(node_minmax_evaluation: NodeMinmaxEvaluation, color: chess.Color) -> bool: Checks if the color to play in the node is winning.
+"""
+
+from valanga import BranchKey, Color, State
+
+from anemone.node_evaluation.node_tree_evaluation.node_tree_evaluation import (
+    NodeTreeEvaluation,
+)
+from anemone.nodes.algorithm_node.algorithm_node import (
+    AlgorithmNode,
+)
+
+from .itree_node import ITreeNode
+from .tree_node import TreeNode
+
+
+def are_all_moves_and_children_opened(tree_node: TreeNode) -> bool:
+    """
+    Checks if all moves and children of a tree node are opened.
+
+    Args:
+        tree_node (TreeNode): The tree node to check.
+
+    Returns:
+        bool: True if all moves and children are opened, False otherwise.
+    """
+    return tree_node.all_branches_generated and tree_node.non_opened_branches == set()
+
+
+def a_move_key_sequence_from_root[StateT: State](
+    tree_node: ITreeNode[StateT],
+) -> list[str]:
+    """
+    Returns a list of move sequences from the root node to a given tree node.
+
+    Args:
+        tree_node (ITreeNode): The tree node to get the move sequence for.
+
+    Returns:
+        list[str]: A list of move sequences from the root node to the given tree node.
+    """
+    move_sequence_from_root: list[BranchKey] = []
+    child: ITreeNode[StateT] = tree_node
+    while child.parent_nodes:
+        parent: ITreeNode[StateT] = next(iter(child.parent_nodes))
+        move: BranchKey = child.parent_nodes[parent]
+        move_sequence_from_root.append(move)
+        child = parent
+    move_sequence_from_root.reverse()
+    return [str(i) for i in move_sequence_from_root]
+
+
+def a_branch_str_sequence_from_root[StateT: State](
+    tree_node: ITreeNode[StateT],
+) -> list[str]:
+    """
+    Returns a list of move sequences from the root node to a given tree node.
+
+    Args:
+        tree_node (ITreeNode): The tree node to get the move sequence for.
+
+    Returns:
+        list[str]: A list of move sequences from the root node to the given tree node.
+    """
+    move_sequence_from_root: list[str] = []
+    child: ITreeNode[StateT] = tree_node
+    while child.parent_nodes:
+        parent: ITreeNode[StateT] = next(iter(child.parent_nodes))
+        branch_key: BranchKey = child.parent_nodes[parent]
+        branch_str: str = parent.state.branch_name_from_key(branch_key)
+        move_sequence_from_root.append(branch_str)
+        child = parent
+    move_sequence_from_root.reverse()
+    return [str(i) for i in move_sequence_from_root]
+
+
+def best_node_sequence_from_node[StateT: State](
+    tree_node: AlgorithmNode[StateT],
+) -> list[AlgorithmNode[StateT]]:
+    """
+    Returns the best node sequence from the given tree node following the best moves.
+    Args:
+        tree_node (AlgorithmNode): The tree node to start from.
+    Returns:
+        list[AlgorithmNode]: A list of tree nodes representing the best node sequence.
+    """
+
+    best_move_seq: list[BranchKey] = tree_node.tree_evaluation.best_branch_sequence
+    index = 0
+    move_sequence: list[AlgorithmNode[StateT]] = [tree_node]
+    child: AlgorithmNode[StateT] = tree_node
+    while child.branches_children:
+        move: BranchKey = best_move_seq[index]
+        child_ = child.branches_children[move]
+        assert child_ is not None
+        child = child_
+        move_sequence.append(child)
+        index = index + 1
+    return move_sequence
+
+
+def print_a_move_sequence_from_root[StateT: State](
+    tree_node: ITreeNode[StateT],
+) -> None:
+    """
+    Prints the move sequence from the root node to a given tree node.
+
+    Args:
+        tree_node (TreeNode): The tree node to print the move sequence for.
+
+    Returns:
+        None
+    """
+    move_sequence_from_root: list[str] = a_move_key_sequence_from_root(
+        tree_node=tree_node
+    )
+    print(f"a_move_sequence_from_root{move_sequence_from_root}")
+
+
+def is_winning(node_tree_evaluation: NodeTreeEvaluation, color: Color) -> bool:
+    """
+    Checks if the color to play in the node is winning.
+
+    Args:
+        node_minmax_evaluation (NodeMinmaxEvaluation): The evaluation of the node.
+        color (chess.Color): The color to check.
+
+    Returns:
+        bool: True if the color is winning, False otherwise.
+    """
+    assert node_tree_evaluation.value_white_minmax is not None
+    winning_if_color_white: bool = (
+        node_tree_evaluation.value_white_minmax > 0.98 and color is Color.WHITE
+    )
+    winning_if_color_black: bool = (
+        node_tree_evaluation.value_white_minmax < -0.98 and color is Color.BLACK
+    )
+
+    return winning_if_color_white or winning_if_color_black

anemone/progress_monitor/progress_monitor.py

@@ -0,0 +1,375 @@
+"""
+This module defines stopping criteria for a move selector in a game tree.
+
+The stopping criteria determine when the move selector should stop exploring the game tree and make a decision.
+
+The module includes the following classes:
+
+- StoppingCriterion: The general stopping criterion class.
+- TreeMoveLimit: A stopping criterion based on a tree move limit.
+- DepthLimit: A stopping criterion based on a depth limit.
+
+It also includes helper classes and functions for creating and managing stopping criteria.
+"""
+
+from abc import abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Callable, Literal, Protocol, runtime_checkable
+
+from anemone import node_selector as node_sel
+from anemone import trees
+from anemone.nodes.algorithm_node.algorithm_node import AlgorithmNode
+
+
+@runtime_checkable
+class DepthToExpendP(Protocol):
+    """
+    Protocol for objects that provide the current depth to expand.
+
+    This protocol defines a single method `get_current_depth_to_expand` that should be implemented by classes
+    that want to provide the current depth to expand.
+
+    Attributes:
+        None
+
+    Methods:
+        get_current_depth_to_expand: Returns the current depth to expand as an integer.
+
+    Examples:
+        >>> class MyDepthToExpend(DepthToExpendP):
+        ...     def get_current_depth_to_expand(self) -> int:
+        ...         return 5
+        ...
+        >>> obj = MyDepthToExpend()
+        >>> obj.get_current_depth_to_expand()
+        5
+    """
+
+    def get_current_depth_to_expand(self) -> int:
+        """
+        Returns the current depth to expand as an integer.
+
+        Returns:
+            The current depth to expand.
+
+        Raises:
+            None
+        """
+        ...
+
+
+class StoppingCriterionTypes(str, Enum):
+    """
+    Enum class representing different types of stopping criteria for tree value calculation.
+    """
+
+    DEPTH_LIMIT = "depth_limit"
+    TREE_MOVE_LIMIT = "tree_move_limit"
+
+
+@dataclass
+class StoppingCriterionArgs:
+    """
+    Represents the arguments for a stopping criterion.
+
+    Attributes:
+        type (StoppingCriterionTypes): The type of stopping criterion.
+    """
+
+    type: StoppingCriterionTypes
+
+
+class ProgressMonitorP[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]](Protocol):
+    """
+    The general stopping criterion Protocol
+    """
+
+    def should_we_continue(self, tree: trees.Tree[NodeT]) -> bool:
+        """
+        Asking should we continue
+
+        Returns:
+            boolean of should we continue
+        """
+        ...
+
+    def respectful_opening_instructions(
+        self,
+        opening_instructions: node_sel.OpeningInstructions[NodeT],
+        tree: trees.Tree[NodeT],
+    ) -> node_sel.OpeningInstructions[NodeT]:
+        """
+        Ensures the opening request do not exceed the stopping criterion
+
+
+        """
+        ...
+
+    def get_string_of_progress(self, tree: trees.Tree[NodeT]) -> str:
+        """
+        Returns a string representation of the progress made by the stopping criterion.
+
+        Args:
+            tree (ValueTree): The move and value tree.
+
+        Returns:
+            str: A string representation of the progress.
+        """
+        ...
+
+    def get_percent_of_progress(
+        self,
+        tree: trees.Tree[NodeT],
+    ) -> str:
+        """Return a human-readable percent progress string."""
+        ...
+
+
+class ProgressMonitor[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]]:
+    """
+    The general stopping criterion base class
+    """
+
+    def should_we_continue(self, tree: trees.Tree[NodeT]) -> bool:
+        """
+        Asking should we continue
+
+        Returns:
+            boolean of should we continue
+        """
+        if tree.root_node.is_over():
+            return False
+        return True
+
+    def respectful_opening_instructions(
+        self,
+        opening_instructions: node_sel.OpeningInstructions[NodeT],
+        tree: trees.Tree[NodeT],
+    ) -> node_sel.OpeningInstructions[NodeT]:
+        """
+        Ensures the opening request do not exceed the stopping criterion
+
+
+        """
+        _ = tree
+        return opening_instructions
+
+    def get_string_of_progress(self, _tree: trees.Tree[NodeT]) -> str:
+        """
+        Returns a string representation of the progress made by the stopping criterion.
+
+        Args:
+            tree (ValueTree): The move and value tree.
+
+        Returns:
+            str: A string representation of the progress.
+        """
+        return ""
+
+    @abstractmethod
+    def get_percent_of_progress(self, tree: trees.Tree[NodeT]) -> int:
+        """Return a numeric progress percentage for this monitor."""
+        ...
+
+    def notify_percent_progress(
+        self,
+        tree: trees.Tree[NodeT],
+        notify_percent_function: Callable[[int], None] | None,
+    ) -> None:
+        """Notify a callback with the current progress percentage."""
+        percent_progress: int = self.get_percent_of_progress(tree=tree)
+
+        if notify_percent_function is not None:
+            notify_percent_function(percent_progress)
+
+
+@dataclass
+class TreeMoveLimitArgs:
+    """Arguments for the tree move limit stopping criterion."""
+
+    type: Literal[StoppingCriterionTypes.TREE_MOVE_LIMIT]
+    tree_move_limit: int
+
+
+class TreeMoveLimit[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]](
+    ProgressMonitor[NodeT]
+):
+    """
+    The stopping criterion based on a tree move limit
+    """
+
+    tree_move_limit: int
+
+    def __init__(self, tree_move_limit: int) -> None:
+        """Initialize the monitor with a move-count limit."""
+        self.tree_move_limit = tree_move_limit
+
+    def should_we_continue(self, tree: trees.Tree[NodeT]) -> bool:
+        """Return True while within the move-count budget."""
+        continue_base: bool = super().should_we_continue(tree=tree)
+
+        should_we: bool
+        if not continue_base:
+            should_we = continue_base
+        else:
+            should_we = tree.move_count < self.tree_move_limit
+        return should_we
+
+    def respectful_opening_instructions(
+        self,
+        opening_instructions: node_sel.OpeningInstructions[NodeT],
+        tree: trees.Tree[NodeT],
+    ) -> node_sel.OpeningInstructions[NodeT]:
+        """
+        Ensures the opening request do not exceed the stopping criterion
+
+
+        """
+        opening_instructions_subset: node_sel.OpeningInstructions[NodeT] = (
+            node_sel.OpeningInstructions()
+        )
+        opening_instructions.pop_items(
+            popped=opening_instructions_subset,
+            how_many=self.tree_move_limit - tree.move_count,
+        )
+        return opening_instructions_subset
+
+    def get_string_of_progress(self, tree: trees.Tree[NodeT]) -> str:
+        """
+        compute the string that display the progress in the terminal
+
+        Returns:
+            a string that display the progress in the terminal
+        """
+        return (
+            f"========= tree move counting: {tree.move_count} out of {self.tree_move_limit}"
+            f" |  {tree.move_count / self.tree_move_limit:.0%}"
+        )
+
+    def get_percent_of_progress(
+        self,
+        tree: trees.Tree[NodeT],
+    ) -> int:
+        """Return progress percentage based on move count."""
+        percent: int = int(tree.move_count / self.tree_move_limit * 100)
+        return percent
+
+
+@dataclass
+class DepthLimitArgs:
+    """
+    Arguments for the depth limit stopping criterion.
+
+    Attributes:
+        depth_limit (int): The maximum depth allowed for the search.
+    """
+
+    type: Literal[StoppingCriterionTypes.DEPTH_LIMIT]
+    depth_limit: int
+
+
+class DepthLimit[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]](
+    ProgressMonitor[NodeT]
+):
+    """
+    The stopping criterion based on a depth limit
+    """
+
+    depth_limit: int
+    node_selector: DepthToExpendP
+
+    def __init__(self, depth_limit: int, node_selector: DepthToExpendP) -> None:
+        """
+        Initializes a StoppingCriterion object.
+
+        Args:
+            depth_limit (int): The maximum depth to search in the tree.
+            node_selector (DepthToExpendP): The node selector used to determine which nodes to expand.
+
+        Returns:
+            None
+        """
+        self.depth_limit = depth_limit
+        self.node_selector = node_selector
+
+    def should_we_continue(self, tree: trees.Tree[NodeT]) -> bool:
+        """
+        Determines whether the search should continue expanding nodes in the tree.
+
+        Args:
+            tree (ValueTree): The tree containing the moves and their corresponding values.
+
+        Returns:
+            bool: True if the search should continue, False otherwise.
+        """
+        continue_base = super().should_we_continue(tree=tree)
+        if not continue_base:
+            return continue_base
+        return self.node_selector.get_current_depth_to_expand() < self.depth_limit
+
+    def get_string_of_progress(self, tree: trees.Tree[NodeT]) -> str:
+        """
+        compute the string that display the progress in the terminal
+
+        Returns:
+            a string that display the progress in the terminal
+        """
+        return (
+            "========= tree move counting: "
+            + str(tree.move_count)
+            + " | Depth: "
+            + str(self.node_selector.get_current_depth_to_expand())
+            + " out of "
+            + str(self.depth_limit)
+        )
+
+    def get_percent_of_progress(
+        self,
+        tree: trees.Tree[NodeT],
+    ) -> int:
+        """Return progress percentage based on current depth."""
+        # todo this percent is not precise
+        percent: int = int(
+            self.node_selector.get_current_depth_to_expand() / self.depth_limit * 100
+        )
+        return percent
+
+
+AllStoppingCriterionArgs = TreeMoveLimitArgs | DepthLimitArgs
+
+
+def create_stopping_criterion[NodeT: AlgorithmNode[Any]](
+    args: AllStoppingCriterionArgs,
+    node_selector: node_sel.NodeSelector[NodeT],
+) -> ProgressMonitor[NodeT]:
+    """
+    creating the stopping criterion
+
+    Args:
+        args:
+        node_selector:
+
+    Returns:
+        A stopping criterion
+
+    """
+    stopping_criterion: ProgressMonitor[NodeT]
+
+    match args.type:
+        case StoppingCriterionTypes.DEPTH_LIMIT:
+            assert isinstance(node_selector, DepthToExpendP)
+            assert isinstance(args, DepthLimitArgs)
+            stopping_criterion = DepthLimit(
+                depth_limit=args.depth_limit, node_selector=node_selector
+            )
+        case StoppingCriterionTypes.TREE_MOVE_LIMIT:
+            assert isinstance(args, TreeMoveLimitArgs)
+
+            stopping_criterion = TreeMoveLimit(tree_move_limit=args.tree_move_limit)
+        case _:
+            raise ValueError(
+                f"stopping criterion builder: can not find {args.type} in file {__name__}"
+            )
+
+    return stopping_criterion

anemone/recommender_rule/__init__.py

@@ -0,0 +1,12 @@
+"""
+This module provides classes for defining recommender rules.
+
+Classes:
+- RecommenderRule: Represents a recommender rule.
+- AllRecommendFunctionsArgs: Represents the arguments for all recommend functions.
+
+"""
+
+from .recommender_rule import AllRecommendFunctionsArgs, RecommenderRule
+
+__all__ = ["AllRecommendFunctionsArgs", "RecommenderRule"]

anemone/recommender_rule/recommender_rule.py

@@ -0,0 +1,140 @@
+"""
+This module defines recommender rules for selecting moves in a tree-based move selector.
+
+The recommender rules are implemented as data classes that define a `__call__` method. The `__call__` method takes a
+`ValueTree` object and a random generator, and returns a recommended chess move.
+
+The available recommender rule types are defined in the `RecommenderRuleTypes` enum.
+
+The module also defines a `RecommenderRule` protocol that all recommender rule classes must implement.
+
+Example usage:
+    rule = AlmostEqualLogistic(type=RecommenderRuleTypes.AlmostEqualLogistic, temperature=0.5)
+    move = rule(tree, random_generator)
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from random import Random
+from typing import Literal, Mapping, Protocol
+
+from valanga import BranchKey, State
+
+from anemone.nodes.algorithm_node.algorithm_node import (
+    AlgorithmNode,
+)
+from anemone.utils.small_tools import softmax
+
+
+@dataclass(frozen=True, slots=True)
+class BranchPolicy:
+    """
+    Represents a probability distribution over branches.
+    """
+
+    probs: Mapping[BranchKey, float]  # should sum to ~1.0
+
+
+def sample_from_policy(policy: BranchPolicy, rng: Random) -> BranchKey:
+    """Sample a branch key from a probability policy using a RNG."""
+    branches = list(policy.probs.keys())
+    weights = list(policy.probs.values())
+    return rng.choices(branches, weights=weights, k=1)[0]
+
+
+class RecommenderRule(Protocol):
+    """
+    Protocol for recommender rules.
+    """
+
+    type: str
+
+    def policy[StateT: State](self, root_node: AlgorithmNode[StateT]) -> BranchPolicy:
+        """Return the policy distribution for the root node."""
+        ...
+
+    def sample(self, policy: BranchPolicy, rng: Random) -> BranchKey:
+        """Sample a branch key using the provided RNG."""
+        ...
+
+
+class RecommenderRuleTypes(str, Enum):
+    """
+    Enum class that defines the available recommender rule types.
+    """
+
+    ALMOST_EQUAL_LOGISTIC = "almost_equal_logistic"
+    SOFTMAX = "softmax"
+
+
+# theses are functions but i still use dataclasses instead
+# of partial to be able to easily construct from yaml files using dacite
+
+
+@dataclass(slots=True)
+class AlmostEqualLogistic:
+    """
+    Almost Equal Logistic recommender rule that selects moves with nearly equal evaluations.
+    """
+
+    type: Literal["almost_equal_logistic"]
+    temperature: float  # kept for config compatibility; rule uses minmax method
+
+    def policy[StateT: State](self, root_node: AlgorithmNode[StateT]) -> BranchPolicy:
+        """Compute a policy based on near-equal best branches."""
+        best: list[BranchKey] = root_node.tree_evaluation.get_all_of_the_best_branches(
+            how_equal="almost_equal_logistic"
+        )
+
+        # Fallback: if empty, uniform over all existing children
+        if not best:
+            best = [
+                bk for bk, ch in root_node.branches_children.items() if ch is not None
+            ]
+
+        # If still empty, something is wrong (no legal moves / not expanded)
+        if not best:
+            return BranchPolicy(probs={})
+
+        p = 1.0 / len(best)
+        return BranchPolicy(probs={bk: p for bk in best})
+
+    def sample(self, policy: BranchPolicy, rng: Random) -> BranchKey:
+        """Sample a branch from the policy using the provided RNG."""
+        return sample_from_policy(policy, rng)
+
+
+@dataclass(slots=True)
+class SoftmaxRule:
+    """
+    Softmax recommender rule that computes a softmax distribution over child evaluations.
+    """
+
+    type: Literal["softmax"]
+    temperature: float
+
+    def policy[StateT: State](self, root_node: AlgorithmNode[StateT]) -> BranchPolicy:
+        """Compute a softmax policy over child evaluations."""
+        branches: list[BranchKey] = []
+        scores: list[float] = []
+
+        for bk, child in root_node.branches_children.items():
+            if child is None:
+                continue
+            branches.append(bk)
+            score = root_node.tree_evaluation.subjective_value_of(child.tree_evaluation)
+            scores.append(float(score))
+
+        if not branches:
+            return BranchPolicy(probs={})
+
+        probs_list = softmax(scores, self.temperature)  # list[float] or Sequence[float]
+        probs = {bk: float(p) for bk, p in zip(branches, probs_list, strict=True)}
+        return BranchPolicy(probs=probs)
+
+    def sample(self, policy: BranchPolicy, rng: Random) -> BranchKey:
+        """Sample a branch from the policy using the provided RNG."""
+        return sample_from_policy(policy, rng)
+
+
+AllRecommendFunctionsArgs = AlmostEqualLogistic | SoftmaxRule

anemone/search_factory/__init__.py

@@ -0,0 +1,14 @@
+"""
+This module provides factories for creating search objects and node selectors.
+
+The factories included in this module are:
+- SearchFactoryP: A factory for creating search objects with parallel execution.
+- SearchFactory: A factory for creating search objects with sequential execution.
+- NodeSelectorFactory: A factory for creating node selectors.
+
+To use this module, import the desired factory class from this module and use it to create the desired objects.
+"""
+
+from .search_factory import NodeSelectorFactory, SearchFactory, SearchFactoryP
+
+__all__ = ["SearchFactoryP", "SearchFactory", "NodeSelectorFactory"]