react-native-ai-hooks 0.2.0 → 0.4.0

package/src/ARCHITECTURE.md

@@ -0,0 +1,301 @@
+/**
+ * React Native AI Hooks - Production Architecture
+ * 
+ * This file documents the complete internal architecture of the react-native-ai-hooks
+ * library, designed for type-safety, multi-provider support, and optimal performance.
+ */
+
+/**
+ * CORE ARCHITECTURE PRINCIPLES
+ * ============================
+ * 
+ * 1. Provider Abstraction Layer
+ *    - All API calls go through ProviderFactory
+ *    - Supports Anthropic, OpenAI, Gemini with uniform interface
+ *    - Easy to extend with new providers
+ * 
+ * 2. Unified Response Normalization
+ *    - Every provider returns standardized AIResponse object
+ *    - Includes text content, raw response, and token usage
+ *    - Enables seamless provider switching
+ * 
+ * 3. Resilience & Retry Logic
+ *    - fetchWithRetry handles exponential backoff
+ *    - Automatic rate-limit (429) handling with Retry-After header
+ *    - Timeout support using AbortController
+ *    - Configurable max retries and delays
+ * 
+ * 4. Performance Optimization
+ *    - useMemo for provider config to prevent recreations
+ *    - useCallback for all callback functions
+ *    - Proper cleanup for abort controllers and timers
+ *    - Minimal re-renders through optimized dependencies
+ * 
+ * 5. Error Handling Consistency
+ *    - All hooks follow same error pattern
+ *    - Errors caught and stored in hook state
+ *    - Abort errors handled gracefully (no-op vs throw)
+ * 
+ * 
+ * PROVIDER FACTORY ARCHITECTURE
+ * =============================
+ * 
+ * The ProviderFactory class (src/utils/providerFactory.ts) is the central hub
+ * for all API communications. It:
+ * 
+ * - Normalizes request/response formats across providers
+ * - Handles authentication (API keys, OAuth for different providers)
+ * - Manages baseUrl configuration for proxy/backend integration
+ * - Applies consistent rate-limit and timeout handling
+ * 
+ * Usage:
+ *   const provider = createProvider({
+ *     provider: 'anthropic',
+ *     apiKey: 'your-key',
+ *     model: 'claude-sonnet-4-20250514',
+ *     baseUrl: 'https://your-proxy.com', // Optional
+ *     timeout: 30000,
+ *     maxRetries: 3
+ *   });
+ * 
+ *   const response = await provider.makeRequest({
+ *     prompt: 'Hello, world!',
+ *     options: { temperature: 0.7, maxTokens: 1024 },
+ *     context: [] // Previous messages
+ *   });
+ * 
+ * Response Structure:
+ *   {
+ *     text: string,           // The AI response
+ *     raw: object,            // Raw provider response
+ *     usage: {
+ *       inputTokens?: number,
+ *       outputTokens?: number,
+ *       totalTokens?: number
+ *     }
+ *   }
+ * 
+ * 
+ * FETCH WITH RETRY UTILITY
+ * ========================
+ * 
+ * The fetchWithRetry function (src/utils/fetchWithRetry.ts) wraps fetch with:
+ * 
+ * - Exponential backoff: baseDelay * (backoffMultiplier ^ attempt)
+ * - Max delay cap: prevents excessive wait times
+ * - Rate limit handling: respects Retry-After header (429 status)
+ * - Timeout support: AbortController with configurable timeout
+ * - Server error retries: automatic retry on 5xx errors
+ * 
+ * Configuration:
+ *   {
+ *     maxRetries: 3,              // Total attempts
+ *     baseDelay: 1000,            // Initial delay (ms)
+ *     maxDelay: 10000,            // Cap delay (ms)
+ *     timeout: 30000,             // Per-request timeout (ms)
+ *     backoffMultiplier: 2        // Exponential backoff factor
+ *   }
+ * 
+ * 
+ * HOOK ARCHITECTURE
+ * =================
+ * 
+ * All hooks follow a consistent pattern:
+ * 
+ * 1. useAIChat - Multi-turn conversations
+ *    - Manages message history
+ *    - Auto-includes system prompt and context
+ *    - Returns messages array + send/abort/clear functions
+ * 
+ * 2. useAIStream - Real-time token streaming
+ *    - Streams responses token-by-token
+ *    - Handles both Anthropic and OpenAI stream formats
+ *    - Supports abort and cleanup
+ * 
+ * 3. useAIForm - Form validation against AI schema
+ *    - Validates entire form at once
+ *    - Parses AI response into errors object
+ *    - Returns FormValidationResult with isValid flag
+ * 
+ * 4. useImageAnalysis - Vision model integration
+ *    - Accepts URI or base64 image
+ *    - Supports Anthropic and OpenAI vision models
+ *    - Auto-converts URIs to base64
+ * 
+ * 5. useAITranslate - Real-time translation
+ *    - Auto-detects source language
+ *    - Supports configurable target language
+ *    - Debounced auto-translate option
+ * 
+ * 6. useAISummarize - Text summarization
+ *    - Adjustable summary length (short/medium/long)
+ *    - Maintains text accuracy and fidelity
+ * 
+ * 7. useAICode - Code generation and explanation
+ *    - Generate code in any language
+ *    - Explain existing code with focus options
+ * 
+ * 
+ * TYPE DEFINITIONS
+ * ================
+ * 
+ * Core types (src/types/index.ts):
+ * 
+ * - Message: Single message object with role, content, timestamp
+ * - AIProviderType: Union of 'anthropic' | 'openai' | 'gemini'
+ * - ProviderConfig: Configuration for creating providers
+ * - AIResponse: Normalized response structure
+ * - AIRequestOptions: Parameters for AI requests
+ * - UseAI*Options: Hook configuration interfaces
+ * - UseAI*Return: Hook return type interfaces
+ * - FormValidationRequest/Result: Form validation types
+ * - *Response: Provider-specific response interfaces
+ * 
+ * 
+ * MULTI-PROVIDER SUPPORT
+ * ======================
+ * 
+ * Supported Providers:
+ * 
+ * Provider    | Base URL                           | Auth Header
+ * ------------|------------------------------------|-----------------------
+ * Anthropic   | api.anthropic.com/v1/messages      | x-api-key
+ * OpenAI      | api.openai.com/v1/chat/completions | Authorization: Bearer
+ * Gemini      | generativelanguage.googleapis.com   | Key in URL param
+ * 
+ * To use different provider:
+ *   const { sendMessage } = useAIChat({
+ *     apiKey: 'your-key',
+ *     provider: 'openai',  // ← Change provider
+ *     model: 'gpt-4'       // ← Use provider-specific model
+ *   });
+ * 
+ * Router automatically selects matching endpoint and auth method.
+ * 
+ * 
+ * SECURITY BEST PRACTICES
+ * =======================
+ * 
+ * 1. API Key Management
+ *    - Store keys in environment variables, never hardcode
+ *    - Consider passing through backend proxy (baseUrl option)
+ * 
+ * 2. Backend Proxy Pattern
+ *    - Set baseUrl to your backend endpoint
+ *    - Backend validates and authenticates requests
+ *    - Example: https://my-api.com/ai (then /v1/messages appended)
+ * 
+ * 3. Rate Limiting
+ *    - All providers have rate limits
+ *    - fetchWithRetry handles 429 responses automatically
+ *    - Implement customer-side throttling for high-volume apps
+ * 
+ * 4. Timeout Configuration
+ *    - Default: 30 seconds per request
+ *    - Adjust based on model complexity and network
+ *    - Lower timeout for real-time UX requirements
+ * 
+ * 
+ * PERFORMANCE TUNING
+ * ==================
+ * 
+ * 1. Hook Dependencies
+ *    - Memoized provider configs via useMemo
+ *    - Wrapped callbacks with useCallback
+ *    - Deps list carefully curated to prevent recreations
+ * 
+ * 2. Message Management
+ *    - Store message history in component state
+ *    - Consider pagination for large conversations
+ *    - useCallback for sendMessage prevents parent re-renders
+ * 
+ * 3. Streaming Performance
+ *    - Streaming in useAIStream is incremental
+ *    - Response state updates are batched by React
+ *    - Large responses streamed smoothly token-by-token
+ * 
+ * 4. Image Analysis
+ *    - Image conversion to base64 happens async
+ *    - Large images may take time to convert
+ *    - Consider file size limits on client-side
+ * 
+ * 
+ * EXTENDING THE LIBRARY
+ * =====================
+ * 
+ * To add a new AI provider:
+ * 
+ * 1. Add provider type to AIProviderType union
+ * 2. Implement makeXyzRequest method in ProviderFactory
+ * 3. Implement normalizeXyzResponse method
+ * 4. Add default model to DEFAULT_MODEL_MAP in hooks
+ * 5. Test with all hook types
+ * 
+ * To add a new hook:
+ * 
+ * 1. Define UseAIXyzOptions interface in types
+ * 2. Define UseAIXyzReturn interface in types
+ * 3. Create src/hooks/useAIXyz.ts
+ * 4. Use ProviderFactory for all API calls
+ * 5. Follow same error/loading/cleanup patterns
+ * 6. Export from src/index.ts
+ * 
+ * 
+ * ERROR HANDLING PATTERNS
+ * =======================
+ * 
+ * All hooks follow this pattern:
+ * 
+ *   try {
+ *     // API call via ProviderFactory
+ *   } catch (err) {
+ *     if (isMountedRef.current) {
+ *       setError(err.message);
+ *     }
+ *   } finally {
+ *     if (isMountedRef.current) {
+ *       setIsLoading(false);
+ *     }
+ *   }
+ * 
+ * The isMountedRef prevents state updates on unmounted components.
+ * 
+ * 
+ * STREAMING IMPLEMENTATION
+ * ========================
+ * 
+ * Streaming works by parsing newline-delimited JSON from response.body:
+ * 
+ * Anthropic Format:
+ *   data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"hello"}}
+ * 
+ * OpenAI Format:
+ *   data: {"choices":[{"delta":{"content":"hello"}}]}
+ * 
+ * Both formats handled in useAIStream with provider-specific parsing.
+ * 
+ * 
+ * TESTING STRATEGY
+ * ================
+ * 
+ * Unit tests should verify:
+ * - Provider factory normalization for each provider
+ * - Retry logic with mock fetch
+ * - Hook state management (loading, error, data)
+ * - Callback cleanup on unmount
+ * - JSON parsing in form validation
+ * 
+ * Integration tests should verify:
+ * - Multi-turn conversation flow
+ * - Image analysis with different mime types
+ * - Form validation with complex schemas
+ * - Streaming response handling
+ * 
+ * E2E tests should verify:
+ * - Real API calls with live keys
+ * - Provider switching credentials
+ * - Rate limit retry behavior
+ * - Error recovery workflows
+ */
+
+export {};

package/src/hooks/useAIChat.ts

@@ -1,66 +1,118 @@
-import { useState, useCallback } from 'react';
+import { useCallback, useRef, useState, useMemo } from 'react';
+import type { Message, UseAIChatOptions, UseAIChatReturn } from '../types';
+import { createProvider } from '../utils/providerFactory';
 
-interface Message {
-  role: 'user' | 'assistant';
-  content: string;
-}
-
-interface UseAIChatOptions {
-  apiKey: string;
-  provider?: 'claude' | 'openai';
-  model?: string;
-}
-
-interface UseAIChatReturn {
-  messages: Message[];
-  isLoading: boolean;
-  error: string | null;
-  sendMessage: (content: string) => Promise<void>;
-  clearMessages: () => void;
-}
+const DEFAULT_MODEL_MAP = {
+  anthropic: 'claude-sonnet-4-20250514',
+  openai: 'gpt-4',
+  gemini: 'gemini-pro',
+};
 
 export function useAIChat(options: UseAIChatOptions): UseAIChatReturn {
   const [messages, setMessages] = useState<Message[]>([]);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  const sendMessage = useCallback(async (content: string) => {
-    setIsLoading(true);
-    setError(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const isMountedRef = useRef(true);
 
-    const userMessage: Message = { role: 'user', content };
-    setMessages(prev => [...prev, userMessage]);
+  // Memoize provider config to prevent unnecessary recreations
+  const providerConfig = useMemo(
+    () => ({
+      provider: (options.provider || 'anthropic') as 'anthropic' | 'openai' | 'gemini',
+      apiKey: options.apiKey,
+      model: options.model || DEFAULT_MODEL_MAP[options.provider || 'anthropic'],
+      baseUrl: options.baseUrl,
+      timeout: options.timeout,
+      maxRetries: options.maxRetries,
+    }),
+    [options],
+  );
 
-    try {
-      const response = await fetch('https://api.anthropic.com/v1/messages', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'x-api-key': options.apiKey,
-          'anthropic-version': '2023-06-01',
-        },
-        body: JSON.stringify({
-          model: options.model || 'claude-sonnet-4-20250514',
-          max_tokens: 1024,
-          messages: [...messages, userMessage],
-        }),
-      });
+  const provider = useMemo(() => createProvider(providerConfig), [providerConfig]);
 
-      const data = await response.json();
-      const assistantMessage: Message = {
-        role: 'assistant',
-        content: data.content[0].text,
-      };
-
-      setMessages(prev => [...prev, assistantMessage]);
-    } catch (err) {
-      setError('Failed to send message');
-    } finally {
+  const abort = useCallback(() => {
+    abortControllerRef.current?.abort();
+    abortControllerRef.current = null;
+    if (isMountedRef.current) {
       setIsLoading(false);
     }
-  }, [messages, options]);
+  }, []);
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    setError(null);
+  }, []);
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      if (!content.trim()) {
+        setError('Message cannot be empty');
+        return;
+      }
+
+      setError(null);
+      const userMessage: Message = {
+        role: 'user',
+        content: content.trim(),
+        timestamp: Date.now(),
+      };
+
+      setMessages((prev: Message[]) => [...prev, userMessage]);
+      setIsLoading(true);
+
+      try {
+        const aiResponse = await provider.makeRequest({
+          prompt: content,
+          options: {
+            system: options.system,
+            temperature: options.temperature,
+            maxTokens: options.maxTokens,
+          },
+          context: messages.map((msg: Message) => ({
+            role: msg.role,
+            content: msg.content,
+          })),
+        });
+
+        const assistantMessage: Message = {
+          role: 'assistant',
+          content: aiResponse.text,
+          timestamp: Date.now(),
+        };
+
+        if (isMountedRef.current) {
+          setMessages((prev: Message[]) => [...prev, assistantMessage]);
+        }
+      } catch (err) {
+        if (isMountedRef.current) {
+          const message = err instanceof Error ? err.message : 'Failed to send message';
+          setError(message);
+        }
+      } finally {
+        if (isMountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [provider, messages, options],
+  );
 
-  const clearMessages = useCallback(() => setMessages([]), []);
+  // Cleanup on unmount
+  useState(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      abortControllerRef.current?.abort();
+    };
+  }, []);
 
-  return { messages, isLoading, error, sendMessage, clearMessages };
+  return {
+    messages,
+    isLoading,
+    error,
+    sendMessage,
+    abort,
+    clearMessages,
+  };
 }

package/src/hooks/useAICode.ts

@@ -0,0 +1,206 @@
+import { useCallback, useRef, useState } from 'react';
+
+interface UseAICodeOptions {
+  apiKey: string;
+  model?: string;
+  system?: string;
+  maxTokens?: number;
+  temperature?: number;
+  defaultLanguage?: string;
+}
+
+interface GenerateCodeInput {
+  prompt: string;
+  language?: string;
+}
+
+interface ExplainCodeInput {
+  code: string;
+  language?: string;
+  focus?: string;
+}
+
+interface UseAICodeReturn {
+  language: string;
+  generatedCode: string;
+  explanation: string;
+  isLoading: boolean;
+  error: string | null;
+  setLanguage: (language: string) => void;
+  generateCode: (input: GenerateCodeInput) => Promise<string | null>;
+  explainCode: (input: ExplainCodeInput) => Promise<string | null>;
+  clearCodeState: () => void;
+}
+
+interface ClaudeTextBlock {
+  type?: string;
+  text?: string;
+}
+
+interface ClaudeApiResult {
+  content?: ClaudeTextBlock[];
+  error?: {
+    message?: string;
+  };
+}
+
+function getClaudeTextContent(data: unknown): string {
+  const content = (data as ClaudeApiResult)?.content;
+  if (!Array.isArray(content)) {
+    return '';
+  }
+
+  return content
+    .filter(item => item?.type === 'text' && typeof item.text === 'string')
+    .map(item => item.text as string)
+    .join('\n')
+    .trim();
+}
+
+export function useAICode(options: UseAICodeOptions): UseAICodeReturn {
+  const [language, setLanguage] = useState(options.defaultLanguage || 'typescript');
+  const [generatedCode, setGeneratedCode] = useState('');
+  const [explanation, setExplanation] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const isMountedRef = useRef(true);
+
+  const clearCodeState = useCallback(() => {
+    setGeneratedCode('');
+    setExplanation('');
+    setError(null);
+  }, []);
+
+  const sendClaudeRequest = useCallback(
+    async (prompt: string) => {
+      const apiResponse = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': options.apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({
+          model: options.model || 'claude-sonnet-4-20250514',
+          max_tokens: options.maxTokens ?? 1800,
+          temperature: options.temperature ?? 0.2,
+          system:
+            options.system ||
+            'You are an expert software engineer. Produce practical, correct code and clear explanations.',
+          messages: [{ role: 'user', content: prompt }],
+        }),
+      });
+
+      const data = (await apiResponse.json()) as ClaudeApiResult;
+      if (!apiResponse.ok) {
+        throw new Error(data?.error?.message || `Claude API error: ${apiResponse.status}`);
+      }
+
+      const text = getClaudeTextContent(data);
+      if (!text) {
+        throw new Error('No content returned by Claude API.');
+      }
+
+      return text;
+    },
+    [options.apiKey, options.maxTokens, options.model, options.system, options.temperature],
+  );
+
+  const generateCode = useCallback(
+    async (input: GenerateCodeInput) => {
+      const taskPrompt = input.prompt.trim();
+      const selectedLanguage = (input.language || language).trim();
+
+      if (!taskPrompt) {
+        setError('No code generation prompt provided.');
+        return null;
+      }
+
+      if (!options.apiKey) {
+        setError('Missing Claude API key.');
+        return null;
+      }
+
+      setIsLoading(true);
+      setError(null);
+      setLanguage(selectedLanguage);
+
+      try {
+        const prompt = [
+          `Generate ${selectedLanguage} code for the following request:`,
+          taskPrompt,
+          'Return runnable code and include brief usage notes only when necessary.',
+        ].join('\n');
+
+        const result = await sendClaudeRequest(prompt);
+        setGeneratedCode(result);
+        return result;
+      } catch (err) {
+        const message = (err as Error).message || 'Failed to generate code';
+        setError(message);
+        return null;
+      } finally {
+        if (isMountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [language, options.apiKey, sendClaudeRequest],
+  );
+
+  const explainCode = useCallback(
+    async (input: ExplainCodeInput) => {
+      const code = input.code.trim();
+      const selectedLanguage = (input.language || language).trim();
+
+      if (!code) {
+        setError('No code provided for explanation.');
+        return null;
+      }
+
+      if (!options.apiKey) {
+        setError('Missing Claude API key.');
+        return null;
+      }
+
+      setIsLoading(true);
+      setError(null);
+      setLanguage(selectedLanguage);
+
+      try {
+        const prompt = [
+          `Explain the following ${selectedLanguage} code.`,
+          input.focus ? `Focus: ${input.focus}` : 'Focus: logic, structure, and potential pitfalls.',
+          'Code:',
+          code,
+        ].join('\n');
+
+        const result = await sendClaudeRequest(prompt);
+        setExplanation(result);
+        return result;
+      } catch (err) {
+        const message = (err as Error).message || 'Failed to explain code';
+        setError(message);
+        return null;
+      } finally {
+        if (isMountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [language, options.apiKey, sendClaudeRequest],
+  );
+
+  return {
+    language,
+    generatedCode,
+    explanation,
+    isLoading,
+    error,
+    setLanguage,
+    generateCode,
+    explainCode,
+    clearCodeState,
+  };
+}