Metadata-Version: 2.5
Name: michelangelo-examples
Version: 0.7.0
Summary: Pip-installable, ready-to-run example models and pipelines for Michelangelo
Author: Michelangelo maintainers
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Provides-Extra: bert-cola
Requires-Dist: accelerate>=0.26.0; extra == 'bert-cola'
Requires-Dist: datasets>=3.0; extra == 'bert-cola'
Requires-Dist: michelangelo>=0.12.0; extra == 'bert-cola'
Requires-Dist: minio<8,>=7.2; extra == 'bert-cola'
Requires-Dist: pytorch-lightning<3.0.0,>=2.2.0; extra == 'bert-cola'
Requires-Dist: ray[data,default]<3.0.0,>=2.55.1; extra == 'bert-cola'
Requires-Dist: s3fs>=2023.1.0; extra == 'bert-cola'
Requires-Dist: torch>=2.0; extra == 'bert-cola'
Requires-Dist: transformers<6,>=4.30; extra == 'bert-cola'
Provides-Extra: california-housing
Requires-Dist: michelangelo>=0.12.0; extra == 'california-housing'
Requires-Dist: minio<8,>=7.2; extra == 'california-housing'
Requires-Dist: pandas>=2.1; extra == 'california-housing'
Requires-Dist: pyarrow<26.0.0,>=19.0.0; extra == 'california-housing'
Requires-Dist: pyspark==4.2.0; extra == 'california-housing'
Requires-Dist: pytorch-lightning<3.0.0,>=2.2.0; extra == 'california-housing'
Requires-Dist: ray[data,default]<3.0.0,>=2.55.1; extra == 'california-housing'
Requires-Dist: s3fs>=2023.1.0; extra == 'california-housing'
Requires-Dist: scikit-learn>=1.3; extra == 'california-housing'
Requires-Dist: torch>=2.0; extra == 'california-housing'
Requires-Dist: xgboost-ray<1,>=0.1.19; extra == 'california-housing'
Requires-Dist: xgboost<4,>=2.0; extra == 'california-housing'
Provides-Extra: gpt-oss-20b-finetune
Requires-Dist: accelerate>=0.26.0; extra == 'gpt-oss-20b-finetune'
Requires-Dist: datasets>=3.0; extra == 'gpt-oss-20b-finetune'
Requires-Dist: michelangelo>=0.12.0; extra == 'gpt-oss-20b-finetune'
Requires-Dist: mlflow<3,>=2.0; extra == 'gpt-oss-20b-finetune'
Requires-Dist: peft<1,>=0.10; extra == 'gpt-oss-20b-finetune'
Requires-Dist: pytorch-lightning<3.0.0,>=2.2.0; extra == 'gpt-oss-20b-finetune'
Requires-Dist: ray[data,default]<3.0.0,>=2.55.1; extra == 'gpt-oss-20b-finetune'
Requires-Dist: s3fs>=2023.1.0; extra == 'gpt-oss-20b-finetune'
Requires-Dist: torch>=2.0; extra == 'gpt-oss-20b-finetune'
Requires-Dist: transformers<5,>=4.30; extra == 'gpt-oss-20b-finetune'
Provides-Extra: movielens
Requires-Dist: michelangelo>=0.12.0; extra == 'movielens'
Requires-Dist: pandas>=2.1; extra == 'movielens'
Requires-Dist: pytorch-lightning<3.0.0,>=2.2.0; extra == 'movielens'
Requires-Dist: ray[data,default]<3.0.0,>=2.55.1; extra == 'movielens'
Requires-Dist: torch>=2.0; extra == 'movielens'
Provides-Extra: nomic-ai
Requires-Dist: datasets>=3.0; extra == 'nomic-ai'
Requires-Dist: einops; extra == 'nomic-ai'
Requires-Dist: michelangelo>=0.11.0; extra == 'nomic-ai'
Requires-Dist: pytorch-lightning<3.0.0,>=2.2.0; extra == 'nomic-ai'
Requires-Dist: ray[data,default]<3.0.0,>=2.55.1; extra == 'nomic-ai'
Requires-Dist: torch>=2.0; extra == 'nomic-ai'
Requires-Dist: transformers<5,>=4.30; extra == 'nomic-ai'
Description-Content-Type: text/markdown

# michelangelo-examples

[![Test](https://github.com/michelangelo-ai/michelangelo-examples/actions/workflows/test.yaml/badge.svg)](https://github.com/michelangelo-ai/michelangelo-examples/actions/workflows/test.yaml)
[![Build examples Docker image](https://github.com/michelangelo-ai/michelangelo-examples/actions/workflows/build-image.yaml/badge.svg)](https://github.com/michelangelo-ai/michelangelo-examples/actions/workflows/build-image.yaml)

Pip-installable, ready-to-run example models and pipelines for
[Michelangelo](https://github.com/michelangelo-ai/michelangelo) — a
lightweight on-ramp for trying Michelangelo without a full monorepo
checkout, the heavyweight `example` extra, or a running sandbox.

```bash
pip install michelangelo-examples[<example-name>]
```

## Why this repo

The full example pipelines in
[`michelangelo/python/examples/`](https://github.com/michelangelo-ai/michelangelo/tree/main/python/examples)
are the canonical, full-fidelity reference — they exercise real
Cadence/Temporal orchestration, Spark, and a live sandbox, and they aren't
going anywhere. But trying one today means checking out the whole monorepo
and installing one heavyweight extra that bundles every example's
dependencies (`torch`, `transformers`, `xgboost`, `pyspark`, `ray`,
`mlflow`, `peft`, and more) at once, regardless of which example you
actually want.

`michelangelo-examples` is a second, lighter tier: each example is its own
pip extra with only the dependencies it needs, plus a plain-Python
`run_local.py` entrypoint that trains/evaluates locally — no Cadence, no
Spark, no sandbox. It's the "try it in five minutes" path underneath the
full pipeline reference, not a replacement for it.

## Examples

Ported so far:
- [`california_housing`](src/michelangelo_examples/california_housing/) — a
  project (use case) with one pipeline so far,
  [`pytorch_train`](src/michelangelo_examples/california_housing/pipelines/pytorch_train/)
  (California Housing price prediction via PyTorch Lightning, migrated from
  core `michelangelo`'s
  `python/examples/pipelines/california_housing_lightning/`). Structuring it
  as a project with a `pipelines/` subfolder leaves room for sibling
  pipelines against the same use case — e.g. a future `xgboost_train`
  pipeline — without another top-level rename.
- [`bert_cola`](src/michelangelo_examples/bert_cola/) — fine-tunes BERT for
  linguistic acceptability classification on the CoLA task, migrated from
  core `michelangelo`'s `python/examples/bert_cola/`.
- [`gpt_oss_20b_finetune`](src/michelangelo_examples/gpt_oss_20b_finetune/) —
  LoRA fine-tuning of GPT-style causal-LM checkpoints (architected for
  GPT-OSS-20B, tested against GPT-2 as a CPU-feasible proxy), migrated from
  core `michelangelo`'s `python/examples/gpt_oss_20b_finetune/`. Requires
  Python 3.11+ (see that project's own README).
- [`movielens`](src/michelangelo_examples/movielens/) — trains a tiny Neural
  Collaborative Filtering model on MovieLens-100k via Ray Train + PyTorch
  Lightning, migrated from core `michelangelo`'s
  `python/examples/movielens/`. Requires Python 3.11+ (see that project's
  own README).
- [`nomic_ai`](src/michelangelo_examples/nomic_ai/) — fine-tunes/encodes
  `nomic-ai/nomic-bert-2048`, a long-context (2048-token) BERT, over a
  WikiText-2 sample via PyTorch Lightning, migrated from core
  `michelangelo`'s `python/examples/nomic_ai/`. Requires Python 3.11+ (see
  that project's own README).

v1 candidates (not yet ported): `amazon_books_qwen`.
See the
[project spec](https://github.com/michelangelo-ai/michelangelo/tree/main/python/examples)
for the full list this repo is drawing from.

Each project lives entirely under
`src/michelangelo_examples/<project-name>/` — a real subpackage of the one
`michelangelo_examples` package this repo ships, including its
`pipeline.yaml`/`README.md` (bundled as package data so a plain `pip
install` gets everything, not just the Python code) alongside each
pipeline's model/training/task code and `__main__.py` local runner. Code
shared across a project's sibling pipelines (e.g. dataset loading/feature
prep) lives in `<project-name>/pipelines/libs/`.

## Installing a project

```bash
pip install "michelangelo-examples[california-housing]"
python -m michelangelo_examples.california_housing.pipelines.pytorch_train
```

Extras are scoped per **project**, not per pipeline: installing
`california-housing` pulls in the dependencies for every pipeline under
that project (today just `pytorch_train`), since they already
share one built image and mostly overlapping dependency sets.

The `pip install` + `python -m` commands above run the lightweight local
tier only. To run a pipeline's full Cadence-dispatched version against a
Michelangelo sandbox (`ma project apply` → `ma pipeline apply` →
`ma pipeline run`), see the end-to-end command sequence in that pipeline's
own README — e.g.
[`pytorch_train`'s](src/michelangelo_examples/california_housing/pipelines/pytorch_train/README.md#end-to-end-sandbox-to-running-pipeline).

## Relationship to other Michelangelo repos

- [`michelangelo`](https://github.com/michelangelo-ai/michelangelo) — the
  core platform; `python/examples/` there remains the full pipeline
  reference (Cadence/Temporal/Spark/sandbox).
- [`michelangelo-models`](https://github.com/michelangelo-ai/michelangelo-models) —
  pluggable model architecture definitions. Some examples here may import
  a seed architecture from there instead of defining their own model.

## Development

This repo uses [`uv`](https://docs.astral.sh/uv/) for dependency
management.

```bash
uv build
uv run pytest
```

## License

[Apache License 2.0](LICENSE)
