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

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)

package/src/infrastructure/services/JOB_PROCESSOR_SERVICE.md

@@ -0,0 +1,174 @@
+# Job Processor Service
+
+Service for handling asynchronous AI generation jobs. Manages job submission, status tracking, and result retrieval with automatic async processing.
+
+## 📍 Import Path
+
+```
+import { jobProcessor } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use job processor to handle long-running AI operations asynchronously. Submit jobs, track status, and retrieve results when ready.
+
+**When to use:**
+- Process long-running operations
+- Track job status over time
+- Implement async job management
+- Handle video generation
+- Manage background processing
+
+## 📌 Strategy
+
+Async processing improves UX. This service:
+- Manages job lifecycle
+- Tracks status changes
+- Stores results for retrieval
+- Handles polling automatically
+- Provides job management
+
+**Key Decision**: Use job processor for operations taking > 30 seconds. Poll for status instead of blocking.
+
+## ⚠️ Rules
+
+### Job Submission Rules
+- **MUST** save request ID after submission
+- **SHOULD** validate input before submission
+- **MUST** handle submission errors
+- **SHOULD** track submitted jobs
+- **MUST NOT** lose request IDs
+
+### Status Tracking Rules
+- **MUST** poll status periodically
+- **SHOULD** implement exponential backoff
+- **MUST** handle status changes
+- **SHOULD** monitor job progress
+- **MUST NOT** poll too frequently
+
+### Result Retrieval Rules
+- **SHOULD** verify job completion
+- **MUST** handle retrieval errors
+- **SHOULD** validate result format
+- **MUST** clear old results
+- **SHOULD NOT** retrieve incomplete jobs
+
+### Cleanup Rules
+- **SHOULD** clear completed jobs
+- **MUST** handle cleanup errors
+- **SHOULD** implement job expiration
+- **MUST** manage memory usage
+- **SHOULD NOT** accumulate old jobs
+
+## 🤖 AI Agent Guidelines
+
+### When Submitting Jobs
+1. **VALIDATE** input parameters
+2. **CALL** submitJob()
+3. **SAVE** request ID
+4. **TRACK** job status
+5. **HANDLE** submission errors
+
+### When Tracking Status
+1. **POLL** getJobStatus() periodically
+2. **IMPLEMENT** exponential backoff
+3. **CHECK** status changes
+4. **UPDATE** UI accordingly
+5. **HANDLE** completion
+
+### When Retrieving Results
+1. **VERIFY** job completion
+2. **CALL** getJobResult()
+3. **VALIDATE** result format
+4. **USE** result data
+5. **CLEAR** job data
+
+### Code Style Rules
+- **SAVE** request IDs persistently
+- **IMPLEMENT** polling with timeout
+- **HANDLE** all status cases
+- **CLEAN UP** old jobs
+- **LOG** job lifecycle events
+
+## 📦 Available Service
+
+### jobProcessor
+
+**Refer to**: [`job-processor.ts`](./job-processor.ts)
+
+**Methods:**
+- `submitJob(model, input)` - Submit async job
+- `getJobStatus(model, requestId)` - Get job status
+- `getJobResult(model, requestId)` - Get job result
+- `clear()` - Clear all jobs
+
+## 🔗 Related Modules
+
+- **Job Manager**: [`../../job/README.md`](../../job/README.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Generation Executor**: [`GENERATION_EXECUTOR_SERVICE.md`](./GENERATION_EXECUTOR_SERVICE.md)
+
+## 📋 Job States
+
+### IN_QUEUE
+Job is queued, waiting to start.
+
+### PROCESSING
+Job is currently being processed.
+
+### COMPLETED
+Job finished successfully with result.
+
+### FAILED
+Job failed with error.
+
+## 🎓 Usage Patterns
+
+### Job Submission
+1. Validate input parameters
+2. Call submitJob()
+3. Save request ID
+4. Display submission status
+5. Begin polling
+
+### Status Polling
+1. Poll getJobStatus() periodically
+2. Implement exponential backoff
+3. Update UI with status
+4. Handle completion/failure
+5. Stop polling when done
+
+### Result Retrieval
+1. Verify job completion
+2. Call getJobResult()
+3. Validate result format
+4. Use result data
+5. Clear job data
+
+### Job Cleanup
+1. Track job completion time
+2. Clear old completed jobs
+3. Remove failed jobs
+4. Manage memory usage
+5. Implement expiration
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Lose request IDs
+- Poll too frequently
+- Skip error handling
+- Forget to clean up jobs
+- Block on job submission
+
+### Do
+- Save request IDs persistently
+- Implement exponential backoff
+- Handle all job states
+- Clean up completed jobs
+- Provide user feedback
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/services/PROVIDER_INITIALIZER_SERVICE.md

@@ -0,0 +1,176 @@
+# Provider Initializer Service
+
+Service for initializing and configuring the Gemini Provider. Handles setup of the core client with provider-specific configuration.
+
+## 📍 Import Path
+
+```
+import { providerInitializer } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use provider initializer to configure and set up the Gemini provider before using any services. Initializes core client with API keys and configuration.
+
+**When to use:**
+- Initialize provider on application startup
+- Configure retry and timeout settings
+- Set default models for different features
+- Reset provider for testing
+- Verify initialization status
+
+## 📌 Strategy
+
+Provider must be initialized before any AI operations. This service:
+- Initializes singleton core client
+- Configures retry and timeout behavior
+- Sets default models for features
+- Prevents duplicate initialization
+- Provides reset capability for testing
+- Validates configuration
+
+**Key Decision**: Initialize provider once at application startup. Use `isInitialized()` to verify before operations.
+
+## ⚠️ Rules
+
+### Initialization Rules
+- **MUST** initialize before using any service
+- **SHOULD** initialize on app startup
+- **MUST** provide valid API key
+- **SHOULD** check initialization status
+- **MUST NOT** reinitialize unnecessarily
+
+### Configuration Rules
+- **MUST** provide API key (required field)
+- **SHOULD** set appropriate retry limits
+- **MUST** configure timeouts appropriately
+- **SHOULD** use environment variables for secrets
+- **MUST NOT** hardcode API keys
+
+### API Key Rules
+- **MUST** store API keys securely
+- **SHOULD** use environment variables
+- **MUST NOT** commit API keys to version control
+- **SHOULD** rotate keys periodically
+- **MUST** validate key format
+
+### Reset Rules
+- **SHOULD** only reset for testing
+- **MUST NOT** reset in production
+- **SHOULD** reinitialize after reset
+- **MUST** handle reset errors
+- **SHOULD** warn before resetting
+
+## 🤖 AI Agent Guidelines
+
+### When Initializing Provider
+1. **CALL** initialize() with configuration
+2. **PROVIDE** valid API key
+3. **SET** appropriate retry/timeout values
+4. **CONFIGURE** default models
+5. **VERIFY** initialization success
+
+### When Checking Status
+1. **CALL** isInitialized() before operations
+2. **THROW** error if not initialized
+3. **INITIALIZE** if not ready
+4. **LOG** initialization status
+5. **HANDLE** initialization errors
+
+### When Resetting Provider
+1. **USE** only in test environments
+2. **CALL** reset() to clear state
+3. **REINITIALIZE** with new config
+4. **VERIFY** reset success
+5. **CLEAN UP** resources
+
+### Code Style Rules
+- **INITIALIZE** early in app lifecycle
+- **VALIDATE** configuration before initialization
+- **HANDLE** initialization errors
+- **LOG** initialization in development
+- **USE** environment variables for secrets
+
+## 📦 Available Service
+
+### providerInitializer
+
+**Refer to**: [`provider-initializer.ts`](./provider-initializer.ts)
+
+**Singleton instance**
+
+**Methods:**
+- `initialize(config)` - Initialize provider with configuration
+- `isInitialized()` - Check if provider is initialized
+- `reset()` - Reset provider state
+
+## 🔗 Related Modules
+
+- **Core Client**: [`CORE_CLIENT_SERVICE.md`](./CORE_CLIENT_SERVICE.md)
+- **Domain Types**: [`../../domain/README.md`](../../domain/README.md)
+- **Services README**: [`./README.md`](./README.md)
+
+## 📋 Configuration
+
+### Required Fields
+- `apiKey`: Google Cloud API key
+
+### Optional Fields
+- `maxRetries`: Maximum retry attempts (default: from core config)
+- `baseDelay`: Base delay for retries in ms (default: from core config)
+- `maxDelay`: Maximum delay for retries in ms (default: from core config)
+- `defaultTimeoutMs`: Default timeout for requests in ms (default: from core config)
+- `textModel`: Default model for text generation
+- `textToImageModel`: Default model for image generation
+- `imageEditModel`: Default model for image editing
+
+## 🎓 Usage Patterns
+
+### Basic Initialization
+1. Import providerInitializer
+2. Call initialize() with API key
+3. Verify initialization success
+4. Use Gemini services normally
+5. Handle initialization errors
+
+### Full Configuration
+1. Create configuration object
+2. Set API key and models
+3. Configure retry/timeout values
+4. Initialize provider
+5. Verify all settings
+
+### React Native Integration
+1. Import in App component
+2. Initialize in useEffect
+3. Set loading state
+4. Handle errors
+5. Render app when ready
+
+### Environment-Based Configuration
+1. Detect environment (dev/prod)
+2. Select appropriate configuration
+3. Initialize with environment settings
+4. Log configuration in development
+5. Use appropriate models
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Initialize provider before every operation
+- Hardcode API keys in source code
+- Skip initialization status checks
+- Use invalid API keys
+- Reset provider in production
+
+### Do
+- Initialize once at app startup
+- Use environment variables for API keys
+- Check initialization status before use
+- Validate configuration format
+- Handle initialization errors gracefully
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)