ossllms (Python SDK + CLI)

Pull open-weight AI models from the ossllms preservation network. An HF-cache-compatible download shim that mirrors the common huggingface_hub download/cache paths for public model pulls — resolving from the torrent layer, verifying integrity + publisher signature, and landing files in the HF-compatible cache. Unsupported HF kwargs (token, repo_type, local_files_only) and auth/gated repos are out of scope. Full design: ../docs/SDK.md and ../docs/INTEROP-HF.md.

Status: V1 proof passed for the launch corpus; current release ossllms==0.2.3 (the V0 0.1.0 and V1 0.2.1 proofs are historical).

Install

python -m pip install ossllms

CLI (simplest UI)

ossllms search minilm                 # find a useful default-catalog model
ossllms pull hf/sentence-transformers/all-MiniLM-L6-v2@0.0.1+1110a243fdf4
ossllms pull hf/sentence-transformers/all-MiniLM-L6-v2@0.0.1+1110a243fdf4 --seed
ossllms contribute                    # start/attach to the managed seed worker
ossllms pull sha256:<64-hex>          # resolve by catalog hash index
ossllms publish ./model               # TTY: prompt/infer, sign, optionally seed
ossllms publish ./model --seed --yes-public # automation: publish and seed local bytes
ossllms contribute --dry-run          # preview seed/publish candidates and caps
ossllms contribute --publish          # TTY: choose publish/seed rows, consent, then seed
ossllms contribute --publish --yes-public # automation: publish selected cache candidates, then seed
ossllms contribute                    # attach to/start managed seed handoff worker
ossllms contribute --status           # show worker metrics
ossllms contribute --stop             # stop worker
ossllms ls                            # what's cached
ossllms verify hf/sentence-transformers/all-MiniLM-L6-v2@0.0.1+1110a243fdf4

If no catalog is configured, the packaged signed default catalog is used. Set OSSLLMS_CATALOG=https://catalog.ossllms.com or pass --catalog ... for a custom directory or http(s) catalog.

Python

from ossllms import snapshot_download, hf_hub_download, pull

path = snapshot_download("hf/sentence-transformers/all-MiniLM-L6-v2@0.0.1+1110a243fdf4")
cfg  = hf_hub_download(
    "hf/sentence-transformers/all-MiniLM-L6-v2",
    "config.json",
    revision="0.0.1+1110a243fdf4",
)

res = pull("hf/sentence-transformers/all-MiniLM-L6-v2@0.0.1+1110a243fdf4")
print(res.verdict.label, res.verdict.signer)             # "Verified" / signer

import ossllms.compat   # opt-in: route huggingface_hub downloads through ossllms

What's built

• pull: resolve signed manifest → download via HTTP web seeds (works today; file:// supported) → verify every file's SHA-256 (the release's identity), the v2 root when a torrent binding is present, and the minisign/Ed25519 signature → place in HF cache. Integrity always enforced; origin shown as Verified/Unverified (--require-signature to enforce). pull --seed starts the managed contribution worker for the pulled snapshot when the catalog has matching torrent metadata.
• Store-qualified refs, sha256: refs, and catalog-paired magnet: refs.
• publish: build and sign a public redistribution bundle from a local model directory; optionally update a static V0 catalog/hash index with --catalog-dir, and start the managed seed worker directly from the local directory with --seed.
• contribute --dry-run: scans local HF cache roots, matches catalog hashes, shows seed/publish candidates, public-publish warnings, and upload caps.
• contribute: attaches to an active managed worker or starts one for complete in-network seed matches, persisting upload caps, zero-download seed metrics, and a worker plan. In a terminal it renders the scan plan, lets the user select publish/seed rows, shows caps, and requires public redistribution consent before publish writes. When release.torrent metadata is available beside release.json, the worker starts libtorrent seed mode from a hardlink-only view of the HF cache.
• Worker-state, HF metadata, provenance, and seed-mode handoff primitives.
• huggingface_hub-compatible snapshot_download / hf_hub_download + compat shim.
• Manifest schema validation, trust store (pinned keys), selective --include.
• libtorrent swarm engine: download scaffold plus live contribute seed adapter included in the default install. Local two-peer E2E gates prove fixture, direct-publish, and contribute-publish no-web-seed swarms over libtorrent.
• Bundled default MiniLM metadata includes release.torrent, so the post-pull default contribution path can start live seed mode on the supported CPython release plane.

Develop / test

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest          # or: PYTHONPATH=. .venv/bin/pytest tests

Verified = verified origin + integrity (+ a matches HF badge). It does not mean the weights are safe to run.