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

package/src/domain/entities/README.md

@@ -0,0 +1,238 @@
+# Domain Entities
+
+Core data structures and type definitions for the Gemini provider. Contains all types required for API communication.
+
+## 📍 Import Path
+
+```
+import type {
+  GeminiConfig,
+  GeminiContent,
+  GeminiResponse,
+  GeminiImageGenerationResult,
+  VideoGenerationResult,
+  GeminiError,
+  GeminiErrorType
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use these types for type-safe integration with Gemini services. Provides TypeScript interfaces for all API operations.
+
+**When to use:**
+- Type-check API requests and responses
+- Define function signatures
+- Validate data structures
+- Understand API response formats
+- Handle typed errors
+
+## 📌 Strategy
+
+Strong typing prevents runtime errors. These types:
+- Define all API request/response structures
+- Provide type safety for operations
+- Enable autocomplete in IDEs
+- Document API contracts
+- Catch errors at compile time
+
+**Key Decision**: All types defined in domain layer have NO external dependencies. This keeps them pure and reusable.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** use types from domain layer
+- **SHOULD** prefer type imports over value imports
+- **MUST** handle all error types
+- **SHOULD** use type guards for validation
+- **MUST NOT** use `any` type
+
+### Type Safety Rules
+- **MUST** define explicit return types
+- **SHOULD** use strict null checks
+- **MUST** validate runtime data
+- **SHOULD** use discriminated unions for errors
+- **MUST NOT** bypass type checking
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **SHOULD** check error types
+- **MUST** handle all error states
+- **SHOULD** provide type-safe error messages
+- **MUST NOT** ignore error types
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Types
+1. **READ** existing type definitions first
+2. **UNDERSTAND** type relationships
+3. **MAINTAIN** backward compatibility
+4. **UPDATE** all usages
+5. **ADD** tests for new types
+
+### When Adding New Types
+1. **CHECK** if similar type exists
+2. **FOLLOW** existing naming conventions
+3. **USE** consistent patterns
+4. **DOCUMENT** with JSDoc comments
+5. **EXPORT** from index files
+
+### When Fixing Type Bugs
+1. **IDENTIFY** root cause in type definition
+2. **FIX** with minimal changes
+3. **UPDATE** all dependent code
+4. **ADD** type tests
+5. **VERIFY** no breaking changes
+
+### Code Style Rules
+- **USE** explicit type annotations
+- **AVOID** `any` type
+- **PREFER** readonly where appropriate
+- **USE** discriminated unions
+- **DOCUMENT** complex types
+
+## 📦 Available Types
+
+### Configuration Types
+
+**GeminiConfig**: Client configuration
+
+**Refer to**: [`gemini.types.ts`](./gemini.types.ts)
+
+### Request/Response Types
+
+**GeminiContent**: API request content structure
+
+**GeminiResponse**: API response structure
+
+**GeminiCandidate**: Generated candidate results
+
+**Refer to**: [`gemini.types.ts`](./gemini.types.ts)
+
+### Image Types
+
+**GeminiImageGenerationResult**: Image generation result
+
+**GeminiImageInput**: Image input structure
+
+**Refer to**: [`gemini.types.ts`](./gemini.types.ts)
+
+### Video Types
+
+**VideoGenerationInput**: Video generation input
+
+**VideoGenerationResult**: Video generation result
+
+**VideoOperationStatus**: Operation status enum
+
+**Refer to**: [`video.types.ts`](./video.types.ts)
+
+### Error Types
+
+**GeminiError**: Custom error class
+
+**GeminiErrorType**: Error type enum
+
+**GeminiErrorInfo**: Error information interface
+
+**Refer to**: [`error.types.ts`](./error.types.ts)
+
+### Model Types
+
+**GeminiModel**: Model information
+
+**GeminiGenerationConfig**: Generation parameters
+
+**Refer to**: [`models.ts`](./models.ts)
+
+## 🔗 Related Modules
+
+- **Services**: [`../../infrastructure/services/README.md`](../../infrastructure/services/README.md)
+- **Error Utilities**: [`../../infrastructure/utils/ERROR_UTILITIES.md`](../../infrastructure/utils/ERROR_UTILITIES.md)
+- **Constants**: [`../constants/README.md`](../constants/README.md)
+
+## 📋 Type Reference
+
+### Finish Reason Types
+
+Values indicating why generation completed:
+- `STOP` - Normal completion
+- `MAX_TOKENS` - Token limit reached
+- `SAFETY` - Blocked by safety filter
+- `RECITATION` - Copyright detected
+- `OTHER` - Other reasons
+
+### Video Operation Status
+
+Operation lifecycle states:
+- `queued` - Waiting in queue
+- `processing` - Currently processing
+- `completed` - Successfully finished
+- `failed` - Operation failed
+
+### Error Categories
+
+Error types for handling:
+- `API_ERROR` - General API errors
+- `VALIDATION_ERROR` - Input validation errors
+- `NETWORK_ERROR` - Network connectivity issues
+- `TIMEOUT_ERROR` - Request timeout
+- `RATE_LIMIT_ERROR` - Too many requests
+- `PARSING_ERROR` - Response parsing failures
+- `QUOTA_EXCEEDED` - API quota exceeded
+- `AUTHENTICATION` - Invalid credentials
+- `SAFETY` - Content safety violations
+- `MODEL_NOT_FOUND` - Invalid model ID
+- `SERVER` - Server errors (5xx)
+
+## 🎓 Usage Patterns
+
+### Type Imports
+1. Import types from package
+2. Use for function parameters
+3. Define return types
+4. Handle typed errors
+5. Validate runtime data
+
+### Error Type Checking
+1. Catch error from operation
+2. Check if `instanceof GeminiError`
+3. Switch on error.type
+4. Handle each error type appropriately
+5. Provide user feedback
+
+### Image Type Usage
+1. Use `GeminiImageInput` for image data
+2. Provide base64-encoded images
+3. Specify MIME type
+4. Handle image generation results
+5. Extract image URL or base64
+
+### Video Type Usage
+1. Use `VideoGenerationInput` for requests
+2. Monitor `VideoOperationStatus`
+3. Handle progress updates
+4. Extract video URL when complete
+5. Handle errors appropriately
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use `any` type to bypass typing
+- Ignore error types
+- Skip type validation
+- Use hardcoded model IDs
+- Forget to handle all error states
+
+### Do
+- Use explicit type annotations
+- Check error types
+- Validate runtime data
+- Use type guards
+- Handle all finish reasons
+- Provide type-safe error messages
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)

package/src/infrastructure/README.md

@@ -0,0 +1,252 @@
+# Infrastructure Layer
+
+Performance optimization, monitoring, and extensibility features. Includes cache, telemetry, and interceptor mechanisms.
+
+## 📍 Import Path
+
+```
+import {
+  SimpleCache,
+  modelSelectionCache,
+  telemetryHooks,
+  requestInterceptors,
+  responseInterceptors
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use infrastructure features to optimize performance, monitor operations, and extend functionality. Provides caching, telemetry, and middleware capabilities.
+
+**When to use:**
+- Cache expensive operations
+- Monitor AI operations
+- Intercept requests/responses
+- Optimize performance
+- Track metrics
+- Extend functionality
+
+## 📌 Strategy
+
+Infrastructure features are cross-cutting concerns. These systems:
+- Improve performance through caching
+- Enable observability through telemetry
+- Provide extensibility through interceptors
+- Support monitoring and debugging
+- Optimize resource usage
+
+**Key Decision**: Use infrastructure features to add capabilities without modifying core services. Keep infrastructure separate from business logic.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize features before use
+- **SHOULD** clean up resources appropriately
+- **MUST** handle cache misses gracefully
+- **SHOULD** monitor telemetry for insights
+- **MUST NOT** create circular dependencies
+
+### Cache Rules
+- **MUST** set appropriate TTL values
+- **SHOULD** monitor cache hit rates
+- **MUST** handle cache size limits
+- **SHOULD** invalidate stale data
+- **MUST NOT** cache everything indiscriminately
+
+### Telemetry Rules
+- **SHOULD** subscribe to events early
+- **MUST** unsubscribe when done
+- **SHOULD NOT** emit sensitive data
+- **MUST** handle listener errors
+- **SHOULD** aggregate metrics
+
+### Interceptor Rules
+- **MUST** return modified context
+- **SHOULD** handle errors in interceptors
+- **MUST** unsubscribe when done
+- **SHOULD NOT** block execution excessively
+- **MUST** maintain order dependency
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Infrastructure
+1. **READ** existing implementations first
+2. **UNDERSTAND** feature dependencies
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** documentation
+
+### When Adding New Features
+1. **CHECK** if similar feature exists
+2. **FOLLOW** existing patterns
+3. **USE** established error handling
+4. **DOCUMENT** in code comments
+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** dependency injection
+- **VALIDATE** inputs
+- **HANDLE** errors gracefully
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Features
+
+### Cache System
+
+LRU cache implementation for performance optimization.
+
+**Refer to**: [`cache/README.md`](./cache/README.md)
+
+**Files:**
+- [`cache/SimpleCache.ts`](./cache/SimpleCache.ts) - Cache implementation
+- [`cache/index.ts`](./cache/index.ts) - Cache exports
+
+### Telemetry System
+
+Event-based monitoring for AI operations.
+
+**Refer to**: [`telemetry/README.md`](./telemetry/README.md)
+
+**Files:**
+- [`telemetry/TelemetryHooks.ts`](./telemetry/TelemetryHooks.ts) - Telemetry implementation
+- [`telemetry/index.ts`](./telemetry/index.ts) - Telemetry exports
+
+### Interceptors
+
+Middleware for request/response transformation.
+
+**Refer to**: [`interceptors/README.md`](./interceptors/README.md)
+
+**Files:**
+- [`interceptors/RequestInterceptors.ts`](./interceptors/RequestInterceptors.ts) - Request interceptors
+- [`interceptors/ResponseInterceptors.ts`](./interceptors/ResponseInterceptors.ts) - Response interceptors
+- [`interceptors/index.ts`](./interceptors/index.ts) - Interceptor exports
+
+## 🔗 Related Modules
+
+- **Services**: [`services/README.md`](./services/README.md)
+- **Utils**: [`utils/README.md`](./utils/README.md)
+- **Domain Types**: [`../domain/README.md`](../domain/README.md)
+
+## 📋 Feature Reference
+
+### SimpleCache
+
+LRU cache with TTL support.
+
+**Methods:**
+- `set(key, value, ttl?)` - Store value
+- `get(key)` - Retrieve value
+- `has(key)` - Check existence
+- `delete(key)` - Remove entry
+- `clear()` - Clear all entries
+- `getStats()` - Get cache statistics
+
+**Configuration:**
+- `maxSize`: Maximum entries (default: 100)
+- `ttl`: Time-to-live in milliseconds (default: 5 minutes)
+
+### Telemetry Hooks
+
+Event system for monitoring operations.
+
+**Events:**
+- `request` - Operation started
+- `response` - Operation completed
+- `error` - Operation failed
+- `retry` - Retry attempted
+
+**Methods:**
+- `subscribe(listener)` - Add event listener
+- `emit(event)` - Emit event
+- `logRequest(model, feature)` - Log request start
+- `logResponse(model, startTime, feature)` - Log response
+- `logError(model, error, feature)` - Log error
+- `clear()` - Clear all listeners
+
+### Request Interceptors
+
+Middleware for request transformation.
+
+**Methods:**
+- `use(interceptor)` - Add interceptor
+- Returns unsubscribe function
+
+**Execution Order:** First added runs first
+
+### Response Interceptors
+
+Middleware for response transformation.
+
+**Methods:**
+- `use(interceptor)` - Add interceptor
+- Returns unsubscribe function
+
+**Execution Order:** Last added runs first (reverse order)
+
+## 🎓 Usage Patterns
+
+### Caching Strategy
+1. Import `SimpleCache` or use global cache
+2. Configure cache size and TTL
+3. Check cache before operation
+4. Store result in cache after operation
+5. Handle cache hits and misses
+
+### Monitoring Setup
+1. Subscribe to telemetry events early
+2. Track metrics in event handler
+3. Send to analytics/monitoring service
+4. Aggregate and analyze metrics
+5. Unsubscribe when done
+
+### Request Interception
+1. Add interceptor before operations
+2. Modify request context
+3. Return modified context
+4. Clean up interceptor when done
+5. Handle errors appropriately
+
+### Response Interception
+1. Add interceptor before operations
+2. Process response data
+3. Return modified context
+4. Clean up interceptor when done
+5. Handle errors appropriately
+
+### Performance Optimization
+1. Cache expensive operations
+2. Monitor cache hit rates
+3. Adjust TTL based on data freshness
+4. Track operation durations
+5. Optimize based on metrics
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Cache everything indiscriminately
+- Forget to unsubscribe from events
+- Block execution in interceptors
+- Emit sensitive data in telemetry
+- Create circular dependencies
+
+### Do
+- Set appropriate cache TTL values
+- Monitor cache hit rates
+- Clean up resources
+- Keep interceptors lightweight
+- Aggregate telemetry metrics
+- Handle errors gracefully
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/cache/CACHE_SYSTEM.md

@@ -0,0 +1,213 @@
+# Cache System
+
+LRU (Least Recently Used) cache implementation for performance optimization. Supports TTL-based expiration and automatic cleanup.
+
+## 📍 Import Path
+
+```
+import {
+  SimpleCache,
+  modelSelectionCache
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use cache to store expensive operation results and avoid redundant API calls. Improves performance and reduces costs.
+
+**When to use:**
+- Cache API responses
+- Store model selection results
+- Optimize expensive operations
+- Reduce API calls
+- Improve response times
+
+## 📌 Strategy
+
+Caching significantly improves performance. This system:
+- Implements LRU eviction policy
+- Supports TTL (time-to-live) for entries
+- Provides type-safe caching
+- Automatically expires stale entries
+- Offers global and instance caching
+
+**Key Decision**: Use `modelSelectionCache` for model selection. Create custom `SimpleCache` instances for specific use cases.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** configure appropriate cache size
+- **SHOULD** set reasonable TTL values
+- **MUST** handle cache misses gracefully
+- **SHOULD** monitor cache hit rates
+- **MUST NOT** cache everything indiscriminately
+
+### Configuration Rules
+- **MUST** set `maxSize` based on memory constraints
+- **SHOULD** set `ttl` based on data freshness needs
+- **MUST** consider cache entry size
+- **SHOULD** invalidate stale data
+- **MUST NOT** use excessive cache sizes
+
+### Cache Key Rules
+- **MUST** use descriptive cache keys
+- **SHOULD** include relevant parameters in key
+- **MUST NOT** use duplicate keys for different data
+- **SHOULD** namespace keys appropriately
+- **MUST** handle key collisions
+
+### Error Handling Rules
+- **MUST** handle cache failures gracefully
+- **SHOULD** log cache errors in development
+- **MUST** provide fallback on cache miss
+- **SHOULD NOT** throw errors from cache operations
+- **MUST** return data on cache miss
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Cache Module
+1. **READ** existing cache implementation first
+2. **UNDERSTAND** LRU eviction logic
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** documentation
+
+### When Adding New Caches
+1. **CHECK** if similar cache exists
+2. **FOLLOW** existing cache patterns
+3. **USE** appropriate configuration
+4. **DOCUMENT** cache purpose
+5. **ADD** usage examples to tests
+
+### When Optimizing Cache
+1. **MEASURE** cache hit rates
+2. **ADJUST** TTL values based on usage
+3. **MONITOR** memory usage
+4. **OPTIMIZE** cache size
+5. **TEST** performance improvements
+
+### Code Style Rules
+- **USE** generic type parameters
+- **VALIDATE** cache inputs
+- **HANDLE** edge cases (null, undefined)
+- **LOG** cache operations in development
+- **COMMENT** complex logic only
+
+## 📦 Available Caches
+
+### SimpleCache
+
+**Refer to**: [`SimpleCache.ts`](./SimpleCache.ts)
+
+Generic LRU cache implementation.
+
+**Methods:**
+- `set(key, value, ttl?)` - Store value
+- `get(key)` - Retrieve value
+- `has(key)` - Check existence
+- `delete(key)` - Remove entry
+- `clear()` - Clear all entries
+- `size()` - Get cache size
+- `keys()` - Get all keys
+- `getStats()` - Get statistics
+
+### modelSelectionCache
+
+**Refer to**: [`index.ts`](./index.ts)
+
+Global cache for model selection results.
+
+**Configuration:**
+- `maxSize`: 50 entries
+- `ttl`: 10 minutes
+- Automatic model-feature mapping
+
+## 🔗 Related Modules
+
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Services**: [`../services/README.md`](../services/README.md)
+- **Performance Utils**: [`../utils/PERFORMANCE_UTILS.md`](../utils/PERFORMANCE_UTILS.md)
+
+## 📋 Configuration Reference
+
+### Cache Options
+
+```typescript
+interface CacheOptions {
+  maxSize?: number;   // Maximum entries (default: 100)
+  ttl?: number;       // Time-to-live in milliseconds (default: 5 minutes)
+}
+```
+
+### Typical TTL Values
+
+- **Hot data**: 30 seconds - 1 minute
+- **Warm data**: 5 - 10 minutes
+- **Cold data**: 30 - 60 minutes
+- **Static data**: 1+ hours
+
+### Cache Size Guidelines
+
+- **Small cache**: 20-50 entries
+- **Medium cache**: 100-200 entries
+- **Large cache**: 500-1000 entries
+- **Consider memory constraints**
+
+## 🎓 Usage Patterns
+
+### Basic Caching
+1. Create `SimpleCache` instance
+2. Configure size and TTL
+3. Check cache before operation
+4. Store result in cache
+5. Handle cache hits and misses
+
+### Model Selection Caching
+1. Import `modelSelectionCache`
+2. Check cache for feature-model mapping
+3. Store selection in cache
+4. Use cached model ID
+5. Handle cache misses
+
+### Cache Invalidation
+1. Get all cache keys
+2. Filter by pattern
+3. Delete matching entries
+4. Clear specific data
+5. Update affected entries
+
+### Multi-Level Caching
+1. Create multiple cache instances
+2. Use different TTL for each level
+3. Check caches in order (fast to slow)
+4. Promote data between levels
+5. Handle multi-level misses
+
+### Cache Monitoring
+1. Call `getStats()` periodically
+2. Calculate cache hit rate
+3. Monitor memory usage
+4. Adjust configuration based on metrics
+5. Log performance data
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Cache everything indiscriminately
+- Set excessive cache sizes
+- Use very long TTL for dynamic data
+- Forget to handle cache misses
+- Cache sensitive or user-specific data without care
+
+### Do
+- Monitor cache hit rates
+- Set appropriate TTL values
+- Handle cache misses gracefully
+- Clear cache periodically
+- Use namespace prefixes for keys
+- Consider memory constraints
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)