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

package/src/infrastructure/services/FEATURE_MODEL_SELECTOR_SERVICE.md

@@ -0,0 +1,206 @@
+# Feature Model Selector Service
+
+Selects appropriate Gemini models based on feature type. Supports runtime model overrides for flexibility.
+
+## 📍 Import Path
+
+```
+import { featureModelSelector } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to select the correct AI model for specific features. Provides default model mappings and supports runtime overrides.
+
+**When to use:**
+- Select models for image/video features
+- Override models for testing or optimization
+- A/B test different models
+- Implement feature-based model selection
+- Configure models based on user preferences
+
+## 📌 Strategy
+
+Different AI features require specialized models. This service:
+- Maps features to appropriate default models
+- Supports runtime model overrides
+- Provides type-safe model selection
+- Maintains feature-to-model relationships
+- Enables flexible model configuration
+
+**Key Decision**: Use feature-based model selection instead of hardcoding model IDs. This allows easy model updates and testing without code changes.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** use valid feature types (ImageFeatureType | VideoFeatureType)
+- **SHOULD** check for existing overrides before setting new ones
+- **MUST** clear overrides after temporary usage
+- **SHOULD** use type-safe feature names
+- **MUST NOT** use string literals for feature names
+
+### Override Rules
+- **SHOULD** use overrides sparingly
+- **MUST** clean up overrides when done
+- **SHOULD** check if override already exists
+- **MUST NOT** set permanent overrides app-wide
+- **SHOULD** restore original state after temporary overrides
+
+### Configuration Rules
+- **MUST** use valid model IDs
+- **SHOULD** validate model IDs before use
+- **MUST** handle model errors appropriately
+- **SHOULD** log override operations in development
+- **MUST NOT** override with invalid model IDs
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** feature-to-model mapping
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if feature type already exists
+2. **FOLLOW** existing patterns
+3. **UPDATE** feature constants
+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** type-safe feature names
+- **VALIDATE** model IDs
+- **LOG** override operations in development
+- **THROW** typed errors for invalid inputs
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `setModelOverride(feature, model)`
+
+Set a custom model override for a specific feature.
+
+**Refer to**: [`feature-model-selector.ts`](./feature-model-selector.ts)
+
+### `clearOverrides()`
+
+Clear all model overrides and revert to default models.
+
+**Refer to**: [`feature-model-selector.ts`](./feature-model-selector.ts)
+
+### `getImageFeatureModel(feature)`
+
+Get the model ID for an image feature.
+
+**Refer to**: [`feature-model-selector.ts`](./feature-model-selector.ts)
+
+### `getVideoFeatureModel(feature)`
+
+Get the model ID for a video feature.
+
+**Refer to**: [`feature-model-selector.ts`](./feature-model-selector.ts)
+
+### `hasOverride(feature)`
+
+Check if a feature has a custom override set.
+
+**Refer to**: [`feature-model-selector.ts`](./feature-model-selector.ts)
+
+## 🔗 Related Modules
+
+- **Feature Constants**: [`domain/constants/feature-models.constants.ts`](../domain/constants/feature-models.constants.ts)
+- **Image Generation**: [`IMAGE_GENERATION_SERVICE.md`](./IMAGE_GENERATION_SERVICE.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### Supported Image Features
+
+- `image-generation` - Text-to-image generation
+- `image-edit` - Image editing and transformation
+- `upscale` - Image upscaling
+- `face-swap` - Face replacement
+- `remove-background` - Background removal
+- `inpainting` - Image inpainting
+- `outpainting` - Image outpainting
+
+### Supported Video Features
+
+- `video-generation` - Text-to-video generation
+- `video-preview` - Video preview generation
+
+### Default Models
+
+**Image Features:**
+- `image-generation`: `imagen-3.0-generate-001`
+- `image-edit`: `imagen-3.0-generate-001`
+- `upscale`: `imagen-3.0-capabilities-001`
+- Other features: `imagen-3.0-capabilities-001`
+
+**Video Features:**
+- `video-generation`: `veo-3.1-generate-001`
+- `video-preview`: `veo-3.1-fast-generate-preview`
+
+## 🎓 Usage Patterns
+
+### Basic Model Selection
+1. Import service
+2. Call `getImageFeatureModel()` or `getVideoFeatureModel()` with feature type
+3. Use returned model ID with generation service
+4. Generate content with selected model
+
+### Runtime Model Override
+1. Call `setModelOverride()` with feature and custom model
+2. Use feature services normally
+3. All requests now use custom model
+4. Clear override when done
+
+### Temporary Override with Cleanup
+1. Save current overrides state
+2. Set temporary override
+3. Execute operation with custom model
+4. Restore original state in finally block
+
+### Feature-Based Model Selection
+1. Determine feature type from request
+2. Call appropriate getter method (image vs video)
+3. Receive model ID for feature
+4. Execute generation with selected model
+
+### A/B Testing Different Models
+1. Define array of models to test
+2. Loop through models
+3. Set override for each model
+4. Generate content and track results
+5. Clear overrides after testing
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Set permanent overrides app-wide
+- Forget to clear overrides after use
+- Use string literals for feature names
+- Override without checking existing state
+- Use invalid model IDs
+
+### Do
+- Clean up overrides in finally blocks
+- Check for existing overrides before setting
+- Use type-safe feature names
+- Validate model IDs before use
+- Test with different models for optimization
+- Log override operations in development
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/GENERATION_EXECUTOR_SERVICE.md

@@ -0,0 +1,176 @@
+# Generation Executor Service
+
+Service for executing different types of AI generation tasks. Handles text, image, and video generation with a unified interface.
+
+## 📍 Import Path
+
+```
+import { generationExecutor } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use generation executor to execute AI generation tasks with a unified interface. Automatically detects generation type and routes to appropriate service.
+
+**When to use:**
+- Execute text, image, or video generation
+- Use unified generation interface
+- Handle multiple generation types
+- Simplify service integration
+- Abstract generation complexity
+
+## 📌 Strategy
+
+Unified interface simplifies integration. This service:
+- Detects generation type automatically
+- Routes to appropriate service
+- Provides consistent interface
+- Handles response formatting
+- Simplifies error handling
+
+**Key Decision**: Use executor for generic generation needs. Use specific services for direct control.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** specify generation type in input
+- **SHOULD** use executor for generic operations
+- **MUST** handle typed responses correctly
+- **SHOULD** validate input parameters
+- **MUST NOT** mix generation types
+
+### Type Detection Rules
+- **MUST** specify input type explicitly
+- **SHOULD** use appropriate input structure
+- **MUST** match type to service
+- **SHOULD** validate type compatibility
+- **MUST NOT** rely on implicit detection
+
+### Response Rules
+- **MUST** handle response types correctly
+- **SHOULD** validate response structure
+- **MUST** check for errors
+- **SHOULD** parse responses appropriately
+- **MUST NOT** assume response format
+
+### Error Handling Rules
+- **MUST** catch generation errors
+- **SHOULD** provide meaningful error messages
+- **MUST** handle service-specific errors
+- **SHOULD** log errors appropriately
+- **MUST NOT** suppress errors
+
+## 🤖 AI Agent Guidelines
+
+### When Executing Generations
+1. **DETERMINE** generation type
+2. **PREPARE** input structure
+3. **CALL** executeGeneration()
+4. **HANDLE** typed response
+5. **PROCESS** result appropriately
+
+### When Using Typed Generations
+1. **SPECIFY** type parameter
+2. **PROVIDE** correct input
+3. **CAST** response appropriately
+4. **VALIDATE** response type
+5. **USE** result safely
+
+### When Handling Errors
+1. **WRAP** execution in try-catch
+2. **CHECK** error type
+3. **HANDLE** service-specific errors
+4. **PROVIDE** fallback behavior
+5. **LOG** error details
+
+### Code Style Rules
+- **SPECIFY** generation type explicitly
+- **USE** type parameters correctly
+- **HANDLE** all error cases
+- **VALIDATE** input structure
+- **DOCUMENT** generation usage
+
+## 📦 Available Service
+
+### generationExecutor
+
+**Refer to**: [`generation-executor.ts`](./generation-executor.ts)
+
+**Methods:**
+- `executeGeneration<T>(model, input, options?)` - Execute generation task
+- `generateWithImages(model, prompt, images)` - Generate with image context
+
+## 🔗 Related Modules
+
+- **Text Generation**: [`TEXT_GENERATION_SERVICE.md`](./TEXT_GENERATION_SERVICE.md)
+- **Image Generation**: [`IMAGE_GENERATION_SERVICE.md`](./IMAGE_GENERATION_SERVICE.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Job Processor**: [`JOB_PROCESSOR_SERVICE.md`](./JOB_PROCESSOR_SERVICE.md)
+
+## 📋 Generation Types
+
+### Text Generation
+- Type: `text`
+- Input: `{ type: 'text', prompt: string }`
+- Returns: `{ text: string; response: unknown }`
+
+### Image Generation
+- Type: `image`
+- Input: `{ type: 'image', prompt: string }`
+- Returns: `{ imageUrl: string; response: unknown }`
+
+### Video Generation
+- Type: `video`
+- Input: `{ type: 'video', prompt: string }`
+- Returns: `{ videoUrl: string; response: unknown }`
+
+## 🎓 Usage Patterns
+
+### Basic Generation
+1. Determine generation type
+2. Prepare input structure
+3. Call executeGeneration()
+4. Get typed response
+5. Use result
+
+### Typed Generation
+1. Specify type parameter
+2. Provide correct input
+3. Execute generation
+4. Validate response type
+5. Use result safely
+
+### Image Context Generation
+1. Call generateWithImages()
+2. Provide prompt and images
+3. Get text response
+4. Handle multimodal result
+5. Process response
+
+### Error Handling
+1. Wrap execution in try-catch
+2. Check error type
+3. Handle specific errors
+4. Provide fallback
+5. Log errors
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Skip type specification
+- Mix generation types
+- Assume response format
+- Suppress errors
+- Use wrong input structure
+
+### Do
+- Always specify type
+- Use correct input structure
+- Handle all error cases
+- Validate responses
+- Use type parameters correctly
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/services/IMAGE_EDIT_SERVICE.md

@@ -0,0 +1,169 @@
+# Image Edit Service
+
+Edits and transforms images using Gemini API. Supports background removal, object removal, face swap, and image enhancements.
+
+## 📍 Import Path
+
+```
+import { geminiImageEditService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to edit and transform existing images with AI. Supports background removal, object deletion, style transfer, image enhancement, and various image manipulation operations.
+
+**When to use:**
+- Remove or replace image backgrounds
+- Remove unwanted objects from images
+- Enhance image quality (upscale, denoise, restore)
+- Apply style transformations (anime, artistic styles)
+- Face swapping and image compositing
+
+## 📌 Strategy
+
+Image editing requires both visual and textual understanding. This service:
+- Uses multimodal models (gemini-2.5-flash-image)
+- Accepts base64-encoded images as input
+- Returns edited images with text descriptions
+- Supports both single and multiple image inputs
+- Handles image-specific response formats
+
+**Key Decision**: Image editing uses TEXT + IMAGE response modalities. The service returns both edited image data and explanatory text when applicable.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider with API key before use
+- **MUST** provide base64-encoded images
+- **SHOULD** use specific, clear prompts
+- **MUST NOT** exceed image size limits
+- **MUST** handle image editing errors appropriately
+
+### Prompt Rules
+- **SHOULD** clearly describe desired edit
+- **MUST** specify what to keep vs remove
+- **SHOULD** include fill instructions for removals
+- **MUST NOT** request prohibited content
+
+### Configuration Rules
+- **MUST** use valid model IDs (gemini-2.5-flash-image)
+- **SHOULD** optimize image size before sending
+- **MUST** respect content safety guidelines
+- **SHOULD** implement retry logic for failures
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **MUST** provide user-friendly error messages
+- **SHOULD** log errors for debugging
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** multimodal response format
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar feature exists in image services
+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** async/await (no callbacks)
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `editImage(prompt, images)`
+
+Edit images with text instructions.
+
+**Refer to**: [`gemini-image-edit.service.ts`](./gemini-image-edit.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Image Generation**: [`IMAGE_GENERATION_SERVICE.md`](./IMAGE_GENERATION_SERVICE.md)
+- **Core Client**: [`CORE_CLIENT_SERVICE.md`](./CORE_CLIENT_SERVICE.md)
+- **Image Preparers**: [`IMAGE_PREPARER_UTILS.md`](../infrastructure/utils/IMAGE_PREPARER_UTILS.md)
+
+## 📋 Configuration Reference
+
+### Generation Config
+See: [`domain/entities/README.md`](../domain/entities/README.md)
+
+### Model Selection
+- Current model: `gemini-2.5-flash-image`
+- Response modalities: TEXT + IMAGE
+- Output format: PNG (typically)
+
+### Error Types
+See: [`ERROR_UTILITIES.md`](../infrastructure/utils/ERROR_UTILITIES.md)
+
+## 🎓 Usage Patterns
+
+### Background Removal
+1. Import service
+2. Prepare base64-encoded image
+3. Call `editImage()` with removal prompt
+4. Handle response (contains `imageUrl`, `imageBase64`)
+5. Display or save edited image
+
+### Object Removal
+1. Import service
+2. Prepare base64-encoded image
+3. Create prompt describing object to remove and fill instructions
+4. Call `editImage()` with prompt and image
+5. Handle result showing edited image
+
+### Background Replacement
+1. Import service
+2. Prepare base64-encoded image
+3. Create prompt describing new background
+4. Specify to keep main subject
+5. Call `editImage()` with detailed prompt
+6. Handle response
+
+### Image Enhancement
+1. Import service
+2. Prepare base64-encoded image
+3. Create enhancement prompt (brightness, contrast, etc.)
+4. Call `editImage()` with prompt and image
+5. Handle enhanced result
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use vague prompts ("remove this")
+- Forget to specify fill instructions
+- Send extremely large images
+- Expect perfect results on complex edits
+- Ignore safety filters
+
+### Do
+- Be specific about what to edit
+- Describe how to fill removed areas
+- Optimize image size before sending
+- Handle multimodal responses (text + image)
+- Implement retry logic
+- Test with various image types
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/IMAGE_GENERATION_SERVICE.md

@@ -0,0 +1,166 @@
+# Image Generation Service
+
+Generates images from text prompts using Google Imagen API.
+
+## 📍 Import Path
+
+```
+import { geminiImageGenerationService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to generate AI-powered images from text descriptions. Supports creating photorealistic images, artistic renderings, and various visual styles using Imagen 4.0 model.
+
+**When to use:**
+- Generate images from text descriptions
+- Create visual content for applications
+- Generate artistic or photorealistic imagery
+- Product visualization and concept art
+
+## 📌 Strategy
+
+Image generation requires specialized handling compared to text generation. This service:
+- Uses Imagen 4.0 model specifically for images
+- Returns base64-encoded image data
+- Handles image-specific response formats
+- Integrates with retry logic for reliability
+- Validates prompt content for safety
+
+**Key Decision**: Images are returned as base64 data URLs for React Native compatibility. Use `imageBase64` for raw data or `imageUrl` for React Native Image component.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider with API key before use
+- **MUST** handle image data appropriately (display or save)
+- **MUST NOT** exceed API rate limits
+- **SHOULD** provide detailed prompts for better results
+- **MUST** handle image generation errors appropriately
+
+### Prompt Rules
+- **SHOULD** be descriptive and specific
+- **SHOULD** include style and lighting information
+- **MUST NOT** include prohibited content
+- **SHOULD** follow prompt templates for consistency
+
+### Configuration Rules
+- **MUST** use valid model IDs
+- **SHOULD** configure aspect ratio appropriately (currently 1:1 only)
+- **MUST** respect content safety guidelines
+- **SHOULD** implement retry logic for failures
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **MUST** provide user-friendly error messages
+- **SHOULD** log errors for debugging
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** image response format
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar feature exists in image services
+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** async/await (no callbacks)
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `generateImage(prompt, images?, config?)`
+
+Generate an image from text prompt.
+
+**Refer to**: [`gemini-image-generation.service.ts`](./gemini-image-generation.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Image Edit Service**: [`IMAGE_EDIT_SERVICE.md`](./IMAGE_EDIT_SERVICE.md)
+- **Core Client**: [`CORE_CLIENT_SERVICE.md`](./CORE_CLIENT_SERVICE.md)
+- **Retry Service**: [`RETRY_SERVICE.md`](./RETRY_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### Generation Config
+See: [`domain/entities/README.md`](../domain/entities/README.md)
+
+### Model Selection
+- Current model: `imagen-4.0-generate-001`
+- Aspect ratio: 1:1 (only supported ratio)
+- Format: `image/png`
+- Encoding: Base64
+
+### Error Types
+See: [`ERROR_UTILITIES.md`](../infrastructure/utils/ERROR_UTILITIES.md)
+
+## 🎓 Usage Patterns
+
+### Basic Image Generation
+1. Import service
+2. Call `generateImage()` with descriptive prompt
+3. Handle response (contains `imageUrl`, `imageBase64`, `mimeType`)
+4. Display image in React Native Image component
+5. Handle errors appropriately
+
+### With Retry Logic
+1. Wrap call in retry mechanism
+2. Configure max retries and delays
+3. Handle retryable errors (network, rate limits)
+4. Provide feedback to user during retries
+
+### Saving Generated Images
+1. Generate image using service
+2. Extract `imageBase64` from result
+3. Save to filesystem using React Native FS
+4. Handle file system errors
+
+### Uploading Generated Images
+1. Generate image using service
+2. Extract base64 data
+3. Convert to appropriate format
+4. Upload to server/storage
+5. Handle upload errors
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use vague or generic prompts
+- Ignore error handling
+- Assume immediate results (generation takes time)
+- Exceed rate limits
+- Try to edit images with this service (use IMAGE_EDIT_SERVICE)
+
+### Do
+- Provide detailed, specific prompts
+- Include style and lighting information
+- Handle all error types
+- Implement loading states
+- Use image edit service for modifications
+- Cache generated images appropriately
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)