@umituz/react-native-ai-gemini-provider 1.14.28 → 1.14.30

package/src/infrastructure/utils/README.md

@@ -0,0 +1,289 @@
+# Utils
+
+Utility functions and tools for Gemini provider. Handles error management, performance monitoring, data transformation, model validation, image preparation, and input building.
+
+## 📍 Import Path
+
+```
+import {
+  // Error handling
+  mapGeminiError,
+  isGeminiErrorRetryable,
+  categorizeGeminiError,
+  createGeminiError,
+
+  // Model validation
+  isValidModel,
+  validateModel,
+  getSafeModel,
+  getModelCategory,
+  getAllValidModels,
+
+  // Performance
+  measureAsync,
+  measureSync,
+  debounce,
+  throttle,
+  performanceTracker,
+
+  // Data transformation
+  extractBase64Data,
+  extractTextFromResponse,
+
+  // Image preparation
+  prepareImageFromUri,
+  prepareImage,
+  isValidBase64,
+
+  // Input builders
+  buildUpscaleInput,
+  buildPhotoRestoreInput,
+  buildRemoveBackgroundInput,
+  buildReplaceBackgroundInput
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use utility functions for common operations across the provider. Provides error handling, validation, performance monitoring, and data transformation capabilities.
+
+**When to use:**
+- Validate model IDs
+- Handle API errors
+- Monitor performance
+- Transform data formats
+- Prepare images for processing
+- Build complex inputs
+- Measure operation duration
+- Debounce/throttle functions
+
+## 📌 Strategy
+
+Utilities provide reusable, composable functions. This system:
+- Separates concerns from business logic
+- Provides consistent error handling
+- Enables performance monitoring
+- Simplifies data transformations
+- Validates inputs centrally
+- Builds complex inputs from simple data
+
+**Key Decision**: Use utility functions for cross-cutting concerns. Keep services focused on business logic, use utils for operational tasks.
+
+## ⚠️ Rules
+
+### Error Handling Rules
+- **MUST** catch and categorize all API errors
+- **SHOULD** use typed GeminiError instances
+- **MUST** check retryable status before retrying
+- **SHOULD** log errors appropriately
+- **MUST NOT** expose sensitive data in errors
+
+### Model Validation Rules
+- **MUST** validate model IDs before use
+- **SHOULD** use safe fallbacks for invalid models
+- **MUST** check model category for features
+- **SHOULD** validate early in request flow
+- **MUST NOT** allow arbitrary model IDs
+
+### Performance Rules
+- **SHOULD** measure critical operations
+- **MUST** track performance metrics
+- **SHOULD** use debounce/throttle for frequent calls
+- **MUST NOT** impact performance with monitoring
+- **SHOULD** aggregate metrics over time
+
+### Data Transformation Rules
+- **MUST** validate input data format
+- **SHOULD** handle edge cases (null, undefined)
+- **MUST** sanitize sensitive information
+- **SHOULD** preserve data integrity
+- **MUST** handle transformation errors
+
+### Image Preparation Rules
+- **MUST** validate base64 format
+- **SHOULD** handle different image formats
+- **MUST** extract MIME type correctly
+- **SHOULD** handle large images efficiently
+- **MUST** validate image data
+
+## 🤖 AI Agent Guidelines
+
+### When Handling Errors
+1. **CATCH** errors from API calls
+2. **MAP** to GeminiError using mapGeminiError()
+3. **CHECK** if retryable using isGeminiErrorRetryable()
+4. **CATEGORIZE** error type
+5. **HANDLE** appropriately (retry or fail)
+
+### When Validating Models
+1. **CHECK** model validity with isValidModel()
+2. **GET** safe model with getSafeModel()
+3. **DETERMINE** model category
+4. **VALIDATE** category supports feature
+5. **USE** validated model in requests
+
+### When Measuring Performance
+1. **WRAP** operation with measureAsync()
+2. **RECORD** duration with performanceTracker
+3. **ANALYZE** metrics periodically
+4. **IDENTIFY** slow operations
+5. **OPTIMIZE** based on data
+
+### When Preparing Images
+1. **VALIDATE** image source (URI or base64)
+2. **EXTRACT** base64 data if needed
+3. **DETERMINE** MIME type
+4. **PREPARE** image object
+5. **HANDLE** preparation errors
+
+### Code Style Rules
+- **USE** appropriate utility for each task
+- **VALIDATE** inputs early
+- **HANDLE** all error cases
+- **LOG** important operations
+- **COMMENT** complex transformations
+
+## 📦 Available Utilities
+
+### Error Management
+
+**Refer to**: [`ERROR_UTILITIES.md`](./ERROR_UTILITIES.md)
+
+**Functions:**
+- `mapGeminiError(error)` - Map error to GeminiError
+- `isGeminiErrorRetryable(error)` - Check if error is retryable
+- `categorizeGeminiError(error)` - Categorize error type
+- `createGeminiError(error)` - Create GeminiError instance
+
+### Model Validation
+
+**Refer to**: [`MODEL_VALIDATION_UTILS.md`](./MODEL_VALIDATION_UTILS.md)
+
+**Functions:**
+- `isValidModel(model)` - Check if model ID is valid
+- `validateModel(model)` - Validate or throw error
+- `getSafeModel(model, defaultType)` - Get safe model with fallback
+- `getModelCategory(model)` - Get model category
+- `getAllValidModels()` - Get all valid model IDs
+
+### Performance Tools
+
+**Refer to**: [`PERFORMANCE_UTILS.md`](./PERFORMANCE_UTILS.md)
+
+**Functions:**
+- `measureAsync(operation, metadata?)` - Measure async operation
+- `measureSync(operation, metadata?)` - Measure sync operation
+- `debounce(func, wait)` - Create debounced function
+- `throttle(func, limit)` - Create throttled function
+
+**Classes:**
+- `PerformanceTimer` - Timer for operations
+- `performanceTracker` - Global performance tracker
+
+### Data Transformation
+
+**Refer to**: [`DATA_TRANSFORMER_UTILS.md`](./DATA_TRANSFORMER_UTILS.md)
+
+**Functions:**
+- `extractBase64Data(base64)` - Extract base64 from data URL
+- `extractTextFromResponse(response)` - Extract text from Gemini response
+
+### Image Preparation
+
+**Refer to**: [`IMAGE_PREPARER_UTILS.md`](./IMAGE_PREPARER_UTILS.md)
+
+**Functions:**
+- `prepareImageFromUri(uri)` - Prepare image from URI
+- `prepareImage(base64, mimeType)` - Prepare image from base64
+- `isValidBase64(base64)` - Validate base64 format
+
+### Input Builders
+
+**Refer to**: [`INPUT_BUILDERS.md`](./INPUT_BUILDERS.md)
+
+**Single Image Features:**
+- `buildUpscaleInput(base64, options?)` - Build upscale input
+- `buildPhotoRestoreInput(base64, options?)` - Build photo restore input
+- `buildRemoveBackgroundInput(base64, options?)` - Build remove background input
+- `buildReplaceBackgroundInput(base64, options)` - Build replace background input
+
+**Dual Image Features:**
+- `buildFaceSwapInput(sourceBase64, targetBase64, options?)` - Build face swap input
+
+**Video Features:**
+- `buildAIHugInput(base64, options?)` - Build AI hug input
+- `buildAIKissInput(base64, options?)` - Build AI kiss input
+- `buildVideoFromDualImagesInput(base64a, base64b, options?)` - Build dual image video input
+
+## 🔗 Related Modules
+
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Services**: [`../services/README.md`](../services/README.md)
+- **Domain Types**: [`../../domain/README.md`](../../domain/README.md)
+
+## 📋 Error Categories
+
+### Retryable Errors
+- `QUOTA_EXCEEDED` - API quota exceeded
+- `RATE_LIMIT` - Rate limit hit
+- `NETWORK` - Network error
+- `TIMEOUT` - Request timeout
+- `SERVER` - Server error (5xx)
+
+### Non-Retryable Errors
+- `AUTHENTICATION` - Invalid credentials
+- `SAFETY` - Safety filter triggered
+- `MODEL_NOT_FOUND` - Invalid model
+- `VALIDATION` - Invalid request
+- `UNKNOWN` - Unknown error
+
+## 🎓 Usage Patterns
+
+### Error Handling Pattern
+1. Catch API error
+2. Map to GeminiError
+3. Check if retryable
+4. Retry or fail appropriately
+5. Log error for debugging
+
+### Model Validation Pattern
+1. Get user input for model
+2. Validate with isValidModel()
+3. Get safe model with fallback
+4. Check model category
+5. Use validated model
+
+### Performance Measurement Pattern
+1. Wrap operation with measureAsync()
+2. Record duration to performanceTracker
+3. Analyze metrics periodically
+4. Identify optimization opportunities
+5. Iterate on improvements
+
+### Image Processing Pattern
+1. Validate image source
+2. Prepare image with utilities
+3. Build input for feature
+4. Send to image service
+5. Handle result/errors
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Skip model validation
+- Ignore error types
+- Measure too frequently (performance impact)
+- Mutate input data
+- Assume all models support all features
+
+### Do
+- Always validate model IDs
+- Handle all error categories
+- Use debounce/throttle for frequent operations
+- Keep transformations pure
+- Check model capabilities
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/presentation/README.md

@@ -0,0 +1,187 @@
+# Presentation Layer
+
+Bridge between UI layer and service layer. Contains React components and hooks for UI integration.
+
+## 📍 Import Path
+
+```
+import { useGemini } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use presentation layer to integrate AI functionality into React Native UI. Provides React hooks and state management.
+
+**When to use:**
+- Add AI features to React Native components
+- Manage AI operation state in UI
+- Handle loading and error states
+- Create AI-powered user interfaces
+- Build chat interfaces and forms
+
+## 📌 Strategy
+
+Presentation layer abstracts service complexity. This layer:
+- Provides React hooks for AI operations
+- Manages loading, error, and result states
+- Handles component lifecycle
+- Simplifies UI integration
+- Enables reactive AI interactions
+
+**Key Decision**: Use hooks for React Native UI components. They provide clean, declarative integration with AI services.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider before using hooks
+- **SHOULD** use hooks only in React components
+- **MUST** handle loading and error states
+- **SHOULD** implement cleanup on unmount
+- **MUST NOT** use hooks outside React functions
+
+### State Management Rules
+- **SHOULD** display loading indicators
+- **MUST** handle and display errors
+- **SHOULD** implement success callbacks
+- **MUST** reset state when appropriate
+- **SHOULD NOT** ignore state changes
+
+### UI Integration Rules
+- **MUST** provide user feedback during operations
+- **SHOULD** disable controls during loading
+- **MUST** handle all error states gracefully
+- **SHOULD** update UI progressively
+- **MUST NOT** block UI thread
+
+### Performance Rules
+- **SHOULD** implement cleanup on unmount
+- **MUST** cancel operations on unmount
+- **SHOULD** use memoization where appropriate
+- **MUST NOT** create memory leaks
+- **SHOULD** optimize re-renders
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Presentation Layer
+1. **READ** existing hooks first
+2. **UNDERSTAND** React patterns
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** documentation
+
+### When Adding New Hooks
+1. **CHECK** if similar hook exists
+2. **FOLLOW** existing hook patterns
+3. **USE** established state management
+4. **DOCUMENT** in hook documentation
+5. **ADD** examples to tests (not docs)
+
+### When Creating Components
+1. **FOLLOW** React best practices
+2. **USE** hooks for state management
+3. **HANDLE** all edge cases
+4. **PROVIDE** TypeScript types
+5. **TEST** component behavior
+
+### Code Style Rules
+- **FOLLOW** React hooks rules
+- **USE** useMemo/useCallback for optimization
+- **VALIDATE** props
+- **HANDLE** errors gracefully
+- **COMMENT** complex logic only
+
+## 📦 Available Modules
+
+### React Hooks
+
+**useGemini**: Main hook for AI text generation
+
+**Refer to**: [`hooks/README.md`](./hooks/README.md)
+
+**Files:**
+- [`hooks/use-gemini.ts`](./hooks/use-gemini.ts) - Hook implementation
+- [`hooks/USE_GEMINI_HOOK.md`](./hooks/USE_GEMINI_HOOK.md) - Detailed documentation
+
+## 🔗 Related Modules
+
+- **Services**: [`../infrastructure/services/README.md`](../infrastructure/services/README.md)
+- **Domain Types**: [`../domain/README.md`](../domain/README.md)
+- **Providers**: [`../providers/README.md`](../providers/README.md)
+
+## 📋 Hook Features
+
+### State Management
+- `result`: Generated content
+- `isGenerating`: Loading state
+- `error`: Error message
+- `reset`: Clear all state
+
+### Methods
+- `generate(prompt)`: Generate text from prompt
+- `generateWithImage(prompt, image, mimeType)`: Generate with image context
+- `reset()`: Clear all state
+
+### Configuration
+- `model`: Model ID to use
+- `generationConfig`: Generation parameters
+- `onSuccess`: Success callback
+- `onError`: Error callback
+
+## 🎓 Usage Patterns
+
+### Basic Integration
+1. Import hook in component
+2. Call `useGemini()` hook
+3. Use returned methods and state
+4. Display loading, error, and result states
+5. Handle user interactions
+
+### Chat Interface
+1. Use hook for AI responses
+2. Maintain messages array in state
+3. Call `generate()` on user input
+4. Update messages with result
+5. Display conversation
+
+### Form Integration
+1. Integrate hook with form
+2. Call generation on form submit
+3. Disable form during generation
+4. Display errors appropriately
+5. Handle success/failure
+
+### Image Analysis
+1. Use `generateWithImage()` method
+2. Provide base64 image data
+3. Handle loading and result states
+4. Display analysis result
+5. Handle errors
+
+### State Resetting
+1. Use `reset()` to clear state
+2. Implement cleanup on unmount
+3. Reset before new operations
+4. Clear previous results
+5. Handle user actions
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use hooks outside React functions
+- Forget to handle loading states
+- Ignore error states
+- Skip cleanup on unmount
+- Block UI during operations
+
+### Do
+- Always handle loading and error states
+- Provide user feedback
+- Implement cleanup
+- Disable controls during loading
+- Reset state appropriately
+- Handle all edge cases
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)

package/src/presentation/hooks/README.md

@@ -0,0 +1,188 @@
+# React Hooks Overview
+
+React hooks for integrating Gemini AI functionality into React Native applications.
+
+## 📍 Import Path
+
+```
+import { useGemini } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use React hooks to easily integrate Gemini AI functionality into React Native components. Provides state management for AI operations.
+
+**When to use:**
+- Add text generation to components
+- Implement AI-powered features
+- Handle AI state in React components
+- Create chat interfaces
+- Build AI-assisted forms
+
+## 📌 Strategy
+
+React hooks simplify AI integration by managing state automatically. These hooks:
+- Manage loading, error, and result states
+- Provide callbacks for success/error handling
+- Support configuration and model selection
+- Handle lifecycle and cleanup
+- Enable type-safe AI operations
+
+**Key Decision**: Use hooks for React Native UI components. Use services directly for non-UI logic or complex state management needs.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider before using hooks
+- **SHOULD** use hooks only in React components
+- **MUST** handle loading and error states
+- **SHOULD** implement cleanup on unmount
+- **MUST NOT** use hooks outside React functions
+
+### State Management Rules
+- **SHOULD** display loading indicators
+- **MUST** handle errors appropriately
+- **SHOULD** provide user feedback
+- **MUST** reset state when needed
+- **SHOULD NOT** ignore error states
+
+### Configuration Rules
+- **SHOULD** select appropriate model for use case
+- **MUST** use valid model IDs
+- **SHOULD** configure generation parameters appropriately
+- **MUST** validate inputs before generation
+- **SHOULD** implement success/error callbacks
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying These Hooks
+1. **READ** the implementation file first
+2. **UNDERSTAND** React hook patterns
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar hook exists
+2. **FOLLOW** existing hook patterns
+3. **USE** established error handling
+4. **DOCUMENT** in type definitions
+5. **ADD** examples to tests (not docs)
+
+### When Fixing Bugs
+1. **REPRODUCE** bug locally first
+2. **IDENTIFY** root cause
+3. **FIX** with minimal changes
+4. **ADD** regression test
+5. **VERIFY** all tests pass
+
+### Code Style Rules
+- **FOLLOW** React hooks rules
+- **VALIDATE** inputs at hook entry
+- **HANDLE** errors gracefully
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Hooks
+
+### `useGemini(options?)`
+
+React hook for text and image-based generation with Gemini AI.
+
+**Refer to**: [`use-gemini.ts`](./use-gemini.ts)
+
+**Detailed documentation**: [`USE_GEMINI_HOOK.md`](./USE_GEMINI_HOOK.md)
+
+## 🔗 Related Modules
+
+- **Text Generation Service**: [`../../infrastructure/services/TEXT_GENERATION_SERVICE.md`](../../infrastructure/services/TEXT_GENERATION_SERVICE.md)
+- **Domain Types**: [`../../domain/entities/README.md`](../../domain/entities/README.md)
+- **Provider Initialization**: [`../../infrastructure/services/PROVIDER_INITIALIZER_SERVICE.md`](../../infrastructure/services/PROVIDER_INITIALIZER_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### UseGeminiOptions
+
+Configuration options found in: [`use-gemini.ts`](./use-gemini.ts)
+
+**Optional Fields:**
+- `model`: string - Model ID to use
+- `generationConfig`: object - Generation parameters
+- `onSuccess`: (result: string) => void - Success callback
+- `onError`: (error: string) => void - Error callback
+
+### Return Values
+
+Hook returns object with:
+- `generate`: (prompt: string) => Promise<void> - Start text generation
+- `generateWithImage`: (prompt, imageBase64, mimeType) => Promise<void> - Start image-based generation
+- `result`: string | null - Generated text
+- `isGenerating`: boolean - Loading state
+- `error`: string | null - Error message
+- `reset`: () => void - Reset all state
+
+## 🎓 Usage Patterns
+
+### Basic Text Generation
+1. Import hook in component
+2. Call `useGemini()` hook
+3. Use `generate()` with prompt
+4. Display loading, error, and result states
+5. Handle user interactions
+
+### With Model Selection
+1. Import hook
+2. Call `useGemini()` with model option
+3. Select appropriate model for use case
+4. Use hook methods normally
+5. Handle responses
+
+### With Callbacks
+1. Import hook
+2. Configure `onSuccess` callback
+3. Configure `onError` callback
+4. Use hook for generation
+5. Handle callbacks appropriately
+
+### Image Analysis
+1. Import hook
+2. Use `generateWithImage()` method
+3. Provide prompt and base64 image data
+4. Handle image analysis result
+5. Display result to user
+
+### Chat Interface
+1. Import hook
+2. Manage messages array in component state
+3. Call `generate()` for each user message
+4. Update messages on result
+5. Display conversation
+
+### State Management
+1. Import hook
+2. Use `reset()` to clear state
+3. Implement cleanup on unmount
+4. Handle loading and error states
+5. Provide user feedback
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use hooks outside React functions
+- Forget to handle loading states
+- Ignore error states
+- Skip cleanup on unmount
+- Use wrong model for use case
+
+### Do
+- Always handle loading and error states
+- Provide user feedback
+- Implement cleanup
+- Select appropriate models
+- Use callbacks for side effects
+- Reset state when needed
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)