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

package/skills/shared/testing-web/scripts/verify.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — testing-web skill gate. Lints frontend test files for the load-bearing rules.
+#
+# Usage:  scripts/verify.sh [PATH]      (PATH = a test file or a directory; default: current dir)
+#
+# Read-only. Never executes the tests, never edits anything. It checks artifact SHAPE, not whether the
+# assertions are true.
+#
+# Discovers test files matching *.test.* / *.spec.* (.ts/.tsx/.js/.jsx), skipping node_modules/.git/dist.
+# Per file:
+#   HARD fail (exit 1):
+#     - zero `expect(`                                  -> a test that asserts nothing
+#     - a userEvent/`user.<verb>(` interaction not preceded by `await` on the same line
+#   WARN (advisory, never changes exit code):
+#     - getByTestId used while no getByRole/getByLabelText/getByText query is present
+#     - raw fireEvent( where userEvent would do
+#     - act( inside a component (non-hook) test file
+#     - setTimeout(-based waiting instead of waitFor/findBy
+#
+# An empty or clean target exits 0 (no false failure). Stock macOS bash 3.2 compatible.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+TARGET="${1:-.}"
+if [ ! -e "$TARGET" ]; then
+  err "path not found: $TARGET"
+  exit 1
+fi
+
+FILES=()
+if [ -f "$TARGET" ]; then
+  FILES+=("$TARGET")
+else
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$TARGET" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' -o -path '*/build/*' -o -path '*/coverage/*' \) -prune -o \
+      -type f \( -name '*.test.ts' -o -name '*.test.tsx' -o -name '*.test.js' -o -name '*.test.jsx' \
+                 -o -name '*.spec.ts' -o -name '*.spec.tsx' -o -name '*.spec.js' -o -name '*.spec.jsx' \) -print0 2>/dev/null
+  )
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  warn "no *.test.* / *.spec.* files found under $TARGET — nothing to lint"
+  ok "verify.sh passed (empty target)"
+  exit 0
+fi
+
+for f in "${FILES[@]}"; do
+  problems=0
+
+  # --- HARD: must contain at least one assertion ---
+  if ! grep -Eq 'expect[[:space:]]*\(' "$f"; then
+    err "$f: no expect(...) — a test must assert something observable"
+    problems=$((problems + 1))
+  fi
+
+  # --- HARD: every userEvent/user.<verb>( interaction must be awaited on its line ---
+  # Match interaction calls (user.click(, userEvent.type(, etc.) whose line lacks `await`.
+  unawaited="$(grep -nE '(^|[^a-zA-Z0-9_.])(user|userEvent)\.[a-zA-Z]+[[:space:]]*\(' "$f" 2>/dev/null \
+                | grep -vE '\bawait\b' \
+                | grep -vE '\.setup[[:space:]]*\(' || true)"
+  if [ -n "$unawaited" ]; then
+    err "$f: user-event interaction not awaited (await user.click/type/...):"
+    printf '%s\n' "$unawaited" | sed 's/^/      /'
+    problems=$((problems + 1))
+  fi
+
+  # --- WARN: testid as the only query (no role/label/text query present) ---
+  if grep -Eq 'getByTestId|findByTestId|queryByTestId' "$f"; then
+    if ! grep -Eq 'ByRole|ByLabelText|ByText|ByPlaceholderText|ByDisplayValue' "$f"; then
+      warn "$f: uses *ByTestId with no role/label/text query — climb the query ladder first"
+    fi
+  fi
+
+  # --- WARN: raw fireEvent ---
+  if grep -Eq '\bfireEvent\.' "$f"; then
+    warn "$f: uses fireEvent — prefer userEvent.setup() + await user.* for realistic events"
+  fi
+
+  # --- WARN: act( in a component (non-hook) test file ---
+  if grep -Eq '(^|[^a-zA-Z0-9_])act[[:space:]]*\(' "$f"; then
+    if ! grep -Eq 'renderHook' "$f"; then
+      warn "$f: bare act() in a component test — await findBy/waitFor instead"
+    fi
+  fi
+
+  # --- WARN: setTimeout-based waiting ---
+  if grep -Eq '\bsetTimeout[[:space:]]*\(' "$f" && ! grep -Eq 'waitFor|findBy' "$f"; then
+    warn "$f: waits with setTimeout and no waitFor/findBy — use waitFor/findBy to retry until ready"
+  fi
+
+  if [ "$problems" -eq 0 ]; then
+    ok "$f"
+  fi
+done
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then
+  ok "verify.sh passed"
+else
+  err "verify.sh found hard violations"
+fi
+exit "$EXIT"

package/skills/shared/together-fireworks/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: together-fireworks
+description: "Use when calling open-weight LLMs on Together AI or Fireworks AI's OpenAI-compatible endpoints — `base_url` plus namespaced model id, the cheapest model that clears the bar, per-1M-token cost math, serverless vs batch vs dedicated. NOT renting GPUs to self-host weights (that is `runpod`), NOT running a model locally for free (that is `ollama`)."
+tags: [llm, inference, together-ai, fireworks-ai, openai-compatible, open-models, batch, cost]
+recommends: [runpod, modal, ollama, huggingface, fal, cost-tracking, llm-pipeline, prompt-engineering, embeddings-search]
+origin: ai-hub
+---
+
+# together-fireworks
+
+You run open-weight LLMs on two neutral, OpenAI-compatible hosts: **Together AI** and **Fireworks AI**. Neither trains the flagship models — they host open weights (Llama, DeepSeek, Qwen, GPT-OSS, Kimi, Mistral) behind a billed-per-token endpoint. No GPU to provision, no server to babysit. You pay for tokens.
+
+Both speak the OpenAI wire protocol. So the entire mental model is: **same SDK, change three things — `base_url`, `api_key`, and the model id.** That is why these two providers live in one skill: the working knowledge (connect, pick a model, batch for 50% off, do the cost math) is ~90% shared. The only real differences are the base URL string and the model-id naming scheme. Learn both at once.
+
+This skill is *where the tokens come from*. Designing the prompt is `../prompt-engineering/SKILL.md`; chaining calls into a workflow is `../llm-pipeline/SKILL.md`; tracking spend across many providers as a discipline is `../cost-tracking/SKILL.md`. Here you only do the per-model math and the endpoint plumbing.
+
+## The two endpoints (memorize these)
+
+| Provider | `base_url` | Model id shape | Examples (illustrative — confirm on the serverless catalog) |
+|---|---|---|---|
+| Together | `https://api.together.ai/v1` | `<vendor>/<model>` | `openai/gpt-oss-20b`, `meta-llama/Llama-3.3-70B-Instruct-Turbo`, `deepseek-ai/DeepSeek-V4-Pro` |
+| Fireworks | `https://api.fireworks.ai/inference/v1` | `accounts/fireworks/models/<name>` | `accounts/fireworks/models/gpt-oss-20b`, `accounts/fireworks/models/llama-v3p1-8b-instruct` |
+
+The example ids show the *shape* of a valid id, not a guaranteed-live id — the catalog churns and casing matters. Before you ship any id, confirm the exact string on the provider's own catalog (docs.together.ai/docs/serverless-models, docs.fireworks.ai/serverless/pricing). A plausible-looking id that is not in the catalog 404s exactly like a typo, so an unconfirmed id is a bug, not a default.
+
+The #1 failure is a bare model name. `model="llama-3.3-70b"` returns **404 model not found** on both — the id MUST carry its namespace prefix.
+
+## Connect in 30 seconds
+
+Use the official `openai` SDK. Do not install a provider-specific client unless you need a provider-only feature (Together's native Batch API, below).
+
+```python
+import os
+from openai import OpenAI
+
+# Together
+together = OpenAI(
+    base_url="https://api.together.ai/v1",
+    api_key=os.environ["TOGETHER_API_KEY"],   # never a string literal
+)
+r = together.chat.completions.create(
+    model="openai/gpt-oss-20b",               # namespaced — vendor/model
+    messages=[{"role": "user", "content": "Classify: spam or ham?"}],
+)
+
+# Fireworks — same SDK, three things change
+fireworks = OpenAI(
+    base_url="https://api.fireworks.ai/inference/v1",
+    api_key=os.environ["FIREWORKS_API_KEY"],
+)
+r = fireworks.chat.completions.create(
+    model="accounts/fireworks/models/gpt-oss-120b",  # accounts/fireworks/models/<name>
+    messages=[{"role": "user", "content": "Explain this stack trace."}],
+)
+```
+
+```javascript
+import OpenAI from "openai";
+
+const fireworks = new OpenAI({
+  baseURL: "https://api.fireworks.ai/inference/v1",
+  apiKey: process.env.FIREWORKS_API_KEY,
+});
+
+const r = await fireworks.chat.completions.create({
+  model: "accounts/fireworks/models/llama-v3p1-8b-instruct", // namespaced
+  messages: [{ role: "user", content: "Summarize in one line." }],
+});
+```
+
+- **Bad → Good (model id):** `model="gpt-oss-120b"` → `model="openai/gpt-oss-120b"` (Together) or `model="accounts/fireworks/models/gpt-oss-120b"` (Fireworks). Why: the compat layer routes by the full namespaced id; a bare name has no route → 404.
+- **Bad → Good (base_url):** `base_url="https://api.openai.com/v1"` with a Together key → auth error / wrong models. Why: a Together/Fireworks key only authenticates against its own host.
+- **Bad → Good (key):** `api_key="sk-..."` literal → `api_key=os.environ["TOGETHER_API_KEY"]`. Why: a committed key is a leaked key.
+
+`client.embeddings.create()` works identically on both for embedding models — same surface, just swap the model id.
+
+## Pick the model
+
+Match the task to the smallest model that clears the quality bar. Every $/1M figure below is **per 1M tokens, input/output, USD**, read directly off each **provider's own pricing page** on 2026-06-02 (Together: together.ai/pricing; Fireworks: docs.fireworks.ai/serverless/pricing) — never a tracker. Confirm the exact id string and rate at that page before you ship; casing and suffixes (`-Turbo`, `-Lite`) are load-bearing, and a plausible id absent from the catalog 404s like a typo.
+
+Rows tagged **(projected)** are current-generation flagships whose id and price move fast and that you may not recognize from older training data — the number is the page's figure on 2026-06-02, but re-read the page before you quote one. Untagged rows are long-lived ids with stable pricing; the worked examples and defaults below lean on these on purpose.
+
+| Task | Together id + $/1M (in/out) | Fireworks id + $/1M (in/out) |
+|---|---|---|
+| Cheap classify / extract / tag | `openai/gpt-oss-20b` — $0.05 / $0.20 | `accounts/fireworks/models/gpt-oss-20b` — $0.07 / $0.30 |
+| Small instruct | `meta-llama/Meta-Llama-3-8B-Instruct-Lite` — $0.14 / $0.14 | `accounts/fireworks/models/llama-v3p1-8b-instruct` — 4B–16B tier, $0.20 |
+| General chat | `meta-llama/Llama-3.3-70B-Instruct-Turbo` — $1.04 / $1.04 | `accounts/fireworks/models/gpt-oss-120b` — $0.15 / $0.60 |
+| Reasoning / hard tasks | `deepseek-ai/DeepSeek-V4-Pro` — $2.10 / $4.40 *(projected)* | `accounts/fireworks/models/deepseek-v4-pro` — $1.74 / $3.48 *(projected)* |
+| Cheaper reasoning | `Qwen/Qwen3.6-Plus` — $0.50 / $3.00 (watch output) *(projected)* | `accounts/fireworks/models/deepseek-v4-flash` — $0.14 / $0.28 *(projected)*; `kimi-k2p6` — $0.95 / $4.00 *(projected)* |
+| Long context (≥512K) | `Qwen/Qwen3.6-Plus` (1M ctx) *(projected)*; `deepseek-ai/DeepSeek-V4-Pro` (512K serverless) *(projected)* | size/MoE tier — see fallback below |
+| Embeddings | `intfloat/multilingual-e5-large-instruct` — $0.02 / 1M input | embeddings — $0.008–$0.10 / 1M input (by param count) |
+
+Rules:
+- **Output tokens cost 3–7× input.** A reasoning model that thinks for 2k tokens before answering is the expensive part — budget on output, not input. Qwen3.6-Plus is the trap: $0.50 in but $3.00 out.
+- **Fireworks size-tiered fallback** (published on docs.fireworks.ai/serverless/pricing, applies to any model with no named price): <4B $0.10, 4B–16B $0.20, >16B (dense) $0.90, MoE ≤56B $0.50, MoE 56.1B–176B $1.20 per 1M. Use the matching tier to estimate a model not in the named list — these are the provider's own published numbers, so they hold up in a quote (still confirm the specific model's tier).
+- **Default to the cheap small model and only escalate when an eval shows it fails.** Most "we need DeepSeek V4-Pro" is a gpt-oss-20b job in disguise.
+
+Fuller catalog and embedding/fine-tuning numbers: `references/models-and-pricing.md`.
+
+## Serverless vs Batch vs Dedicated
+
+| Serving mode | Use when | The economics |
+|---|---|---|
+| **Serverless** (default) | Real-time, user-facing, bursty, low/spiky volume | Pay per token, no commitment, cold-tolerant |
+| **Batch** | Offline job, no latency need, > ~1k requests | **~50% off** serverless on both providers |
+| **Dedicated** GPU | Sustained high QPS, fixed latency SLA, huge volume | Pay for the GPU-hour; pays off only above a high, steady load |
+
+Decision: **real-time → serverless. Big offline job (eval, synthetic data, bulk classify) → batch. Sustained heavy traffic with an SLA → dedicated.**
+
+> **Gotcha — Together batch is NOT the OpenAI Batch endpoint.** Together's OpenAI-compat layer does **not** expose `/v1/batches`. Use Together's **native Batch API**: upload a JSONL file, default **24h** window, up to **50,000 requests/file**, up to **50% off**, separate rate-limit pool. Pointing the OpenAI Batch client at Together fails. Fireworks instead exposes Batch as a serving *path* through the one API (Serverless 2.0: Standard / Priority / Batch), batch = 50% of serverless. JSONL shape, the upload/poll/download flow, limits, and dedicated-deployment notes: `references/batch-and-tuning.md`.
+
+Two more Fireworks multipliers worth knowing:
+- **Cached input tokens default to 50%** of input price (text/vision models) — repeated prefixes get cheaper automatically.
+- **Priority serving ≈ 1.5× Standard.** Priority is opt-in, not the default; do not budget at Priority rates unless you set it.
+
+## Cost & latency math
+
+Per request:
+
+```text
+cost = (in_tokens * in_price_per_1M + out_tokens * out_price_per_1M) / 1_000_000
+```
+
+Apply the multipliers: cached input → `in_price * 0.5` on the cached portion; Priority → `* 1.5`; Batch → `total * 0.5`.
+
+Worked example — 1,000,000 input + 500,000 output tokens, one shot. Both anchors are **stable** ids (gpt-oss, Llama 3.3 70B), so the arithmetic stays checkable even after the flagship rows churn:
+
+- **GPT-OSS 20B on Together**, serverless: `(1M*0.05 + 0.5M*0.20)/1e6 = $0.05 + $0.10 = $0.15`.
+- **GPT-OSS 120B on Together**, serverless: `(1M*0.15 + 0.5M*0.60)/1e6 = $0.15 + $0.30 = $0.45` — 3× the 20B for the bigger open GPT-OSS.
+- **Llama 3.3 70B on Together**, serverless: `(1M*1.04 + 0.5M*1.04)/1e6 = $1.04 + $0.52 = $1.56` — ~10× the 20B for general chat.
+- Same Llama 3.3 70B job **as batch**: `$1.56 * 0.5 = $0.78`.
+- Escalating to a *(projected)* reasoning flagship (e.g. DeepSeek V4-Pro at $2.10/$4.40 on the 2026-06-02 page) lands near `$4.30` serverless / `$2.15` batch — ~29× the 20B — but re-read the page before you commit to that number.
+
+So for a large offline run the lever is *model choice first* (up to ~29×), *batch second* (2×). Pick the smallest model that passes the eval AND batch it. Realtime is only worth its premium when a human is waiting.
+
+## Write provider-agnostic code
+
+Drive `base_url` and `model` from env so you can switch providers (or arbitrage price) without touching code. Why: these are commodity endpoints — portability is leverage.
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    base_url=os.environ["LLM_BASE_URL"],   # together or fireworks URL
+    api_key=os.environ["LLM_API_KEY"],
+)
+model = os.environ["LLM_MODEL"]            # the namespaced id for that provider
+```
+
+Equivalent ids for the same underlying model:
+
+| Model | Together id | Fireworks id |
+|---|---|---|
+| Llama 3.1 8B Instruct | `meta-llama/Llama-3.1-8B-Instruct-Turbo` | `accounts/fireworks/models/llama-v3p1-8b-instruct` |
+| DeepSeek V4-Pro | `deepseek-ai/DeepSeek-V4-Pro` | `accounts/fireworks/models/deepseek-v4-pro` |
+| GPT-OSS 20B | `openai/gpt-oss-20b` | `accounts/fireworks/models/gpt-oss-20b` |
+
+Keep the id mapping in config, not in `if provider == ...` branches scattered through the code.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Bare model name (`llama-3.3-70b`) | 404 model not found — the route needs the namespace | Use the full `<vendor>/...` or `accounts/fireworks/models/...` id |
+| Together/Fireworks key against `api.openai.com` | Auth fails / wrong model set; key only works on its own host | Set the matching `base_url` for the key you hold |
+| Hardcoded API key string literal | Committed key = leaked key | `os.environ[...]` / `process.env.*` only |
+| Pointing the OpenAI Batch client at Together | Compat layer has no `/v1/batches` | Together native Batch API (JSONL upload, 24h, 50k/file) |
+| Serverless for a 200k-row offline eval | Pays full price for work with no latency need | Batch it — ~50% off on both |
+| Budgeting at Priority rates | Priority ≈ 1.5× and is opt-in, not default | Price at Standard unless you explicitly enable Priority |
+| Reaching for DeepSeek V4-Pro by reflex | ~20–30× the cost of a 20B model that may pass the eval | Start at the cheap small model; escalate only on eval failure |
+| Quoting a price/id from an aggregator | Trackers lag and mis-list — e.g. DeepSeek-V3.1 shown as live on Together when it is not on the serverless catalog | Cite together.ai/pricing or docs.fireworks.ai; confirm the id on the serverless catalog before quoting |
+| Treating these like free/local | They bill per token; ollama is the zero-marginal-cost path | If cost must be zero and weights run on your box → `../ollama/SKILL.md` |
+| Renting GPUs to "save money" then idling them | A serverless token endpoint has no idle cost | Self-host only at sustained scale → `../runpod/SKILL.md` |
+
+Validate any inference snippet/config with `scripts/verify.sh <file-or-dir>` — a static, no-network lint for the right base URLs, namespaced model ids, and env-var keys.

package/skills/shared/together-fireworks/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — together-fireworks
+
+`cases.yaml` holds three things: `should_trigger` (prompts that must route into this skill, including the non-obvious "404 model not found" namespace bug and Spanish/Catalan phrasings), `should_not_trigger` (prompts that belong to a named sibling — `runpod`, `ollama`, `fal`, `huggingface`, `prompt-engineering`, `rag` — for the self-host / local / media / hub / prompt-design / pipeline boundaries), and one `capability` scenario with a `must_include` rubric. There is no automated runner here: route each trigger prompt through your skill-selection harness and confirm it lands (or doesn't) as labelled, then have an agent run the capability scenario and hand-score the output — every `must_include` line should be present (correct base_url + namespaced id, batch + 50% discount, the cost formula with dated numbers, the Together-native-Batch-API note). To structurally check any inference snippet the skill produces, run `../scripts/verify.sh <file-or-dir>`; a clean rubric pass plus a clean verify run is the bar.

package/skills/shared/together-fireworks/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: together-fireworks
+
+should_trigger:
+  - prompt: "Wire up the OpenAI SDK to call DeepSeek on Together AI."
+    why: Core job — point the OpenAI SDK at api.together.ai with the right base_url and namespaced model id.
+  - prompt: "My Fireworks call returns 404 model not found, here's my code."
+    why: Non-obvious — the classic bare-model-name bug; the fix is the accounts/fireworks/models/ namespace, squarely this skill.
+  - prompt: "Cut our open-model inference bill in half for a 200k-row classification job."
+    why: Batch-discount trigger — offline volume + cost; routes to the 50%-off batch decision, not generic cost tracking.
+  - prompt: "¿Qué modelo open source uso en Fireworks y cuánto me cuesta por millón de tokens?"
+    why: Spanish + model choice + per-1M cost — the pick-the-model decision table is this skill.
+  - prompt: "We're on GPT-4 but want a cheaper open-weights endpoint, same code if possible."
+    why: Migration trigger — OpenAI-compatible host means change base_url + key + model id only.
+  - prompt: "Should I use serverless or dedicated on Fireworks for 50 QPS sustained?"
+    why: Serving-mode decision (serverless vs batch vs dedicated) is a core section of this skill.
+  - prompt: "Abaratar la factura d'inferència fent servir batch a Together."
+    why: Catalan + the Together-native-Batch-API gotcha — not the OpenAI Batch endpoint.
+
+should_not_trigger:
+  - prompt: "Spin up an A100 pod and run vLLM myself."
+    route_to: runpod
+    why: Raw GPU self-host — you manage the box; this skill is a per-token hosted endpoint.
+  - prompt: "Run Llama locally on my Mac with no API cost."
+    route_to: ollama
+    why: Local/offline, zero marginal cost; together-fireworks is cloud pay-per-token.
+  - prompt: "Generate images with FLUX on a hosted endpoint."
+    route_to: fal
+    why: Media generation, not text/chat/embeddings LLM inference.
+  - prompt: "Deploy a model from the Hugging Face hub as an inference endpoint."
+    route_to: huggingface
+    why: HF hub + HF Inference Endpoints, a different host with its own ids.
+  - prompt: "Help me write a better system prompt for my chatbot."
+    route_to: prompt-engineering
+    why: Prompt design, not the hosting endpoint where tokens are billed.
+  - prompt: "Build the retrieval + reranking pipeline for my docs."
+    route_to: rag
+    why: A pipeline built on top of inference, not the inference endpoint itself.
+
+capability:
+  - scenario: >
+      A user has a 500,000-document text classification job, no real-time latency
+      requirement, and a tight budget. Recommend a provider, a model with its exact
+      id, a serving mode, and estimate the cost.
+    must_include:
+      - Picks batch inference and states it is ~50% off serverless on both providers.
+      - Names a cheap small model with a concrete namespaced id from a stable (non-projected) row (e.g. openai/gpt-oss-20b on Together, or a Fireworks <4B/4B-16B tier id) — not a fast-moving flagship.
+      - Applies the cost formula (in_tokens*in_price + out_tokens*out_price)/1e6 with the $/1M numbers as read off the provider page on 2026-06-02 and the 0.5 batch multiplier; any flagship/(projected) figure is flagged "re-read the page before quoting".
+      - Uses the correct base_url and a namespaced model id (no bare model name).
+      - Notes that Together uses its native Batch API (JSONL upload), not the OpenAI /v1/batches endpoint.
+      - Prioritizes model choice (cheap small model) over serving mode as the bigger cost lever.

package/skills/shared/together-fireworks/references/batch-and-tuning.md

@@ -0,0 +1,59 @@
+# Batch, dedicated & fine-tuning — Together / Fireworks
+
+Facts dated 2026-06-02. Re-check the provider batch docs before relying on limits.
+
+## Together native Batch API (NOT the OpenAI Batch endpoint)
+
+Together's OpenAI-compat layer does **not** expose `/v1/batches`. Pointing the OpenAI Batch client at Together fails. Use Together's **native** Batch API.
+
+**Limits:** default **24h** completion window, up to **50,000 requests/file**, up to **50% off** serverless pricing, **separate rate-limit pool** from real-time.
+
+**JSONL request file** — one request per line:
+
+```jsonl
+{"custom_id": "req-1", "body": {"model": "openai/gpt-oss-20b", "messages": [{"role": "user", "content": "Label as spam or ham: ..."}]}}
+{"custom_id": "req-2", "body": {"model": "openai/gpt-oss-20b", "messages": [{"role": "user", "content": "Label as spam or ham: ..."}]}}
+```
+
+**Flow** (use the `together` SDK or REST):
+
+```python
+from together import Together
+
+client = Together()  # reads TOGETHER_API_KEY from env
+
+up = client.files.upload(file="requests.jsonl", purpose="batch-api")
+job = client.batches.create_batch(file_id=up.id, endpoint="/v1/chat/completions")
+
+# poll until terminal
+status = client.batches.get_batch(job.id)   # PENDING -> IN_PROGRESS -> COMPLETED / FAILED
+
+# on COMPLETED, download the output file id and parse one JSON result per line,
+# matched back to requests by custom_id.
+```
+
+Each output line carries the `custom_id` so you can join results back to inputs. Handle `FAILED`/partial lines — a row erroring does not fail the whole job.
+
+## Fireworks batch (a serving path, not a separate API)
+
+Fireworks **Serverless 2.0** exposes Standard / Priority / **Batch** through the same API. Batch = **50%** of serverless price on input and output. You select the batch path per request/config rather than uploading a separate JSONL job. Priority (≈1.5×) works with both OpenAI- and Anthropic-compatible endpoints.
+
+## When batch pays off
+
+- No human waiting on the response (eval runs, synthetic-data generation, bulk classification/extraction, backfills).
+- More than ~1k requests — the 50% cut clears any added orchestration overhead.
+- You can tolerate the completion window (Together default 24h).
+
+Do **not** batch a user-facing request — the latency window makes it unusable in real time.
+
+## Dedicated deployments
+
+Both providers offer reserved-GPU / dedicated endpoints billed by GPU-hour (not per token). It only beats serverless above a **high, sustained** QPS or when you need a **fixed latency SLA** or a model not on the serverless menu. Below that load, an idle dedicated GPU burns money a token endpoint never would. If you are leaning dedicated mostly to control infra, that is the self-host tradeoff — compare against renting raw GPUs (`../runpod/SKILL.md`, `../modal/SKILL.md`).
+
+## Fine-tuning (Together)
+
+Tiered per 1M training tokens (together.ai/pricing, 2026-06-02): up to 16B SFT **$0.48** / Full $1.20–$1.35; 17B–69B SFT **$1.50**; 70B–100B SFT **$2.90** / Full $7.25–$8.00 — the published size tiers **stop at 70B–100B; there is no 405B tier**. Beyond that the catalog prices by named specialized model, not size (DeepSeek-R1 SFT $10.00 / DPO $25.00; Llama 4 Maverick SFT $8.00 / DPO $20.00). Serve the result on a dedicated deployment. Re-check the pricing page — these tiers shift.
+
+## Sources (accessed 2026-06-02)
+- https://docs.together.ai/docs/inference/batch/overview · https://www.together.ai/blog/batch-api
+- https://fireworks.ai/blog/serverless-2 · https://docs.fireworks.ai/serverless/pricing

package/skills/shared/together-fireworks/references/models-and-pricing.md

@@ -0,0 +1,79 @@
+# Models & pricing — Together AI / Fireworks AI
+
+Every figure here is **per 1M tokens, USD**, and was read directly off the provider's own pricing/model page on **2026-06-02**. No number on this page is sourced to a third-party tracker — aggregators are addressed (and excluded) in the last section. Prices move and ids get retired; **re-read the primary page before quoting a customer**:
+- Together pricing (authoritative $/1M): https://www.together.ai/pricing — read 2026-06-02
+- Together serverless model catalog (authoritative id list): https://docs.together.ai/docs/serverless-models — read 2026-06-02
+- Fireworks serverless pricing (authoritative $/1M + id): https://docs.fireworks.ai/serverless/pricing — read 2026-06-02
+
+Rule of thumb for grounding: every $/1M figure and every model id below traces to one of the three pages above, as read on the date stated. If you cannot find a model on the provider's own catalog, treat the id as unverified and do not quote it — a tracker listing is not a confirmation.
+
+## Together AI
+
+Base URL `https://api.together.ai/v1`. Model id shape `<vendor>/<model>`. Confirm the exact id string and rate on docs.together.ai/docs/serverless-models and together.ai/pricing before quoting — casing and suffixes (`-Turbo`, `-Lite`) are load-bearing.
+
+Each row's `V` column is the verifiability of the **id + price** as read off together.ai/pricing on 2026-06-02:
+- **stable** — long-lived id, low price churn; safe to quote after a glance at the page.
+- **projected** — current-generation flagship whose id/price moves fast (and whose id you may not recognize from training data); the number is the page's figure on this date, but treat it as a moving target and re-read the page before any quote.
+
+| Model | Model id | Input $/1M | Output $/1M | V | Notes |
+|---|---|---|---|---|---|
+| GPT-OSS 20B | `openai/gpt-oss-20b` | 0.05 | 0.20 | stable | cheapest; classify/extract |
+| GPT-OSS 120B | `openai/gpt-oss-120b` | 0.15 | 0.60 | stable | bigger open GPT-OSS |
+| Llama 3 8B Instruct Lite | `meta-llama/Meta-Llama-3-8B-Instruct-Lite` | 0.14 | 0.14 | stable | small & fast, 8K ctx |
+| Llama 3.3 70B | `meta-llama/Llama-3.3-70B-Instruct-Turbo` | 1.04 | 1.04 | stable | general chat |
+| Qwen 3.6 Plus | `Qwen/Qwen3.6-Plus` | 0.50 | 3.00 | projected | high output cost — watch it; ~1M ctx |
+| DeepSeek V4-Pro | `deepseek-ai/DeepSeek-V4-Pro` | 2.10 | 4.40 | projected | top reasoning; $0.20 cached input; 512K serverless ctx (1M on dedicated) |
+
+Not on Together serverless as of this date (do **not** quote these ids against Together): `deepseek-ai/DeepSeek-V3.1`, `meta-llama/Llama-4-Maverick-*`. They appear on aggregators but are absent from the provider's own serverless catalog — confirm at docs.together.ai/docs/serverless-models.
+
+**Embeddings:** `intfloat/multilingual-e5-large-instruct` — $0.02 / 1M input tokens (together.ai/pricing). Confirm the exact id/price on the pricing page before quoting.
+
+**Fine-tuning** (together.ai/pricing, per 1M training tokens): up to 16B — SFT $0.48 / DPO $0.54 / Full $1.20–$1.35; 17B–69B — SFT $1.50 / DPO $1.65 / Full $3.75–$4.12; 70B–100B — SFT $2.90 / DPO $3.20 / Full $7.25–$8.00. The standard size tiers stop at **70B–100B — there is no published 405B tier** as of this date; a >100B fine-tune runs as one of the specialized models, not a size tier. Specialized: DeepSeek-R1 SFT $10.00 / DPO $25.00 (min $20.00); Llama 4 Maverick SFT $8.00 / DPO $20.00 (min $16.00). Serve the result on a dedicated deployment.
+
+## Fireworks AI
+
+Base URL `https://api.fireworks.ai/inference/v1`. Model id shape `accounts/fireworks/models/<name>`.
+
+**Size-tiered base pricing** (docs.fireworks.ai/serverless/pricing; applies in and out, for any model without a named price):
+
+| Model size | $/1M (input and output) |
+|---|---|
+| < 4B | 0.10 |
+| 4B – 16B | 0.20 |
+| > 16B (dense) | 0.90 |
+| MoE ≤ 56B (e.g. Mixtral 8x7B) | 0.50 |
+| MoE 56.1B – 176B (e.g. DBRX, Mixtral 8x22B) | 1.20 |
+
+These are the provider's own published tiers, so they hold up as a sizing estimate in a quote. They are not a per-model promise — the named-model prices below override the tier where a model is explicitly listed.
+
+**Named models** (docs.fireworks.ai/serverless/pricing — input / cached input / output, Standard tier). `V` = verifiability of id+price as read on 2026-06-02 (same legend as the Together table: **stable** = long-lived; **projected** = fast-moving current flagship, re-read the page before quoting):
+
+| Model | Model id | Input | Cached | Output | V |
+|---|---|---|---|---|---|
+| GPT-OSS 20B | `accounts/fireworks/models/gpt-oss-20b` | 0.07 | 0.035 | 0.30 | stable |
+| GPT-OSS 120B | `accounts/fireworks/models/gpt-oss-120b` | 0.15 | 0.015 | 0.60 | stable |
+| Llama 3.1 8B Instruct | `accounts/fireworks/models/llama-v3p1-8b-instruct` | 4B–16B tier (0.20) | — | 4B–16B tier (0.20) | stable |
+| Kimi K2.6 | `accounts/fireworks/models/kimi-k2p6` | 0.95 | 0.16 | 4.00 | projected |
+| DeepSeek V4-Pro | `accounts/fireworks/models/deepseek-v4-pro` | 1.74 | 0.145 | 3.48 | projected |
+| DeepSeek V4 Flash | `accounts/fireworks/models/deepseek-v4-flash` | 0.14 | 0.028 | 0.28 | projected |
+
+Note `gpt-oss-20b` on Fireworks is $0.07/$0.30, slightly above Together's $0.05/$0.20 for the same weights — the kind of arbitrage the env-driven config in SKILL.md lets you exploit.
+
+**Embeddings:** input only — up to 150M params $0.008, 150M–350M $0.016, Qwen3 8B $0.10 / 1M input (docs.fireworks.ai/serverless/pricing).
+
+**Multipliers** (docs.fireworks.ai/serverless/pricing):
+- **Cached input** defaults to **50%** of input price on text/vision models (named models above publish a lower cached figure — use the published one when available).
+- **Priority serving** is opt-in and runs above Standard — the page lists priority per model (e.g. Kimi K2.6 priority input $1.50 vs $0.95 standard, ≈1.5–1.6×). Do not budget at priority rates unless you enable it.
+- **Batch = 50%** of serverless on both input and output.
+- **Serverless 2.0** routes Standard / Priority / Batch through one API; Priority works with OpenAI- and Anthropic-compatible endpoints.
+
+## Aggregators (use only for cross-provider sizing, never for a per-model quote)
+
+Third-party trackers (Artificial Analysis, aipricing.guru, lmmarketcap, costbench) are useful for a *blended* sense of where the catalog sits but routinely lag and mis-attribute per-model rates — e.g. they still list DeepSeek-V3.1 as a live Together serverless model. For any dollar figure you put in front of a customer, cite the provider page above, not an aggregator.
+
+## Sources (accessed 2026-06-02)
+- https://docs.together.ai/docs/serverless-models
+- https://www.together.ai/pricing
+- https://www.together.ai/blog/deepseek-v4-pro-now-available-on-together-ai
+- https://docs.fireworks.ai/serverless/pricing
+- https://docs.together.ai/docs/openai-api-compatibility