@od-oneapp/ai-platform 0.1.0

package/src/internal/ui-factories/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview UI Factories Module
+ *
+ * React-agnostic factories for tool UI rendering and status messages.
+ * Provides composable utilities for building AI chat interfaces.
+ *
+ * @module ui-factories
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createToolUIRenderer,
+ *   createStatusMessageHelper,
+ *   createToolShimmerManager,
+ * } from '@od-oneapp/ai-platform/ui-factories';
+ *
+ * // Create a tool UI renderer
+ * const renderer = createToolUIRenderer({
+ *   tools: {
+ *     'web_search': {
+ *       pendingLabel: 'Searching the web...',
+ *       completeLabel: (r) => `Found ${(r as { results: unknown[] }).results.length} results`,
+ *       icon: 'search',
+ *     },
+ *   },
+ * });
+ *
+ * // Create a status message helper
+ * const status = createStatusMessageHelper({
+ *   agents: { 'triage': 'Router' },
+ *   messages: { thinking: 'Thinking...' },
+ * });
+ *
+ * // Create a shimmer manager
+ * const shimmer = createToolShimmerManager({
+ *   debounceMs: 100,
+ *   showShimmerDuring: ['tool-call', 'tool-result'],
+ * });
+ *
+ * // Use in your chat UI
+ * const toolUI = renderer.getToolUI('web_search', 'running');
+ * const statusMessage = status.getMessage('thinking', { agent: 'triage' });
+ * const showShimmer = shimmer.shouldShow(messageParts);
+ * ```
+ */
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+export {
+  // Tool UI Renderer types
+  type ToolUIState,
+  type ToolUIConfig,
+  type ToolUIRendererConfig,
+  type ToolUIResult,
+  type ToolUIRenderer,
+  // Status Message types
+  type StatusType,
+  type StatusContext,
+  type StatusMessages,
+  type StatusMessageConfig,
+  type StatusMessageHelper,
+  // Shimmer Manager types
+  type ShimmerState,
+  type ToolShimmerManagerConfig,
+  type MessagePart,
+  type ToolShimmerManager,
+  // Default values
+  DEFAULT_DEBOUNCE_MS,
+  DEFAULT_SHIMMER_STATES,
+  DEFAULT_STATUS_MESSAGES,
+  DEFAULT_TOOL_FALLBACK,
+} from './types';
+
+// -----------------------------------------------------------------------------
+// Factories
+// -----------------------------------------------------------------------------
+
+export { createToolUIRenderer } from './tool-renderer';
+export { createStatusMessageHelper } from './status-helpers';
+export { createToolShimmerManager } from './shimmer-manager';

package/src/internal/ui-factories/shimmer-manager.ts

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview Tool Shimmer Manager Factory
+ *
+ * Creates a shimmer manager for controlling loading state UI based on message parts.
+ * Supports debouncing to prevent flickering during rapid state changes.
+ *
+ * @module ui-factories/shimmer-manager
+ *
+ * @example
+ * ```typescript
+ * import { createToolShimmerManager } from '@od-oneapp/ai-platform/ui-factories';
+ *
+ * const shimmerManager = createToolShimmerManager({
+ *   debounceMs: 100,
+ *   showShimmerDuring: ['tool-call', 'tool-result'],
+ * });
+ *
+ * // Check if shimmer should be shown based on current message parts
+ * const parts = [
+ *   { type: 'tool-invocation', state: 'call' },
+ *   { type: 'text', content: 'Processing your request...' },
+ * ];
+ *
+ * if (shimmerManager.shouldShow(parts)) {
+ *   // Show shimmer loading indicator
+ * }
+ *
+ * // Update state with debouncing
+ * shimmerManager.update(newParts);
+ *
+ * // Check current visibility
+ * console.log(shimmerManager.isShowing()); // true or false
+ *
+ * // Reset state
+ * shimmerManager.reset();
+ * ```
+ */
+
+import {
+  type ToolShimmerManagerConfig,
+  type ToolShimmerManager,
+  type MessagePart,
+  type ShimmerState,
+  DEFAULT_DEBOUNCE_MS,
+  DEFAULT_SHIMMER_STATES,
+} from './types';
+
+/**
+ * Creates a tool shimmer manager with the given configuration.
+ *
+ * The manager determines when to show a shimmer/loading indicator
+ * based on the current message parts. It supports debouncing to
+ * prevent UI flickering during rapid state changes.
+ *
+ * @param config - Configuration for debouncing and shimmer states
+ * @returns A ToolShimmerManager instance
+ *
+ * @example
+ * ```typescript
+ * const manager = createToolShimmerManager({
+ *   debounceMs: 150,
+ *   showShimmerDuring: ['tool-call', 'thinking'],
+ * });
+ *
+ * // Use with streaming messages
+ * useEffect(() => {
+ *   manager.update(message.parts);
+ * }, [message.parts]);
+ *
+ * return manager.isShowing() ? <Shimmer /> : null;
+ * ```
+ */
+export function createToolShimmerManager(
+  config: ToolShimmerManagerConfig = {},
+): ToolShimmerManager {
+  const { debounceMs = DEFAULT_DEBOUNCE_MS, showShimmerDuring = DEFAULT_SHIMMER_STATES } = config;
+
+  // Internal state
+  let currentVisibility = false;
+  let lastUpdateTime = 0;
+  let pendingVisibility: boolean | null = null;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Create a set for efficient lookup
+  const shimmerStates = new Set(showShimmerDuring);
+
+  /**
+   * Check if parts contain any shimmer-triggering states.
+   */
+  function checkParts(parts: readonly MessagePart[]): boolean {
+    for (const part of parts) {
+      // Check for tool invocation states
+      if (part.type === 'tool-invocation' || part.type === 'tool-call') {
+        const state = normalizeState(part.state);
+        if (state && shimmerStates.has(state)) {
+          return true;
+        }
+      }
+
+      // Check for tool-result type
+      if (part.type === 'tool-result' && shimmerStates.has('tool-result')) {
+        return true;
+      }
+
+      // Check for thinking state
+      if (part.type === 'thinking' && shimmerStates.has('thinking')) {
+        return true;
+      }
+
+      // Check for text-delta (indicates ongoing streaming)
+      if (part.type === 'text-delta' && shimmerStates.has('thinking')) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Normalize tool invocation states to shimmer states.
+   */
+  function normalizeState(state: string | undefined): ShimmerState | null {
+    if (!state) return null;
+
+    switch (state) {
+      case 'call':
+      case 'calling':
+      case 'pending':
+        return 'tool-call';
+      case 'result':
+      case 'partial-call':
+        return 'tool-result';
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Determine if shimmer should be shown (immediate check, no state update).
+   */
+  function shouldShow(parts: readonly MessagePart[]): boolean {
+    return checkParts(parts);
+  }
+
+  /**
+   * Update internal state with debouncing.
+   */
+  function update(parts: readonly MessagePart[]): void {
+    const newVisibility = checkParts(parts);
+    const now = Date.now();
+
+    // Clear any pending debounce
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+
+    // If showing shimmer, update immediately
+    if (newVisibility && !currentVisibility) {
+      currentVisibility = true;
+      lastUpdateTime = now;
+      pendingVisibility = null;
+      return;
+    }
+
+    // If hiding shimmer, apply debounce to prevent flickering
+    if (!newVisibility && currentVisibility) {
+      // Check if enough time has passed since last update
+      const timeSinceLastUpdate = now - lastUpdateTime;
+
+      if (timeSinceLastUpdate >= debounceMs) {
+        // Enough time has passed, hide immediately
+        currentVisibility = false;
+        lastUpdateTime = now;
+        pendingVisibility = null;
+      } else {
+        // Schedule the hide after remaining debounce time
+        pendingVisibility = false;
+        const remainingDebounce = debounceMs - timeSinceLastUpdate;
+
+        debounceTimer = setTimeout(() => {
+          if (pendingVisibility === false) {
+            currentVisibility = false;
+            lastUpdateTime = Date.now();
+            pendingVisibility = null;
+          }
+          debounceTimer = null;
+        }, remainingDebounce);
+      }
+    }
+  }
+
+  /**
+   * Reset the manager state.
+   */
+  function reset(): void {
+    currentVisibility = false;
+    lastUpdateTime = 0;
+    pendingVisibility = null;
+
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+  }
+
+  /**
+   * Get the current shimmer visibility state.
+   */
+  function isShowing(): boolean {
+    return currentVisibility;
+  }
+
+  return {
+    shouldShow,
+    update,
+    reset,
+    isShowing,
+  };
+}

package/src/internal/ui-factories/status-helpers.ts

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview Status Message Helper Factory
+ *
+ * Creates a status message helper for generating user-friendly status messages.
+ * Supports agent name substitution and customizable message templates.
+ *
+ * @module ui-factories/status-helpers
+ *
+ * @example
+ * ```typescript
+ * import { createStatusMessageHelper } from '@od-oneapp/ai-platform/ui-factories';
+ *
+ * const status = createStatusMessageHelper({
+ *   agents: {
+ *     'triage': 'Router',
+ *     'research': 'Researcher',
+ *     'summarize': 'Summarizer',
+ *   },
+ *   messages: {
+ *     thinking: 'Thinking...',
+ *     toolCalling: (toolName) => `Using ${toolName}...`,
+ *     complete: 'Done',
+ *     error: (err) => `Error: ${err.message}`,
+ *   },
+ * });
+ *
+ * // Get status message with agent context
+ * status.getMessage('thinking', { agent: 'triage' });
+ * // "Router is thinking..."
+ *
+ * // Get status message for tool calling
+ * status.getMessage('toolCalling', { agent: 'research', toolName: 'web_search' });
+ * // "Researcher is using web_search..."
+ *
+ * // Get error status message
+ * status.getMessage('error', { error: new Error('Network timeout') });
+ * // "Error: Network timeout"
+ * ```
+ */
+
+import {
+  type StatusMessageConfig,
+  type StatusMessageHelper,
+  type StatusType,
+  type StatusContext,
+  DEFAULT_STATUS_MESSAGES,
+} from './types';
+
+/**
+ * Creates a status message helper with the given configuration.
+ *
+ * The helper generates user-friendly status messages based on the
+ * current agent state and context. Agent names can be mapped to
+ * display names for a better user experience.
+ *
+ * @param config - Configuration for agent names and custom messages
+ * @returns A StatusMessageHelper instance
+ *
+ * @example
+ * ```typescript
+ * const status = createStatusMessageHelper({
+ *   agents: { 'triage': 'Assistant' },
+ * });
+ *
+ * // Use in chat UI
+ * const message = status.getMessage(agentState, { agent: currentAgent });
+ * return <StatusIndicator>{message}</StatusIndicator>;
+ * ```
+ */
+export function createStatusMessageHelper(config: StatusMessageConfig = {}): StatusMessageHelper {
+  const { agents = {}, messages = {} } = config;
+
+  // Merge custom messages with defaults
+  const resolvedMessages = {
+    thinking: messages.thinking ?? DEFAULT_STATUS_MESSAGES.thinking,
+    toolCalling: messages.toolCalling ?? DEFAULT_STATUS_MESSAGES.toolCalling,
+    complete: messages.complete ?? DEFAULT_STATUS_MESSAGES.complete,
+    error: messages.error ?? DEFAULT_STATUS_MESSAGES.error,
+  };
+
+  /**
+   * Get the display name for an agent.
+   */
+  function getAgentDisplayName(agentId: string): string {
+    return agents[agentId] ?? agentId;
+  }
+
+  /**
+   * Get the status message for a given type and context.
+   */
+  function getMessage(type: StatusType, context: StatusContext = {}): string {
+    const { agent, toolName, error } = context;
+
+    // Get the agent display name if provided
+    const agentName = agent ? getAgentDisplayName(agent) : undefined;
+
+    // Generate the base message
+    let baseMessage: string;
+    switch (type) {
+      case 'thinking':
+        baseMessage = resolvedMessages.thinking;
+        break;
+      case 'toolCalling':
+        baseMessage = resolvedMessages.toolCalling(toolName ?? 'tool');
+        break;
+      case 'complete':
+        baseMessage = resolvedMessages.complete;
+        break;
+      case 'error':
+        baseMessage = resolvedMessages.error(error ?? new Error('Unknown error'));
+        break;
+    }
+
+    // Prepend agent name if available
+    if (agentName) {
+      return formatWithAgent(agentName, baseMessage, type);
+    }
+
+    return baseMessage;
+  }
+
+  return {
+    getMessage,
+    getAgentDisplayName,
+  };
+}
+
+/**
+ * Format a message with an agent prefix.
+ */
+function formatWithAgent(agentName: string, message: string, type: StatusType): string {
+  // For messages that already have a verb, add "is" between agent and message
+  // e.g., "Router is thinking..." or "Researcher is using web_search..."
+  const lowerMessage = message.toLowerCase();
+
+  // Determine the connecting word based on message structure
+  if (
+    type === 'thinking' ||
+    type === 'toolCalling' ||
+    lowerMessage.startsWith('thinking') ||
+    lowerMessage.startsWith('using ')
+  ) {
+    return `${agentName} is ${lowerMessage}`;
+  }
+
+  // For complete/error, just prefix with agent name
+  // e.g., "Router: Done" or "Researcher: Error: timeout"
+  return `${agentName}: ${message}`;
+}

package/src/internal/ui-factories/tool-renderer.ts

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Tool UI Renderer Factory
+ *
+ * Creates a tool UI renderer for consistent tool status display across components.
+ * React-agnostic design allows use with any UI framework.
+ *
+ * @module ui-factories/tool-renderer
+ *
+ * @example
+ * ```typescript
+ * import { createToolUIRenderer } from '@od-oneapp/ai-platform/ui-factories';
+ *
+ * const renderer = createToolUIRenderer({
+ *   tools: {
+ *     'web_search': {
+ *       pendingLabel: 'Searching the web...',
+ *       completeLabel: (r) => `Found ${(r as { results: unknown[] }).results.length} results`,
+ *       icon: 'search',
+ *     },
+ *     'read_file': {
+ *       pendingLabel: 'Reading file...',
+ *       completeLabel: (r) => `Read ${(r as { bytes: number }).bytes} bytes`,
+ *       icon: 'file',
+ *     },
+ *   },
+ *   fallback: {
+ *     pendingLabel: 'Processing...',
+ *     icon: 'cog',
+ *   },
+ * });
+ *
+ * // Get UI for a known tool
+ * const searchUI = renderer.getToolUI('web_search', 'running');
+ * // { label: 'Searching the web...', icon: 'search', state: 'running' }
+ *
+ * // Get UI for completion with result
+ * const completeUI = renderer.getToolUI('web_search', 'complete', { results: [1, 2, 3] });
+ * // { label: 'Found 3 results', icon: 'search', state: 'complete' }
+ *
+ * // Get UI for unknown tool (uses fallback)
+ * const unknownUI = renderer.getToolUI('unknown_tool', 'pending');
+ * // { label: 'Processing...', icon: 'cog', state: 'pending' }
+ * ```
+ */
+
+import {
+  type ToolUIRendererConfig,
+  type ToolUIRenderer,
+  type ToolUIState,
+  type ToolUIResult,
+  DEFAULT_TOOL_FALLBACK,
+} from './types';
+
+/**
+ * Creates a tool UI renderer with the given configuration.
+ *
+ * The renderer provides consistent tool status labels and icons
+ * based on the tool name and current state.
+ *
+ * @param config - Configuration specifying tool-specific UI settings
+ * @returns A ToolUIRenderer instance
+ *
+ * @example
+ * ```typescript
+ * const renderer = createToolUIRenderer({
+ *   tools: {
+ *     'database_query': {
+ *       pendingLabel: 'Querying database...',
+ *       completeLabel: (r) => `Found ${(r as { count: number }).count} records`,
+ *       icon: 'database',
+ *     },
+ *   },
+ * });
+ *
+ * // Use in component
+ * const ui = renderer.getToolUI(toolCall.name, toolCall.state, toolCall.result);
+ * return <ToolStatus label={ui.label} icon={ui.icon} />;
+ * ```
+ */
+export function createToolUIRenderer(config: ToolUIRendererConfig): ToolUIRenderer {
+  const { tools, fallback = DEFAULT_TOOL_FALLBACK } = config;
+
+  /**
+   * Get the UI representation for a tool invocation.
+   */
+  function getToolUI(toolName: string, state: ToolUIState, result?: unknown): ToolUIResult {
+    const toolConfig = tools[toolName];
+
+    // Use tool-specific config if available
+    if (toolConfig) {
+      const label = getLabel(toolConfig.pendingLabel, toolConfig.completeLabel, state, result);
+      return {
+        label,
+        icon: toolConfig.icon,
+        state,
+      };
+    }
+
+    // Fall back to default config
+    return {
+      label: getFallbackLabel(fallback.pendingLabel, state, result),
+      icon: fallback.icon,
+      state,
+    };
+  }
+
+  /**
+   * Check if a tool has a custom configuration.
+   */
+  function hasToolConfig(toolName: string): boolean {
+    return toolName in tools;
+  }
+
+  /**
+   * Get all configured tool names.
+   */
+  function getConfiguredTools(): string[] {
+    return Object.keys(tools);
+  }
+
+  return {
+    getToolUI,
+    hasToolConfig,
+    getConfiguredTools,
+  };
+}
+
+/**
+ * Get the label for a tool based on its state.
+ */
+function getLabel(
+  pendingLabel: string,
+  completeLabel: (result: unknown) => string,
+  state: ToolUIState,
+  result?: unknown,
+): string {
+  switch (state) {
+    case 'pending':
+    case 'running':
+      return pendingLabel;
+    case 'complete':
+      try {
+        return completeLabel(result);
+      } catch {
+        // If completeLabel throws, return a generic message
+        return 'Completed';
+      }
+    case 'error':
+      return 'Failed';
+  }
+}
+
+/**
+ * Get the fallback label for unknown tools.
+ */
+function getFallbackLabel(pendingLabel: string, state: ToolUIState, result?: unknown): string {
+  void result;
+  switch (state) {
+    case 'pending':
+    case 'running':
+      return pendingLabel;
+    case 'complete':
+      return 'Completed';
+    case 'error':
+      return 'Failed';
+  }
+}