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

package/src/infrastructure/services/gemini-provider.ts

@@ -23,7 +23,10 @@ import type {
 } from "../../domain/entities";
 import { geminiImageGenerationService } from "./gemini-image-generation.service";
 import { geminiImageEditService } from "./gemini-image-edit.service";
-import { providerInitializer, type GeminiProviderConfig } from "./provider-initializer";
+import {
+  providerInitializer,
+  type GeminiProviderConfig,
+} from "./provider-initializer";
 import { jobProcessor } from "./job-processor";
 import { generationExecutor } from "./generation-executor";
 import { featureInputBuilder } from "./feature-input-builder";
@@ -50,6 +53,7 @@ const GEMINI_CAPABILITIES: ProviderCapabilities = {
   textToVideo: true,
   imageToVideo: true,
   textToVoice: false,
+  textToText: true,
 };
 
 export class GeminiProvider implements IAIProvider {
@@ -76,7 +80,10 @@ export class GeminiProvider implements IAIProvider {
     );
   }
 
-  submitJob(model: string, input: Record<string, unknown>): Promise<JobSubmission> {
+  submitJob(
+    model: string,
+    input: Record<string, unknown>,
+  ): Promise<JobSubmission> {
     return jobProcessor.submitJob(model, input);
   }
 

package/src/infrastructure/telemetry/README.md

@@ -0,0 +1,203 @@
+# Telemetry Module
+
+Monitoring and logging system for AI operations. Tracks request, response, error, and retry events for observability and debugging.
+
+## 📍 Import Path
+
+```
+import { telemetryHooks } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use telemetry to monitor AI operations in real-time. Provides event-based system for tracking performance, errors, and usage patterns.
+
+**When to use:**
+- Monitor API call performance
+- Track error rates and types
+- Analyze usage patterns
+- Debug AI operations
+- Send events to analytics services
+- Implement custom monitoring
+- Track rate limiting
+- Generate metrics
+
+## 📌 Strategy
+
+Telemetry provides visibility into AI operations. This system:
+- Uses publish-subscribe pattern for events
+- Supports multiple listeners simultaneously
+- Emits events for all operations
+- Provides timing and metadata
+- Enables custom monitoring solutions
+- Integrates with analytics platforms
+
+**Key Decision**: Subscribe to telemetry events early in application lifecycle. Use events for monitoring, analytics, and debugging without modifying core services.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** subscribe to events before operations
+- **SHOULD** unsubscribe when done
+- **MUST NOT** emit sensitive data in events
+- **SHOULD** aggregate metrics for performance
+- **MUST** handle listener errors gracefully
+
+### Event Subscription Rules
+- **SHOULD** subscribe at application startup
+- **MUST** store unsubscribe function
+- **SHOULD** handle all event types
+- **MUST NOT** block event emission
+- **SHOULD** filter events as needed
+
+### Data Privacy Rules
+- **MUST NOT** log API keys in events
+- **SHOULD NOT** include user data in metadata
+- **MUST** sanitize sensitive information
+- **SHOULD** use anonymized IDs
+- **MUST** comply with privacy policies
+
+### Performance Rules
+- **SHOULD** keep listeners lightweight
+- **MUST** avoid expensive operations in listeners
+- **SHOULD** batch event processing
+- **MUST NOT** block main thread
+- **SHOULD** use async operations for heavy processing
+
+## 🤖 AI Agent Guidelines
+
+### When Adding Telemetry
+1. **SUBSCRIBE** to telemetry events early
+2. **HANDLE** all event types appropriately
+3. **AGGREGATE** metrics for analysis
+4. **SEND** to monitoring/analytics service
+5. **UNSUBSCRIBE** on cleanup
+
+### When Creating Custom Monitoring
+1. **DEFINE** metrics to track
+2. **CREATE** data structures for aggregation
+3. **IMPLEMENT** event filtering
+4. **CALCULATE** statistics periodically
+5. **EXPORT** metrics for visualization
+
+### When Debugging with Telemetry
+1. **ADD** verbose logging for events
+2. **TRACK** request/response correlation
+3. **MONITOR** error patterns
+4. **ANALYZE** performance metrics
+5. **IDENTIFY** bottlenecks
+
+### Code Style Rules
+- **USE** unsubscribe pattern for cleanup
+- **FILTER** events by type or model
+- **AGGREGATE** metrics efficiently
+- **HANDLE** errors in listeners
+- **LOG** important state changes
+
+## 📦 Available Telemetry
+
+### TelemetryHooks
+
+**Refer to**: [`TelemetryHooks.ts`](./TelemetryHooks.ts)
+
+**Singleton instance**: `telemetryHooks`
+
+**Methods:**
+- `subscribe(listener)` - Add event listener
+- `emit(event)` - Emit custom event
+- `logRequest(model, feature?)` - Log request start
+- `logResponse(model, startTime, feature?, metadata?)` - Log response
+- `logError(model, error, feature?)` - Log error
+- `logRetry(model, attempt, feature?)` - Log retry
+- `clear()` - Clear all listeners
+- `getListenerCount()` - Get active listener count
+
+## 🔗 Related Modules
+
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Services**: [`../services/README.md`](../services/README.md)
+- **Interceptors**: [`../interceptors/README.md`](../interceptors/README.md)
+
+## 📋 Event Types
+
+### Request Event
+Emitted when operation starts.
+- Contains model and feature
+- Includes timestamp
+- No duration yet
+
+### Response Event
+Emitted when operation completes.
+- Contains model and feature
+- Includes duration in milliseconds
+- May include metadata (token count, finish reason)
+
+### Error Event
+Emitted when operation fails.
+- Contains model and feature
+- Includes error information
+- May include error type
+
+### Retry Event
+Emitted when retry is attempted.
+- Contains model and feature
+- Includes attempt number
+- Tracks retry behavior
+
+## 🎓 Usage Patterns
+
+### Basic Monitoring
+1. Import `telemetryHooks`
+2. Subscribe to events with listener function
+3. Handle different event types
+4. Store unsubscribe function
+5. Unsubscribe on cleanup
+
+### Analytics Integration
+1. Subscribe to telemetry events
+2. Transform events to analytics format
+3. Send to analytics service
+4. Filter sensitive information
+5. Handle errors gracefully
+
+### Performance Tracking
+1. Track response times by model
+2. Calculate statistics (avg, min, max)
+3. Monitor trends over time
+4. Alert on slow operations
+5. Generate performance reports
+
+### Error Tracking
+1. Subscribe to error events
+2. Categorize errors by type
+3. Track error rates
+4. Send to error tracking service
+5. Monitor for anomalies
+
+### Custom Dashboard
+1. Aggregate event data
+2. Calculate statistics
+3. Track model usage
+4. Monitor success rates
+5. Generate dashboard metrics
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Forget to unsubscribe from events
+- Log sensitive data in events
+- Block event emission with heavy processing
+- Subscribe multiple times without cleanup
+- Emit custom events without proper format
+
+### Do
+- Subscribe early in application lifecycle
+- Clean up listeners when done
+- Keep listeners lightweight
+- Aggregate metrics efficiently
+- Handle all event types appropriately
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/telemetry/TELEMETRY_SYSTEM.md

@@ -0,0 +1,200 @@
+# Telemetry System
+
+Monitoring and logging system for AI operations. Allows applications to track requests, responses, errors, and retries in real-time.
+
+## 📍 Import Path
+
+```
+import { telemetryHooks } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use telemetry to monitor AI operations in real-time. Provides event-based system for tracking performance, errors, and usage patterns.
+
+**When to use:**
+- Monitor API call performance
+- Track error rates and types
+- Analyze usage patterns
+- Debug AI operations
+- Send events to analytics services
+- Track rate limiting
+
+## 📌 Strategy
+
+Telemetry provides visibility into AI operations. This system:
+- Uses publish-subscribe pattern for events
+- Supports multiple listeners simultaneously
+- Emits events for all operations
+- Provides timing and metadata
+- Enables custom monitoring solutions
+
+**Key Decision**: Subscribe to telemetry events early in application lifecycle. Use events for monitoring, analytics, and debugging.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** subscribe to events before operations
+- **SHOULD** unsubscribe when done
+- **MUST NOT** emit sensitive data in events
+- **SHOULD** aggregate metrics for performance
+- **MUST** handle listener errors gracefully
+
+### Event Subscription Rules
+- **SHOULD** subscribe at application startup
+- **MUST** store unsubscribe function
+- **SHOULD** handle all event types
+- **MUST NOT** block event emission
+- **SHOULD** filter events as needed
+
+### Data Privacy Rules
+- **MUST NOT** log API keys in events
+- **SHOULD NOT** include user data in metadata
+- **MUST** sanitize sensitive information
+- **SHOULD** use anonymized IDs
+- **MUST** comply with privacy policies
+
+### Performance Rules
+- **SHOULD** keep listeners lightweight
+- **MUST** avoid expensive operations in listeners
+- **SHOULD** batch event processing
+- **MUST NOT** block main thread
+- **SHOULD** use async operations for heavy processing
+
+## 🤖 AI Agent Guidelines
+
+### When Adding Telemetry
+1. **SUBSCRIBE** to telemetry events early
+2. **HANDLE** all event types appropriately
+3. **AGGREGATE** metrics for analysis
+4. **SEND** to monitoring/analytics service
+5. **UNSUBSCRIBE** on cleanup
+
+### When Creating Custom Monitoring
+1. **DEFINE** metrics to track
+2. **CREATE** data structures for aggregation
+3. **IMPLEMENT** event filtering
+4. **CALCULATE** statistics periodically
+5. **EXPORT** metrics for visualization
+
+### When Debugging with Telemetry
+1. **ADD** verbose logging for events
+2. **TRACK** request/response correlation
+3. **MONITOR** error patterns
+4. **ANALYZE** performance metrics
+5. **IDENTIFY** bottlenecks
+
+### Code Style Rules
+- **USE** unsubscribe pattern for cleanup
+- **FILTER** events by type or model
+- **AGGREGATE** metrics efficiently
+- **HANDLE** errors in listeners
+- **LOG** important state changes
+
+## 📦 Available System
+
+### telemetryHooks
+
+**Refer to**: [`TelemetryHooks.ts`](./TelemetryHooks.ts)
+
+**Singleton instance**
+
+**Methods:**
+- `subscribe(listener)` - Add event listener
+- `emit(event)` - Emit custom event
+- `logRequest(model, feature?)` - Log request start
+- `logResponse(model, startTime, feature?, metadata?)` - Log response
+- `logError(model, error, feature?)` - Log error
+- `logRetry(model, attempt, feature?)` - Log retry
+- `clear()` - Clear all listeners
+- `getListenerCount()` - Get active listener count
+
+## 🔗 Related Modules
+
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Services**: [`../services/README.md`](../services/README.md)
+- **Interceptors**: [`../interceptors/README.md`](../interceptors/README.md)
+
+## 📋 Event Types
+
+### Request Event
+Emitted when operation starts.
+- Contains model and feature
+- Includes timestamp
+- No duration yet
+
+### Response Event
+Emitted when operation completes.
+- Contains model and feature
+- Includes duration in milliseconds
+- May include metadata (token count, finish reason)
+
+### Error Event
+Emitted when operation fails.
+- Contains model and feature
+- Includes error information
+- May include error type
+
+### Retry Event
+Emitted when retry is attempted.
+- Contains model and feature
+- Includes attempt number
+- Tracks retry behavior
+
+## 🎓 Usage Patterns
+
+### Basic Monitoring
+1. Subscribe to telemetry events
+2. Track metrics in event handler
+3. Send to analytics/monitoring service
+4. Aggregate and analyze metrics
+5. Unsubscribe when done
+
+### Analytics Integration
+1. Subscribe to telemetry events
+2. Transform events to analytics format
+3. Send to analytics service
+4. Filter sensitive information
+5. Handle errors gracefully
+
+### Performance Tracking
+1. Track response times by model
+2. Calculate statistics (avg, min, max)
+3. Monitor trends over time
+4. Alert on slow operations
+5. Generate performance reports
+
+### Error Tracking
+1. Subscribe to error events
+2. Categorize errors by type
+3. Track error rates
+4. Send to error tracking service
+5. Monitor for anomalies
+
+### Custom Dashboard
+1. Aggregate event data
+2. Calculate statistics
+3. Track model usage
+4. Monitor success rates
+5. Generate dashboard metrics
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Forget to unsubscribe from events
+- Log sensitive data in events
+- Block event emission with heavy processing
+- Subscribe multiple times without cleanup
+- Emit custom events without proper format
+
+### Do
+- Subscribe early in application lifecycle
+- Clean up listeners when done
+- Keep listeners lightweight
+- Aggregate telemetry metrics
+- Handle all event types appropriately
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/utils/DATA_TRANSFORMER_UTILS.md

@@ -0,0 +1,175 @@
+# Data Transformer Utilities
+
+Helper functions for transforming and processing Gemini API data. Extracts and converts data formats.
+
+## 📍 Import Path
+
+```
+import {
+  extractBase64Data,
+  extractTextFromResponse
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use data transformers to extract and convert Gemini API data formats. Handles base64 extraction and text parsing.
+
+**When to use:**
+- Extract base64 from data URLs
+- Parse text from API responses
+- Clean up data formats
+- Transform response structures
+- Process multimodal data
+
+## 📌 Strategy
+
+Data transformation ensures compatibility. This system:
+- Extracts base64 from various formats
+- Parses text from complex responses
+- Handles missing data gracefully
+- Normalizes data structures
+- Simplifies data processing
+
+**Key Decision**: Always use transformers for data extraction. Handles edge cases and format variations automatically.
+
+## ⚠️ Rules
+
+### Extraction Rules
+- **MUST** handle missing data gracefully
+- **SHOULD** validate input format
+- **MUST** return empty string on failure
+- **SHOULD** log extraction errors
+- **MUST NOT** throw on invalid data
+
+### Format Rules
+- **MUST** support multiple input formats
+- **SHOULD** detect format automatically
+- **MUST** preserve data integrity
+- **SHOULD** handle encoding correctly
+- **MUST NOT** corrupt data
+
+### Validation Rules
+- **SHOULD** validate base64 before use
+- **MUST** check for empty responses
+- **SHOULD** handle malformed data
+- **MUST** provide safe defaults
+- **SHOULD NOT** assume format
+
+### Error Handling Rules
+- **MUST** wrap extraction in try-catch
+- **SHOULD** log transformation errors
+- **MUST** return safe defaults
+- **SHOULD NOT** propagate errors
+- **MUST** handle all edge cases
+
+## 🤖 AI Agent Guidelines
+
+### When Extracting Base64
+1. **CALL** extractBase64Data()
+2. **PROVIDE** data URL or base64
+3. **GET** pure base64 string
+4. **VALIDATE** output
+5. **HANDLE** extraction errors
+
+### When Extracting Text
+1. **CALL** extractTextFromResponse()
+2. **PROVIDE** Gemini response object
+3. **GET** concatenated text
+4. **CHECK** for empty results
+5. **HANDLE** missing text
+
+### When Transforming Data
+1. **VALIDATE** input format
+2. **CALL** appropriate transformer
+3. **CHECK** output validity
+4. **USE** transformed data
+5. **HANDLE** transformation errors
+
+### Code Style Rules
+- **VALIDATE** input before transformation
+- **HANDLE** all edge cases
+- **PROVIDE** safe defaults
+- **LOG** transformation errors
+- **TEST** with various formats
+
+## 📦 Available Functions
+
+**Refer to**: [`gemini-data-transformer.util.ts`](./gemini-data-transformer.util.ts)
+
+### Base64 Extraction
+- `extractBase64Data(base64)` - Extract base64 from data URL
+
+### Text Extraction
+- `extractTextFromResponse(response)` - Extract text from Gemini response
+
+## 🔗 Related Modules
+
+- **Domain Entities**: [`../../domain/entities/README.md`](../../domain/entities/README.md)
+- **Image Edit Service**: [`../services/IMAGE_EDIT_SERVICE.md`](../services/IMAGE_EDIT_SERVICE.md)
+- **Response Formatter**: [`../response/RESPONSE_FORMATTER.md`](../response/RESPONSE_FORMATTER.md)
+
+## 📋 Supported Formats
+
+### Base64 Input Formats
+- Data URL: `data:image/png;base64,iVBORw0KG...`
+- Pure base64: `iVBORw0KG...`
+- Various MIME types: PNG, JPEG, GIF, WebP
+
+### Response Structure
+```typescript
+{
+  candidates: [{
+    content: {
+      parts: [
+        { text: string },
+        { inlineData: { mimeType: string; data: string } }
+      ]
+    }
+  }]
+}
+```
+
+## 🎓 Usage Patterns
+
+### Base64 Extraction
+1. Provide data URL or base64
+2. Call extractBase64Data()
+3. Get pure base64 string
+4. Use in API requests
+5. Handle empty results
+
+### Text Extraction
+1. Provide Gemini response object
+2. Call extractTextFromResponse()
+3. Get concatenated text
+4. Use extracted text
+5. Handle empty responses
+
+### Data Processing
+1. Validate input format
+2. Transform with utilities
+3. Validate output
+4. Use in application
+5. Handle errors gracefully
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume data format
+- Skip validation
+- Throw on invalid data
+- Ignore empty responses
+- Corrupt data during transformation
+
+### Do
+- Validate input format
+- Handle all edge cases
+- Provide safe defaults
+- Test with various formats
+- Handle errors gracefully
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)