pathos-ai 0.1.0__py3-none-any.whl

pathos/__init__.py

@@ -0,0 +1,5 @@
+from pathos.core.space import Space
+from pathos.spaces.graph import GraphSpace
+from pathos.spaces.csp import CSPSpace
+from pathos.spaces.tour import TourSpace
+from pathos.spaces.game import GameSpace

pathos/algorithms/__init__.py

@@ -0,0 +1,7 @@
+from pathos.algorithms.base import Algorithm
+from pathos.algorithms.uninformed import BFS, DFS, IDDFS, UCS
+from pathos.algorithms.informed import AStar, IDAstar, GreedyBestFirst, WeightedAStar, BidirectionalAStar
+from pathos.algorithms.local import HillClimbing, TabuSearch, LocalBeamSearch
+from pathos.algorithms.evolutionary import SimulatedAnnealing, GeneticAlgorithm, DifferentialEvolution
+from pathos.algorithms.adversarial import Minimax, AlphaBeta, Negamax, MCTS
+from pathos.algorithms.csp import Backtracking, ForwardChecking, AC3, MinConflicts

pathos/algorithms/adversarial.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+import time
+import math
+import random
+from typing import Any
+from pathos.algorithms.base import Algorithm
+from pathos.core.capabilities import Capability
+from pathos.core.result import SearchResult
+from pathos.core.solver import register
+
+
+@register
+class Minimax(Algorithm):
+    """Minimax search for two-player zero-sum games.
+
+    Requires: successors, terminal, utility.
+
+    Attributes:
+        requires: Capability set needed.
+        power_rank: 40.
+    """
+
+    requires = frozenset({Capability.SUCCESSORS, Capability.TERMINAL, Capability.UTILITY})
+    power_rank = 40
+
+    def __init__(self, space: Any, max_depth: int = 100) -> None:
+        super().__init__(space)
+        self.max_depth = max_depth
+
+    def _minimax(self, state: Any, depth: int, is_max: bool) -> tuple[float, Any]:
+        if self.space._terminal(state) or depth == 0:
+            player = self.space._maximizing_player
+            return self.space._utility(state, player), state
+        moves = list(self.space._successors(state))
+        if not moves:
+            return self.space._utility(state, self.space._maximizing_player), state
+        if is_max:
+            best_val, best_state = -math.inf, None
+            for _, child in moves:
+                val, leaf = self._minimax(child, depth - 1, False)
+                if val > best_val:
+                    best_val, best_state = val, leaf
+            return best_val, best_state
+        else:
+            best_val, best_state = math.inf, None
+            for _, child in moves:
+                val, leaf = self._minimax(child, depth - 1, True)
+                if val < best_val:
+                    best_val, best_state = val, leaf
+            return best_val, best_state
+
+    def solve(self) -> SearchResult:
+        t0 = time.perf_counter()
+        val, state = self._minimax(self.space._initial, self.max_depth, True)
+        return SearchResult(state, None, val, "Minimax", 0, time.perf_counter() - t0, state is not None)
+
+
+@register
+class AlphaBeta(Algorithm):
+    """Alpha-Beta pruning — Minimax with branch pruning for efficiency.
+
+    Requires: successors, terminal, utility.
+
+    Attributes:
+        requires: Capability set needed.
+        power_rank: 45 (preferred over Minimax when available).
+    """
+
+    requires = frozenset({Capability.SUCCESSORS, Capability.TERMINAL, Capability.UTILITY})
+    power_rank = 45
+
+    def __init__(self, space: Any, max_depth: int = 100) -> None:
+        super().__init__(space)
+        self.max_depth = max_depth
+
+    def _ab(self, state: Any, depth: int, alpha: float, beta: float, is_max: bool) -> tuple[float, Any]:
+        if self.space._terminal(state) or depth == 0:
+            return self.space._utility(state, self.space._maximizing_player), state
+        moves = list(self.space._successors(state))
+        if not moves:
+            return self.space._utility(state, self.space._maximizing_player), state
+        best_state = None
+        if is_max:
+            val = -math.inf
+            for _, child in moves:
+                child_val, child_leaf = self._ab(child, depth - 1, alpha, beta, False)
+                if child_val > val:
+                    val, best_state = child_val, child_leaf
+                alpha = max(alpha, val)
+                if alpha >= beta:
+                    break
+        else:
+            val = math.inf
+            for _, child in moves:
+                child_val, child_leaf = self._ab(child, depth - 1, alpha, beta, True)
+                if child_val < val:
+                    val, best_state = child_val, child_leaf
+                beta = min(beta, val)
+                if alpha >= beta:
+                    break
+        return val, best_state
+
+    def solve(self) -> SearchResult:
+        t0 = time.perf_counter()
+        val, state = self._ab(self.space._initial, self.max_depth, -math.inf, math.inf, True)
+        return SearchResult(state, None, val, "AlphaBeta", 0, time.perf_counter() - t0, state is not None)
+
+
+@register
+class Negamax(Algorithm):
+    """Negamax — Minimax variant using score negation for multi-player support.
+
+    Requires: successors, terminal, utility.
+
+    Attributes:
+        requires: Capability set needed.
+        power_rank: 42.
+    """
+
+    requires = frozenset({Capability.SUCCESSORS, Capability.TERMINAL, Capability.UTILITY})
+    power_rank = 42
+
+    def __init__(self, space: Any, max_depth: int = 100) -> None:
+        super().__init__(space)
+        self.max_depth = max_depth
+
+    def _negamax(self, state: Any, depth: int, alpha: float, beta: float, player: int) -> tuple[float, Any]:
+        if self.space._terminal(state) or depth == 0:
+            val = self.space._utility(state, player)
+            return val, state
+        moves = list(self.space._successors(state))
+        if not moves:
+            return self.space._utility(state, player), state
+        best_val, best_state = -math.inf, moves[0][1]
+        next_player = (player + 1) % self.space._players
+        for _, child in moves:
+            child_val, _ = self._negamax(child, depth - 1, -beta, -alpha, next_player)
+            if -child_val > best_val:
+                best_val, best_state = -child_val, child
+            alpha = max(alpha, best_val)
+            if alpha >= beta:
+                break
+        return best_val, best_state
+
+    def solve(self) -> SearchResult:
+        t0 = time.perf_counter()
+        val, state = self._negamax(
+            self.space._initial, self.max_depth, -math.inf, math.inf,
+            self.space._maximizing_player
+        )
+        return SearchResult(state, None, val, "Negamax", 0, time.perf_counter() - t0, state is not None)
+
+
+class _MCTSNode:
+    __slots__ = ("state", "parent", "children", "visits", "value", "untried")
+
+    def __init__(self, state: Any, parent: _MCTSNode | None, space: Any) -> None:
+        self.state = state
+        self.parent = parent
+        self.children: list[_MCTSNode] = []
+        self.visits = 0
+        self.value = 0.0
+        self.untried = list(space._successors(state)) if not space._terminal(state) else []
+
+    def uct_score(self, c: float = 1.414) -> float:
+        if self.visits == 0:
+            return math.inf
+        assert self.parent is not None
+        return self.value / self.visits + c * math.sqrt(math.log(self.parent.visits) / self.visits)
+
+    def best_child(self) -> _MCTSNode:
+        return max(self.children, key=lambda n: n.uct_score())
+
+    def is_fully_expanded(self) -> bool:
+        return len(self.untried) == 0
+
+
+@register
+class MCTS(Algorithm):
+    """Monte Carlo Tree Search — simulation-based game tree exploration.
+
+    Requires: successors, terminal, utility.
+
+    Attributes:
+        requires: Capability set needed.
+        power_rank: 43.
+    """
+
+    requires = frozenset({Capability.SUCCESSORS, Capability.TERMINAL, Capability.UTILITY})
+    power_rank = 43
+
+    def __init__(self, space: Any, iterations: int = 1000) -> None:
+        super().__init__(space)
+        self.iterations = iterations
+
+    def solve(self) -> SearchResult:
+        t0 = time.perf_counter()
+        root = _MCTSNode(self.space._initial, None, self.space)
+
+        for _ in range(self.iterations):
+            node = self._select(root)
+            if not self.space._terminal(node.state):
+                node = self._expand(node)
+            reward = self._simulate(node.state)
+            self._backprop(node, reward)
+
+        best = max(root.children, key=lambda n: n.visits) if root.children else root
+        return SearchResult(
+            best.state, None,
+            self.space._utility(best.state, self.space._maximizing_player),
+            "MCTS", self.iterations, time.perf_counter() - t0, True,
+        )
+
+    def _select(self, node: _MCTSNode) -> _MCTSNode:
+        while not self.space._terminal(node.state) and node.is_fully_expanded():
+            node = node.best_child()
+        return node
+
+    def _expand(self, node: _MCTSNode) -> _MCTSNode:
+        action, child_state = node.untried.pop()
+        child = _MCTSNode(child_state, node, self.space)
+        node.children.append(child)
+        return child
+
+    def _simulate(self, state: Any) -> float:
+        depth = 0
+        while not self.space._terminal(state) and depth < 50:
+            moves = list(self.space._successors(state))
+            if not moves:
+                break
+            _, state = random.choice(moves)
+            depth += 1
+        result: float = self.space._utility(state, self.space._maximizing_player)
+        return result
+
+    def _backprop(self, node: _MCTSNode | None, reward: float) -> None:
+        while node is not None:
+            node.visits += 1
+            node.value += reward
+            node = node.parent

pathos/algorithms/base.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Any, TYPE_CHECKING
+from pathos.core.capabilities import Capability
+from pathos.core.result import SearchResult
+
+if TYPE_CHECKING:
+    from pathos.core.space import Space
+
+
+class Algorithm(ABC):
+    requires: frozenset[Capability] = frozenset()
+    power_rank: int = 0  # higher = preferred when multiple are compatible
+
+    def __init__(self, space: Space) -> None:
+        missing = self.requires - space.capabilities
+        if missing:
+            raise ValueError(
+                f"{self.__class__.__name__} requires capabilities: "
+                f"{', '.join(c.name for c in missing)}"
+            )
+        self.space = space
+        self._n_workers: int = space._n_workers
+
+    @abstractmethod
+    def solve(self) -> SearchResult:
+        ...
+
+    @classmethod
+    def compatible_with(cls, space: Space) -> bool:
+        return cls.requires <= space.capabilities
+
+    @classmethod
+    def score_for(cls, space: Space) -> float:
+        """Context-aware preference score for `space`. Higher = preferred.
+
+        The auto-solver picks the compatible algorithm with the highest
+        `score_for(space)`. Defaults to `float(power_rank)`, so any
+        algorithm that doesn't care about problem context keeps its
+        existing fixed-rank behavior.
+
+        Override to encode self-knowledge that isn't captured by the
+        coarse static rank — for example, "I work well on small problems
+        but lose to a sibling on large ones", or "without `@successors`
+        I degenerate to a no-op, so cede to siblings that don't need it".
+
+        Returning a value below `power_rank` lets the algorithm cede to
+        better-suited siblings without changing its global ordering.
+        """
+        return float(cls.power_rank)
+
+    def _goal_reached(self, state: Any) -> bool:
+        """Whether `state` satisfies the space's declared goal predicate.
+
+        If the space has no GOAL capability, returns True — the algorithm
+        terminated by its own stopping rule and there's no goal to check.
+        Otherwise consults `space._goal(state)`.
+
+        Used by local-search / metaheuristic algorithms (HC, Tabu, Beam, SA,
+        GA, DE) so they can't report `found=True` on a goal-bearing problem
+        when the best state they reached doesn't actually satisfy the goal.
+        """
+        if Capability.GOAL in self.space.capabilities:
+            return bool(self.space._goal(state))
+        return True

pathos/algorithms/csp.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+import time
+import random
+from typing import Any, cast
+from pathos.algorithms.base import Algorithm
+from pathos.core.capabilities import Capability
+from pathos.core.result import SearchResult
+from pathos.core.solver import register
+
+
+def _is_csp_shaped(space: Any) -> bool:
+    """True if state is a partial-assignment dict — the precondition for the
+    incremental-extension recursion used by Backtracking / ForwardChecking /
+    MinConflicts. Without this guard they're offered for any
+    successors+goal space and recurse forever (8-puzzle: RecursionError) or
+    silent-fail (MinConflicts on plain Space)."""
+    return isinstance(space._initial, dict)
+
+
+@register
+class Backtracking(Algorithm):
+    """Backtracking search — systematic recursive CSP solver.
+
+    Uses the space's successors as CSP expansion (typically via CSPSpace).
+
+    Requires: successors, goal.
+
+    Attributes:
+        requires: Capability set needed.
+        power_rank: 9.
+    """
+
+    requires = frozenset({Capability.SUCCESSORS, Capability.GOAL})
+    power_rank = 9
+
+    @classmethod
+    def compatible_with(cls, space: Any) -> bool:
+        return super().compatible_with(space) and _is_csp_shaped(space)
+
+    def _bt(self, state: Any, expanded: list[int]) -> Any | None:
+        if self.space._goal(state):
+            return state
+        for _, child in self.space._successors(state):
+            expanded[0] += 1
+            result = self._bt(child, expanded)
+            if result is not None:
+                return result
+        return None
+
+    def solve(self) -> SearchResult:
+        t0 = time.perf_counter()
+        expanded = [0]
+        result = self._bt(self.space._initial, expanded)
+        elapsed = time.perf_counter() - t0
+        if result is not None:
+            return SearchResult(result, None, None, "Backtracking", expanded[0], elapsed, True)
+        return SearchResult.not_found("Backtracking", expanded[0], elapsed)
+
+
+@register
+class ForwardChecking(Algorithm):
+    """Forward Checking — Backtracking with look-ahead pruning.
+
+    Before recursing, checks that each child has at least one valid successor.
+
+    The current look-ahead is shallow (a child is pruned only when it has no
+    successors and is not itself a goal), so node counts match plain
+    Backtracking and the constant factor is higher. Until real domain-level
+    pruning is implemented, FC is ranked below Backtracking so the auto-
+    solver picks the faster of the two.
+
+    Requires: successors, goal.
+
+    Attributes:
+        requires: Capability set needed.
+        power_rank: 8 (below Backtracking's 9).
+    """
+
+    requires = frozenset({Capability.SUCCESSORS, Capability.GOAL})
+    power_rank = 8
+
+    @classmethod
+    def compatible_with(cls, space: Any) -> bool:
+        return super().compatible_with(space) and _is_csp_shaped(space)
+
+    def _fc(self, state: Any, expanded: list[int]) -> Any | None:
+        if self.space._goal(state):
+            return state
+        children = list(self.space._successors(state))
+        if not children:
+            return None
+        for _, child in children:
+            expanded[0] += 1
+            # check if any successor exists from child (look-ahead)
+            future = list(self.space._successors(child))
+            if future or self.space._goal(child):
+                result = self._fc(child, expanded)
+                if result is not None:
+                    return result
+        return None
+
+    def solve(self) -> SearchResult:
+        t0 = time.perf_counter()
+        expanded = [0]
+        result = self._fc(self.space._initial, expanded)
+        elapsed = time.perf_counter() - t0
+        if result is not None:
+            return SearchResult(result, None, None, "ForwardChecking", expanded[0], elapsed, True)
+        return SearchResult.not_found("ForwardChecking", expanded[0], elapsed)
+
+
+class AC3(Algorithm):
+    """AC-3 arc consistency — domain-pruning preprocessor for CSPs.
+
+    AC-3 is not a stand-alone CSP solver: it iterates over arcs and prunes
+    domain values that can't satisfy any binary constraint, then hands off
+    a (possibly smaller) problem to Backtracking / ForwardChecking. It is
+    intentionally NOT @register'd so the auto-selector won't pick it as a
+    terminal solver — its `solve()` returns the pruned domains, not an
+    assignment, so power_rank=22 would mis-rank it above MinConflicts.
+
+    Use directly: `AC3(csp_space).solve()` returns a SearchResult whose
+    `.solution` is the pruned-domain dict. Production code typically
+    composes AC-3 with a Backtracking-style solver — see issue tracker
+    for the planned `pathos.algorithms.preprocessors` API.
+    """
+    requires = frozenset({Capability.VARIABLES, Capability.DOMAINS, Capability.CONSTRAINTS})
+    power_rank = 22
+
+    def solve(self) -> SearchResult:
+        from pathos.spaces.csp import CSPSpace
+        t0 = time.perf_counter()
+        # This is invoked by CSPSpace which sets up the variables/domains/constraints
+        csp = cast(CSPSpace, self.space)
+        variables = csp._variables()
+        domains: dict[Any, list[Any]] = {v: list(csp._domain(v)) for v in variables}
+        arcs = [(xi, xj) for xi in variables for xj in variables if xi != xj]
+        queue = list(arcs)
+
+        while queue:
+            xi, xj = queue.pop(0)
+            if self._revise(domains, xi, xj, csp):
+                if not domains[xi]:
+                    return SearchResult.not_found("AC3", 0, time.perf_counter() - t0)
+                for xk in variables:
+                    if xk != xi and xk != xj:
+                        queue.append((xk, xi))
+
+        return SearchResult(domains, None, None, "AC3", 0, time.perf_counter() - t0, True)
+
+    def _revise(self, domains: dict[Any, list[Any]], xi: Any, xj: Any, csp: Any) -> bool:
+        revised = False
+        for x in domains[xi][:]:
+            if not any(csp._constraints({xi: x, xj: y}) for y in domains[xj]):
+                domains[xi].remove(x)
+                revised = True
+        return revised
+
+
+@register
+class MinConflicts(Algorithm):
+    """Min-Conflicts heuristic — local repair CSP solver.
+
+    Repeatedly selects the neighbor that minimizes constraint violations.
+
+    Requires: successors, goal, evaluate.
+
+    Attributes:
+        requires: Capability set needed.
+        power_rank: 19.
+    """
+
+    requires = frozenset({Capability.SUCCESSORS, Capability.GOAL, Capability.EVALUATE})
+    power_rank = 19
+
+    @classmethod
+    def compatible_with(cls, space: Any) -> bool:
+        return super().compatible_with(space) and _is_csp_shaped(space)
+
+    def __init__(self, space: Any, max_iter: int = 1000) -> None:
+        super().__init__(space)
+        self.max_iter = max_iter
+
+    def solve(self) -> SearchResult:
+        t0 = time.perf_counter()
+        current = self.space._initial
+
+        for i in range(self.max_iter):
+            if self.space._goal(current):
+                return SearchResult(current, None, 0.0, "MinConflicts", i, time.perf_counter() - t0, True)
+            neighbors = list(self.space._successors(current))
+            if not neighbors:
+                break
+            _, current = min(neighbors, key=lambda ac: self.space._evaluate(ac[1]))
+
+        return SearchResult.not_found("MinConflicts", self.max_iter, time.perf_counter() - t0)