Skip to content

PATHOS

Production-ready classical AI search algorithms for Python — no machine learning, pure search.

CI PyPI Python License: MIT

PATHOS is problem-centric: you declare what your problem can do with decorator hooks; the auto-solver picks the best compatible algorithm.

from pathos import Space

space = Space().initial("Madrid")

@space.successors
def neighbors(city):
    for next_city, km in roads[city]:
        yield next_city, next_city

@space.goal
def reached(city): return city == "Lisboa"

@space.heuristic
def h(city): return straight_line_km(city, "Lisboa")

# Default mode is anytime — returns proven optimal if it finishes,
# best incumbent if the budget runs out. Never not_found if any
# feasible path exists.
result = space.solver(timeout=10).solve()
print(result.path, result.cost, result.algorithm, result.optimal)

Install

pip install pathos-ai

Requires Python 3.11+. MIT license.

Highlights

  • Problem-centric

    Declare your problem's structure with decorators. The solver figures out which algorithm fits.

    Getting started

  • Anytime by default

    solver().solve() runs a cascade tuned to your problem family (informed, local, CSP, adversarial) and always delivers the best incumbent within your budget — never not_found when a feasible answer exists.

    Modes & anytime

  • Cooperative cancellation

    Every algorithm checks a cancel token in its main loop. Set a timeout and metaheuristics return their best individual seen — automatically.

    Cancel-token protocol

  • Comprehensive coverage

    Uninformed (BFS, DFS, IDDFS, UCS), informed (A*, IDA*, WAStar, Greedy, Bidirectional), local search (HC, Tabu, Beam), evolutionary (GA, DE, PSO, SA), adversarial (Minimax, AlphaBeta, MCTS), CSP (Backtracking, FC, MC).

    API reference

Algorithm families

Declare Algorithms available
@evaluate SA, GA, DE, PSO
@successors + @goal BFS, DFS, IDDFS (DFS is non-optimal — for shortest paths prefer BFS/UCS)
@successors + @evaluate AnytimeLocal (default under mode="auto"), HillClimbing, TabuSearch, LocalBeamSearch, SimulatedAnnealing
@successors + @goal + @heuristic GreedyBestFirst
@successors + @goal + @heuristic + @evaluate AnytimeAStar (default under mode="auto"), AStar, IDAstar, WeightedAStar, BidirectionalAStar, UCS
.adversarial() + @terminal + @utility AnytimeAdversarial (default under mode="auto"), Minimax, AlphaBeta, Negamax, MCTS
CSPSpace + @constraint AnytimeCSP (default under mode="auto"), Backtracking, ForwardChecking, MinConflicts