@od-oneapp/ai-platform 0.1.0

package/src/server/messages/extraction.ts

@@ -0,0 +1,328 @@
+/**
+ * @fileoverview Message extraction and session utilities migrated from @repo/ai.
+ *
+ * Provides functions for extracting content from UI messages, validating messages,
+ * session initialization, and message persistence helpers.
+ *
+ * @module @od-oneapp/ai-platform/server/messages/extraction
+ */
+
+import { generateId } from '../../shared';
+
+import type { SDKUIMessage, JSONValue } from '../../shared';
+
+// =============================================================================
+// Local types for message part introspection
+// =============================================================================
+
+/** Minimal part shape used for extraction type guards. */
+interface MessagePartLike {
+  type?: string;
+  text?: string;
+  name?: string;
+  url?: string;
+  mimeType?: string;
+  state?: string;
+}
+
+/** File attachment extracted from a UIMessage. */
+export interface ExtractedFilePart {
+  readonly type: 'file';
+  readonly name: string;
+  readonly url: string;
+  readonly mimeType: string;
+  readonly size?: number;
+}
+
+// =============================================================================
+// Session Types
+// =============================================================================
+
+/** Initializes or retrieves a session, returning its ID and newness flag. */
+export type InitializeSessionFn = (
+  sessionId?: string,
+) => Promise<{ sessionId: string; isNew: boolean }>;
+
+/** Persists a message to storage for a given session. */
+export type PersistMessageFn = (
+  sessionId: string,
+  content: string,
+  options?: { autoTitle?: boolean },
+) => Promise<void>;
+
+/** Sets up a resumable stream for a given response and session. */
+export type SetupResumableStreamFn = (response: Response, sessionId: string) => Promise<void>;
+
+// =============================================================================
+// Message Extraction Functions
+// =============================================================================
+
+/**
+ * Extract text content from a UIMessage by joining all text parts.
+ *
+ * @param message - UI message to extract text from
+ * @returns Concatenated text from all text parts, or empty string
+ *
+ * @example
+ * ```ts
+ * const text = extractTextContent(message);
+ * ```
+ */
+export function extractTextContent(message: SDKUIMessage): string {
+  if (!message.parts) return '';
+
+  return message.parts
+    .filter((part): part is { type: 'text'; text: string } => {
+      const p = part as MessagePartLike;
+      return p.type === 'text' && 'text' in part;
+    })
+    .map(part => part.text)
+    .join('\n');
+}
+
+/**
+ * Extract file attachments from a UIMessage.
+ *
+ * @param message - UI message to extract files from
+ * @returns Array of extracted file parts
+ *
+ * @example
+ * ```ts
+ * const files = extractFileAttachments(message);
+ * ```
+ */
+export function extractFileAttachments(message: SDKUIMessage): ExtractedFilePart[] {
+  if (!message.parts) return [];
+
+  return message.parts.filter(part => {
+    const p = part as MessagePartLike;
+    return p.type === 'file' && 'name' in part && 'url' in part && 'mimeType' in part;
+  }) as unknown as ExtractedFilePart[];
+}
+
+/**
+ * Find the last user message in an array of messages.
+ *
+ * @param messages - Array of UIMessage objects
+ * @returns The last user message or null if none found
+ *
+ * @example
+ * ```ts
+ * const lastUser = getLastUserMessage(messages);
+ * if (lastUser) {
+ *   console.log(extractTextContent(lastUser));
+ * }
+ * ```
+ */
+export function getLastUserMessage(messages: SDKUIMessage[]): SDKUIMessage | null {
+  return messages.findLast(message => message.role === 'user') ?? null;
+}
+
+/**
+ * Basic message validator for UIMessage arrays.
+ *
+ * @param messages - Unknown value to validate
+ * @returns Type guard confirming the value is a UIMessage array
+ */
+export function defaultValidateMessages(messages: unknown): messages is SDKUIMessage[] {
+  return Array.isArray(messages);
+}
+
+/**
+ * Extract text from a UIMessage that may contain parts or plain content.
+ *
+ * @param message - UI message to extract text from
+ * @returns Plain text string from the message
+ */
+export function defaultGetMessageText(message: SDKUIMessage): string {
+  if ('content' in message && typeof (message as { content?: unknown }).content === 'string') {
+    return (message as { content: string }).content;
+  }
+
+  if ('parts' in message && Array.isArray((message as { parts?: JSONValue[] }).parts)) {
+    return (message as { parts: Array<{ type: string; text?: string }> }).parts
+      .filter(
+        (p): p is { type: 'text'; text: string } => p.type === 'text' && typeof p.text === 'string',
+      )
+      .map(p => p.text)
+      .join('');
+  }
+
+  return '';
+}
+
+// =============================================================================
+// Session Helpers
+// =============================================================================
+
+/**
+ * Minimal default session initializer using in-memory IDs.
+ * Consumers can override with database-backed implementations.
+ */
+export const inMemoryInitializeSession: InitializeSessionFn = async sessionId => ({
+  sessionId: sessionId ?? generateId(),
+  isNew: !sessionId,
+});
+
+/** No-op persistence helper for environments without storage. */
+export const noopPersistMessage: PersistMessageFn = async () => {};
+
+/** No-op resumable stream helper for environments without resumption support. */
+export const noopSetupResumableStream: SetupResumableStreamFn = async () => {};
+
+// =============================================================================
+// Reasoning & Finish Event Utilities
+// =============================================================================
+
+/**
+ * Extract reasoning text from a finish event.
+ * Handles both array and string formats for reasoning.
+ *
+ * @param finishEvent - Finish event from streamText/generateText
+ * @returns Reasoning text string or undefined
+ *
+ * @example
+ * ```ts
+ * const reasoning = extractReasoningText(event);
+ * if (reasoning) {
+ *   console.log('Model reasoning:', reasoning);
+ * }
+ * ```
+ */
+export function extractReasoningText(finishEvent: {
+  reasoning?: Array<{ text?: string }> | string;
+}): string | undefined {
+  if (!finishEvent.reasoning) return undefined;
+
+  if (Array.isArray(finishEvent.reasoning)) {
+    return finishEvent.reasoning.map((r: { text?: string }) => r?.text ?? '').join('');
+  }
+
+  if (typeof finishEvent.reasoning === 'string') {
+    return finishEvent.reasoning;
+  }
+
+  return undefined;
+}
+
+/**
+ * Build UI message parts from AI SDK finish event.
+ * Extracts text, reasoning, tool calls, and tool results from the finish event.
+ *
+ * @param finishEvent - Finish event from streamText/generateText
+ * @returns Array of UI message parts
+ */
+export function buildUIMessagePartsFromFinishEvent(finishEvent: {
+  text?: string;
+  reasoning?: Array<{ text?: string }> | string;
+  toolCalls?: Array<{
+    toolCallId: string;
+    toolName: string;
+    args?: unknown;
+    input?: unknown;
+  }>;
+  toolResults?: Array<{
+    toolCallId: string;
+    toolName: string;
+    result?: unknown;
+    output?: unknown;
+  }>;
+}): Array<{
+  type: string;
+  text?: string;
+  toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  result?: unknown;
+}> {
+  const parts: Array<{
+    type: string;
+    text?: string;
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+    result?: unknown;
+  }> = [];
+
+  // Add text part
+  if (finishEvent.text) {
+    parts.push({ type: 'text', text: finishEvent.text });
+  }
+
+  // Add reasoning if present
+  if (finishEvent.reasoning && Array.isArray(finishEvent.reasoning)) {
+    const reasoningText = finishEvent.reasoning
+      .map((r: { text?: string }) => r?.text ?? '')
+      .join('');
+    if (reasoningText) {
+      parts.push({ type: 'reasoning', text: reasoningText });
+    }
+  } else if (finishEvent.reasoning && typeof finishEvent.reasoning === 'string') {
+    parts.push({ type: 'reasoning', text: finishEvent.reasoning });
+  }
+
+  // Add tool invocations as parts
+  if (finishEvent.toolCalls && finishEvent.toolCalls.length > 0) {
+    for (const tc of finishEvent.toolCalls) {
+      const args = 'args' in tc ? tc.args : (tc as Record<string, unknown>).input;
+      parts.push({
+        type: 'tool-invocation',
+        toolCallId: tc.toolCallId,
+        toolName: tc.toolName,
+        args: args ?? {},
+      });
+    }
+  }
+
+  // Add tool results as parts
+  if (finishEvent.toolResults && finishEvent.toolResults.length > 0) {
+    for (const tr of finishEvent.toolResults) {
+      const result = 'result' in tr ? tr.result : (tr as Record<string, unknown>).output;
+      parts.push({
+        type: 'tool-result',
+        toolCallId: tr.toolCallId,
+        toolName: tr.toolName,
+        result: result ?? null,
+      });
+    }
+  }
+
+  return parts;
+}
+
+/**
+ * Map stored message to UI message format.
+ * Converts database-stored message format to AI SDK UIMessage format.
+ *
+ * @param stored - Stored message from database
+ * @returns UIMessage compatible with AI SDK
+ */
+export function mapStoredToUIMessage(stored: {
+  id: string;
+  role: string;
+  parts?: JSONValue[];
+  content?: string;
+}): SDKUIMessage {
+  return {
+    id: stored.id,
+    role: stored.role as SDKUIMessage['role'],
+    parts:
+      Array.isArray(stored.parts) && stored.parts.length > 0
+        ? (stored.parts as SDKUIMessage['parts'])
+        : stored.content
+          ? [{ type: 'text', text: stored.content }]
+          : [],
+  };
+}
+
+/**
+ * Map array of stored messages to UI messages format.
+ *
+ * @param stored - Array of stored messages from database
+ * @returns Array of UIMessage compatible with AI SDK
+ */
+export function mapStoredMessagesToUI(
+  stored: Array<{ id: string; role: string; parts?: JSONValue[]; content?: string }>,
+): SDKUIMessage[] {
+  return stored.map(mapStoredToUIMessage);
+}

package/src/server/messages/index.ts

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Messages module for AI SDK v6 message handling.
+ * @module @od-oneapp/ai-platform/messages
+ *
+ * Provides utilities for message conversion, data part extraction,
+ * and message window management.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createMessageConverter,
+ *   createDataPartExtractor,
+ *   createMessageWindow,
+ * } from '@od-oneapp/ai-platform/messages';
+ *
+ * // Convert UI messages to model format
+ * const converter = createMessageConverter({ maxMessages: 50 });
+ * const modelMessages = await converter.toModelMessages(uiMessages);
+ *
+ * // Extract typed data parts
+ * const extractor = createDataPartExtractor({
+ *   schemas: { progress: ProgressSchema },
+ * });
+ * const progress = extractor.extract(messages, 'progress');
+ *
+ * // Manage message window with token limits
+ * const window = createMessageWindow({ maxTokens: 8000 });
+ * const truncated = await window.apply(messages);
+ * ```
+ */
+
+// =============================================================================
+// Type Exports
+// =============================================================================
+
+export type {
+  // Message types
+  MessageRole,
+  DataPart,
+  ToolCallPart,
+  ToolResultPart,
+  TextPart,
+  MessagePart,
+  UIMessage,
+  ModelMessage,
+  // Converter types
+  MessageConverterConfig,
+  MessageConverter,
+  // Data part extractor types
+  DataPartSchemaMap,
+  DataPartExtractorConfig,
+  ExtractedDataParts,
+  DataPartExtractor,
+  // Window types
+  TokenizerType,
+  TruncationStrategy,
+  MessageWindowConfig,
+  MessageWindow,
+} from './types';
+
+// =============================================================================
+// Converter Exports
+// =============================================================================
+
+export {
+  createMessageConverter,
+  chainTransforms,
+  filterByRole,
+  filterByContent,
+  transformContent,
+} from './converter';
+
+// =============================================================================
+// Data Parts Exports
+// =============================================================================
+
+export {
+  createDataPartExtractor,
+  mergeSchemas,
+  collectDataParts,
+  groupDataPartsByType,
+  getLatestDataPart,
+} from './data-parts';
+
+// =============================================================================
+// Window Exports
+// =============================================================================
+
+export {
+  createMessageWindow,
+  wordBasedTokenizer,
+  createCompactWindow,
+  createStandardWindow,
+  createLargeWindow,
+  createExtendedWindow,
+} from './window';
+
+// =============================================================================
+// Extraction & Session Exports (migrated from @repo/ai)
+// =============================================================================
+
+export {
+  // Message extraction
+  extractTextContent,
+  extractFileAttachments,
+  getLastUserMessage,
+  defaultValidateMessages,
+  defaultGetMessageText,
+  // Session helpers
+  inMemoryInitializeSession,
+  noopPersistMessage,
+  noopSetupResumableStream,
+  // Reasoning & finish event utilities
+  extractReasoningText,
+  buildUIMessagePartsFromFinishEvent,
+  // Stored message mapping
+  mapStoredToUIMessage,
+  mapStoredMessagesToUI,
+} from './extraction';
+
+export type {
+  ExtractedFilePart,
+  InitializeSessionFn,
+  PersistMessageFn,
+  SetupResumableStreamFn,
+} from './extraction';