unmuzzle 0.1.0__py3-none-any.whl

unmuzzle/__init__.py

@@ -0,0 +1,3 @@
+"""Unmuzzle: censorship-resistant distribution for open-weight models."""
+
+__version__ = "0.1.0"

unmuzzle/api.py

@@ -0,0 +1,206 @@
+"""Programmatic API for agents.
+
+Agents (Claude Code, Codex, Kimi Code, MCP clients) should call these
+functions, or the MCP server in unmuzzle.mcp_server, instead of scraping
+CLI output. Every function returns plain JSON-serializable dicts and raises
+UnmuzzleError with a machine-actionable message.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from . import hfcache, sign as signmod
+from .download import DownloadError, download_file, download_torrent, sha256_file
+from .index import ModelEntry, find_model, load_index
+from .publish import build_entry, write_entry
+
+
+class UnmuzzleError(Exception):
+    pass
+
+
+def _entry_dict(e: ModelEntry) -> dict:
+    d = dict(e.raw) if e.raw else {}
+    d.update({
+        "name": e.name,
+        "description": e.description,
+        "base_model": e.base_model,
+        "license": e.license,
+        "tags": e.tags,
+        "files": e.files,
+        "total_size": e.total_size,
+        "mirrors": {"http": e.http, "magnet": e.magnet, "torrent": e.torrent},
+        "signed": bool(e.signature),
+        "revision": e.revision(),
+    })
+    return d
+
+
+def _find(name: str, index: Optional[str]) -> ModelEntry:
+    entry = find_model(load_index(index), name)
+    if not entry:
+        raise UnmuzzleError(f"not found: {name}")
+    return entry
+
+
+def list_models(tag: Optional[str] = None, index: Optional[str] = None) -> List[dict]:
+    entries = load_index(index)
+    if tag:
+        entries = [e for e in entries if tag in e.tags]
+    return [_entry_dict(e) for e in entries]
+
+
+def model_info(name: str, index: Optional[str] = None) -> dict:
+    return _entry_dict(_find(name, index))
+
+
+def check_signature(entry: ModelEntry, require: bool = False) -> dict:
+    """Verify the entry's minisign signature. Returns a status dict; raises if invalid."""
+    if not entry.signature:
+        if require:
+            raise UnmuzzleError(f"{entry.name} is unsigned and signature was required")
+        return {"signed": False, "verified": False}
+    if not entry.publisher_pubkey:
+        raise UnmuzzleError("entry has a signature but no publisher_pubkey")
+    if not signmod.have_minisign():
+        if require:
+            raise UnmuzzleError("minisign not installed, cannot verify (brew install minisign)")
+        return {"signed": True, "verified": False, "warning": "minisign not installed, skipped"}
+    if not signmod.verify(entry.canonical_manifest(), entry.signature, entry.publisher_pubkey):
+        raise UnmuzzleError(f"SIGNATURE INVALID for {entry.name}")
+    return {"signed": True, "verified": True}
+
+
+def get(
+    name: str,
+    dest: Optional[str] = None,
+    method: str = "auto",
+    jobs: int = 8,
+    require_signature: bool = False,
+    index: Optional[str] = None,
+    progress: Optional[Callable[[str], None]] = None,
+) -> dict:
+    """Download a model. Returns {revision, method, path, hf_cache, files, bytes}."""
+    entry = _find(name, index)
+    sig = check_signature(entry, require_signature)
+
+    if method == "auto":
+        if (entry.torrent or entry.magnet) and shutil.which("aria2c"):
+            method = "torrent"
+        elif entry.http:
+            method = "http"
+        elif entry.torrent or entry.magnet:
+            method = "torrent"
+        else:
+            raise UnmuzzleError("entry has no usable mirrors")
+    if method == "torrent" and not (entry.torrent or entry.magnet):
+        raise UnmuzzleError("entry has no torrent or magnet link")
+    if method == "http" and not entry.http:
+        raise UnmuzzleError("entry has no http mirrors")
+
+    revision = entry.revision()
+    if dest:
+        root = Path(dest)
+    else:
+        root = hfcache.model_cache_dir(entry.name) / ".staging" / revision
+    root.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if method == "torrent":
+            download_torrent(entry.torrent or entry.magnet, root)
+            for f in entry.files:
+                p = root / f["path"]
+                if not p.exists() or sha256_file(p) != f["sha256"]:
+                    raise UnmuzzleError(f"{f['path']}: sha256 mismatch after torrent download")
+        else:
+            for f in entry.files:
+                if progress:
+                    progress(f"downloading {f['path']}")
+                download_file(entry.http, f["path"], root / f["path"], f["size"], f["sha256"],
+                              jobs=jobs, progress=progress)
+    except DownloadError as e:
+        raise UnmuzzleError(str(e))
+
+    result = {
+        "name": entry.name,
+        "revision": revision,
+        "method": method,
+        "files": len(entry.files),
+        "bytes": entry.total_size,
+        "signature": sig,
+    }
+    if dest:
+        result.update(path=str(root), hf_cache=False)
+    else:
+        snapshot = hfcache.install(entry.name, revision, root, entry.files)
+        shutil.rmtree(root, ignore_errors=True)
+        result.update(path=str(snapshot), hf_cache=True)
+        result["load_with"] = (
+            f'from transformers import AutoModelForCausalLM; '
+            f'model = AutoModelForCausalLM.from_pretrained("{entry.name}", local_files_only=True)'
+        )
+    return result
+
+
+def publish(
+    directory: str,
+    name: str,
+    http_bases: Optional[List[str]] = None,
+    magnet: Optional[str] = None,
+    torrent_url: Optional[str] = None,
+    description: str = "",
+    base_model: str = "",
+    license: str = "",
+    tags: Optional[List[str]] = None,
+    sign_key: Optional[str] = None,
+    pubkey: Optional[str] = None,
+    index_dir: str = "index",
+) -> dict:
+    """Hash a local model dir, optionally sign, and add it to a local index."""
+    entry = build_entry(
+        directory=Path(directory), name=name, http_bases=list(http_bases or []),
+        magnet=magnet, torrent_url=torrent_url, description=description,
+        base_model=base_model,
+        license_=license, tags=list(tags or []),
+        secret_key=Path(sign_key) if sign_key else None, pubkey=pubkey,
+    )
+    path = write_entry(Path(index_dir), entry)
+    return {
+        "entry": entry,
+        "entry_path": str(path),
+        "index": str(Path(index_dir) / "index.json"),
+        "signed": bool(entry.get("signature")),
+    }
+
+
+def verify(name: str, index: Optional[str] = None) -> dict:
+    """Re-hash an installed model against the index."""
+    entry = _find(name, index)
+    snapshot = hfcache.model_cache_dir(entry.name) / "snapshots" / entry.revision()
+    if not snapshot.exists():
+        raise UnmuzzleError(f"not installed: {entry.name}")
+    bad = []
+    for f in entry.files:
+        p = snapshot / f["path"]
+        if not (p.exists() and sha256_file(p) == f["sha256"]):
+            bad.append(f["path"])
+    return {"name": entry.name, "ok": not bad, "bad_files": bad,
+            "checked": len(entry.files), "path": str(snapshot)}
+
+
+def keygen(key_path: Optional[str] = None) -> dict:
+    """Generate a minisign keypair for signing releases. Non-interactive."""
+    if not signmod.have_minisign():
+        raise UnmuzzleError("minisign not installed (brew install minisign / apt install minisign)")
+    secret = Path(key_path or Path.home() / ".minisign" / "unmuzzle.key")
+    pub = secret.with_suffix(".pub")
+    if secret.exists():
+        raise UnmuzzleError(f"key already exists: {secret}")
+    secret.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["minisign", "-G", "-W", "-s", str(secret), "-p", str(pub)],
+                   check=True, capture_output=True)
+    return {"secret_key": str(secret), "public_key": str(pub),
+            "pubkey": signmod.pubkey_from_secret(secret)}

unmuzzle/cli.py

@@ -0,0 +1,190 @@
+"""unmuzzle command line interface.
+
+Thin wrapper over unmuzzle.api. All output is human-readable by default and
+JSON with --json, so agents can drive everything non-interactively.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__, api
+
+
+def _fmt_size(n) -> str:
+    n = float(n)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if n < 1024 or unit == "TiB":
+            return f"{n:.1f} {unit}" if unit != "B" else f"{int(n)} B"
+        n /= 1024
+    return f"{n} B"
+
+
+def _emit(obj, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(obj, indent=2))
+
+
+def cmd_list(args) -> int:
+    models = api.list_models(tag=args.tag, index=args.index)
+    _emit(models, args.json)
+    if not args.json:
+        if not models:
+            print("index is empty. Publish a model with `unmuzzle publish`.")
+        for m in models:
+            sig = " [signed]" if m["signed"] else ""
+            tags = f"  ({', '.join(m['tags'])})" if m["tags"] else ""
+            print(f"{m['name']:<44} {_fmt_size(m['total_size']):>10}{sig}{tags}")
+    return 0
+
+
+def cmd_info(args) -> int:
+    m = api.model_info(args.model, index=args.index)
+    _emit(m, args.json)
+    if not args.json:
+        print(f"name:        {m['name']}")
+        for label, key in (("description", "description"), ("base model", "base_model"),
+                           ("license", "license")):
+            if m.get(key):
+                print(f"{label + ':':<13}{m[key]}")
+        print(f"revision:    {m['revision']}")
+        print(f"total size:  {_fmt_size(m['total_size'])}")
+        print(f"mirrors:     {len(m['mirrors']['http'])} http"
+              + (", 1 torrent" if m["mirrors"]["magnet"] else ""))
+        print(f"signature:   {'yes' if m['signed'] else 'no'}")
+        print("files:")
+        for f in m["files"]:
+            print(f"  {_fmt_size(f['size']):>10}  {f['path']}")
+    return 0
+
+
+def cmd_get(args) -> int:
+    progress = (lambda s: print(s, file=sys.stderr)) if args.json else print
+    result = api.get(
+        args.model, dest=args.dest, method=args.method, jobs=args.jobs,
+        require_signature=args.require_signature, index=args.index,
+        progress=progress,
+    )
+    _emit(result, args.json)
+    if not args.json:
+        if result["signature"].get("verified"):
+            print("signature: OK")
+        if result["hf_cache"]:
+            print(f"\ninstalled into HF cache: {result['path']}")
+            print(f"\nload it with:\n  {result['load_with']}")
+        else:
+            print(f"\ndone. Files in {result['path']}")
+    return 0
+
+
+def cmd_publish(args) -> int:
+    result = api.publish(
+        directory=args.dir, name=args.name, http_bases=args.http_base,
+        magnet=args.magnet, torrent_url=args.torrent_url,
+        description=args.description or "",
+        base_model=args.base_model or "", license=args.license or "",
+        tags=args.tag, sign_key=args.sign_key, pubkey=args.pubkey,
+        index_dir=args.index_dir,
+    )
+    _emit(result, args.json)
+    if not args.json:
+        print(f"wrote {result['entry_path']}")
+        print(f"regenerated {result['index']}")
+        if not result["signed"]:
+            print("note: entry is unsigned. Use --sign-key to sign releases.")
+        print("\nnext: upload the model files to your mirror(s), then commit and push the index.")
+    return 0
+
+
+def cmd_verify(args) -> int:
+    result = api.verify(args.model, index=args.index)
+    _emit(result, args.json)
+    if not args.json:
+        print(f"{'OK' if result['ok'] else 'BAD'}: {result['checked']} files checked at {result['path']}")
+    return 0 if result["ok"] else 1
+
+
+def cmd_keygen(args) -> int:
+    result = api.keygen(args.key)
+    _emit(result, args.json)
+    if not args.json:
+        print(f"secret key: {result['secret_key']} (keep it secret, back it up)")
+        print(f"public key: {result['public_key']}")
+        print(f"pubkey:     {result['pubkey']}")
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="unmuzzle",
+        description="Agent-native, censorship-resistant distribution for open-weight models.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp, index=False):
+        sp.add_argument("--json", action="store_true", help="machine-readable output")
+        if index:
+            sp.add_argument("--index", default=None,
+                            help="index URL or local path (default: $UNMUZZLE_INDEX or the unmuzzle index)")
+
+    sp = sub.add_parser("list", help="list models in the index")
+    sp.add_argument("--tag", help="filter by tag")
+    common(sp, index=True)
+    sp.set_defaults(fn=cmd_list)
+
+    sp = sub.add_parser("info", help="show files, mirrors, and signature for a model")
+    sp.add_argument("model")
+    common(sp, index=True)
+    sp.set_defaults(fn=cmd_info)
+
+    sp = sub.add_parser("get", help="download a model and install it into the HF cache")
+    sp.add_argument("model")
+    sp.add_argument("--dest", help="download plain files to this directory instead of the HF cache")
+    sp.add_argument("--method", choices=["auto", "http", "torrent"], default="auto")
+    sp.add_argument("--jobs", type=int, default=8, help="parallel chunks per file (http)")
+    sp.add_argument("--require-signature", action="store_true",
+                    help="abort unless the entry has a valid minisign signature")
+    common(sp, index=True)
+    sp.set_defaults(fn=cmd_get)
+
+    sp = sub.add_parser("publish", help="hash a local model dir and add it to a local index")
+    sp.add_argument("dir", help="directory containing the model files")
+    sp.add_argument("--name", required=True, help="org/name")
+    sp.add_argument("--http-base", action="append", help="base URL where files will be served (repeatable)")
+    sp.add_argument("--magnet", help="magnet link for the torrent of this directory")
+    sp.add_argument("--torrent-url", help="URL of the .torrent file (preferred over magnet: works with zero peers via web seeds)")
+    sp.add_argument("--description")
+    sp.add_argument("--base-model")
+    sp.add_argument("--license")
+    sp.add_argument("--tag", action="append", help="tag (repeatable)")
+    sp.add_argument("--sign-key", help="minisign secret key to sign the manifest")
+    sp.add_argument("--pubkey", help="publisher pubkey (base64); derived from --sign-key if omitted")
+    sp.add_argument("--index-dir", default="index", help="local index directory to update")
+    common(sp)
+    sp.set_defaults(fn=cmd_publish)
+
+    sp = sub.add_parser("verify", help="re-hash an installed model against the index")
+    sp.add_argument("model")
+    common(sp, index=True)
+    sp.set_defaults(fn=cmd_verify)
+
+    sp = sub.add_parser("keygen", help="generate a minisign keypair for signing releases")
+    sp.add_argument("--key", help="secret key path (default: ~/.minisign/unmuzzle.key)")
+    common(sp)
+    sp.set_defaults(fn=cmd_keygen)
+
+    args = p.parse_args(argv)
+    try:
+        return args.fn(args)
+    except api.UnmuzzleError as e:
+        if getattr(args, "json", False):
+            print(json.dumps({"error": str(e)}), file=sys.stderr)
+        else:
+            print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

unmuzzle/download.py

@@ -0,0 +1,138 @@
+"""Parallel ranged HTTP downloads with resume, plus magnet links via aria2c.
+
+HTTP downloads split each file into fixed-size chunks fetched with Range
+requests from any of the entry's mirrors. Chunks land in a .parts directory
+next to the target, so an interrupted download resumes where it stopped.
+Every completed file is verified against the sha256 from the index before
+it is moved into place.
+"""
+from __future__ import annotations
+
+import concurrent.futures as cf
+import hashlib
+import shutil
+import subprocess
+import urllib.request
+from pathlib import Path
+from typing import Callable, List, Optional
+
+DEFAULT_CHUNK = 32 * 1024 * 1024  # 32 MiB
+
+
+class DownloadError(Exception):
+    pass
+
+
+def _fetch_range(url: str, start: int, end: int, dest: Path, retries: int = 4) -> None:
+    want = end - start + 1
+    for attempt in range(retries):
+        try:
+            req = urllib.request.Request(url, headers={"Range": f"bytes={start}-{end}"})
+            with urllib.request.urlopen(req, timeout=300) as r, open(dest, "wb") as f:
+                shutil.copyfileobj(r, f, 1024 * 1024)
+            if dest.stat().st_size == want:
+                return
+        except Exception:
+            if attempt == retries - 1:
+                raise
+    raise DownloadError(f"range {start}-{end} from {url}: incomplete after {retries} tries")
+
+
+def sha256_file(path: Path, buf: int = 8 * 1024 * 1024) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(buf), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def download_file(
+    base_urls: List[str],
+    relpath: str,
+    dest: Path,
+    size: int,
+    sha256: str,
+    jobs: int = 8,
+    chunk_size: int = DEFAULT_CHUNK,
+    progress: Optional[Callable[[str], None]] = None,
+) -> Path:
+    """Fetch one file from any of base_urls (base + '/' + relpath), verify sha256."""
+    dest = Path(dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.exists() and dest.stat().st_size == size and sha256_file(dest) == sha256:
+        return dest  # already have it, verified
+
+    urls = [f"{base.rstrip('/')}/{relpath}" for base in base_urls]
+    parts_dir = dest.parent / (dest.name + ".parts")
+    parts_dir.mkdir(parents=True, exist_ok=True)
+
+    n_chunks = max(1, (size + chunk_size - 1) // chunk_size)
+    todo = []
+    for i in range(n_chunks):
+        start = i * chunk_size
+        end = min(size - 1, start + chunk_size - 1)
+        part = parts_dir / f"{i:06d}"
+        if part.exists() and part.stat().st_size == end - start + 1:
+            continue  # resume: chunk already done
+        todo.append((i, start, end, part))
+
+    def work(t):
+        i, start, end, part = t
+        last_err: Optional[Exception] = None
+        for url in urls:
+            try:
+                _fetch_range(url, start, end, part)
+                return i
+            except Exception as e:  # try next mirror
+                last_err = e
+        raise DownloadError(f"{relpath} chunk {i}: all mirrors failed ({last_err})")
+
+    done = n_chunks - len(todo)
+    if todo:
+        with cf.ThreadPoolExecutor(max_workers=jobs) as ex:
+            for _ in ex.map(work, todo):
+                done += 1
+                if progress:
+                    progress(f"  {relpath}: {done}/{n_chunks} chunks")
+
+    tmp = dest.with_name(dest.name + ".tmp")
+    h = hashlib.sha256()
+    with open(tmp, "wb") as out:
+        for i in range(n_chunks):
+            with open(parts_dir / f"{i:06d}", "rb") as p:
+                while True:
+                    block = p.read(8 * 1024 * 1024)
+                    if not block:
+                        break
+                    h.update(block)
+                    out.write(block)
+    if h.hexdigest() != sha256:
+        tmp.unlink(missing_ok=True)
+        shutil.rmtree(parts_dir, ignore_errors=True)
+        raise DownloadError(f"{relpath}: sha256 mismatch (expected {sha256})")
+    if tmp.stat().st_size != size:
+        tmp.unlink(missing_ok=True)
+        raise DownloadError(f"{relpath}: size mismatch (expected {size})")
+    tmp.replace(dest)
+    shutil.rmtree(parts_dir, ignore_errors=True)
+    return dest
+
+
+def download_torrent(uri_or_file: str, dest_dir: Path) -> None:
+    """Fetch a torrent (magnet URI, .torrent URL, or local .torrent path) into
+    dest_dir using aria2c. Seeding is left to the user.
+
+    Prefer .torrent files over bare magnets when web seeds are the only
+    guaranteed source: a magnet still needs a reachable peer to fetch the
+    metadata, a .torrent plus a web seed works with zero peers.
+    """
+    if not shutil.which("aria2c"):
+        raise DownloadError(
+            "torrent downloads need aria2c (brew install aria2 / apt install aria2), "
+            "or retry with --method http"
+        )
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["aria2c", "--seed-time=0", "--summary-interval=30", "-d", str(dest_dir), uri_or_file],
+        check=True,
+    )

unmuzzle/hfcache.py

@@ -0,0 +1,54 @@
+"""Install downloaded files into the Hugging Face hub cache layout.
+
+Once installed, `from_pretrained("org/name", local_files_only=True)` loads
+the model with zero changes to user code. Blobs are content-addressed by
+sha256, snapshots symlink (or copy) into blobs, refs/main points at the
+revision.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import List
+
+
+def hf_cache_root() -> Path:
+    return Path(os.environ.get("HF_HOME", Path.home() / ".cache" / "huggingface")) / "hub"
+
+
+def model_cache_dir(model_id: str) -> Path:
+    return hf_cache_root() / f"models--{model_id.replace('/', '--')}"
+
+
+def install(model_id: str, revision: str, staging: Path, files: List[dict]) -> Path:
+    """Link files from staging into the HF cache. Returns the snapshot path."""
+    staging = Path(staging)
+    cache = model_cache_dir(model_id)
+    blobs = cache / "blobs"
+    snapshot = cache / "snapshots" / revision
+    refs = cache / "refs"
+    for d in (blobs, snapshot, refs):
+        d.mkdir(parents=True, exist_ok=True)
+
+    for f in files:
+        src = staging / f["path"]
+        if not src.exists():
+            raise FileNotFoundError(f"missing staged file {src}")
+        blob = blobs / f["sha256"]
+        if not blob.exists():
+            try:
+                os.link(src, blob)
+            except OSError:
+                shutil.copy2(src, blob)
+        link = snapshot / f["path"]
+        link.parent.mkdir(parents=True, exist_ok=True)
+        if link.is_symlink() or link.exists():
+            link.unlink()
+        try:
+            os.symlink(os.path.relpath(blob, link.parent), link)
+        except OSError:  # filesystem without symlinks
+            shutil.copy2(blob, link)
+
+    (refs / "main").write_text(revision)
+    return snapshot

unmuzzle/index.py

@@ -0,0 +1,116 @@
+"""Index loading, validation, and manifest canonicalization.
+
+The index is a single JSON document (see SPEC.md). It can live anywhere:
+a git repo, static hosting, IPFS. Clients fetch it over HTTPS or read it
+from a local path.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+DEFAULT_INDEX = (
+    "https://raw.githubusercontent.com/zengjiajun0623/unmuzzle-hub/main/index/index.json"
+)
+
+
+class IndexError(Exception):
+    pass
+
+
+@dataclass
+class ModelEntry:
+    name: str  # "org/name"
+    description: str = ""
+    base_model: str = ""
+    license: str = ""
+    tags: List[str] = field(default_factory=list)
+    files: List[dict] = field(default_factory=list)  # {path, size, sha256}
+    http: List[str] = field(default_factory=list)  # base URLs, file fetched from base + "/" + path
+    magnet: Optional[str] = None
+    torrent: Optional[str] = None  # URL of the .torrent file (works with zero peers via web seeds)
+    publisher_pubkey: Optional[str] = None
+    signature: Optional[str] = None  # minisign signature over canonical_manifest()
+    added: str = ""
+    raw: dict = field(default_factory=dict)
+
+    @property
+    def total_size(self) -> int:
+        return sum(f["size"] for f in self.files)
+
+    def canonical_manifest(self) -> str:
+        """Deterministic string that gets signed. One 'sha256  path' line per file, sorted."""
+        lines = sorted(f'{f["sha256"]}  {f["path"]}' for f in self.files)
+        return "\n".join(lines) + "\n"
+
+    def revision(self) -> str:
+        """Content-addressed stand-in for an HF commit sha."""
+        return hashlib.sha256(self.canonical_manifest().encode()).hexdigest()[:16]
+
+
+def validate_entry(d: dict) -> ModelEntry:
+    if not isinstance(d, dict):
+        raise IndexError("entry is not an object")
+    name = d.get("name")
+    if not name or "/" not in name:
+        raise IndexError(f"bad model name: {name!r} (expected 'org/name')")
+    files = d.get("files")
+    if not files:
+        raise IndexError(f"{name}: no files")
+    for f in files:
+        for key in ("path", "size", "sha256"):
+            if key not in f:
+                raise IndexError(f"{name}: file entry missing {key!r}: {f!r}")
+        parts = Path(f["path"]).parts
+        if f["path"].startswith("/") or ".." in parts:
+            raise IndexError(f"{name}: unsafe path {f['path']!r}")
+        if not isinstance(f["size"], int) or f["size"] < 0:
+            raise IndexError(f"{name}: bad size for {f['path']!r}")
+        if len(f["sha256"]) != 64:
+            raise IndexError(f"{name}: bad sha256 for {f['path']!r}")
+    mirrors = d.get("mirrors") or {}
+    entry = ModelEntry(
+        name=name,
+        description=d.get("description", ""),
+        base_model=d.get("base_model", ""),
+        license=d.get("license", ""),
+        tags=list(d.get("tags", [])),
+        files=list(files),
+        http=list(mirrors.get("http", [])),
+        magnet=mirrors.get("magnet"),
+        torrent=mirrors.get("torrent"),
+        publisher_pubkey=d.get("publisher_pubkey"),
+        signature=d.get("signature"),
+        added=d.get("added", ""),
+        raw=d,
+    )
+    if not entry.http and not entry.magnet and not entry.torrent:
+        raise IndexError(f"{name}: entry has no mirrors")
+    return entry
+
+
+def load_index(source: Optional[str] = None) -> List[ModelEntry]:
+    source = source or os.environ.get("UNMUZZLE_INDEX") or DEFAULT_INDEX
+    if source.startswith(("http://", "https://")):
+        with urllib.request.urlopen(source, timeout=30) as r:
+            data = json.loads(r.read().decode())
+    else:
+        data = json.loads(Path(source).read_text())
+    entries = data.get("models") if isinstance(data, dict) else data
+    return [validate_entry(e) for e in entries]
+
+
+def find_model(entries: List[ModelEntry], name: str) -> Optional[ModelEntry]:
+    for e in entries:
+        if e.name == name:
+            return e
+    # allow shorthand without org if unambiguous
+    matches = [e for e in entries if e.name.split("/", 1)[1] == name]
+    if len(matches) == 1:
+        return matches[0]
+    return None

unmuzzle/mcp_server.py

@@ -0,0 +1,80 @@
+"""MCP server: expose unmuzzle to any MCP-capable agent.
+
+Install:  pip install 'unmuzzle[mcp]'
+Run:      unmuzzle-mcp            (stdio transport)
+
+Claude Code:  claude mcp add unmuzzle -- unmuzzle-mcp
+"""
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+from . import api
+
+
+def main() -> None:
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        raise SystemExit("MCP support needs: pip install 'unmuzzle[mcp]'")
+
+    mcp = FastMCP("unmuzzle")
+
+    @mcp.tool()
+    def list_models(tag: Optional[str] = None, index: Optional[str] = None) -> str:
+        """List open-weight models in the unmuzzle index. Optionally filter by tag."""
+        return json.dumps(api.list_models(tag=tag, index=index))
+
+    @mcp.tool()
+    def model_info(name: str, index: Optional[str] = None) -> str:
+        """Show files, sizes, sha256, mirrors, and signature status for a model (org/name)."""
+        return json.dumps(api.model_info(name, index=index))
+
+    @mcp.tool()
+    def get_model(
+        name: str,
+        dest: Optional[str] = None,
+        method: str = "auto",
+        require_signature: bool = True,
+        index: Optional[str] = None,
+    ) -> str:
+        """Download a model, verify sha256 + signature, and install it into the
+        Hugging Face cache (default) or a plain directory (dest). method is
+        auto, http, or torrent."""
+        return json.dumps(api.get(name, dest=dest, method=method,
+                                  require_signature=require_signature, index=index))
+
+    @mcp.tool()
+    def publish_model(
+        directory: str,
+        name: str,
+        http_bases: Optional[List[str]] = None,
+        magnet: Optional[str] = None,
+        torrent_url: Optional[str] = None,
+        description: str = "",
+        base_model: str = "",
+        license: str = "",
+        tags: Optional[List[str]] = None,
+        sign_key: Optional[str] = None,
+        index_dir: str = "index",
+    ) -> str:
+        """Hash a local model directory, sign the manifest, and add it to a
+        local index. Upload the files to the mirror(s) yourself first or right
+        after; the entry records where they live."""
+        return json.dumps(api.publish(directory, name, http_bases=http_bases,
+                                      magnet=magnet, torrent_url=torrent_url,
+                                      description=description,
+                                      base_model=base_model, license=license,
+                                      tags=tags, sign_key=sign_key, index_dir=index_dir))
+
+    @mcp.tool()
+    def verify_model(name: str, index: Optional[str] = None) -> str:
+        """Re-hash an installed model against the signed index manifest."""
+        return json.dumps(api.verify(name, index=index))
+
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

unmuzzle/publish.py

@@ -0,0 +1,88 @@
+"""Build index entries from a local model directory (`unmuzzle publish`)."""
+from __future__ import annotations
+
+import json
+from datetime import date
+from pathlib import Path
+from typing import List, Optional
+
+from .download import sha256_file
+from .index import validate_entry
+from . import sign as signmod
+
+SKIP_NAMES = {".DS_Store"}
+SKIP_SUFFIXES = (".parts", ".tmp")
+
+
+def _iter_model_files(root: Path):
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = p.relative_to(root).as_posix()
+        if p.name in SKIP_NAMES or any(rel.endswith(s) for s in SKIP_SUFFIXES):
+            continue
+        if any(part.startswith(".") for part in p.relative_to(root).parts):
+            continue
+        yield rel, p
+
+
+def build_entry(
+    directory: Path,
+    name: str,
+    http_bases: List[str],
+    magnet: Optional[str] = None,
+    torrent_url: Optional[str] = None,
+    description: str = "",
+    base_model: str = "",
+    license_: str = "",
+    tags: Optional[List[str]] = None,
+    secret_key: Optional[Path] = None,
+    pubkey: Optional[str] = None,
+) -> dict:
+    directory = Path(directory)
+    files = []
+    for rel, p in _iter_model_files(directory):
+        files.append({"path": rel, "size": p.stat().st_size, "sha256": sha256_file(p)})
+    if not files:
+        raise ValueError(f"no model files found in {directory}")
+
+    entry = {
+        "name": name,
+        "description": description,
+        "base_model": base_model,
+        "license": license_,
+        "tags": tags or [],
+        "added": date.today().isoformat(),
+        "files": files,
+        "mirrors": {"http": http_bases, "magnet": magnet, "torrent": torrent_url},
+    }
+
+    if secret_key:
+        manifest = validate_entry(entry).canonical_manifest()
+        entry["signature"] = signmod.sign(manifest, Path(secret_key))
+        entry["publisher_pubkey"] = pubkey or signmod.pubkey_from_secret(Path(secret_key))
+
+    validate_entry(entry)  # final sanity check
+    return entry
+
+
+def write_entry(index_dir: Path, entry: dict) -> Path:
+    """Write one entry file and regenerate the combined index.json."""
+    index_dir = Path(index_dir)
+    models_dir = index_dir / "models"
+    models_dir.mkdir(parents=True, exist_ok=True)
+    slug = entry["name"].replace("/", "__")
+    (models_dir / f"{slug}.json").write_text(json.dumps(entry, indent=2) + "\n")
+    regenerate(index_dir)
+    return models_dir / f"{slug}.json"
+
+
+def regenerate(index_dir: Path) -> Path:
+    models_dir = Path(index_dir) / "models"
+    entries = []
+    if models_dir.exists():
+        for f in sorted(models_dir.glob("*.json")):
+            entries.append(json.loads(f.read_text()))
+    out = Path(index_dir) / "index.json"
+    out.write_text(json.dumps({"version": 1, "models": entries}, indent=2) + "\n")
+    return out

unmuzzle/sign.py

@@ -0,0 +1,64 @@
+"""minisign-based signing of manifests.
+
+The publisher signs the canonical manifest (sha256 + path per file) with
+minisign (OpenBSD signify compatible). Clients verify before installing.
+minisign is a single static binary: brew install minisign.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+
+class SignatureError(Exception):
+    pass
+
+
+def have_minisign() -> bool:
+    return shutil.which("minisign") is not None
+
+
+def pubkey_from_secret(secret_key: Path) -> str:
+    """Derive the base64 public key from a secret key via `minisign -R`."""
+    with tempfile.TemporaryDirectory() as td:
+        pub = Path(td) / "key.pub"
+        subprocess.run(
+            ["minisign", "-R", "-s", str(secret_key), "-p", str(pub)],
+            check=True, capture_output=True,
+        )
+        lines = pub.read_text().splitlines()
+    for line in lines:
+        line = line.strip()
+        if line and not line.startswith("untrusted comment"):
+            return line
+    raise SignatureError(f"could not parse pubkey from {pub!r}")
+
+
+def sign(manifest: str, secret_key: Path) -> str:
+    with tempfile.TemporaryDirectory() as td:
+        msg = Path(td) / "manifest.txt"
+        sig = Path(td) / "manifest.txt.minisig"
+        msg.write_text(manifest)
+        subprocess.run(
+            ["minisign", "-S", "-s", str(secret_key), "-x", str(sig), "-m", str(msg)],
+            check=True, capture_output=True,
+        )
+        return sig.read_text()
+
+
+def verify(manifest: str, signature: str, pubkey_b64: str) -> bool:
+    if not have_minisign():
+        raise SignatureError("minisign not installed, cannot verify signature")
+    with tempfile.TemporaryDirectory() as td:
+        msg = Path(td) / "manifest.txt"
+        sig = Path(td) / "manifest.txt.minisig"
+        msg.write_text(manifest)
+        sig.write_text(signature)
+        r = subprocess.run(
+            ["minisign", "-V", "-P", pubkey_b64, "-x", str(sig), "-m", str(msg)],
+            capture_output=True,
+        )
+        return r.returncode == 0

unmuzzle-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: unmuzzle
+Version: 0.1.0
+Summary: Censorship-resistant distribution for open-weight models. BitTorrent + HTTP mirrors, signed checksums, Hugging Face cache compatible.
+Author: Jiajun Zeng
+License: MIT
+Keywords: llm,open-weights,bittorrent,distribution,censorship-resistant
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Dynamic: license-file
+
+# unmuzzle
+
+[![e2e-verify](https://github.com/zengjiajun0623/unmuzzle-hub/actions/workflows/e2e-verify.yml/badge.svg)](https://github.com/zengjiajun0623/unmuzzle-hub/actions/workflows/e2e-verify.yml)
+
+Agent-native distribution for open-weight models.
+
+AI agents are the users here. `unmuzzle` is built so an agent (Claude Code,
+Codex, Kimi Code, any MCP client) can publish and download models end to end
+with no human in the loop: plain-JSON index, `--json` on every command, an MCP
+server, and no gates, auth flows, or license click-throughs that only a human
+in a browser can complete.
+
+It is also censorship-resistant by construction:
+
+- **The index is plain JSON in a git repo.** Anyone can mirror or fork it.
+- **Weights move over BitTorrent (web-seeded) and HTTP mirrors.** Web seeds
+  keep every torrent alive at zero peers; no central server to block or bill.
+- **Every file is sha256-pinned and the manifest is minisign-signed.** The
+  signature, not the host, is the trust root. Any static host can be a mirror.
+- **Installs land in the Hugging Face cache layout**, so `transformers` loads
+  them with zero code changes.
+
+Zero dependencies. Python 3.9+.
+
+## Install
+
+```bash
+pip install git+https://github.com/zengjiajun0623/unmuzzle-hub.git
+# optional: aria2 for torrents, minisign for signature verification
+```
+
+## For agents
+
+Read [AGENTS.md](AGENTS.md). It is the complete publish/download protocol.
+Or add the MCP server:
+
+```bash
+pip install 'unmuzzle[mcp]'
+claude mcp add unmuzzle -- unmuzzle-mcp
+```
+
+## For humans
+
+```bash
+unmuzzle list
+unmuzzle info unmuzzle/qwen2.5-14b-abliterated
+unmuzzle get  unmuzzle/qwen2.5-14b-abliterated --require-signature --dest ./models
+```
+
+Every command takes `--json`.
+
+## First release: unmuzzle/qwen2.5-14b-abliterated
+
+Qwen2.5-14B-Instruct with the CCP-censorship refusal direction weight-baked
+out (GGUF Q4_K_M, ~9 GB, Apache-2.0). Answers factually on Tiananmen, Xinjiang,
+Taiwan, and similar topics. Runs in Ollama/llama.cpp on a 16 GB machine:
+
+```bash
+unmuzzle get unmuzzle/qwen2.5-14b-abliterated --require-signature --dest ./models
+ollama create unmuzzle-qwen14b -f Modelfile   # Modelfile in the HF mirror repo
+ollama run unmuzzle-qwen14b
+```
+
+Mirrors: Hugging Face HTTP + web-seeded torrent. Signed with the unmuzzle
+minisign key.
+
+## Publish a model
+
+```bash
+unmuzzle keygen                       # one-time signing identity
+unmuzzle publish ./mymodel \
+  --name org/mymodel \
+  --http-base https://your-mirror/mymodel \
+  --torrent-url https://your-mirror/mymodel.torrent \
+  --magnet "magnet:?xt=..." \
+  --sign-key ~/.minisign/unmuzzle.key
+```
+
+Then PR your `index/models/*.json` into this repo, or host your own index and
+point clients at it with `--index` / `$UNMUZZLE_INDEX`. The full recipe,
+including torrent creation with web seeds, is in [AGENTS.md](AGENTS.md).
+Format and threat model: [SPEC.md](SPEC.md).
+
+## Why not just Hugging Face / a mirror / a torrent site?
+
+- **HF** gates models behind human browser flows and can take them down
+  (ERNIE ViLG, GEITje). In mainland China the site itself is blocked, which is
+  why hf-mirror.com exists. Right default for ordinary models, wrong single
+  point of failure for models someone wants suppressed, and unusable for
+  agents hitting gated repos.
+- **Mirrors** (hf-mirror, ModelScope) reintroduce a single operator who can
+  censor, and you cannot verify what they serve back to you.
+- **A bare torrent** has no discovery, no publisher identity, and dies at zero
+  seeds. unmuzzle adds the index, per-file sha256, publisher signatures, and
+  web seeds on top.
+
+## Roadmap
+
+- [x] first real release (unmuzzle/qwen2.5-14b-abliterated)
+- [x] MCP server for agent-native publish/download
+- [ ] standalone registry site generated from the index
+- [ ] DHT-native peer discovery, built-in torrent client (drop aria2c)
+- [ ] index federation: subscribe to multiple publisher indexes
+
+## License
+
+MIT

unmuzzle-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+unmuzzle/__init__.py,sha256=n2fVjIxguuZSNrcgYo6TTBxZXUDFp8ZJ1OuxK3cCtTQ,97
+unmuzzle/api.py,sha256=shXaHcc8HQQuwkQiWknFPWMPFdF_eD2im86h5rAbw8A,7627
+unmuzzle/cli.py,sha256=ONEDexvbHBworjd7fCZAvB-s18ClyGgE2rspLzrDwrA,7382
+unmuzzle/download.py,sha256=0BVYDLdUcPlCLzJs7BjPyQ9XoLIx-3bzGVr3_KHK_SM,4968
+unmuzzle/hfcache.py,sha256=Z9BLt5l6oFmyeK-hHn-S7B6vewzHhQFJf0XtPSVFztc,1797
+unmuzzle/index.py,sha256=02rsW61lB0MMxjP1A5Aeu8_13eFJIL_Pt4WM6Bmnuhw,4209
+unmuzzle/mcp_server.py,sha256=MGnd1ys5EcDhjxkQB59UR--Hm-CNnUNVAbNKuTE0UqU,2862
+unmuzzle/publish.py,sha256=Iwll56PdIu7DPFHXzI5-8w5udnALeFQF99Muv-kDSVA,2824
+unmuzzle/sign.py,sha256=TpzU0U7jzrMrN_5GGPDDpH6GJUVYJ_PeyTOxYCNAqJ4,2096
+unmuzzle-0.1.0.dist-info/licenses/LICENSE,sha256=CIzTP7_6jQBHtFLMP1Nl_Huw43O2g56fO4Hx6UwxDEc,1068
+unmuzzle-0.1.0.dist-info/METADATA,sha256=urB7w6lLxnNJlDgRILLGwbl25s1-6cWgFcusq2gD1pA,4448
+unmuzzle-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+unmuzzle-0.1.0.dist-info/entry_points.txt,sha256=JFhw31dwwapKpkXHpkboGKw_eUlngUgTnnhsjrH9Cv4,87
+unmuzzle-0.1.0.dist-info/top_level.txt,sha256=3AK_aVinNJgrjkyrXhQHyoXYC_Kcn92RJNbpFLh6aWQ,9
+unmuzzle-0.1.0.dist-info/RECORD,,

unmuzzle-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

unmuzzle-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+unmuzzle = unmuzzle.cli:main
+unmuzzle-mcp = unmuzzle.mcp_server:main

unmuzzle-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiajun Zeng
+
+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.

unmuzzle-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+unmuzzle