{"id":50784680,"url":"https://github.com/muditnautiyal-21/mudra-ml","last_synced_at":"2026-06-12T07:00:35.963Z","repository":{"id":362598590,"uuid":"1259899268","full_name":"MuditNautiyal-21/mudra-ml","owner":"MuditNautiyal-21","description":"Glass-box autonomous data science in Python. Profiles data, builds leakage-safe pipelines, recommends and tunes models, and logs every decision behind the result.","archived":false,"fork":false,"pushed_at":"2026-06-05T02:11:53.000Z","size":56,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T00:10:18.799Z","etag":null,"topics":["automl","classification","clustering","data-science","explainable","machine-learning","pipeline","python","regression","scikit-learn"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mudra-ml/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MuditNautiyal-21.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T01:11:39.000Z","updated_at":"2026-06-05T02:11:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MuditNautiyal-21/mudra-ml","commit_stats":null,"previous_names":["muditnautiyal-21/mudra-ml","muditnautiyal-21/mudraml"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/MuditNautiyal-21/mudra-ml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuditNautiyal-21%2Fmudra-ml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuditNautiyal-21%2Fmudra-ml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuditNautiyal-21%2Fmudra-ml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuditNautiyal-21%2Fmudra-ml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MuditNautiyal-21","download_url":"https://codeload.github.com/MuditNautiyal-21/mudra-ml/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuditNautiyal-21%2Fmudra-ml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34232790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automl","classification","clustering","data-science","explainable","machine-learning","pipeline","python","regression","scikit-learn"],"created_at":"2026-06-12T07:00:15.277Z","updated_at":"2026-06-12T07:00:35.958Z","avatar_url":"https://github.com/MuditNautiyal-21.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mudra-ML\n\nPoint it at a table of data. It cleans the data, trains several models, picks the best one, and writes a report that explains every choice it made.\n\n[![PyPI version](https://img.shields.io/pypi/v/mudra-ml.svg?v=1)](https://pypi.org/project/mudra-ml/)\n[![Python versions](https://img.shields.io/pypi/pyversions/mudra-ml.svg?v=1)](https://pypi.org/project/mudra-ml/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![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)\n\n## What it does\n\nMudra-ML automates the routine part of supervised machine learning on tables: reading the file, working out what each column holds, repairing messy values, splitting the data safely, choosing which algorithms to try, tuning them, and measuring the winner on data it never saw during training. Every one of those choices follows a written rule, and every rule that fired is logged and printed in the report. Nothing is decided by a hidden model, and the library never calls the network.\n\n## Install\n\n```\npip install mudra-ml\n```\n\nOptional extras:\n\n```\npip install mudra-ml[files]    # parquet and excel readers\npip install mudra-ml[boost]    # xgboost, lightgbm, and catboost candidates\n```\n\nThe base install runs fully on scikit-learn. The boosting libraries join the candidate list only when they are installed. A missing one is skipped with a note in the log, never an error.\n\n## Quickstart\n\n```python\nfrom mudra_ml import Mudra\n\nm = Mudra()\nresult = m.run(\"data.csv\")\n\nprint(result.task)          # what it decided to do\nprint(result.metrics)       # how well the chosen model did\nprint(result.report_path)   # the full explanation, on disk\n```\n\nThat is the whole loop. `run` accepts a file path (csv, tsv, excel, json, or parquet) or a pandas DataFrame. If you do not name a target column, it looks for a plausible one and tells you what it picked. The report lands next to your script as markdown and HTML.\n\n## Classification\n\nClassification predicts a label, such as whether a customer leaves or stays. Name the column you want predicted:\n\n```python\nresult = Mudra().run(\"churn.csv\", target=\"churned\")\n\nprint(result.metrics[\"f1\"])\nprint(result.positive_label)   # the class treated as the event of interest\n```\n\nFor a two-class target the minority class is treated as the positive class, because the rarer outcome (the churn, the fraud, the diagnosis) is usually the one you care about. The report records this choice.\n\n## Regression\n\nRegression predicts a number, such as a price:\n\n```python\nresult = Mudra().run(\"houses.csv\", target=\"price\")\n\nprint(result.metrics[\"rmse\"])   # typical size of the prediction error\nprint(result.metrics[\"r2\"])     # share of variation the model explains\n```\n\n## Clustering\n\nClustering groups similar rows when there is nothing to predict:\n\n```python\nresult = Mudra().run(\"customers.csv\", task=\"clustering\")\n\nlabels = result.predict(my_dataframe)   # cluster id per row\n```\n\n## Steering the run\n\nYou can set as much or as little as you want. Anything you do not set is inferred and the report says so.\n\n```python\nresult = Mudra(random_state=7).run(\n    \"churn.csv\",\n    target=\"churned\",\n    task=\"classification\",\n    metric=\"f1\",\n    constraints={\"interpretable\": True, \"max_train_seconds\": 120},\n)\n```\n\nWith `interpretable` set, only models a person can read directly are trained, such as logistic regression and a small decision tree.\n\n## What data it accepts\n\nTables. One row per example, one column per attribute, with a header row. Numeric, categorical, boolean, date, text, and id columns are all recognized and handled. Messy values that real exports produce are repaired on the way in:\n\n- Numbers written as text, with thousands separators, currency symbols, or percent signs, are parsed back to numbers.\n- Missing-value spellings that pandas does not catch (`--`, `?`, the word `missing`) are treated as missing. Real categories such as `Unknown` or `Other` are left alone.\n- Booleans written as `yes`/`no`, `true`/`false`, `t`/`f`, or 0/1 all work.\n- Dates are expanded into year, month, day, and weekday features.\n- Id columns carry no signal and are dropped.\n\nData the library cannot handle stops the run with a `MudraError` that names the column, states the problem, and suggests a fix. You never see a raw pandas or scikit-learn traceback.\n\n## What happens at each step\n\n1. Ingest. The file is read. Delimiter, encoding, and header row are detected.\n2. Profile. Each column gets a type (numeric, categorical, boolean, date, text, id) by rule.\n3. Goal. Target, task, and metric are taken from you or inferred, in that order of priority.\n4. Quality. Constant columns, duplicate rows, class imbalance, and features that look leaked from the target are flagged.\n5. Preprocess. Imputation, outlier clipping, encoding, and scaling are fitted on the training split only, so nothing from the test split can leak into the model.\n6. Recommend. A documented rule set picks a small shortlist of algorithms that fit the task, the dataset size, the dimensionality, and the sparsity. It never runs every model on every dataset.\n7. Tune and select. Each shortlisted model is tuned with a fixed-seed randomized search. The best is chosen by cross-validation alone. The held-out test set is scored once, for the winner, for reporting only.\n8. Report. Markdown and HTML, listing every decision and the rule that produced it.\n\n## Models it can train\n\nClassification: 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. XGBoost, LightGBM, and CatBoost join the shortlist when the `boost` extra is installed.\n\nWhich of these actually run depends on your data. For example, k-nearest neighbors is only tried when the feature count is modest and the data is dense, and kernel models are only tried when the row count keeps their cost reasonable. The report states which models were shortlisted and why.\n\n## Save, load, and predict on new data\n\n```python\nresult = Mudra().run(\"churn.csv\", target=\"churned\")\n\npath = result.save(\"churn_model\")        # writes churn_model.joblib + churn_model.json\nloaded = Mudra.load(\"churn_model\")       # restores the exact model\n\npreds = loaded.predict(new_dataframe)          # labels\nprobs = loaded.predict_proba(new_dataframe)    # class probabilities\n```\n\nA saved then loaded model gives predictions identical to the original. The `.json` file next to the model records the library version, python version, creation date, task, target, metric, selected model, seed, positive class, and the input schema.\n\nNew data is checked against that schema before prediction. A missing column, an unexpected column, a column whose type changed, or a category the model never saw all raise a clear `MudraError` instead of returning silently wrong numbers.\n\nThe result object has a stable surface you can build on: `best_model`, `pipeline`, `metrics`, `report_path`, `task`, `target`, `feature_names`, `positive_label`, and `model_path`.\n\n## The decision report\n\nThe report is the product as much as the model is. Open `result.report_path` (markdown) or the `.html` file next to it. It contains the goal and which parts of it were inferred, the full decision log by stage, the data-quality findings, every candidate model with its cross-validation score, the winner's held-out metrics next to a naive baseline, the train-versus-test gap, per-class breakdowns and curves for classification, residual diagnostics for regression, and feature importance with its uncertainty.\n\n## Determinism\n\nOne seed is threaded through the split, the search, the estimators, and any sampling. Two runs on the same input produce the same model, the same numbers, and byte-identical reports. Set the seed with `Mudra(random_state=...)`.\n\n## Command line\n\n```\nmudra-ml run data.csv --target churn --metric f1 --save churn_model\nmudra-ml profile data.csv\n```\n\n`run` trains and writes the report. `profile` prints the inferred column types, missingness, cardinality, and candidate targets without training anything.\n\n## Scope\n\nMudra-ML is built for tabular data that fits in memory: the everyday spreadsheet, database extract, or csv export with up to a few hundred thousand rows. It covers binary and multiclass classification, regression, and k-means clustering, end to end, with an audit trail.\n\n## Limits\n\nKnow what it does not do, and when not to use it:\n\n- No deep learning. Images, audio, and video are out of scope.\n- Text columns are reduced to simple length features. For real language understanding, use a dedicated text pipeline.\n- No time-series forecasting. The random split assumes rows are exchangeable, which time series are not.\n- Data larger than memory is not supported.\n- Do not use the output for decisions that affect people (credit, hiring, medical, legal) 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.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuditnautiyal-21%2Fmudra-ml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuditnautiyal-21%2Fmudra-ml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuditnautiyal-21%2Fmudra-ml/lists"}