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

package/src/ai/FlinkTool.ts

@@ -0,0 +1,165 @@
+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; // Allow additional JSON Schema keywords
+}
+
+/**
+ * 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;
+  // String-specific
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  // Number-specific
+  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; // For AI understanding
+
+  /**
+   * 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/src/ai/InMemoryConversationAgent.ts

@@ -0,0 +1,149 @@
+import { FlinkContext } from "../FlinkContext";
+import { ConversationAgent, ConversationData, logger } from "./ConversationAgent";
+import { AgentExecuteResult, AgentFinishContext } from "./FlinkAgent";
+
+/**
+ * In-memory conversation storage (development/testing only).
+ *
+ * ⚠️ WARNING: Data is lost when the process restarts.
+ * Use MongoDB, Redis, or another persistent backend for production.
+ */
+const conversationStore = new Map<string, ConversationData>();
+
+/**
+ * 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 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 async loadConversation(conversationId: string): Promise<ConversationData | null> {
+        logger.debug(`Loading conversation ${conversationId}`);
+        return conversationStore.get(conversationId) || null;
+    }
+
+    /**
+     * Save conversation to in-memory Map.
+     *
+     * @internal Implemented by InMemoryConversationAgent - no need to override
+     */
+    protected async saveConversation(conversationId: string, data: ConversationData, result: AgentExecuteResult, context: AgentFinishContext): Promise<void> {
+        logger.debug(`Saving ${data.messages.length} messages`);
+        conversationStore.set(conversationId, data);
+    }
+
+    /**
+     * Clear all stored conversations.
+     * Useful for testing and resetting state.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *     InMemoryConversationAgent.clearAll();
+     * });
+     * ```
+     */
+    static clearAll(): void {
+        conversationStore.clear();
+    }
+
+    /**
+     * Get the number of stored conversations.
+     * Useful for testing and debugging.
+     *
+     * @example
+     * ```typescript
+     * expect(InMemoryConversationAgent.getConversationCount()).toBe(2);
+     * ```
+     */
+    static getConversationCount(): number {
+        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);
+     * ```
+     */
+    static getConversation(conversationId: string): ConversationData | undefined {
+        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");
+     * ```
+     */
+    static getAllConversationIds(): string[] {
+        return Array.from(conversationStore.keys());
+    }
+}

package/src/ai/LLMAdapter.ts

@@ -0,0 +1,126 @@
+/**
+ * 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> } // Provider-specific metadata (e.g., responseId)
+  | { type: "done"; stopReason: string };