@od-oneapp/ai-platform 0.1.0

package/src/streaming/control/budget-guard.ts

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview Budget guard utilities for token and cost limits.
+ * @module @od-oneapp/ai-platform/streaming-control
+ *
+ * Provides functions for calculating costs and checking budget limits:
+ * - Cost calculation based on token usage and model pricing
+ * - Budget checking for token and cost limits
+ * - OnFinish handlers for AI SDK integration
+ *
+ * @example
+ * ```ts
+ * import {
+ *   calculateCost,
+ *   createBudgetChecker,
+ *   createBudgetGuardedOnFinish,
+ *   DEFAULT_COST_TABLE
+ * } from '@od-oneapp/ai-platform/streaming-control';
+ *
+ * const cost = calculateCost(
+ *   { promptTokens: 1000, completionTokens: 500, totalTokens: 1500 },
+ *   'gpt-4o'
+ * );
+ * ```
+ */
+
+import {
+  type BudgetCheckResult,
+  type BudgetGuardConfig,
+  type CostEntry,
+  type TokenUsage,
+} from './types';
+
+/**
+ * Default cost table for common models.
+ * Prices are per 1K tokens in USD.
+ *
+ * @remarks
+ * Prices are approximate and may change. Update this table
+ * or provide custom entries via BudgetGuardConfig.costTable.
+ */
+export const DEFAULT_COST_TABLE: Record<string, CostEntry> = {
+  // OpenAI models
+  'gpt-4o': { input: 0.0025, output: 0.01 },
+  'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
+  'gpt-4-turbo': { input: 0.01, output: 0.03 },
+  'gpt-4': { input: 0.03, output: 0.06 },
+  'gpt-3.5-turbo': { input: 0.0005, output: 0.0015 },
+  o1: { input: 0.015, output: 0.06 },
+  'o1-mini': { input: 0.003, output: 0.012 },
+  'o3-mini': { input: 0.0011, output: 0.0044 },
+  // Anthropic models
+  'claude-3-5-sonnet-20241022': { input: 0.003, output: 0.015 },
+  'claude-3-5-sonnet': { input: 0.003, output: 0.015 },
+  'claude-sonnet-4-20250514': { input: 0.003, output: 0.015 },
+  'claude-3-5-haiku-20241022': { input: 0.0008, output: 0.004 },
+  'claude-3-5-haiku': { input: 0.0008, output: 0.004 },
+  'claude-3-opus': { input: 0.015, output: 0.075 },
+  'claude-3-sonnet': { input: 0.003, output: 0.015 },
+  'claude-3-haiku': { input: 0.00025, output: 0.00125 },
+  // Google models
+  'gemini-1.5-pro': { input: 0.00125, output: 0.005 },
+  'gemini-1.5-flash': { input: 0.000075, output: 0.0003 },
+  'gemini-2.0-flash': { input: 0.0001, output: 0.0004 },
+};
+
+/**
+ * Calculates the cost in USD for a given token usage and model.
+ *
+ * @param usage - Token usage with prompt and completion tokens.
+ * @param modelId - Model identifier to look up in cost table.
+ * @param costTable - Optional custom cost table (merged with defaults).
+ * @returns Cost in USD, or 0 if model is not in cost table.
+ *
+ * @example
+ * ```ts
+ * const usage = { promptTokens: 1000, completionTokens: 500, totalTokens: 1500 };
+ *
+ * // Using default cost table
+ * const cost = calculateCost(usage, 'gpt-4o');
+ * // cost = (1000/1000 * 0.0025) + (500/1000 * 0.01) = 0.0025 + 0.005 = 0.0075
+ *
+ * // Using custom cost table
+ * const customCost = calculateCost(usage, 'custom-model', {
+ *   'custom-model': { input: 0.001, output: 0.002 }
+ * });
+ * ```
+ */
+export function calculateCost(
+  usage: TokenUsage,
+  modelId: string,
+  costTable?: Record<string, CostEntry>,
+): number {
+  const mergedTable = { ...DEFAULT_COST_TABLE, ...costTable };
+  const entry = mergedTable[modelId];
+
+  if (!entry) {
+    return 0;
+  }
+
+  const inputCost = (usage.promptTokens / 1000) * entry.input;
+  const outputCost = (usage.completionTokens / 1000) * entry.output;
+
+  return inputCost + outputCost;
+}
+
+/**
+ * Creates a budget checker function from configuration.
+ *
+ * @param config - Budget guard configuration with limits.
+ * @returns Function that checks if budget is exceeded for given usage.
+ *
+ * @example
+ * ```ts
+ * const checkBudget = createBudgetChecker({
+ *   maxTokens: 10_000,
+ *   maxCost: 1.00,
+ *   onBudgetExceeded: (usage, limit) => {
+ *     console.error(`Budget exceeded: ${limit.type}`);
+ *   }
+ * });
+ *
+ * const result = checkBudget(
+ *   { promptTokens: 5000, completionTokens: 6000, totalTokens: 11000 },
+ *   'gpt-4o'
+ * );
+ * // result.exceeded === true
+ * // result.limit === { type: 'tokens', limit: 10000, actual: 11000 }
+ * ```
+ */
+export function createBudgetChecker(
+  config: BudgetGuardConfig,
+): (usage: TokenUsage, modelId: string) => BudgetCheckResult {
+  return (usage: TokenUsage, modelId: string): BudgetCheckResult => {
+    // Check token limit first
+    if (config.maxTokens !== undefined && usage.totalTokens > config.maxTokens) {
+      const limit = {
+        type: 'tokens' as const,
+        limit: config.maxTokens,
+        actual: usage.totalTokens,
+      };
+
+      config.onBudgetExceeded?.(usage, limit);
+
+      return {
+        exceeded: true,
+        limit,
+      };
+    }
+
+    // Check cost limit
+    if (config.maxCost !== undefined) {
+      const cost = calculateCost(usage, modelId, config.costTable);
+
+      if (cost > config.maxCost) {
+        const limit = {
+          type: 'cost' as const,
+          limit: config.maxCost,
+          actual: cost,
+        };
+
+        config.onBudgetExceeded?.(usage, limit);
+
+        return {
+          exceeded: true,
+          limit,
+        };
+      }
+    }
+
+    return { exceeded: false };
+  };
+}
+
+/**
+ * Result type for AI SDK onFinish callback.
+ * Matches the shape expected by Vercel AI SDK v6.
+ */
+export interface OnFinishResult {
+  /** Token usage from the model response. */
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens?: number;
+  };
+}
+
+/**
+ * Creates an onFinish handler for AI SDK that checks budget limits.
+ *
+ * @param config - Budget guard configuration.
+ * @param modelId - Model identifier for cost calculation.
+ * @returns onFinish handler function for AI SDK.
+ *
+ * @example
+ * ```ts
+ * import { streamText } from 'ai';
+ *
+ * const result = await streamText({
+ *   model: myModel,
+ *   prompt: 'Hello',
+ *   onFinish: createBudgetGuardedOnFinish(
+ *     { maxTokens: 50_000, maxCost: 5.00 },
+ *     'gpt-4o'
+ *   )
+ * });
+ * ```
+ */
+export function createBudgetGuardedOnFinish(
+  config: BudgetGuardConfig,
+  modelId: string,
+): (result: OnFinishResult) => void {
+  const checkBudget = createBudgetChecker(config);
+
+  return (result: OnFinishResult): void => {
+    if (!result.usage) {
+      return;
+    }
+
+    const usage: TokenUsage = {
+      promptTokens: result.usage.promptTokens,
+      completionTokens: result.usage.completionTokens,
+      totalTokens:
+        result.usage.totalTokens ?? result.usage.promptTokens + result.usage.completionTokens,
+    };
+
+    // Check budget (callback will be invoked if exceeded)
+    checkBudget(usage, modelId);
+  };
+}
+
+/**
+ * Estimates cost for a request before execution.
+ * Useful for pre-flight budget checks.
+ *
+ * @param estimatedPromptTokens - Estimated number of prompt tokens.
+ * @param estimatedCompletionTokens - Estimated number of completion tokens.
+ * @param modelId - Model identifier for cost lookup.
+ * @param costTable - Optional custom cost table.
+ * @returns Estimated cost in USD.
+ *
+ * @example
+ * ```ts
+ * const estimatedCost = estimateCost(2000, 1000, 'gpt-4o');
+ * if (estimatedCost > budget) {
+ *   throw new Error('Estimated cost exceeds budget');
+ * }
+ * ```
+ */
+export function estimateCost(
+  estimatedPromptTokens: number,
+  estimatedCompletionTokens: number,
+  modelId: string,
+  costTable?: Record<string, CostEntry>,
+): number {
+  return calculateCost(
+    {
+      promptTokens: estimatedPromptTokens,
+      completionTokens: estimatedCompletionTokens,
+      totalTokens: estimatedPromptTokens + estimatedCompletionTokens,
+    },
+    modelId,
+    costTable,
+  );
+}

package/src/streaming/control/controller.ts

@@ -0,0 +1,255 @@
+/**
+ * @fileoverview Stream controller for fluent composition.
+ * @module @od-oneapp/ai-platform/streaming-control
+ *
+ * Provides a fluent API for composing streaming control configurations:
+ * - Budget guards for token and cost limits
+ * - Step limits for agent loop control
+ * - Stream smoothing for improved UX
+ *
+ * @example
+ * ```ts
+ * import { createStreamController } from '@od-oneapp/ai-platform/streaming-control';
+ *
+ * const controller = createStreamController()
+ *   .withBudgetGuard({
+ *     maxTokens: 100_000,
+ *     maxCost: 10.00,
+ *     onBudgetExceeded: (usage, limit) => {
+ *       console.error(`Budget exceeded: ${limit.type}`);
+ *     }
+ *   })
+ *   .withStepLimit({
+ *     maxSteps: 10,
+ *     strategy: 'stop',
+ *     onLimitReached: (count) => {
+ *       console.log(`Reached ${count} steps`);
+ *     }
+ *   })
+ *   .withSmoothStream({
+ *     delayInMs: 20,
+ *     chunking: 'word'
+ *   });
+ *
+ * const config = controller.getConfig();
+ * ```
+ */
+
+import { logWarn } from '@repo/shared/logs';
+
+import {
+  type BudgetGuardConfig,
+  type SmoothStreamConfig,
+  type StepLimitConfig,
+  type StreamController,
+  type StreamControllerConfig,
+} from './types';
+
+/**
+ * Internal implementation of StreamController.
+ * @internal
+ */
+class StreamControllerImpl implements StreamController {
+  private config: StreamControllerConfig;
+
+  constructor(initialConfig: StreamControllerConfig = {}) {
+    this.config = { ...initialConfig };
+  }
+
+  /**
+   * Adds budget guard configuration.
+   * Merges with existing budget guard config if present.
+   */
+  withBudgetGuard(budgetConfig: BudgetGuardConfig): StreamController {
+    return new StreamControllerImpl({
+      ...this.config,
+      budgetGuard: {
+        ...this.config.budgetGuard,
+        ...budgetConfig,
+        // Merge cost tables if both exist
+        costTable: {
+          ...this.config.budgetGuard?.costTable,
+          ...budgetConfig.costTable,
+        },
+      },
+    });
+  }
+
+  /**
+   * Adds step limit configuration.
+   * Replaces existing step limit config if present.
+   */
+  withStepLimit(stepConfig: StepLimitConfig): StreamController {
+    return new StreamControllerImpl({
+      ...this.config,
+      stepLimit: stepConfig,
+    });
+  }
+
+  /**
+   * Adds smooth stream configuration.
+   * Merges with existing smooth stream config if present.
+   */
+  withSmoothStream(smoothConfig: SmoothStreamConfig): StreamController {
+    return new StreamControllerImpl({
+      ...this.config,
+      smoothStream: {
+        ...this.config.smoothStream,
+        ...smoothConfig,
+      },
+    });
+  }
+
+  /**
+   * Gets the combined configuration.
+   */
+  getConfig(): StreamControllerConfig {
+    return { ...this.config };
+  }
+}
+
+/**
+ * Creates a new stream controller for fluent composition.
+ *
+ * @param initialConfig - Optional initial configuration.
+ * @returns StreamController instance for chaining.
+ *
+ * @remarks
+ * The stream controller provides a fluent API for building
+ * streaming control configurations. Each method returns a new
+ * controller instance, making the configuration immutable.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const controller = createStreamController()
+ *   .withBudgetGuard({ maxTokens: 50_000 })
+ *   .withStepLimit({ maxSteps: 5 });
+ *
+ * // With initial config
+ * const controller2 = createStreamController({
+ *   smoothStream: { delayInMs: 10 }
+ * }).withBudgetGuard({ maxCost: 5.00 });
+ *
+ * // Get final config
+ * const config = controller.getConfig();
+ * // config = {
+ * //   budgetGuard: { maxTokens: 50_000 },
+ * //   stepLimit: { maxSteps: 5 }
+ * // }
+ * ```
+ */
+export function createStreamController(initialConfig?: StreamControllerConfig): StreamController {
+  return new StreamControllerImpl(initialConfig);
+}
+
+/**
+ * Merges multiple stream controller configs into one.
+ *
+ * @param configs - Array of configs to merge.
+ * @returns Merged StreamControllerConfig.
+ *
+ * @example
+ * ```ts
+ * const budgetConfig = createStreamController()
+ *   .withBudgetGuard({ maxTokens: 100_000 })
+ *   .getConfig();
+ *
+ * const stepConfig = createStreamController()
+ *   .withStepLimit({ maxSteps: 10 })
+ *   .getConfig();
+ *
+ * const merged = mergeStreamConfigs([budgetConfig, stepConfig]);
+ * ```
+ */
+export function mergeStreamConfigs(configs: StreamControllerConfig[]): StreamControllerConfig {
+  let result = createStreamController();
+
+  for (const config of configs) {
+    if (config.budgetGuard) {
+      result = result.withBudgetGuard(config.budgetGuard);
+    }
+    if (config.stepLimit) {
+      result = result.withStepLimit(config.stepLimit);
+    }
+    if (config.smoothStream) {
+      result = result.withSmoothStream(config.smoothStream);
+    }
+  }
+
+  return result.getConfig();
+}
+
+/**
+ * Creates a preset configuration for development/testing.
+ * Higher limits and verbose callbacks.
+ *
+ * @returns StreamController with development presets.
+ *
+ * @example
+ * ```ts
+ * const devController = createDevStreamController();
+ * const config = devController.getConfig();
+ * ```
+ */
+export function createDevStreamController(): StreamController {
+  return createStreamController()
+    .withBudgetGuard({
+      maxTokens: 500_000,
+      maxCost: 50.0,
+      onBudgetExceeded: (usage, limit) => {
+        logWarn('[DEV] Budget exceeded', { usage, limit });
+      },
+    })
+    .withStepLimit({
+      maxSteps: 20,
+      strategy: 'warn',
+      onLimitReached: count => {
+        logWarn('[DEV] Step limit reached', { count });
+      },
+    })
+    .withSmoothStream({
+      delayInMs: 5,
+      chunking: 'word',
+    });
+}
+
+/**
+ * Creates a preset configuration for production.
+ * Conservative limits and minimal overhead.
+ *
+ * @param options - Production configuration options.
+ * @returns StreamController with production presets.
+ *
+ * @example
+ * ```ts
+ * const prodController = createProdStreamController({
+ *   maxTokens: 100_000,
+ *   maxCost: 10.00,
+ *   maxSteps: 10
+ * });
+ * ```
+ */
+export function createProdStreamController(options?: {
+  maxTokens?: number;
+  maxCost?: number;
+  maxSteps?: number;
+  onBudgetExceeded?: BudgetGuardConfig['onBudgetExceeded'];
+  onStepLimitReached?: StepLimitConfig['onLimitReached'];
+}): StreamController {
+  return createStreamController()
+    .withBudgetGuard({
+      maxTokens: options?.maxTokens ?? 100_000,
+      maxCost: options?.maxCost ?? 10.0,
+      onBudgetExceeded: options?.onBudgetExceeded,
+    })
+    .withStepLimit({
+      maxSteps: options?.maxSteps ?? 10,
+      strategy: 'stop',
+      onLimitReached: options?.onStepLimitReached,
+    })
+    .withSmoothStream({
+      delayInMs: 10,
+      chunking: 'word',
+    });
+}

package/src/streaming/control/index.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Streaming control module for composable streaming patterns.
+ * @module @od-oneapp/ai-platform/streaming-control
+ *
+ * Provides composable patterns for controlling AI streaming:
+ * - Budget guards for token and cost limits
+ * - Step limits for agent loop control
+ * - Stream smoothing for improved UX
+ * - Fluent controller API for configuration composition
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createStreamController,
+ *   createBudgetChecker,
+ *   createStepCounter,
+ *   createSmoothStreamTransform,
+ *   calculateCost,
+ *   DEFAULT_COST_TABLE
+ * } from '@od-oneapp/ai-platform/streaming-control';
+ *
+ * // Fluent composition
+ * const controller = createStreamController()
+ *   .withBudgetGuard({
+ *     maxTokens: 100_000,
+ *     maxCost: 10.00,
+ *     onBudgetExceeded: (usage, limit) => {
+ *       console.error(`Budget exceeded: ${limit.type}`);
+ *     }
+ *   })
+ *   .withStepLimit({
+ *     maxSteps: 10,
+ *     strategy: 'stop',
+ *     onLimitReached: (count) => {
+ *       console.log(`Reached ${count} steps`);
+ *     }
+ *   })
+ *   .withSmoothStream({
+ *     delayInMs: 20,
+ *     chunking: 'word'
+ *   });
+ *
+ * const config = controller.getConfig();
+ *
+ * // Individual utilities
+ * const cost = calculateCost(
+ *   { promptTokens: 1000, completionTokens: 500, totalTokens: 1500 },
+ *   'gpt-4o'
+ * );
+ *
+ * const stepCounter = createStepCounter({ maxSteps: 5, strategy: 'stop' });
+ * stepCounter.increment();
+ *
+ * const smoothTransform = createSmoothStreamTransform({ delayInMs: 20 });
+ * ```
+ */
+
+// Types
+export {
+  type TokenUsage,
+  type BudgetLimit,
+  type CostEntry,
+  type BudgetGuardConfig,
+  type StepLimitConfig,
+  type SmoothStreamConfig,
+  type StreamController,
+  type StreamControllerConfig,
+  type BudgetCheckResult,
+  type StepCounter,
+  type SmoothStreamTransform,
+} from './types';
+
+// Budget guard
+export {
+  DEFAULT_COST_TABLE,
+  calculateCost,
+  createBudgetChecker,
+  createBudgetGuardedOnFinish,
+  estimateCost,
+  type OnFinishResult,
+} from './budget-guard';
+
+// Step limit
+export {
+  createStepCounter,
+  createStepLimitCondition,
+  withStepLimit,
+  StepLimitExceededError,
+} from './step-limit';
+
+// Smoothing
+export {
+  createSmoothStreamTransform,
+  splitIntoChunks,
+  smoothTextGenerator,
+  withSmoothStream,
+} from './smoothing';
+
+// Controller
+export {
+  createStreamController,
+  mergeStreamConfigs,
+  createDevStreamController,
+  createProdStreamController,
+} from './controller';