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

package/src/infrastructure/services/VIDEO_GENERATION_SERVICE.md

@@ -0,0 +1,176 @@
+# Video Generation Service
+
+Generates videos from text prompts and images using Google Veo API.
+
+## 📍 Import Path
+
+```
+import { geminiVideoGenerationService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to generate AI-powered videos from text descriptions or images. Supports text-to-video and image-to-video generation with progress tracking using Veo models.
+
+**When to use:**
+- Generate videos from text descriptions
+- Animate existing images
+- Create video content for applications
+- Product visualization and motion graphics
+
+## 📌 Strategy
+
+Video generation is an async, long-running operation that requires special handling. This service:
+- Implements automatic polling for operation status
+- Provides progress callbacks for UI feedback
+- Supports multiple aspect ratios for different platforms
+- Handles video download and URL generation
+- Manages queuing and processing states
+
+**Key Decision**: Video generation uses polling mechanism since processing takes time. The service automatically handles status checks and provides progress updates through callbacks.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider with API key before use
+- **MUST** handle async operation completion
+- **SHOULD** implement progress callbacks for UX
+- **MUST NOT** assume immediate results
+- **MUST** handle video generation errors appropriately
+
+### Prompt Rules
+- **SHOULD** describe motion and action clearly
+- **SHOULD** specify camera movements
+- **MUST NOT** exceed 2000 character limit
+- **SHOULD** include atmosphere and mood details
+
+### Configuration Rules
+- **MUST** use valid model IDs (veo-3.1-fast-generate-preview)
+- **SHOULD** select appropriate aspect ratio for platform
+- **MUST** respect content safety guidelines
+- **SHOULD** set reasonable timeout expectations
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **MUST** check `result.status` for completion
+- **MUST** handle `result.error` for failures
+- **SHOULD** provide user-friendly error messages
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** polling mechanism
+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 video 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 (no callbacks except onProgress)
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `generateTextToVideo(input, onProgress?)`
+
+Generate video from text prompt.
+
+**Refer to**: [`gemini-video-generation.service.ts`](./gemini-video-generation.service.ts)
+
+### `generateVideo(input, onProgress?)`
+
+Generate video from text and/or image.
+
+**Refer to**: [`gemini-video-generation.service.ts`](./gemini-video-generation.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Veo HTTP Client**: [`VEO_HTTP_CLIENT_SERVICE.md`](./VEO_HTTP_CLIENT_SERVICE.md)
+- **Veo Polling**: [`VEO_POLLING_SERVICE.md`](./VEO_POLLING_SERVICE.md)
+- **Video Downloader**: [`VIDEO_DOWNLOADER_SERVICE.md`](./VIDEO_DOWNLOADER_SERVICE.md)
+- **Video Error Handler**: [`VIDEO_ERROR_HANDLER_SERVICE.md`](./VIDEO_ERROR_HANDLER_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### Generation Config
+See: [`domain/entities/README.md`](../domain/entities/README.md)
+
+### Model Selection
+- Current model: `veo-3.1-fast-generate-preview`
+- Aspect ratios: `16:9` | `9:16` | `1:1` | `4:3`
+- Resolution: Up to 4K
+- Duration: Auto-determined by model
+
+### Error Types
+See: [`ERROR_UTILITIES.md`](../infrastructure/utils/ERROR_UTILITIES.md)
+
+## 🎓 Usage Patterns
+
+### Basic Text-to-Video
+1. Import service
+2. Call `generateTextToVideo()` with prompt and options
+3. Provide `onProgress` callback for UI updates
+4. Handle response (contains `videoUrl`, `status`, `progress`)
+5. Display video or handle errors
+
+### Image-to-Video
+1. Import service
+2. Prepare base64-encoded image
+3. Call `generateVideo()` with prompt and image
+4. Monitor progress through callback
+5. Download or display result video
+
+### With Progress Tracking
+1. Implement progress callback function
+2. Update UI with progress percentage and status
+3. Handle status changes: queued → processing → completed/failed
+4. Show appropriate loading states
+5. Display final video or error message
+
+### With Negative Prompts
+1. Prepare main prompt describing desired content
+2. Add negative prompt for unwanted elements
+3. Call generation method with both prompts
+4. Handle result as normal
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume immediate video generation (takes minutes)
+- Ignore progress callbacks (bad UX)
+- Forget to handle failed status
+- Use extremely long prompts (>2000 chars)
+- Expect all videos to have same duration
+
+### Do
+- Implement progress tracking
+- Handle all status states (queued, processing, completed, failed)
+- Provide loading feedback to users
+- Use descriptive prompts with motion details
+- Specify camera movements and atmosphere
+- Handle timeouts appropriately
+- Consider aspect ratio for target platform
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/VIDEO_URL_EXTRACTOR_SERVICE.md

@@ -0,0 +1,186 @@
+# Video URL Extractor Service
+
+Utility for extracting video URLs from Veo API operation responses. Handles multiple response formats from different Veo API versions.
+
+## 📍 Import Path
+
+```
+import { extractVideoUrl } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use video URL extractor to get video URLs from Veo operation responses. Handles multiple API response formats transparently.
+
+**When to use:**
+- Extract video URLs from Veo responses
+- Handle different API versions
+- Parse operation results
+- Get download URLs
+- Process video generation responses
+
+## 📌 Strategy
+
+Veo API has multiple response formats. This utility:
+- Handles all response format variations
+- Extracts URLs transparently
+- Provides null safety
+- Supports API version changes
+- Simplifies response parsing
+
+**Key Decision**: Always use extractor for Veo responses. Handles format variations automatically.
+
+## ⚠️ Rules
+
+### Extraction Rules
+- **MUST** handle all response formats
+- **SHOULD** validate operation object
+- **MUST** return null if URL not found
+- **SHOULD** log unexpected formats
+- **MUST NOT** throw on missing URL
+
+### Validation Rules
+- **SHOULD** check operation structure
+- **MUST** validate URL format
+- **SHOULD** handle null responses
+- **MUST** verify URL accessibility
+- **SHOULD NOT** assume format
+
+### Error Handling Rules
+- **MUST** return null on failure
+- **SHOULD** log parsing errors
+- **MUST NOT** throw exceptions
+- **SHOULD** handle malformed responses
+- **MUST** provide graceful degradation
+
+### URL Handling Rules
+- **MUST** validate URL strings
+- **SHOULD** check URL scheme
+- **MUST** handle authentication requirements
+- **SHOULD NOT** expose sensitive data
+- **MUST** preserve URL parameters
+
+## 🤖 AI Agent Guidelines
+
+### When Extracting URLs
+1. **PROVIDE** operation object
+2. **CALL** extractVideoUrl()
+3. **CHECK** return value
+4. **HANDLE** null result
+5. **USE** URL or report error
+
+### When Handling Missing URLs
+1. **CHECK** if result is null
+2. **LOG** response structure
+3. **VERIFY** operation completed
+4. **REPORT** error to user
+5. **PROVIDE** recovery options
+
+### When Validating Responses
+1. **CHECK** operation object structure
+2. **LOOK** for expected fields
+3. **HANDLE** format variations
+4. **LOG** unexpected formats
+5. **UPDATE** for new API versions
+
+### Code Style Rules
+- **VALIDATE** input structure
+- **HANDLE** all format variations
+- **RETURN** null for missing URLs
+- **LOG** unexpected structures
+- **TEST** with various formats
+
+## 📦 Available Function
+
+### extractVideoUrl
+
+**Refer to**: [`gemini-video-url-extractor.ts`](./gemini-video-url-extractor.ts)
+
+**Parameters:**
+- `operation`: VeoOperation - Veo operation response object
+
+**Returns:** string | null - Video URL if found, otherwise null
+
+## 🔗 Related Modules
+
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Video Downloader**: [`VIDEO_DOWNLOADER_SERVICE.md`](./VIDEO_DOWNLOADER_SERVICE.md)
+- **Veo Polling**: [`VEO_POLLING_SERVICE.md`](./VEO_POLLING_SERVICE.md)
+
+## 📋 Supported Response Formats
+
+### Format 1: New SDK Format
+```typescript
+{
+  response: {
+    generatedVideos: [{
+      video: { uri: "https://..." }
+    }]
+  }
+}
+```
+
+### Format 2: Alternative SDK Format
+```typescript
+{
+  response: {
+    generatedVideos: [{
+      uri: "https://..."
+    }]
+  }
+}
+```
+
+### Format 3: Legacy Format
+```typescript
+{
+  done: true,
+  response: {
+    videoUri: "https://..."
+  }
+}
+```
+
+## 🎓 Usage Patterns
+
+### URL Extraction
+1. Get operation response
+2. Call extractVideoUrl()
+3. Check if URL exists
+4. Use URL for download
+5. Handle missing URL
+
+### Format Handling
+1. Provide operation object
+2. Extract URL transparently
+3. Handle any format variation
+4. Get URL or null
+5. Process result accordingly
+
+### Error Handling
+1. Call extractor
+2. Check for null result
+3. Log response structure if missing
+4. Report error to user
+5. Provide recovery options
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume specific response format
+- Throw on missing URL
+- Skip null checking
+- Hardcode response paths
+- Ignore format variations
+
+### Do
+- Always check for null
+- Handle all formats
+- Log unexpected structures
+- Return null gracefully
+- Test with various responses
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

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)