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

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)

package/src/infrastructure/services/VEO_HTTP_CLIENT_SERVICE.md

@@ -0,0 +1,179 @@
+# Veo HTTP Client Service
+
+Makes HTTP requests to Google Veo API for video generation. Initiates video generation operations and queries status.
+
+## 📍 Import Path
+
+```
+import { veoHttpClient } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to communicate directly with Veo API for video generation operations. Handles HTTP requests for starting and polling video generation.
+
+**When to use:**
+- Start video generation operations
+- Query operation status
+- Access raw Veo API responses
+- Implement custom polling logic
+- Debug video generation issues
+
+## 📌 Strategy
+
+Veo API uses asynchronous operations with polling. This service:
+- Sends HTTP requests to Veo API endpoints
+- Initiates video generation operations
+- Queries operation status
+- Returns raw API responses
+- Implements retry logic for network failures
+
+**Key Decision**: Use `veo-polling.service.ts` for automatic polling instead of manually polling with this service. This service is for advanced use cases requiring custom polling logic.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** provide valid API key
+- **MUST** use valid Veo model IDs
+- **SHOULD** save operation names for polling
+- **MUST** handle network errors appropriately
+- **SHOULD NOT** poll manually (use polling service)
+
+### Request Rules
+- **MUST** provide prompt in instances array
+- **SHOULD** set appropriate aspect ratio
+- **MUST** use supported parameters
+- **SHOULD** include negative prompt when needed
+- **MUST NOT** exceed request size limits
+
+### Error Handling Rules
+- **MUST** catch and handle HTTP errors
+- **SHOULD** check operation error field
+- **MUST** validate operation responses
+- **SHOULD** implement retry logic for failures
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** Veo API structure
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if feature exists in Veo API
+2. **FOLLOW** existing request 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** HTTP requests in development
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `startOperation(model, apiKey, instances, parameters)`
+
+Initiate video generation operation.
+
+**Refer to**: [`veo-http-client.service.ts`](./veo-http-client.service.ts)
+
+### `getOperation(operationName, apiKey, model)`
+
+Query operation status.
+
+**Refer to**: [`veo-http-client.service.ts`](./veo-http-client.service.ts)
+
+## 🔗 Related Modules
+
+- **Veo Polling**: [`VEO_POLLING_SERVICE.md`](./VEO_POLLING_SERVICE.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Video Downloader**: [`VIDEO_DOWNLOADER_SERVICE.md`](./VIDEO_DOWNLOADER_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### VeoOperation
+
+Operation response structure defined in: [`domain/entities/README.md`](../domain/entities/README.md)
+
+**Fields:**
+- `name`: string - Operation full path
+- `done`: boolean - Completion status
+- `response`: object - Video data (when complete)
+- `metadata`: object - Progress information
+- `error`: object - Error details (if failed)
+
+### API Endpoints
+
+**Start Operation:**
+- Method: POST
+- URL: `https://generativelanguage.googleapis.com/v1beta/models/{model}:predict`
+- Body: `{ instances: [{ prompt: string }], parameters: { aspectRatio: string } }`
+
+**Get Operation:**
+- Method: GET
+- URL: `https://generativelanguage.googleapis.com/v1beta/{operationName}`
+
+### Model IDs
+
+Supported Veo models: `veo-3.1-fast-generate-preview`, `veo-3.0-generate-001`
+
+See: [`domain/constants/README.md`](../domain/constants/README.md)
+
+## 🎓 Usage Patterns
+
+### Start Video Generation
+1. Import service
+2. Call `startOperation()` with model, API key, and prompt
+3. Save returned operation name
+4. Use operation name for polling
+5. Handle network errors
+
+### Query Operation Status
+1. Import service
+2. Call `getOperation()` with operation name
+3. Check `done` field for completion
+4. Check `error` field for failures
+5. Extract video URL from response when complete
+
+### Custom Polling Logic
+1. Start operation with `startOperation()`
+2. Poll with `getOperation()` in loop
+3. Check completion status each iteration
+4. Handle progress updates
+5. Exit when complete or failed
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Poll manually (use veo-polling.service.ts)
+- Forget to save operation name
+- Ignore operation error field
+- Expose API keys in logs
+- Poll too frequently (rate limits)
+
+### Do
+- Save operation name immediately
+- Use polling service for automatic polling
+- Check error field in responses
+- Implement backoff between polls
+- Handle network errors gracefully
+- Validate API responses
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/VEO_POLLING_SERVICE.md

@@ -0,0 +1,173 @@
+# Veo Polling Service
+
+Tracks video generation operations using polling mechanism. Regularly checks operation status until completion.
+
+## 📍 Import Path
+
+```
+import { veoPollingService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to automatically poll video generation operations until completion. Provides progress updates and handles polling logic.
+
+**When to use:**
+- Wait for video generation to complete
+- Track generation progress
+- Provide progress feedback to users
+- Handle long-running operations
+- Implement video generation UI
+
+## 📌 Strategy
+
+Video generation takes time and requires polling. This service:
+- Implements automatic polling with backoff
+- Provides progress callbacks for UI updates
+- Handles operation completion and errors
+- Manages polling intervals and timeouts
+- Simplifies video generation workflow
+
+**Key Decision**: Use this service instead of manual polling. It handles backoff, timeouts, and progress tracking automatically.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** provide valid operation name
+- **MUST** provide API key and model ID
+- **SHOULD** implement progress callback
+- **MUST** handle polling completion appropriately
+- **SHOULD NOT** implement custom polling logic
+
+### Polling Rules
+- **MUST** wait between polls (automatic backoff)
+- **SHOULD** provide progress updates to users
+- **MUST** handle operation errors
+- **SHOULD** implement timeout for long operations
+- **MUST NOT** poll too frequently
+
+### Error Handling Rules
+- **MUST** check operation error field
+- **SHOULD** handle polling errors
+- **MUST** throw errors on operation failure
+- **SHOULD** provide user-friendly error messages
+- **MUST NOT** ignore timeout 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
+2. **FOLLOW** existing polling 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** polling operations in development
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `pollOperation(operationName, apiKey, model, onProgress?)`
+
+Poll operation until completion with progress updates.
+
+**Refer to**: [`veo-polling.service.ts`](./veo-polling.service.ts)
+
+## 🔗 Related Modules
+
+- **Veo HTTP Client**: [`VEO_HTTP_CLIENT_SERVICE.md`](./VEO_HTTP_CLIENT_SERVICE.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Error Handler**: [`VIDEO_ERROR_HANDLER_SERVICE.md`](./VIDEO_ERROR_HANDLER_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### Polling Strategy
+
+**Polling Intervals:**
+- Initial: Every 2 seconds
+- Backoff: Gradually increases based on progress
+- Maximum: 5 minutes total wait time
+
+**Polling Flow:**
+1. Start → Check status
+2. If not complete → Wait 2s → Check again
+3. If progress update → Call onProgress callback
+4. If complete or error → Return result
+5. If timeout → Throw error
+
+### Progress Callback
+
+Callback receives `VideoGenerationProgress` with:
+- `status`: Operation status (queued, processing, completed, failed)
+- `progress`: Percentage (0-100)
+- `message`: Optional status message
+
+## 🎓 Usage Patterns
+
+### Basic Polling
+1. Import service
+2. Call `pollOperation()` with operation name from HTTP client
+3. Wait for completion promise to resolve
+4. Extract video URL from result
+5. Handle errors appropriately
+
+### With Progress Updates
+1. Import service
+2. Implement `onProgress` callback
+3. Update UI with progress percentage
+4. Display status message to user
+5. Handle completion
+
+### With Timeout
+1. Calculate timeout duration
+2. Implement timeout check in progress callback
+3. Throw error if timeout exceeded
+4. Handle timeout error appropriately
+5. Provide user feedback
+
+### React Native Integration
+1. Create state for progress and video URL
+2. Start polling on user action
+3. Update state in progress callback
+4. Display progress to user
+5. Show video when complete
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Implement manual polling (use this service)
+- Ignore progress updates (bad UX)
+- Forget to handle errors
+- Poll without backoff (rate limits)
+- Block UI during polling
+
+### Do
+- Always use progress callbacks
+- Update UI with progress
+- Handle all error states
+- Implement cancellation support
+- Provide user feedback
+- Use reasonable timeouts
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)