Metadata-Version: 2.4
Name: ai-mk-toolkit
Version: 8.0.0
Summary: Unified AI/ML toolkit providing a consistent API for accessing 205 models and tasks from scikit-learn, PyTorch, TensorFlow, and other popular libraries.
Author-email: Manojna Karuparthi <manojnak03@gmail.com>
License-Expression: MIT
Keywords: machine-learning,deep-learning,nlp,computer-vision,reinforcement-learning,ai,unified-api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.24
Requires-Dist: scikit-learn<2,>=1.3
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: joblib<2,>=1.3
Requires-Dist: torch<3,>=2.2
Requires-Dist: torchvision<1,>=0.17
Requires-Dist: tensorflow<3,>=2.16
Provides-Extra: ml-boosting
Requires-Dist: xgboost<3,>=2.1; extra == "ml-boosting"
Requires-Dist: lightgbm<5,>=4.5; extra == "ml-boosting"
Requires-Dist: catboost<2,>=1.2; extra == "ml-boosting"
Requires-Dist: umap-learn<1,>=0.5; extra == "ml-boosting"
Provides-Extra: dl
Requires-Dist: timm<2,>=1.0; extra == "dl"
Requires-Dist: ultralytics<9,>=8.3; extra == "dl"
Provides-Extra: nlp
Requires-Dist: nltk<4,>=3.9; extra == "nlp"
Requires-Dist: spacy<4,>=3.7; extra == "nlp"
Requires-Dist: gensim<5,>=4.3; extra == "nlp"
Requires-Dist: transformers<5,>=4.45; extra == "nlp"
Requires-Dist: sentence-transformers<4,>=3.0; extra == "nlp"
Provides-Extra: rl
Requires-Dist: stable-baselines3<3,>=2.3; extra == "rl"
Requires-Dist: sb3-contrib<3,>=2.3; extra == "rl"
Provides-Extra: cv
Requires-Dist: ultralytics<9,>=8.3; extra == "cv"
Requires-Dist: transformers<5,>=4.45; extra == "cv"
Provides-Extra: viz
Requires-Dist: matplotlib<4,>=3.8; extra == "viz"
Requires-Dist: seaborn<1,>=0.13; extra == "viz"
Provides-Extra: full
Requires-Dist: xgboost<3,>=2.1; extra == "full"
Requires-Dist: lightgbm<5,>=4.5; extra == "full"
Requires-Dist: catboost<2,>=1.2; extra == "full"
Requires-Dist: umap-learn<1,>=0.5; extra == "full"
Requires-Dist: timm<2,>=1.0; extra == "full"
Requires-Dist: ultralytics<9,>=8.3; extra == "full"
Requires-Dist: nltk<4,>=3.9; extra == "full"
Requires-Dist: spacy<4,>=3.7; extra == "full"
Requires-Dist: gensim<5,>=4.3; extra == "full"
Requires-Dist: transformers<5,>=4.45; extra == "full"
Requires-Dist: sentence-transformers<4,>=3.0; extra == "full"
Requires-Dist: stable-baselines3<3,>=2.3; extra == "full"
Requires-Dist: sb3-contrib<3,>=2.3; extra == "full"
Requires-Dist: matplotlib<4,>=3.8; extra == "full"
Requires-Dist: seaborn<1,>=0.13; extra == "full"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8.2; extra == "dev"
Requires-Dist: ruff<1,>=0.5; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Dynamic: license-file

# AI_MK_Toolkit

A well-tested Python package providing a unified API for accessing 205 models and tasks from popular open-source machine learning, deep learning, NLP, reinforcement learning, and computer vision libraries. All entries are callable via intuitive dot-path imports like `ai_mk_toolkit.ml.RandomForest()`.

**This package is a unified interface wrapper** built on top of open-source libraries. It does not reimplement algorithms but provides convenient access to widely used models from leading frameworks.

**Requires Python >= 3.10.** Tested on Windows, Linux, and macOS.

## 🚀 Why This Project?

Working across scikit-learn, PyTorch, TensorFlow, and dozens of other libraries means learning different APIs, managing disparate imports, and juggling installation quirks. AI_MK_Toolkit gives you **one consistent interface** so you can focus on experiments rather than boilerplate.

## ✨ Key Features

- **Unified API**: Single interface for accessing models across frameworks (scikit-learn, PyTorch, TensorFlow)
- **Lazy Loading**: Heavy optional dependencies loaded only when used
- **205 Entries**: Pre-configured access to 51 ML, 67 DL, 54 NLP, 19 RL models and 14 CV task APIs from trusted libraries
- **Consistent Interface**: Provides the same API patterns whether you use PyTorch or TensorFlow implementations under the hood
- **Designed for Production Use**: Type hints, error handling, PEP 561 compliance (`py.typed`)
- **License Aware**: Documents the licenses of all underlying libraries so users can make informed decisions

## 📖 About This Project

**What it is**: `ai-mk-toolkit` is a **unified Python interface** that wraps popular, well-tested machine learning libraries. It lets you access 205 models and tasks through a consistent, intuitive API.

**What it is NOT**: This package does **NOT** reimplement algorithms from scikit-learn, PyTorch, TensorFlow, or any other library. It solely provides a convenient interface layer for accessing these libraries.

**Design Philosophy**:
- Wrap battle-tested libraries (scikit-learn, PyTorch, TensorFlow, etc.) — never reimplement
- Provide a consistent API across different frameworks
- Let users install only what they need (modular optional dependencies)
- Respect and document all open-source licenses
- Be transparent about authorship and attribution

## 📦 Installation

### Base Install

Installs core dependencies: `numpy`, `scikit-learn`, `pyyaml`, `joblib`, `torch`, `torchvision`, `tensorflow`.

```bash
pip install ai-mk-toolkit
```

### With Additional Deep Learning Libraries

```bash
pip install ai-mk-toolkit[dl]            # Adds timm, ultralytics
```

### With NLP & Transformers

```bash
pip install ai-mk-toolkit[nlp]           # Adds transformers, nltk, spacy, gensim
```

### With Reinforcement Learning

```bash
pip install ai-mk-toolkit[rl]            # Adds stable-baselines3, sb3-contrib
```

### Everything

```bash
pip install ai-mk-toolkit[full]          # All optional extras
```

## 🎯 Quick Start

### Classical Machine Learning

```python
from ai_mk_toolkit import ml

# 51 models: regression, classification, clustering, dimensionality reduction
regressor = ml.LinearRegression()
regressor.fit(X_train, y_train)
predictions = regressor.predict(X_test)

# Or by name
xgb = ml.get_model("XGBoost", n_estimators=50)
pca = ml.PCA(n_components=10)
svm = ml.SVC(kernel="rbf")
```

### Deep Learning

```python
from ai_mk_toolkit import dl

resnet = dl.ResNet50(backend="torch", pretrained=True)  # CNN (PyTorch)
yolo = dl.YOLOv8()                                      # Object Detection (ultralytics)
lstm = dl.LSTM(backend="torch", units=128)               # Sequence model
```

### Natural Language Processing

```python
from ai_mk_toolkit import nlp

# Classical NLP (NLTK / spaCy wrappers)
tokenizer = nlp.Tokenizer()

# Encoder model — suited for embeddings, classification, NER
bert = nlp.BERT()

# Causal / generative LLM — suited for text generation
llama3 = nlp.Llama3()
```

### Reinforcement Learning

Tabular RL algorithms (`QLearning`, `SARSA`, `ExpectedSARSA`, `MonteCarlo`) are lightweight original implementations included in this package. Deep RL classes (`DQN`, `PPO`, `A2C`, `SAC`, etc.) are wrappers around **stable-baselines3**.

```python
from ai_mk_toolkit import rl

# Tabular RL (included implementation)
ql = rl.QLearning(n_states=16, n_actions=4)

# Deep RL (stable-baselines3 wrapper, requires [rl] extra)
dqn = rl.DQN(policy="MlpPolicy", env=env)
sarsa = rl.SARSA(n_states=16, n_actions=4)
```

### Computer Vision Tasks

The `cv` module provides **task-oriented APIs** that route to appropriate underlying models (e.g., ResNet, YOLO). These are task interfaces, not standalone model implementations.

```python
from ai_mk_toolkit import cv

image_clf = cv.ImageClassification()   # Routes to ResNet50
detector = cv.ObjectDetection()        # Routes to YOLOv8
segmenter = cv.ImageSegmentation()     # Routes to Mask R-CNN
```

## 📊 Model & Task Catalog

> **Note**: The counts below include both unique model wrappers and task-level APIs. Some entries (e.g., Computer Vision tasks) are convenience interfaces that route to underlying models listed in other categories.

**📈 Machine Learning — 51 model wrappers** (scikit-learn, XGBoost, LightGBM, CatBoost, UMAP):
LinearRegression, Ridge, Lasso, ElasticNet, SVC, LogisticRegression, RandomForest, DecisionTree, XGBoost, LightGBM, CatBoost, KNN, PCA, TSNE, UMAP, and 36 more

**🧠 Deep Learning — 67 model wrappers** (36 CNNs + 12 detectors + 8 sequence + 11 GANs):
ResNet18/34/50/101/152, VGG16/19, MobileNetV2/V3, EfficientNetB0-B7, YOLOv5/v8/v9/v10, LSTM, GRU, GAN, StyleGAN, CycleGAN, WGAN, and more

**🤖 NLP — 54 entries** (12 classical tools + 30 transformer models + 12 task pipelines):
BERT (encoder), GPT-2 (causal), Llama 3 (causal), Mistral, T5 (seq2seq), Word2Vec, FastText, TFIDF, TextClassification, Summarization, and more

**🎮 Reinforcement Learning — 19 entries** (5 tabular + 14 deep RL):
QLearning, SARSA, ExpectedSARSA, MonteCarlo, TDLearning (tabular — included implementations) + DQN, DoubleDQN, PPO, A2C, SAC, TD3, DDPG, TRPO (deep RL — stable-baselines3 wrappers)

**👁️ Computer Vision — 14 task APIs** (routing interfaces to DL models above):
ImageClassification, ObjectDetection, ImageSegmentation, PoseEstimation, OCR, FaceRecognition, ImageCaptioning, ImageGeneration, DepthEstimation, and more

## 🏗️ Architecture

```
ai_mk_toolkit/
├── ml/              # 51 scikit-learn / XGBoost / LightGBM / CatBoost wrappers
├── dl/              # Deep learning model wrappers (PyTorch / TensorFlow)
├── nlp/             # NLP model wrappers (NLTK, spaCy, Transformers)
├── rl/              # Tabular RL + stable-baselines3 wrappers
├── cv/              # Task-oriented computer vision APIs
├── core/            # Device detection, caching, logging, serialization
├── backends/        # PyTorch / TensorFlow / sklearn backend abstraction
├── automl/          # Hyperparameter search and model comparison
├── datasets/        # Built-in dataset loaders
├── preprocessing/   # Data transformation utilities
├── metrics/         # Evaluation metrics (classification, regression, clustering)
├── explainability/  # Feature importance, SHAP, LIME wrappers
├── visualization/   # Matplotlib-based plotting helpers
├── deployment/      # Model export (ONNX, TorchScript, SavedModel, joblib)
└── plugins/         # User-extensible model/dataset/metric registration
```

## 🔧 Advanced Usage

### Unified Classifiers (scikit-learn backed)

```python
from ai_mk_toolkit import UnifiedClassifier

clf = UnifiedClassifier(model="svc", kernel="rbf")
clf.fit(X_train, y_train)
print(clf.backend_name)
```

### Deep Learning with Backend Selection

```python
from ai_mk_toolkit import UnifiedModel

model = UnifiedModel(backend="pytorch")
model.add_dense(128, activation="relu")
model.compile(task="classification")
model.fit(X_train, y_train, epochs=10)
predictions = model.predict(X_test)
```

## ✅ Quality Assurance

- **Static Analysis**: Ruff is used to continuously check for unused imports (F401) and unused variables (F841). Current status: all checks passing.
- **Comprehensive Testing**: 89 tests passing (framework-specific tests included). Full coverage of core functionality.
- **Build & Packaging**: Passes PyPI validation via twine. Builds successfully for both sdist and wheel distributions.
- **Wrapper Architecture**: No algorithm reimplementations. Pure interface layer over open-source libraries.
- **Dependencies**: Core dependencies auto-installed; optional extras available for specialized domains.

## 📋 Testing

```bash
pytest                    # All tests
pytest -v                 # Verbose
pytest tests/test_classical_models.py  # Specific test
```

## ⚖️ License & Attribution

AI_MK_Toolkit itself is released under the **MIT License** — see [LICENSE](LICENSE).

The underlying libraries have their own licenses:

| Library | License |
|---------|---------|
| numpy, scikit-learn | BSD |
| torch, torchvision | BSD |
| tensorflow | Apache 2.0 |
| transformers, sentence-transformers | Apache 2.0 |
| xgboost, lightgbm, catboost | Apache 2.0 |
| nltk, spacy | Apache 2.0 |
| gensim | LGPL-2.1+ |
| ultralytics | AGPL-3.0 |
| stable-baselines3, sb3-contrib | MIT |
| timm | Apache 2.0 |
| pyyaml | MIT |
| joblib | BSD |

> **Important**: Some optional dependencies (e.g., `ultralytics` under AGPL-3.0, `gensim` under LGPL-2.1+) have copyleft license terms. **Users are responsible for complying with the licenses of the optional dependencies they choose to install.** If your project requires only permissive licenses, avoid installing the `[cv]` and `[nlp]` extras, or review individual package licenses before use.

## 🙏 Acknowledgments

This package is built on top of the following open-source libraries. We are grateful for their contributions to the ML community.

**Core Dependencies** (always installed):
- **scikit-learn** (BSD-3-Clause) — Classical ML algorithms
- **NumPy** (BSD) — Numerical computing foundation
- **PyTorch** (BSD) — Deep learning framework
- **torchvision** (BSD) — Pre-trained computer vision models
- **TensorFlow/Keras** (Apache 2.0) — Deep learning framework
- **PyYAML** (MIT) — Configuration management
- **joblib** (BSD) — Serialization and parallelism

**Optional Deep Learning** (install via `[dl]` extra):
- **timm** (Apache 2.0) — PyTorch image models library
- **Ultralytics** (⚠️ AGPL-3.0) — YOLO object detection models

**Optional ML Boosting** (install via `[ml_boosting]` extra):
- **XGBoost** (Apache 2.0) — Gradient boosting
- **LightGBM** (MIT) — Fast gradient boosting
- **CatBoost** (Apache 2.0) — Categorical gradient boosting
- **UMAP** (BSD-3-Clause) — Dimensionality reduction

**Optional NLP** (install via `[nlp]` extra):
- **Transformers** (Apache 2.0) — HuggingFace transformer models (BERT, GPT, Llama, Mistral, etc.)
- **NLTK** (Apache 2.0) — Classical NLP tools
- **spaCy** (MIT) — Industrial-strength NLP
- **Gensim** (⚠️ LGPL-2.1+) — Topic modeling and embeddings
- **sentence-transformers** (Apache 2.0) — Semantic embeddings

**Optional Reinforcement Learning** (install via `[rl]` extra):
- **Stable Baselines 3** (MIT) — RL algorithms (DQN, PPO, A2C, etc.)
- **sb3-contrib** (MIT) — Additional RL algorithms

## 📝 Contributing

### ✅ What IS Acceptable

1. **Wrapping existing libraries** — Creating unified interfaces to access models from sklearn, PyTorch, TensorFlow, etc.
2. **Adding new model aliases** — Mapping additional models from existing libraries
3. **Improving documentation** — Better examples, guides, and explanations
4. **Fixing bugs** — Improving robustness and error handling
5. **Performance optimization** — Making wrappers more efficient
6. **Enhanced testing** — Expanding test coverage

### ❌ What IS NOT Acceptable

1. **Copying source code** from TensorFlow, PyTorch, scikit-learn, or any other library
2. **Reimplementing algorithms** that already exist in well-maintained libraries
3. **Claiming ownership** of algorithms from other libraries
4. **Removing or obscuring attribution** to underlying libraries

### Dependency Policy

**Core Dependencies** (installed by default): `numpy`, `scikit-learn`, `pyyaml`, `joblib`, `torch`, `torchvision`, `tensorflow`. Any change to core dependencies must be discussed before merging.

**Optional Extras**: Use `pip install ai-mk-toolkit[extra_name]` pattern. Group related libraries together. Keep extras for specialized or heavy libraries not needed by every user.

### License Compliance

Before adding a new library as a dependency:
- **Check the license** — Preferred: MIT, BSD, Apache 2.0. Acceptable: LGPL (document clearly). Avoid: GPL (incompatible with MIT).
- **Document in README** — Add library name and license to the Acknowledgments section.
- **Update pyproject.toml** — Add version constraints and place in appropriate optional-dependencies group.

### Testing Guidelines

- Write tests that verify wrapper behavior, not algorithm correctness
- ❌ Don't test that scikit-learn's SVM actually works correctly
- ✅ Do test that our wrapper instantiates and calls SVM correctly
