@od-oneapp/ai-platform 0.1.0

package/src/client/chat-usage.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Chat usage aggregation helpers.
+ *
+ * Lightweight, client-safe aggregation for LanguageModelUsage values
+ * used across chat-based UI surfaces.
+ */
+
+import type { SDKLanguageModelUsage as LanguageModelUsage } from '../shared';
+
+/**
+ * Aggregate two usage snapshots into a single LanguageModelUsage object.
+ *
+ * Normalizes `cachedInputTokens` and `reasoningTokens` from both top-level and
+ * nested detail fields when present.
+ */
+export function aggregateUsage(
+  current: Partial<LanguageModelUsage>,
+  addition: Partial<LanguageModelUsage>,
+): LanguageModelUsage {
+  const reasoningTokens =
+    (current.outputTokenDetails?.reasoningTokens ?? current.reasoningTokens ?? 0) +
+    (addition.outputTokenDetails?.reasoningTokens ?? addition.reasoningTokens ?? 0);
+
+  const cacheReadTokens =
+    (current.inputTokenDetails?.cacheReadTokens ?? current.cachedInputTokens ?? 0) +
+    (addition.inputTokenDetails?.cacheReadTokens ?? addition.cachedInputTokens ?? 0);
+
+  const noCacheTokens = (current.inputTokenDetails?.noCacheTokens ?? 0) + (addition.inputTokenDetails?.noCacheTokens ?? 0);
+
+  const cacheWriteTokens =
+    (current.inputTokenDetails?.cacheWriteTokens ?? 0) +
+    (addition.inputTokenDetails?.cacheWriteTokens ?? 0);
+
+  const textTokens =
+    (current.outputTokenDetails?.textTokens ?? 0) + (addition.outputTokenDetails?.textTokens ?? 0);
+
+  return {
+    inputTokens: (current.inputTokens ?? 0) + (addition.inputTokens ?? 0),
+    outputTokens: (current.outputTokens ?? 0) + (addition.outputTokens ?? 0),
+    totalTokens: (current.totalTokens ?? 0) + (addition.totalTokens ?? 0),
+    reasoningTokens,
+    cachedInputTokens: cacheReadTokens,
+    inputTokenDetails: {
+      noCacheTokens: noCacheTokens || undefined,
+      cacheReadTokens: cacheReadTokens || undefined,
+      cacheWriteTokens: cacheWriteTokens || undefined,
+    },
+    outputTokenDetails: {
+      textTokens: textTokens || undefined,
+      reasoningTokens: reasoningTokens || undefined,
+    },
+  } as LanguageModelUsage;
+}

package/src/client/hooks.ts

@@ -0,0 +1,343 @@
+'use client';
+
+/**
+ * @fileoverview Client-side React hooks for AI operations
+ *
+ * Browser-safe React hooks for vector search, chat, embeddings,
+ * and recommendation operations. All hooks use fetch() internally
+ * and do not import Node.js APIs.
+ *
+ * @module @od-oneapp/ai-platform/client/hooks
+ */
+
+import { useCallback, useState } from 'react';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result from a vector search operation. */
+export interface VectorSearchResult {
+  id: string;
+  score: number;
+  content?: string;
+  metadata?: Record<string, unknown>;
+  embedding?: number[];
+}
+
+/** Message enriched with vector context. */
+export interface VectorEnrichedMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  vectorContext?: VectorSearchResult[];
+  metadata?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// useVectorSearch
+// ---------------------------------------------------------------------------
+
+/** Configuration for useVectorSearch hook. */
+export interface UseVectorSearchConfig {
+  apiRoute?: string;
+  apiKey?: string;
+  timeout?: number;
+}
+
+/**
+ * React hook for vector search operations.
+ *
+ * @example
+ * ```tsx
+ * const { search, results, isLoading } = useVectorSearch({ apiRoute: '/api/vector/search' });
+ * const hits = await search('query', { topK: 5 });
+ * ```
+ */
+export function useVectorSearch(config: UseVectorSearchConfig) {
+  const [isLoading, setIsLoading] = useState(false);
+  const [results, setResults] = useState<VectorSearchResult[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  const search = useCallback(
+    async (
+      query: string,
+      options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+        threshold?: number;
+      },
+    ): Promise<VectorSearchResult[]> => {
+      if (!query.trim()) {
+        setResults([]);
+        return [];
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const response = await fetch(config.apiRoute ?? '/api/vector/search', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+          },
+          body: JSON.stringify({ query, ...options }),
+          signal: AbortSignal.timeout(config.timeout ?? 30000),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Search failed: ${response.statusText}`);
+        }
+
+        const data = (await response.json()) as { results?: VectorSearchResult[] };
+        const searchResults = data.results ?? [];
+        setResults(searchResults);
+        return searchResults;
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+        setError(errorMessage);
+        setResults([]);
+        return [];
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [config.apiRoute, config.apiKey, config.timeout],
+  );
+
+  const clearResults = useCallback(() => {
+    setResults([]);
+    setError(null);
+  }, []);
+
+  return { search, results, isLoading, error, clearResults };
+}
+
+// ---------------------------------------------------------------------------
+// useVectorChat
+// ---------------------------------------------------------------------------
+
+/** Configuration for useVectorChat hook. */
+export interface UseVectorChatConfig {
+  apiRoute?: string;
+  chatRoute?: string;
+  apiKey?: string;
+  autoEnrichContext?: boolean;
+  contextTopK?: number;
+  similarityThreshold?: number;
+}
+
+/**
+ * React hook for vector-enhanced chat.
+ *
+ * Optionally enriches user messages with vector search context
+ * before sending to the chat API.
+ *
+ * @example
+ * ```tsx
+ * const { sendMessage, messages, isLoading } = useVectorChat({
+ *   autoEnrichContext: true,
+ *   contextTopK: 5,
+ * });
+ * ```
+ */
+export function useVectorChat(config: UseVectorChatConfig) {
+  const [messages, setMessages] = useState<VectorEnrichedMessage[]>([]);
+  const [vectorContext, setVectorContext] = useState<VectorSearchResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      const userMessage: VectorEnrichedMessage = { role: 'user', content };
+      setMessages(prev => [...prev, userMessage]);
+      setIsLoading(true);
+
+      try {
+        let contextResults: VectorSearchResult[] = [];
+
+        if (config.autoEnrichContext) {
+          const contextResponse = await fetch(config.apiRoute ?? '/api/vector/search', {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+            },
+            body: JSON.stringify({
+              query: content,
+              topK: config.contextTopK ?? 5,
+              threshold: config.similarityThreshold ?? 0.7,
+            }),
+          });
+
+          if (contextResponse.ok) {
+            const contextData = (await contextResponse.json()) as {
+              results?: VectorSearchResult[];
+            };
+            contextResults = contextData.results ?? [];
+            setVectorContext(contextResults);
+          }
+        }
+
+        const chatResponse = await fetch(config.chatRoute ?? '/api/chat', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            messages: [...messages, userMessage],
+            vectorContext: contextResults,
+          }),
+        });
+
+        if (!chatResponse.ok) {
+          throw new Error(`Chat failed: ${chatResponse.statusText}`);
+        }
+
+        const assistantMessage = (await chatResponse.json()) as VectorEnrichedMessage;
+        setMessages(prev => [...prev, assistantMessage]);
+      } catch (_error) {
+        setMessages(prev => [
+          ...prev,
+          {
+            role: 'assistant' as const,
+            content: 'Sorry, I encountered an error processing your message.',
+          },
+        ]);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [messages, config],
+  );
+
+  const clearChat = useCallback(() => {
+    setMessages([]);
+    setVectorContext([]);
+  }, []);
+
+  return {
+    messages,
+    vectorContext,
+    sendMessage,
+    isLoading,
+    clearChat,
+    hasContext: vectorContext.length > 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// useEmbeddings
+// ---------------------------------------------------------------------------
+
+/** Configuration for useEmbeddings hook. */
+export interface UseEmbeddingsConfig {
+  apiRoute?: string;
+  apiKey?: string;
+  embeddingModel?: string;
+}
+
+/**
+ * React hook for embedding generation.
+ *
+ * @example
+ * ```tsx
+ * const { generateEmbeddings, isGenerating } = useEmbeddings({});
+ * const result = await generateEmbeddings('some text');
+ * ```
+ */
+export function useEmbeddings(config: UseEmbeddingsConfig) {
+  const [isGenerating, setIsGenerating] = useState(false);
+  const [lastEmbeddings, setLastEmbeddings] = useState<number[][]>([]);
+
+  const generateEmbeddings = useCallback(
+    async (content: string | string[]) => {
+      setIsGenerating(true);
+
+      try {
+        const response = await fetch(config.apiRoute ?? '/api/vector/embed', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+          },
+          body: JSON.stringify({
+            content: Array.isArray(content) ? content : [content],
+            model: config.embeddingModel ?? 'text-embedding-3-small',
+          }),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Embedding generation failed: ${response.statusText}`);
+        }
+
+        const data = (await response.json()) as { embeddings: number[][] };
+        setLastEmbeddings(data.embeddings);
+        return data;
+      } finally {
+        setIsGenerating(false);
+      }
+    },
+    [config],
+  );
+
+  return { generateEmbeddings, isGenerating, lastEmbeddings };
+}
+
+// ---------------------------------------------------------------------------
+// useVectorRecommendations
+// ---------------------------------------------------------------------------
+
+/** Configuration for useVectorRecommendations hook. */
+export interface UseVectorRecommendationsConfig {
+  apiRoute?: string;
+  apiKey?: string;
+}
+
+/**
+ * React hook for vector-based recommendations.
+ *
+ * @example
+ * ```tsx
+ * const { getRecommendations, recommendations } = useVectorRecommendations({});
+ * await getRecommendations('item-123', { topK: 10 });
+ * ```
+ */
+export function useVectorRecommendations(config: UseVectorRecommendationsConfig) {
+  const [recommendations, setRecommendations] = useState<VectorSearchResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const getRecommendations = useCallback(
+    async (
+      targetId: string,
+      options?: { topK?: number; threshold?: number },
+    ): Promise<VectorSearchResult[]> => {
+      setIsLoading(true);
+
+      try {
+        const response = await fetch(config.apiRoute ?? '/api/vector/recommend', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+          },
+          body: JSON.stringify({ targetId, ...options }),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Recommendations failed: ${response.statusText}`);
+        }
+
+        const data = (await response.json()) as { results?: VectorSearchResult[] };
+        const results = data.results ?? [];
+        setRecommendations(results);
+        return results;
+      } catch (_error) {
+        return [];
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [config],
+  );
+
+  return { recommendations, getRecommendations, isLoading };
+}

package/src/client/index.ts

@@ -0,0 +1,36 @@
+'use client';
+
+/**
+ * @module @od-oneapp/ai-platform/client
+ * Client-side utilities -- React hooks, browser-safe helpers.
+ *
+ * All exports are browser-safe (no Node.js APIs).
+ */
+
+export {
+  useVectorSearch,
+  useVectorChat,
+  useEmbeddings,
+  useVectorRecommendations,
+  type VectorSearchResult,
+  type VectorEnrichedMessage,
+  type UseVectorSearchConfig,
+  type UseVectorChatConfig,
+  type UseEmbeddingsConfig,
+  type UseVectorRecommendationsConfig,
+} from './hooks';
+
+export { CLIENT_CONSTANTS, ClientAIError, clientUtils } from './utils';
+
+// Client-safe message utilities
+export { extractTextContent } from './message-utils';
+export { aggregateUsage } from './chat-usage';
+
+// Generative UI hook
+export { useGenerativeUI } from './use-generative-ui';
+export type {
+  UITree,
+  UIElement,
+  UseGenerativeUIConfig,
+  UseGenerativeUIReturn,
+} from '../generative-ui/types';

package/src/client/message-utils.ts

@@ -0,0 +1,29 @@
+'use client';
+
+/**
+ * @fileoverview Client-safe message utilities.
+ * Browser-safe functions for working with AI SDK UIMessage objects.
+ */
+
+import type { SDKUIMessage } from '../shared';
+
+/**
+ * Extract text content from a UIMessage's parts.
+ *
+ * @example
+ * ```tsx
+ * import { extractTextContent } from '@od-oneapp/ai-platform/client';
+ * const text = extractTextContent(message);
+ * ```
+ */
+export function extractTextContent(message: SDKUIMessage): string {
+  if (!message.parts) return '';
+
+  return message.parts
+    .filter(
+      (part): part is Extract<(typeof message.parts)[number], { type: 'text' }> =>
+        part.type === 'text' && 'text' in part,
+    )
+    .map(part => part.text)
+    .join('\n');
+}

package/src/client/use-generative-ui.ts

@@ -0,0 +1,174 @@
+'use client';
+
+/**
+ * @fileoverview useGenerativeUI - Client hook for AI-generated interfaces.
+ * @module @od-oneapp/ai-platform/client
+ *
+ * React hook that manages the lifecycle of AI-generated UI trees:
+ * - Triggers generation via API
+ * - Streams partial UI trees in real-time
+ * - Provides abort/cancel capability
+ * - Error handling with callbacks
+ *
+ * @example
+ * ```tsx
+ * import { useGenerativeUI } from '@od-oneapp/ai-platform/client';
+ *
+ * function DynamicDashboard() {
+ *   const { tree, isGenerating, generate, abort, error } = useGenerativeUI({
+ *     api: '/api/generative-ui',
+ *     onTree: (tree) => console.log('New tree:', tree),
+ *     onError: (err) => console.error('Generation failed:', err),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate('Show me a sales dashboard')}>
+ *         Generate
+ *       </button>
+ *       {isGenerating && <button onClick={abort}>Cancel</button>}
+ *       {error && <p>Error: {error.message}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { UITree, UseGenerativeUIConfig, UseGenerativeUIReturn } from '../generative-ui/types';
+
+/**
+ * React hook for generating and managing AI-driven UI trees.
+ *
+ * Streams `data-uiTreeDelta` parts from the API endpoint and maintains
+ * the latest partial tree in state. Supports abort/cancel via AbortController.
+ *
+ * @param config - Hook configuration.
+ * @returns Stateful values and generation controls.
+ */
+export function useGenerativeUI(config: UseGenerativeUIConfig = {}): UseGenerativeUIReturn {
+  const { api = '/api/generative-ui', onTree, onError, onFinish } = config;
+
+  const [tree, setTree] = useState<UITree | null>(null);
+  const [isGenerating, setIsGenerating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const latestTreeRef = useRef<UITree | null>(null);
+
+  const abort = useCallback(() => {
+    abortControllerRef.current?.abort();
+    abortControllerRef.current = null;
+    setIsGenerating(false);
+  }, []);
+
+  const generate = useCallback(
+    (prompt: string) => {
+      // Abort any in-flight request
+      abortControllerRef.current?.abort();
+
+      const controller = new AbortController();
+      abortControllerRef.current = controller;
+
+      setIsGenerating(true);
+      setError(null);
+      setTree(null);
+      latestTreeRef.current = null;
+
+      void (async () => {
+        try {
+          const response = await fetch(api, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ prompt }),
+            signal: controller.signal,
+          });
+
+          if (!response.ok) {
+            throw new Error(`Generation failed: ${response.status} ${response.statusText}`);
+          }
+
+          if (!response.body) {
+            throw new Error('No response body');
+          }
+
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          let buffer = '';
+
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            buffer += decoder.decode(value, { stream: true });
+
+            // Parse newline-delimited JSON chunks
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+
+            for (const line of lines) {
+              const trimmed = line.trim();
+              if (!trimmed) continue;
+
+              try {
+                const parsed = JSON.parse(trimmed) as { type?: string; data?: string };
+                if (parsed.type === 'data-uiTreeDelta' && parsed.data) {
+                  const partialTree = JSON.parse(parsed.data) as UITree;
+                  latestTreeRef.current = partialTree;
+                  setTree(partialTree);
+                  onTree?.(partialTree);
+                }
+              } catch {
+                // Skip malformed lines during streaming
+              }
+            }
+          }
+
+          // Process remaining buffer
+          if (buffer.trim()) {
+            try {
+              const parsed = JSON.parse(buffer.trim()) as { type?: string; data?: string };
+              if (parsed.type === 'data-uiTreeDelta' && parsed.data) {
+                const finalTree = JSON.parse(parsed.data) as UITree;
+                latestTreeRef.current = finalTree;
+                setTree(finalTree);
+                onTree?.(finalTree);
+              }
+            } catch {
+              // Final buffer wasn't valid JSON
+            }
+          }
+
+          // Call onFinish with the final tree
+          if (latestTreeRef.current) {
+            onFinish?.(latestTreeRef.current);
+          }
+        } catch (err) {
+          if (err instanceof Error && err.name === 'AbortError') {
+            return;
+          }
+          const e = err instanceof Error ? err : new Error(String(err));
+          setError(e);
+          onError?.(e);
+        } finally {
+          if (abortControllerRef.current === controller) {
+            setIsGenerating(false);
+            abortControllerRef.current = null;
+          }
+        }
+      })();
+    },
+    [api, onTree, onError, onFinish],
+  );
+
+  // Abort in-flight request on unmount to prevent state updates after unmount
+  useEffect(() => {
+    return () => {
+      abortControllerRef.current?.abort();
+      abortControllerRef.current = null;
+    };
+  }, []);
+
+  return { tree, isGenerating, generate, abort, error };
+}

package/src/client/utils.ts

@@ -0,0 +1,66 @@
+'use client';
+
+/**
+ * @fileoverview Client-side AI utilities (browser-safe)
+ *
+ * Constants, error class, and utility functions that are safe
+ * to use in browser/client components.
+ *
+ * @module @od-oneapp/ai-platform/client/utils
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default client-side constants. */
+export const CLIENT_CONSTANTS = {
+  DEFAULT_TIMEOUT: 30000,
+  MAX_RETRIES: 3,
+  DEFAULT_MODEL: 'gpt-4o',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+/** Client-safe error class for AI operations. */
+export class ClientAIError extends Error {
+  constructor(
+    message: string,
+    public code?: string,
+    public statusCode?: number,
+  ) {
+    super(message);
+    this.name = 'ClientAIError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Utility functions
+// ---------------------------------------------------------------------------
+
+/** Browser-safe utility functions. */
+export const clientUtils = {
+  /** Generate a simple UUID (browser-safe). */
+  generateId: (): string => {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+      const r = (Math.random() * 16) | 0;
+      const v = c === 'x' ? r : (r & 0x3) | 0x8;
+      return v.toString(16);
+    });
+  },
+
+  /** Simple delay utility. */
+  delay: (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms)),
+
+  /** Format bytes for display. */
+  formatBytes: (bytes: number, decimals = 2): string => {
+    if (bytes === 0) return '0 Bytes';
+    const k = 1024;
+    const dm = decimals < 0 ? 0 : decimals;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${sizes[i]}`;
+  },
+};