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