llmt-cli 0.2.0__tar.gz

llmt_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLM Torrents
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llmt_cli-0.2.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: llmt-cli
+Version: 0.2.0
+Summary: Find, download (over BitTorrent + webseeds), and SHA-256-verify LLM models from the LLM Torrents catalog.
+Author: LLM Torrents
+License: MIT
+Project-URL: Homepage, https://llmtorrents.com
+Project-URL: Source, https://llmtorrents.com
+Keywords: llm,torrent,bittorrent,webseed,sha256,ed25519,models,aria2
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: PyNaCl>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: requests-mock>=1.9; extra == "dev"
+Dynamic: license-file
+
+# llmt — LLM Torrents command-line client
+
+`llmt` finds LLM models in the [LLM Torrents](https://llmtorrents.com) catalog,
+downloads them over **BitTorrent with HTTP webseeds**, and — the point of the
+whole thing — **verifies what you got**: it fetches the catalog's
+**Ed25519-signed manifest** for the torrent, checks the signature against a
+public key **pinned inside this package** (not fetched from the network), and
+then verifies every downloaded file's SHA-256 against that verified manifest.
+If a byte is wrong — or the manifest cannot be authenticated — `llmt` tells
+you and exits non-zero.
+
+## Install
+
+```bash
+pip install llmt-cli      # from PyPI (once published; installs the `llmt` command)
+# or, from a checkout:
+pip install -e .
+```
+
+Requires Python ≥ 3.9 and [`aria2c`](https://aria2.github.io/) on your `PATH`
+for downloading/seeding (`apt install aria2`, `brew install aria2`, …). If
+`aria2c` is missing, `llmt` prints a clear message instead of crashing.
+
+## Security & supply chain
+
+`llmt` is high-trust software (it hashes your disk and drives a torrent
+client), so it is built to be audited, not trusted:
+
+- Catalog manifests are **Ed25519-signed**; `pull`/`verify`/`seed` verify the
+  signature against the public key **pinned in the package**
+  (`llmt/data/manifest-pubkey.json`) — the trust root ships with the code and
+  is never fetched from the network at runtime. A manifest that cannot be
+  authenticated (unreachable, malformed, bad signature, wrong/rotated key, or
+  disagreeing with the catalog) is **never reported as verified**: distinct
+  error, exit `15`. Key rotation ships as a new `llmt` release.
+- `llmt permissions` prints exactly what the tool reads, writes, and sends
+  (no telemetry, **no self-update** — enforced by unit test). Prose version:
+  [docs/PERMISSIONS.md](docs/PERMISSIONS.md).
+- Dependencies are pinned: `pip install llmt-cli -c constraints.txt`, or
+  fully hash-verified in two steps (the lock file covers the dependency
+  closure only — `llmt` itself is not in it, so install it separately):
+  `pip install --require-hashes -r requirements.lock && pip install --no-deps .`
+- Releases ship a `SHA256SUMS` file (checksums published on
+  llmtorrents.com); build + signing process: [docs/RELEASING.md](docs/RELEASING.md).
+- Vulnerability reports: [SECURITY.md](SECURITY.md).
+- Docker image (pinned base, non-root) and homelab recipes:
+  [docs/recipes/](docs/recipes/).
+
+## Usage
+
+```bash
+llmt search "llama"                       # readable table of matches
+llmt search "qwen" --fit --rig vram_gb=24 # fit verdict for your rig
+llmt search "phi" --json                  # machine-readable
+
+llmt pull microsoft-phi-4-mini            # best quant -> download -> verify
+llmt pull microsoft-phi-4-mini:Q4_K_M     # a specific quant
+llmt pull acme-tiny-1b --dry-run          # show the exact aria2c command
+
+llmt verify ./acme-tiny-1b-Q4_K_M acme-tiny-1b:Q4_K_M   # re-check, no download
+llmt seed acme-tiny-1b:Q4_K_M ./acme-tiny-1b-Q4_K_M     # help the swarm
+```
+
+Global flags on every command: `--json`, `--api-base`, `--api-key`,
+`--timeout`. Configure via env: `LLMT_API_BASE`, `LLMT_API_KEY`
+(the complete list of every env var `llmt` reads is in
+[docs/PERMISSIONS.md](docs/PERMISSIONS.md) and `llmt permissions`).
+An API key is optional and only **raises your rate limits** — all reads are
+public.
+
+## The trust story (signed manifest + SHA-256)
+
+A torrent's own piece hashes only prove the bytes match *that* `.torrent`.
+They don't prove the `.torrent` describes the model the catalog vouched for
+— and TLS alone only proves who you *talked to*, not that the file list is
+the one the catalog *signed*. `llmt` closes both gaps:
+
+1. **The Ed25519-signed manifest is the source of truth.** For a non-gated
+   model, `llmt` fetches the torrent's manifest
+   (`GET /api/manifests/{info_hash}`) and **verifies its detached Ed25519
+   signature** against the public key pinned inside this package
+   (`llmt/data/manifest-pubkey.json`, per the open
+   [manifest spec](https://llmtorrents.com/schema/manifest-v0.1.0.json)).
+   It also checks that the signed document actually names the torrent being
+   verified, and that the API's `download.files[]` block agrees with the
+   signed manifest.
+2. **After the download**, `llmt` streams each file through SHA-256 (64 KiB
+   chunks, no whole-file buffering) and compares byte-for-byte against the
+   **verified manifest's** hash. This is a real, independent check — not
+   aria2c's piece check.
+3. **Any mismatch, missing file, or wrong size fails the run** and `llmt`
+   exits non-zero (`3`). A tampered or truncated file cannot pass silently.
+   A file for which no hash was supplied is flagged `NO-HASH`, never waved
+   through.
+4. **An unauthenticatable manifest fails the run before any hashing** —
+   unreachable endpoint (e.g. offline), malformed document, invalid
+   signature, unknown/rotated signing key, wrong torrent, or a
+   catalog/manifest disagreement each produce a distinct error and exit
+   `15`. `llmt` never silently falls back to trusting unsigned hashes over
+   TLS. (If the key was rotated, upgrading to the newest `llmt` release
+   picks up the new pinned key.)
+5. **`llmt verify`** re-runs exactly this check on already-downloaded files
+   — including the manifest signature check, so it needs the catalog API to
+   be reachable; there is no offline "verified". `llmt seed` refuses to
+   seed a torrent whose manifest cannot be authenticated.
+
+Because a wrong file trips a non-zero exit, `llmt pull` / `llmt verify` drop
+straight into a pipeline: if it exits `0`, every file matched the
+Ed25519-verified manifest.
+
+## License-gated models (why some models won't download)
+
+Some models are distributed under a click-through license. For those, the
+catalog API serves **no download artifacts at all** — no magnet, no hashes, no
+file list. `llmt` detects this and tells you to accept the license on the
+model's page first:
+
+```
+$ llmt pull meta-llama-llama-3-3-70b-instruct
+'meta-llama-llama-3-3-70b-instruct' is license-gated. The catalog API does not
+serve download artifacts for gated models.
+Accept the license here, then retry: https://llmtorrents.com/models/meta-llama-llama-3-3-70b-instruct
+```
+
+`llmt` will never fabricate a magnet or hash to work around a gate.
+
+## How the download works (aria2c + webseeds)
+
+`llmt` delegates the transfer to `aria2c`, passing the catalog's magnet URI
+plus every webseed URL as trailing HTTP URIs, so aria2c uses the project's
+HTTP mirrors as web-seeds alongside the BitTorrent swarm. Roughly:
+
+```
+aria2c --dir <out> --enable-dht=true --bt-enable-lpd=true \
+       --check-integrity=true --max-connection-per-server=8 --seed-time=0 \
+       [--bt-tracker <tracker> ...] \
+       <magnet> <webseed-url-1> <webseed-url-2> ...
+```
+
+Use `llmt pull ... --dry-run` to print the exact command for your model.
+
+### Known webseed quirks (why aria2c may exit non-zero on a good download)
+
+Both HTTP origins serve the model files but **403 the bare base URL**
+(directory listings are disabled by design), and hybrid v1+v2 torrents
+contain BEP-47 `.pad` entries that **404 on the HTTP mirrors** (often seen as
+a "stall" at 98-99% in aria2c's progress summary). Either can make `aria2c`
+exit non-zero (e.g. code 22) even though every payload byte arrived.
+
+`llmt pull` handles this: when aria2c exits non-zero it checks that every
+expected file is present on disk at its expected size. If so, it notes the
+quirk on stderr and proceeds straight to the full SHA-256 verification — the
+hash check against the signed manifest, not aria2c's exit code, is the trust
+signal. If files are missing or the wrong size, the download really did fail
+and `llmt` exits `10` loudly.
+
+`llmt verify <dir> <ref>` accepts either the **outer** download directory
+(the one `pull` created) or the **inner** payload directory the torrent
+unpacked inside it — it detects which you passed. If it can't find the files
+at all, it tells you exactly which directory to pass.
+
+## Seeding your existing models (the layout mapper)
+
+SHA-256 tells you a file *is* the right bytes, but a BitTorrent client won't
+seed those bytes unless they appear at the exact path the torrent expects,
+under the torrent's root folder. Your model lives at
+`/models/qwen3-30b/model.gguf`; the torrent wants
+`qwen3-30b-a3b-q4-k-m/Qwen3-30B-A3B-Q4_K_M.gguf`. The layout mapper plans how to
+present your existing file to the client **without moving or copying it**.
+
+- **Direct-use:** if your file already sits at the expected relative path, the
+  plan is just "add the torrent with this save path" — no links at all.
+- **Link farm (default for mismatched layouts):** the mapper builds a tiny tree
+  under `~/.llmt/seeding-layouts/<torrent-root>/…` whose entries are hard/sym
+  **links** back to your real file. Your model folder stays your model folder;
+  the farm is just a set of pointers the client can follow. Save path is the
+  layouts dir; the client rechecks, sees 100%, and seeds. Model weights are
+  never re-downloaded and nothing is duplicated on disk. One honest caveat for
+  multi-file torrents you hold only partially: small companion files
+  (license/README-class, at most 10 MiB total per torrent) may be fetched by
+  your client, and `llmt scan` prints a notice naming them and where they land
+  first; any larger missing file is marked "do not download" in your client
+  before the torrent can resume, with a warning that it will seed only what
+  you have and show as incomplete.
+
+Hardlinks are preferred whenever the file and the farm are on the same
+filesystem/volume — they need no privileges and every client follows them. A
+symlink is the labelled cross-volume fallback.
+
+| Platform | Same volume | Cross volume |
+| --- | --- | --- |
+| Linux / macOS | hardlink | symlink |
+| Windows | hardlink (same drive, no admin) | symlink — needs **Administrator or Developer Mode** (NTFS junctions redirect directories only, not files) |
+
+The client must **force-recheck** after adding so it verifies the linked bytes
+and reaches 100%. The mapper refuses any path that would escape the layouts dir
+(`..`, absolute/drive-letter/UNC tricks, reserved names, null bytes) and never
+silently replaces an existing link that points somewhere else.
+
+**Dockerized or remote clients (seedbox / unRAID):** a qBittorrent or
+Transmission running in a container only sees its own **mounted volumes**, not
+host paths like `~/.llmt/seeding-layouts`. If the link farm lives on a path the
+client cannot see, its force-recheck reads **0%** and `llmt scan` **fails
+closed** (it never resumes an unverified torrent). Point the farm at a directory
+the client has mounted with `--layout-base`, e.g.
+`llmt scan --layout-base /mnt/user/appdata/qbittorrent/llmt-layouts`. `llmt
+scan` also prints an early advisory when it detects the client's own default
+save path does not exist on the machine llmt is running on (a sign the two are
+on different filesystems), and `llmt doctor` reports a `layout-base-visible`
+check that WARNs in the same situation.
+
+## Opt-in seeding telemetry (off by default)
+
+Telemetry lets the LLM Torrents site **credit you for the artifacts you
+seed**. It is a *separate, explicit, off-by-default, revocable* opt-in — it
+never runs until you turn it on, and it never sends file paths or scan data.
+
+```bash
+llmt telemetry enable            # prints the exact consent statement, then
+                                 # prompts for your token (from the website)
+llmt telemetry enable --yes --token llmta_xx…   # non-interactive (scripts)
+llmt telemetry status            # consent state, token presence, last beat
+llmt telemetry whoami            # who the stored token belongs to (GET /me)
+llmt telemetry beat --qb-url http://localhost:8080   # send one heartbeat
+llmt telemetry beat --loop       # keep beating every 15 min (or --interval N)
+llmt telemetry disable           # stop sending AND delete the stored token
+```
+
+`beat` reads the torrents from your client (`--qb-url`/`--tr-url` or
+`LLMT_QB_URL`/`LLMT_TR_URL`, same flags as `scan`/`doctor`), reports each
+torrent's infohashes (v1 **and** v2 for hybrid torrents), name, state and
+progress plus the SHA-256s of the artifacts you hold, and answers any
+possession challenges the server issues by hashing a server-chosen byte range
+of the local file. Run it from `cron` (the primary mode) or with `--loop`.
+
+**What is sent:** torrent infohashes/names/states/progress, artifact
+SHA-256s, and challenge byte-range hashes — nothing else.
+**What is never sent:** file paths, filenames, scan data, or machine info.
+The token is stored at `~/.llmt/agent-token` (mode `0600`) and is never
+printed after it is saved. View or delete your server-side data on the
+website (Account -> Telemetry). See [docs/PERMISSIONS.md](docs/PERMISSIONS.md)
+and `llmt permissions` for the full statement.
+
+Config keys (in `~/.llmt/config.json`, all under `telemetry`):
+`enabled` (default `false`), `endpoint` (default `https://llmtorrents.com`),
+`interval_minutes` (`15`), `max_torrents_per_heartbeat` (`500`),
+`report_artifacts` (`true`), `token_path`, `challenge_chunk_size`.
+Override the endpoint per-run with `--endpoint` or `LLMT_TELEMETRY_ENDPOINT`.
+
+## Exit codes
+
+| code | meaning |
+|------|---------|
+| 0 | success / all files verified |
+| 2 | generic API error (incl. 403) |
+| 3 | **SHA-256 verification failed** |
+| 4 | not found (404) |
+| 5 | rate limited (429; respects `Retry-After`) |
+| 6 | request timed out |
+| 7 | model is license-gated (D7) |
+| 8 | no gate-passed torrent available |
+| 9 | `aria2c` not installed |
+| 10 | `aria2c` failed and the download is incomplete |
+| 14 | torrent-client add/connection failed |
+| 15 | **manifest unverifiable** (fetch failed/offline, malformed, bad signature, wrong/rotated key, wrong torrent, or catalog/manifest mismatch) — nothing was verified |
+| 20 | telemetry error (generic / disabled) |
+| 21 | telemetry token missing/unknown/revoked (401) |
+| 22 | telemetry token lacks `telemetry:write` scope (403) |
+| 23 | telemetry config error (no token / bad endpoint) |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -m "not live"   # offline unit suite (mocked API)
+pytest -m live         # read-only smoke calls to the real API
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

llmt_cli-0.2.0/README.md

@@ -0,0 +1,281 @@
+# llmt — LLM Torrents command-line client
+
+`llmt` finds LLM models in the [LLM Torrents](https://llmtorrents.com) catalog,
+downloads them over **BitTorrent with HTTP webseeds**, and — the point of the
+whole thing — **verifies what you got**: it fetches the catalog's
+**Ed25519-signed manifest** for the torrent, checks the signature against a
+public key **pinned inside this package** (not fetched from the network), and
+then verifies every downloaded file's SHA-256 against that verified manifest.
+If a byte is wrong — or the manifest cannot be authenticated — `llmt` tells
+you and exits non-zero.
+
+## Install
+
+```bash
+pip install llmt-cli      # from PyPI (once published; installs the `llmt` command)
+# or, from a checkout:
+pip install -e .
+```
+
+Requires Python ≥ 3.9 and [`aria2c`](https://aria2.github.io/) on your `PATH`
+for downloading/seeding (`apt install aria2`, `brew install aria2`, …). If
+`aria2c` is missing, `llmt` prints a clear message instead of crashing.
+
+## Security & supply chain
+
+`llmt` is high-trust software (it hashes your disk and drives a torrent
+client), so it is built to be audited, not trusted:
+
+- Catalog manifests are **Ed25519-signed**; `pull`/`verify`/`seed` verify the
+  signature against the public key **pinned in the package**
+  (`llmt/data/manifest-pubkey.json`) — the trust root ships with the code and
+  is never fetched from the network at runtime. A manifest that cannot be
+  authenticated (unreachable, malformed, bad signature, wrong/rotated key, or
+  disagreeing with the catalog) is **never reported as verified**: distinct
+  error, exit `15`. Key rotation ships as a new `llmt` release.
+- `llmt permissions` prints exactly what the tool reads, writes, and sends
+  (no telemetry, **no self-update** — enforced by unit test). Prose version:
+  [docs/PERMISSIONS.md](docs/PERMISSIONS.md).
+- Dependencies are pinned: `pip install llmt-cli -c constraints.txt`, or
+  fully hash-verified in two steps (the lock file covers the dependency
+  closure only — `llmt` itself is not in it, so install it separately):
+  `pip install --require-hashes -r requirements.lock && pip install --no-deps .`
+- Releases ship a `SHA256SUMS` file (checksums published on
+  llmtorrents.com); build + signing process: [docs/RELEASING.md](docs/RELEASING.md).
+- Vulnerability reports: [SECURITY.md](SECURITY.md).
+- Docker image (pinned base, non-root) and homelab recipes:
+  [docs/recipes/](docs/recipes/).
+
+## Usage
+
+```bash
+llmt search "llama"                       # readable table of matches
+llmt search "qwen" --fit --rig vram_gb=24 # fit verdict for your rig
+llmt search "phi" --json                  # machine-readable
+
+llmt pull microsoft-phi-4-mini            # best quant -> download -> verify
+llmt pull microsoft-phi-4-mini:Q4_K_M     # a specific quant
+llmt pull acme-tiny-1b --dry-run          # show the exact aria2c command
+
+llmt verify ./acme-tiny-1b-Q4_K_M acme-tiny-1b:Q4_K_M   # re-check, no download
+llmt seed acme-tiny-1b:Q4_K_M ./acme-tiny-1b-Q4_K_M     # help the swarm
+```
+
+Global flags on every command: `--json`, `--api-base`, `--api-key`,
+`--timeout`. Configure via env: `LLMT_API_BASE`, `LLMT_API_KEY`
+(the complete list of every env var `llmt` reads is in
+[docs/PERMISSIONS.md](docs/PERMISSIONS.md) and `llmt permissions`).
+An API key is optional and only **raises your rate limits** — all reads are
+public.
+
+## The trust story (signed manifest + SHA-256)
+
+A torrent's own piece hashes only prove the bytes match *that* `.torrent`.
+They don't prove the `.torrent` describes the model the catalog vouched for
+— and TLS alone only proves who you *talked to*, not that the file list is
+the one the catalog *signed*. `llmt` closes both gaps:
+
+1. **The Ed25519-signed manifest is the source of truth.** For a non-gated
+   model, `llmt` fetches the torrent's manifest
+   (`GET /api/manifests/{info_hash}`) and **verifies its detached Ed25519
+   signature** against the public key pinned inside this package
+   (`llmt/data/manifest-pubkey.json`, per the open
+   [manifest spec](https://llmtorrents.com/schema/manifest-v0.1.0.json)).
+   It also checks that the signed document actually names the torrent being
+   verified, and that the API's `download.files[]` block agrees with the
+   signed manifest.
+2. **After the download**, `llmt` streams each file through SHA-256 (64 KiB
+   chunks, no whole-file buffering) and compares byte-for-byte against the
+   **verified manifest's** hash. This is a real, independent check — not
+   aria2c's piece check.
+3. **Any mismatch, missing file, or wrong size fails the run** and `llmt`
+   exits non-zero (`3`). A tampered or truncated file cannot pass silently.
+   A file for which no hash was supplied is flagged `NO-HASH`, never waved
+   through.
+4. **An unauthenticatable manifest fails the run before any hashing** —
+   unreachable endpoint (e.g. offline), malformed document, invalid
+   signature, unknown/rotated signing key, wrong torrent, or a
+   catalog/manifest disagreement each produce a distinct error and exit
+   `15`. `llmt` never silently falls back to trusting unsigned hashes over
+   TLS. (If the key was rotated, upgrading to the newest `llmt` release
+   picks up the new pinned key.)
+5. **`llmt verify`** re-runs exactly this check on already-downloaded files
+   — including the manifest signature check, so it needs the catalog API to
+   be reachable; there is no offline "verified". `llmt seed` refuses to
+   seed a torrent whose manifest cannot be authenticated.
+
+Because a wrong file trips a non-zero exit, `llmt pull` / `llmt verify` drop
+straight into a pipeline: if it exits `0`, every file matched the
+Ed25519-verified manifest.
+
+## License-gated models (why some models won't download)
+
+Some models are distributed under a click-through license. For those, the
+catalog API serves **no download artifacts at all** — no magnet, no hashes, no
+file list. `llmt` detects this and tells you to accept the license on the
+model's page first:
+
+```
+$ llmt pull meta-llama-llama-3-3-70b-instruct
+'meta-llama-llama-3-3-70b-instruct' is license-gated. The catalog API does not
+serve download artifacts for gated models.
+Accept the license here, then retry: https://llmtorrents.com/models/meta-llama-llama-3-3-70b-instruct
+```
+
+`llmt` will never fabricate a magnet or hash to work around a gate.
+
+## How the download works (aria2c + webseeds)
+
+`llmt` delegates the transfer to `aria2c`, passing the catalog's magnet URI
+plus every webseed URL as trailing HTTP URIs, so aria2c uses the project's
+HTTP mirrors as web-seeds alongside the BitTorrent swarm. Roughly:
+
+```
+aria2c --dir <out> --enable-dht=true --bt-enable-lpd=true \
+       --check-integrity=true --max-connection-per-server=8 --seed-time=0 \
+       [--bt-tracker <tracker> ...] \
+       <magnet> <webseed-url-1> <webseed-url-2> ...
+```
+
+Use `llmt pull ... --dry-run` to print the exact command for your model.
+
+### Known webseed quirks (why aria2c may exit non-zero on a good download)
+
+Both HTTP origins serve the model files but **403 the bare base URL**
+(directory listings are disabled by design), and hybrid v1+v2 torrents
+contain BEP-47 `.pad` entries that **404 on the HTTP mirrors** (often seen as
+a "stall" at 98-99% in aria2c's progress summary). Either can make `aria2c`
+exit non-zero (e.g. code 22) even though every payload byte arrived.
+
+`llmt pull` handles this: when aria2c exits non-zero it checks that every
+expected file is present on disk at its expected size. If so, it notes the
+quirk on stderr and proceeds straight to the full SHA-256 verification — the
+hash check against the signed manifest, not aria2c's exit code, is the trust
+signal. If files are missing or the wrong size, the download really did fail
+and `llmt` exits `10` loudly.
+
+`llmt verify <dir> <ref>` accepts either the **outer** download directory
+(the one `pull` created) or the **inner** payload directory the torrent
+unpacked inside it — it detects which you passed. If it can't find the files
+at all, it tells you exactly which directory to pass.
+
+## Seeding your existing models (the layout mapper)
+
+SHA-256 tells you a file *is* the right bytes, but a BitTorrent client won't
+seed those bytes unless they appear at the exact path the torrent expects,
+under the torrent's root folder. Your model lives at
+`/models/qwen3-30b/model.gguf`; the torrent wants
+`qwen3-30b-a3b-q4-k-m/Qwen3-30B-A3B-Q4_K_M.gguf`. The layout mapper plans how to
+present your existing file to the client **without moving or copying it**.
+
+- **Direct-use:** if your file already sits at the expected relative path, the
+  plan is just "add the torrent with this save path" — no links at all.
+- **Link farm (default for mismatched layouts):** the mapper builds a tiny tree
+  under `~/.llmt/seeding-layouts/<torrent-root>/…` whose entries are hard/sym
+  **links** back to your real file. Your model folder stays your model folder;
+  the farm is just a set of pointers the client can follow. Save path is the
+  layouts dir; the client rechecks, sees 100%, and seeds. Model weights are
+  never re-downloaded and nothing is duplicated on disk. One honest caveat for
+  multi-file torrents you hold only partially: small companion files
+  (license/README-class, at most 10 MiB total per torrent) may be fetched by
+  your client, and `llmt scan` prints a notice naming them and where they land
+  first; any larger missing file is marked "do not download" in your client
+  before the torrent can resume, with a warning that it will seed only what
+  you have and show as incomplete.
+
+Hardlinks are preferred whenever the file and the farm are on the same
+filesystem/volume — they need no privileges and every client follows them. A
+symlink is the labelled cross-volume fallback.
+
+| Platform | Same volume | Cross volume |
+| --- | --- | --- |
+| Linux / macOS | hardlink | symlink |
+| Windows | hardlink (same drive, no admin) | symlink — needs **Administrator or Developer Mode** (NTFS junctions redirect directories only, not files) |
+
+The client must **force-recheck** after adding so it verifies the linked bytes
+and reaches 100%. The mapper refuses any path that would escape the layouts dir
+(`..`, absolute/drive-letter/UNC tricks, reserved names, null bytes) and never
+silently replaces an existing link that points somewhere else.
+
+**Dockerized or remote clients (seedbox / unRAID):** a qBittorrent or
+Transmission running in a container only sees its own **mounted volumes**, not
+host paths like `~/.llmt/seeding-layouts`. If the link farm lives on a path the
+client cannot see, its force-recheck reads **0%** and `llmt scan` **fails
+closed** (it never resumes an unverified torrent). Point the farm at a directory
+the client has mounted with `--layout-base`, e.g.
+`llmt scan --layout-base /mnt/user/appdata/qbittorrent/llmt-layouts`. `llmt
+scan` also prints an early advisory when it detects the client's own default
+save path does not exist on the machine llmt is running on (a sign the two are
+on different filesystems), and `llmt doctor` reports a `layout-base-visible`
+check that WARNs in the same situation.
+
+## Opt-in seeding telemetry (off by default)
+
+Telemetry lets the LLM Torrents site **credit you for the artifacts you
+seed**. It is a *separate, explicit, off-by-default, revocable* opt-in — it
+never runs until you turn it on, and it never sends file paths or scan data.
+
+```bash
+llmt telemetry enable            # prints the exact consent statement, then
+                                 # prompts for your token (from the website)
+llmt telemetry enable --yes --token llmta_xx…   # non-interactive (scripts)
+llmt telemetry status            # consent state, token presence, last beat
+llmt telemetry whoami            # who the stored token belongs to (GET /me)
+llmt telemetry beat --qb-url http://localhost:8080   # send one heartbeat
+llmt telemetry beat --loop       # keep beating every 15 min (or --interval N)
+llmt telemetry disable           # stop sending AND delete the stored token
+```
+
+`beat` reads the torrents from your client (`--qb-url`/`--tr-url` or
+`LLMT_QB_URL`/`LLMT_TR_URL`, same flags as `scan`/`doctor`), reports each
+torrent's infohashes (v1 **and** v2 for hybrid torrents), name, state and
+progress plus the SHA-256s of the artifacts you hold, and answers any
+possession challenges the server issues by hashing a server-chosen byte range
+of the local file. Run it from `cron` (the primary mode) or with `--loop`.
+
+**What is sent:** torrent infohashes/names/states/progress, artifact
+SHA-256s, and challenge byte-range hashes — nothing else.
+**What is never sent:** file paths, filenames, scan data, or machine info.
+The token is stored at `~/.llmt/agent-token` (mode `0600`) and is never
+printed after it is saved. View or delete your server-side data on the
+website (Account -> Telemetry). See [docs/PERMISSIONS.md](docs/PERMISSIONS.md)
+and `llmt permissions` for the full statement.
+
+Config keys (in `~/.llmt/config.json`, all under `telemetry`):
+`enabled` (default `false`), `endpoint` (default `https://llmtorrents.com`),
+`interval_minutes` (`15`), `max_torrents_per_heartbeat` (`500`),
+`report_artifacts` (`true`), `token_path`, `challenge_chunk_size`.
+Override the endpoint per-run with `--endpoint` or `LLMT_TELEMETRY_ENDPOINT`.
+
+## Exit codes
+
+| code | meaning |
+|------|---------|
+| 0 | success / all files verified |
+| 2 | generic API error (incl. 403) |
+| 3 | **SHA-256 verification failed** |
+| 4 | not found (404) |
+| 5 | rate limited (429; respects `Retry-After`) |
+| 6 | request timed out |
+| 7 | model is license-gated (D7) |
+| 8 | no gate-passed torrent available |
+| 9 | `aria2c` not installed |
+| 10 | `aria2c` failed and the download is incomplete |
+| 14 | torrent-client add/connection failed |
+| 15 | **manifest unverifiable** (fetch failed/offline, malformed, bad signature, wrong/rotated key, wrong torrent, or catalog/manifest mismatch) — nothing was verified |
+| 20 | telemetry error (generic / disabled) |
+| 21 | telemetry token missing/unknown/revoked (401) |
+| 22 | telemetry token lacks `telemetry:write` scope (403) |
+| 23 | telemetry config error (no token / bad endpoint) |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -m "not live"   # offline unit suite (mocked API)
+pytest -m live         # read-only smoke calls to the real API
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

llmt_cli-0.2.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llmt-cli"
+version = "0.2.0"
+description = "Find, download (over BitTorrent + webseeds), and SHA-256-verify LLM models from the LLM Torrents catalog."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "LLM Torrents" }]
+keywords = ["llm", "torrent", "bittorrent", "webseed", "sha256", "ed25519", "models", "aria2"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: File Sharing",
+    "Topic :: Utilities",
+]
+# PyNaCl provides the Ed25519 verify primitive for signed manifests (M2):
+# it binds libsodium — the same library the catalog signs with
+# (crypto_sign_detached) — and is the verifier the frozen manifest spec's
+# reference example uses. Growing this list is a deliberate, reviewed act:
+# see tests/test_supply_chain.py::test_runtime_deps_stay_minimal.
+dependencies = [
+    "requests>=2.25",
+    "PyNaCl>=1.5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "requests-mock>=1.9"]
+
+[project.urls]
+Homepage = "https://llmtorrents.com"
+Source = "https://llmtorrents.com"
+
+[project.scripts]
+llmt = "llmt.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# The pinned manifest-signing public key (trust root for `llmt verify`).
+llmt = ["data/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: hits the real llmtorrents.com API (read-only smoke); run with -m live",
+]

llmt_cli-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

llmt_cli-0.2.0/src/llmt/__init__.py

@@ -0,0 +1,7 @@
+"""llmt — LLM Torrents command-line client.
+
+Find, download (over BitTorrent + webseeds) and SHA-256-verify LLM models
+from the public LLM Torrents catalog API.
+"""
+
+__version__ = "0.2.0"