@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/dist/src/ai/FlinkTool.d.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { FlinkContext } from "../FlinkContext";
+/**
+ * Standardized tool result format for better error handling
+ */
+export type ToolResult<T = any> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+    code?: string;
+};
+/**
+ * JSON Schema types
+ */
+export type JSONSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+/**
+ * JSON Schema for object types
+ */
+export interface JSONSchemaObject {
+    type: "object";
+    properties?: Record<string, ToolJSONSchema>;
+    required?: string[];
+    additionalProperties?: boolean | ToolJSONSchema;
+    description?: string;
+    [key: string]: any;
+}
+/**
+ * JSON Schema for array types
+ */
+export interface JSONSchemaArray {
+    type: "array";
+    items?: ToolJSONSchema | ToolJSONSchema[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    description?: string;
+    [key: string]: any;
+}
+/**
+ * JSON Schema for primitive types
+ */
+export interface JSONSchemaPrimitive {
+    type: "string" | "number" | "integer" | "boolean" | "null";
+    description?: string;
+    enum?: any[];
+    const?: any;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    [key: string]: any;
+}
+/**
+ * Recursive JSON Schema type for tools
+ * Used when you can't provide Zod schemas (e.g., stuck on Zod 3.x)
+ */
+export type ToolJSONSchema = JSONSchemaObject | JSONSchemaArray | JSONSchemaPrimitive;
+/**
+ * FlinkToolProps - defines a Flink AI tool
+ *
+ * You can provide schemas in three ways (in order of precedence):
+ * 1. Zod 4.x schemas: `inputSchema` + `outputSchema` (manual Zod validation)
+ * 2. JSON schemas: `inputJsonSchema` + `outputJsonSchema` (manual JSON Schema validation)
+ * 3. TypeScript types: Auto-generated from FlinkTool type parameters (no manual schemas needed!)
+ *
+ * If no manual schemas are provided, the compiler will automatically extract schemas
+ * from the FlinkTool<Ctx, Input, Output> type parameters.
+ */
+export interface FlinkToolProps {
+    /**
+     * Unique identifier for the tool (kebab-case)
+     * Used to reference the tool in agents and for registration
+     * Example: "get-cars-tool", "search-users-tool"
+     */
+    id: string;
+    description: string;
+    /**
+     * Zod schema for input validation and type inference
+     * Requires Zod 4.x for proper type inference
+     * OPTIONAL - if not provided, schema will be auto-generated from type parameters
+     *
+     * @example
+     * inputSchema: z.object({ name: z.string(), age: z.number() })
+     */
+    inputSchema?: z.ZodType<any>;
+    /**
+     * Optional Zod schema for output validation (validates the .data field)
+     * Requires Zod 4.x for proper type inference
+     * OPTIONAL - if not provided, schema will be auto-generated from type parameters
+     *
+     * @example
+     * outputSchema: z.string()
+     */
+    outputSchema?: z.ZodType<any>;
+    /**
+     * JSON Schema for input (alternative to inputSchema)
+     * Use this if you're stuck on Zod 3.x and can't upgrade
+     * OPTIONAL - if not provided, schema will be auto-generated from type parameters
+     * If both inputSchema and inputJsonSchema are provided, inputSchema takes precedence
+     */
+    inputJsonSchema?: ToolJSONSchema;
+    /**
+     * JSON Schema for output (alternative to outputSchema)
+     * Use this if you're stuck on Zod 3.x and can't upgrade
+     * OPTIONAL - if not provided, schema will be auto-generated from type parameters
+     * If both outputSchema and outputJsonSchema are provided, outputSchema takes precedence
+     */
+    outputJsonSchema?: ToolJSONSchema;
+    permissions?: string | string[] | ((input: any, user?: any) => boolean | Promise<boolean>);
+}
+export interface FlinkTool<Ctx extends FlinkContext, Input = any, Output = any, ConversationCtx = any> {
+    (params: {
+        input: Input;
+        ctx: Ctx;
+        user?: any;
+        permissions?: string[];
+        conversationCtx?: ConversationCtx;
+    }): Promise<ToolResult<Output>>;
+}
+export type FlinkToolFile = {
+    default: FlinkTool<any, any, any>;
+    Tool: FlinkToolProps;
+    /**
+     * Typescript source file path (relative to project root), set at compile time by Flink compiler.
+     * Used to look up tool metadata from schema-manifest.json at runtime.
+     */
+    __file?: string;
+};

package/dist/src/ai/FlinkTool.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/ai/InMemoryConversationAgent.d.ts

@@ -0,0 +1,121 @@
+import { FlinkContext } from "../FlinkContext";
+import { ConversationAgent, ConversationData } from "./ConversationAgent";
+import { AgentExecuteResult, AgentFinishContext } from "./FlinkAgent";
+/**
+ * Opinionated base class for agents with in-memory conversation persistence.
+ *
+ * Provides ready-to-use Map-based storage for rapid prototyping and testing.
+ * Storage methods (loadConversation/saveConversation) are already implemented - just extend and configure!
+ *
+ * ⚠️ **WARNING**: Data is stored in memory and lost on process restart.
+ * Only use for:
+ * - Rapid prototyping
+ * - Development environments
+ * - Integration testing
+ * - Demo applications
+ *
+ * For production, extend `ConversationAgent` with persistent storage (MongoDB, Redis, etc.)
+ *
+ * @example Basic Usage
+ * ```typescript
+ * export default class MyAgent extends InMemoryConversationAgent<AppContext> {
+ *     id = "my-agent";
+ *     description = "Quick prototype agent";
+ *     instructions = "You are a helpful assistant...";
+ *     tools = ["search-knowledge"];
+ *     // That's it! No loadConversation or saveConversation needed
+ * }
+ * ```
+ *
+ * @example With Custom Behavior
+ * ```typescript
+ * export default class CustomAgent extends InMemoryConversationAgent<AppContext> {
+ *     id = "custom-agent";
+ *     description = "Custom agent with hooks";
+ *     instructions = "...";
+ *
+ *     protected async afterRun(result, context) {
+ *         await super.afterRun(result, context); // Still saves to memory
+ *         // Add custom logic (logging, analytics, etc.)
+ *     }
+ * }
+ * ```
+ *
+ * @example Testing
+ * ```typescript
+ * beforeEach(() => {
+ *     InMemoryConversationAgent.clearAll(); // Reset between tests
+ * });
+ *
+ * it("should maintain conversation context", async () => {
+ *     const agent = new MyAgent();
+ *     await agent.execute({ message: "Hello", conversationId: "test-1" });
+ *
+ *     expect(InMemoryConversationAgent.getConversationCount()).toBe(1);
+ *     expect(InMemoryConversationAgent.getAllConversationIds()).toContain("test-1");
+ * });
+ * ```
+ *
+ * @template Context - Application context type extending FlinkContext
+ */
+export declare abstract class InMemoryConversationAgent<Context extends FlinkContext = FlinkContext> extends ConversationAgent<Context> {
+    /**
+     * Load conversation from in-memory Map.
+     *
+     * @internal Implemented by InMemoryConversationAgent - no need to override
+     */
+    protected loadConversation(conversationId: string): Promise<ConversationData | null>;
+    /**
+     * Save conversation to in-memory Map.
+     *
+     * @internal Implemented by InMemoryConversationAgent - no need to override
+     */
+    protected saveConversation(conversationId: string, data: ConversationData, result: AgentExecuteResult, context: AgentFinishContext): Promise<void>;
+    /**
+     * Clear all stored conversations.
+     * Useful for testing and resetting state.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *     InMemoryConversationAgent.clearAll();
+     * });
+     * ```
+     */
+    static clearAll(): void;
+    /**
+     * Get the number of stored conversations.
+     * Useful for testing and debugging.
+     *
+     * @example
+     * ```typescript
+     * expect(InMemoryConversationAgent.getConversationCount()).toBe(2);
+     * ```
+     */
+    static getConversationCount(): number;
+    /**
+     * Get a specific conversation by ID.
+     * Useful for testing and debugging.
+     *
+     * @param conversationId - The conversation ID to retrieve
+     * @returns Conversation data or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const conv = InMemoryConversationAgent.getConversation("conv-123");
+     * expect(conv?.messages.length).toBe(4);
+     * ```
+     */
+    static getConversation(conversationId: string): ConversationData | undefined;
+    /**
+     * Get all stored conversation IDs.
+     * Useful for testing and debugging.
+     *
+     * @example
+     * ```typescript
+     * const ids = InMemoryConversationAgent.getAllConversationIds();
+     * expect(ids).toContain("conv-123");
+     * ```
+     */
+    static getAllConversationIds(): string[];
+}

package/dist/src/ai/InMemoryConversationAgent.js

@@ -0,0 +1,209 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+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 };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryConversationAgent = void 0;
+var ConversationAgent_1 = require("./ConversationAgent");
+/**
+ * In-memory conversation storage (development/testing only).
+ *
+ * ⚠️ WARNING: Data is lost when the process restarts.
+ * Use MongoDB, Redis, or another persistent backend for production.
+ */
+var conversationStore = new Map();
+/**
+ * Opinionated base class for agents with in-memory conversation persistence.
+ *
+ * Provides ready-to-use Map-based storage for rapid prototyping and testing.
+ * Storage methods (loadConversation/saveConversation) are already implemented - just extend and configure!
+ *
+ * ⚠️ **WARNING**: Data is stored in memory and lost on process restart.
+ * Only use for:
+ * - Rapid prototyping
+ * - Development environments
+ * - Integration testing
+ * - Demo applications
+ *
+ * For production, extend `ConversationAgent` with persistent storage (MongoDB, Redis, etc.)
+ *
+ * @example Basic Usage
+ * ```typescript
+ * export default class MyAgent extends InMemoryConversationAgent<AppContext> {
+ *     id = "my-agent";
+ *     description = "Quick prototype agent";
+ *     instructions = "You are a helpful assistant...";
+ *     tools = ["search-knowledge"];
+ *     // That's it! No loadConversation or saveConversation needed
+ * }
+ * ```
+ *
+ * @example With Custom Behavior
+ * ```typescript
+ * export default class CustomAgent extends InMemoryConversationAgent<AppContext> {
+ *     id = "custom-agent";
+ *     description = "Custom agent with hooks";
+ *     instructions = "...";
+ *
+ *     protected async afterRun(result, context) {
+ *         await super.afterRun(result, context); // Still saves to memory
+ *         // Add custom logic (logging, analytics, etc.)
+ *     }
+ * }
+ * ```
+ *
+ * @example Testing
+ * ```typescript
+ * beforeEach(() => {
+ *     InMemoryConversationAgent.clearAll(); // Reset between tests
+ * });
+ *
+ * it("should maintain conversation context", async () => {
+ *     const agent = new MyAgent();
+ *     await agent.execute({ message: "Hello", conversationId: "test-1" });
+ *
+ *     expect(InMemoryConversationAgent.getConversationCount()).toBe(1);
+ *     expect(InMemoryConversationAgent.getAllConversationIds()).toContain("test-1");
+ * });
+ * ```
+ *
+ * @template Context - Application context type extending FlinkContext
+ */
+var InMemoryConversationAgent = /** @class */ (function (_super) {
+    __extends(InMemoryConversationAgent, _super);
+    function InMemoryConversationAgent() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    /**
+     * Load conversation from in-memory Map.
+     *
+     * @internal Implemented by InMemoryConversationAgent - no need to override
+     */
+    InMemoryConversationAgent.prototype.loadConversation = function (conversationId) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                ConversationAgent_1.logger.debug("Loading conversation ".concat(conversationId));
+                return [2 /*return*/, conversationStore.get(conversationId) || null];
+            });
+        });
+    };
+    /**
+     * Save conversation to in-memory Map.
+     *
+     * @internal Implemented by InMemoryConversationAgent - no need to override
+     */
+    InMemoryConversationAgent.prototype.saveConversation = function (conversationId, data, result, context) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                ConversationAgent_1.logger.debug("Saving ".concat(data.messages.length, " messages"));
+                conversationStore.set(conversationId, data);
+                return [2 /*return*/];
+            });
+        });
+    };
+    /**
+     * Clear all stored conversations.
+     * Useful for testing and resetting state.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *     InMemoryConversationAgent.clearAll();
+     * });
+     * ```
+     */
+    InMemoryConversationAgent.clearAll = function () {
+        conversationStore.clear();
+    };
+    /**
+     * Get the number of stored conversations.
+     * Useful for testing and debugging.
+     *
+     * @example
+     * ```typescript
+     * expect(InMemoryConversationAgent.getConversationCount()).toBe(2);
+     * ```
+     */
+    InMemoryConversationAgent.getConversationCount = function () {
+        return conversationStore.size;
+    };
+    /**
+     * Get a specific conversation by ID.
+     * Useful for testing and debugging.
+     *
+     * @param conversationId - The conversation ID to retrieve
+     * @returns Conversation data or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const conv = InMemoryConversationAgent.getConversation("conv-123");
+     * expect(conv?.messages.length).toBe(4);
+     * ```
+     */
+    InMemoryConversationAgent.getConversation = function (conversationId) {
+        return conversationStore.get(conversationId);
+    };
+    /**
+     * Get all stored conversation IDs.
+     * Useful for testing and debugging.
+     *
+     * @example
+     * ```typescript
+     * const ids = InMemoryConversationAgent.getAllConversationIds();
+     * expect(ids).toContain("conv-123");
+     * ```
+     */
+    InMemoryConversationAgent.getAllConversationIds = function () {
+        return Array.from(conversationStore.keys());
+    };
+    return InMemoryConversationAgent;
+}(ConversationAgent_1.ConversationAgent));
+exports.InMemoryConversationAgent = InMemoryConversationAgent;

package/dist/src/ai/LLMAdapter.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Generic message format for LLM conversations
+ * Compatible with most LLM providers (Anthropic, OpenAI, etc.)
+ */
+export type LLMMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | LLMContentBlock[];
+} | {
+    role: "assistant";
+    content: string | LLMContentBlock[];
+};
+export type LLMContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    url: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: any;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+/**
+ * Standard Flink tool schema format
+ * This is the format generated by ToolExecutor.getToolSchema()
+ * Adapters convert this to provider-specific formats
+ */
+export interface FlinkToolSchema {
+    /**
+     * Tool name (kebab-case identifier)
+     */
+    name: string;
+    /**
+     * Human-readable description for the LLM
+     */
+    description: string;
+    /**
+     * JSON Schema for tool input validation
+     * Generated from Zod schema via z.toJSONSchema()
+     */
+    inputSchema: Record<string, any>;
+}
+/**
+ * LLM Adapter interface for provider abstraction
+ * Enables support for multiple AI providers (Anthropic, OpenAI, Mistral, etc.)
+ *
+ * All adapters use streaming as the primary method since:
+ * - All modern LLM providers support streaming
+ * - Better user experience (time-to-first-token <500ms)
+ * - Prevents HTTP timeouts for long responses
+ * - FlinkAgent's lazy generator pattern allows both streaming and awaiting final result
+ *
+ * @template ToolSchema - The tool schema format accepted by this adapter (defaults to FlinkToolSchema)
+ */
+export interface LLMAdapter<ToolSchema = FlinkToolSchema> {
+    /**
+     * Optional debug flag to enable detailed logging
+     * When enabled, adapters will log:
+     * - Full request parameters sent to the LLM provider
+     * - Tool call decisions made by the LLM
+     * - Token usage and performance metrics
+     * - Error details and response metadata
+     *
+     * Useful for development and troubleshooting.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Stream a completion with tool calling support
+     * Returns async generator for streaming responses
+     *
+     * Even if you want non-streaming UX, use this method and await the final result:
+     * ```typescript
+     * const response = agent.execute({ message: "Hello" });
+     * const result = await response.result; // Non-streaming consumption
+     * ```
+     */
+    stream(params: {
+        /**
+         * Instructions that define agent behavior and personality.
+         * Adapters should prepend this as a system message to the conversation.
+         * Following Vercel AI SDK pattern.
+         */
+        instructions: string;
+        messages: LLMMessage[];
+        tools: ToolSchema[];
+        maxTokens: number;
+        temperature: number;
+        /**
+         * Provider-specific metadata for tracking and future use
+         * Example: { openai: { responseId: "resp_123" } }
+         */
+        providerMetadata?: Record<string, any>;
+    }): AsyncGenerator<LLMStreamChunk>;
+}
+/**
+ * Token usage information from LLM providers
+ *
+ * Includes cache-related metrics for cost optimization and performance tracking:
+ * - cachedInputTokens: Tokens served from cache (OpenAI, Anthropic)
+ * - cacheCreationInputTokens: Tokens written to cache (Anthropic only)
+ *
+ * Cache economics:
+ * - OpenAI: Cached tokens cost ~10% of regular tokens
+ * - Anthropic: Cache reads cost 10%, cache writes cost 125% of regular tokens
+ */
+export interface LLMUsage {
+    /** Total input tokens (including cached) */
+    inputTokens: number;
+    /** Total output tokens */
+    outputTokens: number;
+    /** Input tokens served from cache (lower cost) */
+    cachedInputTokens?: number;
+    /** Input tokens written to cache (Anthropic only, higher cost) */
+    cacheCreationInputTokens?: number;
+}
+/**
+ * Streaming chunk types
+ */
+export type LLMStreamChunk = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool_call";
+    toolCall: {
+        id: string;
+        name: string;
+        input: any;
+    };
+} | {
+    type: "usage";
+    usage: LLMUsage;
+} | {
+    type: "metadata";
+    metadata: Record<string, any>;
+} | {
+    type: "done";
+    stopReason: string;
+};

package/dist/src/ai/LLMAdapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });