@warlock.js/ai-groq 4.6.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog — @warlock.js/ai-groq
+
+All notable changes to `@warlock.js/ai-groq` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
+
+## 4.6.0
+
+### Added
+
+- **First release.** `GroqSDK` — a thin wrapper over `@warlock.js/ai-openai` that points one internal `OpenAISDK` at Groq's OpenAI-compatible endpoint (`https://api.groq.com/openai/v1`) with `provider: "groq"`, delegating transport, streaming, structured output, error wrapping, and token accounting to the battle-tested adapter. Serves Groq-hosted open models (`llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, `openai/gpt-oss-*`, `deepseek-r1-distill-llama-70b`) on LPU hardware via `.model()` and `.count()`. `GROQ_BASE_URL` / `GROQ_PROVIDER` / `GROQ_KNOWN_MODELS` exported.
+- **Groq-aware capability inference** — because Groq ids are upstream open-weight names, not OpenAI's, the wrapper carries its own lists: `vision` is auto-set for `gpt-oss` / `llama-4` / `llama-3.2-*-vision`; `reasoning` for `gpt-oss` / `deepseek-r1` / `qwq` / `qwen3`. An explicit `vision` / `reasoning` / `structuredOutput` always wins. Exported as `inferVisionCapability` / `inferReasoningCapability`.
+- **Default pricing registry** (USD per 1,000,000 tokens) for the known Groq models as the final fallback; resolution per-model > SDK-level `pricing[name]` > built-in default > `undefined`. No embeddings endpoint on Groq (`.embedder()` is delegated for symmetry but calls fail upstream) and no `image()`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @warlock.js/ai-groq
+
+Groq adapter for [`@warlock.js/ai`](../ai). Groq serves open models (Llama, GPT-OSS, DeepSeek-R1 distill) fast on its LPU hardware and speaks the **OpenAI Chat Completions** wire protocol verbatim, so this package is a **thin wrapper** over [`@warlock.js/ai-openai`](../ai-openai): `GroqSDK` builds one internal `OpenAISDK` pointed at Groq's `baseURL` with `provider: "groq"` and delegates every call to it. It does not re-implement the transport, streaming, structured output, error wrapping, or token accounting.
+
+```bash
+npm install @warlock.js/ai @warlock.js/ai-openai @warlock.js/ai-groq @warlock.js/seal openai
+```
+
+> `@warlock.js/seal` is the recommended Standard Schema library for tool inputs and structured output. Any Standard Schema V1 library works (Zod, Valibot, …).
+
+## Quick start
+
+```ts
+import { GroqSDK } from "@warlock.js/ai-groq";
+import { ai } from "@warlock.js/ai";
+
+const groq = new GroqSDK({ apiKey: process.env.GROQ_API_KEY! });
+
+const myAgent = ai.agent({
+  model: groq.model({ name: "llama-3.3-70b-versatile" }),
+});
+
+const result = await myAgent.execute("Hello!");
+console.log(result.text);
+```
+
+Construct one SDK per account and reuse it everywhere — the single underlying `OpenAI` client (connection pool, auth, rate-limit state) is shared by every model it produces.
+
+## API surface
+
+```ts
+new GroqSDK(config: GroqSDKConfig)              // = OpenAI ClientOptions + Groq baseURL/provider defaults
+  .model(config: GroqModelConfig)               // → ModelContract
+  .embedder(config: GroqEmbedderConfig)         // → EmbedderContract (see caveat below)
+  .count(text, model?)                          // approximate token count
+
+GroqModelConfig {
+  name: string;                                 // Groq-hosted open-weight id, e.g. "llama-3.3-70b-versatile", "openai/gpt-oss-120b"
+  temperature?: number;
+  maxTokens?: number;
+  vision?: boolean;                             // override auto-inference (gpt-oss, llama-4, llama-3.2-*-vision)
+  reasoning?: boolean;                          // override auto-inference (gpt-oss, deepseek-r1, qwq, qwen3)
+  structuredOutput?: boolean;                   // default true
+  // ...neutral ModelConfig fields pass through
+}
+```
+
+## Base URL & model families
+
+`baseURL` defaults to `https://api.groq.com/openai/v1` (Groq's OpenAI-compatible endpoint) — override it only to route through a proxy or self-hosted gateway. `provider` defaults to `"groq"` and flows through to `ModelContract.provider`, `AgentReport.model.provider`, and logs. Every other upstream OpenAI `ClientOptions` field (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …) is forwarded verbatim to the inner client. Both constants are exported as `GROQ_BASE_URL` and `GROQ_PROVIDER`.
+
+A curated (not exhaustive, not an allow-list) set of current production ids is exported as `GROQ_KNOWN_MODELS`:
+
+| Model id | Notes |
+| --- | --- |
+| `llama-3.3-70b-versatile` | Flagship general-purpose text |
+| `llama-3.1-8b-instant` | Fastest / cheapest small text |
+| `openai/gpt-oss-120b` / `openai/gpt-oss-20b` | OpenAI open-weight family — vision + reasoning capable |
+| `deepseek-r1-distill-llama-70b` | DeepSeek-R1-style reasoning |
+
+`name` is the upstream open-weight id (e.g. `openai/gpt-oss-120b`), NOT an OpenAI id. `groq.model()` accepts any string, so a newly launched Groq id works the moment Groq ships it.
+
+## Capabilities
+
+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 and injects the result as explicit capability config, which wins over the inner adapter's inference. An explicit caller value always wins.
+
+| Capability | Default |
+| --- | --- |
+| `vision` | Inferred from the Groq id — `true` for `gpt-oss`, `llama-4`, `llama-3.2-*-vision`; `false` otherwise (e.g. `llama-3.3-70b-versatile`). |
+| `reasoning` | Inferred from the Groq id — `true` for `gpt-oss`, `deepseek-r1` / `deepseek-r1-distill`, `qwq`, `qwen3`; `false` otherwise. Drives whether `reasoning.effort` maps to `reasoning_effort` on the wire. |
+| `structuredOutput` | `true` — Groq accepts OpenAI-style `response_format`. |
+
+```ts
+groq.model({ name: "openai/gpt-oss-120b" });                 // vision + reasoning auto-true
+groq.model({ name: "deepseek-r1-distill-llama-70b" });       // reasoning auto-true
+groq.model({ name: "some-custom-llama", vision: true });     // explicit override
+```
+
+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" });
+await model.complete(messages, { reasoning: { effort: "high" } });   // → reasoning_effort: "high"
+```
+
+## 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 for API symmetry) but a live `.embed()` call fails at the provider. Use [`@warlock.js/ai-openai`](../ai-openai) or `@warlock.js/ai-google` for retrieval embeddings.
+
+## No image generation
+
+Groq hosts no image-generation API, so `GroqSDK` intentionally does **not** expose `image()`. The structural absence of the method is the capability guard — `ai.groq.image(...)` is a compile-time error rather than a runtime failure.
+
+## Pricing
+
+The adapter ships built-in default rates (USD per 1,000,000 tokens) for the known Groq models as the final fallback. Supply your own `pricing` registry (keyed by model name) to win per id:
+
+```ts
+const groq = new GroqSDK({
+  apiKey: process.env.GROQ_API_KEY!,
+  pricing: {
+    "llama-3.3-70b-versatile": { input: 0.59, output: 0.79 },
+  },
+});
+```
+
+Resolution at `model()` time: per-model `pricing` > SDK-level `pricing[name]` > adapter built-in default for the id > `undefined`. 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`.
+
+## Setup skill
+
+For agent wiring, capability inference, reasoning, and pricing detail, see the bundled setup skill: [`skills/setup-groq/SKILL.md`](./skills/setup-groq/SKILL.md).
+
+## Tests
+
+```bash
+npm test
+```
+
+Covers baseURL / provider wiring, Groq-specific vision & reasoning inference, pricing resolution, and count / embedder delegation.
+
+## License
+
+MIT

package/cjs/index.cjs

@@ -0,0 +1,281 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_ai_openai = require("@warlock.js/ai-openai");
+
+//#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
+//#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 _warlock_js_ai_openai.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
+exports.GROQ_BASE_URL = GROQ_BASE_URL;
+exports.GROQ_KNOWN_MODELS = GROQ_KNOWN_MODELS;
+exports.GROQ_PROVIDER = GROQ_PROVIDER;
+exports.GroqSDK = GroqSDK;
+exports.inferReasoningCapability = inferReasoningCapability;
+exports.inferVisionCapability = inferVisionCapability;
+//# sourceMappingURL=index.cjs.map

package/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["OpenAISDK"],"sources":["../../../../../../@warlock.js/ai-groq/src/known-models.ts","../../../../../../@warlock.js/ai-groq/src/sdk.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","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":";;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC9DA,IAAa,UAAb,MAAmD;CAWjD,AAAO,YAAY,QAAuB;EACxC,MAAM,EAAE,SAAS,UAAU,SAAS,GAAG,kBAAkB;EAEzD,KAAK,WAAW;EAChB,KAAK,UAAU;EAQf,KAAK,SAAS,IAAIA,gCAAU;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/esm/config.type.d.mts

@@ -0,0 +1,122 @@
+import { OpenAISDKConfig } from "@warlock.js/ai-openai";
+import { EmbedderConfig, ModelConfig, ModelPricing } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-groq/src/config.type.d.ts
+/**
+ * Configuration for the Groq SDK adapter.
+ *
+ * Groq speaks the OpenAI Chat Completions wire protocol, so this type
+ * is structurally `OpenAISDKConfig` (which is `openai`'s `ClientOptions`
+ * + `provider` + `pricing`) with two ergonomic differences:
+ *
+ * - `baseURL` is **optional** here — it defaults to Groq's
+ *   OpenAI-compatible endpoint (`https://api.groq.com/openai/v1`) when
+ *   omitted, so the common path is just `{ apiKey }`. Override it only
+ *   to point at a proxy/gateway.
+ * - `provider` defaults to `"groq"` (not `"openai"`), so every model the
+ *   SDK produces self-identifies as Groq on `ModelContract.provider`,
+ *   `AgentReport.model`, logs, and provider-aware middleware.
+ *
+ * Every other upstream `ClientOptions` field (`timeout`, `maxRetries`,
+ * `defaultHeaders`, `fetch`, `organization`, …) is forwarded verbatim to
+ * the internal `OpenAISDK` it wraps.
+ *
+ * `pricing` is an optional SDK-level registry keyed by model name.
+ * Resolution at `model()` call time: per-model `pricing` > this SDK
+ * registry > the adapter's built-in default rates for known Groq models
+ * > `undefined` (no cost computed).
+ *
+ * @example
+ * // Common path — apiKey only; baseURL + provider default to Groq.
+ * new GroqSDK({ apiKey: process.env.GROQ_API_KEY! });
+ *
+ * @example
+ * // SDK-level pricing registry — USD per 1,000,000 tokens.
+ * new GroqSDK({
+ *   apiKey,
+ *   pricing: { "llama-3.3-70b-versatile": { input: 0.59, output: 0.79 } },
+ * });
+ */
+type GroqSDKConfig = Omit<OpenAISDKConfig, "baseURL" | "provider"> & {
+  /**
+   * Override Groq's OpenAI-compatible endpoint. Defaults to
+   * `https://api.groq.com/openai/v1` when omitted — set this only to
+   * route through a proxy or self-hosted gateway.
+   */
+  baseURL?: string;
+  /**
+   * Override the upstream provider label. Defaults to `"groq"`; flows
+   * through to `ModelContract.provider` and every report/log derived
+   * from it.
+   */
+  provider?: string;
+  /**
+   * Per-model USD pricing registry, keyed by model name. Surfaced onto
+   * every model produced by `model()`; per-model `GroqModelConfig.pricing`
+   * still wins when both are set, and the adapter's built-in default
+   * rates fill the gap when neither is provided.
+   */
+  pricing?: Record<string, ModelPricing>;
+};
+/**
+ * Per-model configuration for `GroqSDK.model()`. `name` is the
+ * Groq-hosted model id — the upstream open-weight name (e.g.
+ * `"llama-3.3-70b-versatile"`, `"openai/gpt-oss-120b"`,
+ * `"deepseek-r1-distill-llama-70b"`), NOT an OpenAI id.
+ *
+ * The capability overrides mirror the OpenAI adapter, but their
+ * auto-inference is driven by **Groq's** model-name lists
+ * (`known-models.ts`) rather than OpenAI's — that is the core reason
+ * this wrapper exists. Any explicit `true`/`false` always wins over
+ * inference.
+ *
+ * @example
+ * groq.model({ name: "llama-3.3-70b-versatile" });           // text, no vision/reasoning
+ * groq.model({ name: "openai/gpt-oss-120b" });               // vision + reasoning auto-true
+ * groq.model({ name: "custom-llama", vision: true });        // explicit override
+ */
+type GroqModelConfig = ModelConfig & {
+  /**
+   * Override the auto-inferred vision capability. When omitted, the
+   * adapter checks the model id against Groq's known multimodal families
+   * (see `known-models.ts`) — `true` for `gpt-oss` / `llama-4` /
+   * `llama-3.2-*-vision`, `false` otherwise. Explicit `true`/`false`
+   * always wins.
+   */
+  vision?: boolean;
+  /**
+   * Override the auto-inferred reasoning capability. When omitted, the
+   * adapter checks the model id against Groq's known reasoning families
+   * (see `known-models.ts`) — `true` for `gpt-oss` / `deepseek-r1` /
+   * `qwq` / `qwen3`, `false` otherwise. Drives whether
+   * `ModelCallOptions.reasoning` maps to `reasoning_effort` on the wire.
+   * Explicit `true`/`false` always wins.
+   */
+  reasoning?: boolean;
+  /**
+   * Override the inferred `structuredOutput` capability. Defaults to
+   * `true` — Groq's Chat Completions endpoint accepts OpenAI-style
+   * `response_format`. Set `false` (or pass `responseFormat` on the
+   * underlying model) for a model that rejects strict `json_schema`, so
+   * the agent re-injects a soft schema hint into the system prompt.
+   */
+  structuredOutput?: boolean;
+};
+/**
+ * Per-embedder configuration for `GroqSDK.embedder()`. Mirrors the
+ * neutral {@link EmbedderConfig}.
+ *
+ * NOTE: as of mid-2026 Groq does **not** expose an OpenAI-compatible
+ * embeddings endpoint — `embedder()` is delegated to the inner
+ * `OpenAISDK` for API symmetry, but a live `.embed()` call will fail at
+ * the provider. Use a dedicated embeddings provider
+ * (`@warlock.js/ai-openai` / `@warlock.js/ai-google`) for retrieval.
+ *
+ * @example
+ * // Will construct, but Groq currently has no embeddings model to call.
+ * groq.embedder({ name: "some-future-embeddings-model" });
+ */
+type GroqEmbedderConfig = EmbedderConfig;
+//#endregion
+export { GroqEmbedderConfig, GroqModelConfig, GroqSDKConfig };
+//# sourceMappingURL=config.type.d.mts.map

package/esm/config.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai-groq/src/config.type.ts"],"mappings":";;;;;;AAsCA;;;;;;;;;;;;;;;;;AAmBuC;AAoBvC;;;;;;;;;AAyBkB;AAiBlB;;;;AAA+C;KAjFnC,aAAA,GAAgB,IAAA,CAAK,eAAA;;;;;;EAM/B,OAAA;;;;;;EAMA,QAAA;;;;;;;EAOA,OAAA,GAAU,MAAA,SAAe,YAAA;AAAA;;;;;;;;;;;;;;;;;;KAoBf,eAAA,GAAkB,WAAW;;;;;;;;EAQvC,MAAA;;;;;;;;;EASA,SAAA;;;;;;;;EAQA,gBAAA;AAAA;;;;;;;;;;;;;;;KAiBU,kBAAA,GAAqB,cAAc"}

package/esm/index.d.mts

@@ -0,0 +1,4 @@
+import { GroqEmbedderConfig, GroqModelConfig, GroqSDKConfig } from "./config.type.mjs";
+import { GroqSDK } from "./sdk.mjs";
+import { GROQ_BASE_URL, GROQ_KNOWN_MODELS, GROQ_PROVIDER, inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+export { GROQ_BASE_URL, GROQ_KNOWN_MODELS, GROQ_PROVIDER, type GroqEmbedderConfig, type GroqModelConfig, GroqSDK, type GroqSDKConfig, inferReasoningCapability, inferVisionCapability };

package/esm/index.mjs

@@ -0,0 +1,4 @@
+import { GROQ_BASE_URL, GROQ_KNOWN_MODELS, GROQ_PROVIDER, inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+import { GroqSDK } from "./sdk.mjs";
+
+export { GROQ_BASE_URL, GROQ_KNOWN_MODELS, GROQ_PROVIDER, GroqSDK, inferReasoningCapability, inferVisionCapability };