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

package/src/infrastructure/job/README.md

@@ -0,0 +1,194 @@
+# Job Manager
+
+Async job submission, tracking, and status management service. Manages long-running operations with polling capability.
+
+## 📍 Import Path
+
+```
+import {
+  JobManager,
+  AIJobStatusType
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use job manager to handle async operations that take time to complete. Provides job lifecycle management, status tracking, and result retrieval.
+
+**When to use:**
+- Submit long-running AI operations
+- Track job status over time
+- Implement polling for completion
+- Manage async job lifecycles
+- Handle batch processing
+- Monitor job progress
+- Retrieve results when ready
+
+## 📌 Strategy
+
+Job manager abstracts async operation complexity. This system:
+- Generates unique job IDs
+- Tracks job status through lifecycle
+- Stores results for retrieval
+- Handles errors gracefully
+- Supports status polling
+- Manages job completion
+
+**Key Decision**: Use job manager for video generation and other long-running operations. Poll for status instead of blocking.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** save job ID after submission
+- **SHOULD** check job status before getting result
+- **MUST** handle job completion and failure
+- **SHOULD** implement polling for long operations
+- **MUST NOT** lose job IDs
+
+### Job Lifecycle Rules
+- **JOBS** start as IN_QUEUE
+- **MUST** update status through lifecycle
+- **SHOULD** set result or error on completion
+- **MUST** handle all status transitions
+- **SHOULD** clean up completed jobs
+
+### Error Handling Rules
+- **MUST** set job error on failure
+- **SHOULD** propagate errors to callers
+- **MUST** handle timeout scenarios
+- **SHOULD** log job failures
+- **MUST NOT** leave jobs in invalid state
+
+### Polling Rules
+- **SHOULD** poll with appropriate intervals
+- **MUST** implement timeout for polling
+- **SHOULD** handle polling errors
+- **MUST** stop polling on completion
+- **SHOULD NOT** poll too frequently
+
+## 🤖 AI Agent Guidelines
+
+### When Submitting Jobs
+1. **CALL** submitJob() with model and input
+2. **SAVE** returned job ID
+3. **TRACK** job status
+4. **HANDLE** completion/error
+5. **RETRIEVE** result when ready
+
+### When Polling Jobs
+1. **IMPLEMENT** polling loop with timeout
+2. **CHECK** job status each iteration
+3. **WAIT** between polls (exponential backoff)
+4. **RETURN** result on completion
+5. **THROW** on timeout or failure
+
+### When Managing Job Lifecycle
+1. **UPDATE** status appropriately
+2. **SET** result on success
+3. **SET** error on failure
+4. **VERIFY** state transitions
+5. **CLEAN UP** old jobs
+
+### Code Style Rules
+- **USE** descriptive job inputs
+- **HANDLE** all job status cases
+- **IMPLEMENT** polling with timeout
+- **LOG** job state changes
+- **VALIDATE** job IDs
+
+## 📦 Available Classes
+
+### JobManager
+
+**Refer to**: [`JobManager.ts`](./JobManager.ts)
+
+**Methods:**
+- `submitJob(model, input)` - Submit new job
+- `getJobStatus(requestId)` - Get job status
+- `getJobResult(requestId)` - Get job result
+- `updateJobStatus(requestId, status)` - Update job status
+- `setJobResult(requestId, result)` - Set job result
+- `setJobError(requestId, error)` - Set job error
+- `getJob(requestId)` - Get job details
+- `clear()` - Clear all jobs
+
+## 🔗 Related Modules
+
+- **Video Generation Service**: [`../services/VIDEO_GENERATION_SERVICE.md`](../services/VIDEO_GENERATION_SERVICE.md)
+- **Services README**: [`../services/README.md`](../services/README.md)
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+
+## 📋 Job Status Types
+
+### 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.
+
+### CANCELLED
+Job was cancelled before completion.
+
+## 🎓 Usage Patterns
+
+### Basic Job Submission
+1. Create JobManager instance
+2. Call submitJob() with model and input
+3. Store returned job ID
+4. Monitor job status
+5. Retrieve result when complete
+
+### Status Polling
+1. Submit job and get ID
+2. Poll job status periodically
+3. Check for COMPLETED or FAILED
+4. Implement timeout
+5. Return result or throw error
+
+### Batch Processing
+1. Submit multiple jobs
+2. Store all job IDs
+3. Poll all jobs in parallel
+4. Collect all results
+5. Return batch results
+
+### Job Lifecycle Management
+1. Submit job to manager
+2. Update status to PROCESSING
+3. Perform operation
+4. Set result or error
+5. Handle completion
+
+### Error Recovery
+1. Submit job with retry logic
+2. Monitor job status
+3. On failure, check error type
+4. Retry if appropriate
+5. Handle permanent failures
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Lose job ID after submission
+- Call getJobResult() without checking status
+- Poll too frequently
+- Forget to implement timeout
+- Leave completed jobs in queue
+
+### Do
+- Always save job ID
+- Check status before getting result
+- Use exponential backoff for polling
+- Implement timeout for polling
+- Clean up completed jobs
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/response/README.md

@@ -0,0 +1,187 @@
+# Response Module
+
+Response formatting and transformation utilities for Gemini API responses. Provides consistent response structures.
+
+## 📍 Import Path
+
+```
+import {
+  ResponseFormatter
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use response module to format and transform Gemini API responses consistently. Extracts text and image data from responses.
+
+**When to use:**
+- Format API responses consistently
+- Extract text from responses
+- Extract image data from multimodal responses
+- Normalize response structures
+- Handle response types safely
+
+## 📌 Strategy
+
+Response formatting ensures consistency. This module:
+- Extracts text content automatically
+- Handles image data in responses
+- Provides typed response structures
+- Preserves original response
+- Simplifies response handling
+
+**Key Decision**: Always format responses before using. Provides consistent interface for different response types.
+
+## ⚠️ Rules
+
+### Formatting Rules
+- **MUST** format all API responses
+- **SHOULD** specify expected response type
+- **MUST** check for optional fields
+- **SHOULD** preserve original response
+- **MUST NOT** assume response structure
+
+### Type Safety Rules
+- **SHOULD** use generic type parameter
+- **MUST** check for optional fields
+- **SHOULD** use type guards
+- **MUST** handle undefined values
+- **SHOULD NOT** use non-null assertion
+
+### Data Extraction Rules
+- **MUST** handle missing text gracefully
+- **SHOULD** validate image data
+- **MUST** check for image presence
+- **SHOULD** extract MIME type correctly
+- **MUST NOT** fail on partial data
+
+### Error Handling Rules
+- **SHOULD** wrap formatting in try-catch
+- **MUST** handle malformed responses
+- **SHOULD** log formatting errors
+- **MUST** provide fallback values
+- **SHOULD NOT** throw formatting errors
+
+## 🤖 AI Agent Guidelines
+
+### When Formatting Responses
+1. **CREATE** ResponseFormatter instance
+2. **CALL** formatResponse() with type
+3. **CHECK** for optional fields
+4. **EXTRACT** needed data
+5. **HANDLE** missing data gracefully
+
+### When Handling Text Responses
+1. **FORMAT** response with text type
+2. **CHECK** text field exists
+3. **VALIDATE** text not empty
+4. **USE** text value
+5. **HANDLE** empty text case
+
+### When Handling Image Responses
+1. **FORMAT** response with image type
+2. **CHECK** imageUrl exists
+3. **EXTRACT** imageBase64 if needed
+4. **USE** MIME type correctly
+5. **HANDLE** missing image case
+
+### Code Style Rules
+- **USE** generic type parameter
+- **CHECK** optional fields before use
+- **PROVIDE** fallback values
+- **LOG** formatting issues
+- **PRESERVE** original response
+
+## 📦 Available Classes
+
+### ResponseFormatter
+
+**Refer to**: [`ResponseFormatter.ts`](./ResponseFormatter.ts)
+
+**Methods:**
+- `formatResponse<T>(response, input)` - Format response to typed structure
+
+## 🔗 Related Modules
+
+- **Text Generation**: [`../services/TEXT_GENERATION_SERVICE.md`](../services/TEXT_GENERATION_SERVICE.md)
+- **Image Generation**: [`../services/IMAGE_GENERATION_SERVICE.md`](../services/IMAGE_GENERATION_SERVICE.md)
+- **Data Transformer**: [`../utils/DATA_TRANSFORMER_UTILS.md`](../utils/DATA_TRANSFORMER_UTILS.md)
+
+## 📋 Response Types
+
+### Text Response
+```typescript
+{
+  text: string;              // Extracted text content
+  response: unknown;         // Original API response
+}
+```
+
+### Multimodal Response
+```typescript
+{
+  text: string;              // Extracted text content
+  imageUrl: string;          // Data URL (data:image/png;base64,...)
+  imageBase64: string;       // Base64 image data
+  mimeType: string;          // Image MIME type
+  response: unknown;         // Original API response
+}
+```
+
+## 🎓 Usage Patterns
+
+### Basic Formatting
+1. Create ResponseFormatter instance
+2. Call formatResponse() with type
+3. Extract needed fields
+4. Check for optional data
+5. Handle response appropriately
+
+### Text Response Handling
+1. Format response as text type
+2. Check text field exists
+3. Validate text content
+4. Use text in application
+5. Handle empty text case
+
+### Image Response Handling
+1. Format response with image type
+2. Check imageUrl exists
+3. Extract imageBase64 if needed
+4. Use imageUrl for display
+5. Handle missing image case
+
+### Multimodal Handling
+1. Format response
+2. Check for both text and image
+3. Handle different response types
+4. Display appropriate content
+5. Fallback to available data
+
+### Type-Safe Formatting
+1. Define response interface
+2. Format with generic type
+3. Use type guards
+4. Narrow response type
+5. Use typed data safely
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume text field always exists
+- Use imageUrl without checking
+- Discard original response
+- Use non-null assertions
+- Skip type checking
+
+### Do
+- Always check optional fields
+- Validate data before use
+- Preserve original response
+- Use type guards
+- Handle missing data gracefully
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/response/RESPONSE_FORMATTER.md

@@ -0,0 +1,185 @@
+# Response Formatter
+
+Utility for formatting Gemini API responses into consistent output structures. Handles text and image data extraction from API responses.
+
+## 📍 Import Path
+
+```
+import { ResponseFormatter } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use ResponseFormatter to convert raw Gemini API responses into consistent, typed structures. Extracts text and image data automatically.
+
+**When to use:**
+- Format API responses consistently
+- Extract text from responses
+- Extract image data from multimodal responses
+- Normalize response structures
+- Handle response types safely
+
+## 📌 Strategy
+
+Response formatting ensures consistency. This utility:
+- Extracts text content automatically
+- Handles image data in responses
+- Provides typed response structures
+- Preserves original response
+- Simplifies response handling
+
+**Key Decision**: Always format responses before using. Provides consistent interface for different response types.
+
+## ⚠️ Rules
+
+### Formatting Rules
+- **MUST** format all API responses
+- **SHOULD** specify expected response type
+- **MUST** check for optional fields
+- **SHOULD** preserve original response
+- **MUST NOT** assume response structure
+
+### Type Safety Rules
+- **SHOULD** use generic type parameter
+- **MUST** check for optional fields
+- **SHOULD** use type guards
+- **MUST** handle undefined values
+- **SHOULD NOT** use non-null assertion
+
+### Data Extraction Rules
+- **MUST** handle missing text gracefully
+- **SHOULD** validate image data
+- **MUST** check for image presence
+- **SHOULD** extract MIME type correctly
+- **MUST NOT** fail on partial data
+
+### Error Handling Rules
+- **SHOULD** wrap formatting in try-catch
+- **MUST** handle malformed responses
+- **SHOULD** log formatting errors
+- **MUST** provide fallback values
+- **SHOULD NOT** throw formatting errors
+
+## 🤖 AI Agent Guidelines
+
+### When Formatting Responses
+1. **CREATE** ResponseFormatter instance
+2. **CALL** formatResponse() with type
+3. **CHECK** for optional fields
+4. **EXTRACT** needed data
+5. **HANDLE** missing data gracefully
+
+### When Handling Text Responses
+1. **FORMAT** response with text type
+2. **CHECK** text field exists
+3. **VALIDATE** text not empty
+4. **USE** text value
+5. **HANDLE** empty text case
+
+### When Handling Image Responses
+1. **FORMAT** response with image type
+2. **CHECK** imageUrl exists
+3. **EXTRACT** imageBase64 data
+4. **USE** MIME type correctly
+5. **HANDLE** missing image case
+
+### Code Style Rules
+- **USE** generic type parameter
+- **CHECK** optional fields before use
+- **PROVIDE** fallback values
+- **LOG** formatting issues
+- **PRESERVE** original response
+
+## 📦 Available Class
+
+### ResponseFormatter
+
+**Refer to**: [`ResponseFormatter.ts`](./ResponseFormatter.ts)
+
+**Methods:**
+- `formatResponse<T>(response, input)` - Format response to typed structure
+
+## 🔗 Related Modules
+
+- **Text Generation Service**: [`../services/TEXT_GENERATION_SERVICE.md`](../services/TEXT_GENERATION_SERVICE.md)
+- **Image Generation Service**: [`../services/IMAGE_GENERATION_SERVICE.md`](../services/IMAGE_GENERATION_SERVICE.md)
+- **Generation Executor**: [`../services/GENERATION_EXECUTOR_SERVICE.md`](../services/GENERATION_EXECUTOR_SERVICE.md)
+
+## 📋 Response Types
+
+### Text Response
+```typescript
+{
+  text: string;              // Extracted text content
+  response: unknown;         // Original API response
+}
+```
+
+### Multimodal Response
+```typescript
+{
+  text: string;              // Extracted text content
+  imageUrl: string;          // Data URL (data:image/png;base64,...)
+  imageBase64: string;       // Base64 image data
+  mimeType: string;          // Image MIME type
+  response: unknown;         // Original API response
+}
+```
+
+## 🎓 Usage Patterns
+
+### Basic Formatting
+1. Create ResponseFormatter instance
+2. Call formatResponse() with type
+3. Extract needed fields
+4. Check for optional data
+5. Handle response appropriately
+
+### Text Response Handling
+1. Format response as text type
+2. Check text field exists
+3. Validate text content
+4. Use text in application
+5. Handle empty text case
+
+### Image Response Handling
+1. Format response with image type
+2. Check imageUrl exists
+3. Extract imageBase64 if needed
+4. Use imageUrl for display
+5. Handle missing image case
+
+### Multimodal Handling
+1. Format response
+2. Check for both text and image
+3. Handle different response types
+4. Display appropriate content
+5. Fallback to available data
+
+### Type-Safe Formatting
+1. Define response interface
+2. Format with generic type
+3. Use type guards
+4. Narrow response type
+5. Use typed data safely
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume text field always exists
+- Use imageUrl without checking
+- Discard original response
+- Use non-null assertions
+- Skip type checking
+
+### Do
+- Always check optional fields
+- Validate data before use
+- Preserve original response
+- Use type guards
+- Handle missing data gracefully
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)