Skip to content

[RNE Rewrite] Update huggingface model cards #1374

Closed

Description

@msluszniak

We need to update HF models cards as some seems be outdated, they are not in the same style. This should unify them all.

Activity

  1. added this to the v0.10.0 milestone on Aug 21, 2026
  2. added theissue type on Aug 21, 2026
  3. changed the title [-]Update huggingface model cards[/-] [+][RNE Rewrite] Update huggingface model cards[/+] on Aug 21, 2026
  4. self-assigned this
    on Aug 24, 2026
  5. msluszniak commented on Aug 27, 2026

    @msluszniak
    MemberAuthor

    @barhanc I think we should establish some template for that and add this maybe to spec repository on HF, wdyt?

  6. removed their assignment
    on Sep 2, 2026
  7. self-assigned this
    on Sep 3, 2026
  8. msluszniak commented on Sep 3, 2026

    @msluszniak
    MemberAuthor

    @barhanc thanks, updated the template with your points:

    • Compatibility no longer names a react-native-executorch version, only the ExecuTorch runtime, so a library release does not force an edit to every card.
    • I/O contract, latency/benchmarks and required preprocessing moved to an explicit "do not write" list. The two config shapes are called out as a reason to converge them rather than hand-write I/O in 54 places.
    • Model details, languages and classes are now gated on the model being niche or the upstream link not covering it.
    • Reworded the usage sentence to yours and pointed it at the loading-models docs page.

    Model card standard

    Every software-mansion/react-native-executorch-* repository carries a
    README.md in this shape. Four 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. Multi-component variants contribute one row per component.

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

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

    4. 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/loading-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.
  9. barhanc commented on Sep 3, 2026

    @barhanc
    Member

    In general looks good.

    • In the compatibility template I'm not sure about this fragment 'that react-native-executorch 0.10 bundles' - it will require updating after every version release even if neither the ExecuTorch version changed nor the model was re-exported.
    • Specifying the i/o contract in free section goes against the 5-th rule as there are the .jsons (although we currently have two different ones -- the schema.json and the older one that only reports upper bounds for dims).
    • Model details I would put only if the model is niche or the upstream link doesn't already cover it. Same goes for stuff like languages, classes, etc. -- I feel like for most models it's easily checkable so no need to duplicate that information. About adding the required preprocessing info I'm not sure -- it's already declared in the models.ts but maybe adding it again here would have some benefits?
    • I'm not sure about the things like model latency, benchmarks there. I'm not sure anyone would actually think to look into model card for these, rather than e.g. docs page. Export notes on the other hand are a very good idea to place them in one place.
    • Maybe rephrase this
      Using them through [React Native ExecuTorch](https://www.npmjs.com/package/react-native-executorch)
      needs nothing further: the model constants it ships resolve to files matching
      the runtime it bundles. See the
      [documentation](https://docs.swmansion.com/react-native-executorch/) for the API.
      
      to
      To use them in React Native ExecuTorch simply pass the model constant shipped in the library's model registry to the corresponding task pipeline. See [link to model registry api reference or just docs].
      
      so it doesn't have the LLM-isms.
  10. msluszniak commented on Sep 7, 2026

    @msluszniak
    MemberAuthor

    @barhanc, if you are ok with updated template, I'll start with changes on HF.

  11. barhanc commented on Sep 7, 2026

    @barhanc
    Member

    Looks good.

  12. msluszniak commented on Sep 7, 2026

    @msluszniak
    MemberAuthor

    Completed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

huggingfaceIssues and tasks related to HuggingFace repository

Type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions