@warlock.js/ai-groq 4.6.0

package/esm/known-models.d.mts

@@ -0,0 +1,62 @@
+//#region ../@warlock.js/ai-groq/src/known-models.d.ts
+/**
+ * Default base URL for Groq's OpenAI-compatible Chat Completions
+ * endpoint. Groq exposes the same wire protocol as OpenAI under this
+ * prefix, which is exactly why `GroqSDK` can delegate to the
+ * battle-tested `OpenAISDK` instead of reimplementing the transport.
+ *
+ * Verified against Groq's "OpenAI Compatibility" docs (mid-2026).
+ * Override via `new GroqSDK({ baseURL })` if Groq ever relocates it.
+ */
+declare const GROQ_BASE_URL = "https://api.groq.com/openai/v1";
+/**
+ * The provider label every model produced by `GroqSDK` self-identifies
+ * with. Flows through to `ModelContract.provider`, `AgentReport.model`,
+ * logs, and any provider-aware middleware. Kept as a constant so the
+ * wrapper and the inner `OpenAISDK` agree on one spelling.
+ */
+declare const GROQ_PROVIDER = "groq";
+/**
+ * Infer whether a Groq-hosted model id supports vision based on the
+ * known multimodal-family substrings. Unknown ids default to `false`
+ * so passing an image attachment to a text-only model (e.g.
+ * `llama-3.3-70b-versatile`) surfaces a clear, agent-side capability
+ * error instead of an opaque upstream 400.
+ *
+ * @example
+ * inferVisionCapability("openai/gpt-oss-120b");        // → true
+ * inferVisionCapability("meta-llama/llama-4-scout");   // → true
+ * inferVisionCapability("llama-3.3-70b-versatile");    // → false
+ * inferVisionCapability("llama-3.1-8b-instant");       // → false
+ */
+declare function inferVisionCapability(modelId: string): boolean;
+/**
+ * Infer whether a Groq-hosted model id is a reasoning model based on
+ * the known reasoning-family substrings. Unknown ids default to `false`
+ * so the adapter never forwards an unsupported `reasoning_effort` param
+ * to a non-reasoning model (which would 400).
+ *
+ * @example
+ * inferReasoningCapability("openai/gpt-oss-20b");           // → true
+ * inferReasoningCapability("deepseek-r1-distill-llama-70b"); // → true
+ * inferReasoningCapability("llama-3.3-70b-versatile");      // → false
+ */
+declare function inferReasoningCapability(modelId: string): boolean;
+/**
+ * Curated list of current Groq production chat model ids (mid-2026),
+ * for autocomplete, docs, and default selection. NOT exhaustive and NOT
+ * a runtime allow-list — `groq.model({ name })` accepts any string, so
+ * a newly launched id works the moment Groq ships it without a package
+ * bump. Deprecated ids (e.g. several `llama-4` variants retired in 2026)
+ * are intentionally excluded.
+ *
+ * - `llama-3.3-70b-versatile` — flagship general-purpose text model.
+ * - `llama-3.1-8b-instant` — fastest/cheapest small text model.
+ * - `openai/gpt-oss-120b` / `openai/gpt-oss-20b` — OpenAI open-weight
+ *   family; vision + reasoning capable.
+ * - `deepseek-r1-distill-llama-70b` — DeepSeek-R1-style reasoning.
+ */
+declare const GROQ_KNOWN_MODELS: readonly ["llama-3.3-70b-versatile", "llama-3.1-8b-instant", "openai/gpt-oss-120b", "openai/gpt-oss-20b", "deepseek-r1-distill-llama-70b"];
+//#endregion
+export { GROQ_BASE_URL, GROQ_KNOWN_MODELS, GROQ_PROVIDER, inferReasoningCapability, inferVisionCapability };
+//# sourceMappingURL=known-models.d.mts.map

package/esm/known-models.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-models.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai-groq/src/known-models.ts"],"mappings":";;AASA;;;;AAA0B;AAQ1B;;;cARa,aAAA;AAQa;AAkE1B;;;;AAAqD;AAlE3B,cAAb,aAAA;;;;AAmF2C;AAoBxD;;;;AAMU;;;;;iBA3CM,qBAAA,CAAsB,OAAe;;;;;;;;;;;;iBAiBrC,wBAAA,CAAyB,OAAe;;;;;;;;;;;;;;;cAoB3C,iBAAA"}

package/esm/known-models.mjs

@@ -0,0 +1,124 @@
+//#region ../@warlock.js/ai-groq/src/known-models.ts
+/**
+* Default base URL for Groq's OpenAI-compatible Chat Completions
+* endpoint. Groq exposes the same wire protocol as OpenAI under this
+* prefix, which is exactly why `GroqSDK` can delegate to the
+* battle-tested `OpenAISDK` instead of reimplementing the transport.
+*
+* Verified against Groq's "OpenAI Compatibility" docs (mid-2026).
+* Override via `new GroqSDK({ baseURL })` if Groq ever relocates it.
+*/
+const GROQ_BASE_URL = "https://api.groq.com/openai/v1";
+/**
+* The provider label every model produced by `GroqSDK` self-identifies
+* with. Flows through to `ModelContract.provider`, `AgentReport.model`,
+* logs, and any provider-aware middleware. Kept as a constant so the
+* wrapper and the inner `OpenAISDK` agree on one spelling.
+*/
+const GROQ_PROVIDER = "groq";
+/**
+* Substrings identifying Groq-hosted model ids whose family accepts
+* image input (vision).
+*
+* Groq hosts *open* models on its LPU hardware, so the ids are the
+* upstream open-weight names rather than OpenAI's — which is why the
+* OpenAI adapter's `gpt-4o*` prefix inference would never fire here and
+* this provider must carry its OWN list. Verified against Groq's
+* supported-models catalog (mid-2026):
+*
+* - `openai/gpt-oss-*` — natively multimodal OpenAI open-weight family
+*   (the current production vision + reasoning models on Groq).
+* - `llama-4` / `llama-3.2-*-vision` — Meta's multimodal Llama families.
+*   Kept as substrings so any still-hosted or re-introduced variant is
+*   covered even though some `llama-4` ids were deprecated in 2026.
+*
+* Matched as a substring (not a prefix) because Groq prefixes several
+* ids with an org segment (`openai/`, `meta-llama/`) and appends size /
+* date suffixes. Override per-model via
+* `groq.model({ name, vision: true | false })`.
+*/
+const VISION_CAPABLE_SUBSTRINGS = [
+	"gpt-oss",
+	"llama-4",
+	"llama-3.2-11b-vision",
+	"llama-3.2-90b-vision",
+	"vision"
+];
+/**
+* Substrings identifying Groq-hosted model ids that expose an internal
+* reasoning / thinking channel and accept the `reasoning_effort`
+* request parameter on the OpenAI-compatible Chat Completions endpoint.
+*
+* Verified against Groq's catalog (mid-2026):
+* - `gpt-oss` — the OpenAI open-weight family reasons by default.
+* - `deepseek-r1-distill` — DeepSeek-R1-style reasoning at Groq speed.
+* - `qwq` / `qwen3` — Qwen reasoning families (when hosted).
+*
+* Matched as a substring for the same org-prefix / suffix reason as the
+* vision list. Override per-model via
+* `groq.model({ name, reasoning: true | false })`.
+*/
+const REASONING_CAPABLE_SUBSTRINGS = [
+	"gpt-oss",
+	"deepseek-r1",
+	"deepseek-r1-distill",
+	"qwq",
+	"qwen3"
+];
+/**
+* Infer whether a Groq-hosted model id supports vision based on the
+* known multimodal-family substrings. Unknown ids default to `false`
+* so passing an image attachment to a text-only model (e.g.
+* `llama-3.3-70b-versatile`) surfaces a clear, agent-side capability
+* error instead of an opaque upstream 400.
+*
+* @example
+* inferVisionCapability("openai/gpt-oss-120b");        // → true
+* inferVisionCapability("meta-llama/llama-4-scout");   // → true
+* inferVisionCapability("llama-3.3-70b-versatile");    // → false
+* inferVisionCapability("llama-3.1-8b-instant");       // → false
+*/
+function inferVisionCapability(modelId) {
+	const normalized = modelId.toLowerCase();
+	return VISION_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));
+}
+/**
+* Infer whether a Groq-hosted model id is a reasoning model based on
+* the known reasoning-family substrings. Unknown ids default to `false`
+* so the adapter never forwards an unsupported `reasoning_effort` param
+* to a non-reasoning model (which would 400).
+*
+* @example
+* inferReasoningCapability("openai/gpt-oss-20b");           // → true
+* inferReasoningCapability("deepseek-r1-distill-llama-70b"); // → true
+* inferReasoningCapability("llama-3.3-70b-versatile");      // → false
+*/
+function inferReasoningCapability(modelId) {
+	const normalized = modelId.toLowerCase();
+	return REASONING_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));
+}
+/**
+* Curated list of current Groq production chat model ids (mid-2026),
+* for autocomplete, docs, and default selection. NOT exhaustive and NOT
+* a runtime allow-list — `groq.model({ name })` accepts any string, so
+* a newly launched id works the moment Groq ships it without a package
+* bump. Deprecated ids (e.g. several `llama-4` variants retired in 2026)
+* are intentionally excluded.
+*
+* - `llama-3.3-70b-versatile` — flagship general-purpose text model.
+* - `llama-3.1-8b-instant` — fastest/cheapest small text model.
+* - `openai/gpt-oss-120b` / `openai/gpt-oss-20b` — OpenAI open-weight
+*   family; vision + reasoning capable.
+* - `deepseek-r1-distill-llama-70b` — DeepSeek-R1-style reasoning.
+*/
+const GROQ_KNOWN_MODELS = [
+	"llama-3.3-70b-versatile",
+	"llama-3.1-8b-instant",
+	"openai/gpt-oss-120b",
+	"openai/gpt-oss-20b",
+	"deepseek-r1-distill-llama-70b"
+];
+
+//#endregion
+export { GROQ_BASE_URL, GROQ_KNOWN_MODELS, GROQ_PROVIDER, inferReasoningCapability, inferVisionCapability };
+//# sourceMappingURL=known-models.mjs.map

package/esm/known-models.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-models.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-groq/src/known-models.ts"],"sourcesContent":["/**\n * Default base URL for Groq's OpenAI-compatible Chat Completions\n * endpoint. Groq exposes the same wire protocol as OpenAI under this\n * prefix, which is exactly why `GroqSDK` can delegate to the\n * battle-tested `OpenAISDK` instead of reimplementing the transport.\n *\n * Verified against Groq's \"OpenAI Compatibility\" docs (mid-2026).\n * Override via `new GroqSDK({ baseURL })` if Groq ever relocates it.\n */\nexport const GROQ_BASE_URL = \"https://api.groq.com/openai/v1\";\n\n/**\n * The provider label every model produced by `GroqSDK` self-identifies\n * with. Flows through to `ModelContract.provider`, `AgentReport.model`,\n * logs, and any provider-aware middleware. Kept as a constant so the\n * wrapper and the inner `OpenAISDK` agree on one spelling.\n */\nexport const GROQ_PROVIDER = \"groq\";\n\n/**\n * Substrings identifying Groq-hosted model ids whose family accepts\n * image input (vision).\n *\n * Groq hosts *open* models on its LPU hardware, so the ids are the\n * upstream open-weight names rather than OpenAI's — which is why the\n * OpenAI adapter's `gpt-4o*` prefix inference would never fire here and\n * this provider must carry its OWN list. Verified against Groq's\n * supported-models catalog (mid-2026):\n *\n * - `openai/gpt-oss-*` — natively multimodal OpenAI open-weight family\n *   (the current production vision + reasoning models on Groq).\n * - `llama-4` / `llama-3.2-*-vision` — Meta's multimodal Llama families.\n *   Kept as substrings so any still-hosted or re-introduced variant is\n *   covered even though some `llama-4` ids were deprecated in 2026.\n *\n * Matched as a substring (not a prefix) because Groq prefixes several\n * ids with an org segment (`openai/`, `meta-llama/`) and appends size /\n * date suffixes. Override per-model via\n * `groq.model({ name, vision: true | false })`.\n */\nconst VISION_CAPABLE_SUBSTRINGS = [\n  \"gpt-oss\",\n  \"llama-4\",\n  \"llama-3.2-11b-vision\",\n  \"llama-3.2-90b-vision\",\n  \"vision\",\n];\n\n/**\n * Substrings identifying Groq-hosted model ids that expose an internal\n * reasoning / thinking channel and accept the `reasoning_effort`\n * request parameter on the OpenAI-compatible Chat Completions endpoint.\n *\n * Verified against Groq's catalog (mid-2026):\n * - `gpt-oss` — the OpenAI open-weight family reasons by default.\n * - `deepseek-r1-distill` — DeepSeek-R1-style reasoning at Groq speed.\n * - `qwq` / `qwen3` — Qwen reasoning families (when hosted).\n *\n * Matched as a substring for the same org-prefix / suffix reason as the\n * vision list. Override per-model via\n * `groq.model({ name, reasoning: true | false })`.\n */\nconst REASONING_CAPABLE_SUBSTRINGS = [\n  \"gpt-oss\",\n  \"deepseek-r1\",\n  \"deepseek-r1-distill\",\n  \"qwq\",\n  \"qwen3\",\n];\n\n/**\n * Infer whether a Groq-hosted model id supports vision based on the\n * known multimodal-family substrings. Unknown ids default to `false`\n * so passing an image attachment to a text-only model (e.g.\n * `llama-3.3-70b-versatile`) surfaces a clear, agent-side capability\n * error instead of an opaque upstream 400.\n *\n * @example\n * inferVisionCapability(\"openai/gpt-oss-120b\");        // → true\n * inferVisionCapability(\"meta-llama/llama-4-scout\");   // → true\n * inferVisionCapability(\"llama-3.3-70b-versatile\");    // → false\n * inferVisionCapability(\"llama-3.1-8b-instant\");       // → false\n */\nexport function inferVisionCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return VISION_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));\n}\n\n/**\n * Infer whether a Groq-hosted model id is a reasoning model based on\n * the known reasoning-family substrings. Unknown ids default to `false`\n * so the adapter never forwards an unsupported `reasoning_effort` param\n * to a non-reasoning model (which would 400).\n *\n * @example\n * inferReasoningCapability(\"openai/gpt-oss-20b\");           // → true\n * inferReasoningCapability(\"deepseek-r1-distill-llama-70b\"); // → true\n * inferReasoningCapability(\"llama-3.3-70b-versatile\");      // → false\n */\nexport function inferReasoningCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return REASONING_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));\n}\n\n/**\n * Curated list of current Groq production chat model ids (mid-2026),\n * for autocomplete, docs, and default selection. NOT exhaustive and NOT\n * a runtime allow-list — `groq.model({ name })` accepts any string, so\n * a newly launched id works the moment Groq ships it without a package\n * bump. Deprecated ids (e.g. several `llama-4` variants retired in 2026)\n * are intentionally excluded.\n *\n * - `llama-3.3-70b-versatile` — flagship general-purpose text model.\n * - `llama-3.1-8b-instant` — fastest/cheapest small text model.\n * - `openai/gpt-oss-120b` / `openai/gpt-oss-20b` — OpenAI open-weight\n *   family; vision + reasoning capable.\n * - `deepseek-r1-distill-llama-70b` — DeepSeek-R1-style reasoning.\n */\nexport const GROQ_KNOWN_MODELS = [\n  \"llama-3.3-70b-versatile\",\n  \"llama-3.1-8b-instant\",\n  \"openai/gpt-oss-120b\",\n  \"openai/gpt-oss-20b\",\n  \"deepseek-r1-distill-llama-70b\",\n] as const;\n"],"mappings":";;;;;;;;;;AASA,MAAa,gBAAgB;;;;;;;AAQ7B,MAAa,gBAAgB;;;;;;;;;;;;;;;;;;;;;;AAuB7B,MAAM,4BAA4B;CAChC;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;;AAgBA,MAAM,+BAA+B;CACnC;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;AAeA,SAAgB,sBAAsB,SAA0B;CAC9D,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,0BAA0B,MAAM,aAAa,WAAW,SAAS,QAAQ,CAAC;AACnF;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,SAA0B;CACjE,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,6BAA6B,MAAM,aAAa,WAAW,SAAS,QAAQ,CAAC;AACtF;;;;;;;;;;;;;;;AAgBA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;AACF"}

package/esm/sdk.d.mts

@@ -0,0 +1,100 @@
+import { GroqEmbedderConfig, GroqModelConfig, GroqSDKConfig } from "./config.type.mjs";
+import { EmbedderContract, ModelContract, SDKAdapterContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-groq/src/sdk.d.ts
+/**
+ * Groq-backed implementation of `SDKAdapterContract`.
+ *
+ * **Role.** The package entry point for Groq-hosted open models
+ * (`llama-3.3-70b-versatile`, `llama-3.1-8b-instant`,
+ * `openai/gpt-oss-*`, `deepseek-r1-distill-*`, …) served on Groq's fast
+ * LPU hardware. Because Groq exposes the OpenAI Chat Completions wire
+ * protocol verbatim, `GroqSDK` is a **thin wrapper over the already
+ * battle-tested {@link OpenAISDK}** rather than a fresh transport
+ * implementation — it owns one internal `OpenAISDK` pointed at Groq's
+ * `baseURL` with the `"groq"` provider label, and delegates `model()` /
+ * `embedder()` / `count()` to it.
+ *
+ * **Why a wrapper and not `OpenAISDK` directly?** Groq hosts *open*
+ * models whose ids are the upstream open-weight names (`llama-…`,
+ * `openai/gpt-oss-…`), not OpenAI's (`gpt-4o`, `o3`). The OpenAI
+ * adapter's capability inference keys on OpenAI prefixes and would never
+ * fire here, so every Groq model would come back with `vision`/
+ * `reasoning` silently `false`. `GroqSDK` fixes that by computing
+ * **this provider's own** vision/reasoning inference (see
+ * `known-models.ts`) and injecting the result as explicit capability
+ * config — which wins over the inner adapter's inference — plus a set of
+ * default per-model pricing rates. Everything else (transport, retries,
+ * streaming, structured output, error wrapping, usage accounting) is
+ * inherited unchanged from `OpenAISDK`.
+ *
+ * **Responsibility.**
+ * - Owns: one long-lived internal `OpenAISDK` (auth + Groq base URL) and
+ *   this provider's capability + default-pricing inference.
+ * - Does NOT own: the wire protocol, streaming loop, structured-output
+ *   mapping, or error wrapping — all inherited from `OpenAISDK`.
+ *
+ * Modeled as a class (see §4.2 of code-style.md — "long-lived state
+ * across many calls"), fronted by FP usage like the other adapters.
+ *
+ * @example
+ * const groq = new GroqSDK({ apiKey: process.env.GROQ_API_KEY! });
+ * const model = groq.model({ name: "llama-3.3-70b-versatile", temperature: 0.7 });
+ * const reasoner = groq.model({ name: "openai/gpt-oss-120b" }); // vision + reasoning auto-true
+ *
+ * @example
+ * // Compose into an `ai.groq` namespace for ergonomic agent wiring
+ * const ai = { agent, tool, systemPrompt, groq: new GroqSDK({ apiKey }) };
+ * const myAgent = ai.agent({ model: ai.groq.model({ name: "llama-3.1-8b-instant" }) });
+ */
+declare class GroqSDK implements SDKAdapterContract {
+  /**
+   * The wrapped OpenAI-compatible adapter, pre-pointed at Groq's
+   * `baseURL` and labeled with the `"groq"` provider. All real wire work
+   * happens here; `GroqSDK` only enriches the per-model config before
+   * delegating.
+   */
+  private readonly openai;
+  private readonly provider;
+  private readonly pricing?;
+  constructor(config: GroqSDKConfig);
+  /**
+   * Build a `ModelContract` bound to the internal Groq-pointed client.
+   *
+   * The wrapper's whole job lives here: it computes **Groq's** vision /
+   * reasoning inference from the model id and forwards the result as
+   * *explicit* `vision` / `reasoning` config to the inner
+   * `OpenAISDK.model()`. Because explicit capability config wins over the
+   * inner adapter's OpenAI-prefix inference, the returned model reports
+   * the right capabilities even though the id isn't an OpenAI name. A
+   * caller-supplied `vision` / `reasoning` still wins over this
+   * inference (we only fill the gap when the field is omitted).
+   *
+   * Pricing resolution: per-model `config.pricing` wins; otherwise this
+   * SDK's `pricing` registry keyed by `config.name`; otherwise the
+   * adapter's built-in default rate for the model; otherwise `undefined`
+   * (no cost computed).
+   */
+  model(config: GroqModelConfig): ModelContract;
+  /**
+   * Rough offline token-count estimate. Delegated straight to the inner
+   * `OpenAISDK`, which uses the core character-heuristic
+   * (`approximateTokenCount`). Good for budgeting / quota guards, not for
+   * billing.
+   */
+  count(text: string, model?: string): Promise<number>;
+  /**
+   * Build an embedder bound to the internal client. Delegated to the
+   * inner `OpenAISDK`.
+   *
+   * IMPORTANT: as of mid-2026 Groq does **not** expose an
+   * OpenAI-compatible embeddings endpoint, so a live `.embed()` /
+   * `.embedMany()` call will fail at the provider. The method is kept for
+   * adapter symmetry; use `@warlock.js/ai-openai` or
+   * `@warlock.js/ai-google` for retrieval embeddings.
+   */
+  embedder(config: GroqEmbedderConfig): EmbedderContract;
+}
+//#endregion
+export { GroqSDK };
+//# sourceMappingURL=sdk.d.mts.map

package/esm/sdk.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai-groq/src/sdk.ts"],"mappings":";;;;;;AAgEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoF+D;;;;;;;;;;;cApFlD,OAAA,YAAmB,kBAAA;;;;;;;mBAOb,MAAA;EAAA,iBACA,QAAA;EAAA,iBACA,OAAA;cAEE,MAAA,EAAQ,aAAA;;;;;;;;;;;;;;;;;;EAqCpB,KAAA,CAAM,MAAA,EAAQ,eAAA,GAAkB,aAAA;;;;;;;EAsB1B,KAAA,CAAM,IAAA,UAAc,KAAA,YAAiB,OAAA;;;;;;;;;;;EAc3C,QAAA,CAAS,MAAA,EAAQ,kBAAA,GAAqB,gBAAA;AAAA"}

package/esm/sdk.mjs

@@ -0,0 +1,154 @@
+import { GROQ_BASE_URL, GROQ_PROVIDER, inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+//#region ../@warlock.js/ai-groq/src/sdk.ts
+/**
+* Groq-backed implementation of `SDKAdapterContract`.
+*
+* **Role.** The package entry point for Groq-hosted open models
+* (`llama-3.3-70b-versatile`, `llama-3.1-8b-instant`,
+* `openai/gpt-oss-*`, `deepseek-r1-distill-*`, …) served on Groq's fast
+* LPU hardware. Because Groq exposes the OpenAI Chat Completions wire
+* protocol verbatim, `GroqSDK` is a **thin wrapper over the already
+* battle-tested {@link OpenAISDK}** rather than a fresh transport
+* implementation — it owns one internal `OpenAISDK` pointed at Groq's
+* `baseURL` with the `"groq"` provider label, and delegates `model()` /
+* `embedder()` / `count()` to it.
+*
+* **Why a wrapper and not `OpenAISDK` directly?** Groq hosts *open*
+* models whose ids are the upstream open-weight names (`llama-…`,
+* `openai/gpt-oss-…`), not OpenAI's (`gpt-4o`, `o3`). The OpenAI
+* adapter's capability inference keys on OpenAI prefixes and would never
+* fire here, so every Groq model would come back with `vision`/
+* `reasoning` silently `false`. `GroqSDK` fixes that by computing
+* **this provider's own** vision/reasoning inference (see
+* `known-models.ts`) and injecting the result as explicit capability
+* config — which wins over the inner adapter's inference — plus a set of
+* default per-model pricing rates. Everything else (transport, retries,
+* streaming, structured output, error wrapping, usage accounting) is
+* inherited unchanged from `OpenAISDK`.
+*
+* **Responsibility.**
+* - Owns: one long-lived internal `OpenAISDK` (auth + Groq base URL) and
+*   this provider's capability + default-pricing inference.
+* - Does NOT own: the wire protocol, streaming loop, structured-output
+*   mapping, or error wrapping — all inherited from `OpenAISDK`.
+*
+* Modeled as a class (see §4.2 of code-style.md — "long-lived state
+* across many calls"), fronted by FP usage like the other adapters.
+*
+* @example
+* const groq = new GroqSDK({ apiKey: process.env.GROQ_API_KEY! });
+* const model = groq.model({ name: "llama-3.3-70b-versatile", temperature: 0.7 });
+* const reasoner = groq.model({ name: "openai/gpt-oss-120b" }); // vision + reasoning auto-true
+*
+* @example
+* // Compose into an `ai.groq` namespace for ergonomic agent wiring
+* const ai = { agent, tool, systemPrompt, groq: new GroqSDK({ apiKey }) };
+* const myAgent = ai.agent({ model: ai.groq.model({ name: "llama-3.1-8b-instant" }) });
+*/
+var GroqSDK = class {
+	constructor(config) {
+		const { baseURL, provider, pricing, ...clientOptions } = config;
+		this.provider = provider ?? "groq";
+		this.pricing = pricing;
+		this.openai = new OpenAISDK({
+			...clientOptions,
+			baseURL: baseURL ?? "https://api.groq.com/openai/v1",
+			provider: this.provider,
+			pricing
+		});
+	}
+	/**
+	* Build a `ModelContract` bound to the internal Groq-pointed client.
+	*
+	* The wrapper's whole job lives here: it computes **Groq's** vision /
+	* reasoning inference from the model id and forwards the result as
+	* *explicit* `vision` / `reasoning` config to the inner
+	* `OpenAISDK.model()`. Because explicit capability config wins over the
+	* inner adapter's OpenAI-prefix inference, the returned model reports
+	* the right capabilities even though the id isn't an OpenAI name. A
+	* caller-supplied `vision` / `reasoning` still wins over this
+	* inference (we only fill the gap when the field is omitted).
+	*
+	* Pricing resolution: per-model `config.pricing` wins; otherwise this
+	* SDK's `pricing` registry keyed by `config.name`; otherwise the
+	* adapter's built-in default rate for the model; otherwise `undefined`
+	* (no cost computed).
+	*/
+	model(config) {
+		const resolvedPricing = config.pricing ?? this.pricing?.[config.name] ?? defaultPricingFor(config.name);
+		return this.openai.model({
+			...config,
+			vision: config.vision ?? inferVisionCapability(config.name),
+			reasoning: config.reasoning ?? inferReasoningCapability(config.name),
+			structuredOutput: config.structuredOutput ?? true,
+			pricing: resolvedPricing
+		});
+	}
+	/**
+	* Rough offline token-count estimate. Delegated straight to the inner
+	* `OpenAISDK`, which uses the core character-heuristic
+	* (`approximateTokenCount`). Good for budgeting / quota guards, not for
+	* billing.
+	*/
+	async count(text, model) {
+		return this.openai.count(text, model);
+	}
+	/**
+	* Build an embedder bound to the internal client. Delegated to the
+	* inner `OpenAISDK`.
+	*
+	* IMPORTANT: as of mid-2026 Groq does **not** expose an
+	* OpenAI-compatible embeddings endpoint, so a live `.embed()` /
+	* `.embedMany()` call will fail at the provider. The method is kept for
+	* adapter symmetry; use `@warlock.js/ai-openai` or
+	* `@warlock.js/ai-google` for retrieval embeddings.
+	*/
+	embedder(config) {
+		return this.openai.embedder(config);
+	}
+};
+/**
+* Built-in default USD-per-1,000,000-token rates for the current Groq
+* production models (mid-2026), used as the last fallback in `model()`'s
+* pricing resolution. A per-model or SDK-level `pricing` entry always
+* wins over these. Returns `undefined` for any unlisted id so cost stays
+* an honest absence rather than a false zero. Update when Groq revises
+* its public price list.
+*/
+function defaultPricingFor(name) {
+	return GROQ_DEFAULT_PRICING[name];
+}
+/**
+* Default per-million-token USD rates for known Groq models. Kept inline
+* (not exported) so the public surface stays the inference helpers; a
+* caller who wants different numbers supplies `pricing` on the SDK or
+* per model.
+*/
+const GROQ_DEFAULT_PRICING = {
+	"llama-3.3-70b-versatile": {
+		input: .59,
+		output: .79
+	},
+	"llama-3.1-8b-instant": {
+		input: .05,
+		output: .08
+	},
+	"openai/gpt-oss-120b": {
+		input: .15,
+		output: .75
+	},
+	"openai/gpt-oss-20b": {
+		input: .1,
+		output: .5
+	},
+	"deepseek-r1-distill-llama-70b": {
+		input: .75,
+		output: .99
+	}
+};
+
+//#endregion
+export { GroqSDK };
+//# sourceMappingURL=sdk.mjs.map

package/esm/sdk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-groq/src/sdk.ts"],"sourcesContent":["import type {\n  EmbedderContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { OpenAISDK } from \"@warlock.js/ai-openai\";\nimport type {\n  GroqEmbedderConfig,\n  GroqModelConfig,\n  GroqSDKConfig,\n} from \"./config.type\";\nimport {\n  GROQ_BASE_URL,\n  GROQ_PROVIDER,\n  inferReasoningCapability,\n  inferVisionCapability,\n} from \"./known-models\";\n\n/**\n * Groq-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for Groq-hosted open models\n * (`llama-3.3-70b-versatile`, `llama-3.1-8b-instant`,\n * `openai/gpt-oss-*`, `deepseek-r1-distill-*`, …) served on Groq's fast\n * LPU hardware. Because Groq exposes the OpenAI Chat Completions wire\n * protocol verbatim, `GroqSDK` is a **thin wrapper over the already\n * battle-tested {@link OpenAISDK}** rather than a fresh transport\n * implementation — it owns one internal `OpenAISDK` pointed at Groq's\n * `baseURL` with the `\"groq\"` provider label, and delegates `model()` /\n * `embedder()` / `count()` to it.\n *\n * **Why a wrapper and not `OpenAISDK` directly?** Groq hosts *open*\n * models whose ids are the upstream open-weight names (`llama-…`,\n * `openai/gpt-oss-…`), not OpenAI's (`gpt-4o`, `o3`). The OpenAI\n * adapter's capability inference keys on OpenAI prefixes and would never\n * fire here, so every Groq model would come back with `vision`/\n * `reasoning` silently `false`. `GroqSDK` fixes that by computing\n * **this provider's own** vision/reasoning inference (see\n * `known-models.ts`) and injecting the result as explicit capability\n * config — which wins over the inner adapter's inference — plus a set of\n * default per-model pricing rates. Everything else (transport, retries,\n * streaming, structured output, error wrapping, usage accounting) is\n * inherited unchanged from `OpenAISDK`.\n *\n * **Responsibility.**\n * - Owns: one long-lived internal `OpenAISDK` (auth + Groq base URL) and\n *   this provider's capability + default-pricing inference.\n * - Does NOT own: the wire protocol, streaming loop, structured-output\n *   mapping, or error wrapping — all inherited from `OpenAISDK`.\n *\n * Modeled as a class (see §4.2 of code-style.md — \"long-lived state\n * across many calls\"), fronted by FP usage like the other adapters.\n *\n * @example\n * const groq = new GroqSDK({ apiKey: process.env.GROQ_API_KEY! });\n * const model = groq.model({ name: \"llama-3.3-70b-versatile\", temperature: 0.7 });\n * const reasoner = groq.model({ name: \"openai/gpt-oss-120b\" }); // vision + reasoning auto-true\n *\n * @example\n * // Compose into an `ai.groq` namespace for ergonomic agent wiring\n * const ai = { agent, tool, systemPrompt, groq: new GroqSDK({ apiKey }) };\n * const myAgent = ai.agent({ model: ai.groq.model({ name: \"llama-3.1-8b-instant\" }) });\n */\nexport class GroqSDK implements SDKAdapterContract {\n  /**\n   * The wrapped OpenAI-compatible adapter, pre-pointed at Groq's\n   * `baseURL` and labeled with the `\"groq\"` provider. All real wire work\n   * happens here; `GroqSDK` only enriches the per-model config before\n   * delegating.\n   */\n  private readonly openai: OpenAISDK;\n  private readonly provider: string;\n  private readonly pricing?: Record<string, ModelPricing>;\n\n  public constructor(config: GroqSDKConfig) {\n    const { baseURL, provider, pricing, ...clientOptions } = config;\n\n    this.provider = provider ?? GROQ_PROVIDER;\n    this.pricing = pricing;\n\n    // Build the inner OpenAI-compatible client pointed at Groq. Forward\n    // every other upstream ClientOptions (timeout, maxRetries,\n    // defaultHeaders, fetch, …) verbatim — they type-check, so dropping\n    // them would be a silent footgun. We pass `pricing` through too so\n    // the inner registry stays a fallback, while THIS class's `model()`\n    // layers Groq default rates on top.\n    this.openai = new OpenAISDK({\n      ...clientOptions,\n      baseURL: baseURL ?? GROQ_BASE_URL,\n      provider: this.provider,\n      pricing,\n    });\n  }\n\n  /**\n   * Build a `ModelContract` bound to the internal Groq-pointed client.\n   *\n   * The wrapper's whole job lives here: it computes **Groq's** vision /\n   * reasoning inference from the model id and forwards the result as\n   * *explicit* `vision` / `reasoning` config to the inner\n   * `OpenAISDK.model()`. Because explicit capability config wins over the\n   * inner adapter's OpenAI-prefix inference, the returned model reports\n   * the right capabilities even though the id isn't an OpenAI name. A\n   * caller-supplied `vision` / `reasoning` still wins over this\n   * inference (we only fill the gap when the field is omitted).\n   *\n   * Pricing resolution: per-model `config.pricing` wins; otherwise this\n   * SDK's `pricing` registry keyed by `config.name`; otherwise the\n   * adapter's built-in default rate for the model; otherwise `undefined`\n   * (no cost computed).\n   */\n  public model(config: GroqModelConfig): ModelContract {\n    const resolvedPricing =\n      config.pricing ?? this.pricing?.[config.name] ?? defaultPricingFor(config.name);\n\n    return this.openai.model({\n      ...config,\n      // Fill capability inference only when the caller didn't pin it —\n      // explicit caller config always wins, then Groq inference, then\n      // (inside OpenAISDK) the harmless OpenAI inference that won't match.\n      vision: config.vision ?? inferVisionCapability(config.name),\n      reasoning: config.reasoning ?? inferReasoningCapability(config.name),\n      structuredOutput: config.structuredOutput ?? true,\n      pricing: resolvedPricing,\n    });\n  }\n\n  /**\n   * Rough offline token-count estimate. Delegated straight to the inner\n   * `OpenAISDK`, which uses the core character-heuristic\n   * (`approximateTokenCount`). Good for budgeting / quota guards, not for\n   * billing.\n   */\n  public async count(text: string, model?: string): Promise<number> {\n    return this.openai.count(text, model);\n  }\n\n  /**\n   * Build an embedder bound to the internal client. Delegated to the\n   * inner `OpenAISDK`.\n   *\n   * IMPORTANT: as of mid-2026 Groq does **not** expose an\n   * OpenAI-compatible embeddings endpoint, so a live `.embed()` /\n   * `.embedMany()` call will fail at the provider. The method is kept for\n   * adapter symmetry; use `@warlock.js/ai-openai` or\n   * `@warlock.js/ai-google` for retrieval embeddings.\n   */\n  public embedder(config: GroqEmbedderConfig): EmbedderContract {\n    return this.openai.embedder(config);\n  }\n\n  // NOTE: `image()` is intentionally NOT implemented. Groq hosts no\n  // image-generation API, and `SDKAdapterContract.image` is optional —\n  // its structural absence IS the capability guard, so\n  // `ai.groq.image(...)` is a compile-time error rather than a runtime\n  // surprise (mirrors Anthropic / Bedrock / Ollama).\n}\n\n/**\n * Built-in default USD-per-1,000,000-token rates for the current Groq\n * production models (mid-2026), used as the last fallback in `model()`'s\n * pricing resolution. A per-model or SDK-level `pricing` entry always\n * wins over these. Returns `undefined` for any unlisted id so cost stays\n * an honest absence rather than a false zero. Update when Groq revises\n * its public price list.\n */\nfunction defaultPricingFor(name: string): ModelPricing | undefined {\n  return GROQ_DEFAULT_PRICING[name];\n}\n\n/**\n * Default per-million-token USD rates for known Groq models. Kept inline\n * (not exported) so the public surface stays the inference helpers; a\n * caller who wants different numbers supplies `pricing` on the SDK or\n * per model.\n */\nconst GROQ_DEFAULT_PRICING: Record<string, ModelPricing> = {\n  \"llama-3.3-70b-versatile\": { input: 0.59, output: 0.79 },\n  \"llama-3.1-8b-instant\": { input: 0.05, output: 0.08 },\n  \"openai/gpt-oss-120b\": { input: 0.15, output: 0.75 },\n  \"openai/gpt-oss-20b\": { input: 0.1, output: 0.5 },\n  \"deepseek-r1-distill-llama-70b\": { input: 0.75, output: 0.99 },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,IAAa,UAAb,MAAmD;CAWjD,AAAO,YAAY,QAAuB;EACxC,MAAM,EAAE,SAAS,UAAU,SAAS,GAAG,kBAAkB;EAEzD,KAAK,WAAW;EAChB,KAAK,UAAU;EAQf,KAAK,SAAS,IAAI,UAAU;GAC1B,GAAG;GACH,SAAS;GACT,UAAU,KAAK;GACf;EACF,CAAC;CACH;;;;;;;;;;;;;;;;;;CAmBA,AAAO,MAAM,QAAwC;EACnD,MAAM,kBACJ,OAAO,WAAW,KAAK,UAAU,OAAO,SAAS,kBAAkB,OAAO,IAAI;EAEhF,OAAO,KAAK,OAAO,MAAM;GACvB,GAAG;GAIH,QAAQ,OAAO,UAAU,sBAAsB,OAAO,IAAI;GAC1D,WAAW,OAAO,aAAa,yBAAyB,OAAO,IAAI;GACnE,kBAAkB,OAAO,oBAAoB;GAC7C,SAAS;EACX,CAAC;CACH;;;;;;;CAQA,MAAa,MAAM,MAAc,OAAiC;EAChE,OAAO,KAAK,OAAO,MAAM,MAAM,KAAK;CACtC;;;;;;;;;;;CAYA,AAAO,SAAS,QAA8C;EAC5D,OAAO,KAAK,OAAO,SAAS,MAAM;CACpC;AAOF;;;;;;;;;AAUA,SAAS,kBAAkB,MAAwC;CACjE,OAAO,qBAAqB;AAC9B;;;;;;;AAQA,MAAM,uBAAqD;CACzD,2BAA2B;EAAE,OAAO;EAAM,QAAQ;CAAK;CACvD,wBAAwB;EAAE,OAAO;EAAM,QAAQ;CAAK;CACpD,uBAAuB;EAAE,OAAO;EAAM,QAAQ;CAAK;CACnD,sBAAsB;EAAE,OAAO;EAAK,QAAQ;CAAI;CAChD,iCAAiC;EAAE,OAAO;EAAM,QAAQ;CAAK;AAC/D"}

package/llms-full.txt

@@ -0,0 +1,122 @@
+# Warlock AI Groq — full skills
+
+> Package: `@warlock.js/ai-groq`
+
+> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/ai-groq/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
+
+## setup-groq  `@warlock.js/ai-groq/setup-groq/SKILL.md`
+
+---
+name: setup-groq
+description: 'Wire @warlock.js/ai-groq — new GroqSDK({apiKey, baseURL?, provider?, pricing?}) for Groq-hosted open models on LPU hardware (llama-3.3-70b-versatile, llama-3.1-8b-instant, openai/gpt-oss-120b/20b, deepseek-r1-distill-llama-70b). Thin wrapper over @warlock.js/ai-openai — uses the OpenAI-compatible endpoint https://api.groq.com/openai/v1, delegating transport/streaming/structured-output/errors to OpenAISDK while injecting Groqs OWN vision/reasoning inference + default pricing. .model({name, vision?, reasoning?, structuredOutput?}) for ModelContract. Triggers: `GroqSDK`, `groq.model`, `groq.count`, `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, `gpt-oss`, `deepseek-r1-distill`, `groq vision`, `groq reasoning`, `reasoning_effort`, `https://api.groq.com/openai/v1`, OpenAI-compatible Groq, LPU, fast inference; "wire groq into a warlock agent", "use llama 3.3 on groq", "run gpt-oss / deepseek reasoning on groq", "point warlock at the groq endpoint"; import `import { GroqSDK } from "@warlock.js/ai-groq"`. Skip: agent wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; adapter comparison — `@warlock.js/ai/pick-ai-provider/SKILL.md`; the wrapped adapter `@warlock.js/ai-openai` (`setup-openai`); embeddings (Groq has none — use openai/google); siblings `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `groq-sdk` / `openai` SDK.'
+---
+
+# `@warlock.js/ai-groq`
+
+Provider adapter for **Groq** — open models (Llama, GPT-OSS, DeepSeek-R1 distill) served fast on Groq's LPU hardware. Groq speaks the OpenAI Chat Completions protocol, so this package is a **thin wrapper over `@warlock.js/ai-openai`**: it owns an internal `OpenAISDK` pointed at Groq's endpoint and delegates the wire work, while injecting Groq's own capability inference and default pricing. Pair with `@warlock.js/ai` for the agent / tool / system-prompt surface.
+
+## Construction
+
+```ts
+import { GroqSDK } from "@warlock.js/ai-groq";
+
+// Common path — apiKey only. baseURL + provider default to Groq.
+const groq = new GroqSDK({ apiKey: process.env.GROQ_API_KEY! });
+```
+
+`baseURL` defaults to `https://api.groq.com/openai/v1` (Groq's **OpenAI-compatible endpoint**) — override only to route through a proxy/gateway. `provider` defaults to `"groq"` and flows through to `ModelContract.provider`, `AgentReport.model.provider`, and logs.
+
+`GroqSDK` is a class (not a factory) — it holds a long-lived internal `OpenAISDK` and aligns with the other adapter entry points. Every upstream `openai` `ClientOptions` field (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …) is forwarded verbatim to that inner client.
+
+## Producing a model
+
+```ts
+groq.model({ name: "llama-3.3-70b-versatile" })          // flagship general-purpose text
+groq.model({ name: "llama-3.1-8b-instant" })             // fastest / cheapest small text
+groq.model({ name: "openai/gpt-oss-120b" })              // vision + reasoning auto-true
+groq.model({ name: "deepseek-r1-distill-llama-70b" })    // reasoning auto-true
+```
+
+Returns a `ModelContract` you pass straight into `ai.agent({ model })`. `name` is the Groq-hosted **open-weight** id (the upstream name, e.g. `openai/gpt-oss-120b`), NOT an OpenAI id. Any current Groq model id works — the list above is curated, not an allow-list.
+
+## Capabilities — what's auto-set
+
+The whole reason this wrapper exists: Groq's ids aren't OpenAI's, so the OpenAI adapter's prefix inference would never fire. `GroqSDK` carries its **own** name lists.
+
+| Flag | Default |
+| --- | --- |
+| `vision` | Inferred from the Groq model id. `true` for `gpt-oss`, `llama-4`, `llama-3.2-*-vision`; `false` otherwise (e.g. `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`). |
+| `reasoning` | Inferred from the Groq model id. `true` for `gpt-oss`, `deepseek-r1` / `deepseek-r1-distill`, `qwq`, `qwen3`; `false` otherwise. Drives whether `reasoning_effort` is forwarded. |
+| `structuredOutput` | `true` — Groq accepts OpenAI-style `response_format`. |
+| `promptCaching` | Inherited from the inner OpenAI adapter (`true`; read-side `cachedTokens` accounting). |
+
+**Override `vision`, `reasoning`, or `structuredOutput` explicitly** via `.model({ name, vision?, reasoning?, structuredOutput? })` — an explicit value always wins over inference.
+
+```ts
+groq.model({ name: "some-custom-llama", vision: true })  // force on for an unlisted multimodal id
+groq.model({ name: "openai/gpt-oss-120b", reasoning: false }) // pin off
+```
+
+## Reasoning (gpt-oss / deepseek-r1 distill)
+
+Reasoning models accept a discrete effort knob, forwarded by the inner adapter as OpenAI's `reasoning_effort`:
+
+```ts
+const model = groq.model({ name: "deepseek-r1-distill-llama-70b" }); // reasoning auto-true
+await model.complete(messages, { reasoning: { effort: "high" } });   // → reasoning_effort: "high"
+```
+
+- `reasoning.effort` (`"low" | "medium" | "high"`) maps verbatim.
+- `reasoning.maxTokens` has no Chat Completions equivalent and is ignored (same as the OpenAI adapter).
+- When `capabilities.reasoning` is `false` (e.g. `llama-3.3-70b-versatile`), the option is dropped — never sent as an unsupported param.
+
+## Structured output & streaming
+
+Inherited unchanged from `@warlock.js/ai-openai`: a `responseSchema` maps to `response_format: json_schema` (strict) when the schema is a proper root object, else loose `json_object`; `model.stream()` drains the streaming Chat Completions response and yields `delta` / `tool-call` / `done` chunks with `include_usage` on. See [`setup-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) for the full wire behavior.
+
+## Embeddings — not available on Groq
+
+As of mid-2026 Groq exposes **no** OpenAI-compatible embeddings endpoint. `groq.embedder({ name })` constructs (delegated to the inner adapter) but a live `.embed()` call fails at the provider. Use `@warlock.js/ai-openai` or `@warlock.js/ai-google` for retrieval embeddings.
+
+There is also no image-generation API on Groq, so `GroqSDK` intentionally does **not** define `image()` — `ai.groq.image(...)` is a compile-time error (structural capability guard, like Anthropic / Bedrock / Ollama).
+
+## Pricing — per-model registry + built-in defaults
+
+`pricing` is a registry keyed by model name, rates in **USD per 1,000,000 tokens** (`ModelPricing`: `input`, `output`, optional `cachedInput` / `cachedOutput`). The adapter ships **built-in default rates** for the known Groq models as the final fallback.
+
+```ts
+const groq = new GroqSDK({
+  apiKey,
+  pricing: {
+    "llama-3.3-70b-versatile": { input: 0.59, output: 0.79 }, // USD per 1M tokens
+  },
+});
+```
+
+Resolution at `model()` time: per-model `pricing` (`groq.model({ name, pricing })`) > SDK `pricing[name]` > adapter built-in default for the id > `undefined` (no cost computed). Built-in defaults exist for `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, `openai/gpt-oss-120b`, `openai/gpt-oss-20b`, and `deepseek-r1-distill-llama-70b`; supply your own for anything else.
+
+## Token counting
+
+```ts
+await groq.count("some text")  // approximate heuristic (delegated), not a real tokenizer
+```
+
+Good for budgeting; not for billing.
+
+## Errors
+
+Raw errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the inner OpenAI adapter's error wrapper (dispatch keys on `status + code`). See [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md). Note Groq's documented OpenAI-compat gaps — `n` must be `1`, and `logprobs` / `logit_bias` / `top_logprobs` / `messages[].name` are unsupported.
+
+## When NOT to use this skill
+
+- Embeddings or image generation — Groq has neither; use `@warlock.js/ai-openai` / `@warlock.js/ai-google`.
+- OpenAI / Azure / OpenRouter — use `@warlock.js/ai-openai` (`setup-openai`); this wraps it but for Groq specifically.
+- Anthropic — `@warlock.js/ai-anthropic`. Bedrock — `@warlock.js/ai-bedrock`. Gemini — `@warlock.js/ai-google`. Local Ollama — `@warlock.js/ai-ollama`.
+
+## See also
+
+- [`@warlock.js/ai-openai/skills/setup-openai/SKILL.md`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — the wrapped adapter; full wire / streaming / structured-output detail
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — passing the model into `ai.agent({...})`
+- [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) — adapter comparison
+
+

package/llms.txt

@@ -0,0 +1,9 @@
+# Warlock AI Groq
+
+> Package: `@warlock.js/ai-groq`
+
+> Groq adapter for @warlock.js/ai (OpenAI-compatible, thin wrapper over @warlock.js/ai-openai)
+
+## Skills
+
+- [setup-groq](@warlock.js/ai-groq/setup-groq/SKILL.md): Wire @warlock.js/ai-groq — new GroqSDK({apiKey, baseURL?, provider?, pricing?}) for Groq-hosted open models on LPU hardware (llama-3.3-70b-versatile, llama-3.1-8b-instant, openai/gpt-oss-120b/20b, deepseek-r1-distill-llama-70b). Thin wrapper over @warlock.js/ai-openai — uses the OpenAI-compatible endpoint https://api.groq.com/openai/v1, delegating transport/streaming/structured-output/errors to OpenAISDK while injecting Groqs OWN vision/reasoning inference + default pricing. .model({name, vision?, reasoning?, structuredOutput?}) for ModelContract. Triggers: `GroqSDK`, `groq.model`, `groq.count`, `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, `gpt-oss`, `deepseek-r1-distill`, `groq vision`, `groq reasoning`, `reasoning_effort`, `https://api.groq.com/openai/v1`, OpenAI-compatible Groq, LPU, fast inference; "wire groq into a warlock agent", "use llama 3.3 on groq", "run gpt-oss / deepseek reasoning on groq", "point warlock at the groq endpoint"; import `import { GroqSDK } from "@warlock.js/ai-groq"`. Skip: agent wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; adapter comparison — `@warlock.js/ai/pick-ai-provider/SKILL.md`; the wrapped adapter `@warlock.js/ai-openai` (`setup-openai`); embeddings (Groq has none — use openai/google); siblings `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `groq-sdk` / `openai` SDK.