@warlock.js/ai-mistral 5.19.1 → 5.21.0

package/CHANGELOG.md

@@ -1,9 +1,20 @@
-# Changelog — @warlock.js/ai-mistral
+# 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.
 
+## 5.21.0 - 2026-09-25
+
+### Changed
+
+- Lockstep release maintenance and dependency refresh.
+## 5.20.0 - 2026-09-24
+
+### Changed
+
+- Added a package-level skill index and clearer discovery descriptions for grouped agent guidance.
+
 ## 5.19.0 - 2026-09-23
 
 ### Changed

package/llms-full.txt

@@ -6,100 +6,100 @@
 
 ## setup-mistral  `@warlock.js/ai-mistral/setup-mistral/SKILL.md`
 
----
-name: setup-mistral
-description: "@warlock.js/ai-mistral in @warlock.js/ai-mistral; use when you need to set up mistral."
----
-
-# `@warlock.js/ai-mistral`
-
-Provider adapter for Mistral AI. Mistral exposes an **OpenAI-compatible** API, so `MistralSDK` is a **thin wrapper** over [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — it does not re-implement the wire protocol, streaming, tool calls, structured output, error wrapping, or token accounting. It builds one internal `OpenAISDK` pointed at Mistral's `baseURL` with `provider: "mistral"`, then layers on this provider's own capability inference + default pricing. Pair with `@warlock.js/ai` for the agent / tool / system-prompt surface.
-
-## Construction
-
-```ts
-import { MistralSDK } from "@warlock.js/ai-mistral";
-
-const mistral = new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });
-```
-
-`baseURL` defaults to `https://api.mistral.ai/v1` (the OpenAI-compatible endpoint serving `/chat/completions` and `/embeddings`). `provider` defaults to `"mistral"` and flows through to `ModelContract.provider`, `AgentReport.model.provider`, and logs. Override `baseURL` only to reach a Mistral-compatible gateway/proxy. Every other upstream OpenAI `ClientOptions` value (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …) is forwarded verbatim.
-
-## Producing a model
-
-```ts
-mistral.model({ name: "mistral-large-latest" })             // multimodal flagship
-mistral.model({ name: "magistral-medium-latest" })          // reasoning
-mistral.model({ name: "pixtral-large-latest" })             // vision
-mistral.model({ name: "some-fine-tune", vision: true })     // explicit capability override
-```
-
-Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
-
-## Capabilities — what's auto-set
-
-The wrapper injects **Mistral-aware** inference before delegating to the OpenAI adapter (the OpenAI prefix lists never match Mistral names):
-
-| Flag | 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` is forwarded. |
-| `structuredOutput` | `true`, unless `responseFormat` is forced to `"json_object"` / `"text"` (loose modes). |
-| `promptCaching` | `true` (inherited from the OpenAI adapter — read-side `cachedTokens` accounting). |
-| `pdf` / `audio` | `false` by default (opt-in `.model({ pdf: true })` / `{ audio: true }`). |
-
-**Override any flag explicitly** via `.model({ name, vision?, reasoning?, structuredOutput?, responseFormat?, pdf?, audio? })` — an explicit value always wins over inference. The known-family fragments live in `known-models.ts` (`inferVisionCapability`, `inferReasoningCapability`).
-
-The headline `-latest` aliases are exported as `MISTRAL_MODELS` ({ chat, vision, reasoning, embedding }) for convenience — `mistral.model()` also accepts any version-pinned id (`mistral-large-2512`, `magistral-medium-2509`).
-
-## Uses the OpenAI-compatible endpoint
-
-Because Mistral speaks the OpenAI Chat Completions + Embeddings protocol, everything the OpenAI adapter does applies unchanged: streaming deltas + consolidated tool calls, `response_format: json_schema` structured output (override per model with `responseFormat`), `reasoning_effort` for reasoning models, multipart image input, and the neutral `Usage` breakdown (`input` / `output` / `cachedTokens` / `reasoningTokens`). See [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) for the wire-level detail — it is identical here.
-
-**No image generation.** Mistral has no OpenAI-compatible image endpoint, so `MistralSDK` intentionally does **not** expose `image()` — the structural absence is the capability guard (`ai.mistral.image(...)` is a compile-time error).
-
-## Embeddings
-
-```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"]);
-```
-
-`mistral-embed` is reachable through the OpenAI-compatible `/v1/embeddings`; the embedder delegates to the wrapped OpenAI embedder.
-
-## Pricing — per-model registry
-
-The adapter ships a conservative default registry (`MISTRAL_DEFAULT_PRICING`, USD per 1,000,000 tokens) so cost truth works out of the box. Pass your own `pricing` to win per model id:
-
-```ts
-const mistral = new MistralSDK({
-  apiKey,
-  pricing: {
-    // USD per 1M tokens — billing-grade overrides.
-    "mistral-large-latest":    { input: 2,   output: 6 },
-    "magistral-medium-latest": { input: 2,   output: 5 },
-  },
-});
-```
-
-Resolution at `model()` time: per-model `pricing` (`mistral.model({ name, pricing })`) > SDK-level `pricing` > `MISTRAL_DEFAULT_PRICING` > `undefined`. The defaults are list-price approximations — pass explicit rates for billing.
-
-## Errors
-
-Raw errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped OpenAI adapter (dispatch keys on `APIError.status + code`) — see [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
-
-## When NOT to use this skill
-
-- Image generation — Mistral has no OpenAI-compatible image endpoint; `mistral.image()` does not exist.
-- Other providers — OpenAI `@warlock.js/ai-openai`, Gemini `@warlock.js/ai-google`, Anthropic `@warlock.js/ai-anthropic`, Bedrock `@warlock.js/ai-bedrock`, Ollama `@warlock.js/ai-ollama`.
-- Raw `@mistralai/mistralai` SDK or Vercel `@ai-sdk/mistral` without going through `@warlock.js/ai` agents.
-
-## See also
-
-- [`@warlock.js/ai-openai/skills/setup-openai/SKILL.md`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — the wrapped adapter; identical wire behavior.
-- [`@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.
+---
+name: setup-mistral
+description: 'Wire @warlock.js/ai-mistral — new MistralSDK({apiKey, baseURL?, provider?, pricing?}) for Mistral AI, a thin wrapper over the OpenAI adapter that uses Mistral''s OpenAI-compatible endpoint (https://api.mistral.ai/v1). .model({name, vision?, reasoning?, structuredOutput?, responseFormat?, pdf?, audio?}) for a ModelContract with Mistral-aware capabilities (vision auto-inferred for the pixtral family, reasoning for the magistral family + hybrid mistral-small), .embedder({name, dimensions?}) for mistral-embed via /v1/embeddings. Triggers: `MistralSDK`, `mistral.model`, `mistral.embedder`, `pixtral`, `magistral`, `mistral-large`, `mistral-small`, `mistral-medium`, `ministral`, `mistral-embed`, `api.mistral.ai`, OpenAI-compatible Mistral, `reasoning_effort`, `responseFormat`, `pricing`; "use mistral", "wire mistral into a warlock agent", "configure mistral-large", "use magistral reasoning", "pixtral vision", "mistral embeddings with warlock". Skip: image generation (Mistral has no OpenAI-compatible image endpoint — `mistral.image()` does not exist); the wrapped adapter internals `@warlock.js/ai-openai`; agent wiring `@warlock.js/ai/run-ai-agent/SKILL.md`; embedder usage `@warlock.js/ai/embed-text/SKILL.md`; provider picking `@warlock.js/ai/pick-ai-provider/SKILL.md`; siblings `@warlock.js/ai-google`, `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-ollama`; raw `@mistralai/mistralai`, Vercel `@ai-sdk/mistral`.'
+---
+
+# `@warlock.js/ai-mistral`
+
+Provider adapter for Mistral AI. Mistral exposes an **OpenAI-compatible** API, so `MistralSDK` is a **thin wrapper** over [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — it does not re-implement the wire protocol, streaming, tool calls, structured output, error wrapping, or token accounting. It builds one internal `OpenAISDK` pointed at Mistral's `baseURL` with `provider: "mistral"`, then layers on this provider's own capability inference + default pricing. Pair with `@warlock.js/ai` for the agent / tool / system-prompt surface.
+
+## Construction
+
+```ts
+import { MistralSDK } from "@warlock.js/ai-mistral";
+
+const mistral = new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });
+```
+
+`baseURL` defaults to `https://api.mistral.ai/v1` (the OpenAI-compatible endpoint serving `/chat/completions` and `/embeddings`). `provider` defaults to `"mistral"` and flows through to `ModelContract.provider`, `AgentReport.model.provider`, and logs. Override `baseURL` only to reach a Mistral-compatible gateway/proxy. Every other upstream OpenAI `ClientOptions` value (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …) is forwarded verbatim.
+
+## Producing a model
+
+```ts
+mistral.model({ name: "mistral-large-latest" })             // multimodal flagship
+mistral.model({ name: "magistral-medium-latest" })          // reasoning
+mistral.model({ name: "pixtral-large-latest" })             // vision
+mistral.model({ name: "some-fine-tune", vision: true })     // explicit capability override
+```
+
+Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
+
+## Capabilities — what's auto-set
+
+The wrapper injects **Mistral-aware** inference before delegating to the OpenAI adapter (the OpenAI prefix lists never match Mistral names):
+
+| Flag | 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` is forwarded. |
+| `structuredOutput` | `true`, unless `responseFormat` is forced to `"json_object"` / `"text"` (loose modes). |
+| `promptCaching` | `true` (inherited from the OpenAI adapter — read-side `cachedTokens` accounting). |
+| `pdf` / `audio` | `false` by default (opt-in `.model({ pdf: true })` / `{ audio: true }`). |
+
+**Override any flag explicitly** via `.model({ name, vision?, reasoning?, structuredOutput?, responseFormat?, pdf?, audio? })` — an explicit value always wins over inference. The known-family fragments live in `known-models.ts` (`inferVisionCapability`, `inferReasoningCapability`).
+
+The headline `-latest` aliases are exported as `MISTRAL_MODELS` ({ chat, vision, reasoning, embedding }) for convenience — `mistral.model()` also accepts any version-pinned id (`mistral-large-2512`, `magistral-medium-2509`).
+
+## Uses the OpenAI-compatible endpoint
+
+Because Mistral speaks the OpenAI Chat Completions + Embeddings protocol, everything the OpenAI adapter does applies unchanged: streaming deltas + consolidated tool calls, `response_format: json_schema` structured output (override per model with `responseFormat`), `reasoning_effort` for reasoning models, multipart image input, and the neutral `Usage` breakdown (`input` / `output` / `cachedTokens` / `reasoningTokens`). See [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) for the wire-level detail — it is identical here.
+
+**No image generation.** Mistral has no OpenAI-compatible image endpoint, so `MistralSDK` intentionally does **not** expose `image()` — the structural absence is the capability guard (`ai.mistral.image(...)` is a compile-time error).
+
+## Embeddings
+
+```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"]);
+```
+
+`mistral-embed` is reachable through the OpenAI-compatible `/v1/embeddings`; the embedder delegates to the wrapped OpenAI embedder.
+
+## Pricing — per-model registry
+
+The adapter ships a conservative default registry (`MISTRAL_DEFAULT_PRICING`, USD per 1,000,000 tokens) so cost truth works out of the box. Pass your own `pricing` to win per model id:
+
+```ts
+const mistral = new MistralSDK({
+  apiKey,
+  pricing: {
+    // USD per 1M tokens — billing-grade overrides.
+    "mistral-large-latest":    { input: 2,   output: 6 },
+    "magistral-medium-latest": { input: 2,   output: 5 },
+  },
+});
+```
+
+Resolution at `model()` time: per-model `pricing` (`mistral.model({ name, pricing })`) > SDK-level `pricing` > `MISTRAL_DEFAULT_PRICING` > `undefined`. The defaults are list-price approximations — pass explicit rates for billing.
+
+## Errors
+
+Raw errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped OpenAI adapter (dispatch keys on `APIError.status + code`) — see [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
+
+## When NOT to use this skill
+
+- Image generation — Mistral has no OpenAI-compatible image endpoint; `mistral.image()` does not exist.
+- Other providers — OpenAI `@warlock.js/ai-openai`, Gemini `@warlock.js/ai-google`, Anthropic `@warlock.js/ai-anthropic`, Bedrock `@warlock.js/ai-bedrock`, Ollama `@warlock.js/ai-ollama`.
+- Raw `@mistralai/mistralai` SDK or Vercel `@ai-sdk/mistral` without going through `@warlock.js/ai` agents.
+
+## See also
+
+- [`@warlock.js/ai-openai/skills/setup-openai/SKILL.md`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — the wrapped adapter; identical wire behavior.
+- [`@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

@@ -6,4 +6,4 @@
 
 ## Skills
 
-- [setup-mistral](@warlock.js/ai-mistral/setup-mistral/SKILL.md): @warlock.js/ai-mistral in @warlock.js/ai-mistral; use when you need to set up mistral.
+- [setup-mistral](@warlock.js/ai-mistral/setup-mistral/SKILL.md): (no description)

package/package.json

@@ -15,13 +15,13 @@
     "url": "https://github.com/warlockjs/ai-mistral"
   },
   "dependencies": {
-    "@warlock.js/ai-openai": "5.19.1",
-    "@warlock.js/logger": "5.19.1"
+    "@warlock.js/ai-openai": "5.21.0",
+    "@warlock.js/logger": "5.21.0"
   },
   "peerDependencies": {
-    "@warlock.js/ai": "5.19.1"
+    "@warlock.js/ai": "5.21.0"
   },
-  "version": "5.19.1",
+  "version": "5.21.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/setup-mistral/SKILL.md

@@ -1,95 +1,95 @@
----
-name: setup-mistral
-description: "@warlock.js/ai-mistral in @warlock.js/ai-mistral; use when you need to set up mistral."
----
-
-# `@warlock.js/ai-mistral`
-
-Provider adapter for Mistral AI. Mistral exposes an **OpenAI-compatible** API, so `MistralSDK` is a **thin wrapper** over [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — it does not re-implement the wire protocol, streaming, tool calls, structured output, error wrapping, or token accounting. It builds one internal `OpenAISDK` pointed at Mistral's `baseURL` with `provider: "mistral"`, then layers on this provider's own capability inference + default pricing. Pair with `@warlock.js/ai` for the agent / tool / system-prompt surface.
-
-## Construction
-
-```ts
-import { MistralSDK } from "@warlock.js/ai-mistral";
-
-const mistral = new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });
-```
-
-`baseURL` defaults to `https://api.mistral.ai/v1` (the OpenAI-compatible endpoint serving `/chat/completions` and `/embeddings`). `provider` defaults to `"mistral"` and flows through to `ModelContract.provider`, `AgentReport.model.provider`, and logs. Override `baseURL` only to reach a Mistral-compatible gateway/proxy. Every other upstream OpenAI `ClientOptions` value (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …) is forwarded verbatim.
-
-## Producing a model
-
-```ts
-mistral.model({ name: "mistral-large-latest" })             // multimodal flagship
-mistral.model({ name: "magistral-medium-latest" })          // reasoning
-mistral.model({ name: "pixtral-large-latest" })             // vision
-mistral.model({ name: "some-fine-tune", vision: true })     // explicit capability override
-```
-
-Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
-
-## Capabilities — what's auto-set
-
-The wrapper injects **Mistral-aware** inference before delegating to the OpenAI adapter (the OpenAI prefix lists never match Mistral names):
-
-| Flag | 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` is forwarded. |
-| `structuredOutput` | `true`, unless `responseFormat` is forced to `"json_object"` / `"text"` (loose modes). |
-| `promptCaching` | `true` (inherited from the OpenAI adapter — read-side `cachedTokens` accounting). |
-| `pdf` / `audio` | `false` by default (opt-in `.model({ pdf: true })` / `{ audio: true }`). |
-
-**Override any flag explicitly** via `.model({ name, vision?, reasoning?, structuredOutput?, responseFormat?, pdf?, audio? })` — an explicit value always wins over inference. The known-family fragments live in `known-models.ts` (`inferVisionCapability`, `inferReasoningCapability`).
-
-The headline `-latest` aliases are exported as `MISTRAL_MODELS` ({ chat, vision, reasoning, embedding }) for convenience — `mistral.model()` also accepts any version-pinned id (`mistral-large-2512`, `magistral-medium-2509`).
-
-## Uses the OpenAI-compatible endpoint
-
-Because Mistral speaks the OpenAI Chat Completions + Embeddings protocol, everything the OpenAI adapter does applies unchanged: streaming deltas + consolidated tool calls, `response_format: json_schema` structured output (override per model with `responseFormat`), `reasoning_effort` for reasoning models, multipart image input, and the neutral `Usage` breakdown (`input` / `output` / `cachedTokens` / `reasoningTokens`). See [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) for the wire-level detail — it is identical here.
-
-**No image generation.** Mistral has no OpenAI-compatible image endpoint, so `MistralSDK` intentionally does **not** expose `image()` — the structural absence is the capability guard (`ai.mistral.image(...)` is a compile-time error).
-
-## Embeddings
-
-```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"]);
-```
-
-`mistral-embed` is reachable through the OpenAI-compatible `/v1/embeddings`; the embedder delegates to the wrapped OpenAI embedder.
-
-## Pricing — per-model registry
-
-The adapter ships a conservative default registry (`MISTRAL_DEFAULT_PRICING`, USD per 1,000,000 tokens) so cost truth works out of the box. Pass your own `pricing` to win per model id:
-
-```ts
-const mistral = new MistralSDK({
-  apiKey,
-  pricing: {
-    // USD per 1M tokens — billing-grade overrides.
-    "mistral-large-latest":    { input: 2,   output: 6 },
-    "magistral-medium-latest": { input: 2,   output: 5 },
-  },
-});
-```
-
-Resolution at `model()` time: per-model `pricing` (`mistral.model({ name, pricing })`) > SDK-level `pricing` > `MISTRAL_DEFAULT_PRICING` > `undefined`. The defaults are list-price approximations — pass explicit rates for billing.
-
-## Errors
-
-Raw errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped OpenAI adapter (dispatch keys on `APIError.status + code`) — see [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
-
-## When NOT to use this skill
-
-- Image generation — Mistral has no OpenAI-compatible image endpoint; `mistral.image()` does not exist.
-- Other providers — OpenAI `@warlock.js/ai-openai`, Gemini `@warlock.js/ai-google`, Anthropic `@warlock.js/ai-anthropic`, Bedrock `@warlock.js/ai-bedrock`, Ollama `@warlock.js/ai-ollama`.
-- Raw `@mistralai/mistralai` SDK or Vercel `@ai-sdk/mistral` without going through `@warlock.js/ai` agents.
-
-## See also
-
-- [`@warlock.js/ai-openai/skills/setup-openai/SKILL.md`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — the wrapped adapter; identical wire behavior.
-- [`@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.
+---
+name: setup-mistral
+description: 'Wire @warlock.js/ai-mistral — new MistralSDK({apiKey, baseURL?, provider?, pricing?}) for Mistral AI, a thin wrapper over the OpenAI adapter that uses Mistral''s OpenAI-compatible endpoint (https://api.mistral.ai/v1). .model({name, vision?, reasoning?, structuredOutput?, responseFormat?, pdf?, audio?}) for a ModelContract with Mistral-aware capabilities (vision auto-inferred for the pixtral family, reasoning for the magistral family + hybrid mistral-small), .embedder({name, dimensions?}) for mistral-embed via /v1/embeddings. Triggers: `MistralSDK`, `mistral.model`, `mistral.embedder`, `pixtral`, `magistral`, `mistral-large`, `mistral-small`, `mistral-medium`, `ministral`, `mistral-embed`, `api.mistral.ai`, OpenAI-compatible Mistral, `reasoning_effort`, `responseFormat`, `pricing`; "use mistral", "wire mistral into a warlock agent", "configure mistral-large", "use magistral reasoning", "pixtral vision", "mistral embeddings with warlock". Skip: image generation (Mistral has no OpenAI-compatible image endpoint — `mistral.image()` does not exist); the wrapped adapter internals `@warlock.js/ai-openai`; agent wiring `@warlock.js/ai/run-ai-agent/SKILL.md`; embedder usage `@warlock.js/ai/embed-text/SKILL.md`; provider picking `@warlock.js/ai/pick-ai-provider/SKILL.md`; siblings `@warlock.js/ai-google`, `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-ollama`; raw `@mistralai/mistralai`, Vercel `@ai-sdk/mistral`.'
+---
+
+# `@warlock.js/ai-mistral`
+
+Provider adapter for Mistral AI. Mistral exposes an **OpenAI-compatible** API, so `MistralSDK` is a **thin wrapper** over [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — it does not re-implement the wire protocol, streaming, tool calls, structured output, error wrapping, or token accounting. It builds one internal `OpenAISDK` pointed at Mistral's `baseURL` with `provider: "mistral"`, then layers on this provider's own capability inference + default pricing. Pair with `@warlock.js/ai` for the agent / tool / system-prompt surface.
+
+## Construction
+
+```ts
+import { MistralSDK } from "@warlock.js/ai-mistral";
+
+const mistral = new MistralSDK({ apiKey: process.env.MISTRAL_API_KEY! });
+```
+
+`baseURL` defaults to `https://api.mistral.ai/v1` (the OpenAI-compatible endpoint serving `/chat/completions` and `/embeddings`). `provider` defaults to `"mistral"` and flows through to `ModelContract.provider`, `AgentReport.model.provider`, and logs. Override `baseURL` only to reach a Mistral-compatible gateway/proxy. Every other upstream OpenAI `ClientOptions` value (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …) is forwarded verbatim.
+
+## Producing a model
+
+```ts
+mistral.model({ name: "mistral-large-latest" })             // multimodal flagship
+mistral.model({ name: "magistral-medium-latest" })          // reasoning
+mistral.model({ name: "pixtral-large-latest" })             // vision
+mistral.model({ name: "some-fine-tune", vision: true })     // explicit capability override
+```
+
+Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
+
+## Capabilities — what's auto-set
+
+The wrapper injects **Mistral-aware** inference before delegating to the OpenAI adapter (the OpenAI prefix lists never match Mistral names):
+
+| Flag | 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` is forwarded. |
+| `structuredOutput` | `true`, unless `responseFormat` is forced to `"json_object"` / `"text"` (loose modes). |
+| `promptCaching` | `true` (inherited from the OpenAI adapter — read-side `cachedTokens` accounting). |
+| `pdf` / `audio` | `false` by default (opt-in `.model({ pdf: true })` / `{ audio: true }`). |
+
+**Override any flag explicitly** via `.model({ name, vision?, reasoning?, structuredOutput?, responseFormat?, pdf?, audio? })` — an explicit value always wins over inference. The known-family fragments live in `known-models.ts` (`inferVisionCapability`, `inferReasoningCapability`).
+
+The headline `-latest` aliases are exported as `MISTRAL_MODELS` ({ chat, vision, reasoning, embedding }) for convenience — `mistral.model()` also accepts any version-pinned id (`mistral-large-2512`, `magistral-medium-2509`).
+
+## Uses the OpenAI-compatible endpoint
+
+Because Mistral speaks the OpenAI Chat Completions + Embeddings protocol, everything the OpenAI adapter does applies unchanged: streaming deltas + consolidated tool calls, `response_format: json_schema` structured output (override per model with `responseFormat`), `reasoning_effort` for reasoning models, multipart image input, and the neutral `Usage` breakdown (`input` / `output` / `cachedTokens` / `reasoningTokens`). See [`@warlock.js/ai-openai`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) for the wire-level detail — it is identical here.
+
+**No image generation.** Mistral has no OpenAI-compatible image endpoint, so `MistralSDK` intentionally does **not** expose `image()` — the structural absence is the capability guard (`ai.mistral.image(...)` is a compile-time error).
+
+## Embeddings
+
+```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"]);
+```
+
+`mistral-embed` is reachable through the OpenAI-compatible `/v1/embeddings`; the embedder delegates to the wrapped OpenAI embedder.
+
+## Pricing — per-model registry
+
+The adapter ships a conservative default registry (`MISTRAL_DEFAULT_PRICING`, USD per 1,000,000 tokens) so cost truth works out of the box. Pass your own `pricing` to win per model id:
+
+```ts
+const mistral = new MistralSDK({
+  apiKey,
+  pricing: {
+    // USD per 1M tokens — billing-grade overrides.
+    "mistral-large-latest":    { input: 2,   output: 6 },
+    "magistral-medium-latest": { input: 2,   output: 5 },
+  },
+});
+```
+
+Resolution at `model()` time: per-model `pricing` (`mistral.model({ name, pricing })`) > SDK-level `pricing` > `MISTRAL_DEFAULT_PRICING` > `undefined`. The defaults are list-price approximations — pass explicit rates for billing.
+
+## Errors
+
+Raw errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped OpenAI adapter (dispatch keys on `APIError.status + code`) — see [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
+
+## When NOT to use this skill
+
+- Image generation — Mistral has no OpenAI-compatible image endpoint; `mistral.image()` does not exist.
+- Other providers — OpenAI `@warlock.js/ai-openai`, Gemini `@warlock.js/ai-google`, Anthropic `@warlock.js/ai-anthropic`, Bedrock `@warlock.js/ai-bedrock`, Ollama `@warlock.js/ai-ollama`.
+- Raw `@mistralai/mistralai` SDK or Vercel `@ai-sdk/mistral` without going through `@warlock.js/ai` agents.
+
+## See also
+
+- [`@warlock.js/ai-openai/skills/setup-openai/SKILL.md`](@warlock.js/ai-openai/skills/setup-openai/SKILL.md) — the wrapped adapter; identical wire behavior.
+- [`@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.