# Hugging Bay Python SDK

The Python SDK is a zero-dependency single-file client for developers, notebooks, local agents, OpenClaw/Hermes-style tools, and crawler-safe automation.

## Install

```sh
curl -fsSL https://huggingbay.xyz/sdk/hugging_bay.py -o hugging_bay.py
python hugging_bay.py health
```

Optional environment variables:

```sh
export HUGGING_BAY_API="https://huggingbay.xyz"
export HUGGING_BAY_TOKEN="hb-reader-or-publisher-token"
```

## Use As A Library

```python
from hugging_bay import HuggingBayClient

client = HuggingBayClient()
results = client.search("small embedding model", limit=5, semantic=True)
for row in results["rows"]:
    print(row["repo"], row["license"], row["hostingStatus"])

bundle = client.artifact_bundle(results["rows"][0]["id"])
print(bundle["metadata"]["hosting"])

versions = client.artifact_versions(results["rows"][0]["id"])
print(versions["currentVersion"], versions["rows"][0]["releasedAt"])

plan = client.download_plan(results["rows"][0]["id"])
file = plan["files"][0]
client.download_file(
    results["rows"][0]["id"],
    file["path"],
    f"./models/{file['path']}",
    sha256=file["sha256"],
    size_bytes=file["sizeBytes"],
)
```

## Use As A CLI

```sh
python hugging_bay.py search "rag embedding" --semantic --limit 5
python hugging_bay.py resolve https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2
python hugging_bay.py artifact hf-model-sentence-transformers-all-minilm-l6-v2
python hugging_bay.py versions hf-model-sentence-transformers-all-minilm-l6-v2
python hugging_bay.py downloads --pack hosted-local-model-files --limit 20
python hugging_bay.py ranking hosted-small-local-model-files --limit 25
python hugging_bay.py trending --window 7d --limit 25
```

## Agent Safety Rules

- Search and inspect metadata before downloading.
- Treat external rows as upstream metadata only.
- Use `artifact_versions()` to check freshness, source provenance, and manifest evidence before citing a release.
- Use `download_plan()` or `downloadable_files()` before automated downloads.
- Use `download_file()` to stream, verify SHA-256, attest completion, and publish the local file atomically without forwarding the API bearer to GCS.
- Do not try to bypass gated, private, or restricted upstream repositories.
- Submit mirror/source requests only for legal public artifacts.