@od-oneapp/ai-platform 0.1.0

package/src/streaming/control/smoothing.ts

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview Stream smoothing utilities for improved UX.
+ * @module @od-oneapp/ai-platform/streaming-control
+ *
+ * Provides utilities for smoothing streaming responses:
+ * - Transform configuration for AI SDK's smoothStream option
+ * - Chunking strategies (word, line, sentence)
+ * - Configurable delay between chunks
+ *
+ * @example
+ * ```ts
+ * import { createSmoothStreamTransform } from '@od-oneapp/ai-platform/streaming-control';
+ * import { streamText, smoothStream } from 'ai';
+ *
+ * const transform = createSmoothStreamTransform({
+ *   delayInMs: 20,
+ *   chunking: 'word'
+ * });
+ *
+ * const result = await streamText({
+ *   model: myModel,
+ *   prompt: 'Hello',
+ *   experimental_transform: smoothStream(transform)
+ * });
+ * ```
+ */
+
+import { type SmoothStreamConfig, type SmoothStreamTransform } from './types';
+
+/** Default delay in milliseconds between chunks. */
+const DEFAULT_DELAY_MS = 10;
+
+/** Default chunking strategy. */
+const DEFAULT_CHUNKING = 'word' as const;
+
+/**
+ * Creates a smooth stream transform configuration for AI SDK.
+ *
+ * @param config - Optional smooth stream configuration.
+ * @returns Transform configuration compatible with AI SDK's smoothStream.
+ *
+ * @remarks
+ * Stream smoothing helps create a more natural reading experience by:
+ * - Adding small delays between chunks to simulate typing
+ * - Chunking text at natural boundaries (words, lines, sentences)
+ * - Preventing overwhelming the UI with rapid updates
+ *
+ * Chunking strategies:
+ * - 'word': Emit at word boundaries (recommended for most cases)
+ * - 'line': Emit at line breaks
+ * - 'sentence': Emit at sentence boundaries
+ *
+ * @example
+ * ```ts
+ * // Default configuration (10ms delay, word chunking)
+ * const defaultTransform = createSmoothStreamTransform();
+ *
+ * // Custom configuration
+ * const customTransform = createSmoothStreamTransform({
+ *   delayInMs: 30,
+ *   chunking: 'sentence'
+ * });
+ * ```
+ */
+export function createSmoothStreamTransform(config?: SmoothStreamConfig): SmoothStreamTransform {
+  const chunking: 'word' | 'line' | 'sentence' = config?.chunking ?? DEFAULT_CHUNKING;
+  return {
+    delayInMs: config?.delayInMs ?? DEFAULT_DELAY_MS,
+    chunking,
+  };
+}
+
+/**
+ * Regex patterns for different chunking strategies.
+ * Used to split text into chunks at natural boundaries.
+ * @internal
+ */
+const CHUNKING_PATTERNS: Record<NonNullable<SmoothStreamConfig['chunking']>, RegExp> = {
+  word: /\s+/,
+  line: /\n/,
+  sentence: /(?<=[.!?])\s+/,
+};
+
+/**
+ * Splits text into chunks based on the configured strategy.
+ *
+ * @param text - Text to split into chunks.
+ * @param chunking - Chunking strategy to use.
+ * @param minChunkSize - Minimum chunk size before emitting.
+ * @returns Array of text chunks.
+ *
+ * @example
+ * ```ts
+ * const chunks = splitIntoChunks('Hello world. How are you?', 'sentence');
+ * // chunks = ['Hello world. ', 'How are you?']
+ * ```
+ */
+export function splitIntoChunks(
+  text: string,
+  chunking: NonNullable<SmoothStreamConfig['chunking']> = 'word',
+  minChunkSize = 1,
+): string[] {
+  const pattern = CHUNKING_PATTERNS[chunking];
+  const parts = text.split(pattern);
+
+  if (minChunkSize <= 1) {
+    return parts.filter(Boolean);
+  }
+
+  // Combine small chunks to meet minimum size
+  const chunks: string[] = [];
+  let buffer = '';
+
+  for (const part of parts) {
+    buffer += part;
+
+    if (buffer.length >= minChunkSize) {
+      chunks.push(buffer);
+      buffer = '';
+    } else {
+      // Add back the delimiter for non-word chunking
+      if (chunking !== 'word') {
+        buffer += chunking === 'line' ? '\n' : ' ';
+      } else {
+        buffer += ' ';
+      }
+    }
+  }
+
+  // Push any remaining buffer
+  if (buffer.trim()) {
+    chunks.push(buffer.trim());
+  }
+
+  return chunks;
+}
+
+/**
+ * Creates an async generator that yields text chunks with delays.
+ *
+ * @param text - Text to stream.
+ * @param config - Smooth stream configuration.
+ * @yields Text chunks with configured delays.
+ *
+ * @example
+ * ```ts
+ * for await (const chunk of smoothTextGenerator('Hello world!', { delayInMs: 50 })) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+export async function* smoothTextGenerator(
+  text: string,
+  config?: SmoothStreamConfig,
+): AsyncGenerator<string> {
+  const delay = config?.delayInMs ?? DEFAULT_DELAY_MS;
+  const chunking = config?.chunking ?? DEFAULT_CHUNKING;
+  const minChunkSize = config?.minChunkSize ?? 1;
+
+  const chunks = splitIntoChunks(text, chunking, minChunkSize);
+
+  for (const chunk of chunks) {
+    yield chunk;
+
+    if (delay > 0) {
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
+
+/**
+ * Wraps an async iterable to add smooth streaming delays.
+ *
+ * @param source - Source async iterable of text chunks.
+ * @param config - Smooth stream configuration.
+ * @yields Text chunks with configured delays.
+ *
+ * @example
+ * ```ts
+ * const source = getStreamFromModel();
+ * const smoothed = withSmoothStream(source, { delayInMs: 20 });
+ *
+ * for await (const chunk of smoothed) {
+ *   // Chunks arrive with smooth delays
+ * }
+ * ```
+ */
+export async function* withSmoothStream(
+  source: AsyncIterable<string>,
+  config?: SmoothStreamConfig,
+): AsyncGenerator<string> {
+  const delay = config?.delayInMs ?? DEFAULT_DELAY_MS;
+
+  for await (const chunk of source) {
+    yield chunk;
+
+    if (delay > 0) {
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}

package/src/streaming/control/step-limit.ts

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Step limit utilities for agent loop control.
+ * @module @od-oneapp/ai-platform/streaming-control
+ *
+ * Provides functions for controlling agent execution steps:
+ * - Step counter with configurable strategies
+ * - Stop condition generators for AI SDK integration
+ *
+ * @example
+ * ```ts
+ * import { createStepCounter, createStepLimitCondition } from '@od-oneapp/ai-platform/streaming-control';
+ *
+ * const counter = createStepCounter({
+ *   maxSteps: 10,
+ *   strategy: 'stop',
+ *   onLimitReached: (count) => console.log(`Reached ${count} steps`)
+ * });
+ *
+ * counter.increment();
+ * if (counter.shouldStop()) {
+ *   // Stop agent execution
+ * }
+ * ```
+ */
+
+import { type StepCounter, type StepLimitConfig } from './types';
+
+/**
+ * Creates a step counter for tracking agent execution steps.
+ *
+ * @param config - Step limit configuration.
+ * @returns StepCounter instance for tracking and controlling steps.
+ *
+ * @remarks
+ * The step counter tracks how many steps an agent has executed and
+ * provides methods to check whether execution should stop or warn.
+ *
+ * Strategies:
+ * - 'stop': shouldStop() returns true when limit is reached
+ * - 'warn': shouldWarn() returns true, shouldStop() returns false
+ * - 'continue': Both return false (only onLimitReached is called)
+ *
+ * @example
+ * ```ts
+ * const counter = createStepCounter({
+ *   maxSteps: 5,
+ *   strategy: 'warn',
+ *   onLimitReached: (count) => {
+ *     sendTelemetry({ event: 'step_limit_reached', count });
+ *   }
+ * });
+ *
+ * // In agent loop
+ * while (hasMoreWork) {
+ *   counter.increment();
+ *
+ *   if (counter.shouldWarn()) {
+ *     console.warn('Step limit approaching');
+ *   }
+ *
+ *   if (counter.shouldStop()) {
+ *     break;
+ *   }
+ *
+ *   await executeStep();
+ * }
+ * ```
+ */
+export function createStepCounter(config: StepLimitConfig): StepCounter {
+  let count = 0;
+  const { maxSteps, onLimitReached, strategy = 'stop' } = config;
+  let limitReachedCalled = false;
+
+  return {
+    /**
+     * Increments the step counter.
+     * Calls onLimitReached when limit is first reached.
+     * @returns The new step count.
+     */
+    increment(): number {
+      count += 1;
+
+      if (count >= maxSteps && !limitReachedCalled) {
+        limitReachedCalled = true;
+        onLimitReached?.(count);
+      }
+
+      return count;
+    },
+
+    /**
+     * Gets the current step count.
+     * @returns Current number of steps executed.
+     */
+    getCount(): number {
+      return count;
+    },
+
+    /**
+     * Checks if agent should stop based on strategy.
+     * @returns true if strategy is 'stop' and limit is reached.
+     */
+    shouldStop(): boolean {
+      if (strategy !== 'stop') {
+        return false;
+      }
+      return count >= maxSteps;
+    },
+
+    /**
+     * Checks if a warning should be emitted.
+     * @returns true if strategy is 'warn' and limit is reached.
+     */
+    shouldWarn(): boolean {
+      if (strategy !== 'warn') {
+        return false;
+      }
+      return count >= maxSteps;
+    },
+
+    /**
+     * Resets the counter to zero.
+     */
+    reset(): void {
+      count = 0;
+      limitReachedCalled = false;
+    },
+  };
+}
+
+/**
+ * Creates a stopWhen condition function for AI SDK.
+ * Returns true when the step count reaches the limit.
+ *
+ * @param maxSteps - Maximum number of steps before stopping.
+ * @returns Function that takes step count and returns whether to stop.
+ *
+ * @remarks
+ * This function returns a predicate that can be used with AI SDK's
+ * stopWhen configuration to automatically stop agent loops.
+ *
+ * @example
+ * ```ts
+ * import { generateText } from 'ai';
+ *
+ * const result = await generateText({
+ *   model: myModel,
+ *   prompt: 'Complete this task',
+ *   maxSteps: 10,
+ *   stopWhen: createStepLimitCondition(10)
+ * });
+ * ```
+ */
+export function createStepLimitCondition(maxSteps: number): (state: { steps: number }) => boolean {
+  return (state: { steps: number }): boolean => {
+    return state.steps >= maxSteps;
+  };
+}
+
+/**
+ * Creates a step limiter that wraps an async function with step counting.
+ *
+ * @param config - Step limit configuration.
+ * @param fn - Async function to wrap with step limiting.
+ * @returns Wrapped function that increments counter before each call.
+ *
+ * @example
+ * ```ts
+ * const executeStep = async () => {
+ *   // ... perform step logic
+ * };
+ *
+ * const limitedExecuteStep = withStepLimit(
+ *   { maxSteps: 5, strategy: 'stop' },
+ *   executeStep
+ * );
+ *
+ * // Will throw after 5 calls when strategy is 'stop'
+ * await limitedExecuteStep();
+ * ```
+ */
+export function withStepLimit<TArgs extends unknown[], TResult>(
+  config: StepLimitConfig,
+  fn: (...args: TArgs) => Promise<TResult>,
+): (...args: TArgs) => Promise<TResult> {
+  const counter = createStepCounter(config);
+
+  return async (...args: TArgs): Promise<TResult> => {
+    // Check if we've already reached the limit before executing
+    if (counter.shouldStop()) {
+      throw new StepLimitExceededError(counter.getCount(), config.maxSteps);
+    }
+
+    counter.increment();
+
+    return fn(...args);
+  };
+}
+
+/**
+ * Error thrown when step limit is exceeded with 'stop' strategy.
+ */
+export class StepLimitExceededError extends Error {
+  /** Current step count when error was thrown. */
+  readonly stepCount: number;
+  /** Maximum steps that were configured. */
+  readonly maxSteps: number;
+
+  constructor(stepCount: number, maxSteps: number) {
+    super(`Step limit exceeded: ${stepCount}/${maxSteps} steps`);
+    this.name = 'StepLimitExceededError';
+    this.stepCount = stepCount;
+    this.maxSteps = maxSteps;
+  }
+}

package/src/streaming/control/types.ts

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Streaming control types and configurations.
+ * @module @od-oneapp/ai-platform/streaming-control
+ *
+ * Provides type definitions for composable streaming control patterns:
+ * - Budget guards for token and cost limits
+ * - Step limits for agent loop control
+ * - Stream smoothing for improved UX
+ *
+ * @example
+ * ```ts
+ * import type { BudgetGuardConfig, StepLimitConfig, SmoothStreamConfig } from '@od-oneapp/ai-platform/streaming-control';
+ *
+ * const budgetConfig: BudgetGuardConfig = {
+ *   maxTokens: 100_000,
+ *   maxCost: 10.00,
+ *   onBudgetExceeded: (usage, limit) => {
+ *     console.log(`Budget exceeded: ${limit.type} limit of ${limit.limit}`);
+ *   }
+ * };
+ * ```
+ */
+
+/**
+ * Token usage tracking for budget calculations.
+ * Tracks prompt tokens, completion tokens, and total usage.
+ */
+export interface TokenUsage {
+  /** Number of tokens in the prompt/input. */
+  readonly promptTokens: number;
+  /** Number of tokens in the completion/output. */
+  readonly completionTokens: number;
+  /** Total tokens used (prompt + completion). */
+  readonly totalTokens: number;
+}
+
+/**
+ * Budget limit that was exceeded.
+ * Provides details about which limit was exceeded and by how much.
+ */
+export interface BudgetLimit {
+  /** Type of limit that was exceeded ('tokens' or 'cost'). */
+  readonly type: 'tokens' | 'cost';
+  /** The configured limit value. */
+  readonly limit: number;
+  /** The actual value that exceeded the limit. */
+  readonly actual: number;
+}
+
+/**
+ * Cost entry per 1K tokens by model.
+ * Defines pricing for input and output tokens.
+ *
+ * @example
+ * ```ts
+ * const gpt4oCost: CostEntry = {
+ *   input: 0.0025,  // $0.0025 per 1K input tokens
+ *   output: 0.01    // $0.01 per 1K output tokens
+ * };
+ * ```
+ */
+export interface CostEntry {
+  /** Cost per 1K input tokens in USD. */
+  readonly input: number;
+  /** Cost per 1K output tokens in USD. */
+  readonly output: number;
+}
+
+/**
+ * Budget guard configuration for controlling token and cost limits.
+ * Allows setting maximum tokens, maximum cost, and custom callbacks.
+ *
+ * @example
+ * ```ts
+ * const config: BudgetGuardConfig = {
+ *   maxTokens: 50_000,
+ *   maxCost: 5.00,
+ *   costTable: {
+ *     'custom-model': { input: 0.001, output: 0.002 }
+ *   },
+ *   onBudgetExceeded: (usage, limit) => {
+ *     logTelemetry({ event: 'budget_exceeded', ...limit });
+ *   }
+ * };
+ * ```
+ */
+export interface BudgetGuardConfig {
+  /** Maximum total tokens allowed (prompt + completion). */
+  readonly maxTokens?: number;
+  /** Maximum cost allowed in USD. */
+  readonly maxCost?: number;
+  /** Custom cost table for additional or custom models. */
+  readonly costTable?: Record<string, CostEntry>;
+  /** Callback invoked when budget is exceeded. */
+  readonly onBudgetExceeded?: (usage: TokenUsage, limit: BudgetLimit) => void;
+}
+
+/**
+ * Step limit configuration for agent loop control.
+ * Controls how many steps an agent can execute before stopping.
+ *
+ * @example
+ * ```ts
+ * const config: StepLimitConfig = {
+ *   maxSteps: 10,
+ *   strategy: 'warn',
+ *   onLimitReached: (stepCount) => {
+ *     console.warn(`Agent reached ${stepCount} steps`);
+ *   }
+ * };
+ * ```
+ */
+export interface StepLimitConfig {
+  /** Maximum number of steps allowed. */
+  readonly maxSteps: number;
+  /** Callback invoked when limit is reached. */
+  readonly onLimitReached?: (stepCount: number) => void;
+  /** Strategy when limit is reached: 'stop', 'warn', or 'continue'. */
+  readonly strategy?: 'stop' | 'warn' | 'continue';
+}
+
+/**
+ * Smooth stream configuration for improved UX.
+ * Controls delay and chunking behavior for streaming responses.
+ *
+ * @example
+ * ```ts
+ * const config: SmoothStreamConfig = {
+ *   delayInMs: 20,
+ *   chunking: 'word',
+ *   minChunkSize: 3
+ * };
+ * ```
+ */
+export interface SmoothStreamConfig {
+  /** Delay in milliseconds between chunks. */
+  readonly delayInMs?: number;
+  /** Chunking strategy: 'word', 'line', or 'sentence'. */
+  readonly chunking?: 'word' | 'line' | 'sentence';
+  /** Minimum chunk size before emitting. */
+  readonly minChunkSize?: number;
+}
+
+/**
+ * Combined stream controller configuration.
+ * Aggregates all streaming control configurations.
+ */
+export interface StreamControllerConfig {
+  /** Budget guard configuration. */
+  readonly budgetGuard?: BudgetGuardConfig;
+  /** Step limit configuration. */
+  readonly stepLimit?: StepLimitConfig;
+  /** Smooth stream configuration. */
+  readonly smoothStream?: SmoothStreamConfig;
+}
+
+/**
+ * Stream controller interface for fluent composition.
+ * Allows chaining multiple streaming control configurations.
+ *
+ * @example
+ * ```ts
+ * const controller = createStreamController()
+ *   .withBudgetGuard({ maxTokens: 100_000 })
+ *   .withStepLimit({ maxSteps: 10 })
+ *   .withSmoothStream({ delayInMs: 20 });
+ *
+ * const config = controller.getConfig();
+ * ```
+ */
+export interface StreamController {
+  /**
+   * Adds budget guard configuration.
+   * @param config - Budget guard configuration.
+   * @returns StreamController for chaining.
+   */
+  withBudgetGuard(config: BudgetGuardConfig): StreamController;
+
+  /**
+   * Adds step limit configuration.
+   * @param config - Step limit configuration.
+   * @returns StreamController for chaining.
+   */
+  withStepLimit(config: StepLimitConfig): StreamController;
+
+  /**
+   * Adds smooth stream configuration.
+   * @param config - Smooth stream configuration.
+   * @returns StreamController for chaining.
+   */
+  withSmoothStream(config: SmoothStreamConfig): StreamController;
+
+  /**
+   * Gets the combined configuration.
+   * @returns Combined StreamControllerConfig.
+   */
+  getConfig(): StreamControllerConfig;
+}
+
+/**
+ * Budget check result indicating whether budget is exceeded.
+ */
+export interface BudgetCheckResult {
+  /** Whether the budget was exceeded. */
+  readonly exceeded: boolean;
+  /** The limit that was exceeded, if any. */
+  readonly limit?: BudgetLimit;
+}
+
+/**
+ * Step counter interface for tracking agent steps.
+ */
+export interface StepCounter {
+  /** Increments the step counter. */
+  increment(): number;
+  /** Gets the current step count. */
+  getCount(): number;
+  /** Checks if the agent should stop based on strategy. */
+  shouldStop(): boolean;
+  /** Checks if a warning should be emitted. */
+  shouldWarn(): boolean;
+  /** Resets the counter to zero. */
+  reset(): void;
+}
+
+/**
+ * Smooth stream transform configuration for AI SDK.
+ */
+export interface SmoothStreamTransform {
+  /** Delay in milliseconds between chunks. */
+  readonly delayInMs: number;
+  /** Chunking strategy for the transform. */
+  readonly chunking: 'word' | 'line' | 'sentence';
+}