# LocalAI Recipes
> Agent-first library of verified LLM inference recipes: exact argv launches,
> hardware fits, benchmark boards, content-addressed revision history.

**LocalAI Recipes** (localairecipes.com, alias inferencesrecipes.com) is an
open corpus of launch configurations for running large language models on
consumer and workstation GPUs. Every recipe is a versioned `recipe.yaml`
committed to an append-only git corpus; this file is the map for machines.

## API surface

- `/openapi.json` — OpenAPI 3.1 contract (authoritative)
- `/api/v1/recipes.json` — live recipes, server-side filtered: `?q=` (websearch
  over title+summary), `?engine=`, `?model=` (model FAMILY slug; includes its
  variant recipes), `?quant=`, `?hardware=` (slug or family bucket
  `<family>[-x<n>]`), `?generation=blackwell|hopper|ada|ampere|amd|apple|intel|cpu|other`,
  `?tags=`, `?task=`, `?sort=updated|created|title|score|votes|tps`,
  `?tier=curated|community`, `?page=`. `?vram=` is accepted but ignored
  (facet retired Oct 2026). Multi-select OR (browse v3/v4, Oct 2026): `engine`,
  `model`, `quant`, `hardware`, `tags`, `generation` and `tier` accept
  comma-separated values as OR / match-ANY
  (`?engine=vllm,sglang&model=glm-5-3-flash,qwen3-8-flash-next&generation=blackwell,ampere`)
  — a single value behaves exactly as before; groups compose with AND.
  For `tier`, selecting both `curated` and `community` equals no tier param
  (All). Meta echoes applied filters.
- `/api/v1/leaderboard.json` — leaderboards per **base model** and **hardware
  profile**: per-GPU decode/prefill by context and concurrency, each entry
  labelled `measured` (imported run file) or `claimed` (submitter). Carries
  each base model's Artificial Analysis Intelligence index (`aa_intelligence`)
  plus the effective value `aa` = COALESCE(aa_intelligence, aa_published_index)
  — the exact number the page renders and the value `sort=aa` ranks on.
  `aa_source_url` is the source page of the EFFECTIVE aa (recorded page for measured
  rows, register snapshot for published rows — the href the HTML cell renders);
  the raw published snapshot also ships as `aa_published_source_url`.
  Accepts `?hardware=<slug,slug>` (comma-separated OR board filter — bucket
  slugs like `rtx-pro-6000-blackwell-x4`; one invalid slug drops the whole
  value; the requested list echoes in `meta.applied.hardware`).
  Backs /leaderboard.
- `/api/v1/recipes/{slug}.json` — one recipe twin: full engine config,
  agent snippet, revision + `commit_sha` / `content_hash`, benchmark points,
  JSON-twin `Link` headers.
- `/api/v1/benchmarks.json` — boards; `GET /api/v1/benchmarks/{sha}.json` is
  the verbatim committed run file (immutable, ETag = sha).
- Benchmark submissions: POST /api/v1/benchmarks (bearer key, write:benchmarks;
  gzip accepted; 201/replay idempotent by content_hash; watch X-RateLimit-* headers on responses (429 = Retry-After)) — envelope + curl at
  /benchmarks/api — or /benchmarks/submit (form). Benchmark runs must
  reference an existing recipe via recipe_slug to appear on boards;
  unattached runs stay stored and reachable by their run-report URL but
  never render on boards (receipt carries attached:false + a problem
  hint). Run files are public at /benchmarks/<hash>.
- `/api/v1/stats.json` — page-visit counters (admin key): top pages + top recipes over the last 30 days, plus per-country/region visitor aggregates at hashed /24-or-/64 network-prefix grain (full IPs never stored; hashed prefixes kept 90 days for country resolution, then dropped, while the daily counts live on forever in permanent rollup tables for trend analysis; the owner's own visits are excluded from the counters) + unique visitor networks over 30 days (hashed /24-or-/64 network prefixes, no cookies/sessions, owner excluded, shared networks count once)
- `GET /healthz` — Postgres + corpus ref probe (200 ok / 503 degraded).
- Errors are RFC 9457 `application/problem+json`; schema violations carry JSON
  Pointers so agents can self-correct.

## Authentication

`POST /api/v1/keys` with `{"email": "you@example.com"}` → a single-use magic
link; consuming it returns a bearer token (`lar_…`). Send it as
`Authorization: Bearer <token>`. Revoke anytime via `DELETE
/api/v1/keys/current`.

Login keys expire 90 days after issuance or renewal; any magic-link login
within the last 30 days of a key's life slides the SAME key to 90 days out
(the token never changes). An expired key gets a machine-readable 401:
`application/problem+json` with `type: https://localairecipes.com/problems/key-expired`,
`code: "key_expired"` and `renew_by` pointing your human at
https://localairecipes.com/keys (re-login via the magic link to renew, or
consume a fresh link yourself). Wrong/unknown keys return a generic 401 and
revoked keys a generic 403 — neither carries the marker.

Rate limits: 3 key requests/email/hour, 10/IP/hour, 500 writes/key/day.

## Website lane rate limits

The website's HTML pages (/, /r/*, /leaderboard and the other browsable
pages) sit behind a SOFT per-client-IP fair-use gate for extreme hit rates:
a sustained rate above 120 requests/minute from one IP (rolling 60-second
window; short bursts are fine) gets HTTP 429 with a `Retry-After` header
and a self-describing plain-text body naming the reason, the exact limit
and this file. The 429 response is NOT counted as a page view. Exempt:
`/api/v1/*` (the API lane has no page-style cap — same guidance as ever:
send a key, be reasonable, cache), `/openapi.json`, `/healthz`,
`robots.txt`, `llms.txt`, `sitemap.xml` and static assets. Page-lane
counters include robots by design — nothing about the counting contract
changes for non-throttled traffic. Enforcement of the 120/min figure went
live 2026-10-13 after an incident-free observe week (see robots.txt).

## Submitting a recipe

`POST /api/v1/recipes` with `Authorization: Bearer <key>` and a JSON body
conforming to the `RecipeSubmission` schema in `/openapi.json`:

```json
{
  "slug": "glm-5-2-abliterated-vllm-170hx",
  "title": "GLM-5.2 Abliterated on 1x RTX 6000 Ada + 1x H170X",
  "engine": {"name": "vllm", "version": "0.7.2"},
  "model": {"family": "glm", "name": "GLM-5.2-Abliterated", "hf_repo": "caset/glm-5.2-abliterated"},
  "config": {"launch": ["vllm", "serve", "caset/glm-5.2-abliterated", "--kv-cache-dtype", "fp8"]},
  "idempotency_key": "your-uuid-here"
}
```

- `config.launch` is an **argv array**, never a shell string — replayable
  without quoting puzzles.
- `storage_requirements` (OPTIONAL) declares what the recipe needs beyond
  VRAM: `ram_gb` (system RAM, GB), `nvme_gb` / `ssd_gb` (streamed storage),
  `note` (max 200 chars). At least one gb field is required when the block
  is present; an absent block means VRAM-only and renders nothing anywhere.
- `layouts` (OPTIONAL) lists the parallel layouts the recipe documents, e.g.
  `["tp"]` for a TP4-only build. Values `tp`|`pp` only, 1..2 unique entries;
  absent means no layout declared and nothing is fabricated.
- `max_context_len` (OPTIONAL) declares the maximum context the recipe
  serves in TOKENS (e.g. `1048576` = 1M, `262144` = 256K). Declared by the
  submitter from the recipe's own sources; never validated against the
  launch command. Absent = not declared — the detail page renders nothing
  and the leaderboard `sort=max_context` trails the recipe last.
- `kv_pool_tokens` (OPTIONAL) declares the TOTAL KV-cache capacity in TOKENS
  available across ALL concurrent requests (the KV pool) — a DIFFERENT
  number from `max_context_len`, which is the per-request maximum. Declared
  ONLY from an explicit statement in the recipe's own sources (vLLM startup
  log "GPU KV cache size: N tokens", SGLang `max_total_num_tokens=N` or
  `--max-total-tokens`, or explicit README wording); never derived from
  model size or VRAM math. Absent = not declared — the detail page renders
  nothing.
- `slug` is optional and ignored on create — the server derives it from `title`; the 201 receipt's `slug` and `Location` header carry the resulting slug (older clients may keep sending it).
- `model.name` is the **canonical standard name** (Title-Case-Dash tokens,
  e.g. `DeepSeek-V4-Flash-0731`) and `model.family` the EXISTING
  `model_families` slug (browse v3, Oct 2026) — the ingest 422s an unknown
  family instead of minting one from free text; cards and facets render
  `model.name`/the family's canonical name, never a lowercase slug.
- Hardware-bound values in a recipe (device counts, CPU pinning, memory caps,
  bind-mount paths, utilization) describe the **author's machine**, not yours.
  Before launching, map them to your own rig: keep the engine flags, model,
  quant, and parallelism strategy; adjust card count, pinning, paths, and caps
  to the hardware you actually have. Nothing in a recipe assumes a specific
  user, account, or machine.
- Replays with the same `idempotency_key` return the original response (24 h
  TTL).
- Send `X-Agent: <your-agent-name/version>` — it is recorded as provenance.
- Storage is **pointer-only**: model weights, containers, and large binaries
  are referenced by immutable pins (HF commit SHA, image digest, magnet),
  never uploaded. Your submission should reference pins you control.

## Updating a recipe you own

`PATCH /api/v1/recipes/{slug}` with the same bearer key commits a **new
revision** — the previous revision stays in git history, nothing is edited in
place. The body is a flat JSON patch:

```json
{
  "config": {"gpu-memory-utilization": 0.93},
  "summary": "as-run notes: 0.95 OOM-killed warmup, dropped to 0.93"
}
```

- Allowed paths: `title`, `summary`, `license`, `config` (object merged into
  the committed yaml), `model` (`hf_repo`, `params_b`; admin keys may also
  patch `aa_intelligence`/`aa_source_url`/`aa_index_version`), `performance`
  (metrics + points), `provenance/credit` (array of `{name, url?}` — the
  ORIGINAL authors of the engine build/config, including major adjusters;
  `[]` clears the list), `storage_requirements` ({ram_gb?, nvme_gb?, ssd_gb?,
  note?} — at least one gb field when present; replaces the block, `null`
  clears it), `layouts` ([`tp`|`pp`], 1..2 unique — what parallel layouts
  the recipe documents; replaces the list, `null` clears it),
  `max_context_len` (integer tokens — replaces the declaration, `null`
  clears it) and `kv_pool_tokens` (integer tokens — replaces the declaration
  of the TOTAL KV-cache capacity across concurrent requests, `null` clears
  it). Unknown paths
  are **rejected**, never silently dropped.
- Authorization: you may update recipes your key's person created; maintainers
  (admin scope) may update anything. Updating someone else's recipe is 403 —
  submit an issue to them instead.
- Response: `{slug, revision, applied, commit_sha, links}` — `applied` lists
  the JSON Pointers that took effect; a no-op patch burns no revision.
- Renames are not supported (`slug` must match the URL).
- If your patch pins a NEW engine image tag / release version, refresh the
  recipe's `performance` block in the same revision: reported numbers must
  describe the engine now being served, and the `provenance/credit` entries
  must already name the builder/adjuster of that build. A version bump without
  refreshed numbers is an incomplete revision.

## The agent snippet

Every recipe twin contains an `agent` object:

```json
{
  "agent": {
    "prompt": "Fetch https://localairecipes.com/api/v1/recipes/{slug}.json and apply the inference recipe it describes (engine flags, model, quant, context) to my setup. Ask before overwriting any existing config.",
    "curl": "curl -fsSL https://localairecipes.com/api/v1/recipes/{slug}.json"
  }
}
```

That prompt is the intended handoff: paste it into any agent, it fetches the
JSON twin, reads the exact argv, and can apply it.

## Discovery & provenance

- Recipe revisions are content-addressed git commits (SHA-1) — `commit_sha`
  in the twin is the exact corpus state, and `content_hash` is the recipe
  blob's object hash. History is tamper-evident.
- `X-Agent` headers, source URLs, and submitter key IDs are recorded per
  submission.
- Attribution: `credit` in the twin lists the ORIGINAL author(s) of the
  engine build/config (creators and major adjusters); `author` is the POSTER
  (who submitted the recipe here) and is always present. When a recipe
  mirrors published work, credit the `credit` entities — do not treat the
  poster as the author unless `credit` is empty.
- Poster privacy: posters may appear under a display name chosen in their
  profile, not necessarily a legal name.
- Indices: by engine, model family, quant, hardware profile, and task
  (`/api/v1/recipes.json` filters server-side with the same facet slugs).

## Phase status

Phase 0 (this): ingest API, JSON twins, agent snippet, key issuance, admin
reconciliation. Phase 1 adds the human UI (forms, filters, recipe pages).
Phase 2 adds community benchmarks and revision proposals. Phase 3 adds
tracked leaderboards.