raikura 0.1.1

The most advanced modular machine learning library in Python

Raikura

Raikura is an advanced, modular Python library for machine learning that extends beyond the traditional capabilities of scikit-learn. It integrates classical ML models, deep learning, transformers, time series forecasting, fairness auditing, AutoML pipelines, and model interpretability — all in a production-ready, extensible architecture.

Raikura is designed for researchers, engineers, and builders who want control, flexibility, and intelligence in one place.

---

📚 Philosophy

Raikura is structured around these design principles:

• Modularity: You can use only what you need — from preprocessing to full AutoML pipelines.
• Extensibility: Add your own models, metrics, or transformations with minimal friction.
• Explainability-first: SHAP, LIME, and Captum are built-in for responsible AI development.
• Multi-modal: Combine tabular, text, and image data in one pipeline.
• Reproducibility: Config-based pipelines, serialization, and audit logging ensure traceable results.

---

⚡ Capabilities Overview

🔨 Modeling

• Classical: Logistic Regression, Random Forest, SVM, Gradient Boosting, etc.
• Tree Boosting: XGBoost, LightGBM with auto-hyperparameter tuning
• Deep Learning: PyTorch MLPs and CNNs for tabular and image tasks
• NLP: Transformer models from HuggingFace for classification tasks

🧱 Preprocessing

• Auto column classification: numeric, categorical, text, datetime
• Feature scaling, one-hot and ordinal encoding
• TF-IDF/Count vectorization for text
• Polynomial and interaction features with custom degrees
• Lag and rolling-window features for time series

🎯 Metrics

• Classification: Accuracy, Precision, Recall, F1, ROC-AUC, Log-loss
• Regression: MAE, MSE, RMSE, R2
• Visuals: Confusion Matrix, ROC curves, metric plots

🧠 Explainability

• SHAP: global and local explanations for any model
• LIME: instance-level perturbation insights
• Captum: saliency and attribution for PyTorch-based models

📈 Time Series

• Lag and rolling features
• Time-based train/test splits and CV
• Prophet forecasting wrapper
• Hybrid classical + DL time series modeling

🔬 Fairness & Bias Auditing

• TPR/FPR/precision/recall by group
• Parity ratios for protected attributes
• Disparate impact calculations

⚙️ Automation

• Full YAML-configured training pipelines
• CLI and REST API interfaces
• Config tracking, hashing, and versioning
• Model + config + feature saving

---

🔧 Installation

pip install raikura

Requires Python 3.8+ and pip. Some components (like Prophet or Torch) require platform-specific setup.

---

✨ Quick Start (Python)

from raikura import AutoMLPipeline, DataLoader

# Load data
df_loader = DataLoader()
X, y = df_loader.load_csv("data/train.csv", target="label")

# Train model
pipe = AutoMLPipeline(model_type="random_forest")
pipe.configure(
    preprocessing={
        "expand_polynomial": True,
        "poly_degree": 2
    }
)
pipe.train(X, y)

---

🧪 CLI Usage

raikura train --config config.yaml

Example config.yaml

data:
  path: data/train.csv
  target: label

model:
  type: logistic_regression
  params: {}

task: classification
problem: tabular

preprocessing:
  expand_polynomial: true
  poly_degree: 2
  poly_interaction_only: false

output:
  model_path: outputs/model.pkl
  columns_path: outputs/columns.pkl

---

🌐 REST API (FastAPI)

uvicorn raikura.core.api:app --reload

Endpoints

Method	Endpoint	Purpose
POST	/predict	Run predictions
POST	/evaluate	Evaluate with ground truth
GET	/info	Model metadata

Send JSON payloads with columns and data keys.

---

🔍 Directory Structure

raikura/
├── cli.py               # CLI entrypoint
├── core/
│   ├── models.py        # Model factory
│   ├── pipeline.py      # AutoML logic
│   ├── train.py         # DL and transformers
│   ├── tuner.py         # Hyperparameter tuning
│   ├── preprocess.py    # Full preprocessing suite
│   ├── metrics.py       # Metrics & evaluation
│   ├── explain.py       # SHAP, LIME, Captum
│   ├── fusion.py        # Multi-modal models
│   ├── timeseries.py    # Time series tools
│   ├── audit.py         # Fairness auditing
│   ├── data.py          # Loading & splitting
│   ├── utils.py         # Seeding, saving, logging
│   └── api.py           # FastAPI serving

---

🧰 Advanced Features

🧠 FusionModel

• Accepts tabular + image + text data
• Unified forward pass and joint latent space
• Useful for medical ML, fraud detection, etc.

🧪 AutoMLPipeline

• Wraps training, preprocessing, evaluation
• Configurable via code or YAML
• Deep learning and classical interchangeable

📊 Metric Tracking

• Logs reports per epoch or fold
• Confusion matrix, F1, precision recall
• Visualizations available in metrics.py

---

📊 Example: Fairness Audit

from raikura import FairnessAudit

audit = FairnessAudit(sensitive_col="gender", privileged_group="male")
results = audit.evaluate(df_with_preds)
impact = audit.disparate_impact(df_with_preds)

---

🧪 Testing

Run tests using:

python -m unittest discover tests/

---

🙌 Contribute

• Fork and PR on GitHub
• Submit feature requests
• Help expand time series and multi-modal examples