@flowlab/all/packages/ai/src/types.ts

A cool library focusing on handling various flows

// src/types.ts
import { IWorkflowContext, INodeContext } from '@flowlab/core';

/**
 * Configuration for an AI Provider instance.
 * Specific providers might extend this.
 */
export interface AIProviderConfig {
  apiKey?: string;       // API Key (consider secure loading, e.g., env vars)
  endpoint?: string;     // Custom endpoint URL
  defaultModel?: string; // Default model to use if not specified in options
  // Add other common configs like default timeouts, retry strategies specific to the provider
  [key: string]: any;    // Allow provider-specific options
}

/**
 * Common options for making an AI model request.
 */
export interface AIModelOptions {
  model?: string;         // Specific model identifier (e.g., 'gpt-4', 'gemini-pro')
  temperature?: number;   // Controls randomness (0.0 to 1.0+)
  maxTokens?: number;     // Max tokens to generate
  stopSequences?: string[]; // Sequences where generation should stop
  topP?: number;          // Nucleus sampling parameter
  presencePenalty?: number; // Penalize new tokens based on presence
  frequencyPenalty?: number;// Penalize new tokens based on frequency
  // Add specific options for vision, function calling etc. if needed
  userId?: string;        // Optional user identifier for tracking/moderation
  [key: string]: any;     // Allow model-specific options
}

/**
 * MARK: 使用信息
 * Standardized usage information returned by AI providers.
 */
export interface AIUsageInfo {
  promptTokens?: number;
  completionTokens?: number;
  totalTokens?: number;
  // Potentially add cost estimation here later
}

/**
 * MARK: AI 提供者接口
 * Interface defining the capabilities of an AI Provider.
 */
export interface IAIProvider {
  readonly providerName: string; // e.g., 'openai', 'gemini', 'anthropic'

  /** Generate text completion based on a prompt. */
  generateText(prompt: string, options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ text: string; usage?: AIUsageInfo }>;

  /** Engage in a chat-like conversation. */
  chatComplete(messages: Array<{ role: 'user' | 'assistant' | 'system'; content: string }>, options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ message: { role: 'assistant'; content: string }; usage?: AIUsageInfo }>;

  /** Generate vector embeddings for text. */
  generateEmbedding(text: string | string[], options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ embeddings: number[][] | number[]; usage?: AIUsageInfo }>;

  /** Extract structured data matching a JSON schema. */
  extractStructuredData<T extends object>(text: string, schema: object, options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ data: T; usage?: AIUsageInfo }>;

  /** Classify text against provided labels. */
  classify(text: string, labels: string[], options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ classification: { label: string; score: number }; usage?: AIUsageInfo }>;

  /** Request the AI to decide if a function should be called based on the prompt. */
  decideFunctionCall(prompt: string, functions: any[], options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ functionCall?: { name: string; arguments: object }; text?: string; usage?: AIUsageInfo }>;

  // --- Potential Future Additions ---
  generateImage(prompt: string, options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ image: string; usage?: AIUsageInfo }>;

  analyzeImage(image: string, options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ analysis: string; usage?: AIUsageInfo }>;

  transcribeAudio(audio: string, options?: AIModelOptions, nodeContext?: INodeContext): Promise<{ transcription: string; usage?: AIUsageInfo }>;
}