Metadata-Version: 2.4
Name: mudra-ml
Version: 0.3.1
Summary: Glass-box autonomous data science: profile, clean, model, and explain every decision.
Project-URL: Homepage, https://github.com/MuditNautiyal-21/MudraML
Project-URL: Repository, https://github.com/MuditNautiyal-21/MudraML
Project-URL: Issues, https://github.com/MuditNautiyal-21/MudraML/issues
Project-URL: Changelog, https://github.com/MuditNautiyal-21/MudraML/blob/main/CHANGELOG.md
Author: Mudit Nautiyal
License: MIT License
        
        Copyright (c) 2026 Mudit Nautiyal
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automl,data-science,explainable,machine-learning,pipeline,scikit-learn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1
Requires-Dist: joblib>=1.2
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scikit-learn>=1.2
Requires-Dist: typer>=0.9
Provides-Extra: boost
Requires-Dist: lightgbm>=4.0; extra == 'boost'
Requires-Dist: xgboost>=1.7; extra == 'boost'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: openpyxl>=3.1; extra == 'dev'
Requires-Dist: pyarrow>=12.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Provides-Extra: files
Requires-Dist: openpyxl>=3.1; extra == 'files'
Requires-Dist: pyarrow>=12.0; extra == 'files'
Provides-Extra: parquet
Requires-Dist: pyarrow>=12.0; extra == 'parquet'
Description-Content-Type: text/markdown

# Mudra-ML

Automated, glass-box data science. Point it at a data file, get a fitted model and a report of every decision behind it.

[![PyPI version](https://img.shields.io/pypi/v/mudra-ml.svg?v=1)](https://pypi.org/project/mudra-ml/)
[![Python versions](https://img.shields.io/pypi/pyversions/mudra-ml.svg?v=1)](https://pypi.org/project/mudra-ml/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/MuditNautiyal-21/mudra-ml/actions/workflows/ci.yml/badge.svg)](https://github.com/MuditNautiyal-21/mudra-ml/actions/workflows/ci.yml)

MudraML automates the common data science workflow and shows its work. You point it at a data file, optionally state a goal, and it ingests the data, profiles it, cleans it, picks an algorithm, trains and tunes a shortlist of models, evaluates them, and returns the best fitted model together with a report of every decision it made and the rule behind that decision.

The point of difference is the decision engine. It is rule-based and statistical, not another model. Outlier handling uses IQR or z-score rules. Missing values are filled by median, mode, or a constant, or the column is dropped past a missingness threshold. The algorithm shortlist comes from a documented rule set keyed on the task, the dataset size, the feature count, and your constraints. Every one of those choices is written into the report, so a person can read why the pipeline did what it did and disagree with it if they want.

This is the glass-box position: the models are the product, and the way the pipeline reaches them is auditable rather than hidden inside a search.

## Install

```
pip install mudra-ml
```

Optional extras:

```
pip install mudra-ml[files]    # parquet and excel readers
pip install mudra-ml[boost]    # xgboost and lightgbm candidates
```

The library runs fully on the scikit-learn core. The boosters are added to the shortlist only when the extra is installed.

## Quickstart

Fully automatic. MudraML infers the task, the target, and the metric:

```python
from mudra_ml import Mudra

m = Mudra()
result = m.run("data.csv")
print(result.report_path)   # markdown and HTML report on disk
model = result.best_model   # fitted, ready to predict
```

Operator-defined goal. You set what you care about and MudraML honors it:

```python
result = m.run(
    "churn.csv",
    target="churn",
    task="classification",
    metric="f1",
    constraints={"interpretable": True, "max_train_seconds": 120},
)
```

When `interpretable` is set, the shortlist is limited to models you can read directly, such as logistic regression and a single decision tree. The report states which goal fields you set and which ones were inferred.

## What the report looks like

Every run writes a markdown report and an HTML report. The HTML report carries the same content plus diagnostic charts (confusion matrix heatmap, ROC and precision-recall curves, target distribution, feature correlation, residual and predicted-versus-actual plots for regression). The block below is an excerpt from a real run on the scikit-learn breast cancer dataset.

```
## Trust summary

Held-out test size: 114 rows. Training size: 455 rows.
Baseline: dummy_most_frequent (no learning, predicts the most frequent class or the mean).

| Metric    | Best model | Baseline | Difference |
| --------- | ---------- | -------- | ---------- |
| accuracy  | 0.9737     | 0.6316   | 0.3421     |
| f1        | 0.9793     | 0.7742   | 0.2051     |
| precision | 0.9726     | 0.6316   | 0.3410     |
| recall    | 0.9861     | 1.0000   | -0.0139    |
| roc_auc   | 0.9970     | 0.5000   | 0.4970     |

Train vs test gap on selected metrics (positive means train is better than test).

| Metric    | Train  | Test   | Gap    |
| --------- | ------ | ------ | ------ |
| accuracy  | 0.9846 | 0.9737 | 0.0109 |
| f1        | 0.9878 | 0.9793 | 0.0085 |
| precision | 0.9793 | 0.9726 | 0.0067 |
| recall    | 0.9965 | 0.9861 | 0.0104 |

## Result

Selected model: logistic_regression
Cross-validation score: 0.9801 +/- 0.0129

### Per-class report

| Class | Precision | Recall | F1     | Support |
| ----- | --------- | ------ | ------ | ------- |
| 0     | 0.9756    | 0.9524 | 0.9639 | 42      |
| 1     | 0.9726    | 0.9861 | 0.9793 | 72      |

## Feature importance (permutation, mean across 10 repeats)

Impurity importance is biased toward high-cardinality features. The permutation view is more reliable because it scores each feature by how much shuffling it hurts the model.

- worst smoothness: 0.0193 (+/- 0.0102)
- worst texture: 0.0175 (+/- 0.0111)
- area error: 0.0149 (+/- 0.0111)
- worst concave points: 0.0114 (+/- 0.0056)
- mean smoothness: 0.0105 (+/- 0.0086)
```

The numbers above come from a real run. The HTML report adds confusion matrix, ROC, and precision-recall charts alongside these tables.

## Predict and reuse

```python
result.save("run_artifact")            # pipeline + model + metadata
loaded = Mudra.load("run_artifact")
preds = loaded.predict(new_dataframe)
```

The preprocessing pipeline travels with the model, so new rows are transformed the same way the training rows were.

## Command line

```
mudra-ml run data.csv --target churn --task classification --metric f1
mudra-ml profile data.csv
```

`run` writes the report and prints the selected model and its held-out metrics. `profile` prints the inferred column types, missingness, cardinality, and the candidate target columns.

## What it does, stage by stage

1. Ingest. Readers for csv, tsv, excel, json, and parquet. For delimited text the delimiter, encoding, and header row are detected.
2. Profile. Per-column type inference (numeric, categorical, datetime, boolean, id, text), missingness, cardinality, distribution stats, and candidate-target ranking.
3. Goal. Rule-based inference of the task, target, and metric, with any field you set taking precedence.
4. Preprocess. A leakage-safe scikit-learn Pipeline and ColumnTransformer. Imputation, datetime part extraction, outlier clipping, encoding, and scaling are all fit on the training split only.
5. Recommend. A documented rule set returns a candidate shortlist.
6. Train and evaluate. Cross-validated training and tuning with RandomizedSearchCV at a fixed seed. Model selection follows the cross-validation score, so the held-out test set is scored only once, for the selected model, and never used to choose among candidates. Feature importance is reported where the model exposes it.
7. Report. Markdown and HTML that log every decision and the rule that produced it.

## Why leakage safety matters here

Every statistic that preprocessing needs (a median, a category frequency, an outlier bound, a scaler mean) is learned during `fit`. MudraML fits the pipeline on the training split and only transforms the test split. No information from the test data reaches the model through preprocessing. The test suite checks this property directly: it fits on a slice with a known mean and confirms the learned imputation value matches the train slice rather than the whole dataset.

## Determinism

One `random_state` is threaded through every stochastic step (the split, the search, the estimators) and defaults to a fixed value. Two runs on the same data and the same goal produce the same result and the same report.

## Tasks and metrics

| Task | Default metric | Also reported |
| --- | --- | --- |
| classification | f1 | accuracy, precision, recall, roc_auc, per-class precision/recall/f1, confusion matrix, ROC and precision-recall curves |
| regression | rmse | mae, mse, r2, residual mean and std, predicted vs actual |
| clustering | silhouette | davies_bouldin |

## Trust and data quality

Every run reports the headline metrics against a naive baseline (most-frequent class for classification, mean for regression), the cross-validation score as mean plus or minus standard deviation across folds, and the train versus test gap so that overfitting is visible. When the held-out set is below 50 rows the metrics are labeled indicative only. Permutation importance with its standard deviation is reported alongside impurity importance, with a note that impurity importance is biased toward high-cardinality features.

The data-quality section calls out constant columns, duplicate rows, high-cardinality categoricals, class imbalance, missing targets, and features that look suspiciously predictive of the target (a simple leakage check). A limitations and next-steps section turns those warnings into concrete actions.

## Dirty data and clear failures

Real tabular data arrives messy, so the run path coerces and validates the data before modeling and records what it did.

- Messy numeric columns. A numeric column written with thousands separators, a currency symbol, or a percent sign is coerced to numeric when most of its non-empty values parse as numbers. Missing tokens that pandas does not treat as missing by default (a double dash, the word `missing`, and a bare `?`) are read as missing. Legitimate categories such as `Unknown`, `None`, and `Other` stay categories and are never turned into missing. Every coercion is written to the decision log.
- Boolean columns. A boolean column, in true/false, string, or numeric form, is cast to a 0/1 numeric array before imputation, and it is kept out of the outlier check, which has no meaning for a two-value column.
- Binary metrics for any labels. Precision, recall, f1, and roc_auc work for any pair of labels, not only the integer `1`. Targets labelled `<=50K`/`>50K`, `bad`/`good`, `yes`/`no`, and `1`/`2` are all handled. The positive class is chosen by a deterministic rule, the minority class, since that is usually the event of interest such as stroke, churn, or fraud, and it is recorded in the report.
- Class-imbalance safety. The train/test split is stratified, the cross-validation fold count is capped at the smallest class count so a five percent positive rate still trains, and a class too small to split and cross-validate stops the run with a clear message rather than a crash.
- Clear failures. When the library cannot handle the data it raises a `MudraError` that names the offending column and suggests a fix, instead of a raw pandas or scikit-learn traceback. File-read failures raise `IngestError`, a subclass of `MudraError`, so they are caught by the same handling.

## Stress tested

The pipeline is exercised against a battery of adversarial datasets: a tiny set, a single-feature set, a single-class target, an all-missing column, a constant column, all-duplicate rows, a wide dataset, an id-like high-cardinality feature, a strongly imbalanced target, mixed dtypes with messy datetimes, a leakage-injected dataset where a feature equals the target, a target with missing values, and a 10k-row dataset. All four task variants run: binary and multiclass classification, regression, and clustering.

## Scope

This release covers the supervised classification and regression cases and KMeans clustering, end to end, with the decision log and the report. Deep text modeling, time series, model-based imputation, and a search beyond curated grids are out of scope by design, since the engine is meant to stay explainable. See the changelog for the version history.

## License

MIT. See [LICENSE](LICENSE).
