@umituz/react-native-ai-gemini-provider 1.14.39 → 1.14.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-gemini-provider",
-  "version": "1.14.39",
+  "version": "1.14.40",
   "description": "Google Gemini AI provider for React Native applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/domain/constants/feature-models.constants.ts

@@ -34,8 +34,8 @@ export const GEMINI_IMAGE_FEATURE_MODELS: Record<ImageFeatureType, string> = {
  * Using gemini-2.0-flash-exp for video generation capabilities
  */
 export const GEMINI_VIDEO_FEATURE_MODELS: Record<VideoFeatureType, string> = {
-  "ai-hug": "gemini-2.0-flash-exp",
-  "ai-kiss": "gemini-2.0-flash-exp",
+  "image-to-video": "gemini-2.0-flash-exp",
+  "text-to-video": "gemini-2.0-flash-exp",
 };
 
 /**

package/src/infrastructure/services/feature-input-builder.ts

@@ -69,13 +69,17 @@ class FeatureInputBuilder {
     const { sourceImageBase64, targetImageBase64, prompt, options } = data;
 
     switch (feature) {
-      case "ai-hug":
-      case "ai-kiss":
+      case "image-to-video":
         return buildVideoFromDualImagesInput(sourceImageBase64, {
           target_image: targetImageBase64,
           motion_prompt: prompt,
           ...options,
         });
+      case "text-to-video":
+        return buildVideoFromDualImagesInput(sourceImageBase64 || "", {
+          motion_prompt: prompt,
+          ...options,
+        });
       default:
         throw new Error(`Unknown video feature: ${String(feature)}`);
     }

package/src/infrastructure/services/gemini-provider.ts

@@ -48,7 +48,7 @@ const GEMINI_CAPABILITIES: ProviderCapabilities = {
     "hd-touch-up",
     "replace-background",
   ] as const,
-  videoFeatures: ["ai-hug", "ai-kiss"] as const,
+  videoFeatures: ["image-to-video", "text-to-video"] as const,
   textToImage: true,
   textToVideo: true,
   imageToVideo: true,

package/src/infrastructure/utils/video-feature-builders.util.ts

@@ -7,36 +7,22 @@ import { buildSingleImageInput, buildDualImageInput } from "./base-input-builder
 import type { VideoFromImageOptions, VideoFromDualImageOptions } from "./input-builder.types";
 
 /**
- * Build AI hug video input for Gemini
+ * Build video from single image input for Gemini
  */
-export function buildAIHugInput(
+export function buildVideoFromImageInput(
   base64: string,
   options?: VideoFromImageOptions,
 ): Record<string, unknown> {
-  const motionPrompt = options?.motion_prompt || "Create a warm hugging animation";
+  const motionPrompt = options?.motion_prompt || "Animate this image with natural, smooth motion";
 
-  const prompt = `Transform this image into a video. ${motionPrompt}. Make it natural and emotional.`;
-
-  return buildSingleImageInput(base64, prompt);
-}
-
-/**
- * Build AI kiss video input for Gemini
- */
-export function buildAIKissInput(
-  base64: string,
-  options?: VideoFromImageOptions,
-): Record<string, unknown> {
-  const motionPrompt = options?.motion_prompt || "Create a kissing animation";
-
-  const prompt = `Transform this image into a video. ${motionPrompt}. Make it romantic and natural.`;
+  const prompt = `Transform this image into a video. ${motionPrompt}. Make it natural and cinematic.`;
 
   return buildSingleImageInput(base64, prompt);
 }
 
 /**
  * Build video from dual images input for Gemini
- * Used for ai-hug and ai-kiss features that need source and target images
+ * Used for features that need source and target images
  */
 export function buildVideoFromDualImagesInput(
   sourceBase64: string,
@@ -47,11 +33,11 @@ export function buildVideoFromDualImagesInput(
 
   if (!targetBase64) {
     // Single image case (fallback)
-    const prompt = `Transform this image into a video. ${motionPrompt}. Make it natural and emotional.`;
+    const prompt = `Transform this image into a video. ${motionPrompt}. Make it natural and cinematic.`;
     return buildSingleImageInput(sourceBase64, prompt);
   }
 
-  const prompt = `Transform these two images into a video. ${motionPrompt}. Make it natural and emotional. The first image is the source person, the second is the target person.`;
+  const prompt = `Transform these two images into a video. ${motionPrompt}. Make it natural and cinematic. The first image is the source person, the second is the target person.`;
 
   return buildDualImageInput(sourceBase64, targetBase64, prompt);
 }

package/src/domain/constants/README.md

@@ -1,191 +0,0 @@
-# Domain Constants
-
-Constant values and model catalogs for Gemini provider. Contains feature-based model mappings for image and video operations.
-
-## 📍 Import Path
-
-```
-import {
-  GEMINI_IMAGE_FEATURE_MODELS,
-  GEMINI_VIDEO_FEATURE_MODELS,
-  getGeminiImageFeatureModel,
-  getGeminiVideoFeatureModel,
-  getAllFeatureModels
-} from '@umituz/react-native-ai-gemini-provider';
-```
-
-## 🎯 Purpose
-
-Use constants to map features to appropriate models. Provides centralized model selection for image and video processing features.
-
-**When to use:**
-- Get model ID for specific feature
-- Display available features in UI
-- Validate feature requests
-- Map user features to models
-- List supported operations
-
-## 📌 Strategy
-
-Features map to specific models. This system:
-- Provides constant feature-to-model mappings
-- Centralizes model configuration
-- Enables feature validation
-- Simplifies model selection
-- Maintains consistency across codebase
-
-**Key Decision**: Use feature constants instead of hardcoded model IDs. This enables centralized model management and updates.
-
-## ⚠️ Rules
-
-### Usage Rules
-- **MUST** use constants for model selection
-- **SHOULD** validate feature before use
-- **MUST** handle unknown features gracefully
-- **SHOULD** check model compatibility
-- **MUST NOT** hardcode model IDs
-
-### Feature Selection Rules
-- **MUST** select appropriate model for feature
-- **SHOULD** use getter functions
-- **MUST** validate feature type
-- **SHOULD** handle missing features
-- **MUST** return valid model IDs
-
-### Validation Rules
-- **SHOULD** validate feature strings
-- **MUST** check feature exists
-- **SHOULD** provide fallback models
-- **MUST** throw on invalid features
-- **SHOULD** log validation failures
-
-### Maintenance Rules
-- **MUST** update constants when models change
-- **SHOULD** document model changes
-- **MUST** maintain backward compatibility
-- **SHOULD** test feature mappings
-- **MUST** update documentation
-
-## 🤖 AI Agent Guidelines
-
-### When Getting Model for Feature
-1. **CALL** getGeminiImageFeatureModel() or getGeminiVideoFeatureModel()
-2. **VALIDATE** feature exists
-3. **RETURN** model ID
-4. **HANDLE** unknown features
-5. **LOG** model selection
-
-### When Listing Features
-1. **CALL** getAllFeatureModels()
-2. **FILTER** by feature type
-3. **DISPLAY** to user
-4. **GROUP** by category
-5. **HANDLE** empty lists
-
-### When Validating Features
-1. **CHECK** feature in constants
-2. **VERIFY** model exists
-3. **RETURN** validation result
-4. **PROVIDE** error messages
-5. **SUGGEST** alternatives
-
-### Code Style Rules
-- **USE** constants instead of hardcoded values
-- **IMPORT** specific constants needed
-- **VALIDATE** feature inputs
-- **HANDLE** edge cases
-- **DOCUMENT** custom features
-
-## 📦 Available Constants
-
-### Image Feature Models
-
-**Refer to**: [`feature-models.constants.ts`](./feature-models.constants.ts)
-
-**Features:**
-- `upscale` - Image upscaling
-- `photo-restore` - Photo restoration
-- `face-swap` - Face swapping
-- `anime-selfie` - Anime style transformation
-- `remove-background` - Background removal
-- `remove-object` - Object removal
-- `hd-touch-up` - HD enhancement
-- `replace-background` - Background replacement
-
-**Model**: All use `gemini-2.0-flash-exp`
-
-### Video Feature Models
-
-**Refer to**: [`feature-models.constants.ts`](./feature-models.constants.ts)
-
-**Features:**
-- `ai-hug` - AI hugging effect
-- `ai-kiss` - AI kissing effect
-
-**Model**: All use `gemini-2.0-flash-exp`
-
-## 🔗 Related Modules
-
-- **Domain Entities**: [`../entities/README.md`](../entities/README.md)
-- **Domain README**: [`../README.md`](../README.md)
-- **Model Selector**: [`../../infrastructure/services/FEATURE_MODEL_SELECTOR_SERVICE.md`](../../infrastructure/services/FEATURE_MODEL_SELECTOR_SERVICE.md)
-
-## 📋 Feature Reference
-
-### Image Editing Features
-- **upscale**: Enlarge image while maintaining quality
-- **photo-restore**: Restore old or damaged photos
-- **face-swap**: Swap faces between images
-- **anime-selfie**: Transform selfie to anime style
-- **remove-background**: Remove image background
-- **remove-object**: Remove specific objects from image
-- **hd-touch-up**: Enhance image quality to HD
-- **replace-background**: Replace image background
-
-### Video Features
-- **ai-hug**: Generate video of subjects hugging
-- **ai-kiss**: Generate video of subjects kissing
-
-## 🎓 Usage Patterns
-
-### Feature-Based Model Selection
-1. Determine feature type (image or video)
-2. Call appropriate getter function
-3. Get model ID for feature
-4. Use model in service call
-5. Handle unknown features
-
-### Feature Listing
-1. Call getAllFeatureModels()
-2. Iterate through feature list
-3. Group by category
-4. Display to user
-5. Handle feature selection
-
-### Feature Validation
-1. Check feature in constants
-2. Verify model mapping exists
-3. Validate feature type
-4. Return validation result
-5. Provide feedback
-
-## 🚨 Common Pitfalls
-
-### Don't
-- Hardcode model IDs in application code
-- Use features without validation
-- Assume all features use same model
-- Skip feature existence checks
-- Use invalid feature strings
-
-### Do
-- Use constants for model selection
-- Validate features before use
-- Check model mappings
-- Handle unknown features gracefully
-- Update constants when models change
-
----
-
-**Last Updated**: 2025-01-08
-**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)

package/src/infrastructure/utils/INPUT_BUILDERS.md

@@ -1,214 +0,0 @@
-# Input Builders
-
-Helper functions for building Gemini API inputs for image and video processing features. Creates properly formatted prompts and image arrays.
-
-## 📍 Import Path
-
-```
-import {
-  buildUpscaleInput,
-  buildPhotoRestoreInput,
-  buildRemoveBackgroundInput,
-  buildReplaceBackgroundInput,
-  buildFaceSwapInput,
-  buildSingleImageInput,
-  buildDualImageInput
-} from '@umituz/react-native-ai-gemini-provider';
-```
-
-## 🎯 Purpose
-
-Use input builders to create properly formatted inputs for image and video features. Simplifies prompt engineering and image data preparation.
-
-**When to use:**
-- Build inputs for image editing features
-- Create prompts for video generation
-- Format image data correctly
-- Combine multiple images
-- Simplify feature integration
-
-## 📌 Strategy
-
-Input builders encapsulate prompt complexity. This system:
-- Creates optimized prompts for features
-- Formats image data correctly
-- Handles single and multiple images
-- Provides consistent interface
-- Simplifies feature usage
-
-**Key Decision**: Always use input builders for image/video features. Ensures correct prompt engineering and data formatting.
-
-## ⚠️ Rules
-
-### Usage Rules
-- **MUST** use builders for image/video features
-- **SHOULD** provide valid base64 data
-- **MUST** check required parameters
-- **SHOULD** handle missing options
-- **MUST NOT** create inputs manually
-
-### Data Rules
-- **MUST** provide valid base64 strings
-- **SHOULD** validate image data
-- **MUST** include correct MIME types
-- **SHOULD** handle encoding errors
-- **MUST NOT** pass invalid data
-
-### Prompt Rules
-- **MUST** use builder-generated prompts
-- **SHOULD NOT** modify builder prompts
-- **MUST** follow prompt patterns
-- **SHOULD** test prompt effectiveness
-- **MUST NOT** hardcode prompts
-
-### Options Rules
-- **SHOULD** provide appropriate options
-- **MUST** check required parameters
-- **SHOULD** use default values wisely
-- **MUST** validate option values
-- **SHOULD NOT** ignore option validation
-
-## 🤖 AI Agent Guidelines
-
-### When Building Inputs
-1. **SELECT** appropriate builder function
-2. **PROVIDE** valid base64 data
-3. **CONFIGURE** options if needed
-4. **USE** returned prompt and images
-5. **HANDLE** builder errors
-
-### When Using Image Features
-1. **PREPARE** image base64 data
-2. **CALL** appropriate builder
-3. **USE** prompt from builder
-4. **PASS** images array to service
-5. **HANDLE** service response
-
-### When Creating Custom Builders
-1. **ANALYZE** existing builders
-2. **FOLLOW** builder pattern
-3. **CREATE** optimized prompt
-4. **RETURN** consistent structure
-5. **TEST** builder thoroughly
-
-### Code Style Rules
-- **USE** builders instead of manual input
-- **VALIDATE** input data
-- **HANDLE** missing options
-- **FOLLOW** builder patterns
-- **TEST** builder output
-
-## 📦 Available Builders
-
-### Single Image Builders
-
-**Refer to**: [`image-feature-builders.util.ts`](./image-feature-builders.util.ts)
-
-- `buildUpscaleInput(base64, options?)` - Image upscaling
-- `buildPhotoRestoreInput(base64, options?)` - Photo restoration
-- `buildAnimeSelfieInput(base64, options?)` - Anime style transformation
-- `buildRemoveBackgroundInput(base64, options?)` - Background removal
-- `buildRemoveObjectInput(base64, options?)` - Object removal
-- `buildReplaceBackgroundInput(base64, options)` - Background replacement
-- `buildHDTouchUpInput(base64, options?)` - HD enhancement
-
-### Dual Image Builders
-
-**Refer to**: [`image-feature-builders.util.ts`](./image-feature-builders.util.ts)
-
-- `buildFaceSwapInput(sourceBase64, targetBase64, options?)` - Face swapping
-
-### Video Builders
-
-**Refer to**: [`video-feature-builders.util.ts`](./video-feature-builders.util.ts)
-
-- `buildAIHugInput(base64, options?)` - AI hugging effect
-- `buildAIKissInput(base64, options?)` - AI kissing effect
-- `buildVideoFromDualImagesInput(base64a, base64b, options?)` - Dual image to video
-
-### Base Builders
-
-**Refer to**: [`base-input-builders.util.ts`](./base-input-builders.util.ts)
-
-- `buildSingleImageInput(base64, prompt)` - Single image input
-- `buildDualImageInput(base64a, base64b, prompt)` - Dual image input
-
-## 🔗 Related Modules
-
-- **Image Edit Service**: [`../services/IMAGE_EDIT_SERVICE.md`](../services/IMAGE_EDIT_SERVICE.md)
-- **Image Preparer Utils**: [`../utils/IMAGE_PREPARER_UTILS.md`](../utils/IMAGE_PREPARER_UTILS.md)
-- **Content Builder**: [`../content/README.md`](../content/README.md)
-
-## 📋 Builder Return Type
-
-All builders return:
-
-```typescript
-{
-  prompt: string;
-  images: Array<{
-    base64: string;
-    mimeType: string;
-  }>;
-}
-```
-
-This structure is compatible with `geminiImageEditService.editImage()`.
-
-## 🎓 Usage Patterns
-
-### Basic Feature Usage
-1. Prepare image base64 data
-2. Call appropriate builder function
-3. Configure options if needed
-4. Use returned prompt and images
-5. Call image edit service
-
-### Single Image Processing
-1. Get image base64 string
-2. Call single-image builder
-3. Pass prompt and images to service
-4. Handle service response
-5. Display result
-
-### Dual Image Processing
-1. Get both image base64 strings
-2. Call dual-image builder
-3. Use returned input structure
-4. Call appropriate service
-5. Handle response
-
-### Batch Processing
-1. Prepare all images
-2. Call builder for each image
-3. Process inputs in sequence
-4. Collect all results
-5. Return batch results
-
-### Custom Features
-1. Analyze existing builders
-2. Create custom builder function
-3. Follow builder pattern
-4. Return consistent structure
-5. Test thoroughly
-
-## 🚨 Common Pitfalls
-
-### Don't
-- Create inputs manually
-- Modify builder prompts
-- Skip builder functions
-- Hardcode prompts
-- Use invalid base64 data
-
-### Do
-- Always use input builders
-- Follow builder patterns
-- Validate input data
-- Use builder-generated prompts
-- Test builder output
-
----
-
-**Last Updated**: 2025-01-08
-**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/utils/README.md

@@ -1,289 +0,0 @@
-# Utils
-
-Utility functions and tools for Gemini provider. Handles error management, performance monitoring, data transformation, model validation, image preparation, and input building.
-
-## 📍 Import Path
-
-```
-import {
-  // Error handling
-  mapGeminiError,
-  isGeminiErrorRetryable,
-  categorizeGeminiError,
-  createGeminiError,
-
-  // Model validation
-  isValidModel,
-  validateModel,
-  getSafeModel,
-  getModelCategory,
-  getAllValidModels,
-
-  // Performance
-  measureAsync,
-  measureSync,
-  debounce,
-  throttle,
-  performanceTracker,
-
-  // Data transformation
-  extractBase64Data,
-  extractTextFromResponse,
-
-  // Image preparation
-  prepareImageFromUri,
-  prepareImage,
-  isValidBase64,
-
-  // Input builders
-  buildUpscaleInput,
-  buildPhotoRestoreInput,
-  buildRemoveBackgroundInput,
-  buildReplaceBackgroundInput
-} from '@umituz/react-native-ai-gemini-provider';
-```
-
-## 🎯 Purpose
-
-Use utility functions for common operations across the provider. Provides error handling, validation, performance monitoring, and data transformation capabilities.
-
-**When to use:**
-- Validate model IDs
-- Handle API errors
-- Monitor performance
-- Transform data formats
-- Prepare images for processing
-- Build complex inputs
-- Measure operation duration
-- Debounce/throttle functions
-
-## 📌 Strategy
-
-Utilities provide reusable, composable functions. This system:
-- Separates concerns from business logic
-- Provides consistent error handling
-- Enables performance monitoring
-- Simplifies data transformations
-- Validates inputs centrally
-- Builds complex inputs from simple data
-
-**Key Decision**: Use utility functions for cross-cutting concerns. Keep services focused on business logic, use utils for operational tasks.
-
-## ⚠️ Rules
-
-### Error Handling Rules
-- **MUST** catch and categorize all API errors
-- **SHOULD** use typed GeminiError instances
-- **MUST** check retryable status before retrying
-- **SHOULD** log errors appropriately
-- **MUST NOT** expose sensitive data in errors
-
-### Model Validation Rules
-- **MUST** validate model IDs before use
-- **SHOULD** use safe fallbacks for invalid models
-- **MUST** check model category for features
-- **SHOULD** validate early in request flow
-- **MUST NOT** allow arbitrary model IDs
-
-### Performance Rules
-- **SHOULD** measure critical operations
-- **MUST** track performance metrics
-- **SHOULD** use debounce/throttle for frequent calls
-- **MUST NOT** impact performance with monitoring
-- **SHOULD** aggregate metrics over time
-
-### Data Transformation Rules
-- **MUST** validate input data format
-- **SHOULD** handle edge cases (null, undefined)
-- **MUST** sanitize sensitive information
-- **SHOULD** preserve data integrity
-- **MUST** handle transformation errors
-
-### Image Preparation Rules
-- **MUST** validate base64 format
-- **SHOULD** handle different image formats
-- **MUST** extract MIME type correctly
-- **SHOULD** handle large images efficiently
-- **MUST** validate image data
-
-## 🤖 AI Agent Guidelines
-
-### When Handling Errors
-1. **CATCH** errors from API calls
-2. **MAP** to GeminiError using mapGeminiError()
-3. **CHECK** if retryable using isGeminiErrorRetryable()
-4. **CATEGORIZE** error type
-5. **HANDLE** appropriately (retry or fail)
-
-### When Validating Models
-1. **CHECK** model validity with isValidModel()
-2. **GET** safe model with getSafeModel()
-3. **DETERMINE** model category
-4. **VALIDATE** category supports feature
-5. **USE** validated model in requests
-
-### When Measuring Performance
-1. **WRAP** operation with measureAsync()
-2. **RECORD** duration with performanceTracker
-3. **ANALYZE** metrics periodically
-4. **IDENTIFY** slow operations
-5. **OPTIMIZE** based on data
-
-### When Preparing Images
-1. **VALIDATE** image source (URI or base64)
-2. **EXTRACT** base64 data if needed
-3. **DETERMINE** MIME type
-4. **PREPARE** image object
-5. **HANDLE** preparation errors
-
-### Code Style Rules
-- **USE** appropriate utility for each task
-- **VALIDATE** inputs early
-- **HANDLE** all error cases
-- **LOG** important operations
-- **COMMENT** complex transformations
-
-## 📦 Available Utilities
-
-### Error Management
-
-**Refer to**: [`ERROR_UTILITIES.md`](./ERROR_UTILITIES.md)
-
-**Functions:**
-- `mapGeminiError(error)` - Map error to GeminiError
-- `isGeminiErrorRetryable(error)` - Check if error is retryable
-- `categorizeGeminiError(error)` - Categorize error type
-- `createGeminiError(error)` - Create GeminiError instance
-
-### Model Validation
-
-**Refer to**: [`MODEL_VALIDATION_UTILS.md`](./MODEL_VALIDATION_UTILS.md)
-
-**Functions:**
-- `isValidModel(model)` - Check if model ID is valid
-- `validateModel(model)` - Validate or throw error
-- `getSafeModel(model, defaultType)` - Get safe model with fallback
-- `getModelCategory(model)` - Get model category
-- `getAllValidModels()` - Get all valid model IDs
-
-### Performance Tools
-
-**Refer to**: [`PERFORMANCE_UTILS.md`](./PERFORMANCE_UTILS.md)
-
-**Functions:**
-- `measureAsync(operation, metadata?)` - Measure async operation
-- `measureSync(operation, metadata?)` - Measure sync operation
-- `debounce(func, wait)` - Create debounced function
-- `throttle(func, limit)` - Create throttled function
-
-**Classes:**
-- `PerformanceTimer` - Timer for operations
-- `performanceTracker` - Global performance tracker
-
-### Data Transformation
-
-**Refer to**: [`DATA_TRANSFORMER_UTILS.md`](./DATA_TRANSFORMER_UTILS.md)
-
-**Functions:**
-- `extractBase64Data(base64)` - Extract base64 from data URL
-- `extractTextFromResponse(response)` - Extract text from Gemini response
-
-### Image Preparation
-
-**Refer to**: [`IMAGE_PREPARER_UTILS.md`](./IMAGE_PREPARER_UTILS.md)
-
-**Functions:**
-- `prepareImageFromUri(uri)` - Prepare image from URI
-- `prepareImage(base64, mimeType)` - Prepare image from base64
-- `isValidBase64(base64)` - Validate base64 format
-
-### Input Builders
-
-**Refer to**: [`INPUT_BUILDERS.md`](./INPUT_BUILDERS.md)
-
-**Single Image Features:**
-- `buildUpscaleInput(base64, options?)` - Build upscale input
-- `buildPhotoRestoreInput(base64, options?)` - Build photo restore input
-- `buildRemoveBackgroundInput(base64, options?)` - Build remove background input
-- `buildReplaceBackgroundInput(base64, options)` - Build replace background input
-
-**Dual Image Features:**
-- `buildFaceSwapInput(sourceBase64, targetBase64, options?)` - Build face swap input
-
-**Video Features:**
-- `buildAIHugInput(base64, options?)` - Build AI hug input
-- `buildAIKissInput(base64, options?)` - Build AI kiss input
-- `buildVideoFromDualImagesInput(base64a, base64b, options?)` - Build dual image video input
-
-## 🔗 Related Modules
-
-- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
-- **Services**: [`../services/README.md`](../services/README.md)
-- **Domain Types**: [`../../domain/README.md`](../../domain/README.md)
-
-## 📋 Error Categories
-
-### Retryable Errors
-- `QUOTA_EXCEEDED` - API quota exceeded
-- `RATE_LIMIT` - Rate limit hit
-- `NETWORK` - Network error
-- `TIMEOUT` - Request timeout
-- `SERVER` - Server error (5xx)
-
-### Non-Retryable Errors
-- `AUTHENTICATION` - Invalid credentials
-- `SAFETY` - Safety filter triggered
-- `MODEL_NOT_FOUND` - Invalid model
-- `VALIDATION` - Invalid request
-- `UNKNOWN` - Unknown error
-
-## 🎓 Usage Patterns
-
-### Error Handling Pattern
-1. Catch API error
-2. Map to GeminiError
-3. Check if retryable
-4. Retry or fail appropriately
-5. Log error for debugging
-
-### Model Validation Pattern
-1. Get user input for model
-2. Validate with isValidModel()
-3. Get safe model with fallback
-4. Check model category
-5. Use validated model
-
-### Performance Measurement Pattern
-1. Wrap operation with measureAsync()
-2. Record duration to performanceTracker
-3. Analyze metrics periodically
-4. Identify optimization opportunities
-5. Iterate on improvements
-
-### Image Processing Pattern
-1. Validate image source
-2. Prepare image with utilities
-3. Build input for feature
-4. Send to image service
-5. Handle result/errors
-
-## 🚨 Common Pitfalls
-
-### Don't
-- Skip model validation
-- Ignore error types
-- Measure too frequently (performance impact)
-- Mutate input data
-- Assume all models support all features
-
-### Do
-- Always validate model IDs
-- Handle all error categories
-- Use debounce/throttle for frequent operations
-- Keep transformations pure
-- Check model capabilities
-
----
-
-**Last Updated**: 2025-01-08
-**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)