Skip to content
Docs
Working With Models
Hugging Face models

Hugging Face Models

Tensormorph can open a checkpoint hosted on the Hugging Face Hub directly, without a separate manual download step. This page covers how a Hub model is addressed and cached, not how to author or publish one - Tensormorph is a consumer of Hub-hosted checkpoints, not a Hub client.

Addressing a model by revision

A Hub repository is a Git-backed store where every commit, branch, and tag is a valid revision. Tensormorph accepts any of the three when you open a Hub model:

  • org/model - resolves to the main branch.
  • org/model@a1b2c3d - pins to an exact commit hash.
  • org/model@v2 - resolves a tag or branch name.

Pinning by commit hash is the only one of the three that's guaranteed stable: a branch or tag can move to a different commit later, while a hash always refers to the same content. When Tensormorph records what a comparison or a workspace was built from, it stores the resolved hash, not the branch or tag name you typed - the same principle behind the commit-pin mechanism described in Merge Conflicts.

Local cache layout

Once a Hub model has been opened, Tensormorph keeps a local, content-addressed cache so re-opening the same revision - or a different revision that shares most of its tensors - doesn't re-download unchanged bytes. The layout mirrors the Hub's own local-cache convention:

<cache>/
├── models--<org>--<repo>/
│   ├── blobs/       # file contents, stored once per content hash
│   ├── refs/        # branch/tag name → resolved commit hash
│   └── snapshots/   # one folder per commit hash, symlinked into blobs/
  • blobs/ holds every distinct file's bytes exactly once, keyed by content hash - if two revisions share a tensor file unchanged, it's stored once and referenced twice.
  • refs/ maps a mutable name (main, v2) to the commit hash it currently resolves to, so Tensormorph can tell you a branch pointer moved without re-fetching anything.
  • snapshots/ gives each commit hash its own folder of symlinks back into blobs/, so "the full set of files at commit X" is always a cheap directory listing, never a copy.
💡

This is the same content-addressed, symlink-snapshot pattern used for Lob's own local object cache - Tensormorph didn't invent a second scheme for Hub-sourced models.

Instant tree population

Most Hub-hosted checkpoints ship as safetensors, so opening one gets the same near-instant tree population described in Safetensors: Tensormorph range-fetches each shard's header before downloading any weight bytes, and the Outliner populates from those headers alone.

Related resources

  • Sharded Checkpoints - most Hub models above a few gigabytes ship as multiple safetensors shards with an index file.
  • Model Cards - the structured metadata attached to a Hub repository, beyond what's in the checkpoint file itself.
Sharded checkpointsONNX