react-native-ai-hooks 0.3.0 → 0.5.0

package/src/hooks/useAIForm.ts

@@ -1,57 +1,12 @@
-import { useCallback, useRef, useState } from 'react';
-
-interface UseAIFormOptions {
-  apiKey: string;
-  model?: string;
-  system?: string;
-  maxTokens?: number;
-  temperature?: number;
-}
-
-interface ValidateFieldInput {
-  fieldName: string;
-  value: string;
-  formData?: Record<string, string>;
-  validationRule?: string;
-}
-
-interface AutocompleteFieldInput {
-  fieldName: string;
-  value: string;
-  formData?: Record<string, string>;
-  instruction?: string;
-  maxSuggestions?: number;
-}
-
-interface AIFieldValidation {
-  isValid: boolean;
-  feedback: string;
-  suggestion?: string;
-}
+import { useCallback, useRef, useState, useMemo, useEffect } from 'react';
+import type { UseAIFormOptions, UseAIFormReturn, FormValidationRequest, FormValidationResult } from '../types';
+import { createProvider } from '../utils/providerFactory';
 
-interface UseAIFormReturn {
-  validations: Record<string, AIFieldValidation>;
-  autocomplete: Record<string, string[]>;
-  isLoading: boolean;
-  error: string | null;
-  validateField: (input: ValidateFieldInput) => Promise<AIFieldValidation | null>;
-  autocompleteField: (input: AutocompleteFieldInput) => Promise<string[] | null>;
-  clearFormAI: () => void;
-  cancelRequests: () => void;
-}
-
-function extractTextContent(data: unknown): string {
-  const content = (data as { content?: Array<{ type?: string; text?: string }> })?.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();
-}
+const DEFAULT_MODEL_MAP = {
+  anthropic: 'claude-sonnet-4-20250514',
+  openai: 'gpt-4',
+  gemini: 'gemini-pro',
+};
 
 function parseJsonFromText<T>(text: string): T {
   const trimmed = text.trim();
@@ -60,186 +15,121 @@ function parseJsonFromText<T>(text: string): T {
   return JSON.parse(candidate) as T;
 }
 
+/**
+ * Validates form payloads using an AI model and returns structured validation errors.
+ *
+ * @param options Validation configuration including provider, API key, model, transport
+ * settings, and generation controls used when composing validation prompts.
+ * @returns Form validation state containing the latest validation result,
+ * loading/error indicators, and actions to validate data or clear prior results.
+ */
 export function useAIForm(options: UseAIFormOptions): UseAIFormReturn {
-  const [validations, setValidations] = useState<Record<string, AIFieldValidation>>({});
-  const [autocomplete, setAutocomplete] = useState<Record<string, string[]>>({});
-  const [error, setError] = useState<string | null>(null);
+  const [validationResult, setValidationResult] = useState<FormValidationResult | null>(null);
   const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
 
-  const validationAbortRef = useRef<AbortController | null>(null);
-  const autocompleteAbortRef = useRef<AbortController | null>(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const isMountedRef = useRef(true);
+
+  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],
+  );
 
-  const cancelRequests = useCallback(() => {
-    validationAbortRef.current?.abort();
-    autocompleteAbortRef.current?.abort();
-    validationAbortRef.current = null;
-    autocompleteAbortRef.current = null;
-    setIsLoading(false);
-  }, []);
+  const provider = useMemo(() => createProvider(providerConfig), [providerConfig]);
 
-  const clearFormAI = useCallback(() => {
-    setValidations({});
-    setAutocomplete({});
+  const clearValidation = useCallback(() => {
+    setValidationResult(null);
     setError(null);
   }, []);
 
-  const sendClaudeRequest = useCallback(
-    async (prompt: string, signal: AbortSignal) => {
-      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: options.maxTokens ?? 800,
-          temperature: options.temperature ?? 0.2,
-          system:
-            options.system ||
-            'You are a form assistant. Return precise, concise, JSON-only responses with no markdown unless explicitly requested.',
-          messages: [{ role: 'user', content: prompt }],
-        }),
-        signal,
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(errorText || `Claude API error: ${response.status}`);
+  const validateForm = useCallback(
+    async (input: FormValidationRequest): Promise<FormValidationResult | null> => {
+      if (!input.formData || Object.keys(input.formData).length === 0) {
+        setError('Form data is empty');
+        return null;
       }
 
-      return response.json();
-    },
-    [options],
-  );
-
-  const validateField = useCallback(
-    async (input: ValidateFieldInput) => {
-      validationAbortRef.current?.abort();
-      const controller = new AbortController();
-      validationAbortRef.current = controller;
-
-      setIsLoading(true);
-      setError(null);
-
-      try {
-        const prompt = [
-          'Validate this single form field and return JSON only.',
-          'Schema: {"isValid": boolean, "feedback": string, "suggestion": string}',
-          `Field: ${input.fieldName}`,
-          `Value: ${input.value}`,
-          `Rule: ${input.validationRule || 'Use common real-world validation best practices.'}`,
-          `Other form values: ${JSON.stringify(input.formData || {})}`,
-          'If valid, feedback should be short and positive. suggestion can be empty string.',
-        ].join('\n');
-
-        const data = await sendClaudeRequest(prompt, controller.signal);
-        const text = extractTextContent(data);
-
-        if (!text) {
-          throw new Error('No validation content returned from Claude API.');
-        }
-
-        const parsed = parseJsonFromText<AIFieldValidation>(text);
-
-        if (typeof parsed?.isValid !== 'boolean' || typeof parsed?.feedback !== 'string') {
-          throw new Error('Invalid validation response format returned by Claude API.');
-        }
-
-        const result: AIFieldValidation = {
-          isValid: parsed.isValid,
-          feedback: parsed.feedback,
-          suggestion: typeof parsed.suggestion === 'string' ? parsed.suggestion : undefined,
-        };
-
-        setValidations(prev => ({
-          ...prev,
-          [input.fieldName]: result,
-        }));
-
-        return result;
-      } catch (err) {
-        if ((err as Error).name === 'AbortError') {
-          return null;
-        }
-
-        const message = (err as Error).message || 'Failed to validate field';
-        setError(message);
+      if (!options.apiKey) {
+        setError('Missing API key');
         return null;
-      } finally {
-        validationAbortRef.current = null;
-        setIsLoading(false);
       }
-    },
-    [sendClaudeRequest],
-  );
-
-  const autocompleteField = useCallback(
-    async (input: AutocompleteFieldInput) => {
-      autocompleteAbortRef.current?.abort();
-      const controller = new AbortController();
-      autocompleteAbortRef.current = controller;
 
-      setIsLoading(true);
       setError(null);
+      setIsLoading(true);
 
       try {
+        const schemaText = input.validationSchema ? JSON.stringify(input.validationSchema) : 'Use common validation best practices';
         const prompt = [
-          'Generate form autocomplete suggestions for one field and return JSON only.',
-          'Schema: {"suggestions": string[]}',
-          `Field: ${input.fieldName}`,
-          `Current value: ${input.value}`,
-          `Max suggestions: ${input.maxSuggestions ?? 5}`,
-          `Instruction: ${input.instruction || 'Provide useful, natural completions for this field value.'}`,
-          `Other form values: ${JSON.stringify(input.formData || {})}`,
-          'Suggestions should be unique, concise, and ordered best-first.',
+          'Validate the following form data.',
+          'Return ONLY valid JSON with this schema: {"errors": {"fieldName": "errorMessage"}}',
+          'If all fields are valid, return: {"errors": {}}',
+          `Validation schema: ${schemaText}`,
+          `Custom instructions: ${input.customInstructions || 'None'}`,
+          'Form data:',
+          JSON.stringify(input.formData),
         ].join('\n');
 
-        const data = await sendClaudeRequest(prompt, controller.signal);
-        const text = extractTextContent(data);
+        const aiResponse = await provider.makeRequest({
+          prompt,
+          options: {
+            system:
+              options.system ||
+              'You are a form validation assistant. Return ONLY valid JSON responses, no markdown or explanations.',
+            temperature: options.temperature ?? 0.2,
+            maxTokens: options.maxTokens ?? 800,
+          },
+        });
+
+        const parsed = parseJsonFromText<{ errors?: Record<string, string> }>(aiResponse.text);
+        const errors = parsed?.errors || {};
+        const isValid = Object.keys(errors).length === 0;
+
+        const result: FormValidationResult = {
+          isValid,
+          errors,
+          raw: parsed,
+        };
 
-        if (!text) {
-          throw new Error('No autocomplete content returned from Claude API.');
+        if (isMountedRef.current) {
+          setValidationResult(result);
         }
-
-        const parsed = parseJsonFromText<{ suggestions?: unknown }>(text);
-        const suggestions = Array.isArray(parsed?.suggestions)
-          ? parsed.suggestions.filter((item): item is string => typeof item === 'string')
-          : [];
-
-        const limitedSuggestions = suggestions.slice(0, input.maxSuggestions ?? 5);
-
-        setAutocomplete(prev => ({
-          ...prev,
-          [input.fieldName]: limitedSuggestions,
-        }));
-
-        return limitedSuggestions;
+        return result;
       } catch (err) {
-        if ((err as Error).name === 'AbortError') {
-          return null;
+        if (isMountedRef.current) {
+          const message = err instanceof Error ? err.message : 'Failed to validate form';
+          setError(message);
         }
-
-        const message = (err as Error).message || 'Failed to generate autocomplete suggestions';
-        setError(message);
         return null;
       } finally {
-        autocompleteAbortRef.current = null;
-        setIsLoading(false);
+        if (isMountedRef.current) {
+          setIsLoading(false);
+        }
       }
     },
-    [sendClaudeRequest],
+    [provider, options],
   );
 
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      abortControllerRef.current?.abort();
+    };
+  }, []);
+
   return {
-    validations,
-    autocomplete,
+    validationResult,
     isLoading,
     error,
-    validateField,
-    autocompleteField,
-    clearFormAI,
-    cancelRequests,
+    validateForm,
+    clearValidation,
   };
 }

package/src/hooks/useAIStream.ts

@@ -1,32 +1,46 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-interface UseAIStreamOptions {
-  apiKey: string;
-  model?: string;
-  system?: string;
-  maxTokens?: number;
-  temperature?: number;
-}
-
-interface UseAIStreamReturn {
-  response: string;
-  isLoading: boolean;
-  error: string | null;
-  streamResponse: (prompt: string) => Promise<void>;
-  abortStream: () => void;
-  clearResponse: () => void;
-}
-
+import { useCallback, useEffect, useRef, useState, useMemo } from 'react';
+import type { UseAIStreamOptions, UseAIStreamReturn } from '../types';
+import { fetchWithRetry } from '../utils/fetchWithRetry';
+
+const DEFAULT_MODEL_MAP = {
+  anthropic: 'claude-sonnet-4-20250514',
+  openai: 'gpt-4',
+  gemini: 'gemini-pro',
+};
+
+/**
+ * Streams AI responses token-by-token and exposes incremental output state.
+ *
+ * @param options Stream configuration including provider, API key, model, base URL,
+ * timeout/retry controls, and generation settings such as system prompt, temperature,
+ * and max tokens.
+ * @returns Stream state with accumulated response text, loading/error flags, and actions
+ * to start streaming, abort an in-flight stream, or clear the current response.
+ */
 export function useAIStream(options: UseAIStreamOptions): UseAIStreamReturn {
   const [response, setResponse] = useState('');
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
+
   const abortControllerRef = useRef<AbortController | null>(null);
+  const isMountedRef = useRef(true);
+
+  const providerConfig = useMemo(
+    () => ({
+      provider: options.provider || 'anthropic',
+      apiKey: options.apiKey,
+      model: options.model || DEFAULT_MODEL_MAP[options.provider || 'anthropic'],
+      baseUrl: options.baseUrl,
+    }),
+    [options],
+  );
 
-  const abortStream = useCallback(() => {
+  const abort = useCallback(() => {
     abortControllerRef.current?.abort();
     abortControllerRef.current = null;
-    setIsLoading(false);
+    if (isMountedRef.current) {
+      setIsLoading(false);
+    }
   }, []);
 
   const clearResponse = useCallback(() => {
@@ -36,7 +50,7 @@ export function useAIStream(options: UseAIStreamOptions): UseAIStreamReturn {
 
   const streamResponse = useCallback(
     async (prompt: string) => {
-      abortStream();
+      abort();
       setResponse('');
       setError(null);
       setIsLoading(true);
@@ -45,43 +59,71 @@ export function useAIStream(options: UseAIStreamOptions): UseAIStreamReturn {
       abortControllerRef.current = controller;
 
       try {
-        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',
+        let url = '';
+        let body: Record<string, unknown> = {};
+        let headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+        };
+
+        if (providerConfig.provider === 'anthropic') {
+          url = `${providerConfig.baseUrl || 'https://api.anthropic.com'}/v1/messages`;
+          headers['x-api-key'] = options.apiKey;
+          headers['anthropic-version'] = '2023-06-01';
+          body = {
+            model: providerConfig.model,
+            max_tokens: options.maxTokens ?? 1024,
+            temperature: options.temperature ?? 0.7,
+            stream: true,
+            system: options.system,
+            messages: [{ role: 'user', content: prompt }],
+          };
+        } else if (providerConfig.provider === 'openai') {
+          url = `${providerConfig.baseUrl || 'https://api.openai.com'}/v1/chat/completions`;
+          headers.Authorization = `Bearer ${options.apiKey}`;
+          body = {
+            model: providerConfig.model,
             max_tokens: options.maxTokens ?? 1024,
             temperature: options.temperature ?? 0.7,
             stream: true,
             system: options.system,
             messages: [{ role: 'user', content: prompt }],
-          }),
-          signal: controller.signal,
-        });
+          };
+        } else {
+          throw new Error(`Streaming not supported for provider: ${providerConfig.provider}`);
+        }
+
+        const apiResponse = await fetchWithRetry(
+          url,
+          {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+          },
+          {
+            timeout: options.timeout || 30000,
+            maxRetries: options.maxRetries ?? 3,
+          },
+        );
 
         if (!apiResponse.ok) {
           const errorText = await apiResponse.text();
-          throw new Error(errorText || `Claude API error: ${apiResponse.status}`);
+          throw new Error(errorText || `API error: ${apiResponse.status}`);
         }
 
         if (!apiResponse.body) {
-          throw new Error('Streaming is not supported in this environment.');
+          throw new Error('Streaming not supported in this environment');
         }
 
         const reader = apiResponse.body.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
 
+        // eslint-disable-next-line no-constant-condition
         while (true) {
           const { done, value } = await reader.read();
 
-          if (done) {
-            break;
-          }
+          if (done) break;
 
           buffer += decoder.decode(value, { stream: true });
           const lines = buffer.split('\n');
@@ -89,44 +131,58 @@ export function useAIStream(options: UseAIStreamOptions): UseAIStreamReturn {
 
           for (const rawLine of lines) {
             const line = rawLine.trim();
-
-            if (!line || !line.startsWith('data:')) {
-              continue;
-            }
+            if (!line || !line.startsWith('data:')) continue;
 
             const payload = line.slice(5).trim();
-            if (!payload || payload === '[DONE]') {
-              continue;
-            }
+            if (!payload || payload === '[DONE]') continue;
 
             try {
               const parsed = JSON.parse(payload);
-              if (
-                parsed.type === 'content_block_delta' &&
-                parsed.delta?.type === 'text_delta' &&
-                typeof parsed.delta.text === 'string'
-              ) {
-                setResponse(prev => prev + parsed.delta.text);
+
+              if (providerConfig.provider === 'anthropic') {
+                if (
+                  parsed.type === 'content_block_delta' &&
+                  parsed.delta?.type === 'text_delta' &&
+                  typeof parsed.delta.text === 'string'
+                ) {
+                  if (isMountedRef.current) {
+                    setResponse((prev: string) => prev + parsed.delta.text);
+                  }
+                }
+              } else if (providerConfig.provider === 'openai') {
+                if (
+                  parsed.choices?.[0]?.delta?.content &&
+                  typeof parsed.choices[0].delta.content === 'string'
+                ) {
+                  if (isMountedRef.current) {
+                    setResponse((prev: string) => prev + parsed.choices[0].delta.content);
+                  }
+                }
               }
             } catch {
-              // Ignore malformed stream chunks and keep consuming the stream.
+              // Ignore malformed stream chunks
             }
           }
         }
       } catch (err) {
-        if ((err as Error).name !== 'AbortError') {
-          setError((err as Error).message || 'Failed to stream response');
+        if (isMountedRef.current && (err as Error).name !== 'AbortError') {
+          const message = err instanceof Error ? err.message : 'Failed to stream response';
+          setError(message);
         }
       } finally {
         abortControllerRef.current = null;
-        setIsLoading(false);
+        if (isMountedRef.current) {
+          setIsLoading(false);
+        }
       }
     },
-    [abortStream, options],
+    [abort, options, providerConfig],
   );
 
   useEffect(() => {
+    isMountedRef.current = true;
     return () => {
+      isMountedRef.current = false;
       abortControllerRef.current?.abort();
     };
   }, []);
@@ -136,7 +192,7 @@ export function useAIStream(options: UseAIStreamOptions): UseAIStreamReturn {
     isLoading,
     error,
     streamResponse,
-    abortStream,
+    abort,
     clearResponse,
   };
 }

package/src/hooks/useAISummarize.ts

@@ -63,6 +63,14 @@ function lengthInstruction(length: SummaryLength): string {
   return 'Produce a balanced summary in 1-2 paragraphs plus a short bullet list of key takeaways.';
 }
 
+/**
+ * Summarizes long-form text with selectable output length (short, medium, or long).
+ *
+ * @param options Summarization configuration including API key, model/system behavior,
+ * token/temperature controls, and default summary length.
+ * @returns Summarization state with current summary text, selected length,
+ * loading/error indicators, and actions to set length, generate summaries, or clear output.
+ */
 export function useAISummarize(options: UseAISummarizeOptions): UseAISummarizeReturn {
   const [summary, setSummary] = useState('');
   const [length, setLength] = useState<SummaryLength>(options.defaultLength || 'medium');

package/src/hooks/useAITranslate.ts

@@ -62,6 +62,15 @@ function parseJsonFromText<T>(text: string): T {
   return JSON.parse(candidate) as T;
 }
 
+/**
+ * Translates source text into a target language with optional automatic debounced translation.
+ *
+ * @param options Translation configuration including API key, model/system settings,
+ * temperature/token controls, initial target language, and auto-translate behavior.
+ * @returns Translation state with source/translated text, detected source language,
+ * target language, status/error flags, and actions to update text/language, translate,
+ * or reset translation state.
+ */
 export function useAITranslate(options: UseAITranslateOptions): UseAITranslateReturn {
   const [sourceText, setSourceText] = useState('');
   const [translatedText, setTranslatedText] = useState('');

package/src/hooks/useAIVoice.ts

@@ -58,6 +58,14 @@ function getClaudeTextContent(data: unknown): string {
 		.trim();
 }
 
+/**
+ * Handles speech-to-text capture and optional AI response generation from transcribed speech.
+ *
+ * @param options Voice hook configuration including API key, model settings, recognition
+ * language, and whether transcription should be auto-sent after recording stops.
+ * @returns Voice interaction state with transcription/response values, recording and loading
+ * indicators, error state, and actions to start/stop recording, send transcription, and clear state.
+ */
 export function useAIVoice(options: UseAIVoiceOptions): UseAIVoiceReturn {
 	const [transcription, setTranscription] = useState('');
 	const [response, setResponse] = useState('');