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.
