aialgos 0.1.0__tar.gz

aialgos-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: aialgos
+Version: 0.1.0
+Summary: Beginner-friendly AI search algorithms: BFS, DFS, A*, Minimax, CSP, ANN and more
+Author-email: Qasim Alvi <qasimalvio685@email.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mQasim04/aialgos
+Project-URL: Repository, https://github.com/mQasim04/aialgos
+Project-URL: Issues, https://github.com/mQasim04/aialgos/issues
+Keywords: ai,artificial-intelligence,search,algorithms,bfs,dfs,a-star,minimax,csp,neural-network,machine-learning,education,beginners
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# aialgos 🤖
+
+A **beginner-friendly** Python library covering the core AI algorithms taught in university courses.
+
+**Zero dependencies** — pure Python, works everywhere.
+
+```bash
+pip install aialgos
+```
+
+---
+
+## What's inside?
+
+| Module | Algorithms |
+|--------|-----------|
+| `uninformed` | BFS, DFS, DLS, UCS, Bidirectional BFS |
+| `informed` | Greedy Best-First, A* |
+| `adversarial` | Minimax, Alpha-Beta Pruning |
+| `beyond_classical` | Hill Climbing, Steepest-Ascent HC, Simulated Annealing, Local Beam Search |
+| `csp` | Backtracking, Forward Checking, MRV, LCV, Degree Heuristic |
+| `ann` | Feedforward Neural Network (from scratch) |
+
+---
+
+## Quick Start
+
+### Uninformed Search (BFS)
+
+```python
+from aialgos import bfs
+
+graph = {
+    'A': ['B', 'C'],
+    'B': ['D', 'E'],
+    'C': ['F'],
+    'D': [], 'E': [], 'F': []
+}
+
+path = bfs(graph, start='A', goal='E')
+print(path)  # ['A', 'B', 'E']
+```
+
+### Informed Search (A*)
+
+```python
+from aialgos import a_star
+
+graph = {
+    'A': [('B', 1), ('C', 4)],
+    'B': [('D', 5)],
+    'C': [('D', 1)],
+    'D': []
+}
+heuristic = {'A': 4, 'B': 3, 'C': 1, 'D': 0}
+
+path, cost = a_star(graph, 'A', 'D', heuristic)
+print(path, cost)  # ['A', 'C', 'D'] 5
+```
+
+### Adversarial Search (Minimax)
+
+```python
+from aialgos import minimax
+
+# Game tree as nested lists (leaf values: positive=MAX wins)
+tree = {'A': ['B', 'C'], 'B': ['D', 'E'], 'C': ['F', 'G'],
+        'D': 3, 'E': 5, 'F': 2, 'G': 9}
+
+def get_children(node):
+    v = tree[node]
+    return v if isinstance(v, list) else []
+
+def evaluate(node):
+    v = tree[node]
+    return v if isinstance(v, int) else 0
+
+score = minimax('A', depth=0, is_maximizing=True,
+                get_children=get_children, evaluate=evaluate, max_depth=2)
+print(score)  # 5
+```
+
+### Neural Network (ANN)
+
+```python
+from aialgos import NeuralNetwork
+
+# Solve XOR problem
+nn = NeuralNetwork([2, 4, 1], learning_rate=0.1)
+
+X = [[0,0], [0,1], [1,0], [1,1]]
+y = [[0],   [1],   [1],   [0]]
+
+nn.train(X, y, epochs=2000, print_every=500)
+
+print(nn.predict([0, 1]))  # ≈ [0.95]
+print(nn.predict([0, 0]))  # ≈ [0.05]
+```
+
+### CSP (Map Coloring)
+
+```python
+from aialgos import forward_checking
+
+variables = ['WA', 'NT', 'SA', 'Q', 'NSW', 'V']
+domains   = {v: ['Red', 'Green', 'Blue'] for v in variables}
+
+def diff(a, b): return a != b
+
+constraints_map = {
+    'WA':  [('NT', diff), ('SA', diff)],
+    'NT':  [('WA', diff), ('SA', diff), ('Q', diff)],
+    'SA':  [('WA', diff), ('NT', diff), ('Q', diff), ('NSW', diff), ('V', diff)],
+    'Q':   [('NT', diff), ('SA', diff), ('NSW', diff)],
+    'NSW': [('Q',  diff), ('SA', diff), ('V', diff)],
+    'V':   [('SA', diff), ('NSW', diff)],
+}
+
+result = forward_checking(variables, domains, constraints_map)
+print(result)  # {'WA': 'Red', 'NT': 'Green', 'SA': 'Blue', ...}
+```
+
+---
+
+## Installation
+
+```bash
+pip install aialgos
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/mQasim04/aialgos
+cd aialgos
+pip install -e .
+```
+
+---
+
+## Similar Libraries
+
+| Library | Focus |
+|---------|-------|
+| `aima3` | Textbook algorithms (Russell & Norvig) - less beginner-friendly |
+| `networkx` | Graph algorithms only |
+| `python-constraint` | CSP only |
+| `scikit-learn` | ML — no search algorithms |
+| **aialgos** | All-in-one, beginner-focused, zero dependencies |
+
+---
+
+## License
+
+MIT — free to use in education and projects.

aialgos-0.1.0/README.md

@@ -0,0 +1,155 @@
+# aialgos 🤖
+
+A **beginner-friendly** Python library covering the core AI algorithms taught in university courses.
+
+**Zero dependencies** — pure Python, works everywhere.
+
+```bash
+pip install aialgos
+```
+
+---
+
+## What's inside?
+
+| Module | Algorithms |
+|--------|-----------|
+| `uninformed` | BFS, DFS, DLS, UCS, Bidirectional BFS |
+| `informed` | Greedy Best-First, A* |
+| `adversarial` | Minimax, Alpha-Beta Pruning |
+| `beyond_classical` | Hill Climbing, Steepest-Ascent HC, Simulated Annealing, Local Beam Search |
+| `csp` | Backtracking, Forward Checking, MRV, LCV, Degree Heuristic |
+| `ann` | Feedforward Neural Network (from scratch) |
+
+---
+
+## Quick Start
+
+### Uninformed Search (BFS)
+
+```python
+from aialgos import bfs
+
+graph = {
+    'A': ['B', 'C'],
+    'B': ['D', 'E'],
+    'C': ['F'],
+    'D': [], 'E': [], 'F': []
+}
+
+path = bfs(graph, start='A', goal='E')
+print(path)  # ['A', 'B', 'E']
+```
+
+### Informed Search (A*)
+
+```python
+from aialgos import a_star
+
+graph = {
+    'A': [('B', 1), ('C', 4)],
+    'B': [('D', 5)],
+    'C': [('D', 1)],
+    'D': []
+}
+heuristic = {'A': 4, 'B': 3, 'C': 1, 'D': 0}
+
+path, cost = a_star(graph, 'A', 'D', heuristic)
+print(path, cost)  # ['A', 'C', 'D'] 5
+```
+
+### Adversarial Search (Minimax)
+
+```python
+from aialgos import minimax
+
+# Game tree as nested lists (leaf values: positive=MAX wins)
+tree = {'A': ['B', 'C'], 'B': ['D', 'E'], 'C': ['F', 'G'],
+        'D': 3, 'E': 5, 'F': 2, 'G': 9}
+
+def get_children(node):
+    v = tree[node]
+    return v if isinstance(v, list) else []
+
+def evaluate(node):
+    v = tree[node]
+    return v if isinstance(v, int) else 0
+
+score = minimax('A', depth=0, is_maximizing=True,
+                get_children=get_children, evaluate=evaluate, max_depth=2)
+print(score)  # 5
+```
+
+### Neural Network (ANN)
+
+```python
+from aialgos import NeuralNetwork
+
+# Solve XOR problem
+nn = NeuralNetwork([2, 4, 1], learning_rate=0.1)
+
+X = [[0,0], [0,1], [1,0], [1,1]]
+y = [[0],   [1],   [1],   [0]]
+
+nn.train(X, y, epochs=2000, print_every=500)
+
+print(nn.predict([0, 1]))  # ≈ [0.95]
+print(nn.predict([0, 0]))  # ≈ [0.05]
+```
+
+### CSP (Map Coloring)
+
+```python
+from aialgos import forward_checking
+
+variables = ['WA', 'NT', 'SA', 'Q', 'NSW', 'V']
+domains   = {v: ['Red', 'Green', 'Blue'] for v in variables}
+
+def diff(a, b): return a != b
+
+constraints_map = {
+    'WA':  [('NT', diff), ('SA', diff)],
+    'NT':  [('WA', diff), ('SA', diff), ('Q', diff)],
+    'SA':  [('WA', diff), ('NT', diff), ('Q', diff), ('NSW', diff), ('V', diff)],
+    'Q':   [('NT', diff), ('SA', diff), ('NSW', diff)],
+    'NSW': [('Q',  diff), ('SA', diff), ('V', diff)],
+    'V':   [('SA', diff), ('NSW', diff)],
+}
+
+result = forward_checking(variables, domains, constraints_map)
+print(result)  # {'WA': 'Red', 'NT': 'Green', 'SA': 'Blue', ...}
+```
+
+---
+
+## Installation
+
+```bash
+pip install aialgos
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/mQasim04/aialgos
+cd aialgos
+pip install -e .
+```
+
+---
+
+## Similar Libraries
+
+| Library | Focus |
+|---------|-------|
+| `aima3` | Textbook algorithms (Russell & Norvig) - less beginner-friendly |
+| `networkx` | Graph algorithms only |
+| `python-constraint` | CSP only |
+| `scikit-learn` | ML — no search algorithms |
+| **aialgos** | All-in-one, beginner-focused, zero dependencies |
+
+---
+
+## License
+
+MIT — free to use in education and projects.

aialgos-0.1.0/aialgos/__init__.py

@@ -0,0 +1,49 @@
+"""
+aialgos - A beginner-friendly AI algorithms library
+====================================================
+Topics covered:
+  - Uninformed Searches (BFS, DFS, DLS, UCS, Bidirectional)
+  - Informed Searches (Greedy Best-First, A*)
+  - Adversarial Searches (Minimax, Alpha-Beta Pruning)
+  - Beyond Classical Searches (Hill Climbing, Simulated Annealing, LBS)
+  - CSP (Backtracking, Forward Checking, MRV, LCV, Degree Heuristic)
+  - ANN (Artificial Neural Networks)
+"""
+
+from aialgos.uninformed import bfs, dfs, dls, ucs, bidirectional_bfs
+from aialgos.informed import greedy_best_first, a_star
+from aialgos.adversarial import minimax, alpha_beta_pruning
+from aialgos.beyond_classical import (
+    hill_climbing,
+    steepest_ascent_hill_climbing,
+    simulated_annealing,
+    local_beam_search,
+)
+from aialgos.csp import (
+    backtracking_search,
+    forward_checking,
+    select_mrv,
+    order_lcv,
+    degree_heuristic,
+)
+from aialgos.ann import NeuralNetwork
+
+__version__ = "0.1.0"
+__author__ = "Muhammad Qasim Alvi"
+
+__all__ = [
+    # Uninformed
+    "bfs", "dfs", "dls", "ucs", "bidirectional_bfs",
+    # Informed
+    "greedy_best_first", "a_star",
+    # Adversarial
+    "minimax", "alpha_beta_pruning",
+    # Beyond Classical
+    "hill_climbing", "steepest_ascent_hill_climbing",
+    "simulated_annealing", "local_beam_search",
+    # CSP
+    "backtracking_search", "forward_checking",
+    "select_mrv", "order_lcv", "degree_heuristic",
+    # ANN
+    "NeuralNetwork",
+]

aialgos-0.1.0/aialgos/adversarial/__init__.py

@@ -0,0 +1,170 @@
+"""
+Adversarial Search Algorithms
+===============================
+Used in two-player zero-sum games (like Tic-Tac-Toe, Chess).
+One player tries to MAXIMIZE score, the other tries to MINIMIZE it.
+
+Algorithms:
+  - Minimax
+  - Alpha-Beta Pruning (faster Minimax)
+"""
+
+
+def minimax(state, depth, is_maximizing, get_children, evaluate, max_depth):
+    """
+    Minimax Algorithm
+    -----------------
+    The MAX player picks the move with the highest score.
+    The MIN player picks the move with the lowest score.
+    Explores the full game tree up to max_depth.
+
+    Parameters:
+        state           : Current game state (any format — board, dict, etc.)
+        depth      (int): Current depth in the game tree (start with 0).
+        is_maximizing (bool): True if current player is the maximizer.
+        get_children (callable): Function(state) → list of child states.
+        evaluate     (callable): Function(state) → numeric score.
+                                 Positive = good for MAX, negative = good for MIN.
+        max_depth    (int): How many levels deep to search.
+
+    Returns:
+        int: The best score achievable from this state.
+
+    Example (Tic-Tac-Toe style):
+        >>> # See examples/adversarial_example.py for a full game demo
+        >>> def get_children(state): return [state + [i] for i in range(3)]
+        >>> def evaluate(state): return len(state) % 2  # dummy eval
+        >>> minimax([], 0, True, get_children, evaluate, max_depth=2)
+        1
+    """
+    # Base case: reached depth limit or terminal state
+    if depth == max_depth or not get_children(state):
+        return evaluate(state)
+
+    if is_maximizing:
+        best = float('-inf')
+        for child in get_children(state):
+            score = minimax(child, depth + 1, False, get_children, evaluate, max_depth)
+            best = max(best, score)
+        return best
+    else:
+        best = float('inf')
+        for child in get_children(state):
+            score = minimax(child, depth + 1, True, get_children, evaluate, max_depth)
+            best = min(best, score)
+        return best
+
+
+def minimax_best_move(state, get_children, evaluate, max_depth):
+    """
+    Find the best move using Minimax (for the maximizing player).
+
+    Parameters:
+        state           : Current game state.
+        get_children (callable): Function(state) → list of child states.
+        evaluate     (callable): Function(state) → numeric score.
+        max_depth    (int): How many levels deep to search.
+
+    Returns:
+        The child state (move) with the best minimax score.
+
+    Example:
+        >>> # See examples/adversarial_example.py for Tic-Tac-Toe demo
+    """
+    best_score = float('-inf')
+    best_child = None
+
+    for child in get_children(state):
+        score = minimax(child, 1, False, get_children, evaluate, max_depth)
+        if score > best_score:
+            best_score = score
+            best_child = child
+
+    return best_child
+
+
+def alpha_beta_pruning(state, depth, alpha, beta, is_maximizing,
+                       get_children, evaluate, max_depth):
+    """
+    Alpha-Beta Pruning
+    ------------------
+    An optimized version of Minimax. Skips branches that cannot
+    affect the final decision — often searches TWICE AS DEEP in the
+    same time as plain Minimax.
+
+    alpha = best score MAX can guarantee so far (starts at -inf)
+    beta  = best score MIN can guarantee so far (starts at +inf)
+    If alpha >= beta, prune (stop exploring that branch).
+
+    Parameters:
+        state           : Current game state.
+        depth      (int): Current depth (start with 0).
+        alpha    (float): Alpha value (start with float('-inf')).
+        beta     (float): Beta value  (start with float('inf')).
+        is_maximizing (bool): True if current player is the maximizer.
+        get_children (callable): Function(state) → list of child states.
+        evaluate     (callable): Function(state) → numeric score.
+        max_depth    (int): How many levels deep to search.
+
+    Returns:
+        int: Best achievable score.
+
+    Example:
+        >>> score = alpha_beta_pruning(
+        ...     state=[], depth=0,
+        ...     alpha=float('-inf'), beta=float('inf'),
+        ...     is_maximizing=True,
+        ...     get_children=lambda s: [s+[i] for i in range(3)],
+        ...     evaluate=lambda s: len(s) % 2,
+        ...     max_depth=2
+        ... )
+    """
+    if depth == max_depth or not get_children(state):
+        return evaluate(state)
+
+    if is_maximizing:
+        value = float('-inf')
+        for child in get_children(state):
+            score = alpha_beta_pruning(child, depth + 1, alpha, beta,
+                                       False, get_children, evaluate, max_depth)
+            value = max(value, score)
+            alpha = max(alpha, value)
+            if beta <= alpha:
+                break  # Beta cutoff — MIN won't allow this branch
+        return value
+    else:
+        value = float('inf')
+        for child in get_children(state):
+            score = alpha_beta_pruning(child, depth + 1, alpha, beta,
+                                       True, get_children, evaluate, max_depth)
+            value = min(value, score)
+            beta = min(beta, value)
+            if beta <= alpha:
+                break  # Alpha cutoff — MAX won't allow this branch
+        return value
+
+
+def alpha_beta_best_move(state, get_children, evaluate, max_depth):
+    """
+    Find the best move using Alpha-Beta Pruning (for the maximizer).
+
+    Parameters:
+        state           : Current game state.
+        get_children (callable): Function(state) → list of child states.
+        evaluate     (callable): Function(state) → numeric score.
+        max_depth    (int): How many levels deep to search.
+
+    Returns:
+        The child state (move) with the best alpha-beta score.
+    """
+    best_score = float('-inf')
+    best_child = None
+
+    for child in get_children(state):
+        score = alpha_beta_pruning(child, 1, float('-inf'), float('inf'),
+                                   False, get_children, evaluate, max_depth)
+        if score > best_score:
+            best_score = score
+            best_child = child
+
+    return best_child