@orq-ai/evaluatorq 1.2.2 → 1.2.3-rc.1

package/dist/lib/integrations/ai-sdk/index.d.ts

@@ -1,5 +1,7 @@
 export { generateItemId } from "../common/index.js";
 export { buildInputFromSteps, buildOpenResponsesFromSteps, convertToOpenResponses, } from "./convert.js";
+export type { AISdkSimulationAdapterOptions } from "./simulation-adapter.js";
+export { fromAISdkAgent } from "./simulation-adapter.js";
 export type { AgentJobOptions, StepData } from "./types.js";
 export { wrapAISdkAgent } from "./wrap-agent.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/integrations/ai-sdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/integrations/ai-sdk/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/integrations/ai-sdk/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/lib/integrations/ai-sdk/index.js

@@ -1,4 +1,5 @@
 // Re-export common utilities for backwards compatibility
 export { generateItemId } from "../common/index.js";
 export { buildInputFromSteps, buildOpenResponsesFromSteps, convertToOpenResponses, } from "./convert.js";
+export { fromAISdkAgent } from "./simulation-adapter.js";
 export { wrapAISdkAgent } from "./wrap-agent.js";

package/dist/lib/integrations/ai-sdk/simulation-adapter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Adapter to use Vercel AI SDK agents as simulation targets.
+ *
+ * Converts an AI SDK Agent into a `targetCallback` compatible with
+ * the simulation framework's `simulate()` and `wrapSimulationAgent()`.
+ */
+import type { Agent, ToolSet } from "ai";
+import type { ChatMessage } from "../simulation/types.js";
+/**
+ * Options for the AI SDK simulation adapter.
+ */
+export interface AISdkSimulationAdapterOptions {
+    /**
+     * System instructions to prepend to every call.
+     * If omitted, no system message is added — the agent uses its own defaults.
+     */
+    instructions?: string;
+}
+/**
+ * Wraps a Vercel AI SDK Agent as a simulation `targetCallback`.
+ *
+ * The returned function accepts `ChatMessage[]` (the simulation's message format)
+ * and returns the agent's text response as a string.
+ *
+ * @example
+ * ```typescript
+ * import { ToolLoopAgent, tool } from "ai";
+ * import { createOpenAI } from "@ai-sdk/openai";
+ * import { fromAISdkAgent } from "@orq-ai/evaluatorq/ai-sdk";
+ * import { simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ * const agent = new ToolLoopAgent({
+ *   model: openai("gpt-4o"),
+ *   tools: { ... },
+ * });
+ *
+ * const results = await simulate({
+ *   evaluationName: "my-agent-sim",
+ *   targetCallback: fromAISdkAgent(agent),
+ *   personas: [...],
+ *   scenarios: [...],
+ * });
+ * ```
+ */
+export declare function fromAISdkAgent<TOOLS extends ToolSet>(agent: Agent<never, TOOLS, never>, options?: AISdkSimulationAdapterOptions): (messages: ChatMessage[]) => Promise<string>;
+//# sourceMappingURL=simulation-adapter.d.ts.map

package/dist/lib/integrations/ai-sdk/simulation-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation-adapter.d.ts","sourceRoot":"","sources":["../../../../src/lib/integrations/ai-sdk/simulation-adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAgB,OAAO,EAAE,MAAM,IAAI,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,OAAO,EAClD,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EACjC,OAAO,GAAE,6BAAkC,GAC1C,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CA8B9C"}

package/dist/lib/integrations/ai-sdk/simulation-adapter.js

@@ -0,0 +1,58 @@
+/**
+ * Adapter to use Vercel AI SDK agents as simulation targets.
+ *
+ * Converts an AI SDK Agent into a `targetCallback` compatible with
+ * the simulation framework's `simulate()` and `wrapSimulationAgent()`.
+ */
+/**
+ * Wraps a Vercel AI SDK Agent as a simulation `targetCallback`.
+ *
+ * The returned function accepts `ChatMessage[]` (the simulation's message format)
+ * and returns the agent's text response as a string.
+ *
+ * @example
+ * ```typescript
+ * import { ToolLoopAgent, tool } from "ai";
+ * import { createOpenAI } from "@ai-sdk/openai";
+ * import { fromAISdkAgent } from "@orq-ai/evaluatorq/ai-sdk";
+ * import { simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ * const agent = new ToolLoopAgent({
+ *   model: openai("gpt-4o"),
+ *   tools: { ... },
+ * });
+ *
+ * const results = await simulate({
+ *   evaluationName: "my-agent-sim",
+ *   targetCallback: fromAISdkAgent(agent),
+ *   personas: [...],
+ *   scenarios: [...],
+ * });
+ * ```
+ */
+export function fromAISdkAgent(agent, options = {}) {
+    const { instructions } = options;
+    return async (messages) => {
+        const modelMessages = [];
+        if (instructions) {
+            modelMessages.push({
+                role: "system",
+                content: instructions,
+            });
+        }
+        for (const msg of messages) {
+            modelMessages.push({
+                role: msg.role,
+                content: msg.content,
+            });
+        }
+        const result = await agent.generate({ messages: modelMessages });
+        const text = result.text;
+        if (!text) {
+            console.warn("AI SDK fromAISdkAgent: agent result contained no text — returning empty string. " +
+                "If your agent only makes tool calls, ensure it also produces a final text response.");
+        }
+        return text ?? "";
+    };
+}

package/dist/lib/integrations/langchain/index.d.ts

@@ -22,6 +22,8 @@
  * ```
  */
 export { convertToOpenResponses } from "./convert.js";
+export type { LangChainSimulationAdapterOptions } from "./simulation-adapter.js";
+export { fromLangChainAgent } from "./simulation-adapter.js";
 export type { AgentJobOptions, ContentBlock, LangChainInvocable, LangChainMessage, LangChainResult, ResponseMetadata, ToolCall, ToolDefinition, UsageMetadata, } from "./types.js";
 export { extractToolsFromAgent, wrapLangChainAgent, wrapLangGraphAgent, } from "./wrap-agent.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/integrations/langchain/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/integrations/langchain/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EACV,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/integrations/langchain/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EAAE,iCAAiC,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EACV,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC"}

package/dist/lib/integrations/langchain/index.js

@@ -22,4 +22,5 @@
  * ```
  */
 export { convertToOpenResponses } from "./convert.js";
+export { fromLangChainAgent } from "./simulation-adapter.js";
 export { extractToolsFromAgent, wrapLangChainAgent, wrapLangGraphAgent, } from "./wrap-agent.js";

package/dist/lib/integrations/langchain/simulation-adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Adapter to use LangChain/LangGraph agents as simulation targets.
+ *
+ * Converts a LangChain invocable into a `targetCallback` compatible with
+ * the simulation framework's `simulate()` and `wrapSimulationAgent()`.
+ */
+import type { ChatMessage } from "../simulation/types.js";
+import type { LangChainInvocable } from "./types.js";
+/**
+ * Options for the LangChain simulation adapter.
+ */
+export interface LangChainSimulationAdapterOptions {
+    /**
+     * System instructions to prepend to every call.
+     * If omitted, no system message is added — the agent uses its own defaults.
+     */
+    instructions?: string;
+}
+/**
+ * Wraps a LangChain/LangGraph agent as a simulation `targetCallback`.
+ *
+ * The returned function accepts `ChatMessage[]` (the simulation's message format)
+ * and returns the agent's text response as a string.
+ *
+ * Compatible with:
+ * - LangChain agents created via `createAgent()` (langchain 1.x)
+ * - LangGraph compiled graphs (`StateGraph.compile()`)
+ * - Any object with an `invoke({ messages })` method
+ *
+ * @example
+ * ```typescript
+ * import { ChatOpenAI } from "@langchain/openai";
+ * import { createReactAgent } from "@langchain/langgraph/prebuilt";
+ * import { fromLangChainAgent } from "@orq-ai/evaluatorq/langchain";
+ * import { simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const model = new ChatOpenAI({ model: "gpt-4o" });
+ * const agent = createReactAgent({ llm: model, tools: [...] });
+ *
+ * const results = await simulate({
+ *   evaluationName: "my-agent-sim",
+ *   targetCallback: fromLangChainAgent(agent),
+ *   personas: [...],
+ *   scenarios: [...],
+ * });
+ * ```
+ */
+export declare function fromLangChainAgent(agent: LangChainInvocable, options?: LangChainSimulationAdapterOptions): (messages: ChatMessage[]) => Promise<string>;
+//# sourceMappingURL=simulation-adapter.d.ts.map

package/dist/lib/integrations/langchain/simulation-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation-adapter.d.ts","sourceRoot":"","sources":["../../../../src/lib/integrations/langchain/simulation-adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAgB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAChD;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,iCAAsC,GAC9C,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAoE9C"}

package/dist/lib/integrations/langchain/simulation-adapter.js

@@ -0,0 +1,110 @@
+/**
+ * Adapter to use LangChain/LangGraph agents as simulation targets.
+ *
+ * Converts a LangChain invocable into a `targetCallback` compatible with
+ * the simulation framework's `simulate()` and `wrapSimulationAgent()`.
+ */
+/**
+ * Extract text content from a LangChain message's content field.
+ * Handles both string content and ContentBlock[] arrays.
+ */
+function extractTextContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const block of content) {
+            if (typeof block === "string") {
+                parts.push(block);
+            }
+            else if (typeof block === "object" &&
+                block !== null &&
+                block.type === "text") {
+                parts.push(block.text ?? "");
+            }
+        }
+        return parts.join("");
+    }
+    return content ? String(content) : "";
+}
+/**
+ * Wraps a LangChain/LangGraph agent as a simulation `targetCallback`.
+ *
+ * The returned function accepts `ChatMessage[]` (the simulation's message format)
+ * and returns the agent's text response as a string.
+ *
+ * Compatible with:
+ * - LangChain agents created via `createAgent()` (langchain 1.x)
+ * - LangGraph compiled graphs (`StateGraph.compile()`)
+ * - Any object with an `invoke({ messages })` method
+ *
+ * @example
+ * ```typescript
+ * import { ChatOpenAI } from "@langchain/openai";
+ * import { createReactAgent } from "@langchain/langgraph/prebuilt";
+ * import { fromLangChainAgent } from "@orq-ai/evaluatorq/langchain";
+ * import { simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const model = new ChatOpenAI({ model: "gpt-4o" });
+ * const agent = createReactAgent({ llm: model, tools: [...] });
+ *
+ * const results = await simulate({
+ *   evaluationName: "my-agent-sim",
+ *   targetCallback: fromLangChainAgent(agent),
+ *   personas: [...],
+ *   scenarios: [...],
+ * });
+ * ```
+ */
+export function fromLangChainAgent(agent, options = {}) {
+    const { instructions } = options;
+    return async (messages) => {
+        const langchainMessages = [];
+        if (instructions) {
+            langchainMessages.push({ role: "system", content: instructions });
+        }
+        for (const msg of messages) {
+            langchainMessages.push({ role: msg.role, content: msg.content });
+        }
+        const result = await agent.invoke({ messages: langchainMessages });
+        // Handle agents that return a plain string directly
+        if (typeof result === "string")
+            return result;
+        if (typeof result.output === "string") {
+            return result.output;
+        }
+        // Extract the last AI/assistant message from the result
+        const resultMessages = result.messages;
+        if (!resultMessages || resultMessages.length === 0) {
+            console.warn("LangChain fromLangChainAgent: agent result contained no messages — returning empty string. " +
+                "Ensure the agent returns a state with a `messages` array, or return a string directly.");
+            return "";
+        }
+        // Walk backwards to find the last AI message
+        for (let i = resultMessages.length - 1; i >= 0; i--) {
+            const msg = resultMessages[i];
+            // Check for BaseMessage with _getType()
+            if (typeof msg._getType === "function") {
+                if (msg._getType() === "ai") {
+                    return extractTextContent(msg.content);
+                }
+                continue;
+            }
+            // Check for dict format with type field
+            if (msg.type === "ai" || msg.role === "assistant") {
+                return extractTextContent(msg.content);
+            }
+            // Check for constructor format (lc serialization)
+            if (msg.type === "constructor" &&
+                Array.isArray(msg.id) &&
+                msg.id.includes("AIMessage")) {
+                const kwargs = msg.kwargs;
+                return extractTextContent(kwargs?.content);
+            }
+        }
+        // Fallback: return the content of the last message regardless of type
+        const lastMsg = resultMessages[resultMessages.length - 1];
+        return extractTextContent(lastMsg?.content);
+    };
+}

package/dist/lib/integrations/simulation/adapters.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Convenience adapters for creating simulation targetCallbacks.
+ *
+ * These helpers create `targetCallback` functions from common agent sources,
+ * so users don't need to wire the plumbing themselves.
+ */
+import type { ChatMessage } from "./types.js";
+/**
+ * Creates a simulation `targetCallback` from an Orq deployment key.
+ *
+ * This is the same bridge that `simulate()` and `wrapSimulationAgent()` use
+ * internally when you pass `agentKey`, but exposed as a standalone function
+ * so you can compose it freely.
+ *
+ * @example
+ * ```typescript
+ * import { fromOrqDeployment, simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const callback = fromOrqDeployment("my-agent-deployment-key");
+ *
+ * const results = await simulate({
+ *   evaluationName: "my-sim",
+ *   targetCallback: callback,
+ *   personas: [...],
+ *   scenarios: [...],
+ * });
+ * ```
+ */
+export declare function fromOrqDeployment(agentKey: string): (messages: ChatMessage[]) => Promise<string>;
+/**
+ * Creates a simulation `targetCallback` from a plain function that calls
+ * an OpenAI-compatible chat completions API.
+ *
+ * Useful for raw OpenAI SDK, Azure OpenAI, or any OpenAI-compatible provider.
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ * import { fromChatCompletions, simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const client = new OpenAI();
+ * const callback = fromChatCompletions(async (messages) => {
+ *   const res = await client.chat.completions.create({
+ *     model: "gpt-4o",
+ *     messages,
+ *   });
+ *   return res.choices[0]?.message.content ?? "";
+ * });
+ *
+ * await simulate({ targetCallback: callback, ... });
+ * ```
+ */
+export declare function fromChatCompletions(fn: (messages: Array<{
+    role: string;
+    content: string;
+}>) => string | Promise<string>): (messages: ChatMessage[]) => Promise<string>;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/lib/integrations/simulation/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../../src/lib/integrations/simulation/adapters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GACf,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAS9C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,CACF,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,KAC/C,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAC5B,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAI9C"}

package/dist/lib/integrations/simulation/adapters.js

@@ -0,0 +1,64 @@
+/**
+ * Convenience adapters for creating simulation targetCallbacks.
+ *
+ * These helpers create `targetCallback` functions from common agent sources,
+ * so users don't need to wire the plumbing themselves.
+ */
+/**
+ * Creates a simulation `targetCallback` from an Orq deployment key.
+ *
+ * This is the same bridge that `simulate()` and `wrapSimulationAgent()` use
+ * internally when you pass `agentKey`, but exposed as a standalone function
+ * so you can compose it freely.
+ *
+ * @example
+ * ```typescript
+ * import { fromOrqDeployment, simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const callback = fromOrqDeployment("my-agent-deployment-key");
+ *
+ * const results = await simulate({
+ *   evaluationName: "my-sim",
+ *   targetCallback: callback,
+ *   personas: [...],
+ *   scenarios: [...],
+ * });
+ * ```
+ */
+export function fromOrqDeployment(agentKey) {
+    if (!agentKey.trim()) {
+        throw new Error("agentKey must be a non-empty string");
+    }
+    return async (messages) => {
+        const { invoke } = await import("../../deployment-helper.js");
+        return invoke(agentKey, { messages });
+    };
+}
+/**
+ * Creates a simulation `targetCallback` from a plain function that calls
+ * an OpenAI-compatible chat completions API.
+ *
+ * Useful for raw OpenAI SDK, Azure OpenAI, or any OpenAI-compatible provider.
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ * import { fromChatCompletions, simulate } from "@orq-ai/evaluatorq/simulation";
+ *
+ * const client = new OpenAI();
+ * const callback = fromChatCompletions(async (messages) => {
+ *   const res = await client.chat.completions.create({
+ *     model: "gpt-4o",
+ *     messages,
+ *   });
+ *   return res.choices[0]?.message.content ?? "";
+ * });
+ *
+ * await simulate({ targetCallback: callback, ... });
+ * ```
+ */
+export function fromChatCompletions(fn) {
+    return async (messages) => {
+        return fn(messages.map((m) => ({ role: m.role, content: m.content })));
+    };
+}

package/dist/lib/integrations/simulation/agents/base.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Base agent class for simulation agents.
+ *
+ * Provides common functionality for all agents in the simulation system,
+ * including LLM interaction with retry logic.
+ */
+import OpenAI from "openai";
+import type { ChatMessage, TokenUsage } from "../types.js";
+/**
+ * Result of a single LLM call, including optional tool calls.
+ */
+export interface LLMResult {
+    content: string;
+    tool_calls?: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[];
+}
+/**
+ * Configuration options for constructing an agent.
+ */
+export interface AgentConfig {
+    /** Model identifier (default: "azure/gpt-4o-mini"). */
+    model?: string;
+    /** Pre-existing OpenAI client to reuse. The agent will NOT close an injected client. */
+    client?: OpenAI;
+    /** API key override. Ignored when `client` is provided. */
+    apiKey?: string;
+}
+/**
+ * Abstract base class for simulation agents.
+ *
+ * Provides common LLM interaction functionality with exponential-backoff
+ * retry logic and cumulative token-usage tracking.
+ *
+ * **Client injection**: pass an existing `OpenAI` client via `config.client`
+ * to share a single HTTP connection across multiple agents. The agent will
+ * NOT close an injected client -- the caller is responsible for its lifecycle.
+ */
+export declare abstract class BaseAgent {
+    protected model: string;
+    protected client: OpenAI;
+    private clientOwned;
+    private usage;
+    constructor(config?: AgentConfig);
+    /** Agent name for identification. */
+    abstract get name(): string;
+    /** System prompt for this agent. */
+    abstract get systemPrompt(): string;
+    /**
+     * Generate a text response for a conversation.
+     *
+     * @param messages - Conversation history
+     * @param options  - Temperature, maxTokens, and timeout overrides
+     * @returns The agent's response text
+     * @throws {Error} If the LLM call returns no content
+     */
+    respondAsync(messages: ChatMessage[], options?: {
+        temperature?: number;
+        maxTokens?: number;
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * Get cumulative token usage for this agent.
+     */
+    getUsage(): TokenUsage;
+    /**
+     * Reset token usage counters to zero.
+     */
+    resetUsage(): void;
+    /**
+     * Close the underlying HTTP client.
+     *
+     * Only closes clients that the agent created itself (not injected ones).
+     */
+    close(): Promise<void>;
+    /**
+     * Call the LLM with retry logic (exponential backoff).
+     *
+     * Retries on rate-limit (429) and server errors (500+). All other errors
+     * are raised immediately.
+     */
+    protected callLLM(messages: ChatMessage[], options?: {
+        temperature?: number;
+        maxTokens?: number;
+        timeout?: number;
+        tools?: OpenAI.Chat.Completions.ChatCompletionTool[];
+        /** External abort signal — aborts in-flight LLM requests immediately. */
+        signal?: AbortSignal;
+    }): Promise<LLMResult>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/lib/integrations/simulation/agents/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../../src/lib/integrations/simulation/agents/base.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQ3D;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,6BAA6B,EAAE,CAAC;CACtE;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAUD;;;;;;;;;GASG;AACH,8BAAsB,SAAS;IAC7B,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,KAAK,CAAa;gBAEd,MAAM,CAAC,EAAE,WAAW;IA2BhC,qCAAqC;IACrC,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC;IAE5B,oCAAoC;IACpC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAC;IAMpC;;;;;;;OAOG;IACG,YAAY,CAChB,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,MAAM,CAAC;IAiBlB;;OAEG;IACH,QAAQ,IAAI,UAAU;IAItB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5B;;;;;OAKG;cACa,OAAO,CACrB,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC;QACrD,yEAAyE;QACzE,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,SAAS,CAAC;CAsHtB"}