@od-oneapp/ai-platform 0.1.0

package/src/streaming/infra/types.ts

@@ -0,0 +1,118 @@
+/**
+ * Streaming infrastructure types
+ */
+
+/**
+ * Stream chunk types
+ */
+export type StreamChunkType =
+  | 'text-delta'
+  | 'tool-call-delta'
+  | 'tool-result'
+  | 'finish'
+  | 'error'
+  | 'metadata';
+
+/**
+ * Base stream chunk
+ */
+export interface StreamChunk<T = unknown> {
+  /** Chunk type */
+  type: StreamChunkType;
+  /** Chunk payload */
+  payload: T;
+  /** Chunk timestamp */
+  timestamp: Date;
+  /** Sequence number */
+  sequence: number;
+}
+
+/**
+ * Text delta chunk
+ */
+export interface TextDeltaChunk extends StreamChunk<{ text: string }> {
+  type: 'text-delta';
+}
+
+/**
+ * Tool call delta chunk
+ */
+export interface ToolCallDeltaChunk extends StreamChunk<{
+  toolCallId: string;
+  toolName: string;
+  argsTextDelta: string;
+}> {
+  type: 'tool-call-delta';
+}
+
+/**
+ * Finish chunk
+ */
+export interface FinishChunk extends StreamChunk<{
+  finishReason: 'stop' | 'length' | 'tool-calls' | 'error' | 'unknown';
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}> {
+  type: 'finish';
+}
+
+/**
+ * Stream transform function
+ */
+export type StreamTransform<TIn, TOut> = (
+  chunk: TIn,
+) => TOut | TOut[] | null | Promise<TOut | TOut[] | null>;
+
+/**
+ * Stream pipeline configuration
+ */
+export interface StreamPipelineConfig {
+  /** Buffer size for backpressure */
+  bufferSize?: number;
+  /** Timeout for stream operations (ms) */
+  timeout?: number;
+  /** Error handling strategy */
+  onError?: 'throw' | 'skip' | 'terminate';
+}
+
+/**
+ * Stream metrics
+ */
+export interface StreamMetrics {
+  /** Total chunks processed */
+  chunksProcessed: number;
+  /** Total bytes transferred */
+  bytesTransferred: number;
+  /** Start time */
+  startTime: Date;
+  /** End time */
+  endTime?: Date;
+  /** Time to first chunk (ms) */
+  timeToFirstChunk?: number;
+  /** Average chunk latency (ms) */
+  avgChunkLatency?: number;
+}
+
+/**
+ * Stream state
+ */
+export type StreamState = 'idle' | 'streaming' | 'paused' | 'completed' | 'error';
+
+/**
+ * Stream controller for managing stream lifecycle
+ */
+export interface StreamController {
+  /** Current stream state */
+  state: StreamState;
+  /** Pause the stream */
+  pause(): void;
+  /** Resume the stream */
+  resume(): void;
+  /** Abort the stream */
+  abort(reason?: string): void;
+  /** Get stream metrics */
+  getMetrics(): StreamMetrics;
+}

package/src/streaming/infra-extra/types.ts

@@ -0,0 +1,118 @@
+/**
+ * Streaming infrastructure types
+ */
+
+/**
+ * Stream chunk types
+ */
+export type StreamChunkType =
+  | 'text-delta'
+  | 'tool-call-delta'
+  | 'tool-result'
+  | 'finish'
+  | 'error'
+  | 'metadata';
+
+/**
+ * Base stream chunk
+ */
+export interface StreamChunk<T = unknown> {
+  /** Chunk type */
+  type: StreamChunkType;
+  /** Chunk payload */
+  payload: T;
+  /** Chunk timestamp */
+  timestamp: Date;
+  /** Sequence number */
+  sequence: number;
+}
+
+/**
+ * Text delta chunk
+ */
+export interface TextDeltaChunk extends StreamChunk<{ text: string }> {
+  type: 'text-delta';
+}
+
+/**
+ * Tool call delta chunk
+ */
+export interface ToolCallDeltaChunk extends StreamChunk<{
+  toolCallId: string;
+  toolName: string;
+  argsTextDelta: string;
+}> {
+  type: 'tool-call-delta';
+}
+
+/**
+ * Finish chunk
+ */
+export interface FinishChunk extends StreamChunk<{
+  finishReason: 'stop' | 'length' | 'tool-calls' | 'error' | 'unknown';
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}> {
+  type: 'finish';
+}
+
+/**
+ * Stream transform function
+ */
+export type StreamTransform<TIn, TOut> = (
+  chunk: TIn,
+) => TOut | TOut[] | null | Promise<TOut | TOut[] | null>;
+
+/**
+ * Stream pipeline configuration
+ */
+export interface StreamPipelineConfig {
+  /** Buffer size for backpressure */
+  bufferSize?: number;
+  /** Timeout for stream operations (ms) */
+  timeout?: number;
+  /** Error handling strategy */
+  onError?: 'throw' | 'skip' | 'terminate';
+}
+
+/**
+ * Stream metrics
+ */
+export interface StreamMetrics {
+  /** Total chunks processed */
+  chunksProcessed: number;
+  /** Total bytes transferred */
+  bytesTransferred: number;
+  /** Start time */
+  startTime: Date;
+  /** End time */
+  endTime?: Date;
+  /** Time to first chunk (ms) */
+  timeToFirstChunk?: number;
+  /** Average chunk latency (ms) */
+  avgChunkLatency?: number;
+}
+
+/**
+ * Stream state
+ */
+export type StreamState = 'idle' | 'streaming' | 'paused' | 'completed' | 'error';
+
+/**
+ * Stream controller for managing stream lifecycle
+ */
+export interface StreamController {
+  /** Current stream state */
+  state: StreamState;
+  /** Pause the stream */
+  pause(): void;
+  /** Resume the stream */
+  resume(): void;
+  /** Abort the stream */
+  abort(reason?: string): void;
+  /** Get stream metrics */
+  getMetrics(): StreamMetrics;
+}

package/src/tools/advanced/caching.ts

@@ -0,0 +1,299 @@
+/**
+ * @fileoverview Tool result caching patterns.
+ * @module @od-oneapp/ai-platform/tools/advanced
+ */
+
+import type { ToolHandler, ToolExecutionContext } from '../core/factory';
+
+/**
+ * Cache entry with TTL.
+ */
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+  hits: number;
+}
+
+/**
+ * In-memory cache for tool results.
+ */
+export class ToolCache<T = unknown> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private maxSize: number;
+  private defaultTTL: number;
+
+  constructor(options: { maxSize?: number; defaultTTL?: number } = {}) {
+    this.maxSize = options.maxSize ?? 1000;
+    this.defaultTTL = options.defaultTTL ?? 60000; // 1 minute default
+  }
+
+  /**
+   * Gets a value from cache.
+   */
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    entry.hits++;
+    return entry.value;
+  }
+
+  /**
+   * Sets a value in cache.
+   */
+  set(key: string, value: T, ttl?: number): void {
+    // Evict if at capacity
+    if (this.cache.size >= this.maxSize) {
+      this.evictLeastUsed();
+    }
+
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + (ttl ?? this.defaultTTL),
+      hits: 0,
+    });
+  }
+
+  /**
+   * Removes expired entries.
+   */
+  prune(): number {
+    const now = Date.now();
+    let pruned = 0;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+        pruned++;
+      }
+    }
+
+    return pruned;
+  }
+
+  /**
+   * Clears the entire cache.
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Gets cache statistics.
+   */
+  stats(): { size: number; maxSize: number; totalHits: number } {
+    let totalHits = 0;
+    for (const entry of this.cache.values()) {
+      totalHits += entry.hits;
+    }
+    return { size: this.cache.size, maxSize: this.maxSize, totalHits };
+  }
+
+  private evictLeastUsed(): void {
+    let minHits = Infinity;
+    let minKey: string | undefined;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.hits < minHits) {
+        minHits = entry.hits;
+        minKey = key;
+      }
+    }
+
+    if (minKey) {
+      this.cache.delete(minKey);
+    }
+  }
+}
+
+/**
+ * Options for cached tool wrapper.
+ */
+export interface CacheOptions<TInput, TOutput> {
+  /** Cache instance to use */
+  cache?: ToolCache<TOutput>;
+  /** TTL in milliseconds */
+  ttl?: number;
+  /** Function to generate cache key from input */
+  keyGenerator?: (input: TInput, context: ToolExecutionContext) => string;
+  /** Whether to cache errors */
+  cacheErrors?: boolean;
+  /** Skip cache for certain inputs */
+  skipCache?: (input: TInput, context: ToolExecutionContext) => boolean;
+}
+
+/**
+ * Wraps a tool handler with caching.
+ *
+ * @param handler - Original handler
+ * @param options - Cache options
+ * @returns Cached handler
+ *
+ * @example
+ * ```ts
+ * const cache = new ToolCache<SearchResult>({ ttl: 300000 });
+ *
+ * const cachedSearch = withCaching(
+ *   async ({ query }) => searchDocs(query),
+ *   { cache, keyGenerator: ({ query }) => `search:${query}` }
+ * );
+ * ```
+ */
+export function withCaching<TInput, TOutput>(
+  handler: ToolHandler<TInput, TOutput>,
+  options: CacheOptions<TInput, TOutput> = {},
+): ToolHandler<TInput, TOutput> {
+  const cache = options.cache ?? new ToolCache<TOutput>();
+  const keyGen = options.keyGenerator ?? defaultKeyGenerator;
+
+  return async (input, context) => {
+    // Check if should skip cache
+    if (options.skipCache?.(input, context)) {
+      return handler(input, context);
+    }
+
+    const key = keyGen(input, context);
+
+    // Check cache
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    // Execute and cache
+    try {
+      const result = await handler(input, context);
+      cache.set(key, result, options.ttl);
+      return result;
+    } catch (error) {
+      if (options.cacheErrors) {
+        // Cache the error result if configured
+        const errorResult = { error: String(error) } as TOutput;
+        cache.set(key, errorResult, options.ttl);
+        return errorResult;
+      }
+      throw error;
+    }
+  };
+}
+
+/**
+ * Default key generator using JSON.stringify.
+ */
+function defaultKeyGenerator<T>(input: T, context: ToolExecutionContext): string {
+  return JSON.stringify({ input, userId: context.userId });
+}
+
+/**
+ * Creates a cache key builder with prefixing.
+ *
+ * @param prefix - Cache key prefix
+ * @returns Key generator function
+ *
+ * @example
+ * ```ts
+ * const keyGen = createKeyBuilder('search');
+ * keyGen({ query: 'test' }, ctx); // => 'search:{"query":"test"}'
+ * ```
+ */
+export function createKeyBuilder(prefix: string) {
+  return function <T>(input: T, context: ToolExecutionContext): string {
+    return `${prefix}:${JSON.stringify({ input, userId: context.userId })}`;
+  };
+}
+
+/**
+ * Creates a selective key generator that only uses specified fields.
+ *
+ * @param prefix - Cache key prefix
+ * @param fields - Fields to include in key
+ * @returns Key generator function
+ *
+ * @example
+ * ```ts
+ * const keyGen = createSelectiveKeyBuilder('search', ['query', 'limit']);
+ * keyGen({ query: 'test', limit: 10, page: 1 }, ctx); // => 'search:test:10'
+ * ```
+ */
+export function createSelectiveKeyBuilder<T extends Record<string, unknown>>(
+  prefix: string,
+  fields: (keyof T)[],
+) {
+  return function (input: T, context: ToolExecutionContext): string {
+    void context;
+    const values = fields.map(f => String(input[f] ?? ''));
+    return `${prefix}:${values.join(':')}`;
+  };
+}
+
+/**
+ * SWR cache entry type.
+ */
+interface SWRCacheEntry<T> {
+  value: T;
+  fetchedAt: number;
+}
+
+/**
+ * Creates a stale-while-revalidate cache wrapper.
+ *
+ * @param handler - Original handler
+ * @param options - SWR options
+ * @returns Handler with SWR caching
+ *
+ * @example
+ * ```ts
+ * const swrSearch = withSWRCaching(searchHandler, {
+ *   staleTTL: 60000,    // 1 minute stale
+ *   maxTTL: 300000,     // 5 minute max
+ * });
+ * ```
+ */
+export function withSWRCaching<TInput, TOutput>(
+  handler: ToolHandler<TInput, TOutput>,
+  options: Omit<CacheOptions<TInput, TOutput>, 'cache'> & {
+    /** Time before entry is considered stale (but still usable) */
+    staleTTL: number;
+    /** Maximum time to keep entry */
+    maxTTL: number;
+  },
+): ToolHandler<TInput, TOutput> {
+  const cache = new ToolCache<SWRCacheEntry<TOutput>>();
+  const keyGen = options.keyGenerator ?? defaultKeyGenerator;
+
+  return async (input, context) => {
+    const key = keyGen(input, context);
+    const cached = cache.get(key);
+    const now = Date.now();
+
+    // Fresh cache hit
+    if (cached && now - cached.fetchedAt < options.staleTTL) {
+      return cached.value;
+    }
+
+    // Stale cache hit - return stale and revalidate
+    if (cached && now - cached.fetchedAt < options.maxTTL) {
+      // Fire and forget revalidation
+      void (async () => {
+        try {
+          const fresh = await handler(input, context);
+          cache.set(key, { value: fresh, fetchedAt: Date.now() }, options.maxTTL);
+        } catch {
+          // Ignore revalidation errors
+        }
+      })();
+
+      return cached.value;
+    }
+
+    // Cache miss - fetch fresh
+    const result = await handler(input, context);
+    cache.set(key, { value: result, fetchedAt: now }, options.maxTTL);
+    return result;
+  };
+}