hippius_hub

Drop-in replacement for huggingface_hub backed by the Hippius registry (registry.hippius.com by default). Same Python API as the official client — from hippius_hub import hf_hub_download works where from huggingface_hub import hf_hub_download worked — with byte movement done by a Rust extension.

The CLI also wraps the Hippius console API: register a namespace, manage docker credentials, browse repositories, and search the AI model index without leaving the terminal.

AI agents / coding assistants: a self-contained reference (install, auth, CLI surface, Python API, workflows, what raises NotImplementedError) lives at llms.txt — point your agent at it instead of this README.

Quickstart

# 1. Install
pip install hippius_hub

# 2. Get your API token at https://console.hippius.com/dashboard/settings
hippius-hub login --hippius-token <paste-token-here>

# 3. Provision a namespace + docker login (one shot)
hippius-hub registry provision my-models --docker-login

# 4. You're set — push, pull, search.
hippius-hub upload my-models/qwen-7b ./checkpoints/v1
hippius-hub download my-models/qwen-7b model.safetensors
hippius-hub models list --mine

Install

pip install hippius_hub

hippius-hub --version   # confirm the install
hippius-hub --help      # discover commands

Or from source. hippius_hub ships a Rust extension (hippius_core) — published wheels include a pre-built binary for your platform, but pip install git+… or maturin develop will compile it locally and needs a working Rust toolchain.

Prerequisite — install Rust via rustup (not Homebrew). rustup ships the correct stdlib for your host triple; Homebrew's rust formula installs to the prefix it was built for, so on Apple Silicon an Intel-prefix (/usr/local) Homebrew rust will fail to build for aarch64-apple-darwin with error[E0463]: can't find crate for 'core'.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustc --version   # should print your host triple, e.g. aarch64-apple-darwin

Then either:

# A) Install the latest main directly
pip install "git+https://github.com/thenervelab/hippius-hub.git@main"

# B) Editable dev install
git clone https://github.com/thenervelab/hippius-hub
cd hippius-hub
python -m venv .venv && source .venv/bin/activate
pip install maturin
maturin develop --release

Authenticate

There are two kinds of credentials, depending on what you're doing:

In Python:

from hippius_hub import login
login(token="hf_xxx")                  # HF-shape: positional token (registry creds)
login(username="me", password="pwd")   # Basic auth (registry creds)

In practice the API token is all you save by hand. hippius-hub registry provision <namespace> mints the docker credentials and writes them into ~/.cache/hippius/hub/token for you, so the next upload/download works without a second hippius-hub login step. Pass --docker-login to also run docker login so docker push/pull work; either way, hippius-hub's own auth is persisted.

The registry secret is printed once on first provision. If you lose it, rotate with hippius-hub registry rotate-token (also re-writes the local cache).

Onboard from the terminal (no UI required)

# 1. Save your API token (grab it at https://console.hippius.com/dashboard/settings)
hippius-hub login --hippius-token <token>

# 2. See what plans exist and what your namespace name should look like
hippius-hub registry plans
hippius-hub registry check my-models

# 3. Create your namespace + optionally run `docker login` in one shot
hippius-hub registry provision my-models --docker-login

# 4. Push an image
docker tag my-image registry.hippius.com/my-models/qwen-7b:v1
docker push registry.hippius.com/my-models/qwen-7b:v1

# 5. Inspect what's in your namespace
hippius-hub registry repos
hippius-hub registry artifacts qwen-7b
hippius-hub registry usage
hippius-hub registry me

The full registry sub-tree:

Search the AI model index

Every artifact pushed to the registry is parsed server-side (GGUF, safetensors, ONNX, Diffusers) and indexed by format / architecture / parameter count / quantization. The models sub-tree exposes that index:

hippius-hub models list --format gguf --arch llama --max-params 8000000000
hippius-hub models show my-models/qwen-7b              # all versions of a repo
hippius-hub models show my-models/qwen-7b v1           # one version, with file breakdown
hippius-hub models list --mine                          # restrict to your own
hippius-hub models formats                              # available filter values

Add --json to models list / models show for machine-readable output.

Push a model from the CLI

# Upload an entire model folder (every file under ./qwen-7b/) as `:v1`.
# Folder uploads merge into the existing revision — re-running
# adds/replaces individual files without wiping the rest.
hippius-hub upload myorg/qwen-7b ./qwen-7b --revision v1

# Upload a single file (e.g. add a README to an existing revision)
hippius-hub upload myorg/qwen-7b ./README.md --revision v1

# Tag a folder as the default `:main` revision
hippius-hub upload myorg/qwen-7b ./qwen-7b

Once the push completes, the model index pipeline runs server-side — the model shows up in hippius-hub models list within a few seconds with format/architecture/parameter-count/quantization parsed out of the bytes server-side.

Mirroring a HuggingFace model to your namespace

# 1. Grab the model from HF (uses huggingface_hub's CLI)
pip install -U "huggingface_hub[cli]" hf_transfer
HF_HUB_ENABLE_HF_TRANSFER=1 hf download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen-7b

# 2. Push the whole folder under your namespace as :v1
hippius-hub upload myorg/qwen-7b ./qwen-7b --revision v1

# 3. Confirm it landed + got indexed
hippius-hub registry repos
hippius-hub models show myorg/qwen-7b v1

Pull a model from the CLI

# One file — uses the parallel Rust downloader, picks up auth from
# ~/.cache/hippius/hub/token (set by `provision --docker-login` or `login`).
hippius-hub download myorg/qwen-7b model-00001-of-00003.safetensors

# Specific revision (= tag)
hippius-hub download myorg/qwen-7b config.json --revision v1

# List a repo's revisions, newest first (the newest is marked "(latest)")
hippius-hub revisions myorg/qwen-7b

# Verify the SHA256 of the bytes after download
hippius-hub download myorg/qwen-7b model.safetensors --verify-hash

Omitting --revision downloads main, which always points to the most recently uploaded content (uploads default to main too) — so the default already gives you the latest, just like huggingface_hub. Use hippius-hub revisions <repo> to discover the available revisions and which one is newest.

For pulling every file in a revision, prefer the Python snapshot_download API below — it parallelizes across files and matches the HF cache layout that transformers / diffusers expect.

Optional flags: --revision <tag>, --chunk-size <bytes> (defaults to HIPPIUS_CHUNK_SIZE), --verify-hash (SHA256 after download), --cache-dir <path>.

Quick start: download a model

from hippius_hub import hf_hub_download

# Pull one file
path = hf_hub_download(
    repo_id="myorg/my-model",
    filename="config.json",
    revision="main",
)
print(path)  # ~/.cache/hippius/hub/models--myorg--my-model/snapshots/main/config.json

Cache layout mirrors huggingface_hub exactly, so transformers / diffusers / datasets reading from the same directory Just Works:

from transformers import AutoConfig
import hippius_hub as huggingface_hub  # drop-in swap
config = AutoConfig.from_pretrained("myorg/my-model")

Snapshot download — entire repo with pattern filters

from hippius_hub import snapshot_download

local_dir = snapshot_download(
    repo_id="myorg/my-model",
    revision="v1.2",
    allow_patterns=["*.safetensors", "*.json"],
    ignore_patterns="optimizer*",
    max_workers=8,
)

Upload a file or folder

from hippius_hub import upload_file, upload_folder

# Single file. path_or_fileobj also accepts bytes or BinaryIO.
upload_file(
    path_or_fileobj="./model.safetensors",
    path_in_repo="model.safetensors",
    repo_id="myorg/my-model",
    revision="main",
    commit_message="Initial checkpoint",
)

# Folder, with pattern filters and delete semantics
upload_folder(
    folder_path="./outputs/checkpoint-1000",
    repo_id="myorg/my-model",
    revision="main",
    allow_patterns=["*.safetensors", "*.json"],
    delete_patterns="*.tmp",   # prune any *.tmp from the existing revision
)

upload_file and upload_folder merge into the existing revision — calling them repeatedly adds/replaces individual files without wiping the rest.

Repo CRUD & inspection

from hippius_hub import (
    create_repo, delete_repo,
    repo_info, model_info, list_repo_files, list_repo_refs,
    repo_exists, revision_exists, file_exists,
)

create_repo("myorg/my-model", exist_ok=True)
print(list_repo_files("myorg/my-model", revision="main"))
info = model_info("myorg/my-model", revision="main")
print(info.id, info.sha, [s.rfilename for s in info.siblings])

# Discover available revisions (HF-compatible GitRefs).
refs = list_repo_refs("myorg/my-model")
print([b.name for b in refs.branches])  # ['main']
print([t.name for t in refs.tags])      # ['v1', 'v1.2', ...]

Object-oriented API: HippiusApi

from hippius_hub import HippiusApi

api = HippiusApi(token="hf_xxx")
api.hf_hub_download("myorg/my-model", "config.json")
api.upload_file(
    path_or_fileobj="./README.md",
    path_in_repo="README.md",
    repo_id="myorg/my-model",
)
api.whoami()

HippiusApi subclasses huggingface_hub.HfApi, so isinstance(api, HfApi) is True. Methods we don't implement (Inference Endpoints, Spaces, Webhooks, Collections, Discussions) raise NotImplementedError with a clear "HF-specific" message — they never silently hit huggingface.co.

Errors are HF's typed exceptions

from hippius_hub.errors import RepositoryNotFoundError, RevisionNotFoundError, EntryNotFoundError
from huggingface_hub.errors import RepositoryNotFoundError as HFRepositoryNotFoundError

# They're the same class — re-exported verbatim
assert RepositoryNotFoundError is HFRepositoryNotFoundError

Existing code that catches HF's exceptions keeps working.

Configuration

Programmatic overrides via the endpoint= kwarg on any function let you point at an alternative Hippius registry.

Large-file chunking

Files at or above HIPPIUS_CHUNK_THRESHOLD (256 MiB) are stored as content-defined chunks (FastCDC, ~4 MiB average) packed into ~64 MiB content-addressed packs (HIPPIUS_PACK_SIZE) rather than one object. The layout is a Git-LFS-style pointer: one pointer.v2 record per file — mapping each chunk to its pack, offset, and size — plus the packs it references. A re-uploaded, slightly-changed model references unchanged chunks by range into existing packs and uploads only the packs holding new chunks; downloads fetch each pack once (concurrently) and slice its chunks to their file offsets. Packing into ~64 MiB units cuts per-file upload round-trips versus one-object-per-chunk, and a shared cap (HIPPIUS_MAX_INFLIGHT_PACKS) bounds concurrent pack uploads so folder uploads don't multiply resident memory. Small files and every pre-existing artifact are unchanged (a single object), so nothing already stored is rewritten.

Effective pack-upload concurrency for one file is min(pack count, HIPPIUS_UPLOAD_WORKERS, HIPPIUS_MAX_INFLIGHT_PACKS). The in-flight cap defaults to the worker count, so raising HIPPIUS_MAX_INFLIGHT_PACKS alone changes nothing for a single file — the per-file pool stays at HIPPIUS_UPLOAD_WORKERS (8); raise both to upload more packs at once. Pack count also caps useful workers: a 1 GiB file at the 64 MiB pack size yields 16 packs, so workers beyond 16 sit idle. Each in-flight pack is held in memory (~64 MiB), so peak resident memory scales as in-flight packs × pack size — that memory ceiling is what the cap exists to bound. Past 32 concurrent packs, connections beyond the upload client's 32 idle-per-host pool re-handshake per pack.

Chunked writes are on by default as of 0.6.0 (HIPPIUS_CHUNKED_WRITE). The reader-side guard ships from 0.6.0: a 0.6.0+ client refuses an unknown layout loudly (UnsupportedLayoutError, with an upgrade hint) instead of misreading it, and reads a chunked-v2 artifact correctly. An already-released client (≤ v0.5.1) has no guard, so it silently writes the pointer as the file — every consumer of large files must be on ≥ 0.6.0 before you push them. Set HIPPIUS_CHUNKED_WRITE=0 to fall back to the byte-identical single-object layout while a consumer is still on an older client.

Diagnosing slow transfers

If downloads/uploads are slow for some users but not others, run the built-in probe and share the report:

hippius-hub diagnose <repo_id> <filename>            # phased report + plain-English verdict
hippius-hub diagnose <repo_id> <filename> --verbose  # add per-chunk transport logs
hippius-hub diagnose <repo_id> <filename> --json     # machine-readable

It measures the endpoint handshake (DNS/TCP/TLS), the auth + metadata round-trips, and — the key signal — single-connection vs parallel-connection throughput, then tells you whether a slow link is being mitigated by parallelism or is bottlenecked elsewhere. See docs/diagnosing-speed.md for the full triage runbook.

What's not supported

hippius_hub aims to be drop-in for the download / upload / repo CRUD surface of huggingface_hub. HF-specific features that have no Hippius equivalent raise NotImplementedError:

• Inference Endpoints (create_inference_endpoint, etc.)
• Spaces (request_space_hardware, enable_space_dev_mode, etc.)
• Webhooks
• Collections
• Discussions / PRs
• HF-typed git refs like refs/pr/3 — only tags are supported as revisions. list_repo_refs reports the main revision under branches and every other revision under tags, with each target_commit set to the revision's digest (resolved best-effort).

Also known semantic divergences:

• model_info fills id, sha, lastModified, siblings, private. Fields with no Hippius analog (pipeline_tag, library_name, tags, downloads, likes) are None.
• hf_hub_url returns the revision's metadata URL — usable for inspection but not a direct CDN download URL like HF's.
• Concurrent upload_file calls to the same repo_id:revision are protected by an If-Match header on the commit: the first writer wins, the second sees ConcurrentManifestUpdateError (subclass of HfHubHTTPError) and can retry on a fresh baseline. If the registry omits the digest header the check relies on, the write proceeds without If-Match and a UserWarning is emitted so the unprotected write is grep-able in logs.

Development

# Build the Rust extension into the venv
maturin develop --release

# Install test deps
pip install -e ".[test]"

# Fast tests (no creds, no network)
pytest

# Full e2e against registry.hippius.com (needs HIPPIUS_TEST_USER / HIPPIUS_TEST_PASS)
HIPPIUS_TEST_USER='...' HIPPIUS_TEST_PASS='...' pytest -m e2e -v

# Drop-in parity tests (also needs network to huggingface.co)
HIPPIUS_TEST_USER='...' HIPPIUS_TEST_PASS='...' pytest -m hf_parity -v

The CI workflow (.github/workflows/e2e.yml) runs fast tests on every PR, the Hippius e2e suite on every PR with credentials, and the full HF-parity nightly.

Production smoke tests

.github/workflows/production-smoke-tests.yml runs hourly and answers one question: can somebody who just ran pip install hippius_hub push a 100 MiB model to registry.hippius.com and pull it back byte-for-byte?

It is deliberately not the e2e suite:

Because it installs from PyPI, a release that builds fine but is broken in the wild (missing console script, wrong abi3 wheel tag, a server-side change the shipped client can't handle) is caught within the hour instead of at the next PR.

The suite lives in smoke/, not tests/. tests/ is a Python package whose conftest.py makes pytest prepend the repo root to sys.path, which shadows the installed wheel with the in-tree source — the exact thing this suite must not do. smoke/pytest.ini keeps pytest's rootdir at smoke/ so that conftest is never loaded.

# Run it locally (from inside smoke/, so rootdir resolves correctly)
pip install -r smoke/requirements.txt
cd smoke
HIPPIUS_TEST_USER='...' HIPPIUS_TEST_PASS='...' HIPPIUS_SMOKE_MODEL_MB=5 pytest -v

Each run pushes freshly random bytes at a unique smoke-<timestamp>-<short> revision. That's not incidental: stored objects are content-addressed, so re-uploading identical bytes would dedup server-side and the "upload" would become a no-op HEAD — the suite would go green without pushing a byte. The cost of that is ~2.4 GB/day of new data, which is why test_01 sweeps revisions older than the retention window before anything else runs. Only revisions whose names parse as smoke-<YYYYmmdd-HHMMSS>-… are touched, so e2e revisions sharing the namespace are never at risk.

On failure, scripts/extract_failure_details.py (ported from hippius-s3, so both smoke suites alert identically) turns the pytest JSON report into a Mattermost message naming the test, a plain-language explanation of the error class, and the traceback frame in our own code.

CI secrets

Both live workflows draw on the same secrets. The creds fixture in tests/conftest.py:34-45 accepts either the USER+PASS pair (Basic Auth) OR the TOKEN (Bearer) path; if both env vars are empty the _have_creds() check returns False and every @pytest.mark.e2e test skips cleanly. This is deliberate so PRs from forks — which never receive secrets under the pull_request trigger by GitHub's default — see the offline suite pass and the live suite skip, rather than a confusing fail.

The smoke suite behaves the opposite way on purpose: missing credentials are a hard failure, not a skip. It only ever runs on a cron with secrets available, and a smoke suite that silently skips is indistinguishable from a green one — precisely the failure mode the job exists to prevent.

Set them in repo settings under Settings → Secrets and variables → Actions → Repository secrets, or via the CLI:

gh secret set HIPPIUS_TEST_USER            # the login printed by `registry keys create`
gh secret set HIPPIUS_TEST_PASS            # interactive prompt; value won't appear in shell history
gh secret set HIPPIUS_TEST_TOKEN           # only if using the Bearer path
gh secret set HIPPIUS_TEST_CONSOLE_TOKEN   # console API token, for the smoke suite's revision sweep
gh secret set MATTERMOST_WEBHOOK_URL       # same webhook hippius-s3 posts its smoke alerts to

Scope the test credentials to test/e2e-client only — never to a production namespace. That keeps the blast radius of any leak limited to test data. For finer-grained scope, create a role-scoped key:

# On the workstation where you're already logged in:
hippius-hub registry keys create ci-e2e --role push --expires-days 90
# Use the printed login/secret as HIPPIUS_TEST_USER / HIPPIUS_TEST_PASS.

The test namespace defaults to test/e2e-client (overridable via HIPPIUS_TEST_REPO).

GitHub Actions auto-masks secret values in job logs (they appear as ***), but a malicious test that explicitly print()s a credential could still leak it via the streamed log. Review test changes accordingly.