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

package/src/infrastructure/services/CORE_CLIENT_SERVICE.md

@@ -0,0 +1,202 @@
+# Core Client Service
+
+Low-level communication with Google Gemini SDK. Handles model loading, configuration, and SDK management.
+
+## 📍 Import Path
+
+```
+import { geminiClientCoreService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to initialize and configure the Gemini SDK. Manages the underlying Gemini client instance and provides access to configured models.
+
+**When to use:**
+- Initialize Gemini SDK with API key
+- Configure default models for different features
+- Access Gemini model instances directly
+- Update SDK configuration at runtime
+- Validate SDK initialization status
+
+## 📌 Strategy
+
+Core client acts as the foundation for all Gemini operations. This service:
+- Implements singleton pattern for single SDK instance
+- Manages SDK lifecycle (initialization, configuration)
+- Provides typed model instances
+- Handles API key and endpoint configuration
+- Validates initialization before operations
+
+**Key Decision**: Use singleton pattern to ensure single Gemini SDK instance. All other services use this core client for model access.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize before any Gemini operations
+- **MUST** provide valid API key in configuration
+- **SHOULD** initialize once at application startup
+- **MUST NOT** create multiple instances (use singleton)
+- **SHOULD** validate initialization before use
+
+### Configuration Rules
+- **MUST** set API key (required field)
+- **SHOULD** configure appropriate models for features
+- **MUST NOT** expose API keys in logs or errors
+- **SHOULD** set reasonable retry limits
+- **MUST** use valid model IDs
+
+### Error Handling Rules
+- **MUST** validate configuration before initialization
+- **MUST** handle initialization errors appropriately
+- **SHOULD** provide clear error messages
+- **MUST** throw errors for invalid API keys
+- **SHOULD** log initialization status in development
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** singleton pattern
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if feature exists in other services
+2. **FOLLOW** existing initialization 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** singleton pattern
+- **VALIDATE** all inputs
+- **THROW** typed errors
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `initialize(config)`
+
+Initialize Gemini client with configuration.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `getModel(model)`
+
+Get Gemini model instance by ID.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `getConfig()`
+
+Get current configuration.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `isInitialized()`
+
+Check if service is initialized.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `validateInitialization()`
+
+Validate initialization, throw error if not initialized.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `updateConfig(config)`
+
+Update configuration at runtime.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **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)
+
+## 📋 Configuration Reference
+
+### GeminiConfig
+
+Configuration interface definition found in: [`domain/entities/README.md`](../domain/entities/README.md)
+
+**Required Fields:**
+- `apiKey`: string - API key from Google Cloud Console
+
+**Optional Fields:**
+- `baseUrl`: string - Custom base URL for API requests
+- `maxRetries`: number - Maximum retry attempts (default: 3)
+- `baseDelay`: number - Initial retry delay in ms (default: 1000)
+- `maxDelay`: number - Maximum retry delay in ms (default: 10000)
+- `defaultTimeoutMs`: number - Request timeout in ms
+- `textModel`: string - Default text generation model
+- `textToImageModel`: string - Default image generation model
+- `imageEditModel`: string - Default image editing model
+- `videoGenerationModel`: string - Default video generation model
+
+### Supported Models
+
+See model IDs in: [`domain/constants/README.md`](../domain/constants/README.md)
+
+## 🎓 Usage Patterns
+
+### Basic Initialization
+1. Import service
+2. Call `initialize()` with API key
+3. Verify initialization with `isInitialized()`
+4. Use services normally
+
+### Advanced Configuration
+1. Prepare configuration object with all settings
+2. Include model IDs for each feature
+3. Set retry and timeout parameters
+4. Call `initialize()` with configuration
+5. Validate initialization succeeded
+
+### Runtime Configuration Updates
+1. Check current configuration with `getConfig()`
+2. Prepare partial config update
+3. Call `updateConfig()` with new values
+4. Verify changes applied
+
+### Direct Model Access
+1. Ensure service is initialized
+2. Call `getModel()` with model ID
+3. Use returned model instance directly
+4. Handle model errors appropriately
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Initialize multiple times
+- Create new instances (use singleton)
+- Skip initialization validation
+- Expose API keys in logs
+- Use uninitialized service
+
+### Do
+- Initialize once at app startup
+- Use singleton instance
+- Validate before use
+- Handle initialization errors
+- Set appropriate model IDs
+- Configure reasonable timeouts
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

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)