@rouvanpm/rouva 0.2.11 → 0.2.12

package/README.md

@@ -190,9 +190,94 @@ 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.
+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_...' })

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.11",
+  "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",