@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/observability/scripts/verify.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+#
+# verify.sh - lint an emitted OpenTelemetry observability setup.
+#
+# Usage:
+#   cd <dir containing the Collector config + SDK init>
+#   ./verify.sh [path-to-collector-config.yaml]
+#
+# Read-only: never mutates anything. Checks the wiring, not just presence:
+#   1. a Collector config exists (a *.yaml/*.yml with receivers: and service:)
+#   2. it is valid: `otelcol validate` if the binary is on PATH, else
+#      a required-keys check for receivers / exporters / service.pipelines
+#   3. every exporter declared under exporters: is referenced in some
+#      pipeline (the classic "exporter defined but never enabled" footgun)
+#   4. SDK init sets the service name (OTEL_SERVICE_NAME /
+#      OTEL_RESOURCE_ATTRIBUTES / a service.name resource attribute) -> warn
+#   5. heuristic cardinality check: warn if user_id|request_id|email|session_id
+#      is used as a metric label/attribute key
+#
+# Emits [ ok ]/[warn]/[fail] per check, then PASS or FAIL.
+# Exits 0 on a clean setup AND when nothing relevant is found (no false failure).
+# Exits 1 only on hard failures: no config, invalid config, unused exporter.
+#
+# Portable: stock macOS bash 3.2 + grep + awk. No associative arrays, no mapfile.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+failed=0
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+
+# --- 1. locate a Collector config -------------------------------------------
+cfg="${1:-}"
+if [ -z "$cfg" ]; then
+  # any yaml/yml that looks like a Collector config (has receivers: and service:)
+  while IFS= read -r f; do
+    if grep -Eq '^[[:space:]]*receivers[[:space:]]*:' "$f" \
+       && grep -Eq '^[[:space:]]*service[[:space:]]*:' "$f"; then
+      cfg="$f"; break
+    fi
+  done < <(find . -maxdepth 3 -type f \( -name '*.yaml' -o -name '*.yml' \) 2>/dev/null)
+fi
+
+if [ -z "$cfg" ] || [ ! -f "$cfg" ]; then
+  skip "no OTel Collector config found (a *.yaml with receivers: + service:) - nothing to verify."
+  exit 0
+fi
+
+printf -- '----- linting %s\n' "$cfg"
+
+# --- 2. validity ------------------------------------------------------------
+if command -v otelcol >/dev/null 2>&1; then
+  if otelcol validate --config "$cfg" >/dev/null 2>&1; then
+    ok "otelcol validate passed"
+  else
+    fail "otelcol validate rejected the config"
+  fi
+elif command -v otelcol-contrib >/dev/null 2>&1; then
+  if otelcol-contrib validate --config "$cfg" >/dev/null 2>&1; then
+    ok "otelcol-contrib validate passed"
+  else
+    fail "otelcol-contrib validate rejected the config"
+  fi
+else
+  # no binary: required top-level/section keys must be present
+  miss=""
+  grep -Eq '^[[:space:]]*receivers[[:space:]]*:'  "$cfg" || miss="$miss receivers"
+  grep -Eq '^[[:space:]]*exporters[[:space:]]*:'  "$cfg" || miss="$miss exporters"
+  grep -Eq '^[[:space:]]*service[[:space:]]*:'    "$cfg" || miss="$miss service"
+  grep -Eq '^[[:space:]]*pipelines[[:space:]]*:'  "$cfg" || miss="$miss service.pipelines"
+  if [ -z "$miss" ]; then
+    ok "required sections present (receivers, exporters, service.pipelines) [otelcol not on PATH; key-check only]"
+  else
+    fail "config missing required section(s):$miss"
+  fi
+fi
+
+# --- 3. every declared exporter is referenced in a pipeline -----------------
+# Collect exporter ids: indented one level under the top-level `exporters:` block,
+# keys ending in ':' (e.g. "otlphttp/traces:"). Then confirm each id's bare name
+# appears somewhere after a "service:"/"pipelines:" context.
+exp_ids="$(awk '
+  /^exporters[[:space:]]*:/        { in_exp=1; ind=-1; next }
+  /^[a-zA-Z0-9_]+[[:space:]]*:/    { if (in_exp) in_exp=0 }   # next top-level block ends it
+  in_exp {
+    if ($0 ~ /^[[:space:]]+[A-Za-z0-9_\/.-]+[[:space:]]*:/) {
+      line=$0
+      sub(/:.*/, "", line); gsub(/[[:space:]]/, "", line)
+      # only the first indentation level (exporter ids), skip deeper config keys
+      lead=match($0, /[^ ]/)-1
+      if (ind==-1) ind=lead
+      if (lead==ind && line!="") print line
+    }
+  }
+' "$cfg" 2>/dev/null || true)"
+
+if [ -z "$exp_ids" ]; then
+  skip "no exporter ids parsed under exporters: - skipping unused-exporter check"
+else
+  # body after the first `service:` line is where pipelines reference exporters
+  svc_body="$(awk '/^service[[:space:]]*:/{s=1} s{print}' "$cfg")"
+  unused=""
+  for e in $exp_ids; do
+    if printf '%s\n' "$svc_body" | grep -Fq "$e"; then
+      :
+    else
+      unused="$unused $e"
+    fi
+  done
+  if [ -z "$unused" ]; then
+    ok "every declared exporter is wired into a pipeline"
+  else
+    fail "exporter(s) declared but never used in any pipeline:$unused (inert until added to service.pipelines)"
+  fi
+fi
+
+# --- 4. service.name is set somewhere in the setup --------------------------
+# Look across the whole dir's likely SDK-init files, not just the yaml.
+sdk_hit=0
+if grep -Rqs -E 'OTEL_SERVICE_NAME|OTEL_RESOURCE_ATTRIBUTES|service[._-]?name|ServiceName' . 2>/dev/null; then
+  sdk_hit=1
+fi
+if [ "$sdk_hit" -eq 1 ]; then
+  ok "service.name is set (OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES / resource attr found)"
+else
+  warn "no service.name found - telemetry will land as 'unknown_service'. Set OTEL_SERVICE_NAME or a service.name resource attribute."
+fi
+
+# --- 5. high-cardinality metric label heuristic -----------------------------
+# Warn (don't fail) if an unbounded id is used as a metric label/attribute key.
+card_hit="$(grep -RnsE '(user_id|request_id|session_id|email)[[:space:]]*[:=]' . 2>/dev/null \
+            | grep -Ei 'label|attribute|metric|tags?|dimension' || true)"
+if [ -n "$card_hit" ]; then
+  warn "possible high-cardinality metric label(s) - keep these off metrics, put them on spans/logs:"
+  printf '%s\n' "$card_hit" | sed 's/^/        /'
+else
+  ok "no obvious high-cardinality metric label (user_id/request_id/session_id/email)"
+fi
+
+# --- verdict ----------------------------------------------------------------
+echo
+if [ "$failed" -eq 0 ]; then
+  printf '%sPASS%s - observability setup is wired.\n' "$GREEN" "$RESET"
+  exit 0
+else
+  printf '%sFAIL%s - fix the items above.\n' "$RED" "$RESET"
+  exit 1
+fi

package/skills/shared/ollama/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: ollama
+description: "Use when running open-weight LLMs locally with Ollama — pulling and tagging models, calling the local API, picking a quantization or GGUF, writing Modelfiles, and sizing VRAM and RAM for the machine at hand. NOT remote or managed GPU serving and autoscaling (that is `runpod`), NOT downloading raw weights or datasets (that is `huggingface`), NOT retrieval pipeline design (that is `rag`)."
+tags: [ollama, local-llm, gguf, quantization, self-hosted-inference]
+recommends: [huggingface, runpod, modal, llm-pipeline, rag]
+origin: ai-hub
+---
+
+# Ollama — run open-weight LLMs on one box
+
+Ollama serves GGUF models from a local daemon at `http://localhost:11434`, exposing both a native
+HTTP API and an OpenAI-compatible layer. Your job: reach for the right command, the right endpoint,
+and the right quant **for the hardware in front of you** — and recognize when the model does not fit
+and the work belongs on a remote GPU instead.
+
+This skill owns: install/serve, pull/tag, the local API (native + OpenAI-compat), Modelfiles,
+quantization choice, and VRAM/RAM sizing on a single machine.
+
+## When to use / when not
+
+**Use when** the model runs on *this* machine: pulling/running a model, fixing an OOM, choosing
+Q4 vs Q8, authoring a Modelfile, or wiring an app to `localhost:11434`.
+
+**Go elsewhere when:**
+
+- Hosting behind a managed/remote GPU, autoscaling, or serverless inference → `runpod`, `modal`,
+  `replicate`, `together-fireworks`, `fal`. Ollama is local, single-box, no autoscale.
+- Downloading raw weights, datasets, `hf`/`transformers`, repo management → `huggingface`.
+- Designing chunking / retrieval / reranking around a model → `rag` or `embeddings-search`.
+- Orchestrating multi-step calls, routing, pipeline evals → `llm-pipeline` / `agent-eval`.
+- Writing the prompt/system-message *content* itself → `prompt-engineering`.
+
+(Those siblings live in the catalog by id; link them only once their `SKILL.md` exists on disk.)
+
+## Quickstart
+
+```bash
+ollama serve                 # start the daemon (a desktop install already runs it)
+ollama pull qwen3:8b         # download a model + tag; :8b is explicit — avoid bare :latest
+ollama run qwen3:8b          # interactive REPL, or: ollama run qwen3:8b "summarize this"
+ollama ps                    # what is LOADED in VRAM right now + when it unloads (keep_alive)
+ollama list                  # what is on disk (pulled), not what is loaded
+ollama show qwen3:8b         # template, params, context length, quant of a model
+ollama rm qwen3:8b           # free disk; ollama stop qwen3:8b unloads from memory
+```
+
+`ps` vs `list` is the OOM-debug split: `list` is disk, `ps` is memory. A model only eats VRAM once a
+request loads it; it unloads after `keep_alive` (default 5m).
+
+## Pick a model + quant
+
+Quantization trades VRAM for quality. The everyday default is **Q4_K_M**: roughly half the memory of
+fp16 for ~3–5% quality loss. **Q8_0** is near-lossless at ~1 byte/param. **fp16** is the unquantized
+ceiling at 2 bytes/param.
+
+Sizing formula (weights only) — a **rule of thumb**, not a per-model spec sheet:
+
+```text
+weights_GB ≈ params(B) × bytes_per_param × 1.2   # ×1.2 = runtime overhead
+bytes_per_param:  Q4_K_M ≈ 0.5   Q8_0 ≈ 1.0   fp16 = 2.0
+# then ADD the KV cache (see below) — it is NOT in this number.
+```
+
+These bytes/param are conservative round-downs of the measured k-quant rates: llama.cpp's quantize
+benchmark reports Q4_K_M ≈ 4.89 bits/weight (~0.6 byte/param) and Q8_0 ≈ 8.5 bits/weight (~1.06
+byte/param) on Llama-3.1-8B ([llama.cpp quantize README](https://github.com/ggml-org/llama.cpp/blob/master/tools/quantize/README.md),
+accessed 2026-06-02). Rounding to 0.5 / 1.0 keeps the estimate on the safe side; the per-row GB figures
+in the table below are derived from this formula, not vendor-published numbers — verify with `ollama show`.
+
+| VRAM / unified mem | Comfortable choice (Q4_K_M) | Notes |
+| --- | --- | --- |
+| 8 GB | 7–8B Q4_K_M (~5–6 GB) | leave headroom for KV cache + the OS |
+| 12 GB | up to ~14B Q4_K_M (~9–10 GB) | 7–8B at Q8_0 also fits |
+| 16 GB | 14B Q4_K_M comfortably; 32B is tight | 32B Q4_K_M ≈ 20 GB — won't fit |
+| 24 GB | 32B Q4_K_M (~20 GB) | 70B does **not** fit at any usable quant |
+| 48 GB+ / 2×24 GB | 70B Q4_K_M (~40–48 GB) | needs the full budget; long context pushes over |
+| Mac unified (e.g. 64 GB) | weights share RAM with everything else | budget against total unified memory |
+
+**KV cache is the trap.** It grows ~linearly with `num_ctx` and lives in VRAM *on top of* the weights.
+At long context (e.g. 128K) a 70B can add tens of GB of cache — often more than people budget for. If
+you are tight: cap `num_ctx`, or shrink the cache with `OLLAMA_KV_CACHE_TYPE=q8_0` (or `q4_0`). See
+[references/hardware-sizing.md](references/hardware-sizing.md) for the KV math and a per-context table.
+
+Ollama runs a llama.cpp-backed engine (GGUF) by default, with a scheduler that reduces OOM crashes and
+improves multi-GPU placement. On Apple Silicon it can use an **MLX** backend (shipped in Ollama 0.19,
+per [ollama.com/blog/mlx](https://ollama.com/blog/mlx), 2026-03-30), but **only on Macs with >32 GB of
+unified memory** — below that gate it stays on the llama.cpp engine. None of this invents memory you
+don't have: when the box can't hold the model, that's a `runpod`/`modal` job, not a quant downgrade.
+
+## The API
+
+Two surfaces, same daemon. Use **native `/api/chat`** when you want Ollama-specific fields
+(`keep_alive`, `format` as a JSON schema, `think`); use the **OpenAI-compat `/v1`** layer to reuse an
+existing OpenAI SDK unchanged.
+
+Native chat (`/api/chat`), non-streaming:
+
+```bash
+curl http://localhost:11434/api/chat -d '{
+  "model": "qwen3:8b",
+  "messages": [{"role": "user", "content": "Name three primes."}],
+  "stream": false,
+  "options": {"temperature": 0.2, "num_ctx": 8192},
+  "keep_alive": "10m"
+}'
+```
+
+`stream` defaults to **true** (NDJSON, one object per line, final object has `done: true` + timing
+stats). `options.num_ctx` sets the context window *for this request* — it does not persist; bake it
+into a Modelfile if you want it permanent.
+
+OpenAI-compatible — point any OpenAI SDK at `localhost:11434/v1` with a dummy key:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")  # key is ignored
+resp = client.chat.completions.create(
+    model="qwen3:8b",
+    messages=[{"role": "user", "content": "Name three primes."}],
+    temperature=0.2,
+)
+print(resp.choices[0].message.content)
+```
+
+Structured output — pass a JSON schema as `format` (native) so the model is constrained to valid JSON:
+
+```bash
+curl http://localhost:11434/api/chat -d '{
+  "model": "qwen3:8b",
+  "messages": [{"role": "user", "content": "Extract name and age from: Ana is 30."}],
+  "stream": false,
+  "format": {
+    "type": "object",
+    "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
+    "required": ["name", "age"]
+  }
+}'
+```
+
+Tool calling (`tools`), multimodal (`images` as base64), embeddings (`/api/embed`), and the full field
+tables live in [references/api.md](references/api.md). Endpoint map at a glance: `/api/generate`,
+`/api/chat`, `/api/embed`, `/api/create`, `/api/pull`, `/api/show`, `/api/ps`, `/api/tags`.
+
+## Modelfiles
+
+A Modelfile bakes a base model + system prompt + parameters into a new named model. Build with
+`ollama create`.
+
+```dockerfile
+FROM qwen3:8b
+SYSTEM "You are a terse senior code reviewer. Answer in bullet points."
+PARAMETER num_ctx 16384
+PARAMETER temperature 0.2
+PARAMETER stop "<|im_end|>"
+```
+
+```bash
+ollama create reviewer -f Modelfile     # now: ollama run reviewer
+```
+
+- `FROM` is required — a model tag or a local file (`FROM ./model.gguf` to import a raw GGUF).
+- `PARAMETER num_ctx` makes the context window permanent (vs the per-request `options.num_ctx`).
+- `SYSTEM`, `TEMPLATE`, `LICENSE`, `ADAPTER` (LoRA) round out the instruction set.
+
+Quantize on create from an fp16/fp32 source:
+
+```bash
+ollama create reviewer --quantize q4_K_M -f Modelfile   # FROM must be an fp16/fp32 model
+```
+
+`--quantize` only works when the `FROM` source is full-precision; you cannot re-quantize an
+already-Q4 model. To go from Hugging Face weights to a GGUF in the first place, that conversion is a
+`huggingface` job — Ollama imports the result.
+
+## When to leave the box
+
+If the comfortable-choice row for your VRAM can't hold the model you actually need (e.g. you need 70B
+quality on a 12 GB laptop), stop downgrading quant — quality collapses below Q4 and you'll still OOM at
+real context. Move it to a remote GPU: `runpod` (rent a GPU), `modal` (serverless container + GPU
+autoscale), or a hosted endpoint (`replicate`, `together-fireworks`, `fal`). Ollama is the right tool
+*until the weights + KV cache exceed the single box*.
+
+## Anti-patterns
+
+| Bad | Good | Why |
+| --- | --- | --- |
+| Pull fp16 on a box that only fits Q4 | Pull Q4_K_M (or Q8_0 if it fits) | fp16 is 4× the VRAM of Q4 for ~3–5% quality; you'll OOM for nothing |
+| `num_ctx: 128000` on a 12 GB GPU | Cap `num_ctx` to what fits; `OLLAMA_KV_CACHE_TYPE=q8_0` | KV cache scales with context and sits on top of weights — long context dwarfs the model |
+| `/api/generate` for a chat with history | `/api/chat` with a `messages` array | `generate` is single-turn; you'd hand-concatenate history and break the chat template |
+| `ollama pull mistral:latest`, assume it's small | Pin an explicit tag (`:7b`, a quant tag) and `ollama show` it | `:latest` size/quant drifts release to release; sizing breaks silently |
+| Treat Ollama as a multi-tenant prod server | Use it local/single-box; scale → `runpod`/`modal` | one daemon, limited parallelism (`OLLAMA_NUM_PARALLEL`); not built for fleet serving |
+| Hardcode `api.openai.com` when target is local | `base_url="http://localhost:11434/v1"`, dummy key | the OpenAI SDK works unchanged against the compat layer; no remote calls, no key leak |
+| Downgrade to Q2 to force a 70B onto 12 GB | Pick a model that fits, or move to a remote GPU | sub-Q4 quality drops sharply *and* it still won't fit at real context |
+| Assume `ollama list` means it's loaded | `ollama ps` for memory, `list` for disk | a pulled model uses 0 VRAM until a request loads it |
+
+## Verify
+
+Run `scripts/verify.sh [TARGET]` from your project root (or a dir holding a `Modelfile`). Static by
+default — it needs neither Ollama installed nor a running daemon. It lints a `Modelfile` (FAIL if no
+`FROM`; WARN on unknown instructions or a `num_ctx` so high it will OOM consumer GPUs), notes whether
+app code points at the local `localhost:11434` / `/v1` endpoint vs only-remote hosts, and — only if
+`ollama` is on PATH — best-effort confirms a model is present (WARN, not FAIL). It exits non-zero
+**only** on a real FAIL; an empty/clean target passes.
+
+## References
+
+- [references/api.md](references/api.md) — full endpoint catalog, request/response field tables,
+  OpenAI-compat path mapping, structured output, tool calling, streaming, embeddings (curl + Python).
+- [references/hardware-sizing.md](references/hardware-sizing.md) — the full quant ladder, VRAM formula
+  derivation, KV-cache math + per-context table, per-model chart, Apple Silicon unified-memory notes,
+  and the env knobs (`OLLAMA_KV_CACHE_TYPE`, `OLLAMA_FLASH_ATTENTION`, `OLLAMA_NUM_PARALLEL`,
+  `OLLAMA_MAX_LOADED_MODELS`) for fitting tight boxes.

package/skills/shared/ollama/evals/README.md

@@ -0,0 +1,9 @@
+# Evals for the `ollama` skill
+
+`cases.yaml` is a routing + capability fixture, not an automated test harness. Run it by hand (or feed
+it to whatever router you use to dispatch skills): for each `should_trigger` prompt, confirm the router
+selects `ollama`; for each `should_not_trigger` prompt, confirm it routes to the named sibling
+(`runpod`, `modal`, `huggingface`, `rag`, `prompt-engineering`) and not here. For the `capability`
+case, have the skill answer the scenario and check the response covers every bullet in `must_include`.
+No models, GPUs, or external services are required — this is purely about whether the skill fires in
+the right situations and produces a complete, correct local-Ollama answer.

package/skills/shared/ollama/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: ollama
+
+should_trigger:
+  - prompt: "How do I run Llama 3.3 70B locally with Ollama?"
+    why: Core local-serve request — pull/run a named model on this machine.
+  - prompt: "My Ollama model keeps OOMing once the conversation gets long — how do I fix it?"
+    why: Non-obvious — the cause is KV-cache growth with context; fix is num_ctx cap / OLLAMA_KV_CACHE_TYPE / smaller model, all owned here.
+  - prompt: "Write a Modelfile that gives qwen3 an 8k context and a terse system prompt."
+    why: Modelfile authoring (FROM + SYSTEM + PARAMETER num_ctx) plus ollama create.
+  - prompt: "Point my OpenAI Python SDK at a local model instead of api.openai.com."
+    why: OpenAI-compat layer at localhost:11434/v1 with a dummy key — a non-obvious 'it just works' path.
+  - prompt: "Quina quantització (Q4 o Q8) i quin model caben a la meva RTX 3060 de 12GB?"
+    why: Catalan; quant choice + VRAM sizing for a specific GPU, the heart of the skill.
+  - prompt: "Convert this GGUF file into an Ollama model and quantize it to Q4_K_M."
+    why: FROM ./model.gguf import plus ollama create --quantize q4_K_M.
+  - prompt: "ejecutar un LLM en local sin API key, totalmente offline"
+    why: Spanish; the local/offline/no-key framing that defines Ollama's niche.
+
+should_not_trigger:
+  - prompt: "Deploy this model on a serverless GPU endpoint that autoscales with traffic."
+    route_to: modal
+    why: Managed/serverless autoscaled serving — Ollama is single-box, no autoscale.
+  - prompt: "Rent a GPU in the cloud to serve a 70B model behind an HTTP endpoint."
+    route_to: runpod
+    why: Remote/managed GPU rental and serving, not local inference.
+  - prompt: "Download the Llama weights and a fine-tuning dataset from the Hub with the hf CLI."
+    route_to: huggingface
+    why: Weights/dataset/repo management — Ollama imports a result, it doesn't manage the Hub.
+  - prompt: "Build a retrieval pipeline that chunks PDFs and reranks before calling the model."
+    route_to: rag
+    why: Retrieval/chunking/reranking design; the model is the downstream consumer.
+  - prompt: "Help me write a better system prompt for tone and refusal behavior."
+    route_to: prompt-engineering
+    why: Prompt content authoring, not model serving or hardware.
+
+capability:
+  - scenario: "I have an RTX 4070 with 12GB VRAM. I want a coding assistant running locally via Ollama, called from a Python app, with a custom 16k-context system prompt."
+    must_include:
+      - Recommends a model size + quant that fits ~12 GB (e.g. 7B–14B at Q4_K_M) with the sizing reasoning (weights ≈ params × bytes/param × 1.2).
+      - Warns that a 16k context adds KV cache on top of weights; suggests PARAMETER num_ctx 16384 and OLLAMA_KV_CACHE_TYPE=q8_0 if tight.
+      - Gives a Modelfile (FROM + SYSTEM + PARAMETER num_ctx 16384) and the ollama create command.
+      - Shows calling it from Python — native /api/chat or the OpenAI-compat /v1 with base_url http://localhost:11434/v1 and a dummy key.
+      - Names the boundary — if it doesn't fit or needs scale, move to runpod/modal.

package/skills/shared/ollama/references/api.md

@@ -0,0 +1,148 @@
+# Ollama local API reference
+
+Daemon base URL: `http://localhost:11434`. Bind elsewhere with `OLLAMA_HOST=0.0.0.0:11434`.
+Two surfaces share the daemon: the **native** API (`/api/*`) and the **OpenAI-compatible** layer
+(`/v1/*`).
+
+## Native endpoint catalog
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| POST | `/api/generate` | single-turn completion (`prompt`) |
+| POST | `/api/chat` | multi-turn chat (`messages`); supports `tools`, `images`, `think` |
+| POST | `/api/embed` | embeddings (`input` string or array); legacy alias `/api/embeddings` |
+| POST | `/api/create` | create a model from a Modelfile / quantize |
+| POST | `/api/pull` | download a model |
+| POST | `/api/push` | upload a model |
+| POST | `/api/show` | model template, params, context length, quant |
+| POST | `/api/copy` | duplicate a model under a new name |
+| DELETE | `/api/delete` | remove a model |
+| GET | `/api/tags` | models on disk (≈ `ollama list`) |
+| GET | `/api/ps` | models loaded in memory (≈ `ollama ps`) |
+| GET | `/api/version` | daemon version |
+
+## Request fields (generate / chat)
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `model` | string | — | **required**; a pulled tag |
+| `prompt` | string | — | `/api/generate` only |
+| `messages` | array | — | `/api/chat`; `{role, content, images?, tool_calls?}` |
+| `stream` | bool | `true` | NDJSON stream; set `false` for a single object |
+| `format` | string \| object | — | `"json"` or a JSON Schema object to constrain output |
+| `options` | object | — | runtime params: `temperature`, `num_ctx`, `top_p`, `seed`, `num_predict`, `stop`, … |
+| `keep_alive` | string \| int | `"5m"` | how long to keep loaded; `0` unloads now, `-1` keeps forever |
+| `tools` | array | — | tool/function definitions for tool calling |
+| `images` | array | — | base64 images for multimodal models |
+| `think` | bool | — | enable/disable reasoning on models that support it |
+
+`options.num_ctx` is per-request and does not persist. Bake a permanent context window into a
+Modelfile with `PARAMETER num_ctx`.
+
+## Response fields
+
+Final object (streaming or not) carries: `done` (bool), `done_reason`, `total_duration`,
+`load_duration`, `prompt_eval_count`, `prompt_eval_duration`, `eval_count`, `eval_duration`.
+Tokens/sec ≈ `eval_count / (eval_duration / 1e9)`.
+
+Streaming = NDJSON: one JSON object per line; accumulate `message.content` (chat) or `response`
+(generate) until `done: true`.
+
+```python
+import requests, json
+
+with requests.post("http://localhost:11434/api/chat",
+                   json={"model": "qwen3:8b",
+                         "messages": [{"role": "user", "content": "Count to 3."}]},
+                   stream=True) as r:
+    for line in r.iter_lines():
+        if line:
+            obj = json.loads(line)
+            print(obj.get("message", {}).get("content", ""), end="", flush=True)
+            if obj.get("done"):
+                break
+```
+
+## Structured output via `format`
+
+Pass a JSON Schema as `format`; the model is constrained to emit conforming JSON. Pair with a low
+temperature and an explicit instruction to return JSON.
+
+```bash
+curl http://localhost:11434/api/chat -d '{
+  "model": "qwen3:8b",
+  "messages": [{"role": "user", "content": "List two EU capitals as JSON."}],
+  "stream": false,
+  "options": {"temperature": 0},
+  "format": {
+    "type": "object",
+    "properties": {
+      "capitals": {"type": "array", "items": {"type": "string"}}
+    },
+    "required": ["capitals"]
+  }
+}'
+```
+
+## Tool calling
+
+Define `tools`; the response may contain `message.tool_calls`. Execute the tool, append a
+`{"role": "tool", "content": "<result>"}` message, and call again.
+
+```bash
+curl http://localhost:11434/api/chat -d '{
+  "model": "qwen3:8b",
+  "stream": false,
+  "messages": [{"role": "user", "content": "Weather in Andorra?"}],
+  "tools": [{
+    "type": "function",
+    "function": {
+      "name": "get_weather",
+      "description": "Current weather for a city",
+      "parameters": {
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"]
+      }
+    }
+  }]
+}'
+```
+
+## Embeddings
+
+```bash
+curl http://localhost:11434/api/embed -d '{
+  "model": "nomic-embed-text",
+  "input": ["first chunk", "second chunk"]
+}'
+```
+
+Returns `embeddings` (array of float arrays). For the retrieval pipeline around these vectors, that's
+`rag` / `embeddings-search`, not this skill.
+
+## OpenAI-compatible layer (`/v1`)
+
+| OpenAI path | Ollama support |
+| --- | --- |
+| `POST /v1/chat/completions` | yes — drop-in for chat |
+| `POST /v1/completions` | yes — legacy text completion |
+| `POST /v1/embeddings` | yes |
+| `GET /v1/models` | lists pulled models |
+
+Point any OpenAI SDK at the base URL with any non-empty key (it is ignored):
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
+
+# streaming
+for chunk in client.chat.completions.create(
+        model="qwen3:8b",
+        messages=[{"role": "user", "content": "hi"}],
+        stream=True):
+    print(chunk.choices[0].delta.content or "", end="")
+```
+
+Native-only knobs (`keep_alive`, `format` as a JSON Schema, `think`) aren't expressible through the
+OpenAI layer — use `/api/chat` when you need them.

package/skills/shared/ollama/references/hardware-sizing.md

@@ -0,0 +1,87 @@
+# Hardware sizing for local Ollama
+
+Total memory = **weights + KV cache + overhead**. People size for weights and forget the KV cache,
+then OOM at long context. Budget all three.
+
+## The quant ladder
+
+| Quant | Bytes/param | Size vs fp16 | Quality | Use it for |
+| --- | --- | --- | --- | --- |
+| fp16 | 2.0 | 100% | reference | when VRAM is abundant or you need max fidelity |
+| Q8_0 | ~1.0 | ~50% | near-lossless | quality-sensitive work that still fits |
+| Q6_K | ~0.8 | ~40% | very close to Q8 | a middle step when Q8 is just too big |
+| **Q4_K_M** | ~0.5 | ~25% | ~3–5% loss; the default | everyday local inference |
+| Q3_K_M | ~0.4 | ~20% | noticeable degradation | last resort to fit |
+| Q2_K | ~0.3 | ~15% | often unusable | rarely worth it — change model size instead |
+
+Rule: drop **model size** before dropping below Q4. A 14B at Q4_K_M beats a 70B at Q2_K on both quality
+and fit.
+
+## Weights formula
+
+```text
+weights_GB ≈ params(B) × bytes_per_param × 1.2
+# the ×1.2 absorbs runtime/format overhead; KV cache is separate (below).
+```
+
+| Model | Q4_K_M (~0.5 B/p) | Q8_0 (~1.0) | fp16 (2.0) |
+| --- | --- | --- | --- |
+| 7–8B | ~5–6 GB | ~9 GB | ~16 GB |
+| 13–14B | ~9–10 GB | ~16 GB | ~30 GB |
+| 32B | ~20 GB | ~36 GB | ~70 GB |
+| 70B | ~40–48 GB | ~75 GB | ~140 GB |
+
+## KV-cache math
+
+KV cache holds keys+values for every token in context, per layer. It grows ~linearly with context
+length and is allocated on top of the weights:
+
+```text
+kv_GB ≈ 2 (K+V) × layers × ctx_tokens × kv_dim × bytes_per_elem / 1e9
+```
+
+You don't need the exact number — you need the shape: **doubling `num_ctx` roughly doubles the cache**,
+and on big models at long context the cache can rival or exceed the weights. Illustrative, large model:
+
+| Context (`num_ctx`) | KV cache (order of magnitude) |
+| --- | --- |
+| 4K | small (≪ weights) |
+| 32K | several GB |
+| 128K | tens of GB on a 70B — often more than the headroom you assumed |
+
+Shrink it: set `OLLAMA_KV_CACHE_TYPE=q8_0` (≈ half) or `q4_0` (≈ quarter) — a small accuracy cost for a
+big memory win. Or just cap `num_ctx` to what the task needs.
+
+## Apple Silicon (unified memory)
+
+On a Mac, weights + KV cache draw from the **single unified memory pool** shared with the OS and apps.
+Budget against total RAM minus what the system needs (leave several GB). A 64 GB Mac can comfortably run
+a 32B Q4_K_M; a 70B Q4_K_M is feasible but leaves little headroom for long context.
+
+**MLX backend gate.** Ollama can run an MLX backend on Apple Silicon (shipped in Ollama 0.19, per
+[ollama.com/blog/mlx](https://ollama.com/blog/mlx), 2026-03-30), but it requires a Mac with **more than
+32 GB of unified memory** — below that gate it stays on the default llama.cpp/GGUF engine. So MLX is not
+a universal Apple-Silicon win: a 16 GB or 32 GB Mac will not use it, and your sizing math is the same
+GGUF math as everywhere else. The 64 GB row above is where MLX actually kicks in.
+
+## Env knobs to fit tight boxes
+
+| Variable | Effect |
+| --- | --- |
+| `OLLAMA_KV_CACHE_TYPE` | `q8_0` / `q4_0` quantize the KV cache → less VRAM at long context |
+| `OLLAMA_FLASH_ATTENTION` | enable flash attention → lower memory + faster on supported GPUs |
+| `OLLAMA_NUM_PARALLEL` | concurrent requests per model; more = more KV cache allocated |
+| `OLLAMA_MAX_LOADED_MODELS` | how many models stay resident at once |
+| `OLLAMA_KEEP_ALIVE` | default unload timer (overrides the 5m default) |
+| `OLLAMA_HOST` | bind address/port |
+| `OLLAMA_MODELS` | where models are stored on disk |
+
+## Decision: fit, or leave the box
+
+1. Compute `weights_GB` for the model+quant you want.
+2. Add a KV-cache budget for your target `num_ctx` (and `OLLAMA_NUM_PARALLEL`).
+3. Add ~1–2 GB OS/overhead.
+4. If the total exceeds your VRAM/unified memory: shrink `num_ctx`, quantize the KV cache, or step the
+   model down one size — **not below Q4**.
+5. If it still doesn't fit at the quality you need: it's a remote-GPU job → `runpod` (rent a GPU),
+   `modal` (serverless + autoscale), or a hosted endpoint (`replicate`, `together-fireworks`, `fal`).