MODEL_CARD.md

# Model card standard

Every `software-mansion/react-native-executorch-*` repository carries a
`README.md` in this shape. Five sections are **generated** from the repository
tree and its `config.json` files, so they cannot drift from what is published.
Anything a model needs beyond them is a **free section**, written by hand and
kept as-is.

Before this standard the estate had 12 distinct heading sequences, four
heading-level conventions, and five different ExecuTorch versions claimed in
prose while 28 of 54 cards claimed none.

## Front matter

Hugging Face card metadata. Required on every repository:

| key | value |
| --- | --- |
| `license` | An SPDX-style Hub identifier for the **upstream** license, not ours. Use `other` plus `license_name` and `license_link` when the upstream license has no Hub identifier. |
| `pipeline_tag` | The Hub task this model serves, so it appears in task search. |
| `library_name` | Always `executorch`. |

Optional: `base_model`, `language`, `tags`. Keep the same identifier here and in
the `license` field of every `config.json` in the repository; they are checked
against each other.

## Generated sections

### 1. Title and introduction

The `# ` title is the repository slug with the `react-native-executorch-`
prefix dropped. One paragraph naming the library, then the upstream model on
its own line:

```markdown
# <slug>

This repository hosts the **<slug>** models exported for the
[React Native ExecuTorch](https://www.npmjs.com/package/react-native-executorch)
library as ExecuTorch `.pte` programs, ready to run on device.

Upstream model: [<name>](<url>)
```

Omit the upstream line when there is no single upstream to point at, rather
than guessing a URL.

### 2. Variants

One row per published `.pte`, read from the `variants` array of every
`config.json`.

```markdown
## Variants

| Path | Backend | Precision |
| --- | --- | --- |
| `xnnpack/model_xnnpack_fp32.pte` | xnnpack | fp32 |
| `xnnpack/model_xnnpack_int8.pte` | xnnpack | int8 |
| `coreml/model_coreml_fp16.pte` | coreml | fp16 |
```

A variant that ships several `.pte` files declares them as a `components` map
of role to filename, and contributes one row per component. Those repositories
gain a `Component` column naming the role; repositories without components do
not carry the column, so the common case stays three columns wide.

```markdown
| Path | Component | Backend | Precision |
| --- | --- | --- | --- |
| `coreml/clip_image_coreml_fp16.pte` | image | coreml | fp16 |
| `coreml/clip_text_coreml_fp16.pte` | text | coreml | fp16 |
```

The precision token is the whole story: `precisions.json` is authoritative for
which tokens are quantized, so the card does not repeat that partition. Nor
does it name a default, because the library resolves one per platform and a
second answer here would only compete with it.

### 3. Unshipped backends

Omitted unless the repository has one. A backend directory carrying a
`NOTES.md` and no `.pte` was exported and not published; the note records why,
and the card links it rather than repeating it.

```markdown
## Unshipped backends

A backend directory carrying a `NOTES.md` and no `.pte` was exported and
not published. Its note records why.

- `coreml` ([why](https://huggingface.co/software-mansion/<repo>/blob/main/coreml/NOTES.md))
```

### 4. Repository structure

Every tracked file except `README.md` and dotfiles, with its size, so a reader
can see the download cost before fetching.

```markdown
## Repository structure

​```
coreml/config.json                 1 kB
coreml/model_coreml_fp16.pte       8.3 MB
xnnpack/config.json                3 kB
xnnpack/model_xnnpack_fp32.pte     31.1 MB
​```
```

Sizes render as `B`, `kB`, `MB` or `GB`.

### 5. Compatibility

Fixed text, parameterised only by the ExecuTorch runtime version. It states
the runtime the files are **published for**, and deliberately does not claim
the version each file was exported with: that is unrecorded for older exports,
and the five conflicting numbers the cards used to carry were all stale.

No react-native-executorch version appears here. Naming one would force an
edit to every card on each library release even when neither the runtime nor
the files changed, which is exactly the drift this standard exists to stop.

```markdown
## Compatibility

These files are published for the **ExecuTorch v1.4.1** runtime. ExecuTorch
gives no forward compatibility guarantee, so an older runtime may fail to load
them.

To use them in React Native ExecuTorch, pass the model constant shipped in the
library's model registry to the corresponding task pipeline. See the
[documentation](https://docs.swmansion.com/react-native-executorch/docs/fundamentals/downloading-models).

To load these files in your own ExecuTorch runtime, read the
[compatibility note](https://github.com/pytorch/executorch/blob/main/runtime/COMPATIBILITY.md)
first.
```

Bump the version here only when the runtime the files are published for
changes.

## Free sections

Everything a model needs that neither the skeleton nor the repository's JSON
can express, appended after Compatibility at `##` level and left exactly as
written.

- `Export notes`, `CoreML notes (iOS)`: export decisions and per-backend
  caveats. These live nowhere else, so the card is their home.
- `Model details`, `Languages`, `Classes (N)`: **only** when the model is
  niche or the upstream link does not already cover it. For a model with a
  well-documented upstream this duplicates a page we do not control and
  cannot keep in sync.

Do not write a free section for:

- **The I/O contract.** The `config.json` files declare it, so restating it
  here breaks rule 5. (Two shapes are in play today, the schema and the older
  one reporting only upper bounds for dims, which is a reason to converge
  them, not to re-document I/O by hand in 54 places.)
- **Latency or benchmark numbers.** They belong on the docs page, where they
  are versioned and compared across models. Nobody looks in a model card for
  them, and a stale number here is worse than none.
- **Required preprocessing.** `models.ts` declares it, and these files are
  published to be consumed through the library, so its readers already have
  the authoritative copy. A second copy here is one more thing to keep in
  sync for an audience that does not need it.

Write a free section only when the answer to "how do I call this correctly?"
follows from neither the variant table nor the JSON.

## Rules

1. Heading levels are fixed: one `#` title, everything else `##`.
2. Never hand-edit a generated section. Fix the tree or the `config.json` and
   re-render, so the card and the artifacts cannot disagree.
3. One ExecuTorch version appears in a card, in Compatibility.
4. Free sections carry the model-specific truth. Boilerplate belongs in the
   generated skeleton, where it is written once.
5. Nothing in a card restates a fact the artifacts already hold. Derive it
   instead, so the two cannot disagree.