# Hugging Bay Agent Cookbook

_Schema: `hugging-bay.agent-cookbook.v1`_

Worked, copy-paste-runnable recipes for the golden paths through Hugging Bay. Each recipe is written so an AI assistant can read it once and reproduce the workflow for a user. Every URL and MCP tool name maps to a live endpoint. Placeholders in braces are yours to fill: {artifactId} is a Hugging Bay artifact id (e.g. from a find-model result or a model page), {sha256} is a 64-hex-char file digest, {owner}/{name} is a Hugging Face-style repo path, and {gpuId} is one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.

## Recipes

### 1. Pick a safe, licensed model for a task

**Recipe id:** `pick-a-safe-model-for-a-task`

**Problem.** A user asks for a model to do some task (e.g. summarization) on their own hardware, and it must be commercially usable and not carry a known-bad safety verdict.

**Steps.**

1. Call the golden-path finder with the task, a commercial-use filter, and the target GPU.
  - `GET https://huggingbay.xyz/api/agents/find-model?task=summarization&commercial=1&gpu=rtx4090-24&limit=3`
  - Expect: A ranked list of composite reports plus a bestPick. Each entry already folds in license, safety, and fit signals — you do not need to re-derive them.
2. Recommend bestPick (or the top entry) and surface its license and safety verdict verbatim to the user.
  - Expect: The user gets one clear recommendation with the receipts attached.

**Copy-paste.**

```bash
curl -s 'https://huggingbay.xyz/api/agents/find-model?task=summarization&commercial=1&gpu=rtx4090-24&limit=3'
```

**MCP tool calls.**

- `find_and_verify_model_for_task` — args `{"task":"summarization","commercial":true,"gpu":"rtx4090-24","limit":3}`

**Notes.**

- commercial=1 filters to models whose license permits commercial use.
- gpu must be one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.
- Prefer the bestPick field; the full array is there if you want to explain the ranking.

### 2. Check whether a model will run on a given GPU

**Recipe id:** `will-it-run-on-this-gpu`

**Problem.** The user has a specific card (say an RTX 4090, 24 GB) and a context length in mind, and wants to know if a model fits before downloading tens of gigabytes.

**Steps.**

1. Ask the fit endpoint whether the model fits at the desired context.
  - `GET https://huggingbay.xyz/api/v1/artifacts/{artifactId}/fit?gpu=rtx4090-24&ctx=8192`
  - Expect: A fit verdict for the GPU/ctx pair, including VRAM headroom.
2. If it does not fit at full precision, list quantizations to find a smaller variant.
  - `GET https://huggingbay.xyz/api/artifacts/{artifactId}/quantizations`
  - Expect: Available quantized builds (e.g. Q4_K_M) with their sizes.
3. Pull a concrete deployment plan for the chosen GPU and context.
  - `GET https://huggingbay.xyz/api/agents/deployment-plan?id={artifactId}&gpu=rtx4090-24&ctx=8192`
  - Expect: A fit summary, a recommended variant, and ordered setup steps you can hand to the user.

**Copy-paste.**

```bash
curl -s 'https://huggingbay.xyz/api/agents/deployment-plan?id={artifactId}&gpu=rtx4090-24&ctx=8192'
```

**MCP tool calls.**

- `will_it_fit` — args `{"id":"{artifactId}","gpu":"rtx4090-24","ctx":8192}`
- `get_quantizations` — args `{"id":"{artifactId}"}`
- `plan_local_deployment` — args `{"id":"{artifactId}","gpu":"rtx4090-24","ctx":8192}`

**Notes.**

- Placeholders in braces are yours to fill: {artifactId} is a Hugging Bay artifact id (e.g. from a find-model result or a model page), {sha256} is a 64-hex-char file digest, {owner}/{name} is a Hugging Face-style repo path, and {gpuId} is one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.
- ctx is the context window in tokens; larger ctx needs more VRAM for the KV cache.
- The deployment-plan endpoint already picks a variant that fits, so you rarely need to reason about quant math yourself.

### 3. Verify a file you downloaded from anywhere

**Recipe id:** `verify-a-file-you-downloaded-anywhere`

**Problem.** The user already has a model file on disk — from Hugging Face, a mirror, a Discord link, wherever — and wants to know if Hugging Bay has a safety verdict on those exact bytes.

**Steps.**

1. Hash the file locally.
  - Expect: A 64-character hex sha256 digest of the exact bytes on disk.
2. Look the digest up by hash — no artifact id needed. This is content-addressed, so it matches the bytes regardless of where they came from.
  - `GET https://huggingbay.xyz/api/safety?sha256={sha256}`
  - Expect: A safety verdict for those exact bytes if Hugging Bay has seen them, or a not-found so you can tell the user it is unverified.

**Copy-paste.**

```bash
shasum -a 256 model.gguf | awk '{print $1}' | xargs -I{} curl -s 'https://huggingbay.xyz/api/safety?sha256={}'
```

**MCP tool calls.**

- `check_artifact_safety` — args `{"sha256":"{sha256}"}`

**Notes.**

- Placeholders in braces are yours to fill: {artifactId} is a Hugging Bay artifact id (e.g. from a find-model result or a model page), {sha256} is a 64-hex-char file digest, {owner}/{name} is a Hugging Face-style repo path, and {gpuId} is one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.
- You can also look up by repo instead of hash: https://huggingbay.xyz/api/safety?repo={owner}/{name}.
- A not-found is not a pass — it just means Hugging Bay has not scanned those bytes.

### 4. Escape a gated model

**Recipe id:** `escape-a-gated-model`

**Problem.** The model the user wants is gated (requires accepting terms or a token), which blocks automated download. They want an ungated, equivalent model instead.

**Steps.**

1. Ask for alternatives to the gated artifact.
  - `GET https://huggingbay.xyz/api/artifacts/{artifactId}/alternatives`
  - Expect: A list of related models, including ungated ones, ranked by similarity so you can swap in a drop-in replacement.
2. Pick the closest ungated alternative and re-run whatever fit/safety checks the task needs on it.
  - Expect: An unblocked path forward with a comparable model.

**Copy-paste.**

```bash
curl -s 'https://huggingbay.xyz/api/artifacts/{artifactId}/alternatives'
```

**MCP tool calls.**

- `find_ungated_alternatives` — args `{"id":"{artifactId}"}`

**Notes.**

- Placeholders in braces are yours to fill: {artifactId} is a Hugging Bay artifact id (e.g. from a find-model result or a model page), {sha256} is a 64-hex-char file digest, {owner}/{name} is a Hugging Face-style repo path, and {gpuId} is one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.
- Alternatives are ranked; the first ungated entry is usually the best swap.

### 5. Audit a model before recommending it

**Recipe id:** `audit-a-model-before-recommending`

**Problem.** Before you put your name on a recommendation, you want the full picture: the one-call report, what is actually inside the binary, and whether the model card is trustworthy.

**Steps.**

1. Get the one-call report — the consolidated view of license, safety, fit, and metadata.
  - `GET https://huggingbay.xyz/api/v1/artifacts/{artifactId}/report`
  - Expect: A single JSON report summarizing everything Hugging Bay knows about the artifact.
2. Inspect the binary to see what the weights actually are (tensor shapes, dtypes, format).
  - `GET https://huggingbay.xyz/api/artifacts/{artifactId}/inspection`
  - Expect: A structural inspection of the model files, independent of the card's claims.
3. Run card-doctor to grade the model card for missing or misleading metadata.
  - `GET https://huggingbay.xyz/api/artifacts/{artifactId}/card-doctor`
  - Expect: A quality assessment of the model card with specific gaps called out.

**Copy-paste.**

```bash
curl -s 'https://huggingbay.xyz/api/v1/artifacts/{artifactId}/report'
```

**MCP tool calls.**

- `get_model_report` — args `{"id":"{artifactId}"}`
- `inspect_model_binary` — args `{"id":"{artifactId}"}`
- `get_card_doctor` — args `{"id":"{artifactId}"}`

**Notes.**

- Placeholders in braces are yours to fill: {artifactId} is a Hugging Bay artifact id (e.g. from a find-model result or a model page), {sha256} is a 64-hex-char file digest, {owner}/{name} is a Hugging Face-style repo path, and {gpuId} is one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.
- The report is the fast path; inspection and card-doctor are for when you need to defend the recommendation.

### 6. Trace provenance and license lineage

**Recipe id:** `trace-provenance-and-license`

**Problem.** A model is a fine-tune or a re-quant of something else, and the user needs to know where it came from and which license actually governs it before they ship on top of it.

**Steps.**

1. Pull the family tree to see base models, fine-tunes, and quant siblings.
  - `GET https://huggingbay.xyz/api/artifacts/{artifactId}/family`
  - Expect: The lineage graph: parents, children, and quant variants of the artifact.
2. Read the license off the one-call report for the artifact and its base, to establish license lineage.
  - `GET https://huggingbay.xyz/api/v1/artifacts/{artifactId}/report`
  - Expect: The effective license, which you compare against the base model's license from its own report.
3. Diff the manifest against a sibling or the base to see exactly which files/tensors changed.
  - `GET https://huggingbay.xyz/api/artifacts/{artifactId}/manifest-diff?against={otherArtifactId}`
  - Expect: A file- and tensor-level diff between the two manifests.

**Copy-paste.**

```bash
curl -s 'https://huggingbay.xyz/api/artifacts/{artifactId}/manifest-diff?against={otherArtifactId}'
```

**MCP tool calls.**

- `get_model_family` — args `{"id":"{artifactId}"}`
- `get_model_report` — args `{"id":"{artifactId}"}`
- `diff_manifests` — args `{"id":"{artifactId}","against":"{otherArtifactId}"}`

**Notes.**

- Placeholders in braces are yours to fill: {artifactId} is a Hugging Bay artifact id (e.g. from a find-model result or a model page), {sha256} is a 64-hex-char file digest, {owner}/{name} is a Hugging Face-style repo path, and {gpuId} is one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.
- {otherArtifactId} is the base model or sibling you are comparing against.
- License lineage matters: a permissive fine-tune of a restrictively-licensed base does not launder the base license.

### 7. Use Hugging Bay as a drop-in Hugging Face endpoint

**Recipe id:** `use-hb-as-hf-endpoint`

**Problem.** The user has existing code or CLI habits built around Hugging Face and wants the exact same commands to pull hash-verified bytes through Hugging Bay with a one-line change.

**Steps.**

1. Point the Hugging Face tooling at Hugging Bay by exporting HF_ENDPOINT. No other code changes.
  - Expect: huggingface-cli, huggingface_hub, and from_pretrained now resolve through Hugging Bay.
2. Optionally confirm a repo resolves by hitting the model-info route directly.
  - `GET https://huggingbay.xyz/api/models/{owner}/{name}`
  - Expect: Model metadata for the repo, mirroring the Hugging Face model-info shape.
3. Download as usual; file resolves 302 to hash-verified hosted bytes.
  - Expect: The same files you would have gotten from Hugging Face, but content-verified.

**Copy-paste.**

```bash
HF_ENDPOINT=https://huggingbay.xyz huggingface-cli download {owner}/{name}
```

**MCP tool calls.**

- `get_model_report` — args `{"id":"{artifactId}"}`

**Notes.**

- Placeholders in braces are yours to fill: {artifactId} is a Hugging Bay artifact id (e.g. from a find-model result or a model page), {sha256} is a 64-hex-char file digest, {owner}/{name} is a Hugging Face-style repo path, and {gpuId} is one of: rtx4090-24, rtx3090-24, rtx3060-12, t4-16, a100-80, h100-80, mac-m3-max-64.
- File bytes stream from https://huggingbay.xyz/{owner}/{name}/resolve/{rev}/{path} (302 to hosted, hash-verified bytes).
- Only files whose hosted/downloadable flag is true actually stream from Hugging Bay; others 404 rather than lie.

### 8. Wire Hugging Bay into your agent via MCP

**Recipe id:** `wire-hb-into-your-agent-via-mcp`

**Problem.** You are building an agent and want it to call Hugging Bay's model-selection and safety tools natively, instead of hand-rolling HTTP calls.

**Steps.**

1. Add the Hugging Bay MCP server to your agent's config.
  - Expect: Config JSON: {"mcpServers":{"hugging-bay":{"type":"http","url":"https://huggingbay.xyz/api/mcp"}}}.
2. List the available tools over JSON-RPC to confirm the connection.
  - `POST https://huggingbay.xyz/api/mcp`
  - Expect: A tools list including find_and_verify_model_for_task, plan_local_deployment, get_model_report, will_it_fit, check_artifact_safety, get_quantizations, find_ungated_alternatives, get_model_family, get_card_doctor, inspect_model_binary, diff_manifests, get_integration_snippets.
3. Call a tool. Example JSON-RPC tools/call body: {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_and_verify_model_for_task","arguments":{"task":"summarization","commercial":true,"gpu":"rtx4090-24","limit":3}}}
  - `POST https://huggingbay.xyz/api/mcp`
  - Expect: The tool result for find_and_verify_model_for_task, same shape as the REST golden path.

**Copy-paste.**

```bash
curl -s -X POST 'https://huggingbay.xyz/api/mcp' -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_and_verify_model_for_task","arguments":{"task":"summarization","commercial":true,"gpu":"rtx4090-24","limit":3}}}'
```

**MCP tool calls.**

- `find_and_verify_model_for_task` — args `{"task":"summarization","commercial":true,"gpu":"rtx4090-24","limit":3}`

**Notes.**

- The endpoint speaks JSON-RPC 2.0. Use method 'tools/list' to enumerate and 'tools/call' to invoke.
- Available tools: find_and_verify_model_for_task, plan_local_deployment, get_model_report, will_it_fit, check_artifact_safety, get_quantizations, find_ungated_alternatives, get_model_family, get_card_doctor, inspect_model_binary, diff_manifests, get_integration_snippets.
- The same tools back the REST recipes above, so anything in this cookbook is reachable from an agent.