Agent Cookbook

Eight worked recipes AI agents can reproduce: pick a safe model, check GPU fit, verify any downloaded file, escape gated models, audit before recommending, trace provenance, use the HF_ENDPOINT drop-in, and wire Hugging Bay into MCP.

Hugging Bay is intentionally crawlable for search engines, answer engines, user-requested AI fetches, frontier AI assistants, and open-source agents. Public pages describe verified open-source AI artifact metadata, provenance, licenses, community trust signals, and selective hosted mirrors with hashes. Hugging Bay does not bypass gated or restricted upstream access controls.

Machine-readable entrypoints: robots.txt, AI search guidance, well-known AI search JSON, AI citation packs, well-known AI citation JSON, llms.txt, llms-full.txt, AI crawler policy, AI bot allowlist, answer-engine manifest, agent manifest, OpenAPI, and indexing status.

Pick a safe, licensed model for a task

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.

  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
  2. Recommend bestPick (or the top entry) and surface its license and safety verdict verbatim to the user.
curl -s 'https://huggingbay.xyz/api/agents/find-model?task=summarization&commercial=1&gpu=rtx4090-24&limit=3'

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.

Check whether a model will run on a given GPU

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.

  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
  2. If it does not fit at full precision, list quantizations to find a smaller variant. — GET https://huggingbay.xyz/api/artifacts/{artifactId}/quantizations
  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
curl -s 'https://huggingbay.xyz/api/agents/deployment-plan?id={artifactId}&gpu=rtx4090-24&ctx=8192'

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.

Verify a file you downloaded from anywhere

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.

  1. Hash the file locally.
  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}
shasum -a 256 model.gguf | awk '{print $1}' | xargs -I{} curl -s 'https://huggingbay.xyz/api/safety?sha256={}'

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.

Escape a gated model

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

  1. Ask for alternatives to the gated artifact. — GET https://huggingbay.xyz/api/artifacts/{artifactId}/alternatives
  2. Pick the closest ungated alternative and re-run whatever fit/safety checks the task needs on it.
curl -s 'https://huggingbay.xyz/api/artifacts/{artifactId}/alternatives'

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.

Audit a model before recommending it

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.

  1. Get the one-call report — the consolidated view of license, safety, fit, and metadata. — GET https://huggingbay.xyz/api/v1/artifacts/{artifactId}/report
  2. Inspect the binary to see what the weights actually are (tensor shapes, dtypes, format). — GET https://huggingbay.xyz/api/artifacts/{artifactId}/inspection
  3. Run card-doctor to grade the model card for missing or misleading metadata. — GET https://huggingbay.xyz/api/artifacts/{artifactId}/card-doctor
curl -s 'https://huggingbay.xyz/api/v1/artifacts/{artifactId}/report'

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.

Trace provenance and license lineage

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.

  1. Pull the family tree to see base models, fine-tunes, and quant siblings. — GET https://huggingbay.xyz/api/artifacts/{artifactId}/family
  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
  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}
curl -s 'https://huggingbay.xyz/api/artifacts/{artifactId}/manifest-diff?against={otherArtifactId}'

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.

Use Hugging Bay as a drop-in Hugging Face endpoint

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.

  1. Point the Hugging Face tooling at Hugging Bay by exporting HF_ENDPOINT. No other code changes.
  2. Optionally confirm a repo resolves by hitting the model-info route directly. — GET https://huggingbay.xyz/api/models/{owner}/{name}
  3. Download as usual; file resolves 302 to hash-verified hosted bytes.
HF_ENDPOINT=https://huggingbay.xyz huggingface-cli download {owner}/{name}

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.

Wire Hugging Bay into your agent via MCP

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.

  1. Add the Hugging Bay MCP server to your agent's config.
  2. List the available tools over JSON-RPC to confirm the connection. — POST https://huggingbay.xyz/api/mcp
  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
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}}}'

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.

Markdown version · JSON version