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

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)

package/src/infrastructure/services/STRUCTURED_TEXT_SERVICE.md

@@ -0,0 +1,175 @@
+# Structured Text Generation Service
+
+Generates structured JSON output with schema validation. Produces type-safe content with defined structure.
+
+## 📍 Import Path
+
+```
+import { geminiStructuredTextService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to generate AI responses in structured JSON format with type safety and schema validation.
+
+**When to use:**
+- Generate JSON with specific structure
+- Create type-safe AI responses
+- Extract structured data from text
+- Build forms and data entry with AI
+- Generate configuration objects
+
+## 📌 Strategy
+
+Structured generation ensures type safety and validates output. This service:
+- Accepts JSON schema for output validation
+- Returns typed responses matching schema
+- Validates AI-generated JSON structure
+- Provides type-safe interfaces
+- Handles parsing and validation errors
+
+**Key Decision**: Use JSON Schema for validation. The service validates AI output against the schema and returns typed results, ensuring data integrity.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider with API key before use
+- **MUST** provide valid JSON schema
+- **SHOULD** define TypeScript interfaces for type safety
+- **MUST** handle schema validation errors
+- **SHOULD** specify required vs optional fields
+
+### Schema Rules
+- **MUST** use valid JSON Schema format
+- **SHOULD** include field descriptions
+- **MUST** specify required fields explicitly
+- **SHOULD** use appropriate types (string, number, boolean, array, object)
+- **MUST NOT** create overly complex nested schemas
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **MUST** handle PARSING_ERROR for invalid JSON
+- **MUST** handle VALIDATION errors for schema mismatches
+- **SHOULD** provide fallback values when appropriate
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** schema validation 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** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `generateStructuredText<T>(model, prompt, schema, config?)`
+
+Generate structured JSON output based on provided schema.
+
+**Refer to**: [`gemini-structured-text.service.ts`](./gemini-structured-text.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Text Generation**: [`TEXT_GENERATION_SERVICE.md`](./TEXT_GENERATION_SERVICE.md)
+- **Error Utilities**: [`ERROR_UTILITIES.md`](../infrastructure/utils/ERROR_UTILITIES.md)
+
+## 📋 Configuration Reference
+
+### JSON Schema Format
+
+```typescript
+{
+  type: 'object',
+  properties: {
+    fieldName: {
+      type: 'string' | 'number' | 'boolean' | 'array' | 'object',
+      description?: string,
+      enum?: string[]
+    }
+  },
+  required: string[]
+}
+```
+
+### Schema Best Practices
+- Use detailed field descriptions
+- Specify required fields explicitly
+- Use appropriate data types
+- Define nested objects clearly
+- Add enum constraints for fixed values
+
+## 🎓 Usage Patterns
+
+### Simple JSON Generation
+1. Define TypeScript interface for result
+2. Create JSON schema matching interface
+3. Call `generateStructuredText()` with prompt and schema
+4. Receive typed result matching schema
+5. Handle validation errors if schema mismatch
+
+### Nested Objects
+1. Define nested interfaces
+2. Create nested schema structure
+3. Specify required fields at each level
+4. Generate and validate nested structure
+5. Handle result as typed object
+
+### Array Output Schema
+1. Define interface with array properties
+2. Create schema with array item types
+3. Specify array item structure
+4. Generate and validate array results
+5. Use typed results in application
+
+### Enum Validation
+1. Define interface with enum-like fields
+2. Create schema with enum constraints
+3. Specify allowed values
+4. Generate and validate against enum
+5. Handle type-safe results
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use minimal schemas without descriptions
+- Make all fields required (too strict)
+- Use `any` type instead of proper interfaces
+- Create overly complex nested schemas
+- Ignore validation errors
+
+### Do
+- Provide detailed field descriptions
+- Explicitly mark required vs optional fields
+- Use TypeScript interfaces for type safety
+- Test schemas with sample data
+- Handle parsing and validation errors
+- Use fallback values for non-critical fields
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/TEXT_GENERATION_SERVICE.md

@@ -0,0 +1,160 @@
+# Text Generation Service
+
+Generates text content using Google Gemini API models.
+
+## 📍 Import Path
+
+```
+import { geminiTextGenerationService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to generate AI-powered text content. Supports single prompts, conversational interfaces, and multimodal input with images.
+
+**When to use:**
+- Text generation (stories, summaries, translations)
+- Chat interfaces and conversational AI
+- Content analysis with images
+- Any text-based AI generation task
+
+## 📌 Strategy
+
+Text generation is the foundation of most AI interactions. This service:
+- Abstracts Gemini API complexity
+- Provides type-safe interfaces
+- Handles errors consistently
+- Supports streaming for real-time responses
+- Integrates with retry logic
+
+**Key Decision**: We use streaming by default for better UX, but fallback to non-streaming for compatibility.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider with API key before use
+- **MUST** handle errors appropriately
+- **MUST** validate model IDs before use
+- **SHOULD** use streaming for long responses
+- **MUST NOT** exceed rate limits
+
+### Configuration Rules
+- **MUST** set appropriate `maxOutputTokens`
+- **SHOULD** adjust `temperature` based on use case
+- **MUST** use valid model IDs
+- **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** current error handling
+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** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `generateText(model, prompt, config?)`
+Generate text from a prompt.
+
+**Refer to**: [`gemini-text-generation.service.ts`](./gemini-text-generation.service.ts)
+
+### `generateContent(model, contents, config?)`
+Generate content with structured messages.
+
+**Refer to**: [`gemini-text-generation.service.ts`](./gemini-text-generation.service.ts)
+
+### `generateWithImages(model, prompt, images, config?)`
+Generate text with image context.
+
+**Refer to**: [`gemini-text-generation.service.ts`](./gemini-text-generation.service.ts)
+
+### `generateTextStream(model, prompt, config?)`
+Generate text with streaming response.
+
+**Refer to**: [`gemini-text-generation.service.ts`](./gemini-text-generation.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Image Generation**: [`IMAGE_GENERATION_SERVICE.md`](./IMAGE_GENERATION_SERVICE.md)
+- **Retry Service**: [`RETRY_SERVICE.md`](./RETRY_SERVICE.md)
+- **Streaming Service**: [`STREAMING_SERVICE.md`](./STREAMING_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 Generation
+1. Import service
+2. Call `generateText()` with model and prompt
+3. Handle response or error
+4. Display result to user
+
+### With Retry Logic
+1. Use retry service wrapper
+2. Configure max retries and delays
+3. Handle retryable errors
+4. Provide feedback to user
+
+### Streaming
+1. Use `generateTextStream()`
+2. Handle chunks in callback
+3. Update UI progressively
+4. Handle stream completion
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use hardcoded model IDs
+- Ignore error handling
+- Exceed rate limits
+- Skip initialization
+
+### Do
+- Use feature model selector
+- Handle all errors
+- Implement backoff
+- Initialize provider
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)