@rouvanpm/rouva 0.4.0 → 0.5.0

package/README.md

@@ -105,8 +105,10 @@ const res = await rouva.chat.completions.create({
 - **`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).
+- **`parallel_tool_calls`** — with `tools`: `false` allows at most one tool call per turn (Claude included).
 
-Unsupported OpenAI options (`logit_bias`, `logprobs`, `reasoning_effort`, `n > 1`, the legacy `functions`/`function_call` fields, …) are rejected by the gateway with an explicit 400 rather than silently ignored.
+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.
 
 ## Unlisted models
 
@@ -128,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` 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.
 
@@ -354,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

@@ -143,6 +143,27 @@ interface ChatCompletionParams {
      * `rouva.run()` doesn't accept it. See https://rouva.io/docs#structured-output
      */
     response_format?: ResponseFormat | null;
+    /**
+     * 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
+     * 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 (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;
+    /**
+     * With `tools` only: `false` limits the model to at most one tool call per
+     * turn. Forwarded to OpenAI-format providers; for Claude the gateway sets
+     * `disable_parallel_tool_use` on `tool_choice`. `rouva.run()` doesn't accept it.
+     */
+    parallel_tool_calls?: boolean | null;
     /**
      * Stream the response. Client-side only — controls whether `create()`
      * returns a ReadableStream or a buffered ChatCompletion; never sent to
@@ -155,8 +176,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 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>>;
     /**
@@ -165,6 +188,66 @@ 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. */
 type ResponseFormat = {
     type: 'text';
@@ -468,6 +551,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;
 }
@@ -508,7 +610,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 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

@@ -143,6 +143,27 @@ interface ChatCompletionParams {
      * `rouva.run()` doesn't accept it. See https://rouva.io/docs#structured-output
      */
     response_format?: ResponseFormat | null;
+    /**
+     * 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
+     * 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 (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;
+    /**
+     * With `tools` only: `false` limits the model to at most one tool call per
+     * turn. Forwarded to OpenAI-format providers; for Claude the gateway sets
+     * `disable_parallel_tool_use` on `tool_choice`. `rouva.run()` doesn't accept it.
+     */
+    parallel_tool_calls?: boolean | null;
     /**
      * Stream the response. Client-side only — controls whether `create()`
      * returns a ReadableStream or a buffered ChatCompletion; never sent to
@@ -155,8 +176,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 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>>;
     /**
@@ -165,6 +188,66 @@ 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. */
 type ResponseFormat = {
     type: 'text';
@@ -468,6 +551,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;
 }
@@ -508,7 +610,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 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.0",
+  "version": "0.5.0",
   "description": "Official Node.js SDK for Rouva — managed AI gateway with intelligent routing and spend tracking",
   "main": "dist/index.js",
   "module": "dist/index.mjs",