@lleverage-ai/agent-sdk 0.0.1

package/dist/testing/recorder.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Recorded response playback system for testing.
+ *
+ * Allows recording agent interactions and replaying them deterministically
+ * for testing and development purposes.
+ *
+ * @packageDocumentation
+ */
+import type { LanguageModelUsage, ModelMessage } from "ai";
+import type { Agent, FinishReason, GenerateResultComplete } from "../types.js";
+import { type MockAgent } from "./mock-agent.js";
+/**
+ * A single recorded interaction.
+ *
+ * @category Testing
+ */
+export interface RecordedInteraction {
+    /** Timestamp when the interaction was recorded */
+    timestamp: string;
+    /** The request options */
+    request: {
+        prompt?: string;
+        messages?: ModelMessage[];
+        threadId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    /** The response */
+    response: {
+        text: string;
+        finishReason: FinishReason;
+        usage?: LanguageModelUsage;
+        output?: unknown;
+        steps?: GenerateResultComplete["steps"];
+    };
+    /** Method used (generate or stream) */
+    method: "generate" | "stream";
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Any error that occurred */
+    error?: {
+        message: string;
+        name: string;
+        stack?: string;
+    };
+}
+/**
+ * A recording session containing multiple interactions.
+ *
+ * @category Testing
+ */
+export interface Recording {
+    /** Version of the recording format */
+    version: string;
+    /** When the recording was created */
+    createdAt: string;
+    /** Optional description of the recording */
+    description?: string;
+    /** Optional tags for categorization */
+    tags?: string[];
+    /** The recorded interactions in order */
+    interactions: RecordedInteraction[];
+    /** Metadata about the recording session */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * An agent that records all interactions.
+ *
+ * @category Testing
+ */
+export interface RecordingAgent extends Agent {
+    /** Get all recorded interactions */
+    getRecording(): Recording;
+    /** Clear all recorded interactions */
+    clearRecording(): void;
+    /** Export recording to JSON */
+    exportRecording(): string;
+    /** The underlying agent being recorded */
+    readonly wrappedAgent: Agent;
+}
+/**
+ * Options for creating a recording agent.
+ *
+ * @category Testing
+ */
+export interface RecordingAgentOptions {
+    /** Description for the recording */
+    description?: string;
+    /** Tags for the recording */
+    tags?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Wraps an agent to record all interactions.
+ *
+ * Use this to capture real agent interactions that can later be replayed
+ * for testing. This is useful for creating deterministic test fixtures
+ * from actual API calls.
+ *
+ * @param agent - The agent to wrap and record
+ * @param options - Recording options
+ * @returns A recording agent that captures all interactions
+ *
+ * @example
+ * ```typescript
+ * import { createRecordingAgent } from "@lleverage-ai/agent-sdk/testing";
+ *
+ * // Wrap a real agent
+ * const recordingAgent = createRecordingAgent(realAgent, {
+ *   description: "User authentication flow",
+ * });
+ *
+ * // Make some real calls
+ * await recordingAgent.generate({ prompt: "Hello" });
+ * await recordingAgent.generate({ prompt: "How are you?" });
+ *
+ * // Export the recording
+ * const json = recordingAgent.exportRecording();
+ * fs.writeFileSync("auth-flow.json", json);
+ * ```
+ *
+ * @category Testing
+ */
+export declare function createRecordingAgent(agent: Agent, options?: RecordingAgentOptions): RecordingAgent;
+/**
+ * Options for creating a playback agent.
+ *
+ * @category Testing
+ */
+export interface PlaybackAgentOptions {
+    /** The recording to play back */
+    recording: Recording;
+    /** How to match requests to recordings */
+    matchMode?: "sequence" | "prompt" | "fuzzy";
+    /** Throw error if no matching recording found */
+    strict?: boolean;
+    /** Delay multiplier for simulating timing (0 = instant, 1 = real timing) */
+    timingMultiplier?: number;
+}
+/**
+ * An agent that plays back recorded interactions.
+ *
+ * @category Testing
+ */
+export interface PlaybackAgent extends MockAgent {
+    /** Get the current playback position */
+    getPlaybackPosition(): number;
+    /** Reset playback to the beginning */
+    resetPlayback(): void;
+    /** Get remaining interactions count */
+    getRemainingCount(): number;
+    /** Check if playback is complete */
+    isComplete(): boolean;
+}
+/**
+ * Creates an agent that plays back recorded interactions.
+ *
+ * Use this to replay previously recorded agent interactions for
+ * deterministic testing. This is useful for regression tests and
+ * testing code that depends on agent behavior.
+ *
+ * @param options - Playback configuration
+ * @returns A playback agent
+ *
+ * @example
+ * ```typescript
+ * import { createPlaybackAgent, parseRecording } from "@lleverage-ai/agent-sdk/testing";
+ * import recordingJson from "./fixtures/auth-flow.json";
+ *
+ * const agent = createPlaybackAgent({
+ *   recording: parseRecording(recordingJson),
+ *   matchMode: "sequence",
+ * });
+ *
+ * // Calls will return recorded responses in order
+ * const r1 = await agent.generate({ prompt: "Hello" });
+ * const r2 = await agent.generate({ prompt: "How are you?" });
+ *
+ * expect(agent.isComplete()).toBe(true);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Match by prompt content
+ * const agent = createPlaybackAgent({
+ *   recording,
+ *   matchMode: "prompt",
+ * });
+ *
+ * // Order doesn't matter - matches by prompt text
+ * await agent.generate({ prompt: "How are you?" }); // Matches second recording
+ * await agent.generate({ prompt: "Hello" }); // Matches first recording
+ * ```
+ *
+ * @category Testing
+ */
+export declare function createPlaybackAgent(options: PlaybackAgentOptions): PlaybackAgent;
+/**
+ * Parse a recording from JSON.
+ *
+ * @param json - JSON string or object
+ * @returns Parsed recording
+ *
+ * @example
+ * ```typescript
+ * const recording = parseRecording(fs.readFileSync("recording.json", "utf-8"));
+ * ```
+ *
+ * @category Testing
+ */
+export declare function parseRecording(json: string | object): Recording;
+/**
+ * Merge multiple recordings into one.
+ *
+ * @param recordings - Recordings to merge
+ * @param options - Merge options
+ * @returns Merged recording
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeRecordings([recording1, recording2], {
+ *   description: "Combined test fixtures",
+ * });
+ * ```
+ *
+ * @category Testing
+ */
+export declare function mergeRecordings(recordings: Recording[], options?: {
+    description?: string;
+    tags?: string[];
+}): Recording;
+/**
+ * Filter a recording to include only matching interactions.
+ *
+ * @param recording - Recording to filter
+ * @param predicate - Filter function
+ * @returns Filtered recording
+ *
+ * @example
+ * ```typescript
+ * // Keep only successful interactions
+ * const filtered = filterRecording(recording, (i) => !i.error);
+ *
+ * // Keep only generate calls
+ * const generates = filterRecording(recording, (i) => i.method === "generate");
+ * ```
+ *
+ * @category Testing
+ */
+export declare function filterRecording(recording: Recording, predicate: (interaction: RecordedInteraction) => boolean): Recording;
+/**
+ * Create a recording from manual interaction definitions.
+ *
+ * Useful for creating test fixtures without running actual agent calls.
+ *
+ * @param interactions - Interactions to include
+ * @param options - Recording options
+ * @returns A recording object
+ *
+ * @example
+ * ```typescript
+ * const recording = createRecording([
+ *   {
+ *     request: { prompt: "Hello" },
+ *     response: { text: "Hi there!", finishReason: "stop" },
+ *   },
+ *   {
+ *     request: { prompt: "Goodbye" },
+ *     response: { text: "See you!", finishReason: "stop" },
+ *   },
+ * ], { description: "Basic greeting flow" });
+ * ```
+ *
+ * @category Testing
+ */
+export declare function createRecording(interactions: Array<{
+    request: RecordedInteraction["request"];
+    response: RecordedInteraction["response"];
+    method?: "generate" | "stream";
+    duration?: number;
+    error?: RecordedInteraction["error"];
+}>, options?: {
+    description?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}): Recording;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/testing/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/testing/recorder.ts"],"names":[],"mappings":"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"}