@od-oneapp/ai-platform 0.1.0

package/src/server/messages/converter.ts

@@ -0,0 +1,245 @@
+/**
+ * @fileoverview Message converter factory for UI to model message transformation.
+ * @module @od-oneapp/ai-platform/messages
+ *
+ * Provides factory for creating message converters that transform UI messages
+ * to model-compatible format with configurable transformations.
+ *
+ * @example
+ * ```ts
+ * import { createMessageConverter } from '@od-oneapp/ai-platform/messages';
+ *
+ * const converter = createMessageConverter({
+ *   maxMessages: 50,
+ *   stripSystemMessages: false,
+ *   transform: (msg) => ({
+ *     ...msg,
+ *     content: msg.content.trim(),
+ *   }),
+ * });
+ *
+ * const modelMessages = await converter.toModelMessages(uiMessages);
+ * ```
+ */
+
+import {
+  type MessageConverter,
+  type MessageConverterConfig,
+  type ModelMessage,
+  type UIMessage,
+} from './types';
+
+// =============================================================================
+// Default Configuration
+// =============================================================================
+
+/**
+ * Default configuration for message converter.
+ */
+const DEFAULT_CONFIG: Required<Omit<MessageConverterConfig, 'transform'>> & {
+  transform: undefined;
+} = {
+  stripSystemMessages: false,
+  maxMessages: Infinity,
+  transform: undefined,
+};
+
+// =============================================================================
+// Message Converter Factory
+// =============================================================================
+
+/**
+ * Creates a message converter for transforming UI messages to model format.
+ *
+ * The converter applies the following transformations in order:
+ * 1. Custom transform function (if provided)
+ * 2. System message filtering (if stripSystemMessages is true)
+ * 3. Sliding window truncation (if maxMessages is set)
+ * 4. Conversion to model message format
+ *
+ * @param config - Converter configuration options.
+ * @returns MessageConverter instance.
+ *
+ * @example Basic usage
+ * ```ts
+ * const converter = createMessageConverter();
+ * const modelMessages = await converter.toModelMessages(uiMessages);
+ * ```
+ *
+ * @example With configuration
+ * ```ts
+ * const converter = createMessageConverter({
+ *   maxMessages: 20,
+ *   stripSystemMessages: true,
+ * });
+ *
+ * // Only last 20 non-system messages will be included
+ * const modelMessages = await converter.toModelMessages(uiMessages);
+ * ```
+ *
+ * @example With custom transform
+ * ```ts
+ * const converter = createMessageConverter({
+ *   transform: (msg) => {
+ *     // Filter out empty messages
+ *     if (!msg.content.trim()) return null;
+ *     // Normalize content
+ *     return { ...msg, content: msg.content.toLowerCase() };
+ *   },
+ * });
+ * ```
+ */
+export function createMessageConverter(config: MessageConverterConfig = {}): MessageConverter {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+
+  /**
+   * Applies all transformations to the message array.
+   * @param messages - Input messages.
+   * @returns Transformed messages.
+   */
+  function processMessages(messages: readonly UIMessage[]): readonly UIMessage[] {
+    let processed = [...messages];
+
+    // 1. Apply custom transform and filter nulls
+    if (mergedConfig.transform) {
+      const { transform } = mergedConfig;
+      processed = processed
+        .map(msg => transform(msg))
+        .filter((msg): msg is UIMessage => msg !== null);
+    }
+
+    // 2. Strip system messages if configured
+    if (mergedConfig.stripSystemMessages) {
+      processed = processed.filter(msg => msg.role !== 'system');
+    }
+
+    // 3. Apply sliding window (keep last N messages)
+    if (mergedConfig.maxMessages < Infinity && processed.length > mergedConfig.maxMessages) {
+      processed = processed.slice(-mergedConfig.maxMessages);
+    }
+
+    return processed;
+  }
+
+  /**
+   * Converts a single UI message to model message format.
+   * @param uiMessage - UI message to convert.
+   * @returns Model message.
+   */
+  function convertToModelMessage(uiMessage: UIMessage): ModelMessage {
+    return {
+      role: uiMessage.role,
+      content: uiMessage.content,
+    };
+  }
+
+  return {
+    async toModelMessages(messages: readonly UIMessage[]): Promise<readonly ModelMessage[]> {
+      const processed = processMessages(messages);
+      return processed.map(convertToModelMessage);
+    },
+
+    toModelMessagesSync(messages: readonly UIMessage[]): readonly ModelMessage[] {
+      const processed = processMessages(messages);
+      return processed.map(convertToModelMessage);
+    },
+  };
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Creates a transform function that chains multiple transforms.
+ *
+ * @param transforms - Array of transform functions to chain.
+ * @returns Combined transform function.
+ *
+ * @example
+ * ```ts
+ * const converter = createMessageConverter({
+ *   transform: chainTransforms([
+ *     // Remove empty messages
+ *     (msg) => msg.content.trim() ? msg : null,
+ *     // Normalize whitespace
+ *     (msg) => ({ ...msg, content: msg.content.replace(/\s+/g, ' ') }),
+ *   ]),
+ * });
+ * ```
+ */
+export function chainTransforms(
+  transforms: ReadonlyArray<(msg: UIMessage) => UIMessage | null>,
+): (msg: UIMessage) => UIMessage | null {
+  return (msg: UIMessage) => {
+    let current: UIMessage | null = msg;
+    for (const transform of transforms) {
+      if (current === null) return null;
+      current = transform(current);
+    }
+    return current;
+  };
+}
+
+/**
+ * Creates a transform that filters messages by role.
+ *
+ * @param allowedRoles - Roles to allow through.
+ * @returns Transform function.
+ *
+ * @example
+ * ```ts
+ * const converter = createMessageConverter({
+ *   transform: filterByRole(['user', 'assistant']),
+ * });
+ * ```
+ */
+export function filterByRole(
+  allowedRoles: readonly UIMessage['role'][],
+): (msg: UIMessage) => UIMessage | null {
+  const roleSet = new Set(allowedRoles);
+  return msg => (roleSet.has(msg.role) ? msg : null);
+}
+
+/**
+ * Creates a transform that filters messages by content.
+ *
+ * @param predicate - Function to test message content.
+ * @returns Transform function.
+ *
+ * @example
+ * ```ts
+ * // Filter out messages with only whitespace
+ * const converter = createMessageConverter({
+ *   transform: filterByContent((content) => content.trim().length > 0),
+ * });
+ * ```
+ */
+export function filterByContent(
+  predicate: (content: string) => boolean,
+): (msg: UIMessage) => UIMessage | null {
+  return msg => (predicate(msg.content) ? msg : null);
+}
+
+/**
+ * Creates a transform that modifies message content.
+ *
+ * @param modifier - Function to modify content.
+ * @returns Transform function.
+ *
+ * @example
+ * ```ts
+ * // Trim all message content
+ * const converter = createMessageConverter({
+ *   transform: transformContent((content) => content.trim()),
+ * });
+ * ```
+ */
+export function transformContent(
+  modifier: (content: string) => string,
+): (msg: UIMessage) => UIMessage {
+  return msg => ({
+    ...msg,
+    content: modifier(msg.content),
+  });
+}

package/src/server/messages/data-parts.ts

@@ -0,0 +1,338 @@
+/**
+ * @fileoverview Data part extractor factory for type-safe data extraction.
+ * @module @od-oneapp/ai-platform/messages
+ *
+ * Provides factory for creating typed data part extractors that validate
+ * and extract custom data from message streams.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { createDataPartExtractor } from '@od-oneapp/ai-platform/messages';
+ *
+ * const ToolShimmerSchema = z.object({
+ *   toolCallId: z.string(),
+ *   toolName: z.string(),
+ *   state: z.enum(['pending', 'loading', 'success', 'error']),
+ * });
+ *
+ * const ProgressSchema = z.object({
+ *   current: z.number(),
+ *   total: z.number(),
+ * });
+ *
+ * const extractor = createDataPartExtractor({
+ *   schemas: {
+ *     'tool-shimmer': ToolShimmerSchema,
+ *     'progress': ProgressSchema,
+ *   },
+ *   onUnknownType: (type, data) => {
+ *     console.warn(`Unknown data part type: ${type}`);
+ *   },
+ * });
+ *
+ * const shimmers = extractor.extract(messages, 'tool-shimmer');
+ * const allParts = extractor.extractAll(messages);
+ * ```
+ */
+
+import { logWarn } from '@repo/shared/logs';
+import { type z } from 'zod';
+
+import {
+  type DataPart,
+  type DataPartExtractor,
+  type DataPartExtractorConfig,
+  type DataPartSchemaMap,
+  type ExtractedDataParts,
+  type UIMessage,
+} from './types';
+
+// =============================================================================
+// Data Part Extractor Factory
+// =============================================================================
+
+/**
+ * Creates a type-safe data part extractor with Zod schema validation.
+ *
+ * The extractor validates each data part against its registered schema,
+ * providing type-safe access to custom streaming data.
+ *
+ * @param config - Extractor configuration with schema map.
+ * @returns DataPartExtractor instance.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const SourceSchema = z.object({
+ *   id: z.string(),
+ *   url: z.string().url(),
+ *   title: z.string(),
+ * });
+ *
+ * const extractor = createDataPartExtractor({
+ *   schemas: { source: SourceSchema },
+ * });
+ *
+ * // Type-safe extraction - returns Source[]
+ * const sources = extractor.extract(messages, 'source');
+ * ```
+ *
+ * @example With unknown type handler
+ * ```ts
+ * const extractor = createDataPartExtractor({
+ *   schemas: { progress: ProgressSchema },
+ *   onUnknownType: (type, data) => {
+ *     // Log unknown types for debugging
+ *     console.warn(`Unhandled data part: ${type}`, data);
+ *   },
+ * });
+ * ```
+ *
+ * @example Extracting all types
+ * ```ts
+ * const allParts = extractor.extractAll(messages);
+ * // { progress: [...], source: [...] }
+ * ```
+ */
+export function createDataPartExtractor<T extends DataPartSchemaMap>(
+  config: DataPartExtractorConfig<T>,
+): DataPartExtractor<T> {
+  const { schemas, onUnknownType } = config;
+  const schemaKeys = new Set(Object.keys(schemas));
+
+  /**
+   * Extracts data parts from a single message.
+   * @param message - Message to extract from.
+   * @returns Array of data parts.
+   */
+  function extractFromMessage(message: UIMessage): readonly DataPart[] {
+    const parts: DataPart[] = [];
+
+    // Extract from message.data if present
+    if (message.data && Array.isArray(message.data)) {
+      parts.push(...message.data);
+    }
+
+    // Extract from message.parts if present (filter for data parts)
+    if (message.parts && Array.isArray(message.parts)) {
+      for (const part of message.parts) {
+        // Data parts have a 'type' and 'data' property
+        if (
+          part &&
+          typeof part === 'object' &&
+          'type' in part &&
+          'data' in part &&
+          typeof (part as DataPart).type === 'string'
+        ) {
+          parts.push(part as DataPart);
+        }
+      }
+    }
+
+    return parts;
+  }
+
+  /**
+   * Validates a data part against its schema.
+   * @param type - Type of the data part.
+   * @param data - Data to validate.
+   * @returns Validated data or null if invalid.
+   */
+  function validateDataPart<K extends keyof T & string>(
+    type: K,
+    data: unknown,
+  ): z.infer<T[K]> | null {
+    const schema = schemas[type];
+    if (!schema) return null;
+
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return result.data as z.infer<T[K]>;
+    }
+
+    // Log validation errors in development
+    if (process.env.NODE_ENV === 'development') {
+      logWarn(`Data part validation failed for type "${type}"`, { error: result.error });
+    }
+
+    return null;
+  }
+
+  return {
+    extract<K extends keyof T & string>(messages: readonly UIMessage[], type: K): z.infer<T[K]>[] {
+      const results: z.infer<T[K]>[] = [];
+
+      for (const message of messages) {
+        const parts = extractFromMessage(message);
+
+        for (const part of parts) {
+          if (part.type === type) {
+            const validated = validateDataPart(type, part.data);
+            if (validated !== null) {
+              results.push(validated);
+            }
+          } else if (!schemaKeys.has(part.type) && onUnknownType) {
+            onUnknownType(part.type, part.data);
+          }
+        }
+      }
+
+      return results;
+    },
+
+    extractAll(messages: readonly UIMessage[]): Partial<ExtractedDataParts<T>> {
+      const results: Partial<ExtractedDataParts<T>> = {};
+
+      // Initialize empty arrays for each schema type
+      for (const type of schemaKeys) {
+        (results as Record<string, unknown[]>)[type] = [];
+      }
+
+      for (const message of messages) {
+        const parts = extractFromMessage(message);
+
+        for (const part of parts) {
+          if (schemaKeys.has(part.type)) {
+            const type = part.type as keyof T & string;
+            const validated = validateDataPart(type, part.data);
+            if (validated !== null) {
+              (results as Record<string, unknown[]>)[type]?.push(validated);
+            }
+          } else if (onUnknownType) {
+            onUnknownType(part.type, part.data);
+          }
+        }
+      }
+
+      return results;
+    },
+
+    hasSchema(type: string): type is keyof T & string {
+      return schemaKeys.has(type);
+    },
+  };
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Creates a combined extractor from multiple schema maps.
+ *
+ * @param extractors - Array of extractor configs to combine.
+ * @returns Combined DataPartExtractorConfig.
+ *
+ * @example
+ * ```ts
+ * const combinedSchemas = mergeSchemas(
+ *   { progress: ProgressSchema },
+ *   { source: SourceSchema, step: StepSchema },
+ * );
+ *
+ * const extractor = createDataPartExtractor({
+ *   schemas: combinedSchemas,
+ * });
+ * ```
+ */
+export function mergeSchemas<T1 extends DataPartSchemaMap, T2 extends DataPartSchemaMap>(
+  schemas1: T1,
+  schemas2: T2,
+): T1 & T2 {
+  return { ...schemas1, ...schemas2 };
+}
+
+/**
+ * Collects all data parts from messages without validation.
+ *
+ * @param messages - Messages to collect from.
+ * @returns Array of all data parts.
+ *
+ * @example
+ * ```ts
+ * const allParts = collectDataParts(messages);
+ * // [{ type: 'progress', data: {...} }, { type: 'source', data: {...} }]
+ * ```
+ */
+export function collectDataParts(messages: readonly UIMessage[]): readonly DataPart[] {
+  const parts: DataPart[] = [];
+
+  for (const message of messages) {
+    // Collect from message.data
+    if (message.data && Array.isArray(message.data)) {
+      parts.push(...message.data);
+    }
+
+    // Collect from message.parts (filter for data parts)
+    if (message.parts && Array.isArray(message.parts)) {
+      for (const part of message.parts) {
+        if (
+          part &&
+          typeof part === 'object' &&
+          'type' in part &&
+          'data' in part &&
+          typeof (part as DataPart).type === 'string'
+        ) {
+          parts.push(part as DataPart);
+        }
+      }
+    }
+  }
+
+  return parts;
+}
+
+/**
+ * Groups data parts by type.
+ *
+ * @param parts - Data parts to group.
+ * @returns Object with data parts grouped by type.
+ *
+ * @example
+ * ```ts
+ * const grouped = groupDataPartsByType(parts);
+ * // { 'progress': [...], 'source': [...] }
+ * ```
+ */
+export function groupDataPartsByType(parts: readonly DataPart[]): Record<string, DataPart[]> {
+  const grouped: Record<string, DataPart[]> = {};
+
+  for (const part of parts) {
+    const bucket = grouped[part.type] ?? [];
+    bucket.push(part);
+    grouped[part.type] = bucket;
+  }
+
+  return grouped;
+}
+
+/**
+ * Gets the latest data part of a specific type.
+ *
+ * @param messages - Messages to search.
+ * @param type - Type of data part to find.
+ * @returns Latest data part of the type or undefined.
+ *
+ * @example
+ * ```ts
+ * const latestProgress = getLatestDataPart(messages, 'progress');
+ * ```
+ */
+export function getLatestDataPart(
+  messages: readonly UIMessage[],
+  type: string,
+): DataPart | undefined {
+  const parts = collectDataParts(messages);
+
+  // Search from end to find latest
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const part = parts[i];
+    if (part?.type === type) {
+      return part;
+    }
+  }
+
+  return undefined;
+}