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

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)

package/src/infrastructure/services/CORE_CLIENT_SERVICE.md

@@ -0,0 +1,202 @@
+# Core Client Service
+
+Low-level communication with Google Gemini SDK. Handles model loading, configuration, and SDK management.
+
+## 📍 Import Path
+
+```
+import { geminiClientCoreService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to initialize and configure the Gemini SDK. Manages the underlying Gemini client instance and provides access to configured models.
+
+**When to use:**
+- Initialize Gemini SDK with API key
+- Configure default models for different features
+- Access Gemini model instances directly
+- Update SDK configuration at runtime
+- Validate SDK initialization status
+
+## 📌 Strategy
+
+Core client acts as the foundation for all Gemini operations. This service:
+- Implements singleton pattern for single SDK instance
+- Manages SDK lifecycle (initialization, configuration)
+- Provides typed model instances
+- Handles API key and endpoint configuration
+- Validates initialization before operations
+
+**Key Decision**: Use singleton pattern to ensure single Gemini SDK instance. All other services use this core client for model access.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize before any Gemini operations
+- **MUST** provide valid API key in configuration
+- **SHOULD** initialize once at application startup
+- **MUST NOT** create multiple instances (use singleton)
+- **SHOULD** validate initialization before use
+
+### Configuration Rules
+- **MUST** set API key (required field)
+- **SHOULD** configure appropriate models for features
+- **MUST NOT** expose API keys in logs or errors
+- **SHOULD** set reasonable retry limits
+- **MUST** use valid model IDs
+
+### Error Handling Rules
+- **MUST** validate configuration before initialization
+- **MUST** handle initialization errors appropriately
+- **SHOULD** provide clear error messages
+- **MUST** throw errors for invalid API keys
+- **SHOULD** log initialization status in development
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** singleton pattern
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if feature exists in other services
+2. **FOLLOW** existing initialization 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** singleton pattern
+- **VALIDATE** all inputs
+- **THROW** typed errors
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `initialize(config)`
+
+Initialize Gemini client with configuration.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `getModel(model)`
+
+Get Gemini model instance by ID.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `getConfig()`
+
+Get current configuration.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `isInitialized()`
+
+Check if service is initialized.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `validateInitialization()`
+
+Validate initialization, throw error if not initialized.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+### `updateConfig(config)`
+
+Update configuration at runtime.
+
+**Refer to**: [`gemini-client-core.service.ts`](./gemini-client-core.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Text Generation**: [`TEXT_GENERATION_SERVICE.md`](./TEXT_GENERATION_SERVICE.md)
+- **Image Generation**: [`IMAGE_GENERATION_SERVICE.md`](./IMAGE_GENERATION_SERVICE.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### GeminiConfig
+
+Configuration interface definition found in: [`domain/entities/README.md`](../domain/entities/README.md)
+
+**Required Fields:**
+- `apiKey`: string - API key from Google Cloud Console
+
+**Optional Fields:**
+- `baseUrl`: string - Custom base URL for API requests
+- `maxRetries`: number - Maximum retry attempts (default: 3)
+- `baseDelay`: number - Initial retry delay in ms (default: 1000)
+- `maxDelay`: number - Maximum retry delay in ms (default: 10000)
+- `defaultTimeoutMs`: number - Request timeout in ms
+- `textModel`: string - Default text generation model
+- `textToImageModel`: string - Default image generation model
+- `imageEditModel`: string - Default image editing model
+- `videoGenerationModel`: string - Default video generation model
+
+### Supported Models
+
+See model IDs in: [`domain/constants/README.md`](../domain/constants/README.md)
+
+## 🎓 Usage Patterns
+
+### Basic Initialization
+1. Import service
+2. Call `initialize()` with API key
+3. Verify initialization with `isInitialized()`
+4. Use services normally
+
+### Advanced Configuration
+1. Prepare configuration object with all settings
+2. Include model IDs for each feature
+3. Set retry and timeout parameters
+4. Call `initialize()` with configuration
+5. Validate initialization succeeded
+
+### Runtime Configuration Updates
+1. Check current configuration with `getConfig()`
+2. Prepare partial config update
+3. Call `updateConfig()` with new values
+4. Verify changes applied
+
+### Direct Model Access
+1. Ensure service is initialized
+2. Call `getModel()` with model ID
+3. Use returned model instance directly
+4. Handle model errors appropriately
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Initialize multiple times
+- Create new instances (use singleton)
+- Skip initialization validation
+- Expose API keys in logs
+- Use uninitialized service
+
+### Do
+- Initialize once at app startup
+- Use singleton instance
+- Validate before use
+- Handle initialization errors
+- Set appropriate model IDs
+- Configure reasonable timeouts
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)