Metadata-Version: 2.1
Name: gafime
Version: 0.3.1
Summary: GPU Accelerated Feature Interaction Mining Engine
Author: Hamza
Author-email: Hamza <hamzausta2222@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/onlyxItachi/GAFIME
Project-URL: Repository, https://github.com/onlyxItachi/GAFIME
Project-URL: Issues, https://github.com/onlyxItachi/GAFIME/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: polars>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.0; extra == "sklearn"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# GAFIME: GPU-Accelerated Feature Interaction Mining Engine 🚀

![PyPI version](https://img.shields.io/pypi/v/gafime)
![Python Versions](https://img.shields.io/pypi/pyversions/gafime)
![License](https://img.shields.io/github/license/onlyxItachi/GAFIME)

GAFIME is a high-performance computing engine engineered to eliminate the biggest bottleneck in modern machine learning workflows: **Feature Interaction Discovery.**

While most data science tools prioritize ease-of-use over execution efficiency, GAFIME treats feature engineering as a low-level systems problem. By combining C++ optimization, Rust memory-safety pipelines, and cross-platform native bindings (CUDA/Metal), GAFIME bridges the gap between high-level data science and the raw power of modern hardware architectures.

## 📦 Installation

GAFIME ships natively compiled wheel binaries for Windows, macOS (Apple Silicon), and Linux heavily optimized for performance out-of-the-box.

**Basic Install (Engine Only):**

```bash
pip install gafime
```

**Data Science Install (Includes Scikit-Learn Wrapper):**

```bash
pip install gafime[sklearn]
```

## ⚡ Quickstart: The Interactive Tutorial

The fastest way to understand GAFIME's speed is to try our built-in interactive tutorial generator. Running this command will generate a pre-configured `gafime_tutorial.ipynb` Jupyter Notebook in your current directory with dummy feature data to instantly evaluate against:

```bash
gafime --init
```

## 🧩 Scikit-Learn Pipeline Integration

You don't need to rewrite your data pipelines to use GAFIME. By importing the `GafimeSelector`, you can inject GPU-accelerated feature discovery natively into `sklearn.pipeline.Pipeline` or `GridSearchCV`:

```python
import numpy as np
from sklearn.pipeline import Pipeline
from sklearn.linear_model import LogisticRegression
from gafime.sklearn import GafimeSelector

# Define dummy data
X_train = np.random.randn(1000, 50).astype(np.float32)
y_train = np.random.randint(0, 2, size=1000).astype(np.float32)

# Create a pipeline that automatically discovers the Top 5 best Feature Interactions
# Evaluated instantly against the GPU logic and appends them to your training dataset
pipe = Pipeline([
    ('interaction_miner', GafimeSelector(k=5, backend='auto', operator='multiply')),
    ('classifier', LogisticRegression())
])

pipe.fit(X_train, y_train)
```

## 🌌 Why GAFIME? The Performance Ceiling

In the current data science landscape, mining interaction data (like checking `Feature X * Feature Y` against the target) is painfully slow on CPUs or inefficiently memory-managed on GPUs. GAFIME achieves:

1. **Hardware-Bound Execution**: GAFIME targets physical memory bandwidth limits, minimizing the overhead of standard GPU python workflows. You hit the system's ceiling.
2. **Zero-Overhead Scaling**: Utilizing Rust's FFI capabilities on top of optimized CUDA C++, GAFIME bypasses the Python Global Interpreter Lock (GIL) ensuring every clock cycle executes pure feature logic.
3. **Cross-Platform Scalability**: Whether you're on a MacBook executing `Metal` fallback logic via Rust, or an RTX workstation targeting `CUDA` registers, GAFIME auto-discovers and optimizes for your hardware at runtime.

### Caching and Branch-less Operations

GAFIME's specialized memory management layout ensures tabular feature data is cached and aligned, dramatically minimizing GPU cycle stalls regardless of noisy dataset inputs.

## 🛠️ Technology Stack

- **Core Engine**: C++ / CUDA (Performance-critical computation paths) and **Metal** (Apple Silicon native acceleration)
- **Safety Pipeline & Schedulers**: Rust (Memory safe FFI interface scheduling)
- **Data Science Interfacing**: Python (Polars / Numpy bindings seamlessly communicating across boundaries)

## ✅ For being honest

-> Current state of the project is its **first v0.2 open beta release**.

-> The project is developed with the help of current frontier SOTA models such as Gemini 3.1 Pro (high reasoning effort) and Claude Opus 4.6 (high).

## 🤝 If you want

You could collaborate with me via using email to communicate 🥰

Email: <hamzausta2222@gmail.com>

---

### Contributing and Advanced Usage

Looking to expand the engine metrics or compile natively yourself?
Please see our detailed references:

- [USAGE.md](/USAGE.md) - Advanced `EngineConfig` features and API logic.
- [CONTRIBUTING.md](/CONTRIBUTING.md) - Local compilation instructions for OS developers.

*GAFIME was conceptualized and engineered for extreme high-frequency feature permutations in complex categorical environments like Banking models.*
