Metadata-Version: 2.4
Name: mlreadyscore
Version: 0.1.0
Summary: Give any dataset an ML-readiness score from 0-100 with actionable suggestions.
Project-URL: Homepage, https://github.com/kingprince35/mlreadyscore/
Project-URL: Documentation, https://github.com/kingprince35/mlreadyscore/#readme
Project-URL: Issues, https://github.com/kingprince35/mlreadyscore/issues
Project-URL: Changelog, https://github.com/kingprince35/mlreadyscore/blob/main/CHANGELOG.md
Author-email: Prince <prajapatiprince982@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: data-preprocessing,data-quality,data-science,data-validation,eda,machine-learning,ml-readiness
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: numpy>=1.22.0
Requires-Dist: pandas>=1.5.0
Provides-Extra: all
Requires-Dist: openpyxl>=3.0; extra == 'all'
Requires-Dist: pyarrow>=10.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.0; extra == 'excel'
Provides-Extra: parquet
Requires-Dist: pyarrow>=10.0; extra == 'parquet'
Description-Content-Type: text/markdown

# mlreadyscore

> Give any dataset an ML-readiness score from 0–100 with actionable suggestions.

**Stop guessing if your data is ready for Machine Learning.** `mlreadyscore` analyzes your dataset and gives you a clear score, issues list, and fix suggestions — all in one line of code.

## Installation

```bash
pip install mlreadyscore
```

## Quick Start

```python
from mlreadyscore import check

# From a CSV file
report = check("my_data.csv")
print(report)

# From a DataFrame
import pandas as pd
df = pd.read_csv("sales.csv")
report = check(df, target="revenue")
print(report.score)       # 72.5
print(report.grade)       # B-
print(report.suggestions) # ['DROP column X...', 'IMPUTE column Y...']
```

## Output

```
============================================================
   ML READINESS REPORT
============================================================
   Dataset:  5000 rows × 12 columns
   Score:    72.5 / 100  (B-)
------------------------------------------------------------

   CHECK SCORES:
   --------------------------------------------
   Dataset Size             [###############]  100.0
   Missing Values           [##########.....]   68.3
   Duplicate Rows           [###############]  100.0
   Data Types               [############...]   85.0
   Outliers                 [##########.....]   70.2
   Multicollinearity        [#########......]   60.0
   Class Imbalance          [########.......]   55.0
   Constant Features        [###############]  100.0
   High Cardinality         [############...]   82.0

   ISSUES FOUND (5):
   --------------------------------------------
    1. 'address' has 42.3% missing — significant gaps
    2. 'price' has 8.2% outliers
    3. 'area' & 'sqft' have 0.97 correlation — near identical
    4. Moderate imbalance: minority/majority ratio = 0.25
    5. 'zipcode' has 847 unique values — high cardinality

   SUGGESTIONS (5):
   --------------------------------------------
    1. IMPUTE 'address' with median/mode
    2. CLIP or TRANSFORM 'price' (log transform or winsorize)
    3. DROP one of 'area' or 'sqft'
    4. TRY class_weight='balanced' or stratified sampling
    5. REDUCE 'zipcode' cardinality with grouping

   --------------------------------------------
   VERDICT: Needs work. Address the suggestions before training.
============================================================
```

## What It Checks

| Check | What It Catches |
|---|---|
| **Dataset Size** | Too few rows, too many columns, curse of dimensionality |
| **Missing Values** | Null/NaN values per column with severity rating |
| **Duplicate Rows** | Exact duplicate rows that can bias your model |
| **Data Types** | Numbers stored as text, dates as strings, mixed types |
| **Outliers** | Extreme values using IQR method |
| **Multicollinearity** | Highly correlated features (>0.85) |
| **Class Imbalance** | Skewed target distribution for classification |
| **Constant Features** | Zero-variance columns that add no information |
| **High Cardinality** | Categorical columns with too many unique values |

## Supported File Formats

- `.csv` — CSV files
- `.tsv` — Tab-separated files
- `.xlsx` / `.xls` — Excel files (requires `pip install mlreadyscore[excel]`)
- `.json` — JSON files
- `.parquet` — Parquet files (requires `pip install mlreadyscore[parquet]`)

## API Reference

### `check(data, target=None)`

Main function. Accepts a file path or DataFrame.

```python
report = check("data.csv")
report = check(df, target="label")
```

### `ReadinessReport`

The returned report object:

```python
report.score        # float: 0-100
report.grade        # str: "A+" to "F"
report.issues       # list[str]: all issues found
report.suggestions  # list[str]: actionable fixes
report.checks       # list[dict]: individual check results
report.summary      # str: one-line verdict

report.to_dict()    # export as dictionary
report.to_json()    # export as JSON string
report.save("report.json")  # save to file
```

### Individual Checks

Run specific checks independently:

```python
from mlreadyscore import check_missing, check_outliers, check_imbalance

result = check_missing(df)
print(result["score"])      # 85.0
print(result["issues"])     # ["'age' has 12.3% missing"]
print(result["suggestions"])  # ["IMPUTE 'age' with mean/median/mode"]
```

## Use Cases

- **Before training:** Run `check()` to catch problems early
- **In CI/CD pipelines:** Automate data validation with score thresholds
- **Teaching/learning:** Understand what makes data ML-ready
- **Data handoff:** Share reports with teammates when passing datasets

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

```bash
git clone https://github.com/yourusername/mlreadyscore.git
cd mlreadyscore
pip install -e ".[dev]"
pytest
```

## License

MIT
