Metadata-Version: 2.4
Name: shaaha
Version: 2.0.1
Summary: Intelligent Meta-Dispatcher — AI-powered backend selection, agent execution, and code optimization.
Author-email: Shaaha <shaaha@example.com>
License: MIT
Project-URL: Homepage, https://github.com/shaaha/shaaha
Project-URL: Documentation, https://shaaha.readthedocs.io
Project-URL: Repository, https://github.com/shaaha/shaaha
Project-URL: Bug Tracker, https://github.com/shaaha/shaaha/issues
Keywords: meta-dispatcher,import-hook,backend-selection,ai-agent,code-optimizer,numpy,pandas,polars,pytorch
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: default
Requires-Dist: numpy; extra == "default"
Requires-Dist: pandas; extra == "default"
Requires-Dist: pillow; extra == "default"
Requires-Dist: matplotlib; extra == "default"
Requires-Dist: scikit-learn; extra == "default"
Requires-Dist: requests; extra == "default"
Provides-Extra: science
Requires-Dist: numpy; extra == "science"
Requires-Dist: scipy; extra == "science"
Requires-Dist: pandas; extra == "science"
Requires-Dist: polars; extra == "science"
Requires-Dist: matplotlib; extra == "science"
Requires-Dist: seaborn; extra == "science"
Requires-Dist: plotly; extra == "science"
Requires-Dist: scikit-learn; extra == "science"
Requires-Dist: statsmodels; extra == "science"
Provides-Extra: gpu
Requires-Dist: torch; extra == "gpu"
Requires-Dist: cupy-cuda12x; extra == "gpu"
Provides-Extra: nlp
Requires-Dist: transformers; extra == "nlp"
Requires-Dist: spacy; extra == "nlp"
Requires-Dist: nltk; extra == "nlp"
Provides-Extra: agent
Requires-Dist: anthropic; extra == "agent"
Provides-Extra: dashboard
Requires-Dist: flask; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: flask; extra == "dev"
Requires-Dist: anthropic; extra == "dev"
Provides-Extra: all
Requires-Dist: numpy; extra == "all"
Requires-Dist: scipy; extra == "all"
Requires-Dist: pandas; extra == "all"
Requires-Dist: polars; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: seaborn; extra == "all"
Requires-Dist: plotly; extra == "all"
Requires-Dist: scikit-learn; extra == "all"
Requires-Dist: statsmodels; extra == "all"
Requires-Dist: requests; extra == "all"
Requires-Dist: httpx; extra == "all"
Requires-Dist: flask; extra == "all"
Requires-Dist: anthropic; extra == "all"
Requires-Dist: rich; extra == "all"

# 🧠 Shaaha

> **One import. Best backend. Always. Now with AI.**

[![PyPI version](https://badge.fury.io/py/shaaha.svg)](https://pypi.org/project/shaaha/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/shaaha)](https://pypi.org/project/shaaha/)

**Shaaha** is the world's first **Self-Optimizing AI-Driven Python Meta-Dispatcher**.

Instead of manually picking numpy, pandas, torch, or sklearn — you write one import and Shaaha silently picks the best available library for your hardware, learns from every run, fixes its own errors, and even rewrites your old code to be faster.

---

## 🚀 Install

```bash
pip install shaaha                      # zero dependencies
pip install "shaaha[default]"           # + numpy, pandas, pillow, sklearn, matplotlib
pip install "shaaha[science]"           # full scientific stack
pip install "shaaha[gpu]"               # CUDA / GPU stack
```

---

## ⚡ Quick Start

```python
import shaaha

import shaaha.math as sm           # → cupy (GPU) or numpy (CPU)
import shaaha.dataframe as df      # → polars (large) or pandas (small)
import shaaha.ml as ml             # → torch (GPU) or sklearn (CPU)
import shaaha.image as img         # → opencv or pillow
import shaaha.viz as viz           # → plotly or matplotlib

arr = sm.array([1, 2, 3, 4, 5])
sm.sqrt(arr)

model = ml.LinearRegression()
model.fit(X_train, y_train)
```

---

## 🤖 Layer 2 — AI Agent

```python
shaaha.agent("load sales.csv, find the top 10 products, and plot a bar chart")
# Breaks task into steps and executes automatically
# 📄 Report saved: shaaha_report.md
```

---

## 🔁 Layer 3 — Code Rewriter

```python
shaaha.optimize_file("my_old_script.py")
# Finds slow patterns, shows diff, asks before applying
# ⚡ Estimated speedup: up to 100x faster
```

---

## 🧠 Layer 4 — Adaptive Brain

```python
shaaha.status()
# "brain_confidence": "87%"
# "recommendations": ["math: 'numpy' fastest on your machine (4.2ms)"]

shaaha.reset_learning()
```

---

## 🩺 Layer 5 — Self-Healer

When a backend crashes, Shaaha auto-switches and always notifies you:
```
⚠️  'jax' failed → switched to 'numpy'.
   shaaha.suppress_warnings = True to hide this.
```

---

## 📖 Layer 6 — Explainer

```python
shaaha.explain("my_script.py", output="report.md")
# Explains every library choice in plain English
# Perfect for students and researchers
```

---

## 📊 Layer 7 — Dashboard

```python
shaaha.dashboard()
# 🚀 Opens http://127.0.0.1:7842
# Shows all operations, backends chosen, speed history
```

---

## 🔌 Layer 8 — Plugin System

```python
shaaha.register_backend("dataframe", "vaex", "vaex", priority=88)
shaaha.list_backends("dataframe")
```

---

## 🤝 Layer 9 — Collaboration

```python
shaaha.share_profile("my_profile.json")
shaaha.import_profile("teammate.json")
shaaha.sync("http://team-server:8080")
```

---

## 🛡️ Layer 10 — Safety Guard

```python
shaaha.safe_mode(True)
# ✅ Results match 100%. Safe to switch from 'jax' to 'numpy'.
```

---

## 🗺️ Supported Domains

| `shaaha.<domain>` | Best Backend | Fallbacks |
|---|---|---|
| `shaaha.math` | cupy / jax | torch → numpy |
| `shaaha.dataframe` | polars | modin → pandas → dask |
| `shaaha.ml` | torch | xgboost → lightgbm → sklearn |
| `shaaha.image` | opencv | pillow → skimage |
| `shaaha.nlp` | transformers | spacy → nltk |
| `shaaha.viz` | plotly | altair → seaborn → matplotlib |
| `shaaha.stats` | statsmodels | scipy → sklearn |
| `shaaha.http` | httpx | requests → urllib3 |
| `shaaha.json` | orjson | ujson → json (stdlib) |

---

## 🏗️ How It Works

Shaaha uses **PEP 302 Import Hooks** (`sys.meta_path`) to intercept Python's import system before it looks for any file. A `MetaPathFinder` captures every `import shaaha.*` call, the `Router` scores available backends by hardware context and learned timing data, and a lazy `ProxyModule` forwards all attribute access transparently — zero cost until first use.

---

## 🎓 MSc Thesis

Shaaha implements three advanced CS concepts:
1. **Python Import Protocol (PEP 302/451)** — MetaPathFinder, Loader, ModuleSpec
2. **Proxy + Strategy + Registry Design Patterns**
3. **Context-Aware Weighted Dispatch with Adaptive Learning**

---

## 📄 License

MIT © Shaaha | [pypi.org/project/shaaha](https://pypi.org/project/shaaha/)
