Metadata-Version: 2.4
Name: aalgoi
Version: 1.1.1
Summary: Artificial Algorithm Intelligence - Self-Adaptive Algorithm Selection & Universal Problem Solving
Author: AAlgoI Team
License: MIT
Project-URL: Homepage, https://github.com/RayAKaan/AAlgoI
Project-URL: Repository, https://github.com/RayAKaan/AAlgoI
Keywords: algorithm,meta-learning,optimization,AI,pipeline
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-image>=0.19.0
Requires-Dist: chromadb>=1.5.0
Requires-Dist: networkx>=3.0
Requires-Dist: requests>=2.28.0
Requires-Dist: click>=8.1.0
Provides-Extra: llm
Requires-Dist: ollama; extra == "llm"
Provides-Extra: web
Requires-Dist: gradio; extra == "web"
Requires-Dist: fastapi; extra == "web"
Requires-Dist: uvicorn; extra == "web"
Provides-Extra: rl
Requires-Dist: torch>=2.0.0; extra == "rl"
Requires-Dist: gymnasium>=0.28.0; extra == "rl"
Provides-Extra: full
Requires-Dist: chromadb>=1.5.0; extra == "full"
Requires-Dist: networkx>=3.0; extra == "full"
Requires-Dist: requests>=2.25.0; extra == "full"
Requires-Dist: ollama; extra == "full"
Requires-Dist: gradio; extra == "full"
Requires-Dist: fastapi; extra == "full"
Requires-Dist: uvicorn; extra == "full"
Requires-Dist: torch>=2.0.0; extra == "full"
Requires-Dist: gymnasium>=0.28.0; extra == "full"
Dynamic: license-file
Dynamic: requires-python

# AAlgoI — Adaptive Algorithm Intelligence

**Artificial Algorithm Intelligence** — a self-adaptive system that automatically selects, executes, and learns from the best algorithm for any given problem. Combining reinforcement learning, a semantic knowledge graph, and a growing registry of 20+ algorithms across sorting, pathfinding, optimization, and machine learning domains.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-226%20passing-brightgreen.svg)](tests/)

---

## Features

- **Algorithm Selector** — PPO-based RL agent picks the optimal algorithm from 20+ candidates based on problem type and data patterns
- **Semantic Knowledge Graph** — NetworkX-powered graph encoding relationships (Problem → Algorithm → Pattern → Constraint) that constrains RL choices and provides fallback alternatives
- **Pre-Trained Model** — 3-stage pipeline (supervised + RL curriculum + self-play) produces a 0.72 MB model with ~0.6 ms inference, validated on sorting, pathfinding, and domain routing (100% accuracy)
- **Self-Learning** — Every execution records feedback (quality, timing, success) to personalize the model via fine-tuning and bandit updates
- **Algorithm Marketplace** — Discover, register, benchmark, and share custom algorithms across instances
- **Natural Language Interface** — `question_parser.py` converts English descriptions into structured problem specs
- **Federated Learning** — Optional P2P or central-server mode for cross-instance knowledge sharing
- **Rich CLI** — `solve`, `benchmark`, `marketplace`, `ml`, `debug`, and more
- **226 Passing Tests** — CI-verified test suite

---

## Quick Start

```bash
# Install
pip install aalgoi

# Solve a problem by description
aalgoi solve "sort this list of numbers" --data 3,1,4,1,5,9,2,6,5,3,5

# Solve with explicit spec
aalgoi solve-spec --type sorting --data 5,2,8,1,9
```

---

## Python API

After `pip install aalgoi`, the simplest usage is one line:

```python
from aalgoi import solve

result = solve("sort ascending", [3, 1, 4, 1, 5])
print(result["result"])       # [1, 1, 3, 4, 5]
print(result["algorithm"])    # "insertion_sort"
print(result["time_ms"])      # 1.2
print(result["success"])      # True
```

The `result` dict always has these keys: `result`, `algorithm`, `time_ms`, `success`, `answer` (a human-readable summary from SmartSolver).

### Sorting

```python
from aalgoi import solve

# Basic sort
solve("sort these numbers", [5, 3, 8, 1, 2])
# → algorithm picks insertion_sort, quicksort, timsort, etc.

# With priority on speed
solve("sort as fast as possible", [5, 3, 8, 1, 2])
# → parser detects "fast" → adds objective minimize execution_time

# Large data
solve("sort this list", list(range(10000, 0, -1)))
# → RL agent picks quicksort or timsort for large reverse-sorted data

# Already-sorted data (adaptive handling)
solve("sort this", [1, 2, 3, 4, 5])
# → context_engine detects is_sorted=True, RL picks timsort (O(n))
```

### Pathfinding

```python
from aalgoi import solve

graph = {
    "A": {"B": 5, "C": 2},
    "B": {"D": 4},
    "C": {"B": 1, "D": 7},
    "D": {}
}

# Auto-detects PATHFINDING from data shape
result = solve("find shortest path from A to D", graph)
print(result["algorithm"])    # "dijkstra" or "a_star"
print(result["result"])       # ['A', 'C', 'B', 'D']  (shortest path)

# Explicit question
result = solve("shortest path from A to D", graph)
print(result["algorithm"])    # "dijkstra"
```

### Optimization (Knapsack)

```python
from aalgoi import solve

items = [
    {"value": 60, "weight": 10},
    {"value": 100, "weight": 20},
    {"value": 120, "weight": 30},
]

result = solve("maximize value within capacity 50", {
    "items": items,
    "capacity": 50
})
print(result["algorithm"])              # "greedy_knapsack"
print(result["result"]["selected"])      # [1, 2]
print(result["result"]["value"])         # 220
```

### Using ProblemSpec

```python
from aalgoi import solve_spec, ProblemSpec, ProblemType

spec = ProblemSpec(
    name="custom_sort",
    problem_type=ProblemType.SORTING,
)

result = solve_spec(spec, [3, 1, 2])
print(result["result"])  # [1, 2, 3]
```

### SmartSolver (with explanation)

```python
from aalgoi import SmartSolver

solver = SmartSolver()
result = solver.ask("sort this list quickly", [4, 2, 7, 1])

print(result["answer"])
# "Solved using timsort in 0.57ms."

print(result["algorithm"])  # "timsort"
print(result["time_ms"])    # 0.57
```

### Explaining an algorithm

```python
from aalgoi import explain, solve

result = solve("sort these", [3, 1, 2])
exp = explain(result)          # extracts algorithm name from result
print(exp.summary)
# "Timsort is a stable hybrid sorting algorithm..."

# Direct by name
exp = explain("quicksort")
print(exp.complexity)   # "O(n log n) average, O(n²) worst case"
print(exp.steps)        # ["Choose a pivot...", "Partition...", "Recursively apply..."]
```

### Benchmarking

```python
from aalgoi import benchmark, ProblemSpec, ProblemType

spec = ProblemSpec(name="test", problem_type=ProblemType.SORTING)
bm = benchmark(spec, [5, 3, 1, 4, 2])
print(bm["winner"])            # "Baseline" (or "AAlgoI")
print(bm["aalgoi_algorithm"])  # "insertion_sort"
```

### Registering a custom algorithm

```python
from aalgoi import UniversalSolver
from algorithms.base import Algorithm

class MySorter(Algorithm):
    def __init__(self):
        super().__init__()
        self.name = "my_sorter"
        self.time_complexity = "O(n log n)"

    def process(self, data):
        return sorted(data)

    def validate_output(self, input_data, output_data):
        return all(output_data[i] <= output_data[i+1]
                   for i in range(len(output_data)-1))

solver = UniversalSolver()
solver.register_algorithm(MySorter())

# RL agent now considers it alongside the 20 built-in algorithms
result = solver.solve(ProblemSpec(name="x", problem_type=ProblemType.SORTING), [3, 1, 2])
```

### Quick reference — problem type detection

Each call auto-detects the problem type from the data + question text, selects the optimal algorithm via the PPO policy, executes it, stores the experience for online RL training (every 20 solves), and returns the result.

```python
from aalgoi import solve

sorting       = solve("sort this", [3, 1, 2])
pathfinding   = solve("find path from A to B", {"A": {"B": 1}, "B": {}})
optimization  = solve("maximize value", {"items": [...], "capacity": 10})
clustering    = solve("cluster this data", [[1, 2], [5, 8], [1.5, 1.8]])
word2vec      = solve("train word2vec on medical corpus with 200 dimensions",
                      {"corpus": ["heart disease treatment", "lung cancer diagnosis"]})
image_blur    = solve("blur this image", image_array)
```

---

## Installation

### From PyPI

```bash
pip install aalgoi
```

For optional features:

```bash
pip install aalgoi[rl]       # Reinforcement learning (PyTorch)
pip install aalgoi[llm]      # LLM integration (Ollama)
```

### From Source

```bash
git clone https://github.com/RayAKaan/AAlgoI.git
cd AAlgoI
pip install -e .
```

### Dependencies

Core: numpy, scikit-learn, networkx, chromadb, click, psutil
RL (optional): torch>=2.0.0

---

## Architecture

```
User Input (CLI)
        │
        ▼
┌───────────────────┐
│   SmartSolver     │  Natural language → ProblemSpec
│ question_parser   │  Zero-shot + keyword fallback
└─────────┬─────────┘
          │
          ▼
┌────────────────────────────────────────────┐
│        UniversalMetaController             │
│                                            │
│  ┌──────────┐   ┌──────────────────┐       │
│  │ RL Agent │   │ Knowledge Graph   │       │
│  │ (PPO)    │   │ (read-only filter)│       │
│  │ 20-action│   │ Problem→Algorithm │       │
│  │ softmax  │   │ Algorithm→Pattern │       │
│  └────┬─────┘   │ Algorithm→Complex │       │
│       │         └────────┬─────────┘       │
│       └─────────┬────────┘                  │
│                 ▼                           │
│         Selected Algorithm                  │
│                 │                           │
│  ┌──────────────▼──────────────┐            │
│  │   Algorithm Registry        │            │
│  │   20 algorithms (growing)   │            │
│  └──────────────┬──────────────┘            │
│                 │                           │
│  ┌──────────────▼──────────────┐            │
│  │   Execution + Feedback      │            │
│  │   quality, timing, success  │            │
│  └──────────────┬──────────────┘            │
│                 │                           │
│  ┌──────────────▼──────────────┐            │
│  │   Knowledge Base (ChromaDB) │            │
│  │   Pattern Store + Metrics   │            │
│  └─────────────────────────────┘            │
└────────────────────────────────────────────┘
```

### Pipeline Flow

1. **Input** — CLI command or natural language
2. **Parsing** — `SmartSolver` / `question_parser` extract problem type and data
3. **State Encoding** — 200-dimensional vector: data stats + problem type one-hot + environment info
4. **RL Selection** — PPO agent outputs action probabilities over 20 algorithms
5. **KG Validation** — Knowledge graph constrains the action to semantically valid candidates
6. **Execution** — Algorithm runs on the data; quality, timing, and success are recorded
7. **Feedback** — Results update the bandit, knowledge base, and optionally fine-tune the RL model

---

## Pre-Trained Model

AAlgoI ships with `pretrained_v1.pt` — a 3-stage pre-trained model:

| Stage | Iterations | Description |
|-------|-----------|-------------|
| 1. Supervised Bootstrapping | 200,000 | Textbook rules via CrossEntropy on raw logits |
| 2. RL Curriculum (optional) | 100,000 | PPO refinement with curriculum-based difficulty |
| 3. Self-Play (optional) | — | Adversarial WorldModel (disabled by default) |

### Guarantees

| Check | Requirement | Actual |
|-------|-------------|--------|
| Sorting Accuracy | 100% | 100% |
| Pathfinding Accuracy | 100% | 100% |
| Domain Routing | 100% | 100% |
| Inference Time | < 5 ms | ~0.6 ms |
| Model Size | < 10 MB | 0.72 MB |

Generate your own:

```bash
python training/pretrain_master.py
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `aalgoi solve` | Solve a problem from natural language description |
| `aalgoi solve-spec` | Solve a structured problem (type, data, constraints) |
| `aalgoi explain` | Explain why a specific algorithm was chosen |
| `aalgoi stats` | Show performance statistics per algorithm |
| `aalgoi benchmark` | Run benchmarks across algorithms |
| `aalgoi marketplace list` | List registered algorithms |
| `aalgoi marketplace search` | Search algorithms by name/pattern |
| `aalgoi ml train-word2vec` | Train a Word2Vec model |
| `aalgoi ml similar-words` | Find similar words in a trained model |
| `aalgoi ml visualize-embeddings` | Visualize word embeddings |
| `aalgoi debug visualize` | Visualize internal state / decision boundaries |

---

## Adding Algorithms

See the **Registering a custom algorithm** section under [Python API](#python-api) above.

For persistent registration, add your algorithm to `algorithms/` and register it in `pipeline.py`.

---

## Training

```bash
# Pre-train the model
python training/pretrain_master.py
```

---

## Tests

```bash
pytest tests/ -v
# 226 passed
```

---

## Project Structure

```
AAlgoI/
├── algorithms/         # Algorithm implementations by domain
│   ├── sorting/        # quicksort, timsort, heapsort, etc.
│   ├── pathfinding/    # dijkstra, a_star, bfs_path
│   ├── optimization/   # greedy_knapsack, simulated_annealing
│   └── ml/             # word2vec, pca, tsne, semantic
├── core/               # Core engine
│   ├── rl/             # PPO agent, WorldModel, reward shaper
│   ├── meta_controller.py  # Central orchestration
│   ├── knowledge_graph.py  # Semantic relationship graph
│   ├── knowledge_base.py   # Vector performance store
│   ├── pipeline_graph.py   # Execution pipeline
│   └── problem_spec.py     # Problem type system
├── interface/          # User interfaces
│   ├── cli.py          # Click CLI
│   ├── cli_ml.py       # ML subcommands
│   ├── cli_debug.py    # Debug subcommands
│   └── nl_parser.py    # Natural language parsing
├── training/           # Training pipelines
│   ├── pretrain_master.py  # 3-stage pre-training
│   ├── self_play.py        # Adversarial self-play
│   ├── curriculum.py       # Difficulty scheduler
│   └── data_generator.py   # Synthetic problem generator
├── tests/              # 226 test cases
├── checkpoints/        # Pretrained model files
└── pipeline.py         # UniversalSolver entry point
```

---

## License

MIT License — see [LICENSE](LICENSE).

---

## Links

- GitHub: [https://github.com/RayAKaan/AAlgoI](https://github.com/RayAKaan/AAlgoI)
- Issues: [https://github.com/RayAKaan/AAlgoI/issues](https://github.com/RayAKaan/AAlgoI/issues)
