@rouvanpm/rouva 0.2.10 → 0.2.12

package/README.md

@@ -119,13 +119,13 @@ Models not recognised by the gateway return a `400` immediately:
 
 Using the OpenAI SDK (or LangChain, the Vercel AI SDK, …) instead of this one? The gateway is also served at `POST /v1/chat/completions` — point `baseURL` at `https://app.rouva.io/v1` with your `rva_` key and it behaves exactly like OpenAI: `model` is required, responses are buffered JSON unless `stream: true`, and only OpenAI-format providers are available (use this SDK or the native endpoint for Anthropic models).
 
-Intelligent routing applies to `/v1` too — Rouva may substitute a cheaper model within the same provider using your requested model as a cost ceiling. For tool call requests specifically, routing only considers non-reasoning models (reasoning models add unpredictable hidden token costs on tool dispatch). To pin a model exactly, disable Intelligent Routing in your dashboard under **Settings**.
+Non-tools requests on `/v1` always honor the named model exactly. **Tools requests on `/v1` benefit from within-provider intelligent routing** when Intelligent Routing is enabled in your dashboard — Rouva picks the cheapest capable model within the same provider, using the named `model` as a cost ceiling. The provider never changes (tool schemas are provider-specific), and `response.model` reflects the model that actually served the request. Turn Intelligent Routing off in dashboard Settings → Gateway to always pin the exact model.
 
 ## 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.
 
-On the native endpoint (`/api/gateway/messages`), the pinned model is always honored exactly — no substitution. On the `/v1` endpoint with Intelligent Routing enabled, Rouva may route to a cheaper non-reasoning model within the same provider. Disable Intelligent Routing in **Settings** to pin the exact model on `/v1`.
+When using the `/v1` endpoint (OpenAI SDK, LangChain, Vercel AI SDK, …) with Intelligent Routing enabled, tools requests are routed to the cheapest capable model within the same provider — see [OpenAI-compatible endpoint](#openai-compatible-endpoint) for details. On the native SDK endpoint (`/api/gateway/messages`), the named model is always honored exactly.
 
 ```typescript
 const res = await rouva.chat.completions.create({
@@ -167,7 +167,7 @@ Responses are normalized to the OpenAI shape regardless of provider: Anthropic `
 
 **Don't branch on `finish_reason` to detect tool calls** — check for the presence of `message.tool_calls` instead. `finish_reason` follows each provider's own semantics, and OpenAI notably returns `"stop"` (not `"tool_calls"`) when `tool_choice` forces a specific function. The SDK passes OpenAI's values through unchanged so behavior matches calling OpenAI directly.
 
-Tools requests record usage and cost but no savings, and are not quality-scored or served from the semantic cache.
+Tools requests record usage and cost. Savings are recorded when within-provider routing substitutes a cheaper model on `/v1`. Tools responses are not quality-scored or served from the semantic cache.
 
 ## Cost optimisations
 
@@ -190,6 +190,118 @@ const rouva = new Rouva({
 })
 ```
 
+## Agentic runs — `rouva.run()`
+
+`rouva.run()` hands the entire agent loop to the Rouva gateway. You define your tools and handler URLs; Rouva calls the model, dispatches tool calls in parallel to your endpoints, and loops until the model stops or a limit is reached — no client-side loop, no streaming required.
+
+```typescript
+const result = await rouva.run({
+  model: 'claude-haiku-4-5-20251001',
+  messages: [{ role: 'user', content: 'What is the weather in Paris and London?' }],
+  tools: [
+    {
+      name: 'get_weather',
+      description: 'Get current weather for a city',
+      input_schema: {
+        type: 'object',
+        properties: { city: { type: 'string' } },
+        required: ['city'],
+      },
+    },
+  ],
+  tool_handlers: {
+    get_weather: 'https://api.example.com/weather',  // gateway POSTs tool input here
+  },
+  max_turns: 5,
+  session_budget_usd: 0.10,  // optional hard cost cap
+})
+
+console.log(result.content)           // final model response
+console.log(result.turns)             // number of turns taken
+console.log(result.tool_calls_made)   // total tool calls dispatched
+console.log(result.session_id)        // dashboard session ID
+console.log(result.session_cost_usd)  // total USD spent
+```
+
+### How it works
+
+1. The gateway sends your `messages` to the model (non-streaming)
+2. When the model returns tool calls, all handlers are dispatched **in parallel** via POST — the request body is the tool's JSON input, the response body is used as the tool result
+3. Results are appended and the loop continues
+4. The loop exits when `finish_reason` is `"stop"` / `"end_turn"`, `max_turns` is reached, or `session_budget_usd` is exceeded
+
+Every turn is logged as a usage snapshot in the Rouva dashboard under the shared `session_id`, giving you a full session replay with per-turn cost, model used, tool calls, and quality score.
+
+### Handler URL requirements
+
+- Must be a public HTTPS URL (private/local addresses are rejected)
+- The gateway sends a `POST` with `Content-Type: application/json` and the tool's input object as the body
+- The response body (text or JSON) is returned to the model as the tool result
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `messages` | `ChatMessage[]` | ✓ | Conversation seed — usually a single user message |
+| `tools` | `object[]` | ✓ | Tool definitions (OpenAI or Anthropic format) |
+| `tool_handlers` | `Record<string, string>` | ✓ | Tool name → handler URL mapping |
+| `model` | `RouvaModel` | recommended | Model to use — required for Anthropic tools |
+| `provider` | `RouvaProvider` | | Force a specific provider |
+| `max_turns` | `number` | | Max loop iterations (default: 10) |
+| `max_tokens` | `number` | | Max tokens per turn (default: 4096) |
+| `temperature` | `number` | | Sampling temperature 0–1 |
+| `session_budget_usd` | `number` | | Hard USD cap across all turns |
+
+### Result shape
+
+```typescript
+interface RunResult {
+  content: string | null        // final model response text
+  turns: number                 // turns executed
+  tool_calls_made: number       // total tool calls dispatched
+  session_id: string            // groups all turns in the dashboard
+  finish_reason: string | null  // "stop", "end_turn", "max_turns", "budget_exceeded", "length"
+  cost_usd: number              // cost of the last turn
+  session_cost_usd: number      // cumulative cost across all turns
+}
+```
+
+### When to use `run()` vs `chat.completions.create()`
+
+| | `rouva.run()` | `chat.completions.create()` |
+|---|---|---|
+| Tool loop | Gateway-managed | Client-managed |
+| Session grouping | Automatic | Manual (`startSession`) |
+| Streaming | No | Yes |
+| Use when | Fully delegating an agentic task | Building your own loop or need streaming |
+
+## Agent session tracking
+
+Group all turns of an agent run under a single session ID so the Rouva dashboard can show per-session cost, token usage, and quality. Use this with `chat.completions.create()` when you manage the loop yourself.
+
+```typescript
+const rouva = new Rouva({ apiKey: 'rva_...' })
+
+// Start a session — auto-generates an ID and attaches it to every request
+const sessionId = rouva.startSession()
+
+// All turns carry the same session ID automatically
+await rouva.chat.completions.create({ messages: [...], tools: [...] })
+await rouva.chat.completions.create({ messages: [...], tools: [...] })
+await rouva.chat.completions.create({ messages: [...], tools: [...] })
+
+// End the session when the agent run is complete
+rouva.endSession()
+```
+
+You can also read the active session ID at any time:
+
+```typescript
+console.log(rouva.sessionId) // 'rva-sess-abc123' or undefined
+```
+
+Sessions are optional — requests without an active session are tracked individually as before.
+
 ## Response metadata
 
 Parsed non-stream responses may include a `_rouva` field with gateway header metadata when available:

package/dist/index.d.mts

@@ -164,6 +164,80 @@ interface RouvaResponseMeta {
     /** Semantic cache status when exposed by the gateway */
     cache?: string;
 }
+interface RunParams {
+    /**
+     * Conversation history to seed the agent loop with.
+     * Typically a single user message, but may include prior turns for
+     * multi-shot agents.
+     */
+    messages: ChatMessage[];
+    /**
+     * Tool definitions to expose to the model. Accepts both OpenAI-style
+     * `{ type: "function", function: { name, description, parameters } }` and
+     * Anthropic-style `{ name, description, input_schema }` objects.
+     * At least one tool is required.
+     */
+    tools: Array<Record<string, unknown>>;
+    /**
+     * Map of tool name → handler URL. When the model calls a tool, the gateway
+     * POSTs the tool input as JSON to the corresponding URL and feeds the
+     * response body back as the tool result. All handlers must be public HTTPS
+     * endpoints.
+     *
+     * @example
+     * { search: 'https://api.example.com/search', calculator: 'https://api.example.com/calc' }
+     */
+    tool_handlers: Record<string, string>;
+    /**
+     * Target model. Must be specified for tool calls — the gateway never
+     * re-routes tool requests across providers since tool schemas are
+     * provider-specific.
+     */
+    model?: RouvaModel;
+    /**
+     * Force a specific provider when paired with `model`.
+     */
+    provider?: RouvaProvider;
+    /**
+     * Maximum number of agentic turns before the loop exits.
+     * Defaults to 10. Each turn = one model call (plus parallel tool dispatch).
+     */
+    max_turns?: number;
+    /**
+     * Maximum tokens the model may generate per turn.
+     * Defaults to 4096.
+     */
+    max_tokens?: number;
+    /**
+     * Sampling temperature 0–1.
+     */
+    temperature?: number;
+    /**
+     * Hard cap on total session spend in USD. The loop exits cleanly when the
+     * cumulative cost of all turns reaches this threshold.
+     */
+    session_budget_usd?: number;
+}
+interface RunResult {
+    /** Final model response text after all tool loops complete. */
+    content: string | null;
+    /** Number of agentic turns executed. */
+    turns: number;
+    /** Total number of tool calls dispatched across all turns. */
+    tool_calls_made: number;
+    /** Session ID — all turns are grouped under this ID in the Rouva dashboard. */
+    session_id: string;
+    /**
+     * Why the loop exited: `"stop"` (model finished), `"max_turns"` (turn limit
+     * reached), `"budget_exceeded"` (session_budget_usd hit), or a provider
+     * finish reason such as `"end_turn"` or `"length"`.
+     */
+    finish_reason: string | null;
+    /** USD cost of the final turn. */
+    cost_usd: number;
+    /** Cumulative USD cost of all turns in the session. */
+    session_cost_usd: number;
+}
 
 declare class Rouva {
     private apiKey;
@@ -189,7 +263,29 @@ declare class Rouva {
     endSession(): void;
     /** The active session ID, or undefined if no session is in progress. */
     get sessionId(): string | undefined;
+    /**
+     * Run a server-side agentic loop. The gateway calls the model, dispatches
+     * tool calls in parallel to your handler URLs, and loops until the model
+     * stops or limits are reached — no streaming, no client-side loop required.
+     *
+     * Every turn is logged as a usage snapshot grouped by `session_id` in the
+     * Rouva dashboard, giving you a full session replay with per-turn cost,
+     * model, and tool call details.
+     *
+     * @example
+     * const result = await rouva.run({
+     *   model: 'claude-haiku-4-5-20251001',
+     *   messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
+     *   tools: [{ name: 'get_weather', description: '...', input_schema: { ... } }],
+     *   tool_handlers: { get_weather: 'https://api.example.com/weather' },
+     *   max_turns: 5,
+     * })
+     * console.log(result.content)      // final model response
+     * console.log(result.turns)        // how many turns it took
+     * console.log(result.session_id)   // dashboard session ID
+     */
+    run(params: RunParams): Promise<RunResult>;
     private _createChatCompletion;
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ResponseMessage, Rouva, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type SystemTextBlock, type ToolResultMessage };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ResponseMessage, Rouva, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.d.ts

@@ -164,6 +164,80 @@ interface RouvaResponseMeta {
     /** Semantic cache status when exposed by the gateway */
     cache?: string;
 }
+interface RunParams {
+    /**
+     * Conversation history to seed the agent loop with.
+     * Typically a single user message, but may include prior turns for
+     * multi-shot agents.
+     */
+    messages: ChatMessage[];
+    /**
+     * Tool definitions to expose to the model. Accepts both OpenAI-style
+     * `{ type: "function", function: { name, description, parameters } }` and
+     * Anthropic-style `{ name, description, input_schema }` objects.
+     * At least one tool is required.
+     */
+    tools: Array<Record<string, unknown>>;
+    /**
+     * Map of tool name → handler URL. When the model calls a tool, the gateway
+     * POSTs the tool input as JSON to the corresponding URL and feeds the
+     * response body back as the tool result. All handlers must be public HTTPS
+     * endpoints.
+     *
+     * @example
+     * { search: 'https://api.example.com/search', calculator: 'https://api.example.com/calc' }
+     */
+    tool_handlers: Record<string, string>;
+    /**
+     * Target model. Must be specified for tool calls — the gateway never
+     * re-routes tool requests across providers since tool schemas are
+     * provider-specific.
+     */
+    model?: RouvaModel;
+    /**
+     * Force a specific provider when paired with `model`.
+     */
+    provider?: RouvaProvider;
+    /**
+     * Maximum number of agentic turns before the loop exits.
+     * Defaults to 10. Each turn = one model call (plus parallel tool dispatch).
+     */
+    max_turns?: number;
+    /**
+     * Maximum tokens the model may generate per turn.
+     * Defaults to 4096.
+     */
+    max_tokens?: number;
+    /**
+     * Sampling temperature 0–1.
+     */
+    temperature?: number;
+    /**
+     * Hard cap on total session spend in USD. The loop exits cleanly when the
+     * cumulative cost of all turns reaches this threshold.
+     */
+    session_budget_usd?: number;
+}
+interface RunResult {
+    /** Final model response text after all tool loops complete. */
+    content: string | null;
+    /** Number of agentic turns executed. */
+    turns: number;
+    /** Total number of tool calls dispatched across all turns. */
+    tool_calls_made: number;
+    /** Session ID — all turns are grouped under this ID in the Rouva dashboard. */
+    session_id: string;
+    /**
+     * Why the loop exited: `"stop"` (model finished), `"max_turns"` (turn limit
+     * reached), `"budget_exceeded"` (session_budget_usd hit), or a provider
+     * finish reason such as `"end_turn"` or `"length"`.
+     */
+    finish_reason: string | null;
+    /** USD cost of the final turn. */
+    cost_usd: number;
+    /** Cumulative USD cost of all turns in the session. */
+    session_cost_usd: number;
+}
 
 declare class Rouva {
     private apiKey;
@@ -189,7 +263,29 @@ declare class Rouva {
     endSession(): void;
     /** The active session ID, or undefined if no session is in progress. */
     get sessionId(): string | undefined;
+    /**
+     * Run a server-side agentic loop. The gateway calls the model, dispatches
+     * tool calls in parallel to your handler URLs, and loops until the model
+     * stops or limits are reached — no streaming, no client-side loop required.
+     *
+     * Every turn is logged as a usage snapshot grouped by `session_id` in the
+     * Rouva dashboard, giving you a full session replay with per-turn cost,
+     * model, and tool call details.
+     *
+     * @example
+     * const result = await rouva.run({
+     *   model: 'claude-haiku-4-5-20251001',
+     *   messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
+     *   tools: [{ name: 'get_weather', description: '...', input_schema: { ... } }],
+     *   tool_handlers: { get_weather: 'https://api.example.com/weather' },
+     *   max_turns: 5,
+     * })
+     * console.log(result.content)      // final model response
+     * console.log(result.turns)        // how many turns it took
+     * console.log(result.session_id)   // dashboard session ID
+     */
+    run(params: RunParams): Promise<RunResult>;
     private _createChatCompletion;
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ResponseMessage, Rouva, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type SystemTextBlock, type ToolResultMessage };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ResponseMessage, Rouva, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.js

@@ -404,6 +404,43 @@ var Rouva = class {
   get sessionId() {
     return this._sessionId;
   }
+  /**
+   * Run a server-side agentic loop. The gateway calls the model, dispatches
+   * tool calls in parallel to your handler URLs, and loops until the model
+   * stops or limits are reached — no streaming, no client-side loop required.
+   *
+   * Every turn is logged as a usage snapshot grouped by `session_id` in the
+   * Rouva dashboard, giving you a full session replay with per-turn cost,
+   * model, and tool call details.
+   *
+   * @example
+   * const result = await rouva.run({
+   *   model: 'claude-haiku-4-5-20251001',
+   *   messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
+   *   tools: [{ name: 'get_weather', description: '...', input_schema: { ... } }],
+   *   tool_handlers: { get_weather: 'https://api.example.com/weather' },
+   *   max_turns: 5,
+   * })
+   * console.log(result.content)      // final model response
+   * console.log(result.turns)        // how many turns it took
+   * console.log(result.session_id)   // dashboard session ID
+   */
+  async run(params) {
+    const url = `${this.baseURL}/api/gateway/run`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(params)
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => res.statusText);
+      throw new Error(`[Rouva] Run error ${res.status}: ${body}`);
+    }
+    return res.json();
+  }
   async _createChatCompletion(params) {
     const url = `${this.baseURL}/api/gateway/messages`;
     const { stream: _stream, ...body } = params;

package/dist/index.mjs

@@ -378,6 +378,43 @@ var Rouva = class {
   get sessionId() {
     return this._sessionId;
   }
+  /**
+   * Run a server-side agentic loop. The gateway calls the model, dispatches
+   * tool calls in parallel to your handler URLs, and loops until the model
+   * stops or limits are reached — no streaming, no client-side loop required.
+   *
+   * Every turn is logged as a usage snapshot grouped by `session_id` in the
+   * Rouva dashboard, giving you a full session replay with per-turn cost,
+   * model, and tool call details.
+   *
+   * @example
+   * const result = await rouva.run({
+   *   model: 'claude-haiku-4-5-20251001',
+   *   messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
+   *   tools: [{ name: 'get_weather', description: '...', input_schema: { ... } }],
+   *   tool_handlers: { get_weather: 'https://api.example.com/weather' },
+   *   max_turns: 5,
+   * })
+   * console.log(result.content)      // final model response
+   * console.log(result.turns)        // how many turns it took
+   * console.log(result.session_id)   // dashboard session ID
+   */
+  async run(params) {
+    const url = `${this.baseURL}/api/gateway/run`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(params)
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => res.statusText);
+      throw new Error(`[Rouva] Run error ${res.status}: ${body}`);
+    }
+    return res.json();
+  }
   async _createChatCompletion(params) {
     const url = `${this.baseURL}/api/gateway/messages`;
     const { stream: _stream, ...body } = params;

package/package.json

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