@flink-app/test-utils 1.0.0 → 2.0.0-alpha.48

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @flink-app/test-utils
 
+## 2.0.0-alpha.48
+
+### Minor Changes
+
+-   AI features
+
 ## 1.0.0
 
 ### Minor Changes

package/dist/ai/conversation.d.ts

@@ -0,0 +1,27 @@
+import type { Message, ToolCall } from "@flink-app/flink/ai";
+/**
+ * Fluent builder for multi-turn conversation testing
+ * Simplifies creating conversation histories
+ *
+ * @example
+ * const conversation = createConversation()
+ *   .user("Book a flight to Paris")
+ *   .assistant("When would you like to travel?")
+ *   .user("Next Monday")
+ *   .assistant("Let me search", [
+ *     { id: "1", name: "search_flights", input: { destination: "Paris" } }
+ *   ])
+ *   .tool("1", "search_flights", JSON.stringify({ flights: [...] }))
+ *   .assistant("I found these flights...")
+ *   .build();
+ */
+export interface ConversationBuilder {
+    user(content: string): ConversationBuilder;
+    assistant(content: string, toolCalls?: ToolCall[]): ConversationBuilder;
+    tool(toolCallId: string, toolName: string, result: string): ConversationBuilder;
+    build(): Message[];
+}
+/**
+ * Creates a new conversation builder
+ */
+export declare function createConversation(): ConversationBuilder;

package/dist/ai/conversation.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConversation = createConversation;
+var ConversationBuilderImpl = /** @class */ (function () {
+    function ConversationBuilderImpl() {
+        this.messages = [];
+    }
+    ConversationBuilderImpl.prototype.user = function (content) {
+        this.messages.push({ role: "user", content: content });
+        return this;
+    };
+    ConversationBuilderImpl.prototype.assistant = function (content, toolCalls) {
+        this.messages.push({ role: "assistant", content: content, toolCalls: toolCalls });
+        return this;
+    };
+    ConversationBuilderImpl.prototype.tool = function (toolCallId, toolName, result) {
+        this.messages.push({ role: "tool", toolCallId: toolCallId, toolName: toolName, result: result });
+        return this;
+    };
+    ConversationBuilderImpl.prototype.build = function () {
+        return this.messages;
+    };
+    return ConversationBuilderImpl;
+}());
+/**
+ * Creates a new conversation builder
+ */
+function createConversation() {
+    return new ConversationBuilderImpl();
+}

package/dist/ai/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./mockLLMAdapter";
+export * from "./mockTool";
+export * from "./mockContext";
+export * from "./conversation";

package/dist/ai/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./mockLLMAdapter"), exports);
+__exportStar(require("./mockTool"), exports);
+__exportStar(require("./mockContext"), exports);
+__exportStar(require("./conversation"), exports);

package/dist/ai/mockContext.d.ts

@@ -0,0 +1,16 @@
+import { FlinkContext } from "@flink-app/flink";
+/**
+ * Creates a mock FlinkContext for tool testing
+ * Provides sensible defaults for all required properties
+ *
+ * @example
+ * const ctx = mockToolContext({
+ *   repos: { carRepo: mockCarRepo },
+ *   plugins: { email: mockEmailPlugin }
+ * });
+ *
+ * @example
+ * // Minimal usage with defaults
+ * const ctx = mockToolContext();
+ */
+export declare function mockToolContext<Ctx extends FlinkContext = FlinkContext>(overrides?: Partial<Ctx>): Ctx;

package/dist/ai/mockContext.js

@@ -0,0 +1,39 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockToolContext = mockToolContext;
+/**
+ * Creates a mock FlinkContext for tool testing
+ * Provides sensible defaults for all required properties
+ *
+ * @example
+ * const ctx = mockToolContext({
+ *   repos: { carRepo: mockCarRepo },
+ *   plugins: { email: mockEmailPlugin }
+ * });
+ *
+ * @example
+ * // Minimal usage with defaults
+ * const ctx = mockToolContext();
+ */
+function mockToolContext(overrides) {
+    if (overrides === void 0) { overrides = {}; }
+    var defaultContext = {
+        repos: {},
+        plugins: {},
+        agents: {},
+    };
+    return __assign(__assign(__assign({}, defaultContext), overrides), { 
+        // Deep merge repos, plugins, and agents
+        repos: __assign(__assign({}, defaultContext.repos), (overrides.repos || {})), plugins: __assign(__assign({}, defaultContext.plugins), (overrides.plugins || {})), agents: __assign(__assign({}, (defaultContext.agents || {})), (overrides.agents || {})) });
+}

package/dist/ai/mockLLMAdapter.d.ts

@@ -0,0 +1,90 @@
+import { LLMAdapter, LLMMessage, LLMStreamChunk } from "@flink-app/flink/ai";
+export interface MockLLMConfig {
+    response?: string;
+    responses?: Array<{
+        text?: string;
+        toolCalls?: Array<{
+            id: string;
+            name: string;
+            input: any;
+        }>;
+        stopReason?: "end_turn" | "tool_use" | "max_tokens";
+        streamChunks?: LLMStreamChunk[];
+    }>;
+    error?: Error;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    defaultStreamChunks?: LLMStreamChunk[];
+}
+export interface MockLLMAdapterInvocation {
+    instructions: string;
+    messages: LLMMessage[];
+    tools: any[];
+    maxTokens: number;
+    temperature: number;
+}
+export interface MockLLMAdapter extends LLMAdapter {
+    invocations: MockLLMAdapterInvocation[];
+    reset(): void;
+    getLastInvocation(): MockLLMAdapterInvocation | undefined;
+    getInvocationCount(): number;
+}
+/**
+ * Creates a mock LLM adapter for testing agents without API calls
+ *
+ * Features:
+ * - Canned responses (single or multi-turn)
+ * - Tool call simulation
+ * - Error simulation
+ * - Automatic invocation tracking
+ * - Token usage simulation
+ *
+ * @example
+ * // Simple response
+ * const adapter = mockLLMAdapter({ response: "Hello!" });
+ *
+ * @example
+ * // Multi-turn with tool calls
+ * const adapter = mockLLMAdapter({
+ *   responses: [
+ *     {
+ *       text: "Let me check",
+ *       toolCalls: [{ id: "1", name: "get_weather", input: { city: "Stockholm" } }]
+ *     },
+ *     { text: "It's sunny and 22°C" }
+ *   ]
+ * });
+ *
+ * @example
+ * // Error simulation
+ * const adapter = mockLLMAdapter({
+ *   error: new Error("Rate limit exceeded")
+ * });
+ */
+export declare function mockLLMAdapter(config?: MockLLMConfig): MockLLMAdapter;
+/**
+ * Helper function to create streaming chunks for testing
+ *
+ * @example
+ * const chunks = createStreamingChunks({
+ *   text: "Hello world",
+ *   chunkText: true,
+ *   toolCalls: [{ id: "1", name: "search", input: { query: "test" } }]
+ * });
+ */
+export declare function createStreamingChunks(config: {
+    text?: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        input: any;
+    }>;
+    chunkText?: boolean;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    stopReason?: "end_turn" | "tool_use" | "max_tokens";
+}): LLMStreamChunk[];

package/dist/ai/mockLLMAdapter.js

@@ -0,0 +1,252 @@
+"use strict";
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockLLMAdapter = mockLLMAdapter;
+exports.createStreamingChunks = createStreamingChunks;
+/**
+ * Creates a mock LLM adapter for testing agents without API calls
+ *
+ * Features:
+ * - Canned responses (single or multi-turn)
+ * - Tool call simulation
+ * - Error simulation
+ * - Automatic invocation tracking
+ * - Token usage simulation
+ *
+ * @example
+ * // Simple response
+ * const adapter = mockLLMAdapter({ response: "Hello!" });
+ *
+ * @example
+ * // Multi-turn with tool calls
+ * const adapter = mockLLMAdapter({
+ *   responses: [
+ *     {
+ *       text: "Let me check",
+ *       toolCalls: [{ id: "1", name: "get_weather", input: { city: "Stockholm" } }]
+ *     },
+ *     { text: "It's sunny and 22°C" }
+ *   ]
+ * });
+ *
+ * @example
+ * // Error simulation
+ * const adapter = mockLLMAdapter({
+ *   error: new Error("Rate limit exceeded")
+ * });
+ */
+function mockLLMAdapter(config) {
+    if (config === void 0) { config = {}; }
+    var invocations = [];
+    var responseQueue = [];
+    var currentResponseIndex = 0;
+    // Initialize response queue
+    if (config.response) {
+        responseQueue = [{ text: config.response, stopReason: "end_turn" }];
+    }
+    else if (config.responses) {
+        responseQueue = config.responses;
+    }
+    var defaultUsage = config.usage || { inputTokens: 10, outputTokens: 20 };
+    var stream = function (params) {
+        return __asyncGenerator(this, arguments, function () {
+            var responseConfig, _i, _a, chunk, _b, _c, chunk, _d, _e, toolCall, stopReason;
+            return __generator(this, function (_f) {
+                switch (_f.label) {
+                    case 0:
+                        // Track invocation
+                        invocations.push({
+                            instructions: params.instructions,
+                            messages: params.messages,
+                            tools: params.tools,
+                            maxTokens: params.maxTokens,
+                            temperature: params.temperature,
+                        });
+                        // Simulate error if configured
+                        if (config.error) {
+                            throw config.error;
+                        }
+                        responseConfig = responseQueue[currentResponseIndex] || responseQueue[responseQueue.length - 1];
+                        if (!responseConfig) {
+                            throw new Error("No responses configured for mockLLMAdapter");
+                        }
+                        currentResponseIndex++;
+                        if (!responseConfig.streamChunks) return [3 /*break*/, 7];
+                        _i = 0, _a = responseConfig.streamChunks;
+                        _f.label = 1;
+                    case 1:
+                        if (!(_i < _a.length)) return [3 /*break*/, 5];
+                        chunk = _a[_i];
+                        return [4 /*yield*/, __await(chunk)];
+                    case 2: return [4 /*yield*/, _f.sent()];
+                    case 3:
+                        _f.sent();
+                        _f.label = 4;
+                    case 4:
+                        _i++;
+                        return [3 /*break*/, 1];
+                    case 5: return [4 /*yield*/, __await(void 0)];
+                    case 6: return [2 /*return*/, _f.sent()];
+                    case 7:
+                        if (!config.defaultStreamChunks) return [3 /*break*/, 14];
+                        _b = 0, _c = config.defaultStreamChunks;
+                        _f.label = 8;
+                    case 8:
+                        if (!(_b < _c.length)) return [3 /*break*/, 12];
+                        chunk = _c[_b];
+                        return [4 /*yield*/, __await(chunk)];
+                    case 9: return [4 /*yield*/, _f.sent()];
+                    case 10:
+                        _f.sent();
+                        _f.label = 11;
+                    case 11:
+                        _b++;
+                        return [3 /*break*/, 8];
+                    case 12: return [4 /*yield*/, __await(void 0)];
+                    case 13: return [2 /*return*/, _f.sent()];
+                    case 14:
+                        if (!responseConfig.text) return [3 /*break*/, 17];
+                        return [4 /*yield*/, __await({
+                                type: "text",
+                                delta: responseConfig.text
+                            })];
+                    case 15: return [4 /*yield*/, _f.sent()];
+                    case 16:
+                        _f.sent();
+                        _f.label = 17;
+                    case 17:
+                        _d = 0, _e = responseConfig.toolCalls || [];
+                        _f.label = 18;
+                    case 18:
+                        if (!(_d < _e.length)) return [3 /*break*/, 22];
+                        toolCall = _e[_d];
+                        return [4 /*yield*/, __await({ type: "tool_call", toolCall: toolCall })];
+                    case 19: return [4 /*yield*/, _f.sent()];
+                    case 20:
+                        _f.sent();
+                        _f.label = 21;
+                    case 21:
+                        _d++;
+                        return [3 /*break*/, 18];
+                    case 22: return [4 /*yield*/, __await({
+                            type: "usage",
+                            usage: defaultUsage,
+                        })];
+                    case 23: return [4 /*yield*/, _f.sent()];
+                    case 24:
+                        _f.sent();
+                        stopReason = "end_turn";
+                        if (responseConfig.stopReason) {
+                            stopReason = responseConfig.stopReason;
+                        }
+                        else if (responseConfig.toolCalls && responseConfig.toolCalls.length > 0) {
+                            stopReason = "tool_use";
+                        }
+                        return [4 /*yield*/, __await({
+                                type: "done",
+                                stopReason: stopReason,
+                            })];
+                    case 25: return [4 /*yield*/, _f.sent()];
+                    case 26:
+                        _f.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    var reset = function () {
+        invocations.length = 0;
+        currentResponseIndex = 0;
+    };
+    var getLastInvocation = function () {
+        return invocations[invocations.length - 1];
+    };
+    var getInvocationCount = function () {
+        return invocations.length;
+    };
+    return {
+        stream: stream,
+        invocations: invocations,
+        reset: reset,
+        getLastInvocation: getLastInvocation,
+        getInvocationCount: getInvocationCount,
+    };
+}
+/**
+ * Helper function to create streaming chunks for testing
+ *
+ * @example
+ * const chunks = createStreamingChunks({
+ *   text: "Hello world",
+ *   chunkText: true,
+ *   toolCalls: [{ id: "1", name: "search", input: { query: "test" } }]
+ * });
+ */
+function createStreamingChunks(config) {
+    var chunks = [];
+    if (config.text) {
+        if (config.chunkText) {
+            // Split into multiple text deltas (by words)
+            var words = config.text.split(' ');
+            for (var _i = 0, words_1 = words; _i < words_1.length; _i++) {
+                var word = words_1[_i];
+                chunks.push({ type: "text", delta: word + ' ' });
+            }
+        }
+        else {
+            chunks.push({ type: "text", delta: config.text });
+        }
+    }
+    for (var _a = 0, _b = config.toolCalls || []; _a < _b.length; _a++) {
+        var toolCall = _b[_a];
+        chunks.push({ type: "tool_call", toolCall: toolCall });
+    }
+    chunks.push({
+        type: "usage",
+        usage: config.usage || { inputTokens: 100, outputTokens: 50 },
+    });
+    chunks.push({
+        type: "done",
+        stopReason: config.stopReason || (config.toolCalls && config.toolCalls.length > 0 ? "tool_use" : "end_turn"),
+    });
+    return chunks;
+}

package/dist/ai/mockTool.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import type { FlinkTool, FlinkToolProps } from "@flink-app/flink/ai";
+export interface MockToolConfig<Input, Output> {
+    name: string;
+    description?: string;
+    inputSchema: z.ZodType<Input>;
+    outputSchema?: z.ZodType<Output>;
+    response?: Output;
+    error?: {
+        error: string;
+        code?: string;
+    };
+    fn?: FlinkTool<any, Input, Output>;
+    permissions?: FlinkToolProps["permissions"];
+}
+export interface MockToolInvocation<Input> {
+    input: Input;
+    user?: any;
+}
+export interface MockToolResult<Input, Output> {
+    props: FlinkToolProps;
+    fn: FlinkTool<any, Input, Output>;
+    invocations: MockToolInvocation<Input>[];
+    getLastInvocation(): MockToolInvocation<Input> | undefined;
+    reset(): void;
+}
+/**
+ * Creates a mock tool with tracking and canned responses
+ *
+ * Features:
+ * - Simple canned responses
+ * - Error simulation
+ * - Custom function support
+ * - Automatic invocation tracking
+ * - Validation helpers
+ *
+ * @example
+ * // Simple canned response
+ * const weatherTool = mockTool({
+ *   name: "get_weather",
+ *   inputSchema: z.object({ city: z.string() }),
+ *   response: { temperature: 22, conditions: "sunny" }
+ * });
+ *
+ * @example
+ * // Custom function with tracking
+ * const calculatorTool = mockTool({
+ *   name: "calculate",
+ *   inputSchema: z.object({ a: z.number(), b: z.number() }),
+ *   fn: async ({ input }) => ({
+ *     success: true,
+ *     data: { result: input.a + input.b }
+ *   })
+ * });
+ *
+ * @example
+ * // Error simulation
+ * const failingTool = mockTool({
+ *   name: "fail",
+ *   inputSchema: z.object({}),
+ *   error: { error: "Tool failed", code: "MOCK_ERROR" }
+ * });
+ */
+export declare function mockTool<Input = any, Output = any>(config: MockToolConfig<Input, Output>): MockToolResult<Input, Output>;