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

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)

package/src/infrastructure/services/RETRY_SERVICE.md

@@ -0,0 +1,178 @@
+# Retry Service
+
+Automatic retry mechanism with exponential backoff strategy. Handles transient errors gracefully.
+
+## 📍 Import Path
+
+```
+import { geminiRetryService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to automatically retry failed operations with intelligent backoff. Handles network issues, rate limits, and transient server errors.
+
+**When to use:**
+- Wrap API calls that may fail transiently
+- Handle rate limiting automatically
+- Improve reliability of network operations
+- Add resilience to critical operations
+- Track retry attempts for monitoring
+
+## 📌 Strategy
+
+Not all errors should be retried. This service:
+- Uses exponential backoff for delays
+- Retries only transient errors (network, rate limit, server errors)
+- Fails fast for permanent errors (auth, validation, safety)
+- Provides retry callbacks for monitoring
+- Configurable retry limits and delays
+
+**Key Decision**: Only retry errors that might succeed on retry (429 rate limits, 5xx server errors, network issues). Never retry validation or authentication errors.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** wrap only retryable operations
+- **SHOULD** configure appropriate max retries
+- **MUST** handle final failure after all retries
+- **SHOULD** use retry callbacks for monitoring
+- **MUST NOT** retry non-idempotent operations without care
+
+### Configuration Rules
+- **MUST** set maxRetries appropriately (default: 3)
+- **SHOULD** configure baseDelay for use case
+- **MUST** set maxDelay to prevent excessive waits
+- **SHOULD** use onRetry callback for logging
+
+### Retryable Errors
+- **WILL RETRY**: QUOTA_EXCEEDED, RATE_LIMIT, NETWORK, TIMEOUT, SERVER (5xx)
+- **WILL NOT RETRY**: AUTHENTICATION, SAFETY, VALIDATION, MODEL_NOT_FOUND
+
+### Error Handling Rules
+- **MUST** catch and handle final errors
+- **SHOULD** log retry attempts
+- **MUST** differentiate retryable vs non-retryable errors
+- **SHOULD** provide user feedback during retries
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** exponential backoff logic
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar feature 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** async/await (no callbacks)
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** retry attempts
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `executeWithRetry(fn, options?)`
+
+Execute function with automatic retry on transient errors.
+
+**Refer to**: [`gemini-retry.service.ts`](./gemini-retry.service.ts)
+
+## 🔗 Related Modules
+
+- **Error Utilities**: [`ERROR_UTILITIES.md`](../infrastructure/utils/ERROR_UTILITIES.md)
+- **Error Mapper**: [`ERROR_MAPPER.md`](../infrastructure/utils/ERROR_MAPPER.md)
+- **Text Generation**: [`TEXT_GENERATION_SERVICE.md`](./TEXT_GENERATION_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### RetryOptions
+
+```typescript
+interface RetryOptions {
+  maxRetries?: number;    // Maximum retry attempts (default: 3)
+  baseDelay?: number;     // Initial delay in ms (default: 1000)
+  maxDelay?: number;      // Maximum delay in ms (default: 10000)
+  onRetry?: (attempt: number, error: unknown) => void;
+}
+```
+
+### Retryable Error Types
+- `QUOTA_EXCEEDED`: Temporary quota exceeded
+- `RATE_LIMIT`: Too many requests
+- `NETWORK`: Network connectivity issues
+- `TIMEOUT`: Request timeout
+- `SERVER`: Server errors (5xx)
+
+### Non-Retryable Error Types
+- `AUTHENTICATION`: Invalid API key or credentials
+- `SAFETY`: Content safety violation
+- `VALIDATION`: Invalid request parameters
+- `MODEL_NOT_FOUND`: Invalid model ID
+
+## 🎓 Usage Patterns
+
+### Basic Retry
+1. Import service
+2. Wrap async function in `executeWithRetry()`
+3. Configure max retries and delays
+4. Handle final success or failure
+5. Provide user feedback
+
+### With Callbacks
+1. Import service
+2. Configure `onRetry` callback
+3. Log retry attempts for monitoring
+4. Update UI with retry status
+5. Track metrics for analytics
+
+### Custom Configuration
+1. Assess operation criticality
+2. Set appropriate maxRetries (1-5)
+3. Configure baseDelay for operation type
+4. Set maxDelay to prevent excessive waits
+5. Test retry behavior
+
+### For Critical Operations
+1. Use higher maxRetries (5+)
+2. Use longer baseDelay (2000ms)
+3. Set longer maxDelay (60000ms)
+4. Implement detailed callbacks
+5. Add timeout wrapper
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Retry authentication failures (won't succeed)
+- Retry validation errors (need input fix)
+- Retry without maxDelay (can wait forever)
+- Retry non-idempotent operations carelessly
+- Ignore retry callbacks (no visibility)
+
+### Do
+- Configure retries based on operation type
+- Use callbacks for monitoring and analytics
+- Set maxDelay to prevent excessive waits
+- Handle non-retryable errors appropriately
+- Differentiate transient vs permanent errors
+- Consider timeouts for total operation time
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/STREAMING_SERVICE.md

@@ -0,0 +1,166 @@
+# Streaming Service
+
+Provides real-time streaming for AI text generation. Delivers responses chunk-by-chunk for immediate display.
+
+## 📍 Import Path
+
+```
+import { geminiStreamingService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to generate AI text responses with streaming. Provides immediate feedback as content is generated, improving user experience for long responses.
+
+**When to use:**
+- Long text generation (stories, articles)
+- Chat interfaces requiring real-time responses
+- Applications needing immediate user feedback
+- Progressive content display
+- Cancelable operations
+
+## 📌 Strategy
+
+Streaming dramatically improves UX for long responses. This service:
+- Returns AsyncGenerator for chunk-by-chunk delivery
+- Enables progressive UI updates
+- Supports cancellation mid-generation
+- Handles stream errors gracefully
+- Provides finish reason for completion status
+
+**Key Decision**: Use streaming for better UX when generating long responses. Each chunk can be displayed immediately, reducing perceived latency.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider with API key before use
+- **MUST** iterate through async generator properly
+- **SHOULD** update UI with each chunk
+- **MUST** handle stream errors appropriately
+- **SHOULD** implement cancellation support
+
+### Stream Handling Rules
+- **MUST** use `for await` to consume stream
+- **SHOULD** buffer very small chunks
+- **MUST** check `finishReason` in final chunk
+- **SHOULD** implement memory limits for buffers
+- **MUST NOT** ignore stream errors
+
+### Configuration Rules
+- **MUST** use valid model IDs
+- **SHOULD** configure appropriate generation parameters
+- **MUST** handle safety filters in stream
+- **SHOULD** implement retry logic for failures
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **MUST** handle stream interruption errors
+- **SHOULD** check finish reasons (SAFETY, MAX_TOKENS)
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** async generator pattern
+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 streaming/text 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 and `for await`
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `streamText(model, prompt, config?)`
+
+Stream text generation chunk-by-chunk.
+
+**Refer to**: [`gemini-streaming.service.ts`](./gemini-streaming.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Text Generation**: [`TEXT_GENERATION_SERVICE.md`](./TEXT_GENERATION_SERVICE.md)
+- **Core Client**: [`CORE_CLIENT_SERVICE.md`](./CORE_CLIENT_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### Generation Config
+See: [`domain/entities/README.md`](../domain/entities/README.md)
+
+### Model Selection
+See: [`FEATURE_MODEL_SELECTOR_SERVICE.md`](./FEATURE_MODEL_SELECTOR_SERVICE.md)
+
+### Error Types
+See: [`ERROR_UTILITIES.md`](../infrastructure/utils/ERROR_UTILITIES.md)
+
+## 🎓 Usage Patterns
+
+### Basic Streaming
+1. Import service
+2. Call `streamText()` with model and prompt
+3. Use `for await` to iterate through chunks
+4. Append each chunk to displayed text
+5. Handle completion or errors
+
+### With UI Updates
+1. Create state for streamed text
+2. Start streaming with `streamText()`
+3. Update state with each chunk
+4. Display progress to user
+5. Handle final chunk and finish reason
+
+### With Cancellation
+1. Start streaming operation
+2. Track cancellation flag
+3. Check flag in stream loop
+4. Break loop if cancelled
+5. Handle cleanup appropriately
+
+### With Error Handling
+1. Wrap stream in try-catch
+2. Check `finishReason` in chunks
+3. Handle SAFETY, MAX_TOKENS reasons
+4. Catch network and timeout errors
+5. Provide user feedback
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Buffer all chunks before displaying (defeats streaming purpose)
+- Ignore finish reasons in final chunk
+- Forget error handling in stream loop
+- Create memory leaks with unbounded buffers
+- Assume streaming is always faster
+
+### Do
+- Update UI with each chunk
+- Check finishReason for completion status
+- Handle stream interruption gracefully
+- Implement buffer size limits
+- Use cancellation for long operations
+- Provide user feedback during streaming
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)