ml-modelfoundry 0.8.2__py3-none-any.whl

ml_modelfoundry-0.8.2.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: ml-modelfoundry
+Version: 0.8.2
+Summary: Compile a YAML recipe into a reproducible, framework-agnostic trained-model instance.
+Project-URL: Homepage, https://github.com/pointmatic/modelfoundry
+Project-URL: Repository, https://github.com/pointmatic/modelfoundry
+Project-URL: Issues, https://github.com/pointmatic/modelfoundry/issues
+Author: Pointmatic
+Maintainer: Pointmatic
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: machine-learning,model-training,optuna,pytorch,reproducibility
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.12
+Requires-Dist: matplotlib
+Requires-Dist: ml-datarefinery>=0.20.0
+Requires-Dist: numpy
+Requires-Dist: optuna
+Requires-Dist: pandas
+Requires-Dist: pillow
+Requires-Dist: pyarrow
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Requires-Dist: scikit-learn
+Requires-Dist: typer
+Provides-Extra: huggingface
+Requires-Dist: evaluate>=0.4; extra == 'huggingface'
+Requires-Dist: peft>=0.10; extra == 'huggingface'
+Requires-Dist: transformers>=4.40; extra == 'huggingface'
+Provides-Extra: keras
+Requires-Dist: keras>=3.0; extra == 'keras'
+Requires-Dist: tensorflow>=2.16; extra == 'keras'
+Provides-Extra: llm
+Requires-Dist: lmentry; extra == 'llm'
+Provides-Extra: notebook-smokes
+Requires-Dist: ipykernel; extra == 'notebook-smokes'
+Requires-Dist: nbclient; extra == 'notebook-smokes'
+Provides-Extra: pytorch
+Requires-Dist: torch>=2.5; extra == 'pytorch'
+Requires-Dist: torchinfo>=1.8; extra == 'pytorch'
+Requires-Dist: torchmetrics>=1.4; extra == 'pytorch'
+Requires-Dist: torchvision>=0.20; extra == 'pytorch'
+Provides-Extra: sklearn
+Description-Content-Type: text/markdown
+
+# ModelFoundry
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+
+Compile a YAML recipe into a reproducible, framework-agnostic trained-model instance.
+
+ModelFoundry consumes a materialized [DataRefinery](https://github.com/pointmatic/datarefinery) instance and compiles a single YAML **model recipe** into a content-addressed, atomically-promoted **ModelInstance**: the trained model, per-epoch metrics, hyperparameter-search trials, held-out evaluation, predictions, visualizations, and a manifest. The result object returns notebook-shaped primitives (`pandas.DataFrame` / `numpy.ndarray` / PNG `bytes`) and works identically inside Jupyter, Marimo, IPython, or a plain `.py` script — no framework imports in user code.
+
+Reproducibility is a first-class concern: every stochastic source is seeded, the cache identity is computed from the recipe's normalized semantic form, and the same `(recipe, data, seed, variant)` tuple materializes to a byte-identical `ModelInstance`.
+
+> **Status:** pre-production (`0.x.y` series). APIs, CLI surface, and cache layout may change between minor versions until the `1.0.0` production release. See [`docs/specs/`](docs/specs/) for the concept, feature, technical, and story specifications.
+
+## Installation
+
+```bash
+pip install ml-modelfoundry[pytorch]
+```
+
+The import name and console script are both `modelfoundry`; the PyPI distribution is `ml-modelfoundry`. The pre-production release ships an end-to-end **PyTorch** plugin (image classification, CIFAR-10-scale) plus a scikit-learn `MLPClassifier` baseline; the base install (`pip install ml-modelfoundry`) carries everything except the framework — a recipe selects its backend via the `[pytorch]` extra.
+
+## Quickstart — CIFAR-10
+
+ModelFoundry never does data prep: splitting, cleaning, sampling, and feature engineering are DataRefinery's job. The quickstart assumes the two bundled recipes — `recipes/cifar10-base.yaml` (the DataRefinery dataset recipe) and `recipes/cifar10_resnet20.yml` (the ModelFoundry ResNet-20 recipe, bound to it).
+
+```bash
+# 1. Materialize the CIFAR-10 dataset with DataRefinery (one-time) → ./data
+datarefinery materialize recipes/cifar10-base.yaml
+
+# 2. Validate, then materialize the model with ModelFoundry → ./models
+modelfoundry validate    recipes/cifar10_resnet20.yml
+modelfoundry materialize recipes/cifar10_resnet20.yml
+```
+
+`materialize` runs the full pipeline — hyperparameter optimization → training → held-out evaluation → output-expectation checks → persistence → report — and atomically promotes the result into the content-addressed cache. Re-running the same recipe finds the existing instance; pass `--overwrite` to recompute.
+
+Then consume the materialized instance — from a script, a notebook, or the CLI:
+
+```python
+from datarefinery import DataRefinery
+from modelfoundry import ModelFoundry
+
+data = DataRefinery.from_recipe("recipes/cifar10-base.yaml").materialize()
+model = ModelFoundry.from_recipe("recipes/cifar10_resnet20.yml", data=data).materialize()
+
+model.evaluation["test"]   # dict[str, value] — held-out metrics for the test split
+model.metrics              # alias for .evaluation: {split: {metric: value}}
+model.confusion_matrix     # dict[str, np.ndarray] — per-split confusion matrices
+model.predictions          # pandas.DataFrame — per-record predictions + class probabilities
+model.figures              # dict[str, bytes] — reporting-visualization PNGs, keyed by name
+model.predict(X)           # np.ndarray — predicted labels for new inputs
+```
+
+## Library API
+
+`ModelFoundry.from_recipe(...)` binds a recipe to a materialized DataRefinery instance; the verbs (`validate` / `materialize` / `status` / `inspect` / `report` / `clean` / `check`) are thin methods over that binding, co-equal with the CLI.
+
+```python
+from modelfoundry import ModelFoundry, ModelInstance
+
+mf = ModelFoundry.from_recipe("model.yml", data=data)
+
+report = mf.validate()              # FR-2 static checks; report.passed is a bool
+instance = mf.materialize()         # train + optimize + evaluate; returns a ModelInstance
+
+# A reloaded instance predicts identically (byte-stable round-trip):
+reloaded = ModelInstance.load(instance.path)
+```
+
+`data` may be a pre-bound `DataRefineryInstance` (as above) or a path to the DataRefinery cache root, in which case the recipe's `Data:` block is resolved against it.
+
+## CLI
+
+```bash
+modelfoundry check                              # environment + plugin health
+modelfoundry validate    <recipe>               # static FR-2 recipe checks
+modelfoundry materialize <recipe> [--overwrite] # train + optimize + evaluate
+modelfoundry status      <recipe>               # is it materialized? show the manifest
+modelfoundry report      <instance-dir>         # re-render the instance report
+modelfoundry inspect     <instance-dir> --view training_curves
+modelfoundry clean       --older-than 7d        # cache management
+modelfoundry init        <recipe-out> --data <datarefinery-recipe>   # scaffold a recipe
+```
+
+Shared options apply to every verb: `--cache-root` / `--data-cache-root` (defaults `./models` and `./data`), `--log-level`, `--log-target` (JSON-lines operational logs), `--plugin-path`, and `-v` / `-q`.
+
+## Notebook-substrate-neutral
+
+The same surface works identically in a Jupyter cell, a Marimo cell, an IPython REPL, or a plain `.py` script — the `ModelInstance` returns plain `pandas` / `numpy` / PNG-`bytes` primitives, so user code imports no framework:
+
+```python
+from IPython.display import Image
+
+mi = ModelFoundry.from_recipe("model.yml", data=data).materialize()
+Image(mi.figures["training_curves"])   # render the reporting PNG
+mi.predictions.head()                  # a DataFrame, renders natively in any host
+```
+
+## Choosing an accelerator
+
+Hardware acceleration is **auto-detected** by default — the PyTorch plugin picks Metal (Apple Silicon) → CUDA → CPU in that order. To pin a specific device (e.g. for CPU-speed benchmarking on a GPU-equipped machine, or to debug a non-deterministic op), set `Training.device` in the recipe:
+
+```yaml
+Training:
+  max_epochs: 10
+  batch_size: 32
+  device: cpu              # one of: auto (default) | cpu | cuda | mps
+```
+
+`device` participates in the recipe's canonical hash, so the same recipe run with `device: cpu` and `device: mps` materializes into two distinct `ModelInstance` cache entries — no silent cross-device collision. Use the `variants:` block to keep both side-by-side without maintaining two recipe files:
+
+```yaml
+variants:
+  cpu_bench:
+    Training: {device: cpu}
+```
+
+```bash
+modelfoundry materialize model.yml --variant cpu_bench
+```
+
+## Documentation
+
+- [`docs/specs/concept.md`](docs/specs/concept.md) — why the project exists
+- [`docs/specs/features.md`](docs/specs/features.md) — what it does (CR / FR / UR / TR requirements)
+- [`docs/specs/tech-spec.md`](docs/specs/tech-spec.md) — how it is built
+- [`docs/specs/project-essentials.md`](docs/specs/project-essentials.md) — must-know invariants (cache identity, determinism, loose coupling)
+- [`docs/specs/stories.md`](docs/specs/stories.md) — the implementation plan
+
+## License
+
+Apache-2.0. Copyright (c) 2026 Pointmatic.

ml_modelfoundry-0.8.2.dist-info/RECORD

@@ -0,0 +1,75 @@
+modelfoundry/__init__.py,sha256=YPLRz-A0Uw9gmB9sDcJDRxAa36MtARmUJHbsBwarRQc,1145
+modelfoundry/__main__.py,sha256=PCCSod2_bbKljHUM8CjvvpV3z9INKZcW_1VRz28OvuM,249
+modelfoundry/_version.py,sha256=OoL4fdHRLWahGFYKUDDrWnt3JIDWbUAHwKw8XH96T0o,147
+modelfoundry/logging.py,sha256=I36gq9wIgMywZbkwc9Z4Qz52Dzq7PUvGWhm5i6601Mg,5029
+modelfoundry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modelfoundry/cache/__init__.py,sha256=YR1oai2_JWk4Ze4N9y7u2Uur5En3xhpL4Ht8LhcPQFk,227
+modelfoundry/cache/atomic.py,sha256=k5Yz1eh4L1BY-gcE3nCbeEAfY1UvYix5VfNeiS-iG00,5518
+modelfoundry/cache/cleaner.py,sha256=S6YIMMU4HjgR22rdYKR0FpYh69jq2xdCDKDxJVdmPLc,6206
+modelfoundry/cache/identity.py,sha256=KERkKARUdpAzcJraccPFOdvv1H0rytQbK8QAUsclxsM,2731
+modelfoundry/cache/layout.py,sha256=MADTvJFtqAxAIdDnnbrpw5SLPz4SXVR7pKhiYo-1OV0,4253
+modelfoundry/cli/__init__.py,sha256=OOrDW-YXy7mLw9u445fDL1D1Ec-w6LsaxNxmyvM-1tk,394
+modelfoundry/cli/app.py,sha256=hMxayCxuxKVMnJvUWmqgvPp3Ix6teV9erkMU8AmPfc0,13431
+modelfoundry/cli/commands/__init__.py,sha256=Aag3S7YpT5n4YfvWgf-Yc1E4Tp3szXg1l3G4_CiYC-4,322
+modelfoundry/cli/commands/check_cmd.py,sha256=qr6tn7P4sXqWU_jLTFoqzF_WuGvUbIo-xtaJlunc27I,2898
+modelfoundry/cli/commands/clean_cmd.py,sha256=bZpthagsWgOopXSMWt88CQ0yQHap5TmNW__eoTqojPY,2537
+modelfoundry/cli/commands/init_cmd.py,sha256=jrqq0yUnIdkN08v1CoKq4aemcqgmtmnoLrqM-XuR1KA,1303
+modelfoundry/cli/commands/inspect_cmd.py,sha256=-TlMjCvWld74uFwghe7XswwRUog2WXFnY4UobAQZums,3030
+modelfoundry/cli/commands/materialize_cmd.py,sha256=HiuXBT46Y5fSCjXRTPxeYGbQjVwjBCcCPRwtuBcXnzE,5689
+modelfoundry/cli/commands/report_cmd.py,sha256=Fk6P_ILV2kWuElDueFnQPxjRr3bFMgAo_LWSbNM87kg,2174
+modelfoundry/cli/commands/status_cmd.py,sha256=PY47LwH28vae1KAPs_ZM3Fe9SGeO-XTkG3ZXJK9IJUA,3904
+modelfoundry/cli/commands/validate_cmd.py,sha256=wYi716uljW4QAbQsMebOH94RO2QXcpmTD14t4oh7oEc,2209
+modelfoundry/core/__init__.py,sha256=UkXtUtM-earS-j5ouExh9xX5piRUZXlqLf_T-RBXVRc,241
+modelfoundry/core/config.py,sha256=pcGYWAst_d9Odxc_rfNU0hlXHOFyolUleh0bGnWhHHE,2283
+modelfoundry/core/errors.py,sha256=MIAeuF4sda2pSTPJgCclWoKoEGFWzohuNesRGmHxeyQ,2619
+modelfoundry/core/instance.py,sha256=uvZYgA-5aI5qFPZNYrU1fau9dpy3IudgAYVrFik5JPk,14329
+modelfoundry/core/manifest.py,sha256=fxt-OzlxSPvUIB-_TPzv7pmrZT4aJ3WHxBqEC6kk6S0,3429
+modelfoundry/core/modelfoundry.py,sha256=RIfFInTVY2LALfC3ZEESD_Qi_XMCBNH1vyVbI_QH0Sc,13146
+modelfoundry/pipeline/__init__.py,sha256=UmyBMcKW2ULIudUOt495kd5Frl3eV8N0_WIkvoYlie4,244
+modelfoundry/pipeline/checkpoint.py,sha256=StkGICrq_h6XplJBHU9RwQk5_hmSy1mOoAr4c98BZOs,2196
+modelfoundry/pipeline/data_binding.py,sha256=6F8gi-gyOGgP3qVn9k-AxklE0YEjV9mOM4R-bjyQ1QA,9305
+modelfoundry/pipeline/expectations.py,sha256=z2nCDuPk-KVW-J0Yb7KtzDsooKL4w5D7J0cEPrgWNUk,3416
+modelfoundry/pipeline/progress.py,sha256=bIp_ysuM95VktH7uMh-peUrWkHVOKu59XiAakyA3OZA,3116
+modelfoundry/pipeline/runner.py,sha256=SP_ORj_jgm7Emo4k_IrbAjvymUmmiflq-F4HMySq4LE,12225
+modelfoundry/pipeline/seeding.py,sha256=4-RN00hossxy4LH3sHkNu5TZA8yJij7x_OWLuWS-XKE,3309
+modelfoundry/plugins/__init__.py,sha256=0GsFEHsmUsgXCytoIdsb0gaT5u8LqkWnyKg0HxHRCdI,226
+modelfoundry/plugins/base.py,sha256=ptwSVJHADP0hqYBRrN3_DPM8KZ4M4exC6V35czor_WQ,5953
+modelfoundry/plugins/discovery.py,sha256=POQxR9iltdJSNaiCr1r3YTrPXT01HxJLRZshJCJi44s,3161
+modelfoundry/plugins/pytorch/__init__.py,sha256=8IaYIxehuy6c9MkERru-_RurVXGrrXJuFb4CHS_eW0k,698
+modelfoundry/plugins/pytorch/architecture.py,sha256=Wgr4NALNUwlmytNUTtLWso6IlE8yeWLmdUi1HQoIrJg,16446
+modelfoundry/plugins/pytorch/augmentations.py,sha256=1AO2O0zD0_P8eLBWa8HkPKDYmOGvs2v1Sgle2QeniGw,10199
+modelfoundry/plugins/pytorch/data.py,sha256=JKLO1Nl5gman6vIxyuSt8Epz1VlcO6GGhXUqXg8WuX8,9841
+modelfoundry/plugins/pytorch/determinism.py,sha256=ZqMHTblUWbIIj5C0Ts6cfOHcYwyMGfUm7a4q42qkZl0,2542
+modelfoundry/plugins/pytorch/evaluation.py,sha256=UhAO2CAJJvRpQKBX_sI-FExRBoyIr-MI8scsCTVlbXE,9690
+modelfoundry/plugins/pytorch/losses.py,sha256=7498eVfbUBtCK0YagmkLPIsjOPS1ZWVfNwpx-Rxp8HU,5169
+modelfoundry/plugins/pytorch/optimization.py,sha256=O4NPg1M-iAsmct3I8RSPofyNsZZjjhr5ZrVtN9U9P0A,8106
+modelfoundry/plugins/pytorch/optimizers.py,sha256=KiMAQZN3V1Ee_WzdAdgVWfT9OoRuY6NFMt2YF4EIHJk,2839
+modelfoundry/plugins/pytorch/persistence.py,sha256=cCbGUo7298_By5ksSYjs_WfUxI-WhfPdmHDPNQgkQ4k,7070
+modelfoundry/plugins/pytorch/plugin.py,sha256=B1VWzGVI5Faky8tesVPxznK-vuekdO3cVtG0WyRm-pw,9451
+modelfoundry/plugins/pytorch/schedules.py,sha256=QwRkARutt-aBs9Yha4nwWw5on1sEzYdAYTIiN8zbz3k,3365
+modelfoundry/plugins/pytorch/summary.py,sha256=HwN-gmxE5HPriOOAvQIHeydqj36zueOGFbPphOVIYZc,6384
+modelfoundry/plugins/pytorch/trainer.py,sha256=WdlWrCbbB2MZU21kRJhpKCBuP-ScxF_UDIKAhBofVLY,15093
+modelfoundry/plugins/pytorch/visualization_specs.py,sha256=-9IsR84UNqI96uxjvgQbfC30RCCDaahUGeWiOk_hxi8,2227
+modelfoundry/plugins/pytorch/visualizations.py,sha256=L4394lTJhNQHiN0KlDmHY4eTEGpa1MMiEO5PBTVj7Dw,8281
+modelfoundry/plugins/sklearn/__init__.py,sha256=J23oTVqdwGhD-5Ejc0aBDHhOrE83fZdx8H-68KrKNVE,340
+modelfoundry/plugins/sklearn/data.py,sha256=dYk9zDT7GG8NL4DTjztCtprCunXD45cZaf-iUu_5grY,2252
+modelfoundry/plugins/sklearn/metrics.py,sha256=qZ6CNlIXz7Q6w87_BEXVo2xjgqWqNFIrh5mQxQkLjgw,4975
+modelfoundry/plugins/sklearn/plugin.py,sha256=FSiJLm5jArdKq9H0XJBIsvOZqLZxcbDkRPlW-DTDe3Q,14582
+modelfoundry/recipe/__init__.py,sha256=90e4-0_XELXtBqSl7atWCYjrhchhmB5WFS0zrqJ1yEU,238
+modelfoundry/recipe/canonical.py,sha256=Eh8AdCPTI0dgjDad-AXwLmQbLP2hME1DNSqlcjHxU_Y,1592
+modelfoundry/recipe/loader.py,sha256=zpKylKbJdq-xyDKtDzdgIWPSuB2F7wGR1hmFCJCkffA,3359
+modelfoundry/recipe/models.py,sha256=bTJOu6i-DRq8yePNP21VC85ISneFnnx0Yh-4D_U15dU,4630
+modelfoundry/recipe/search_space.py,sha256=oMzLlI7DJt_IwifRYgx8RZGnXlByiC8ty2zHmqK_sgE,5411
+modelfoundry/recipe/validator.py,sha256=FYHfemYRuSTOUWrpvk6WmXEAPoSBrTywE8G620zBEZs,18806
+modelfoundry/recipe/variants.py,sha256=qTkzZN9doY-fTQMwWVT_H0kiWVTWSm-8nNnYjRYDA2o,2370
+modelfoundry/reporting/__init__.py,sha256=yvLNy7QMw2h-gO5_Xc6l9dQrV19jcfyiS1jCJNCfnqU,412
+modelfoundry/reporting/report.py,sha256=3g-bua2NrvC3n_zvfGQJpEbNunS5dzGkIccfvGJk0sU,6277
+modelfoundry/reporting/visualizations.py,sha256=OyrEuCpJ8niPEYjj_PGFE9C-3kG2XxGfLHt6r2xpPrE,3428
+modelfoundry/scaffolder/__init__.py,sha256=Ytc1BejTHsU13_Z8OvZ12OoMfsxY7WPa7Fpez08hu9E,395
+modelfoundry/scaffolder/init.py,sha256=Kt_dTIAaHSskwNFZyF-FDXbtESJCHHRo5y8kJ3Y39qg,5612
+modelfoundry/scaffolder/llm.py,sha256=1StNXjr5KXyRrAq1mV5jbhroViCLuqhLsE5hl7jLZC0,473
+ml_modelfoundry-0.8.2.dist-info/METADATA,sha256=EOLZl1N1NDQYld3SJg9RlFUWLjH7WynUsaxwUrgnSr0,9315
+ml_modelfoundry-0.8.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ml_modelfoundry-0.8.2.dist-info/entry_points.txt,sha256=iOYfRxmcypTG67EfoJ3sO1WbyqDnWRPmKe3uV5RwZBA,189
+ml_modelfoundry-0.8.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+ml_modelfoundry-0.8.2.dist-info/RECORD,,

ml_modelfoundry-0.8.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ml_modelfoundry-0.8.2.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+modelfoundry = modelfoundry.cli.app:main
+
+[modelfoundry.plugins]
+pytorch = modelfoundry.plugins.pytorch.plugin:plugin
+sklearn = modelfoundry.plugins.sklearn.plugin:plugin

ml_modelfoundry-0.8.2.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

modelfoundry/__init__.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2026 Pointmatic
+# SPDX-License-Identifier: Apache-2.0
+"""ModelFoundry — compile a YAML recipe into a reproducible trained-model instance.
+
+Public API re-exports are added as the package is built out (see docs/specs/stories.md).
+The pre-production scaffold exposes only the version string.
+"""
+
+from modelfoundry._version import __version__
+from modelfoundry.core.errors import (
+    CacheError,
+    DataBindingError,
+    ExpectationError,
+    InspectionError,
+    InstanceError,
+    MaterializeError,
+    ModelArtifactExistsError,
+    ModelfoundryError,
+    OptimizationError,
+    PluginError,
+    RecipeError,
+    ValidationError,
+)
+from modelfoundry.core.instance import ModelInstance
+from modelfoundry.core.modelfoundry import ModelFoundry, materialize
+
+__all__ = [
+    "CacheError",
+    "DataBindingError",
+    "ExpectationError",
+    "InspectionError",
+    "InstanceError",
+    "MaterializeError",
+    "ModelArtifactExistsError",
+    "ModelFoundry",
+    "ModelInstance",
+    "ModelfoundryError",
+    "OptimizationError",
+    "PluginError",
+    "RecipeError",
+    "ValidationError",
+    "__version__",
+    "materialize",
+]

modelfoundry/__main__.py

@@ -0,0 +1,10 @@
+# Copyright (c) 2026 Pointmatic
+# SPDX-License-Identifier: Apache-2.0
+"""`python -m modelfoundry` entry point — prints the version and exits 0."""
+
+import sys
+
+from modelfoundry.cli.app import main
+
+if __name__ == "__main__":
+    sys.exit(main())

modelfoundry/_version.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2026 Pointmatic
+# SPDX-License-Identifier: Apache-2.0
+"""Single source of truth for the package version."""
+
+__version__ = "0.8.2"

modelfoundry/cache/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Pointmatic
+# SPDX-License-Identifier: Apache-2.0
+"""Cache identity, on-disk layout, atomic promotion, and cleaning.
+
+Public re-exports are added as the package is built out (see docs/specs/stories.md).
+"""