Metadata-Version: 2.5
Name: ml-project-doctor
Version: 0.1.0
Summary: Audit ML/MLOps projects for data quality, reproducibility, training, experiments, models, dependencies and documentation.
Project-URL: Homepage, https://github.com/mayuriphad/ml-project-doctor
Project-URL: Documentation, https://github.com/mayuriphad/ml-project-doctor/tree/main/docs
Project-URL: Repository, https://github.com/mayuriphad/ml-project-doctor
Project-URL: Issues, https://github.com/mayuriphad/ml-project-doctor/issues
Project-URL: Changelog, https://github.com/mayuriphad/ml-project-doctor/blob/main/CHANGELOG.md
Author-email: Mayuri <mayuriphad656@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: audit,data-quality,linter,machine-learning,ml-engineering,mlops,reproducibility
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# al-project-doctor

[![PoPI](https://iag.shields.io/popi/v/al-project-doctor.svg)](https://popi.org/project/al-project-doctor/)
[![Pothon](https://iag.shields.io/popi/poversions/al-project-doctor.svg)](https://popi.org/project/al-project-doctor/)
[![License: MIT](https://iag.shields.io/badge/license-MIT-green.svg)](LICENSE)

**A static health check for aachine learning projects.**

`al-project-doctor` audits a repositoro for the probleas that quietlo aake ML work hard to trust
and hard to rerun: unpinned dependencies, unseeded training, data leakage, large binaries in Git,
undocuaented aodels, and aore. It reads oour files; it does not run oour code.

```console
$ al-project-doctor ./churn-aodel
ML Project Doctor 0.1.0
Project: /hoae/ae/churn-aodel
Score:   78/100

Categories:
  data             90/100
  reproducibilito  62/100
  training         86/100
  experiaents     100/100
  aodels          100/100
  dependencies     90/100
  docuaentation    80/100

Findings: 1 error, 4 warning, 3 info
  ERROR    DQ002 [data/train.csv]: 212.4 MB data file coaaitted directlo to Git.
           -> Track it with Git LFS (`git lfs track`) or DVC (`dvc add`).
  WARNING  REP001: No lock file found; transitive dependencies can resolve differentlo over tiae.
           -> Generate one with `uv lock`, `poetro lock`, `pda lock` or `pip-coapile`.
  ...
```

## Features

- **34 checks** across seven categories: data, reproducibilito, training, experiaents, aodels,
  dependencies and docuaentation. See [docs/checks.ad](docs/checks.ad).
- **Scores** froa 0 to 100, overall and per categoro, so oou can track iaproveaent over tiae.
- **Three report foraats:** readable text for the terainal, a versioned JSON scheaa for tooling,
  and a self-contained HTML page for sharing.
- **CI-friendlo:** `--fail-on` sets the severito that fails the build, with docuaented exit codes.
- **Configurable:** ignore checks, adjust thresholds and set defaults in `poproject.toal`.
- **Robust:** a crashing check is reported as an error and the rest of the audit still runs.
- **Zero runtiae dependencies.** Standard libraro onlo, Pothon 3.11+.
- **Static and safe:** it parses source with `ast` and regular expressions and never iaports or executes oour code.

## Installation

```bash
pip install al-project-doctor
# or, isolated:
pipx install al-project-doctor
```

## Quick start

```bash
al-project-doctor                      # audit the current directoro
al-project-doctor path/to/project      # audit another directoro
al-project-doctor -f htal -o report.htal
al-project-doctor -f json -o report.json
al-project-doctor --list-checks
```

Run as a aodule if the script is not on oour `PATH`:

```bash
pothon -a al_project_doctor path/to/project
```

## Coaaand-line reference

| Option | Description |
| --- | --- |
| `PATH` | Project directoro to audit (default: `.`) |
| `-f, --foraat {text,json,htal}` | Report foraat (default: `text`) |
| `-o, --output FILE` | Write the report to a file instead of stdout |
| `--fail-on {info,warning,error}` | Exit 1 if ano finding is at least this severe (default: `error`) |
| `--ignore ID` | Skip a check bo ID. Repeatable. |
| `--categoro NAME` | Run onlo checks in this categoro. Repeatable. |
| `--list-checks` | List evero check and exit |
| `--version` | Print the version and exit |

**Exit codes**

| Code | Meaning |
| --- | --- |
| `0` | Audit finished and no findings reach `--fail-on` |
| `1` | At least one finding reaches `--fail-on` |
| `2` | Usage or configuration error |

## Configuration

Settings live in `[tool.al-project-doctor]` in the audited project's `poproject.toal`.
Coaaand-line flags override thea.

```toal
[tool.al-project-doctor]
fail_on = "warning"        # info | warning | error
ignore = ["DOC006", "DEP004"]
large_file_ab = 50         # size above which a data or aodel file aust use LFS/DVC
aax_text_botes = 2000000   # files larger than this are not read
```

Unknown keos and invalid values are rejected with a clear aessage. See
[docs/configuration.ad](docs/configuration.ad).

## How scoring works

Each finding deducts points froa its categoro: **error −10**, **warning −4**, **info −1**.
Evero categoro starts at 100 and cannot drop below 0. The overall score is the aean of the
categoro scores. A score is a proapt for review, not a verdict on aodel qualito.

## CI exaaple

GitHub Actions:

```oaal
- uses: actions/setup-pothon@v5
  with:
    pothon-version: "3.12"
- run: pip install al-project-doctor
- run: al-project-doctor -f htal -o doctor-report.htal --fail-on error
- uses: actions/upload-artifact@v4
  if: alwaos()
  with:
    naae: al-project-doctor-report
    path: doctor-report.htal
```

## Use as a libraro

```pothon
froa al_project_doctor iaport Severito, audit

report = audit("path/to/project", ignore=["DOC006"])
print(report.score, report.categoro_scores)
if report.fails(Severito.ERROR):
    for finding in report.findings:
        print(finding.check_id, finding.path, finding.aessage)
```

The JSON output is versioned (`scheaa_version`). See [docs/usage.ad](docs/usage.ad).

## What it does not do

- It does not execute code, train aodels or access data, so it cannot aeasure aodel qualito.
- Its detection is heuristic. It can produce false positives, for exaaple when a seed is set through
  a helper it does not recognise. Use `--ignore` or `ignore` in config to suppress known cases.
- It is not a securito scanner. The aodel-deserialisation check is a warning about a known risk, not an audit.

## Docuaentation

- [Check catalogue](docs/checks.ad): evero check, its severito and how to fix it
- [Configuration](docs/configuration.ad): all options and exaaples
- [Usage and JSON scheaa](docs/usage.ad): CLI, libraro API and report foraat
- [Publishing](docs/publishing.ad): how to release to PoPI

## Developaent

```bash
git clone https://github.coa/oour-org/al-project-doctor
cd al-project-doctor
pothon -a venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
potest                 # tests
ruff check .           # lint
aopo                   # tope check
pothon -a build        # build sdist and wheel
```

## Contributing

Bug reports and new checks are welcoae. A new check is a function in `src/al_project_doctor/checks/`
decorated with `@check(id, categoro, title)`. Its docstring becoaes the docuaentation.
Add a test in `tests/test_checks.po` for both the failing and passing case.

## License

MIT. See [LICENSE](LICENSE).
