@warlock.js/ai-mistral 4.6.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog — @warlock.js/ai-mistral
+
+All notable changes to `@warlock.js/ai-mistral` 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.** `MistralSDK` — a thin wrapper over `@warlock.js/ai-openai` that points one internal `OpenAISDK` at Mistral's OpenAI-compatible endpoint (`https://api.mistral.ai/v1`) with `provider: "mistral"`, delegating transport, streaming, tool calls, structured output, error wrapping, and token accounting to the battle-tested adapter. Exposes `.model()`, `.embedder()` (`mistral-embed`), and `.count()`.
+- **Mistral-aware capability inference** — `vision` is auto-set for the `pixtral` family and recent multimodal generations (`mistral-large`, `mistral-medium`, `ministral-3`); `reasoning` for the `magistral` family and the hybrid `mistral-small` generation. An explicit `vision` / `reasoning` on `.model()` always wins. Exported as `inferVisionCapability` / `inferReasoningCapability`, with the `-latest` aliases grouped under `MISTRAL_MODELS`.
+- **Default pricing registry** (`MISTRAL_DEFAULT_PRICING`, USD per 1,000,000 tokens) merged under any caller-supplied `pricing` so cost truth works out of the box; per-model > SDK-level > default > `undefined`. No `image()` — Mistral has no OpenAI-compatible image endpoint.

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,127 @@
+# @warlock.js/ai-mistral
+
+Mistral AI adapter for [`@warlock.js/ai`](../ai). Mistral exposes an **OpenAI-compatible** Chat Completions + Embeddings API, so this package is a **thin wrapper** over [`@warlock.js/ai-openai`](../ai-openai): `MistralSDK` builds one internal `OpenAISDK` pointed at Mistral's `baseURL` with `provider: "mistral"` and delegates every call to it. It does not re-implement the wire protocol, streaming, tool-call accumulation, structured output, error wrapping, or token accounting.
+
+```bash
+npm install @warlock.js/ai @warlock.js/ai-openai @warlock.js/ai-mistral @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 { MistralSDK } from "@warlock.js/ai-mistral";
+import { ai } from "@warlock.js/ai";
+
+const mistral = new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });
+
+const myAgent = ai.agent({
+  model: mistral.model({ name: "mistral-large-latest" }),
+});
+
+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 and embedder it produces.
+
+## API surface
+
+```ts
+new MistralSDK(config: MistralSDKConfig)        // = OpenAI ClientOptions + provider/pricing defaults
+  .model(config: MistralModelConfig)            // → ModelContract
+  .embedder(config: EmbedderConfig)             // → EmbedderContract
+  .count(text, model?)                          // approximate token count
+
+MistralModelConfig {
+  name: string;                                 // e.g. "mistral-large-latest", "magistral-medium-latest"
+  temperature?: number;
+  maxTokens?: number;
+  vision?: boolean;                             // override auto-inference (pixtral family, recent generations)
+  reasoning?: boolean;                          // override auto-inference (magistral family, hybrid mistral-small)
+  structuredOutput?: boolean;
+  responseFormat?: "json_schema" | "json_object" | "text";
+  pdf?: boolean;                                // opt into PDF document input (default false)
+  audio?: boolean;                              // opt into audio input (default false)
+  // ...neutral ModelConfig fields pass through
+}
+```
+
+## Base URL & model families
+
+`baseURL` defaults to `https://api.mistral.ai/v1` (Mistral's OpenAI-compatible endpoint serving `/chat/completions` and `/embeddings`). Override it only to reach a Mistral-compatible gateway or proxy. `provider` defaults to `"mistral"` and flows through to `ModelContract.provider`, `AgentReport.model.provider`, and logs. Every other upstream OpenAI `ClientOptions` field (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …) is forwarded verbatim.
+
+The headline `-latest` aliases are exported as `MISTRAL_MODELS`, grouped by role:
+
+| Family | Aliases | Notes |
+| --- | --- | --- |
+| `chat` | `mistral-large-latest`, `mistral-medium-latest`, `mistral-small-latest` | General-purpose multimodal flagship / mid / small |
+| `vision` | `pixtral-large-latest`, `pixtral-12b` | Dedicated multimodal (image input) |
+| `reasoning` | `magistral-medium-latest`, `magistral-small-latest` | Chain-of-thought reasoning |
+| `embedding` | `mistral-embed` | Via the OpenAI-compatible `/v1/embeddings` |
+
+`mistral.model()` accepts any id string, so version-pinned ids (`mistral-large-2512`, `magistral-medium-2509`) work just as well — capability inference keys off the family fragment, not the alias list.
+
+## Capabilities
+
+The wrapper injects **Mistral-aware** capability inference before delegating to the OpenAI adapter, because the OpenAI prefix lists (`gpt-4o`, `o3`, …) never match Mistral names. An explicit value always wins over inference.
+
+| Capability | Default |
+| --- | --- |
+| `vision` | Inferred from the model name — `true` for the `pixtral` family and the recent multimodal generations (`mistral-large`, `mistral-medium`, `ministral-3`); `false` otherwise. |
+| `reasoning` | Inferred from the model name — `true` for the `magistral` family and the hybrid `mistral-small` generation; `false` otherwise. Drives whether `reasoning.effort` maps to `reasoning_effort` on the wire. |
+| `structuredOutput` | `true`, unless `responseFormat` is forced to `"json_object"` / `"text"`. |
+
+```ts
+mistral.model({ name: "pixtral-large-latest" });            // vision auto-true
+mistral.model({ name: "magistral-medium-latest" });         // reasoning auto-true
+mistral.model({ name: "some-fine-tune", vision: true });    // explicit override
+```
+
+## Embeddings
+
+`mistral-embed` is served through the OpenAI-compatible `/v1/embeddings`, so the embedder delegates straight to the wrapped OpenAI embedder:
+
+```ts
+const embedder = mistral.embedder({ name: "mistral-embed" });
+
+const { vector, dimensions, usage } = await embedder.embed("Hello world");
+const { vectors } = await embedder.embedMany(["doc 1", "doc 2"]);
+```
+
+## Pricing
+
+The adapter ships a conservative default registry (`MISTRAL_DEFAULT_PRICING`, USD per 1,000,000 tokens) so cost truth works out of the box. Supply your own `pricing` to win per model id:
+
+```ts
+const mistral = new MistralSDK({
+  apiKey: process.env.MISTRAL_API_KEY!,
+  pricing: {
+    "mistral-large-latest": { input: 2, output: 6 },
+    "magistral-medium-latest": { input: 2, output: 5 },
+  },
+});
+```
+
+Resolution at `model()` time: per-model `pricing` > SDK-level `pricing` > `MISTRAL_DEFAULT_PRICING` > `undefined`. The defaults are list-price approximations — pass explicit rates for billing-grade numbers.
+
+## No image generation
+
+Mistral has no OpenAI-compatible image endpoint, so `MistralSDK` intentionally does **not** expose `image()`. The structural absence of the method is the capability guard — `ai.mistral.image(...)` is a compile-time error rather than a runtime failure.
+
+## Setup skill
+
+For agent wiring, capability inference, and pricing detail, see the bundled setup skill: [`skills/setup-mistral/SKILL.md`](./skills/setup-mistral/SKILL.md).
+
+## Tests
+
+```bash
+npm test
+```
+
+Covers baseURL / provider wiring, Mistral-aware vision & reasoning inference, pricing resolution, and embedder / count delegation.
+
+## License
+
+MIT

package/cjs/index.cjs

@@ -0,0 +1,277 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_ai_openai = require("@warlock.js/ai-openai");
+
+//#region ../@warlock.js/ai-mistral/src/known-models.ts
+/**
+* Model-name fragments identifying Mistral families that accept image
+* input (vision / multimodal).
+*
+* - `pixtral` — Mistral's dedicated multimodal family
+*   (`pixtral-large-latest`, `pixtral-12b`); documents, charts, and
+*   natural images.
+* - `mistral-large` / `mistral-medium` — the recent frontier generations
+*   (Large 3, Medium 3.5) are natively multimodal.
+* - `ministral-3` — the current small open-weight line ships with
+*   best-in-class text + vision.
+*
+* Matched as a **substring** (not a strict prefix) so the date / version
+* suffixes Mistral appends (`pixtral-large-2411`, `mistral-large-2512`)
+* and the `-latest` aliases are all covered without enumerating every
+* release tag. Override per-model via
+* `mistral.model({ name, vision: true | false })` — explicit config
+* always wins over inference.
+*
+* Maintenance: append a fragment when Mistral ships a multimodal family
+* that doesn't already match.
+*/
+const VISION_CAPABLE_SUBSTRINGS = [
+	"pixtral",
+	"mistral-large",
+	"mistral-medium",
+	"ministral-3"
+];
+/**
+* Model-name fragments identifying Mistral families that perform
+* explicit chain-of-thought reasoning.
+*
+* - `magistral` — Mistral's dedicated reasoning family
+*   (`magistral-medium-latest`, `magistral-small-latest`); emits
+*   tokenized thinking chunks.
+* - `mistral-small-4` / `mistral-small` — the current Small generation
+*   is a hybrid model that unifies instruct + reasoning + coding.
+*
+* Matched as a **substring** so version-tagged ids
+* (`magistral-medium-2509`, `mistral-small-2603`) and `-latest` aliases
+* are covered. Override per-model via
+* `mistral.model({ name, reasoning: true | false })` — explicit config
+* always wins over inference.
+*
+* Maintenance: append a fragment when Mistral ships a reasoning family
+* that doesn't already match.
+*/
+const REASONING_CAPABLE_SUBSTRINGS = ["magistral", "mistral-small"];
+/**
+* Infer whether a Mistral model id accepts image input (vision) based on
+* the known multimodal-family fragments. Unknown ids default to `false`
+* so passing an image attachment to a text-only model surfaces a clear,
+* agent-side capability error instead of an opaque Mistral 400.
+*
+* @example
+* inferVisionCapability("pixtral-large-latest");   // → true
+* inferVisionCapability("mistral-large-2512");     // → true
+* inferVisionCapability("magistral-medium-latest");// → false
+* inferVisionCapability("mistral-embed");          // → false
+*/
+function inferVisionCapability(modelName) {
+	const normalized = modelName.toLowerCase();
+	return VISION_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));
+}
+/**
+* Infer whether a Mistral model id is a reasoning model (the `magistral`
+* family plus the hybrid `mistral-small` generation) based on the known
+* fragments. Unknown ids default to `false` so the adapter never forwards
+* an unsupported `reasoning_effort` param to a non-reasoning model.
+*
+* @example
+* inferReasoningCapability("magistral-medium-latest"); // → true
+* inferReasoningCapability("mistral-small-2603");      // → true
+* inferReasoningCapability("mistral-large-latest");    // → false
+* inferReasoningCapability("pixtral-12b");             // → false
+*/
+function inferReasoningCapability(modelName) {
+	const normalized = modelName.toLowerCase();
+	return REASONING_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));
+}
+/**
+* Stable `-latest` alias ids for the headline Mistral chat / embeddings
+* models, grouped by role. Convenience constants only — `mistral.model()`
+* accepts any id string, so a version-pinned id
+* (`mistral-large-2512`, `magistral-medium-2509`) works just as well.
+* Capability inference keys off the family fragment, not this list, so a
+* newer alias is recognized the moment its name matches a fragment in
+* {@link inferVisionCapability} / {@link inferReasoningCapability}.
+*/
+const MISTRAL_MODELS = {
+	/** General-purpose multimodal flagship / mid / small chat aliases. */
+	chat: [
+		"mistral-large-latest",
+		"mistral-medium-latest",
+		"mistral-small-latest"
+	],
+	/** Dedicated multimodal (vision) aliases — the `pixtral` family. */
+	vision: ["pixtral-large-latest", "pixtral-12b"],
+	/** Dedicated reasoning aliases — the `magistral` family. */
+	reasoning: ["magistral-medium-latest", "magistral-small-latest"],
+	/** Embeddings model reachable via the OpenAI-compatible `/v1/embeddings`. */
+	embedding: ["mistral-embed"]
+};
+/**
+* Conservative default USD pricing registry (per 1,000,000 tokens),
+* keyed by stable `-latest` alias, surfaced onto every model unless the
+* caller overrides it via SDK-level or per-model `pricing`.
+*
+* These are sane published-list approximations for budgeting / cost-truth
+* out of the box — Mistral revises rates and ships new generations, so
+* pass an explicit `pricing` registry to `new MistralSDK({ pricing })`
+* for billing-grade numbers. Resolution at `model()` time always lets a
+* caller-supplied rate win: per-model `pricing` > SDK `pricing` > these
+* defaults > `undefined`.
+*/
+const MISTRAL_DEFAULT_PRICING = {
+	"mistral-large-latest": {
+		input: 2,
+		output: 6
+	},
+	"mistral-medium-latest": {
+		input: .4,
+		output: 2
+	},
+	"mistral-small-latest": {
+		input: .1,
+		output: .3
+	},
+	"pixtral-large-latest": {
+		input: 2,
+		output: 6
+	},
+	"pixtral-12b": {
+		input: .15,
+		output: .15
+	},
+	"magistral-medium-latest": {
+		input: 2,
+		output: 5
+	},
+	"magistral-small-latest": {
+		input: .5,
+		output: 1.5
+	},
+	"mistral-embed": {
+		input: .1,
+		output: 0
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/ai-mistral/src/sdk.ts
+/** Default OpenAI-compatible base URL for the Mistral API. */
+const MISTRAL_BASE_URL = "https://api.mistral.ai/v1";
+/** Default provider label stamped onto every model this SDK produces. */
+const MISTRAL_PROVIDER = "mistral";
+/**
+* Mistral-backed implementation of `SDKAdapterContract`.
+*
+* **Role.** The package entry point for Mistral AI chat + embeddings.
+* Mistral exposes an **OpenAI-compatible** API (`/v1/chat/completions`,
+* `/v1/embeddings`), so `MistralSDK` is a *thin wrapper* over the
+* battle-tested {@link OpenAISDK} — it does NOT re-implement the wire
+* protocol, streaming loop, tool-call accumulation, structured-output
+* mapping, error wrapping, or token accounting. It constructs one
+* internal `OpenAISDK` pointed at Mistral's `baseURL` with
+* `provider: "mistral"`, and delegates `model()` / `embedder()` /
+* `count()` straight to it.
+*
+* **What this wrapper adds on top of the OpenAI adapter:**
+* - **Defaults.** Injects Mistral's `baseURL` + `provider` label and a
+*   default {@link MISTRAL_DEFAULT_PRICING} registry so cost truth works
+*   out of the box. All are overridable via config.
+* - **Provider-correct capability inference.** Mistral's model names
+*   aren't OpenAI names, so the OpenAI prefix lists never match. Before
+*   delegating `model()`, this wrapper infers `vision` (the `pixtral`
+*   family + recent multimodal generations) and `reasoning` (the
+*   `magistral` family + hybrid `mistral-small`) from *this provider's*
+*   fragment lists and passes them as explicit overrides — which the
+*   inner `OpenAISDK` honors verbatim. A caller-supplied explicit
+*   `vision` / `reasoning` still wins.
+*
+* 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 / embedder produced here.
+*
+* **Note — no image generation.** Mistral has no OpenAI-compatible image
+* endpoint, so `image()` is intentionally NOT exposed. The structural
+* absence of the method IS the capability guard (see
+* `SDKAdapterContract.image`): `ai.mistral.image(...)` is a compile-time
+* error rather than a runtime failure.
+*
+* @example
+* const mistral = new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });
+* const model = mistral.model({ name: "mistral-large-latest", temperature: 0.7 });
+* const embedder = mistral.embedder({ name: "mistral-embed" });
+*
+* @example
+* // Compose into an `ai.mistral` namespace for ergonomic agent wiring.
+* const ai = { agent, tool, systemPrompt, mistral: new MistralSDK({ apiKey }) };
+* const reasoner = ai.agent({ model: ai.mistral.model({ name: "magistral-medium-latest" }) });
+*/
+var MistralSDK = class {
+	constructor(config) {
+		const { provider, baseURL, pricing, ...clientOptions } = config;
+		const mergedPricing = {
+			...MISTRAL_DEFAULT_PRICING,
+			...pricing
+		};
+		this.openai = new _warlock_js_ai_openai.OpenAISDK({
+			...clientOptions,
+			baseURL: baseURL ?? MISTRAL_BASE_URL,
+			provider: provider ?? MISTRAL_PROVIDER,
+			pricing: mergedPricing
+		});
+	}
+	/**
+	* Build a `ModelContract` for a Mistral chat model.
+	*
+	* Delegates to the inner `OpenAISDK.model()` but first injects
+	* **Mistral-aware capability inference**: when the caller omits
+	* `vision` / `reasoning`, they're inferred from this provider's family
+	* fragments (`pixtral` → vision, `magistral` / `mistral-small` →
+	* reasoning, see `known-models.ts`) and passed down as explicit
+	* overrides. Without this step the wrapped OpenAI adapter would check
+	* Mistral ids against OpenAI prefixes (`gpt-4o`, `o3`, …) and wrongly
+	* report every Mistral model as non-vision / non-reasoning.
+	*
+	* A caller-supplied explicit `vision` / `reasoning` is preserved as-is
+	* (explicit config always wins over inference). Pricing resolution is
+	* handled downstream by `OpenAISDK` against the merged registry:
+	* per-model `pricing` > SDK registry (caller + Mistral defaults) >
+	* `undefined`.
+	*/
+	model(config) {
+		const resolvedConfig = {
+			...config,
+			vision: config.vision ?? inferVisionCapability(config.name),
+			reasoning: config.reasoning ?? inferReasoningCapability(config.name)
+		};
+		return this.openai.model(resolvedConfig);
+	}
+	/**
+	* Rough offline token-count estimate. Delegates to the wrapped
+	* `OpenAISDK.count()` (the shared character-heuristic from the core
+	* package) — good for budgeting / quota guards, not billing. The
+	* optional model id is forwarded but currently ignored.
+	*/
+	async count(text, model) {
+		return this.openai.count(text, model);
+	}
+	/**
+	* Build an `EmbedderContract` bound to this SDK's client. Mistral
+	* serves embeddings (`mistral-embed`) through the OpenAI-compatible
+	* `/v1/embeddings` endpoint, so this delegates straight to
+	* `OpenAISDK.embedder()`.
+	*
+	* @example
+	* const embedder = mistral.embedder({ name: "mistral-embed" });
+	* const { vector } = await embedder.embed("Hello world");
+	*/
+	embedder(config) {
+		return this.openai.embedder(config);
+	}
+};
+
+//#endregion
+exports.MISTRAL_DEFAULT_PRICING = MISTRAL_DEFAULT_PRICING;
+exports.MISTRAL_MODELS = MISTRAL_MODELS;
+exports.MistralSDK = MistralSDK;
+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-mistral/src/known-models.ts","../../../../../../@warlock.js/ai-mistral/src/sdk.ts"],"sourcesContent":["import type { ModelPricing } from \"@warlock.js/ai\";\n\n/**\n * Model-name fragments identifying Mistral families that accept image\n * input (vision / multimodal).\n *\n * - `pixtral` — Mistral's dedicated multimodal family\n *   (`pixtral-large-latest`, `pixtral-12b`); documents, charts, and\n *   natural images.\n * - `mistral-large` / `mistral-medium` — the recent frontier generations\n *   (Large 3, Medium 3.5) are natively multimodal.\n * - `ministral-3` — the current small open-weight line ships with\n *   best-in-class text + vision.\n *\n * Matched as a **substring** (not a strict prefix) so the date / version\n * suffixes Mistral appends (`pixtral-large-2411`, `mistral-large-2512`)\n * and the `-latest` aliases are all covered without enumerating every\n * release tag. Override per-model via\n * `mistral.model({ name, vision: true | false })` — explicit config\n * always wins over inference.\n *\n * Maintenance: append a fragment when Mistral ships a multimodal family\n * that doesn't already match.\n */\nconst VISION_CAPABLE_SUBSTRINGS = [\n  \"pixtral\",\n  \"mistral-large\",\n  \"mistral-medium\",\n  \"ministral-3\",\n] as const;\n\n/**\n * Model-name fragments identifying Mistral families that perform\n * explicit chain-of-thought reasoning.\n *\n * - `magistral` — Mistral's dedicated reasoning family\n *   (`magistral-medium-latest`, `magistral-small-latest`); emits\n *   tokenized thinking chunks.\n * - `mistral-small-4` / `mistral-small` — the current Small generation\n *   is a hybrid model that unifies instruct + reasoning + coding.\n *\n * Matched as a **substring** so version-tagged ids\n * (`magistral-medium-2509`, `mistral-small-2603`) and `-latest` aliases\n * are covered. Override per-model via\n * `mistral.model({ name, reasoning: true | false })` — explicit config\n * always wins over inference.\n *\n * Maintenance: append a fragment when Mistral ships a reasoning family\n * that doesn't already match.\n */\nconst REASONING_CAPABLE_SUBSTRINGS = [\"magistral\", \"mistral-small\"] as const;\n\n/**\n * Infer whether a Mistral model id accepts image input (vision) based on\n * the known multimodal-family fragments. Unknown ids default to `false`\n * so passing an image attachment to a text-only model surfaces a clear,\n * agent-side capability error instead of an opaque Mistral 400.\n *\n * @example\n * inferVisionCapability(\"pixtral-large-latest\");   // → true\n * inferVisionCapability(\"mistral-large-2512\");     // → true\n * inferVisionCapability(\"magistral-medium-latest\");// → false\n * inferVisionCapability(\"mistral-embed\");          // → false\n */\nexport function inferVisionCapability(modelName: string): boolean {\n  const normalized = modelName.toLowerCase();\n\n  return VISION_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));\n}\n\n/**\n * Infer whether a Mistral model id is a reasoning model (the `magistral`\n * family plus the hybrid `mistral-small` generation) based on the known\n * fragments. Unknown ids default to `false` so the adapter never forwards\n * an unsupported `reasoning_effort` param to a non-reasoning model.\n *\n * @example\n * inferReasoningCapability(\"magistral-medium-latest\"); // → true\n * inferReasoningCapability(\"mistral-small-2603\");      // → true\n * inferReasoningCapability(\"mistral-large-latest\");    // → false\n * inferReasoningCapability(\"pixtral-12b\");             // → false\n */\nexport function inferReasoningCapability(modelName: string): boolean {\n  const normalized = modelName.toLowerCase();\n\n  return REASONING_CAPABLE_SUBSTRINGS.some((fragment) => normalized.includes(fragment));\n}\n\n/**\n * Stable `-latest` alias ids for the headline Mistral chat / embeddings\n * models, grouped by role. Convenience constants only — `mistral.model()`\n * accepts any id string, so a version-pinned id\n * (`mistral-large-2512`, `magistral-medium-2509`) works just as well.\n * Capability inference keys off the family fragment, not this list, so a\n * newer alias is recognized the moment its name matches a fragment in\n * {@link inferVisionCapability} / {@link inferReasoningCapability}.\n */\nexport const MISTRAL_MODELS = {\n  /** General-purpose multimodal flagship / mid / small chat aliases. */\n  chat: [\"mistral-large-latest\", \"mistral-medium-latest\", \"mistral-small-latest\"],\n  /** Dedicated multimodal (vision) aliases — the `pixtral` family. */\n  vision: [\"pixtral-large-latest\", \"pixtral-12b\"],\n  /** Dedicated reasoning aliases — the `magistral` family. */\n  reasoning: [\"magistral-medium-latest\", \"magistral-small-latest\"],\n  /** Embeddings model reachable via the OpenAI-compatible `/v1/embeddings`. */\n  embedding: [\"mistral-embed\"],\n} as const;\n\n/**\n * Conservative default USD pricing registry (per 1,000,000 tokens),\n * keyed by stable `-latest` alias, surfaced onto every model unless the\n * caller overrides it via SDK-level or per-model `pricing`.\n *\n * These are sane published-list approximations for budgeting / cost-truth\n * out of the box — Mistral revises rates and ships new generations, so\n * pass an explicit `pricing` registry to `new MistralSDK({ pricing })`\n * for billing-grade numbers. Resolution at `model()` time always lets a\n * caller-supplied rate win: per-model `pricing` > SDK `pricing` > these\n * defaults > `undefined`.\n */\nexport const MISTRAL_DEFAULT_PRICING: Record<string, ModelPricing> = {\n  \"mistral-large-latest\": { input: 2, output: 6 },\n  \"mistral-medium-latest\": { input: 0.4, output: 2 },\n  \"mistral-small-latest\": { input: 0.1, output: 0.3 },\n  \"pixtral-large-latest\": { input: 2, output: 6 },\n  \"pixtral-12b\": { input: 0.15, output: 0.15 },\n  \"magistral-medium-latest\": { input: 2, output: 5 },\n  \"magistral-small-latest\": { input: 0.5, output: 1.5 },\n  \"mistral-embed\": { input: 0.1, output: 0 },\n};\n","import type {\n  EmbedderConfig,\n  EmbedderContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { OpenAISDK } from \"@warlock.js/ai-openai\";\nimport type { MistralModelConfig, MistralSDKConfig } from \"./config.type\";\nimport {\n  inferReasoningCapability,\n  inferVisionCapability,\n  MISTRAL_DEFAULT_PRICING,\n} from \"./known-models\";\n\n/** Default OpenAI-compatible base URL for the Mistral API. */\nconst MISTRAL_BASE_URL = \"https://api.mistral.ai/v1\";\n\n/** Default provider label stamped onto every model this SDK produces. */\nconst MISTRAL_PROVIDER = \"mistral\";\n\n/**\n * Mistral-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for Mistral AI chat + embeddings.\n * Mistral exposes an **OpenAI-compatible** API (`/v1/chat/completions`,\n * `/v1/embeddings`), so `MistralSDK` is a *thin wrapper* over the\n * battle-tested {@link OpenAISDK} — it does NOT re-implement the wire\n * protocol, streaming loop, tool-call accumulation, structured-output\n * mapping, error wrapping, or token accounting. It constructs one\n * internal `OpenAISDK` pointed at Mistral's `baseURL` with\n * `provider: \"mistral\"`, and delegates `model()` / `embedder()` /\n * `count()` straight to it.\n *\n * **What this wrapper adds on top of the OpenAI adapter:**\n * - **Defaults.** Injects Mistral's `baseURL` + `provider` label and a\n *   default {@link MISTRAL_DEFAULT_PRICING} registry so cost truth works\n *   out of the box. All are overridable via config.\n * - **Provider-correct capability inference.** Mistral's model names\n *   aren't OpenAI names, so the OpenAI prefix lists never match. Before\n *   delegating `model()`, this wrapper infers `vision` (the `pixtral`\n *   family + recent multimodal generations) and `reasoning` (the\n *   `magistral` family + hybrid `mistral-small`) from *this provider's*\n *   fragment lists and passes them as explicit overrides — which the\n *   inner `OpenAISDK` honors verbatim. A caller-supplied explicit\n *   `vision` / `reasoning` still wins.\n *\n * Construct one SDK per account and reuse it everywhere; the single\n * underlying `OpenAI` client (connection pool, auth, rate-limit state)\n * is shared by every model / embedder produced here.\n *\n * **Note — no image generation.** Mistral has no OpenAI-compatible image\n * endpoint, so `image()` is intentionally NOT exposed. The structural\n * absence of the method IS the capability guard (see\n * `SDKAdapterContract.image`): `ai.mistral.image(...)` is a compile-time\n * error rather than a runtime failure.\n *\n * @example\n * const mistral = new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });\n * const model = mistral.model({ name: \"mistral-large-latest\", temperature: 0.7 });\n * const embedder = mistral.embedder({ name: \"mistral-embed\" });\n *\n * @example\n * // Compose into an `ai.mistral` namespace for ergonomic agent wiring.\n * const ai = { agent, tool, systemPrompt, mistral: new MistralSDK({ apiKey }) };\n * const reasoner = ai.agent({ model: ai.mistral.model({ name: \"magistral-medium-latest\" }) });\n */\nexport class MistralSDK implements SDKAdapterContract {\n  /**\n   * The wrapped OpenAI-compatible adapter doing all the real work. Built\n   * once in the constructor with Mistral's `baseURL`, `provider` label,\n   * and merged pricing registry; every public method delegates to it.\n   */\n  private readonly openai: OpenAISDK;\n\n  public constructor(config: MistralSDKConfig) {\n    const { provider, baseURL, pricing, ...clientOptions } = config;\n\n    // Caller pricing wins per model id; otherwise fall back to this\n    // provider's published-list defaults so cost truth works out of the box.\n    const mergedPricing: Record<string, ModelPricing> = {\n      ...MISTRAL_DEFAULT_PRICING,\n      ...pricing,\n    };\n\n    this.openai = new OpenAISDK({\n      ...clientOptions,\n      baseURL: baseURL ?? MISTRAL_BASE_URL,\n      provider: provider ?? MISTRAL_PROVIDER,\n      pricing: mergedPricing,\n    });\n  }\n\n  /**\n   * Build a `ModelContract` for a Mistral chat model.\n   *\n   * Delegates to the inner `OpenAISDK.model()` but first injects\n   * **Mistral-aware capability inference**: when the caller omits\n   * `vision` / `reasoning`, they're inferred from this provider's family\n   * fragments (`pixtral` → vision, `magistral` / `mistral-small` →\n   * reasoning, see `known-models.ts`) and passed down as explicit\n   * overrides. Without this step the wrapped OpenAI adapter would check\n   * Mistral ids against OpenAI prefixes (`gpt-4o`, `o3`, …) and wrongly\n   * report every Mistral model as non-vision / non-reasoning.\n   *\n   * A caller-supplied explicit `vision` / `reasoning` is preserved as-is\n   * (explicit config always wins over inference). Pricing resolution is\n   * handled downstream by `OpenAISDK` against the merged registry:\n   * per-model `pricing` > SDK registry (caller + Mistral defaults) >\n   * `undefined`.\n   */\n  public model(config: MistralModelConfig): ModelContract {\n    const resolvedConfig: MistralModelConfig = {\n      ...config,\n      vision: config.vision ?? inferVisionCapability(config.name),\n      reasoning: config.reasoning ?? inferReasoningCapability(config.name),\n    };\n\n    return this.openai.model(resolvedConfig);\n  }\n\n  /**\n   * Rough offline token-count estimate. Delegates to the wrapped\n   * `OpenAISDK.count()` (the shared character-heuristic from the core\n   * package) — good for budgeting / quota guards, not billing. The\n   * optional model id is forwarded but currently ignored.\n   */\n  public async count(text: string, model?: string): Promise<number> {\n    return this.openai.count(text, model);\n  }\n\n  /**\n   * Build an `EmbedderContract` bound to this SDK's client. Mistral\n   * serves embeddings (`mistral-embed`) through the OpenAI-compatible\n   * `/v1/embeddings` endpoint, so this delegates straight to\n   * `OpenAISDK.embedder()`.\n   *\n   * @example\n   * const embedder = mistral.embedder({ name: \"mistral-embed\" });\n   * const { vector } = await embedder.embed(\"Hello world\");\n   */\n  public embedder(config: EmbedderConfig): EmbedderContract {\n    // `embedder` is optional on the contract but always present on the\n    // wrapped OpenAI adapter — assert it for the delegation.\n    return this.openai.embedder!(config);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,MAAM,4BAA4B;CAChC;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;;;;;;;AAqBA,MAAM,+BAA+B,CAAC,aAAa,eAAe;;;;;;;;;;;;;AAclE,SAAgB,sBAAsB,WAA4B;CAChE,MAAM,aAAa,UAAU,YAAY;CAEzC,OAAO,0BAA0B,MAAM,aAAa,WAAW,SAAS,QAAQ,CAAC;AACnF;;;;;;;;;;;;;AAcA,SAAgB,yBAAyB,WAA4B;CACnE,MAAM,aAAa,UAAU,YAAY;CAEzC,OAAO,6BAA6B,MAAM,aAAa,WAAW,SAAS,QAAQ,CAAC;AACtF;;;;;;;;;;AAWA,MAAa,iBAAiB;;CAE5B,MAAM;EAAC;EAAwB;EAAyB;CAAsB;;CAE9E,QAAQ,CAAC,wBAAwB,aAAa;;CAE9C,WAAW,CAAC,2BAA2B,wBAAwB;;CAE/D,WAAW,CAAC,eAAe;AAC7B;;;;;;;;;;;;;AAcA,MAAa,0BAAwD;CACnE,wBAAwB;EAAE,OAAO;EAAG,QAAQ;CAAE;CAC9C,yBAAyB;EAAE,OAAO;EAAK,QAAQ;CAAE;CACjD,wBAAwB;EAAE,OAAO;EAAK,QAAQ;CAAI;CAClD,wBAAwB;EAAE,OAAO;EAAG,QAAQ;CAAE;CAC9C,eAAe;EAAE,OAAO;EAAM,QAAQ;CAAK;CAC3C,2BAA2B;EAAE,OAAO;EAAG,QAAQ;CAAE;CACjD,0BAA0B;EAAE,OAAO;EAAK,QAAQ;CAAI;CACpD,iBAAiB;EAAE,OAAO;EAAK,QAAQ;CAAE;AAC3C;;;;;ACjHA,MAAM,mBAAmB;;AAGzB,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDzB,IAAa,aAAb,MAAsD;CAQpD,AAAO,YAAY,QAA0B;EAC3C,MAAM,EAAE,UAAU,SAAS,SAAS,GAAG,kBAAkB;EAIzD,MAAM,gBAA8C;GAClD,GAAG;GACH,GAAG;EACL;EAEA,KAAK,SAAS,IAAIA,gCAAU;GAC1B,GAAG;GACH,SAAS,WAAW;GACpB,UAAU,YAAY;GACtB,SAAS;EACX,CAAC;CACH;;;;;;;;;;;;;;;;;;;CAoBA,AAAO,MAAM,QAA2C;EACtD,MAAM,iBAAqC;GACzC,GAAG;GACH,QAAQ,OAAO,UAAU,sBAAsB,OAAO,IAAI;GAC1D,WAAW,OAAO,aAAa,yBAAyB,OAAO,IAAI;EACrE;EAEA,OAAO,KAAK,OAAO,MAAM,cAAc;CACzC;;;;;;;CAQA,MAAa,MAAM,MAAc,OAAiC;EAChE,OAAO,KAAK,OAAO,MAAM,MAAM,KAAK;CACtC;;;;;;;;;;;CAYA,AAAO,SAAS,QAA0C;EAGxD,OAAO,KAAK,OAAO,SAAU,MAAM;CACrC;AACF"}

package/esm/config.type.d.mts

@@ -0,0 +1,101 @@
+import { OpenAISDKConfig } from "@warlock.js/ai-openai";
+import { ModelConfig } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-mistral/src/config.type.d.ts
+/**
+ * Configuration for the Mistral SDK adapter.
+ *
+ * Mistral exposes an **OpenAI-compatible** Chat Completions + Embeddings
+ * API, so `MistralSDKConfig` is the OpenAI client options
+ * ({@link OpenAISDKConfig}) with this provider's sensible defaults baked
+ * in. The whole object is forwarded to the internal `OpenAISDK`, so any
+ * upstream client option (`timeout`, `maxRetries`, `defaultHeaders`,
+ * `fetch`, …) is accepted verbatim.
+ *
+ * Defaults injected by `MistralSDK` when omitted:
+ * - `baseURL` → `https://api.mistral.ai/v1` (the OpenAI-compatible endpoint).
+ * - `provider` → `"mistral"` (flows through to `ModelContract.provider`,
+ *   `AgentReport.model.provider`, logs, and provider-aware middleware).
+ * - `pricing` → merged on top of {@link MISTRAL_DEFAULT_PRICING} so cost
+ *   accounting works out of the box; a caller entry for the same model id
+ *   wins.
+ *
+ * `apiKey` is still required (your Mistral API key) — it has no honest
+ * default. Point `baseURL` elsewhere only to reach a Mistral-compatible
+ * gateway / proxy.
+ *
+ * @example
+ * new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });
+ *
+ * @example
+ * // Override the default pricing for billing-grade cost truth.
+ * new MistralSDK({
+ *   apiKey,
+ *   pricing: { "mistral-large-latest": { input: 2, output: 6 } },
+ * });
+ */
+type MistralSDKConfig = OpenAISDKConfig;
+/**
+ * Per-model configuration for `MistralSDK.model()`. Extends the neutral
+ * {@link ModelConfig} with the same capability overrides the wrapped
+ * OpenAI adapter understands — Mistral speaks the same Chat Completions
+ * wire, so they pass straight through.
+ *
+ * The difference from the OpenAI adapter is **inference**: when `vision`
+ * / `reasoning` are omitted, `MistralSDK` infers them from this
+ * provider's own family fragments (`pixtral` / `magistral`, see
+ * `known-models.ts`) rather than the OpenAI prefixes. An explicit
+ * `true` / `false` always wins over that inference.
+ *
+ * @example
+ * mistral.model({ name: "mistral-large-latest" });           // vision auto-true
+ * mistral.model({ name: "magistral-medium-latest" });        // reasoning auto-true
+ * mistral.model({ name: "some-fine-tune", vision: true });   // explicit override
+ */
+type MistralModelConfig = ModelConfig & {
+  /**
+   * Override the auto-inferred vision capability. When omitted, the
+   * adapter checks the model id against this provider's multimodal
+   * family fragments (`pixtral`, recent `mistral-large` / `mistral-medium`
+   * / `ministral-3` generations — see `known-models.ts`). Explicit
+   * `true` / `false` always wins over inference.
+   */
+  vision?: boolean;
+  /**
+   * Override the auto-inferred reasoning capability. When omitted, the
+   * adapter checks the model id against the reasoning fragments
+   * (`magistral` family + hybrid `mistral-small`). When the resolved
+   * value is `true`, `ModelCallOptions.reasoning.effort` is forwarded as
+   * the OpenAI-compatible `reasoning_effort`; when `false` it is dropped.
+   * Explicit `true` / `false` always wins over inference.
+   */
+  reasoning?: boolean;
+  /**
+   * Override the inferred `structuredOutput` capability, mirroring the
+   * wrapped OpenAI adapter. When omitted, treated as capable unless
+   * `responseFormat` forces a loose mode (`"json_object"` / `"text"`).
+   */
+  structuredOutput?: boolean;
+  /**
+   * Override the wire-level `response_format` the adapter emits when the
+   * caller supplies a response schema (`"json_schema"` | `"json_object"`
+   * | `"text"`). Forwarded verbatim to the wrapped OpenAI adapter — use
+   * for a Mistral model / gateway that rejects strict `json_schema`.
+   */
+  responseFormat?: "json_schema" | "json_object" | "text";
+  /**
+   * Opt into PDF / document **input** (default `false`). Forwarded to the
+   * wrapped OpenAI adapter, which maps `{ type: "pdf" }` parts to
+   * OpenAI-compatible `file` parts.
+   */
+  pdf?: boolean;
+  /**
+   * Opt into audio **input** (default `false`). Forwarded to the wrapped
+   * OpenAI adapter, which maps `{ type: "audio" }` parts to
+   * OpenAI-compatible `input_audio` parts.
+   */
+  audio?: boolean;
+};
+//#endregion
+export { MistralModelConfig, MistralSDKConfig };
+//# 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-mistral/src/config.type.ts"],"mappings":";;;;;;AAmCA;;;;AAA8C;AAmB9C;;;;;;;;;;;;AA0CO;;;;;;;;;;;;;KA7DK,gBAAA,GAAmB,eAAe;;;;;;;;;;;;;;;;;;KAmBlC,kBAAA,GAAqB,WAAW;;;;;;;;EAQ1C,MAAA;;;;;;;;;EASA,SAAA;;;;;;EAMA,gBAAA;;;;;;;EAOA,cAAA;;;;;;EAMA,GAAA;;;;;;EAMA,KAAA;AAAA"}

package/esm/index.d.mts

@@ -0,0 +1,4 @@
+import { MistralModelConfig, MistralSDKConfig } from "./config.type.mjs";
+import { MistralSDK } from "./sdk.mjs";
+import { MISTRAL_DEFAULT_PRICING, MISTRAL_MODELS, inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+export { MISTRAL_DEFAULT_PRICING, MISTRAL_MODELS, type MistralModelConfig, MistralSDK, type MistralSDKConfig, inferReasoningCapability, inferVisionCapability };

package/esm/index.mjs

@@ -0,0 +1,4 @@
+import { MISTRAL_DEFAULT_PRICING, MISTRAL_MODELS, inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+import { MistralSDK } from "./sdk.mjs";
+
+export { MISTRAL_DEFAULT_PRICING, MISTRAL_MODELS, MistralSDK, inferReasoningCapability, inferVisionCapability };

package/esm/known-models.d.mts

@@ -0,0 +1,60 @@
+import { ModelPricing } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-mistral/src/known-models.d.ts
+/**
+ * Infer whether a Mistral model id accepts image input (vision) based on
+ * the known multimodal-family fragments. Unknown ids default to `false`
+ * so passing an image attachment to a text-only model surfaces a clear,
+ * agent-side capability error instead of an opaque Mistral 400.
+ *
+ * @example
+ * inferVisionCapability("pixtral-large-latest");   // → true
+ * inferVisionCapability("mistral-large-2512");     // → true
+ * inferVisionCapability("magistral-medium-latest");// → false
+ * inferVisionCapability("mistral-embed");          // → false
+ */
+declare function inferVisionCapability(modelName: string): boolean;
+/**
+ * Infer whether a Mistral model id is a reasoning model (the `magistral`
+ * family plus the hybrid `mistral-small` generation) based on the known
+ * fragments. Unknown ids default to `false` so the adapter never forwards
+ * an unsupported `reasoning_effort` param to a non-reasoning model.
+ *
+ * @example
+ * inferReasoningCapability("magistral-medium-latest"); // → true
+ * inferReasoningCapability("mistral-small-2603");      // → true
+ * inferReasoningCapability("mistral-large-latest");    // → false
+ * inferReasoningCapability("pixtral-12b");             // → false
+ */
+declare function inferReasoningCapability(modelName: string): boolean;
+/**
+ * Stable `-latest` alias ids for the headline Mistral chat / embeddings
+ * models, grouped by role. Convenience constants only — `mistral.model()`
+ * accepts any id string, so a version-pinned id
+ * (`mistral-large-2512`, `magistral-medium-2509`) works just as well.
+ * Capability inference keys off the family fragment, not this list, so a
+ * newer alias is recognized the moment its name matches a fragment in
+ * {@link inferVisionCapability} / {@link inferReasoningCapability}.
+ */
+declare const MISTRAL_MODELS: {
+  /** General-purpose multimodal flagship / mid / small chat aliases. */readonly chat: readonly ["mistral-large-latest", "mistral-medium-latest", "mistral-small-latest"]; /** Dedicated multimodal (vision) aliases — the `pixtral` family. */
+  readonly vision: readonly ["pixtral-large-latest", "pixtral-12b"]; /** Dedicated reasoning aliases — the `magistral` family. */
+  readonly reasoning: readonly ["magistral-medium-latest", "magistral-small-latest"]; /** Embeddings model reachable via the OpenAI-compatible `/v1/embeddings`. */
+  readonly embedding: readonly ["mistral-embed"];
+};
+/**
+ * Conservative default USD pricing registry (per 1,000,000 tokens),
+ * keyed by stable `-latest` alias, surfaced onto every model unless the
+ * caller overrides it via SDK-level or per-model `pricing`.
+ *
+ * These are sane published-list approximations for budgeting / cost-truth
+ * out of the box — Mistral revises rates and ships new generations, so
+ * pass an explicit `pricing` registry to `new MistralSDK({ pricing })`
+ * for billing-grade numbers. Resolution at `model()` time always lets a
+ * caller-supplied rate win: per-model `pricing` > SDK `pricing` > these
+ * defaults > `undefined`.
+ */
+declare const MISTRAL_DEFAULT_PRICING: Record<string, ModelPricing>;
+//#endregion
+export { MISTRAL_DEFAULT_PRICING, MISTRAL_MODELS, 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-mistral/src/known-models.ts"],"mappings":";;;;;AAgEA;;;;AAAuD;AAkBvD;;;;AAA0D;iBAlB1C,qBAAA,CAAsB,SAAiB;;;;;;;;;;AAwDvD;;;iBAtCgB,wBAAA,CAAyB,SAAiB;AAsCO;;;;;;;;;AAAA,cAvBpD,cAAA;;;;;;;;;;;;;;;;;;cAuBA,uBAAA,EAAyB,MAAM,SAAS,YAAA"}