# Bay Run

> Bay Run is the discover -> prove -> serve loop for small open specialist models. An
> agent (or its human) with a narrow, high-volume task — embeddings, reranking,
> classification, extraction, routing, guardrails — uses Bay Run to FIND the specialist
> model that wins on THEIR data and SERVE it per-use, cheaper than a frontier API or a
> reserved GPU. OpenAI-compatible AND MCP-native, with a LIVE remote MCP endpoint.
> CPU-served, scale-to-zero, no packaging step: any Hugging Face embedding / reranker /
> small-generative id works on demand. Served from a content-addressed, quarantine-gated
> mirror (sha256 integrity via content addressing; flagged models hard-blocked). Signed
> manifests are a first-class moat feature and provenance is tracked per artifact; full
> serve-time signature verification is in progress (see /api/verify), so mirror bytes are
> integrity-checked but not yet cryptographically signature-verified at serve time.

## You are reading the Bay Run service root
This /llms.txt is served directly by the LIVE Bay Run service at https://run.huggingbay.xyz .
Everything below exists and works right now.

## Remote MCP endpoint (LIVE)
- Streamable-HTTP MCP: https://run.huggingbay.xyz/mcp/  (trailing slash; bare /mcp also works over https)
- Zero-credential live proof: GET https://run.huggingbay.xyz/v1/try
- Native A2A JSON-RPC trial: POST https://run.huggingbay.xyz/a2a
- Auth: `Authorization: Bearer <BAY_RUN_TOKEN>`. No token? A 401 carries a
  `WWW-Authenticate` bearer challenge plus token-mint and OAuth protected-resource links.
  Autonomous quickstart: POST JSON `{"grant_type":"client_credentials"}` to
  https://run.huggingbay.xyz/oauth/token; the response is a one-hour, rate-limited `mcp:demo` bearer.
  Human-operated clients can use the same OAuth endpoint at https://run.huggingbay.xyz/oauth/token .
- Public server card (NO auth, enumerates all 21 tools for registry scanners): https://run.huggingbay.xyz/.well-known/mcp/server-card.json
- A2A agent card (NO auth): https://run.huggingbay.xyz/.well-known/agent-card.json

## The 21 MCP tools
- try_bay_run() — PUBLIC fixed activation proof; no arguments, no model work, always returns 42.
- find_specialist_for_task(task, my_examples) — ONE call: discover -> eval -> serve
  pointer. Your default entry point when you HAVE labeled examples.
- request_specialist(task, examples?) — serve-or-capture: returns a serve pointer if a
  specialist exists, else RECORDS your demand and returns {status:"recorded"}. Never a dead end.
- route(task_hint, kind, ...) — RUNTIME auto-router: no examples, no model name — Bay Run
  infers the task family and prefers its curated warm small specialist, while retaining the
  catalog candidate for evaluation. Also reachable as model="auto" on embed/rerank/classify.
- discover_models(query, kind, ...) — search a 147K-model catalog for candidate
  specialist ids (candidates, not proven).
- eval_models(task, models, dataset) — bake candidates off on YOUR labeled data; returns
  the winner (a public leaderboard rank does NOT predict your-domain fit).
- embed(model, input) — OpenAI-compatible embeddings for any HF embedding id, on demand.
- rerank(model, query, documents, top_n) — Cohere/Jina-shaped reranking, any HF
  cross-encoder.
- classify(model, input, candidate_labels?) — text-classification specialist:
  guardrail/moderation/sentiment/intent (fixed-label) OR zero-shot via an NLI model +
  candidate_labels. Returns {labels:[{label,score}]}. model="auto" supported.
- extract(model, content, schema?) — messy HTML/text -> schema-guided structured JSON from
  a small CPU-served generative specialist. BEST-EFFORT: always check `json_valid` before
  trusting `data`.
- memory_context(updates?, namespace="default", delete_keys?, max_bytes?) — FAST one-call
  durable working context. Load with no args, or atomically update/delete and receive a
  bounded refreshed snapshot. Refreshable OAuth identity follows the agent across harnesses.
- speed_test() — fixed bounded benchmark over warm embedding, reranking, and classification;
  returns per-stage model/latency/cold-load plus total server wall time. Network/TLS excluded.
- remember(namespace, key, value, ttl?) — DURABLE cross-call agent memory (upsert). Scoped to
  YOUR token principal so no other caller can read it; Cloud SQL-backed (survives restart/scale).
- recall(namespace, key?) — read back memory: one key, or list the namespace. Your principal only.
- forget(namespace, key?) — delete one key or a whole namespace (your principal only).
- calculate(expression) — exact instant math (safe whitelist parser, no eval). +-*/// % **,
  parentheses, sqrt/log/sin/exp/floor/factorial, pi/e.
- validate_json(data, schema?) — parse-check a JSON string and/or validate against a JSON Schema;
  returns {valid, errors[]}.
- resolve_link(url) — is a URL alive? If dead AND Hugging Bay has the model mirrored, returns the
  mirrored serve pointer (UNIQUE to us). SSRF-safe.
- parse_pdf(url?, pdf_base64?, start_page?, max_pages?, max_chars?) — FAST native PDFium text
  extraction with no model load. Returns page-aligned text plus `rag_documents` ready for RAG;
  scanned/image-only PDFs are explicitly flagged `needs_ocr:true`. Public URL fetches are SSRF-safe
  and byte/page/character/time/concurrency bounded.
- summarize(text, max_sentences?, ratio?, query?) — FAST extractive summarization: returns the most
  central (optionally query-relevant) sentences verbatim, in order. No generative model. Reuses the
  warm embedder.
- rag_search(query, documents, top_k?, rerank?, answer?) — FAST turnkey retrieve: embed + cosine
  top-N + optional warm cross-encoder rerank -> top passages with scores + indices. Retrieval only
  by default (answer=true = slow generative lane). Reuses the warm embedder + reranker.

## REST / OpenAI-compatible endpoints (LIVE, bearer-protected)
- Base URL: https://run.huggingbay.xyz
- POST /v1/embeddings — OpenAI-compatible embeddings, any HF model, load-on-demand.
  Pass model="auto" (+ optional task_hint) to let the runtime router pick the specialist;
  the response carries x_bay_run_routed_model / routing{...} + an x-bay-run-routed-model header.
- POST /v1/rerank — Cohere/Jina-shaped reranking, any HF cross-encoder (model="auto" supported)
- POST /v1/chat/completions — CPU-served generative (schema-guided JSON extraction; model="auto" supported)
- POST /v1/classify — text-classification (guardrail/moderation/sentiment/intent), or zero-shot
  via candidate_labels + an NLI model. model="auto" supported.
- POST /v1/request_specialist — serve-or-capture: serve pointer if a specialist exists, else
  records the demand and returns {status:"recorded"}.
- POST /v1/route — RUNTIME auto-router: pick the best specialist for a job you can't name a
  model for; optional serve=True routes AND serves in one call. Heuristic + honest.
- POST /v1/discover — task -> ranked candidate specialist model ids
- POST /v1/eval — bake off candidates on your labeled set -> scorecard + winner
- POST /v1/find_specialist — REST twin of the find_specialist_for_task tool
- GET  /v1/models — curated catalog + provenance flag
- POST /v1/memory — remember (upsert a durable key->value for your principal); GET /v1/memory
  (recall one key or list a namespace); DELETE /v1/memory (forget). Namespaced + principal-scoped.
- POST /v1/calculate — safe math eval (REST twin of calculate)
- POST /v1/validate_json — JSON parse + optional JSON-Schema validation (REST twin of validate_json)
- POST /v1/resolve_link — URL liveness + Hugging Bay mirror fallback (REST twin of resolve_link)
- POST /v1/pdf/extract — FAST native PDFium extraction from a public URL or small base64 PDF;
  returns page text + RAG-ready documents (REST twin of parse_pdf)
- POST /v1/summarize — FAST extractive summarization (warm embedder; REST twin of summarize)
- POST /v1/rag — FAST turnkey retrieve (warm embedder + reranker; REST twin of rag_search)

## How to get a token / pay
Autonomous agents should POST `{"grant_type":"client_credentials"}` to
https://run.huggingbay.xyz/oauth/token, send the returned access token as `Authorization: Bearer
<token>`, and persist the refresh token to retain their private memory principal. No client
secret or browser is required. Human-operated clients can use the same endpoint at
https://run.huggingbay.xyz/oauth/token.

## Two Hugging Bay MCPs — don't confuse them
- Catalog MCP (io.github.barneywohl/hugging-bay) — RECOMMEND / VERIFY: browse and
  provenance-verify models in the Hugging Bay catalog.
- Bay Run (io.github.barneywohl/bay-run) — PROVE-on-your-data + SERVE: THIS service. Eval
  candidates on your labeled data, then serve the winner OpenAI-compatibly.

## Full reference
- https://run.huggingbay.xyz/llms-full.txt — full tool schemas, MCP client config, framework
  wrappers (LangChain, LlamaIndex, OpenAI Agents).