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_SMOKE_USER='...' HIPPIUS_SMOKE_PASS='...' HIPPIUS_TEST_CONSOLE_TOKEN='...' 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. The hourly job pushes to veggies-test/e2e-client, not the e2e repo test/e2e-client: the console API deletes only inside the token's own Harbor project (veggies-test).

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

The e2e workflow and the hourly smoke workflow use different registry robots. 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` (project test)
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_SMOKE_USER           # push robot in Harbor project veggies-test
gh secret set HIPPIUS_SMOKE_PASS
gh secret set HIPPIUS_SMOKE_TOKEN          # only if using the Bearer path for smoke
gh secret set HIPPIUS_TEST_CONSOLE_TOKEN   # console API token for the veggies-test account
gh secret set MATTERMOST_WEBHOOK_URL       # same webhook hippius-s3 posts its smoke alerts to

Scope the e2e credentials to test/e2e-client only, and the smoke credentials to veggies-test/e2e-client only — never to a production namespace. That keeps the blast radius of any leak limited to test data. The two robots are different Harbor projects: the console API will not delete a tag outside the token's project. 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
# Logged into project test: HIPPIUS_TEST_USER / HIPPIUS_TEST_PASS.
# Logged into project veggies-test: HIPPIUS_SMOKE_USER / HIPPIUS_SMOKE_PASS.

The e2e namespace defaults to test/e2e-client (overridable via HIPPIUS_TEST_REPO). The hourly smoke namespace defaults to veggies-test/e2e-client (overridable via HIPPIUS_SMOKE_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.