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:

# <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.

## 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.

| 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.

## 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.

## 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.

## 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

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