Metadata-Version: 2.4
Name: ossllms
Version: 0.1.0
Summary: Pull open-weight AI models from the ossllms torrent network. A drop-in for huggingface_hub.
Project-URL: Homepage, https://ossllms.com
Project-URL: Source, https://github.com/gittb/ossllms
Author: ossllms contributors
License-Expression: Apache-2.0
Keywords: ai,bittorrent,huggingface,llm,p2p,preservation
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: jsonschema>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: live-e2e
Requires-Dist: huggingface-hub>=0.23; extra == 'live-e2e'
Provides-Extra: schema
Requires-Dist: jsonschema>=4; extra == 'schema'
Provides-Extra: torrent
Requires-Dist: libtorrent>=2.0; extra == 'torrent'
Description-Content-Type: text/markdown

# ossllms (Python SDK + CLI)

Pull open-weight AI models from the [ossllms](https://ossllms.com) preservation
network. A drop-in for `huggingface_hub` that resolves from the torrent layer,
verifies integrity + publisher signature, and lands files in the HF-compatible
cache. Full design: [`../docs/SDK.md`](../docs/SDK.md) and
[`../docs/INTEROP-HF.md`](../docs/INTEROP-HF.md).

## Install

```bash
pip install 'ossllms[torrent]' # V0 path: HTTP web-seed + libtorrent swarm/seed
```

## CLI (simplest UI)

```bash
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

```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 (v0.1)

- `pull`: resolve signed manifest → download via **HTTP web seeds** (works today;
  `file://` supported) → verify **every file's SHA-256**, **v2 root**, and
  **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 `ossllms[torrent]` is installed and
  `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
  behind the optional torrent extra. 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 when `ossllms[torrent]` is
  installed.

## Develop / test

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