BUNDLE_README.md

# CelsiusToKelvin Edge Bundle

MatrixAI model exported for edge/production inference.
Actions remain `simulate_only`. This bundle only provides predictions.

## Quick start

This model is self-usable: feed **raw, human-readable values** and get back a single numeric value.
Normalization and category encoding are handled for you by `predict.py`.

```bash
python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python predict.py --input example_input.json
```

That should reproduce `expected_output.json`. From your own code:

```python
from predict import MatrixAIModel

model = MatrixAIModel()                 # loads inference_spec.json next to predict.py
print(model.predict({"celsius": 50.0}))
```

## Files

| File | Description |
|------|-------------|
| `model.mxai` | MatrixAI model definition (source of truth) |
| `model.mxtrain` | Training contract: dataset, split, loss, optimizer, epochs |
| `params.best.json` | Trained parameter weights |
| `model.onnx` | ONNX model, opset 17 |
| `model_manifest.json` | Model metadata, hashes and backend contract |
| `export_manifest.json` | Export metadata, tolerance and equivalence check |
| `data_recipe.txt` | The recipe the training data was generated from |
| `reproduce.json` | Whether this model can be rebuilt, and the digest of each artifact that travels |
| `inference_spec.json` | How a raw record maps to the model input (the "tokenizer") |
| `predict.py` | Standalone wrapper: raw values in, labelled prediction out |
| `requirements.txt` | Minimal deps to run predict.py (numpy + onnxruntime) |
| `example_input.json` | A ready-to-run raw example |
| `expected_output.json` | The output predict.py should produce for that example |
| `space/` | A Hugging Face Space template — yours to publish, or to ignore |
| `README.md` | This file |

This package is **reproducible**: `reproduce.json` carries the recipe, the training contract, the expected dataset sha256 and the exact environment, all of it taken from the capture the core recorded while training this model — and every artifact here matches it. It proves internal consistency, not authorship.

## Model info

- Project: `CelsiusToKelvin`
- Model hash: `mxai_fdbe5973e98a1123`
- Parameter set: `v1_best`
- Input: `Reading` shape `[-1, 1]` (float32)
- Output: `prediction` shape `[-1]`

Equivalence check: PASS (max_abs_diff=3.57e-08, atol=1e-05, n=20)

## Advanced: raw onnxruntime access

For most uses prefer `predict.py` above (it handles normalization and labels).
The raw ONNX graph expects an already-normalized float32 vector:

```python
import onnxruntime as ort
import numpy as np

sess = ort.InferenceSession("model.onnx")
x = np.array([[...]], dtype=np.float32)  # shape [batch, 1]
result = sess.run(None, {"Reading": x})[0]  # [-1]
```

## Reproducing this

Everything needed to rebuild this model's data and check it travels inside the package:

| What | File | sha256 |
|---|---|---|
| model | `model.mxai` | `a66357a7adab3ce7…` |
| training contract | `model.mxtrain` | `b7622635f83c8626…` |
| data recipe | `data_recipe.txt` | `7f332dbb7aa59ebf…` |

- **dataset**: 300 rows, sha256 `5827acf2b2b6058d…`
- **generation seed**: `20260825`
- **generation mode**: `coherent`
- **trained with**: environment_sha256 f73756abfe0d07dffabba936f5e66218dd56e5bf3ebc8ee0c507ac69bb3f2f15, matrixai_version 1.6.0, packages {'numpy': '2.4.4', 'onnx': '1.21.0', 'onnxruntime': '1.26.0', 'torch': '2.11.0+cpu'}, platform {'system': 'Linux', 'release': '6.8.0-137-generic', 'machine': 'x86_64', 'platform': 'Linux-6.8.0-137-generic-x86_64-with-glibc2.39'}, python {'version': '3.12.3', 'implementation': 'CPython', 'sys_version': '3.12.3 (main, Jun 19 2026, 12:46:00) [GCC 13.3.0]'}

```bash
matrixai verify .              # integrity + rebuild the dataset
matrixai verify . --retrain    # …and train again (slow)
matrixai verify . --json       # same report, machine readable
```

**What you should see:** `manifest PASS` and `R1 PASS`. With `--retrain`, also `training PASS`. `R3` reports `INCOMPARABLE` unless the package publishes metrics with their tolerance — that is a missing datum, not a failure.

Exit codes: `0` nothing failed · `2` something does not match · `3` it could not be checked.

## Verifying integrity

```python
import json
with open("model_manifest.json") as f:
    manifest = json.load(f)
assert manifest["model_hash"] == "mxai_fdbe5973e98a1123"
assert manifest["parameter_schema_hash"] == "params_e0a02353b5d9884e"
```