@rouvanpm/rouva 0.4.1 → 0.5.1

package/README.md

@@ -24,7 +24,7 @@ console.log(response.choices[0].message.content)
 
 ## Provider agnostic
 
-Rouva works with all connected providers — Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Moonshot, xAI, Z.ai and Alibaba Qwen. You can request a specific model, force a specific provider, or omit both and let Rouva route to the cheapest capable model automatically.
+Rouva works with all connected providers — Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Moonshot, xAI, Z.ai, Alibaba Qwen and MiniMax. You can request a specific model, force a specific provider, or omit both and let Rouva route to the cheapest capable model automatically.
 
 ```typescript
 // Request a specific model
@@ -98,14 +98,14 @@ const res = await rouva.chat.completions.create({
 })
 ```
 
-- **`temperature`** — sampling temperature between 0 and 1. The gateway omits it for models that only accept their default: OpenAI reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+- **`temperature`** — sampling temperature between 0 and 1. The gateway omits it for models that only accept their default: OpenAI reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable), and models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
 - **`max_tokens`** / **`max_completion_tokens`** — either name works. Values below 1024 also steer auto-routing away from reasoning models, which would otherwise spend the whole budget on hidden reasoning tokens.
 - **`top_p`** — nucleus sampling; `top_p: 1` is treated as omitted. OpenAI reasoning models don't support it: routing avoids them when it's set, and pinning one returns a 400. The gateway omits it for the Claude models that reject it (as for `temperature`).
 - **`stop`** — a string or up to 4 stop sequences (Anthropic receives them as `stop_sequences`). OpenAI and xAI reasoning models (e.g. gpt-5, grok-4.5 / 4.6 / 4.7) reject it: routing avoids them when it's set, and pinning one returns a 400.
 - **`metadata`** — up to 10 string key-value pairs (keys up to 64 characters, values up to 256, no null bytes) stored with the request's usage record; not sent to the provider.
 - **`seed`** — best-effort deterministic sampling. Only OpenAI honors it, so it requires an OpenAI `model` and pins the request to that exact model (no routing, no fallbacks).
 - **`response_format`** — JSON mode or a JSON schema; see [Structured output](#structured-output).
-- **`reasoning_effort`** — `'none'` … `'xhigh'`, or `'max'` for Claude. Which values a model takes depends on the model; routing only picks one that takes yours; a listed OpenAI or Claude model you name that doesn't gets a 400, and other providers' models get the value as sent. On gpt-6-luna / gpt-6-sol, `'none'` turns reasoning off. See [the docs](https://rouva.io/docs#reasoning-effort).
+- **`reasoning_effort`** — `'none'` … `'xhigh'`, or `'max'` for Claude. Which values a model takes depends on the model; routing only picks one that takes yours; a listed OpenAI or Claude model you name that doesn't gets a 400, and other providers' models get the value as sent. On gpt-6-luna / gpt-6-sol / gpt-6.1-terra, `'none'` turns reasoning off. See [the docs](https://rouva.io/docs#reasoning-effort).
 - **`parallel_tool_calls`** — with `tools`: `false` allows at most one tool call per turn (Claude included).
 
 Unsupported OpenAI options (`logit_bias`, `logprobs`, `n > 1`, the legacy `functions`/`function_call` fields, …) are rejected by the gateway with an explicit 400 rather than silently ignored.
@@ -130,7 +130,7 @@ Non-tools requests on `/v1` honor the named model exactly unless the workspace o
 
 ## Tool use
 
-Tools are forwarded to your target provider verbatim — define them in the **provider's own format** (OpenAI `{ type: "function", function: {...} }` or Anthropic `{ name, description, input_schema }`) and pin the matching `model`. Tool schemas are provider-specific, so `model` is required and the gateway returns a 400 without it. Models that don't support tools on Chat Completions (`gpt-6.1-sol`, `gpt-5.6-*`) also return a 400.
+Tools are forwarded to your target provider verbatim — define them in the **provider's own format** (OpenAI `{ type: "function", function: {...} }` or Anthropic `{ name, description, input_schema }`) and pin the matching `model`. Tool schemas are provider-specific, so `model` is required and the gateway returns a 400 without it. `gpt-6.1-sol`, `gpt-6-astra` and `gpt-5.6-*` take tools only through OpenAI's Responses API: the gateway uses it for you and converts both ways, so you still send and receive Chat Completions (`seed`, `stop` and a `max_tokens` below 16 are a 400 there). `rouva.run()` still refuses these models.
 
 A tools request only ever moves to another model of the **same provider**: an account routing override for the task (when it targets the same provider), or — on the `/v1` endpoint with Intelligent Routing enabled — the cheapest capable model within that provider, using the named `model` as a cost ceiling (see [OpenAI-compatible endpoint](#openai-compatible-endpoint)). Otherwise the named model is honored exactly.
 
@@ -356,6 +356,25 @@ if (id) {
 
 `pending` means it hasn't settled yet — retry after a moment. `incomplete` means it settled from partial usage (a stream cut short), so the provider may have billed more; `settled` and `scored` costs are final. A key reads only its own requests. A duplicate-cache replay has no `request_id` (nothing new was recorded or charged).
 
+## Explain a routing decision — `rouva.explain()`
+
+A dry run: the model Rouva would pick for a request, why, and the most it could cost — without calling a provider, recording a request or reserving spend.
+
+```typescript
+const e = await rouva.explain({ model: 'gpt-6-sol', messages })
+
+if (e.would_send) {
+  console.log(e.model, e.provider)   // e.g. 'gpt-6-luna', 'openai'
+  console.log(e.route_reason)        // 'intelligent' | 'override' | 'allowlist' | 'direct' | …
+  console.log(e.task_type)           // e.g. 'summarize'
+  console.log(e.max_cost_usd)        // what a spend-capped key would reserve
+} else {
+  console.log(e.status, e.error)     // the refusal the real request would get
+}
+```
+
+It takes the same params as `chat.completions.create()`; pass `{ endpoint: 'v1' }` to explain the same body sent to `/v1/chat/completions`. The prompt is classified as for a real request, and explain has its own per-minute rate limit (a `RouvaError` with `refusal: 'rate'`). Not covered: the duplicate-request cache, a spend cap's remaining budget, and what the provider answers.
+
 ## Structured output
 
 `response_format` asks for JSON: `{ type: 'json_object' }` (JSON mode — your prompt must mention "json") or `{ type: 'json_schema', json_schema: { name, schema, strict } }` (the answer follows your schema). Rouva only routes to models that serve the format; see [the docs](https://rouva.io/docs#structured-output) for which models do.

package/dist/index.d.mts

@@ -50,9 +50,9 @@ interface ContentBlockMessage {
  * valid when `tools` is set on the request.
  */
 type ChatMessage = Message | AssistantToolCallMessage | ToolResultMessage | ContentBlockMessage;
-type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | (string & {});
+type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | 'minimax' | (string & {});
 /**
- * Supported models across all providers (the gateway's list as of SDK 0.3.0).
+ * Supported models across all providers (the gateway's list as of SDK 0.5.1).
  * Omit `model` entirely to let Rouva route to the cheapest capable model automatically.
  *
  * Other IDs are accepted by the type for forward compatibility. On
@@ -64,7 +64,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  *
  * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (string & {});
+type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-5-5' | 'claude-haiku-4-5-20251001' | 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6.1-terra' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-4-argon' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3.1-pro' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | 'MiniMax-M3.1-Flash' | 'MiniMax-M3' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -108,7 +108,8 @@ interface ChatCompletionParams {
      * Sampling temperature 0–1.
      * The gateway omits it for models that only accept their default: OpenAI
      * reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject
-     * it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable), and for
+     * models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     temperature?: number;
     /**
@@ -116,7 +117,8 @@ interface ChatCompletionParams {
      * default) is treated as omitted. OpenAI reasoning models (gpt-5 / gpt-6
      * families, o-series) don't support it: routing avoids them when top_p is
      * set, and pinning one returns a 400. The gateway omits it for the Claude
-     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable),
+     * and for models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     top_p?: number;
     /**
@@ -147,13 +149,14 @@ interface ChatCompletionParams {
      * How hard a reasoning model thinks (gateway support since 2026-10-21).
      * OpenAI models take it as is; Claude gets it as `output_config.effort`.
      * Values depend on the model: gpt-5 / -mini / -nano take minimal–high;
-     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol take none–xhigh; gpt-6.1-sol
-     * low–xhigh; Claude Sonnet / Opus 4.6 low, medium, high, max; newer Claude
-     * models also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
+     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol, gpt-6.1-terra take none–xhigh;
+     * gpt-6.1-sol and gpt-6-astra low–xhigh; Claude Sonnet / Opus 4.6 low, medium,
+     * high, max; newer Claude models (incl. Haiku 5.5) also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
      * only picks a model that takes the value; a listed OpenAI or Claude model you
-     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol, `'none'` turns reasoning off (temperature,
-     * top_p and tools then work) and any other value turns it on (tools and
-     * top_p are then a 400). `rouva.run()` doesn't accept it.
+     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol and gpt-6.1-terra, `'none'` turns reasoning off (temperature,
+     * top_p and tools then work) and any other value turns it on (top_p is then
+     * a 400; tools are served through OpenAI's Responses API). `rouva.run()`
+     * doesn't accept it.
      * See https://rouva.io/docs#reasoning-effort
      */
     reasoning_effort?: ReasoningEffort | null;
@@ -175,8 +178,10 @@ interface ChatCompletionParams {
      * Anthropic `{ name, description, input_schema }`). Requires `model`.
      * Tool schemas are provider-specific, so a tools request only ever moves to
      * another model of the SAME provider (a routing override, or cheaper-model
-     * routing on /v1). Models that don't support tools on Chat Completions
-     * (gpt-6.1-sol, gpt-5.6-*) return a 400.
+     * routing on /v1). gpt-6.1-sol, gpt-6-astra and gpt-5.6-* take tools only through
+     * OpenAI's Responses API: the gateway uses it for you and converts both ways
+     * (you still send and receive Chat Completions), and there `seed`, `stop` and
+     * a `max_tokens` below 16 are a 400. `rouva.run()` still refuses these models.
      */
     tools?: Array<Record<string, unknown>>;
     /**
@@ -185,6 +190,64 @@ interface ChatCompletionParams {
      */
     tool_choice?: string | Record<string, unknown>;
 }
+/**
+ * What `rouva.explain()` returns when the request would be sent: the model
+ * Rouva would pick, why, and the most it could cost — nothing was sent,
+ * recorded or reserved.
+ */
+interface RouvaExplanation {
+    dry_run: true;
+    would_send: true;
+    endpoint: '/api/gateway/messages' | '/v1/chat/completions';
+    provider: string;
+    model: string;
+    /** The model you named, or null. */
+    requested_model: string | null;
+    task_type: string | null;
+    route_reason: RouvaRouteReason;
+    /** How the prompt was classified (e.g. `jev`, `embedding`, `cache`). */
+    classified_by: string | null;
+    /** Jev's confidence (0–1), when Jev classified it. */
+    classifier_confidence: number | null;
+    classifier_latency_ms: number | null;
+    max_tokens: number;
+    stream: boolean;
+    /** The model's billed rates in USD per million tokens, or null when it has no known price. */
+    price_per_1m: {
+        input: number;
+        output: number;
+    } | null;
+    /**
+     * The most the request could cost in USD — what a spend-capped key reserves
+     * (the input as sent plus max_tokens of output, plus reasoning and
+     * summarization allowances where they apply). null: no known price.
+     */
+    max_cost_usd: number | null;
+    /** A long conversation's older turns would be summarized first (Claude). */
+    summarize_history: boolean;
+    spend_capped: boolean;
+}
+/** What `rouva.explain()` returns when the real request would be refused. */
+interface RouvaExplainedRefusal {
+    dry_run: true;
+    would_send: false;
+    /** The status the real request would get. */
+    status: number;
+    /** The error it would get. */
+    error: unknown;
+    /** `X-Rouva-Refusal`, when Rouva marks it (e.g. `unbounded`, `key_cap`). */
+    refusal: string | null;
+    /** The model Rouva had chosen before refusing, when it had chosen one. */
+    provider: string | null;
+    model: string | null;
+    route_reason: RouvaRouteReason | null;
+}
+type RouvaExplainResult = RouvaExplanation | RouvaExplainedRefusal;
+/** Options for `rouva.explain()`. */
+interface ExplainOptions extends RequestOptions {
+    /** `'v1'` explains the same body sent to /v1/chat/completions (which pins the named model). */
+    endpoint?: 'messages' | 'v1';
+}
 /** `reasoning_effort` values the gateway accepts (which ones a model takes varies). */
 type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 /** `response_format` values the gateway accepts. */
@@ -490,6 +553,25 @@ declare class Rouva {
     run(params: RunParams, options?: RequestOptions): Promise<RunResult>;
     private _getRequest;
     private _post;
+    /**
+     * Dry run (`POST /api/gateway/explain`): what Rouva would do with this
+     * request — the model and provider it would pick, why (`route_reason`), how
+     * the prompt was classified, and the most it could cost (`max_cost_usd`) —
+     * without calling a provider, recording a request or reserving spend. Takes
+     * the same params as `chat.completions.create()` (`stream` is ignored, as
+     * there). When the real request would be refused, resolves with
+     * `would_send: false` and the status and error it would get. Throws
+     * `RouvaError` for a bad key or the explain rate limit (429, `refusal: 'rate'`).
+     *
+     * The prompt is classified as for a real request. Not covered: the
+     * duplicate-request cache, a spend cap's remaining budget, provider errors.
+     *
+     * @example
+     * const e = await rouva.explain({ model: 'gpt-6-sol', messages })
+     * if (e.would_send) console.log(e.model, e.route_reason, e.max_cost_usd)
+     * else console.log(e.status, e.error)
+     */
+    explain(params: ChatCompletionParams, options?: ExplainOptions): Promise<RouvaExplainResult>;
     private _fetch;
     private _createChatCompletion;
 }
@@ -530,7 +612,7 @@ declare class RouvaError extends Error {
     readonly requestId?: string;
     /** The parsed JSON body, or the raw text when it isn't JSON. */
     readonly body: unknown;
-    constructor(kind: 'Gateway' | 'Run' | 'Request', status: number, headers: Headers, rawBody: string);
+    constructor(kind: 'Gateway' | 'Run' | 'Request' | 'Explain', status: number, headers: Headers, rawBody: string);
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type ExplainOptions, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaExplainResult, type RouvaExplainedRefusal, type RouvaExplanation, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.d.ts

@@ -50,9 +50,9 @@ interface ContentBlockMessage {
  * valid when `tools` is set on the request.
  */
 type ChatMessage = Message | AssistantToolCallMessage | ToolResultMessage | ContentBlockMessage;
-type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | (string & {});
+type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | 'minimax' | (string & {});
 /**
- * Supported models across all providers (the gateway's list as of SDK 0.3.0).
+ * Supported models across all providers (the gateway's list as of SDK 0.5.1).
  * Omit `model` entirely to let Rouva route to the cheapest capable model automatically.
  *
  * Other IDs are accepted by the type for forward compatibility. On
@@ -64,7 +64,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  *
  * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (string & {});
+type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-5-5' | 'claude-haiku-4-5-20251001' | 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6.1-terra' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-4-argon' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3.1-pro' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | 'MiniMax-M3.1-Flash' | 'MiniMax-M3' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -108,7 +108,8 @@ interface ChatCompletionParams {
      * Sampling temperature 0–1.
      * The gateway omits it for models that only accept their default: OpenAI
      * reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject
-     * it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable), and for
+     * models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     temperature?: number;
     /**
@@ -116,7 +117,8 @@ interface ChatCompletionParams {
      * default) is treated as omitted. OpenAI reasoning models (gpt-5 / gpt-6
      * families, o-series) don't support it: routing avoids them when top_p is
      * set, and pinning one returns a 400. The gateway omits it for the Claude
-     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable),
+     * and for models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     top_p?: number;
     /**
@@ -147,13 +149,14 @@ interface ChatCompletionParams {
      * How hard a reasoning model thinks (gateway support since 2026-10-21).
      * OpenAI models take it as is; Claude gets it as `output_config.effort`.
      * Values depend on the model: gpt-5 / -mini / -nano take minimal–high;
-     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol take none–xhigh; gpt-6.1-sol
-     * low–xhigh; Claude Sonnet / Opus 4.6 low, medium, high, max; newer Claude
-     * models also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
+     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol, gpt-6.1-terra take none–xhigh;
+     * gpt-6.1-sol and gpt-6-astra low–xhigh; Claude Sonnet / Opus 4.6 low, medium,
+     * high, max; newer Claude models (incl. Haiku 5.5) also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
      * only picks a model that takes the value; a listed OpenAI or Claude model you
-     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol, `'none'` turns reasoning off (temperature,
-     * top_p and tools then work) and any other value turns it on (tools and
-     * top_p are then a 400). `rouva.run()` doesn't accept it.
+     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol and gpt-6.1-terra, `'none'` turns reasoning off (temperature,
+     * top_p and tools then work) and any other value turns it on (top_p is then
+     * a 400; tools are served through OpenAI's Responses API). `rouva.run()`
+     * doesn't accept it.
      * See https://rouva.io/docs#reasoning-effort
      */
     reasoning_effort?: ReasoningEffort | null;
@@ -175,8 +178,10 @@ interface ChatCompletionParams {
      * Anthropic `{ name, description, input_schema }`). Requires `model`.
      * Tool schemas are provider-specific, so a tools request only ever moves to
      * another model of the SAME provider (a routing override, or cheaper-model
-     * routing on /v1). Models that don't support tools on Chat Completions
-     * (gpt-6.1-sol, gpt-5.6-*) return a 400.
+     * routing on /v1). gpt-6.1-sol, gpt-6-astra and gpt-5.6-* take tools only through
+     * OpenAI's Responses API: the gateway uses it for you and converts both ways
+     * (you still send and receive Chat Completions), and there `seed`, `stop` and
+     * a `max_tokens` below 16 are a 400. `rouva.run()` still refuses these models.
      */
     tools?: Array<Record<string, unknown>>;
     /**
@@ -185,6 +190,64 @@ interface ChatCompletionParams {
      */
     tool_choice?: string | Record<string, unknown>;
 }
+/**
+ * What `rouva.explain()` returns when the request would be sent: the model
+ * Rouva would pick, why, and the most it could cost — nothing was sent,
+ * recorded or reserved.
+ */
+interface RouvaExplanation {
+    dry_run: true;
+    would_send: true;
+    endpoint: '/api/gateway/messages' | '/v1/chat/completions';
+    provider: string;
+    model: string;
+    /** The model you named, or null. */
+    requested_model: string | null;
+    task_type: string | null;
+    route_reason: RouvaRouteReason;
+    /** How the prompt was classified (e.g. `jev`, `embedding`, `cache`). */
+    classified_by: string | null;
+    /** Jev's confidence (0–1), when Jev classified it. */
+    classifier_confidence: number | null;
+    classifier_latency_ms: number | null;
+    max_tokens: number;
+    stream: boolean;
+    /** The model's billed rates in USD per million tokens, or null when it has no known price. */
+    price_per_1m: {
+        input: number;
+        output: number;
+    } | null;
+    /**
+     * The most the request could cost in USD — what a spend-capped key reserves
+     * (the input as sent plus max_tokens of output, plus reasoning and
+     * summarization allowances where they apply). null: no known price.
+     */
+    max_cost_usd: number | null;
+    /** A long conversation's older turns would be summarized first (Claude). */
+    summarize_history: boolean;
+    spend_capped: boolean;
+}
+/** What `rouva.explain()` returns when the real request would be refused. */
+interface RouvaExplainedRefusal {
+    dry_run: true;
+    would_send: false;
+    /** The status the real request would get. */
+    status: number;
+    /** The error it would get. */
+    error: unknown;
+    /** `X-Rouva-Refusal`, when Rouva marks it (e.g. `unbounded`, `key_cap`). */
+    refusal: string | null;
+    /** The model Rouva had chosen before refusing, when it had chosen one. */
+    provider: string | null;
+    model: string | null;
+    route_reason: RouvaRouteReason | null;
+}
+type RouvaExplainResult = RouvaExplanation | RouvaExplainedRefusal;
+/** Options for `rouva.explain()`. */
+interface ExplainOptions extends RequestOptions {
+    /** `'v1'` explains the same body sent to /v1/chat/completions (which pins the named model). */
+    endpoint?: 'messages' | 'v1';
+}
 /** `reasoning_effort` values the gateway accepts (which ones a model takes varies). */
 type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 /** `response_format` values the gateway accepts. */
@@ -490,6 +553,25 @@ declare class Rouva {
     run(params: RunParams, options?: RequestOptions): Promise<RunResult>;
     private _getRequest;
     private _post;
+    /**
+     * Dry run (`POST /api/gateway/explain`): what Rouva would do with this
+     * request — the model and provider it would pick, why (`route_reason`), how
+     * the prompt was classified, and the most it could cost (`max_cost_usd`) —
+     * without calling a provider, recording a request or reserving spend. Takes
+     * the same params as `chat.completions.create()` (`stream` is ignored, as
+     * there). When the real request would be refused, resolves with
+     * `would_send: false` and the status and error it would get. Throws
+     * `RouvaError` for a bad key or the explain rate limit (429, `refusal: 'rate'`).
+     *
+     * The prompt is classified as for a real request. Not covered: the
+     * duplicate-request cache, a spend cap's remaining budget, provider errors.
+     *
+     * @example
+     * const e = await rouva.explain({ model: 'gpt-6-sol', messages })
+     * if (e.would_send) console.log(e.model, e.route_reason, e.max_cost_usd)
+     * else console.log(e.status, e.error)
+     */
+    explain(params: ChatCompletionParams, options?: ExplainOptions): Promise<RouvaExplainResult>;
     private _fetch;
     private _createChatCompletion;
 }
@@ -530,7 +612,7 @@ declare class RouvaError extends Error {
     readonly requestId?: string;
     /** The parsed JSON body, or the raw text when it isn't JSON. */
     readonly body: unknown;
-    constructor(kind: 'Gateway' | 'Run' | 'Request', status: number, headers: Headers, rawBody: string);
+    constructor(kind: 'Gateway' | 'Run' | 'Request' | 'Explain', status: number, headers: Headers, rawBody: string);
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type ExplainOptions, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaExplainResult, type RouvaExplainedRefusal, type RouvaExplanation, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.js

@@ -492,6 +492,31 @@ var Rouva = class {
   _post(path, body, extraHeaders, options) {
     return this._fetch("POST", path, body, extraHeaders, options);
   }
+  /**
+   * Dry run (`POST /api/gateway/explain`): what Rouva would do with this
+   * request — the model and provider it would pick, why (`route_reason`), how
+   * the prompt was classified, and the most it could cost (`max_cost_usd`) —
+   * without calling a provider, recording a request or reserving spend. Takes
+   * the same params as `chat.completions.create()` (`stream` is ignored, as
+   * there). When the real request would be refused, resolves with
+   * `would_send: false` and the status and error it would get. Throws
+   * `RouvaError` for a bad key or the explain rate limit (429, `refusal: 'rate'`).
+   *
+   * The prompt is classified as for a real request. Not covered: the
+   * duplicate-request cache, a spend cap's remaining budget, provider errors.
+   *
+   * @example
+   * const e = await rouva.explain({ model: 'gpt-6-sol', messages })
+   * if (e.would_send) console.log(e.model, e.route_reason, e.max_cost_usd)
+   * else console.log(e.status, e.error)
+   */
+  async explain(params, options) {
+    const { stream: _stream, ...body } = params;
+    const query = options?.endpoint === "v1" ? "?endpoint=v1" : "";
+    const res = await this._post(`/api/gateway/explain${query}`, body, {}, options);
+    if (!res.ok) throw await toRouvaError("Explain", res);
+    return res.json();
+  }
   // One request path for every endpoint: auth, JSON body, optional abort signal.
   _fetch(method, path, body, extraHeaders, options) {
     return fetch(`${this.baseURL}${path}`, {

package/dist/index.mjs

@@ -465,6 +465,31 @@ var Rouva = class {
   _post(path, body, extraHeaders, options) {
     return this._fetch("POST", path, body, extraHeaders, options);
   }
+  /**
+   * Dry run (`POST /api/gateway/explain`): what Rouva would do with this
+   * request — the model and provider it would pick, why (`route_reason`), how
+   * the prompt was classified, and the most it could cost (`max_cost_usd`) —
+   * without calling a provider, recording a request or reserving spend. Takes
+   * the same params as `chat.completions.create()` (`stream` is ignored, as
+   * there). When the real request would be refused, resolves with
+   * `would_send: false` and the status and error it would get. Throws
+   * `RouvaError` for a bad key or the explain rate limit (429, `refusal: 'rate'`).
+   *
+   * The prompt is classified as for a real request. Not covered: the
+   * duplicate-request cache, a spend cap's remaining budget, provider errors.
+   *
+   * @example
+   * const e = await rouva.explain({ model: 'gpt-6-sol', messages })
+   * if (e.would_send) console.log(e.model, e.route_reason, e.max_cost_usd)
+   * else console.log(e.status, e.error)
+   */
+  async explain(params, options) {
+    const { stream: _stream, ...body } = params;
+    const query = options?.endpoint === "v1" ? "?endpoint=v1" : "";
+    const res = await this._post(`/api/gateway/explain${query}`, body, {}, options);
+    if (!res.ok) throw await toRouvaError("Explain", res);
+    return res.json();
+  }
   // One request path for every endpoint: auth, JSON body, optional abort signal.
   _fetch(method, path, body, extraHeaders, options) {
     return fetch(`${this.baseURL}${path}`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rouvanpm/rouva",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Official Node.js SDK for Rouva — managed AI gateway with intelligent routing and spend tracking",
   "main": "dist/index.js",
   "module": "dist/index.mjs",