@umituz/react-native-ai-gemini-provider 1.14.27 → 1.14.29

package/src/infrastructure/utils/PERFORMANCE_UTILS.md

@@ -0,0 +1,219 @@
+# Performance Utilities
+
+Tools for measuring, tracking, and optimizing AI operation performance.
+
+## 📍 Import Path
+
+```
+import {
+  measureAsync,
+  measureSync,
+  debounce,
+  throttle,
+  PerformanceTimer,
+  performanceTracker
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use these utilities to monitor and optimize AI operation performance. Provides timing, debouncing, throttling, and performance tracking.
+
+**When to use:**
+- Measure API call duration
+- Track performance metrics over time
+- Implement debouncing for user input
+- Throttle expensive operations
+- Monitor slow operations
+- Optimize application performance
+
+## 📌 Strategy
+
+Performance monitoring is crucial for UX. These utilities:
+- Measure operation duration accurately
+- Track metrics over time
+- Provide performance statistics
+- Enable optimization through debouncing/throttling
+- Support performance debugging
+
+**Key Decision**: Use `measureAsync()` for all critical AI operations to identify performance bottlenecks early.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** always stop PerformanceTimers
+- **SHOULD** include metadata for context
+- **MUST** track slow operations (>5s)
+- **SHOULD** clear statistics periodically
+- **MUST NOT** leak timers (always cleanup)
+
+### Measurement Rules
+- **SHOULD** measure async operations
+- **MUST** use descriptive operation names
+- **SHOULD** include relevant metadata
+- **MUST** handle errors in measured operations
+- **SHOULD NOT** measure trivial operations
+
+### Debounce/Throttle Rules
+- **SHOULD** debounce user input
+- **MUST** throttle expensive operations
+- **SHOULD** set appropriate time intervals
+- **MUST NOT** debounce/throttle everything
+- **SHOULD** consider UX impact
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying These Utilities
+1. **READ** the implementation file first
+2. **UNDERSTAND** performance implications
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar utility exists
+2. **FOLLOW** existing 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
+- **USE** precise timing measurements
+- **VALIDATE** inputs
+- **HANDLE** errors gracefully
+- **LOG** performance in development
+- **COMMENT** complex logic only
+
+## 📦 Available Utilities
+
+### `measureAsync(operation, metadata?)`
+
+Measure async operation duration.
+
+**Refer to**: [`performance.util.ts`](./performance.util.ts)
+
+### `measureSync(operation, metadata?)`
+
+Measure sync operation duration.
+
+**Refer to**: [`performance.util.ts`](./performance.util.ts)
+
+### `debounce(func, wait)`
+
+Debounce function calls.
+
+**Refer to**: [`performance.util.ts`](./performance.util.ts)
+
+### `throttle(func, limit)`
+
+Throttle function calls.
+
+**Refer to**: [`performance.util.ts`](./performance.util.ts)
+
+### `PerformanceTimer`
+
+Timer class for measuring operations.
+
+**Refer to**: [`performance.util.ts`](./performance.util.ts)
+
+### `performanceTracker`
+
+Global performance statistics tracker.
+
+**Refer to**: [`performance.util.ts`](./performance.util.ts)
+
+## 🔗 Related Modules
+
+- **Telemetry Service**: [`../services/TELEMETRY_SERVICE.md`](../services/TELEMETRY_SERVICE.md)
+- **Retry Service**: [`../services/RETRY_SERVICE.md`](../services/RETRY_SERVICE.md)
+- **Domain Types**: [`../../domain/entities/README.md`](../../domain/entities/README.md)
+
+## 📋 Configuration Reference
+
+### Performance Metrics
+
+Tracked metrics include:
+- `count`: Number of operations
+- `avg`: Average duration (ms)
+- `min`: Minimum duration (ms)
+- `max`: Maximum duration (ms)
+
+### Debounce/Throttle Timing
+
+**Typical values:**
+- User input debounce: 300-500ms
+- API call throttle: 1000-2000ms
+- Expensive operations: 2000-5000ms
+
+## 🎓 Usage Patterns
+
+### Measuring API Calls
+1. Import `measureAsync`
+2. Wrap API call in measurement
+3. Include descriptive metadata
+4. Check duration for slow operations
+5. Log or report performance issues
+
+### Performance Monitoring
+1. Create `PerformanceTimer` instance
+2. Start timer before operation
+3. Stop timer after operation (in finally block)
+4. Extract metrics from timer
+5. Handle results appropriately
+
+### Performance Statistics
+1. Record operation with `performanceTracker.record()`
+2. Get statistics with `getStats()`
+3. Analyze average/min/max durations
+4. Identify slow operations
+5. Clear stats periodically
+
+### Debouncing User Input
+1. Import `debounce` utility
+2. Wrap user input handler
+3. Set appropriate delay (300-500ms)
+4. Handle debounced calls
+5. Update UI appropriately
+
+### Throttling API Calls
+1. Import `throttle` utility
+2. Wrap expensive operation
+3. Set minimum time between calls
+4. Handle throttled execution
+5. Provide user feedback
+
+### Performance Comparison
+1. Use `measureAsync` for each operation
+2. Compare durations
+3. Identify faster/slower methods
+4. Optimize based on results
+5. Document findings
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Forget to stop timers (memory leaks)
+- Skip metadata (hard to analyze)
+- Ignore slow operations
+- Debounce/throttle everything
+- Clear statistics too frequently
+
+### Do
+- Always stop timers in finally blocks
+- Include descriptive metadata
+- Monitor for slow operations (>5s)
+- Set appropriate debounce/throttle intervals
+- Clear stats periodically (daily)
+- Consider UX when timing operations
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)

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)