mudra-ml 0.5.2

Glass-box autonomous data science: profile, clean, model, and explain every decision.

Mudra-ML

A glass-box automated data science tool. Point it at a table and it profiles the columns, cleans the messy values, trains and tunes a shortlist of models, picks a winner, and writes a report that explains every decision it made and gives an honest read on whether to trust the result. It runs purely on scikit-learn, stays deterministic, and uses no large language model and no network calls.

What makes it different

• It shows its work. Every preprocessing and model choice is recorded in a decision log with the rule that produced it, the inputs the rule read, and the value it produced. Nothing is decided behind the curtain.
• It does not assume numbers. The test split, the cross-validation fold count, the per-column outlier fences, and the encoding boundaries are derived from the data, and the report states each derived value and the reason for it.
• It tells you whether to trust the result. The report opens with a plain-language trust summary and a comparison against a naive baseline, and a validation guard runs nested cross-validation where it fits and raises an optimism flag when the held-out score trails cross-validation beyond fold noise.
• It is deterministic. The same data and the same seed produce the same model, the same numbers, and reports that are identical apart from one labeled wall-clock line.

Install

pip install mudra-ml

The base install runs fully on scikit-learn. Two optional extras are available:

pip install mudra-ml[boost]    # add the xgboost, lightgbm, and catboost candidates
pip install mudra-ml[files]    # add the parquet and excel readers

The boosting libraries join the candidate shortlist only when they are installed. A missing one is skipped with a note in the decision log, never an error.

Quickstart

from mudra_ml import Mudra

result = Mudra().run("data.csv", target="churned")

print(result.task)         # classification, regression, or clustering
print(result.metrics)      # the chosen model's held-out scores
print(result.report_path)  # markdown and HTML written to disk

run accepts a file path (csv, tsv, json, and, with the files extra, excel and parquet) or a pandas DataFrame. If you do not name a target column, it infers a plausible one and records what it picked. The task and metric are inferred the same way when you do not set them.

What you get

The report is as much the product as the model. Open result.report_path for the markdown, or the .html file written next to it. It is laid out in pipeline order:

1. Trust summary: what the pipeline did, the headline metric against the naive baseline, the single biggest risk to trusting the result, and a short verdict that downgrades itself on a leakage suspect, a small test set, a weak lift over the baseline, or a flagged optimistic selection.
2. Run summary and data profile: row and column counts and the inferred type of every column.
3. Data quality: constant columns, duplicate rows, class balance, outlier counts, and features that look leaked from the target.
4. Preprocessing and split: imputation, outlier clipping, encoding, and scaling, all fitted on the training split only, with the derived test fraction.
5. Model shortlist and selection: which models were shortlisted and why, every candidate with its cross-validation score, the compute budget and anything trimmed to fit it, the winner's held-out metrics next to the baseline, the train-versus-test gap, and the validation guard.
6. Diagnostics: per-class breakdowns for classification or residual diagnostics for regression, feature importance with its uncertainty, the limitations, the full decision log by stage, and the fixed defaults with their reasons.

The fitted model saves to disk and reloads for prediction:

result.save("churn_model")            # writes churn_model.joblib and churn_model.json
loaded = Mudra.load("churn_model")    # restores the exact model

preds = loaded.predict(new_rows)          # new_rows is a pandas DataFrame
probs = loaded.predict_proba(new_rows)    # class probabilities, for classification

A saved then loaded model gives predictions identical to the original. The .json sidecar records the library version, python version, creation date, task, target, metric, selected model, seed, positive class, and the input schema. New rows are checked against that schema before prediction, so a missing column, an unexpected column, a changed type, or an unseen category raises a clear MudraError rather than a silently wrong number.

Models it can train

• Classification: logistic regression, decision tree, random forest, extra trees, gradient boosting, support vector classifier, k-nearest neighbors, and gaussian naive bayes.
• Regression: linear regression, ridge, elastic net, decision tree, random forest, extra trees, gradient boosting, support vector regressor, and k-nearest neighbors.
• Clustering: k-means with a swept cluster count.
• With the boost extra: xgboost, lightgbm, and catboost join the shortlist.

Which of these actually run depends on the data. K-nearest neighbors is tried only when the feature count is modest and the matrix is dense, and the kernel models are tried only when the row count keeps their cost reasonable. The report states which models were shortlisted and why.

What it is and is not

The aim is a trustworthy, readable, reproducible baseline on tabular data, not the top of an accuracy leaderboard. It covers binary and multiclass classification, regression, and k-means clustering, end to end, with an audit trail, on data that fits in memory. This is part of the pitch, not a footnote:

• No deep learning. Images, audio, and video are out of scope.
• Text columns are reduced to simple length features. For language understanding, use a dedicated text pipeline.
• No time-series forecasting. The random split assumes rows are exchangeable, which time series are not.
• Data larger than memory is not supported.
• Do not use the output for decisions that affect people without a person reviewing the report, the data-quality findings, and the limits of the data. The report flags many problems, and it cannot flag them all.

Version history

The full history lives in the CHANGELOG and on the releases page.

License

MIT. See LICENSE.