hugging-bay 0.1.0__tar.gz

hugging_bay-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: hugging-bay
+Version: 0.1.0
+Summary: Thin, typed Python client for the Hugging Bay API — verified open-model discovery, safety, and lockfiles.
+Author: Hugging Bay
+License: MIT
+Project-URL: Homepage, https://huggingbay.xyz
+Project-URL: Repository, https://github.com/barneywohl/hugging-bay
+Keywords: hugging-bay,models,safety,gguf,llm,provenance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+
+# hugging-bay
+
+A thin, typed Python client for the [Hugging Bay](https://huggingbay.xyz) API:
+verified open-model discovery, safe-to-run verdicts, provenance passports, and
+offline lockfile verification.
+
+The client is intentionally minimal — one method per endpoint, no client-side
+magic. Verdicts, fits, and identities are computed by the server and returned
+as parsed JSON.
+
+## Install
+
+```bash
+pip install hugging-bay
+```
+
+Requires Python 3.9+. The only runtime dependency is `httpx`.
+
+## Usage
+
+```python
+from hugging_bay import Client
+
+client = Client()  # defaults to https://huggingbay.xyz
+# Optional auth: Client(token="sk-...") sends Authorization: Bearer <token>.
+# The token is never printed in repr()/str() and never logged.
+```
+
+### 1. Find a commercial-safe model for a rig
+
+```python
+from hugging_bay import Client
+
+client = Client()
+result = client.find_model(
+    task="coding",
+    gpu="rtx4090-24",
+    ctx=8192,
+    device_family="nvidia",
+    commercial=True,
+    limit=3,
+)
+best = result["bestPick"]
+print(best["repo"], "-> safe-to-run:", best["safety"]["verdict"])
+```
+
+### 2. Verify a source URL
+
+```python
+from hugging_bay import Client, HuggingBayError
+
+client = Client()
+try:
+    resolved = client.resolve("https://huggingface.co/meta-llama/Llama-3.1-8B")
+    print("resolved artifact:", resolved.get("artifactId") or resolved)
+except HuggingBayError as err:
+    print("could not resolve:", err.status, err.error)
+```
+
+### 3. Pull plan, then verify the lock against local files
+
+```python
+from hugging_bay import Client, verify_lock
+
+client = Client()
+artifact_id = "art_123"
+
+# The hosted download plan (signed manifest + per-file hashes).
+plan = client.download_plan(artifact_id)
+
+# ... download the files into ./models/art_123 using the plan ...
+
+# Recompute local hashes and compare to the bay.lock document — pure stdlib,
+# no network.
+lock = client.lock(artifact_id)
+report = verify_lock(lock, root_dir="./models/art_123")
+if report["ok"]:
+    print(f"verified {report['checked']} files")
+else:
+    for mismatch in report["mismatches"]:
+        print("BAD:", mismatch["path"], mismatch["reason"])
+```
+
+### 4. Diagnose a failing run
+
+```python
+from hugging_bay import Client
+
+client = Client()
+diagnosis = client.doctor(
+    log_text="llama_model_load: error loading model: CUDA out of memory",
+    runtime="llama.cpp",
+)
+if diagnosis["topFix"]:
+    print("top fix:", diagnosis["topFix"])
+for alt in diagnosis.get("smallerHostedAlternatives", []):
+    print("smaller option:", alt)
+```
+
+## API surface
+
+| Method | Endpoint |
+| --- | --- |
+| `find_model(task, gpu, ctx, device_family, commercial, limit)` | `GET /api/agents/find-model` |
+| `artifact(id)` | `GET /api/v1/artifacts/{id}` |
+| `safety(id)` | `GET /api/v1/artifacts/{id}/safety` |
+| `bundle(id)` | `GET /api/artifacts/{id}/bundle` |
+| `passport(id)` | `GET /api/artifacts/{id}/passport` |
+| `resolve(repo_or_url)` | `GET /api/resolve?repo=` |
+| `download_plan(id)` | `GET /api/v1/artifacts/{id}/download-plan` |
+| `lock(id)` | `GET /api/artifacts/{id}/lock` |
+| `doctor(log_text, runtime)` | `POST /api/doctor` |
+| `recipes()` / `recipe(slug)` | `GET /api/recipes[/{slug}]` |
+| `verify_lock(lock_dict, root_dir)` | offline, stdlib only |
+
+## Errors
+
+Any response with status `>= 400` raises `HuggingBayError(status, body)`. The
+server's `error` field is exposed as `.error`; the parsed body is on `.body`.
+On a `503` with a `Retry-After` header the client waits once and retries a
+single time before raising.
+
+## License
+
+MIT

hugging_bay-0.1.0/README.md

@@ -0,0 +1,125 @@
+# hugging-bay
+
+A thin, typed Python client for the [Hugging Bay](https://huggingbay.xyz) API:
+verified open-model discovery, safe-to-run verdicts, provenance passports, and
+offline lockfile verification.
+
+The client is intentionally minimal — one method per endpoint, no client-side
+magic. Verdicts, fits, and identities are computed by the server and returned
+as parsed JSON.
+
+## Install
+
+```bash
+pip install hugging-bay
+```
+
+Requires Python 3.9+. The only runtime dependency is `httpx`.
+
+## Usage
+
+```python
+from hugging_bay import Client
+
+client = Client()  # defaults to https://huggingbay.xyz
+# Optional auth: Client(token="sk-...") sends Authorization: Bearer <token>.
+# The token is never printed in repr()/str() and never logged.
+```
+
+### 1. Find a commercial-safe model for a rig
+
+```python
+from hugging_bay import Client
+
+client = Client()
+result = client.find_model(
+    task="coding",
+    gpu="rtx4090-24",
+    ctx=8192,
+    device_family="nvidia",
+    commercial=True,
+    limit=3,
+)
+best = result["bestPick"]
+print(best["repo"], "-> safe-to-run:", best["safety"]["verdict"])
+```
+
+### 2. Verify a source URL
+
+```python
+from hugging_bay import Client, HuggingBayError
+
+client = Client()
+try:
+    resolved = client.resolve("https://huggingface.co/meta-llama/Llama-3.1-8B")
+    print("resolved artifact:", resolved.get("artifactId") or resolved)
+except HuggingBayError as err:
+    print("could not resolve:", err.status, err.error)
+```
+
+### 3. Pull plan, then verify the lock against local files
+
+```python
+from hugging_bay import Client, verify_lock
+
+client = Client()
+artifact_id = "art_123"
+
+# The hosted download plan (signed manifest + per-file hashes).
+plan = client.download_plan(artifact_id)
+
+# ... download the files into ./models/art_123 using the plan ...
+
+# Recompute local hashes and compare to the bay.lock document — pure stdlib,
+# no network.
+lock = client.lock(artifact_id)
+report = verify_lock(lock, root_dir="./models/art_123")
+if report["ok"]:
+    print(f"verified {report['checked']} files")
+else:
+    for mismatch in report["mismatches"]:
+        print("BAD:", mismatch["path"], mismatch["reason"])
+```
+
+### 4. Diagnose a failing run
+
+```python
+from hugging_bay import Client
+
+client = Client()
+diagnosis = client.doctor(
+    log_text="llama_model_load: error loading model: CUDA out of memory",
+    runtime="llama.cpp",
+)
+if diagnosis["topFix"]:
+    print("top fix:", diagnosis["topFix"])
+for alt in diagnosis.get("smallerHostedAlternatives", []):
+    print("smaller option:", alt)
+```
+
+## API surface
+
+| Method | Endpoint |
+| --- | --- |
+| `find_model(task, gpu, ctx, device_family, commercial, limit)` | `GET /api/agents/find-model` |
+| `artifact(id)` | `GET /api/v1/artifacts/{id}` |
+| `safety(id)` | `GET /api/v1/artifacts/{id}/safety` |
+| `bundle(id)` | `GET /api/artifacts/{id}/bundle` |
+| `passport(id)` | `GET /api/artifacts/{id}/passport` |
+| `resolve(repo_or_url)` | `GET /api/resolve?repo=` |
+| `download_plan(id)` | `GET /api/v1/artifacts/{id}/download-plan` |
+| `lock(id)` | `GET /api/artifacts/{id}/lock` |
+| `doctor(log_text, runtime)` | `POST /api/doctor` |
+| `recipes()` / `recipe(slug)` | `GET /api/recipes[/{slug}]` |
+| `verify_lock(lock_dict, root_dir)` | offline, stdlib only |
+
+## Errors
+
+Any response with status `>= 400` raises `HuggingBayError(status, body)`. The
+server's `error` field is exposed as `.error`; the parsed body is on `.body`.
+On a `503` with a `Retry-After` header the client waits once and retries a
+single time before raising.
+
+## License
+
+MIT

hugging_bay-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugging-bay"
+version = "0.1.0"
+description = "Thin, typed Python client for the Hugging Bay API — verified open-model discovery, safety, and lockfiles."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Hugging Bay" }]
+keywords = ["hugging-bay", "models", "safety", "gguf", "llm", "provenance"]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://huggingbay.xyz"
+Repository = "https://github.com/barneywohl/hugging-bay"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hugging_bay = ["py.typed"]

hugging_bay-0.1.0/setup.cfg

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

hugging_bay-0.1.0/src/hugging_bay/__init__.py

@@ -0,0 +1,8 @@
+"""Hugging Bay Python SDK — a thin, typed client for the Hugging Bay API."""
+
+from .client import Client, HuggingBayError
+from .lock import verify_lock
+
+__version__ = "0.1.0"
+
+__all__ = ["Client", "HuggingBayError", "verify_lock", "__version__"]

hugging_bay-0.1.0/src/hugging_bay/client.py

@@ -0,0 +1,228 @@
+"""Client for the Hugging Bay HTTP API.
+
+The client is deliberately thin: one method per endpoint, no client-side
+business logic, no response reshaping beyond returning parsed JSON. The server
+is the source of truth for verdicts, fits, and identities.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import httpx
+
+__all__ = ["Client", "HuggingBayError"]
+
+_DEFAULT_BASE_URL = "https://huggingbay.xyz"
+
+
+class HuggingBayError(Exception):
+    """Raised when the API returns a >=400 status.
+
+    Attributes:
+        status: HTTP status code.
+        body: parsed JSON body (dict) when available, else the raw text.
+        error: the server's ``error`` field when present, else ``None``.
+    """
+
+    def __init__(self, status: int, body: Any) -> None:
+        self.status = status
+        self.body = body
+        self.error: Optional[str] = None
+        if isinstance(body, dict):
+            value = body.get("error")
+            if isinstance(value, str):
+                self.error = value
+        message = self.error or (body if isinstance(body, str) else "request failed")
+        super().__init__(f"HTTP {status}: {message}")
+
+
+class Client:
+    """Synchronous Hugging Bay API client.
+
+    Args:
+        base_url: API origin. Defaults to the public production host.
+        token: optional bearer token; sent as ``Authorization: Bearer <token>``.
+            The token is never included in ``repr()`` / ``str()`` and never logged.
+        timeout: per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        token: Optional[str] = None,
+        timeout: float = 20,
+        *,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._token = token
+        headers = {"Accept": "application/json", "User-Agent": "hugging-bay-python/0.1.0"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        # `transport` is an injection point for tests (httpx.MockTransport).
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        # Never leak the token.
+        return f"Client(base_url={self.base_url!r}, token={'set' if self._token else None})"
+
+    __str__ = __repr__
+
+    # -- transport ---------------------------------------------------------
+
+    def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                 json: Optional[Dict[str, Any]] = None, _retried: bool = False) -> Any:
+        clean_params = None
+        if params is not None:
+            clean_params = {k: v for k, v in params.items() if v is not None}
+        resp = self._http.request(method, path, params=clean_params, json=json)
+
+        # Honor Retry-After exactly once on a 503.
+        if resp.status_code == 503 and not _retried:
+            retry_after = resp.headers.get("Retry-After")
+            delay = _parse_retry_after(retry_after)
+            if delay is not None:
+                time.sleep(delay)
+                return self._request(method, path, params=params, json=json, _retried=True)
+
+        if resp.status_code >= 400:
+            raise HuggingBayError(resp.status_code, _safe_body(resp))
+        return _safe_body(resp)
+
+    def _get(self, path: str, **params: Any) -> Any:
+        return self._request("GET", path, params=params)
+
+    # -- endpoints ---------------------------------------------------------
+
+    def find_model(
+        self,
+        task: str,
+        gpu: Optional[str] = None,
+        ctx: Optional[int] = None,
+        device_family: Optional[str] = None,
+        commercial: bool = False,
+        limit: int = 3,
+    ) -> Dict[str, Any]:
+        """GET /api/agents/find-model — verified recommendation for a task/rig."""
+        return self._get(
+            "/api/agents/find-model",
+            task=task,
+            gpu=gpu,
+            ctx=ctx,
+            deviceFamily=device_family,
+            commercial="true" if commercial else None,
+            limit=limit,
+        )
+
+    def artifact(self, id: str) -> Dict[str, Any]:
+        """GET /api/v1/artifacts/{id} — one public artifact."""
+        return self._get(f"/api/v1/artifacts/{id}")
+
+    def safety(self, id: str) -> Dict[str, Any]:
+        """GET /api/v1/artifacts/{id}/safety — per-artifact safe-to-run verdict."""
+        return self._get(f"/api/v1/artifacts/{id}/safety")
+
+    def bundle(self, id: str) -> Dict[str, Any]:
+        """GET /api/artifacts/{id}/bundle — trust bundle state."""
+        return self._get(f"/api/artifacts/{id}/bundle")
+
+    def passport(self, id: str) -> Dict[str, Any]:
+        """GET /api/artifacts/{id}/passport — artifact identity passport."""
+        return self._get(f"/api/artifacts/{id}/passport")
+
+    def resolve(self, repo_or_url: str) -> Dict[str, Any]:
+        """GET /api/resolve?repo= — resolve an owner/name or upstream URL."""
+        return self._get("/api/resolve", repo=repo_or_url)
+
+    def download_plan(self, id: str) -> Dict[str, Any]:
+        """GET /api/v1/artifacts/{id}/download-plan — hosted download plan + hashes."""
+        return self._get(f"/api/v1/artifacts/{id}/download-plan")
+
+    def download_completion(
+        self,
+        id: str,
+        path: str,
+        *,
+        sha256: str,
+        size_bytes: int,
+        completion_token: str,
+    ) -> Dict[str, Any]:
+        """POST /api/download-completions/{id}/{path} — attest a completed pull.
+
+        Call ONLY after the file has been downloaded in full and its SHA-256
+        recomputed locally to equal the download-plan's file.sha256.
+        ``completion_token`` is the single-use capability from the
+        ``X-Hugging-Bay-Completion-Token`` header of the download redirect;
+        without it the pull is not counted. Redirect issuance is a download
+        initiation, not a completed pull, and probes never count.
+        """
+        encoded_path = "/".join(quote(part, safe="") for part in str(path).split("/"))
+        return self._request(
+            "POST",
+            f"/api/download-completions/{id}/{encoded_path}",
+            json={
+                "sha256": sha256,
+                "sizeBytes": int(size_bytes),
+                "completionToken": completion_token,
+            },
+        )
+
+    def lock(self, id: str) -> Dict[str, Any]:
+        """GET /api/artifacts/{id}/lock — a bay.lock document (dict)."""
+        return self._get(f"/api/artifacts/{id}/lock")
+
+    def doctor(self, log_text: str, runtime: Optional[str] = None) -> Dict[str, Any]:
+        """POST /api/doctor — diagnose a failing run from its log output."""
+        body: Dict[str, Any] = {"log": log_text}
+        if runtime is not None:
+            body["runner"] = runtime
+        return self._request("POST", "/api/doctor", json=body)
+
+    def recipes(self) -> Dict[str, Any]:
+        """GET /api/recipes — index of locked task recipes."""
+        return self._get("/api/recipes")
+
+    def recipe(self, slug: str) -> Dict[str, Any]:
+        """GET /api/recipes/{slug} — one locked recipe by slug."""
+        return self._get(f"/api/recipes/{slug}")
+
+
+def _safe_body(resp: httpx.Response) -> Any:
+    try:
+        return resp.json()
+    except ValueError:
+        return resp.text
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """Parse a Retry-After header. Only the delta-seconds form is honored;
+    an HTTP-date form is ignored (returns None) to avoid clock-skew guessing."""
+    if not value:
+        return None
+    try:
+        seconds = float(value.strip())
+    except (TypeError, ValueError):
+        return None
+    if seconds < 0:
+        return None
+    # Guard against a hostile/huge value blocking the caller indefinitely.
+    return min(seconds, 60.0)