Metadata-Version: 2.4
Name: featuremind
Version: 3.1.0
Summary: Universal AutoML + Feature Engineering + Explainability Library
Home-page: https://github.com/Nivedithagowda2/featuremind
Author: Niveditha
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.4.0
Provides-Extra: full
Requires-Dist: xgboost; extra == "full"
Requires-Dist: lightgbm; extra == "full"
Requires-Dist: catboost; extra == "full"
Requires-Dist: shap; extra == "full"
Requires-Dist: imbalanced-learn; extra == "full"
Provides-Extra: api
Requires-Dist: fastapi; extra == "api"
Requires-Dist: uvicorn; extra == "api"
Requires-Dist: python-multipart; extra == "api"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🧠 featuremind v3.1.0

**Universal AutoML · Feature Engineering · Reliability Framework**

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/Version-3.1.0-success)](https://github.com/Nivedithagowda2/featuremind/releases)
[![Leakage Guard](https://img.shields.io/badge/Leakage%20Guard-Enabled-red)](https://github.com/Nivedithagowda2/featuremind)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/Nivedithagowda2/featuremind/blob/main/LICENSE)
[![Status](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)](https://github.com/Nivedithagowda2/featuremind)

---

## 📌 What is featuremind?

**featuremind** is a one-line AutoML library that handles the complete machine learning pipeline — from raw CSV to production-ready model — with built-in reliability checking, leakage detection, and feature engineering.

```python
import featuremind as fm
fm.analyze("data.csv")
```

That's it. One line. Full analysis, model selection, feature suggestions, SHAP importance, leakage check, and HTML report — all automated.

---

## 🧪 Tested Datasets

featuremind v3.1 has been verified on:

| Dataset                          | Type           | Score         | Notes                                               |
| -------------------------------- | -------------- | ------------- | --------------------------------------------------- |
| Telecom Churn (7,043 rows)       | Classification | 85.7% F1      | ✅ Stable, well-balanced                             |
| Credit Card Fraud (284,807 rows) | Classification | ~99% F1       | ⚠️ High score due to PCA-transformed separable data |
| Heart Failure Medical            | Classification | ~80% Accuracy | ✅ Works                                             |
| House Prices                     | Regression     | R² reported   | ✅ Works                                             |
| Generic CSVs                     | Auto-detected  | Auto-detected | ✅ Works                                             |

---

## 🚀 Key Features

### 🤖 Auto ML Pipeline

* Loads and cleans any CSV automatically
* Detects target column, task type (classification / regression), and data issues
* Trains 6 models: LogisticRegression, RandomForest, GradientBoosting, XGBoost, LightGBM, CatBoost
* Picks best model using cross-validation
* Auto hyperparameter tuning (RandomizedSearchCV)

### 🛡️ Leakage Guard (Core Feature)

* Detects if any feature formula references the target column
* Flags columns with suspiciously high correlation with target (>0.95)
* Smart ID detection (non-generalizable columns)
* Warns user before model training (no silent failures)

### 🔍 Reliability Engine

* Detects unrealistic scores (>0.98)
* Adjusts confidence level automatically:

  * > 0.99 → Low confidence ❌
  * > 0.98 → Medium ⚠️
* Highlights possible issues:

  * Data leakage
  * Overfitting
  * Sampling bias

### ⚖️ Class Imbalance Handling

* Detects imbalance automatically
* Applies SMOTE (if available)
* Falls back to class weights
* Switches evaluation metric to F1 when needed

### 📊 SHAP Explainability

* Computes SHAP values for model explainability
* Displays top features influencing predictions
* Helps identify real business drivers

### 🔬 Feature Engineering (Multi-layer)

* Domain-aware features: Telecom · Medical · Real Estate · Finance · HR
* Interactions, ratios, log transforms, polynomial features
* Only surfaces features that improve performance

### 🏗️ Production Pipeline

* Save trained model + preprocessing pipeline
* Load and predict on new/unseen data
* Handles missing columns and unseen categories

### 🏆 Experiment Tracking

* Logs every run automatically
* Leaderboard of models and scores
* Export results to CSV

### 🌐 REST API (Optional)

* FastAPI-based prediction server
* Ready-to-use endpoints for deployment

---

## 🆚 Why featuremind?

| Capability          | featuremind | Typical AutoML Tools |
| ------------------- | ----------- | -------------------- |
| One-line usage      | ✅           | ❌                    |
| Leakage detection   | ✅           | ❌                    |
| Reliability scoring | ✅           | ❌                    |
| SHAP explainability | ✅           | ⚠️                   |
| Production pipeline | ✅           | ✅                    |

---

## 📦 Installation

```bash
# Install from local
pip install -e .

# (Recommended) Install advanced ML libraries
pip install xgboost lightgbm catboost shap imbalanced-learn

# Optional API support
pip install fastapi uvicorn python-multipart
```

> 🔜 PyPI release planned:

```bash
pip install featuremind
```

---

## 🚀 Quick Start

```python
import featuremind as fm

# Analyze dataset
fm.analyze("data.csv")

# Leakage check
fm.check_leakage("data.csv", target="Churn")

# Train + save pipeline
pipeline = fm.train("data.csv", target="Churn")
pipeline.save("churn_pipeline")

# Load + predict
pipeline = fm.load_pipeline("churn_pipeline")
results = pipeline.predict_df(new_data)

# Experiment tracking
fm.get_tracker().leaderboard()

# Optional API
fm.serve("churn_pipeline/", port=8000)
```

---

## 🏢 Example Use Case

A company can use **featuremind** to:

1. Upload raw dataset (CSV)
2. Run `fm.analyze()`
3. Identify key drivers using SHAP
4. Validate model reliability
5. Deploy pipeline via API

➡️ Reduces manual ML workflow from days to minutes.

---

## 📁 Project Structure

```
featuremind_project/
│
├── featuremind/
│   ├── analyzer.py
│   ├── feature_engineer.py
│   ├── evaluator.py
│   ├── leakage_guard.py
│   ├── importance.py
│   ├── reporter.py
│   ├── html_reporter.py
│   ├── insights.py
│   ├── pipeline.py
│   ├── tracker.py
│   └── api.py
│
├── setup.py
├── requirements.txt
├── test.py
└── README.md
```

---

## ⚠️ Notes

* High accuracy (>0.98) may indicate:

  * Data leakage
  * Highly separable datasets
  * Sampling bias

* Always validate models on unseen data.

---

## 📊 Output Files

* `featuremind_report.html` → Full analysis report
* `featuremind_report.png` → Feature visualization
* `enhanced_data.csv` → Dataset with engineered features
* `featuremind_experiments.csv` → Experiment logs
* `pipeline/` → Saved production model

---

## 💡 Use Cases

* Telecom churn prediction
* Fraud detection
* Healthcare predictions
* Real estate pricing
* HR analytics
* Any tabular ML problem

---

## 🔮 Roadmap

* Time-series support
* Deep learning integration
* Streamlit dashboard
* Cloud deployment

---

## 📄 License

MIT License

---

## 👩‍💻 Author

**Niveditha** — Aspiring Data Scientist & ML Engineer

---

> ⭐ If this project helps you, consider giving it a star!
