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

package/src/presentation/hooks/USE_GEMINI_HOOK.md

@@ -0,0 +1,226 @@
+# useGemini Hook
+
+React hook for Gemini AI text generation with image support. Provides a simple interface for generating content with loading states, error handling, and result management.
+
+## 📍 File Path
+
+[`use-gemini.ts`](./use-gemini.ts)
+
+## 🎯 Purpose
+
+Use this hook to integrate Gemini AI text generation into React Native components. Manages state and provides methods for AI operations.
+
+**When to use:**
+- Generate AI text in components
+- Implement AI-powered features
+- Create chat interfaces
+- Build AI-assisted forms
+- Add image analysis to UI
+
+## 📌 Strategy
+
+Hook abstracts complexity of AI operations. This hook:
+- Manages loading, error, and result state
+- Provides simple methods for generation
+- Handles image-based generation
+- Supports configuration and callbacks
+- Enables easy UI integration
+
+**Key Decision**: Use this hook for React Native UI components. It provides a clean, React-friendly interface to Gemini AI services.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider before using hook
+- **MUST** call hook only in React components
+- **SHOULD** handle all states (loading, error, result)
+- **MUST** provide user feedback
+- **SHOULD NOT** use hook outside React functions
+
+### State Management Rules
+- **SHOULD** display loading indicators during generation
+- **MUST** handle and display errors
+- **SHOULD** implement success callbacks
+- **MUST** reset state when appropriate
+- **SHOULD** cleanup on unmount
+
+### Configuration Rules
+- **MUST** use valid model IDs
+- **SHOULD** select appropriate model for use case
+- **MUST** configure generation parameters appropriately
+- **SHOULD** implement callbacks for side effects
+- **MUST NOT** hardcode model IDs
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Hook
+1. **READ** the implementation file first
+2. **UNDERSTAND** React hook patterns
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if feature exists in hooks or services
+2. **FOLLOW** existing hook 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
+- **FOLLOW** React hooks rules
+- **USE** useMemo/useCallback for optimization
+- **VALIDATE** inputs
+- **HANDLE** errors gracefully
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### Hook Return Values
+
+The hook returns an object with:
+- `generate(prompt)`: Generate text from prompt
+- `generateWithImage(prompt, imageBase64, mimeType)`: Generate with image context
+- `result`: Generated text (null if no result)
+- `isGenerating`: Loading state
+- `error`: Error message (null if no error)
+- `reset()`: Clear all state
+
+**Refer to**: [`use-gemini.ts`](./use-gemini.ts)
+
+## 🔗 Related Modules
+
+- **Text Generation Service**: [`../../infrastructure/services/TEXT_GENERATION_SERVICE.md`](../../infrastructure/services/TEXT_GENERATION_SERVICE.md)
+- **Image Edit Service**: [`../../infrastructure/services/IMAGE_EDIT_SERVICE.md`](../../infrastructure/services/IMAGE_EDIT_SERVICE.md)
+- **Hooks Overview**: [`README.md`](./README.md)
+
+## 📋 Configuration Reference
+
+### UseGeminiOptions
+
+Configuration interface found in: [`use-gemini.ts`](./use-gemini.ts)
+
+**Options:**
+- `model`: string - Model ID (default: 'gemini-1.5-flash')
+- `generationConfig`: object - Generation parameters (temperature, maxTokens, etc.)
+- `onSuccess`: (result: string) => void - Success callback
+- `onError`: (error: string) => void - Error callback
+
+### Model Selection
+
+See available models in: [`../../infrastructure/services/FEATURE_MODEL_SELECTOR_SERVICE.md`](../../infrastructure/services/FEATURE_MODEL_SELECTOR_SERVICE.md)
+
+## 🎓 Usage Patterns
+
+### Basic Text Generation
+1. Import hook in component
+2. Call `useGemini()` hook
+3. Use `generate()` method with prompt
+4. Display `isGenerating`, `error`, and `result` states
+5. Handle user interactions
+
+### Custom Model
+1. Import hook
+2. Call `useGemini()` with model option
+3. Select appropriate model ID
+4. Use hook methods normally
+5. Handle responses
+
+### With Generation Config
+1. Import hook
+2. Configure `generationConfig` option
+3. Set temperature, max tokens, etc.
+4. Use hook for generation
+5. Handle responses
+
+### With Callbacks
+1. Import hook
+2. Implement `onSuccess` callback
+3. Implement `onError` callback
+4. Handle side effects in callbacks
+5. Use hook for generation
+
+### Image-Based Generation
+1. Import hook
+2. Prepare base64 image data
+3. Call `generateWithImage()` with prompt and image
+4. Handle loading and result states
+5. Display result
+
+### Form Integration
+1. Import hook
+2. Create form with input fields
+3. Call generation on form submit
+4. Display states appropriately
+5. Handle success/error
+
+### Chat Interface
+1. Import hook
+2. Maintain messages array in state
+3. Call `generate()` for each user message
+4. Add result to messages
+5. Display conversation
+
+### Error Handling
+1. Import hook
+2. Configure `onError` callback
+3. Check error types in callback
+4. Show appropriate messages
+5. Implement retry logic
+
+### Auto-Generate on Mount
+1. Import hook
+2. Use `useEffect()` hook
+3. Call `generate()` in effect
+4. Handle result and error
+5. Display to user
+
+### Retry Logic
+1. Import hook
+2. Implement retry counter
+3. Call `generate()` with backoff
+4. Track attempts
+5. Handle final failure
+
+### Debounced Input
+1. Import hook
+2. Implement debounce utility
+3. Call debounced generation
+4. Handle delayed results
+5. Update UI appropriately
+
+### Streaming Simulation
+1. Import hook
+2. Use `generate()` to get result
+3. Implement streaming display effect
+4. Update state progressively
+5. Display to user
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Forget to check loading state
+- Ignore error states
+- Use hook outside React functions
+- Skip cleanup on unmount
+- Hardcode model IDs
+
+### Do
+- Always display loading indicator
+- Handle all error states
+- Implement success callbacks
+- Reset state when needed
+- Provide user feedback
+- Cleanup on unmount
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)

package/src/providers/README.md

@@ -0,0 +1,247 @@
+# Provider Configuration
+
+Tier-based AI provider configuration system. Manages model selection, cost optimization, and quality preferences based on subscription tier.
+
+## 📍 Import Path
+
+```
+import {
+  providerFactory,
+  resolveProviderConfig,
+  getCostOptimizedConfig,
+  getQualityOptimizedConfig
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this system to configure AI provider based on subscription tier and user preferences. Automates model selection and optimization.
+
+**When to use:**
+- Initialize AI provider for application
+- Configure models based on user tier
+- Optimize costs or quality
+- Manage runtime configuration updates
+- Implement tier-based features
+
+## 📌 Strategy
+
+Different users need different configurations. This system:
+- Selects appropriate models for subscription tier
+- Balances cost vs quality
+- Provides runtime configuration updates
+- Supports optimization strategies
+- Manages provider lifecycle
+
+**Key Decision**: Use tier-based configuration to provide different experiences for free vs premium users while optimizing costs.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider before any operations
+- **SHOULD** select appropriate tier for user
+- **MUST** provide valid API key
+- **SHOULD** configure preferences appropriately
+- **MUST NOT** reinitialize unnecessarily
+
+### Configuration Rules
+- **MUST** use valid subscription tier ("free" | "premium")
+- **SHOULD** set quality preference appropriately
+- **MUST** provide API key (required field)
+- **SHOULD** configure retry limits
+- **MUST NOT** use invalid model IDs
+
+### Tier Rules
+- **FREE tier**: Faster models, limited retries
+- **PREMIUM tier**: Higher quality, more retries
+- **SHOULD** match tier to user subscription
+- **MUST** update config when tier changes
+- **SHOULD** optimize based on tier
+
+### Strategy Rules
+- **COST strategy**: Cheapest models, no retries
+- **QUALITY strategy**: Best models, more retries
+- **BALANCED strategy**: Tier-based defaults
+- **SHOULD** select strategy based on environment
+- **MUST** align strategy with business goals
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Provider System
+1. **READ** existing configuration code first
+2. **UNDERSTAND** tier-based logic
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new configurations
+5. **UPDATE** documentation
+
+### When Adding New Tiers
+1. **CHECK** business requirements
+2. **DEFINE** tier configuration
+3. **UPDATE** resolution logic
+4. **TEST** tier transitions
+5. **DOCUMENT** tier differences
+
+### When Adding Optimization Strategies
+1. **ANALYZE** cost/quality tradeoffs
+2. **DEFINE** strategy rules
+3. **IMPLEMENT** selection logic
+4. **TEST** strategy effectiveness
+5. **DOCUMENT** strategy use cases
+
+### Code Style Rules
+- **USE** factory pattern for provider
+- **VALIDATE** configuration inputs
+- **THROW** typed errors for invalid config
+- **LOG** configuration changes
+- **COMMENT** complex logic only
+
+## 📦 Available Functions
+
+### `providerFactory.initialize(options)`
+
+Initialize provider with configuration.
+
+**Refer to**: [`ProviderFactory.ts`](./ProviderFactory.ts)
+
+### `providerFactory.getConfig()`
+
+Get current provider configuration.
+
+**Refer to**: [`ProviderFactory.ts`](./ProviderFactory.ts)
+
+### `providerFactory.isInitialized()`
+
+Check if provider is initialized.
+
+**Refer to**: [`ProviderFactory.ts`](./ProviderFactory.ts)
+
+### `providerFactory.updateConfig(updates)`
+
+Update configuration at runtime.
+
+**Refer to**: [`ProviderFactory.ts`](./ProviderFactory.ts)
+
+### `resolveProviderConfig(input)`
+
+Resolve configuration based on tier and preferences.
+
+**Refer to**: [`ProviderConfig.ts`](./ProviderConfig.ts)
+
+### `getCostOptimizedConfig(input)`
+
+Get cost-optimized configuration.
+
+**Refer to**: [`ProviderConfig.ts`](./ProviderConfig.ts)
+
+### `getQualityOptimizedConfig(input)`
+
+Get quality-optimized configuration.
+
+**Refer to**: [`ProviderConfig.ts`](./ProviderConfig.ts)
+
+## 🔗 Related Modules
+
+- **Core Client**: [`../infrastructure/services/CORE_CLIENT_SERVICE.md`](../infrastructure/services/CORE_CLIENT_SERVICE.md)
+- **Domain Types**: [`../domain/README.md`](../domain/README.md)
+- **Services**: [`../infrastructure/services/README.md`](../infrastructure/services/README.md)
+
+## 📋 Configuration Reference
+
+### Subscription Tiers
+
+**FREE** - Free tier users
+- Faster models (gemini-2.5-flash)
+- Limited retries (1)
+- Shorter timeout (30s)
+
+**PREMIUM** - Premium tier users
+- Higher quality models (gemini-3-pro-image)
+- More retries (2)
+- Longer timeout (60s)
+
+### Quality Preferences
+
+**FAST** - Fast responses
+- Uses fastest models
+
+**BALANCED** - Balanced approach
+- Uses tier default models
+
+**HIGH** - High quality
+- Uses best available models
+
+### Optimization Strategies
+
+**COST** - Minimize cost
+- Cheapest models only
+- No retries
+- Use for: Development, testing
+
+**QUALITY** - Maximize quality
+- Best models
+- More retries
+- Use for: Production, critical operations
+
+**BALANCED** - Tier-based defaults
+- Tier-appropriate models
+- Standard retries
+- Use for: General usage
+
+## 🎓 Usage Patterns
+
+### Basic Initialization
+1. Import `providerFactory`
+2. Call `initialize()` with API key and tier
+3. Verify initialization
+4. Use AI services normally
+5. Handle errors appropriately
+
+### Tier-Based Configuration
+1. Determine user subscription tier
+2. Initialize with appropriate tier
+3. System selects appropriate models
+4. User gets tier-appropriate experience
+5. Update config when tier changes
+
+### Runtime Updates
+1. User upgrades/downgrades subscription
+2. Call `updateConfig()` with new tier
+3. Provider updates without reinitialization
+4. New models take effect immediately
+5. Continue operations normally
+
+### Environment-Specific Strategy
+1. Check environment (dev/staging/prod)
+2. Select appropriate strategy
+3. Initialize with strategy
+4. Dev uses cost strategy
+5. Prod uses quality strategy
+
+### Preference-Based Configuration
+1. Get user preferences from storage
+2. Configure quality preference
+3. Initialize with preferences
+4. System selects models accordingly
+5. User gets preferred experience
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Initialize provider multiple times
+- Use wrong tier for user
+- Skip API key validation
+- Ignore tier changes
+- Use invalid model IDs
+
+### Do
+- Initialize once at startup
+- Match tier to user subscription
+- Update config when tier changes
+- Validate configuration
+- Use appropriate strategies
+- Handle initialization errors
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)