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

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)

package/src/infrastructure/services/README.md

@@ -0,0 +1,233 @@
+# Services Layer
+
+Communication layer with Gemini API. Contains all business logic for text, image, and video generation.
+
+## 📍 Import Path
+
+```
+import {
+  geminiClientCoreService,
+  geminiTextGenerationService,
+  geminiImageGenerationService,
+  geminiImageEditService,
+  geminiVideoGenerationService,
+  geminiStreamingService,
+  geminiRetryService,
+  providerInitializer,
+  featureModelSelector
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use services to execute AI operations. Each service handles specific AI capabilities with proper error handling and retry logic.
+
+**When to use:**
+- Generate text content
+- Create images from text
+- Edit and transform images
+- Generate videos
+- Stream real-time responses
+- Handle AI errors and retries
+
+## 📌 Strategy
+
+Services encapsulate API communication logic. This layer:
+- Provides high-level interfaces for AI operations
+- Handles error detection and retry logic
+- Manages API communication complexity
+- Implements feature-based model selection
+- Supports both simple and advanced use cases
+
+**Key Decision**: Use services for all AI operations. They handle complexity, errors, and optimization automatically.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider before using services
+- **SHOULD** use appropriate service for operation type
+- **MUST** handle service errors appropriately
+- **SHOULD** check model validation
+- **MUST NOT** bypass error handling
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **SHOULD** implement retry logic for transient errors
+- **MUST** provide user-friendly error messages
+- **SHOULD** log errors for debugging
+- **MUST NOT** expose API keys in errors
+
+### Configuration Rules
+- **MUST** use valid model IDs
+- **SHOULD** configure appropriate generation parameters
+- **MUST** respect API rate limits
+- **SHOULD** implement timeouts for long operations
+- **MUST NOT** use deprecated models
+
+### Model Selection Rules
+- **SHOULD** use feature-based model selector
+- **MUST** validate model before use
+- **SHOULD** consider user tier for model selection
+- **MUST NOT** hardcode model IDs in application code
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Services
+1. **READ** the implementation file first
+2. **UNDERSTAND** service dependencies
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** all documentation
+
+### When Adding New Services
+1. **CHECK** if similar service exists
+2. **FOLLOW** existing service patterns
+3. **USE** established error handling
+4. **DOCUMENT** in service documentation
+5. **ADD** examples to tests (not docs)
+
+### When Fixing Service 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 service entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Services
+
+### Core Services
+
+**Text Generation**: Generate AI text content
+
+**Refer to**: [`TEXT_GENERATION_SERVICE.md`](./TEXT_GENERATION_SERVICE.md)
+
+**Image Generation**: Create images from text prompts
+
+**Refer to**: [`IMAGE_GENERATION_SERVICE.md`](./IMAGE_GENERATION_SERVICE.md)
+
+**Image Edit**: Edit and transform images
+
+**Refer to**: [`IMAGE_EDIT_SERVICE.md`](./IMAGE_EDIT_SERVICE.md)
+
+**Video Generation**: Generate videos from text/images
+
+**Refer to**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+
+**Streaming**: Real-time text streaming
+
+**Refer to**: [`STREAMING_SERVICE.md`](./STREAMING_SERVICE.md)
+
+**Retry**: Automatic retry with backoff
+
+**Refer to**: [`RETRY_SERVICE.md`](./RETRY_SERVICE.md)
+
+### Support Services
+
+**Core Client**: Low-level SDK communication
+
+**Refer to**: [`CORE_CLIENT_SERVICE.md`](./CORE_CLIENT_SERVICE.md)
+
+**Feature Model Selector**: Feature-based model selection
+
+**Refer to**: [`FEATURE_MODEL_SELECTOR_SERVICE.md`](./FEATURE_MODEL_SELECTOR_SERVICE.md)
+
+**Provider Initializer**: Provider initialization
+
+**Refer to**: [`PROVIDER_INITIALIZER_SERVICE.md`](./PROVIDER_INITIALIZER_SERVICE.md)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`../../domain/README.md`](../../domain/README.md)
+- **Infrastructure**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Presentation**: [`../presentation/README.md`](../presentation/README.md)
+
+## 📋 Service Categories
+
+### Text Services
+- Text generation (simple and structured)
+- Multimodal content (text + images)
+- Streaming responses
+- Conversational AI
+
+### Image Services
+- Text-to-image generation
+- Image editing and transformation
+- Background removal
+- Image enhancement
+- Style transfer
+
+### Video Services
+- Text-to-video generation
+- Image-to-video generation
+- Progress tracking
+- Polling mechanism
+
+### Infrastructure Services
+- SDK client management
+- Error handling and retry
+- Model selection and validation
+- Provider initialization
+
+## 🎓 Usage Patterns
+
+### Basic Text Generation
+1. Import `geminiTextGenerationService`
+2. Call `generateText()` with model and prompt
+3. Handle response or error
+4. Display result to user
+
+### Image Generation
+1. Import `geminiImageGenerationService`
+2. Call `generateImage()` with descriptive prompt
+3. Handle image data (URL or base64)
+4. Display image in UI
+
+### Video Generation
+1. Import `geminiVideoGenerationService`
+2. Call `generateTextToVideo()` with prompt
+3. Provide progress callback
+4. Monitor progress
+5. Handle completion
+
+### Error Handling
+1. Wrap service call in try-catch
+2. Check if error is `GeminiError`
+3. Switch on error type
+4. Handle each error type appropriately
+5. Provide user feedback
+
+### Streaming
+1. Import `geminiStreamingService`
+2. Call `streamText()` with model and prompt
+3. Use `for await` to consume stream
+4. Display chunks progressively
+5. Handle completion
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use services without initializing provider
+- Ignore error handling
+- Hardcode model IDs
+- Exceed API rate limits
+- Skip progress callbacks for long operations
+
+### Do
+- Initialize provider before using services
+- Handle all error types
+- Use feature model selector
+- Implement retry logic
+- Provide user feedback
+- Monitor long operations
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)