{"schemaVersion":"hugging-bay.agent-cookbook.v1","title":"Hugging Bay Agent Cookbook","intro":"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":[{"id":"pick-a-safe-model-for-a-task","title":"Pick a safe, licensed 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":[{"do":"Call the golden-path finder with the task, a commercial-use filter, and the target GPU.","request":{"method":"GET","url":"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."},{"do":"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."}],"curl":"curl -s 'https://huggingbay.xyz/api/agents/find-model?task=summarization&commercial=1&gpu=rtx4090-24&limit=3'","mcpToolCalls":[{"tool":"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."]},{"id":"will-it-run-on-this-gpu","title":"Check whether a model will run on a given 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":[{"do":"Ask the fit endpoint whether the model fits at the desired context.","request":{"method":"GET","url":"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."},{"do":"If it does not fit at full precision, list quantizations to find a smaller variant.","request":{"method":"GET","url":"https://huggingbay.xyz/api/artifacts/{artifactId}/quantizations"},"expect":"Available quantized builds (e.g. Q4_K_M) with their sizes."},{"do":"Pull a concrete deployment plan for the chosen GPU and context.","request":{"method":"GET","url":"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."}],"curl":"curl -s 'https://huggingbay.xyz/api/agents/deployment-plan?id={artifactId}&gpu=rtx4090-24&ctx=8192'","mcpToolCalls":[{"tool":"will_it_fit","args":{"id":"{artifactId}","gpu":"rtx4090-24","ctx":8192}},{"tool":"get_quantizations","args":{"id":"{artifactId}"}},{"tool":"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."]},{"id":"verify-a-file-you-downloaded-anywhere","title":"Verify a file you downloaded from 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":[{"do":"Hash the file locally.","expect":"A 64-character hex sha256 digest of the exact bytes on disk."},{"do":"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.","request":{"method":"GET","url":"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."}],"curl":"shasum -a 256 model.gguf | awk '{print $1}' | xargs -I{} curl -s 'https://huggingbay.xyz/api/safety?sha256={}'","mcpToolCalls":[{"tool":"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."]},{"id":"escape-a-gated-model","title":"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":[{"do":"Ask for alternatives to the gated artifact.","request":{"method":"GET","url":"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."},{"do":"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."}],"curl":"curl -s 'https://huggingbay.xyz/api/artifacts/{artifactId}/alternatives'","mcpToolCalls":[{"tool":"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."]},{"id":"audit-a-model-before-recommending","title":"Audit a model before recommending it","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":[{"do":"Get the one-call report — the consolidated view of license, safety, fit, and metadata.","request":{"method":"GET","url":"https://huggingbay.xyz/api/v1/artifacts/{artifactId}/report"},"expect":"A single JSON report summarizing everything Hugging Bay knows about the artifact."},{"do":"Inspect the binary to see what the weights actually are (tensor shapes, dtypes, format).","request":{"method":"GET","url":"https://huggingbay.xyz/api/artifacts/{artifactId}/inspection"},"expect":"A structural inspection of the model files, independent of the card's claims."},{"do":"Run card-doctor to grade the model card for missing or misleading metadata.","request":{"method":"GET","url":"https://huggingbay.xyz/api/artifacts/{artifactId}/card-doctor"},"expect":"A quality assessment of the model card with specific gaps called out."}],"curl":"curl -s 'https://huggingbay.xyz/api/v1/artifacts/{artifactId}/report'","mcpToolCalls":[{"tool":"get_model_report","args":{"id":"{artifactId}"}},{"tool":"inspect_model_binary","args":{"id":"{artifactId}"}},{"tool":"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."]},{"id":"trace-provenance-and-license","title":"Trace provenance and license lineage","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":[{"do":"Pull the family tree to see base models, fine-tunes, and quant siblings.","request":{"method":"GET","url":"https://huggingbay.xyz/api/artifacts/{artifactId}/family"},"expect":"The lineage graph: parents, children, and quant variants of the artifact."},{"do":"Read the license off the one-call report for the artifact and its base, to establish license lineage.","request":{"method":"GET","url":"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."},{"do":"Diff the manifest against a sibling or the base to see exactly which files/tensors changed.","request":{"method":"GET","url":"https://huggingbay.xyz/api/artifacts/{artifactId}/manifest-diff?against={otherArtifactId}"},"expect":"A file- and tensor-level diff between the two manifests."}],"curl":"curl -s 'https://huggingbay.xyz/api/artifacts/{artifactId}/manifest-diff?against={otherArtifactId}'","mcpToolCalls":[{"tool":"get_model_family","args":{"id":"{artifactId}"}},{"tool":"get_model_report","args":{"id":"{artifactId}"}},{"tool":"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."]},{"id":"use-hb-as-hf-endpoint","title":"Use Hugging Bay as a drop-in Hugging Face 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":[{"do":"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."},{"do":"Optionally confirm a repo resolves by hitting the model-info route directly.","request":{"method":"GET","url":"https://huggingbay.xyz/api/models/{owner}/{name}"},"expect":"Model metadata for the repo, mirroring the Hugging Face model-info shape."},{"do":"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."}],"curl":"HF_ENDPOINT=https://huggingbay.xyz huggingface-cli download {owner}/{name}","mcpToolCalls":[{"tool":"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."]},{"id":"wire-hb-into-your-agent-via-mcp","title":"Wire Hugging Bay 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":[{"do":"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\"}}}."},{"do":"List the available tools over JSON-RPC to confirm the connection.","request":{"method":"POST","url":"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."},{"do":"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}}}","request":{"method":"POST","url":"https://huggingbay.xyz/api/mcp"},"expect":"The tool result for find_and_verify_model_for_task, same shape as the REST golden path."}],"curl":"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}}}'","mcpToolCalls":[{"tool":"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."]}]}