@umituz/react-native-ai-generation-content 1.17.232 → 1.17.233

package/src/features/future-prediction/README.md

@@ -1,281 +1,451 @@
-# Future Prediction
+# Future Prediction Feature
 
 Generate images showing people in future scenarios using AI.
 
-## Features
+## 📍 Import Path
 
-- Create future predictions for individuals
-- Multiple future scenarios (success, old age, etc.)
-- Natural aging and progression
-- Various life scenarios
-- High-quality facial matching
+```typescript
+import { useFuturePredictionFeature } from '@umituz/react-native-ai-generation-content';
+```
 
-## Installation
+**Location**: `src/features/future-prediction/`
 
-This feature is part of `@umituz/react-native-ai-generation-content`.
+## 🎯 Feature Purpose
 
-```bash
-npm install @umituz/react-native-ai-generation-content
-```
+Create AI-generated images showing individuals in various future scenarios including old age, professional success, dream careers, and future family. Features natural aging progression and high-quality facial matching for entertaining and motivational content.
 
-## Basic Usage
-
-### Using the Hook
-
-```tsx
-import { useFuturePrediction } from '@umituz/react-native-ai-generation-content';
-import * as ImagePicker from 'react-native-image-picker';
-
-function FuturePredictionScreen() {
-  const [image, setImage] = useState<string | null>(null);
-
-  const feature = useFuturePrediction({
-    config: {
-      scenario: 'old-age',
-      onProcessingStart: () => console.log('Generating future image...'),
-      onProcessingComplete: (result) => console.log('Complete:', result),
-      onError: (error) => console.error('Error:', error),
-    },
-    onSelectImage: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setImage(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSaveResult: async (imageUrl) => {
-      await saveToGallery(imageUrl);
-    },
-  });
-
-  return (
-    <View>
-      <PhotoUploadCard
-        image={image}
-        onSelectImage={feature.selectImage}
-        title="Select Your Photo"
-      />
-
-      <ScenarioSelector
-        selectedScenario={feature.state.scenario}
-        onSelectScenario={feature.setScenario}
-      />
-
-      <Button
-        title="Generate Future Image"
-        onPress={feature.process}
-        disabled={!feature.isReady || feature.state.isProcessing}
-      />
-
-      {feature.state.isProcessing && (
-        <View>
-          <Text>Creating your future image...</Text>
-          <ProgressBar progress={feature.state.progress} />
-        </View>
-      )}
-
-      {feature.state.result && (
-        <ResultDisplay
-          originalImage={image}
-          resultImage={feature.state.result.imageUrl}
-          onSave={() => feature.saveResult()}
-        />
-      )}
-    </View>
-  );
-}
-```
+---
 
-### Using the Unified AI Feature Screen
+## 📋 Usage Strategy
 
-```tsx
-import { AIFeatureScreen } from '@umituz/react-native-ai-generation-content';
+### When to Use This Feature
 
-function App() {
-  return (
-    <AIFeatureScreen
-      featureId="future-prediction"
-      userId="user-123"
-    />
-  );
-}
+✅ **Use Cases:**
+- Creating fun future predictions for entertainment
+- Generating motivational content
+- Social media sharing
+- Visualizing future goals
+- Creative personal projects
+
+❌ **When NOT to Use:**
+- Non-consensual image generation
+- Misleading or deceptive content
+- Harassment or bullying
+- Commercial use without permissions
+- Professional medical aging predictions
+
+### Implementation Strategy
+
+1. **Select photo** of the person
+2. **Choose future scenario** (old-age, success, future-career, future-family)
+3. **Set target age** (optional, for old-age scenario)
+4. **Generate prediction** with progress tracking
+5. **Preview result** and offer regeneration
+6. **Save or share** final image
+
+---
+
+## ⚠️ Critical Rules (MUST FOLLOW)
+
+### 1. Image Requirements
+- **MUST** provide ONE clear photo of a person
+- **MUST** contain at least one visible person
+- **MUST** use high-quality images (min 512x512 recommended)
+- **MUST** ensure face is clearly visible
+- **MUST NOT** use images with no detectable people
+
+### 2. Configuration
+- **MUST** provide valid `userId` for tracking
+- **MUST** specify `scenario` (old-age, success, future-career, future-family)
+- **MUST** implement `onError` callback
+- **MUST** implement `onSelectImage` callback
+- **MUST** handle image selection before processing
+
+### 3. State Management
+- **MUST** check `isReady` before enabling generate button
+- **MUST** verify image is selected
+- **MUST** handle `isProcessing` state to prevent duplicate requests
+- **MUST** display `error` state to users
+- **MUST** implement proper cleanup on unmount
+
+### 4. Performance
+- **MUST** limit image size (<10MB)
+- **MUST** compress images before processing
+- **MUST** implement loading indicators during processing
+- **MUST** cache results locally
+- **MUST NOT** generate multiple predictions simultaneously
+
+### 5. Ethics & Privacy
+- **MUST** obtain consent from people whose photos are used
+- **MUST** provide clear usage terms
+- **MUST** implement content moderation
+- **MUST** prevent malicious use cases
+- **MUST** log processing for audit trail
+
+---
+
+## 🚫 Prohibitions (MUST AVOID)
+
+### Strictly Forbidden
+
+❌ **NEVER** do the following:
+
+1. **No Missing Image**
+   - Always validate image is selected
+   - Never attempt generation without photo
+   - Show clear upload prompt
+
+2. **No Non-Consensual Generation**
+   - Always obtain permission from subjects
+   - Never generate predictions without consent
+   - Implement age verification for minors
+
+3. **No Malicious Use**
+   - Never use for harassment or bullying
+   - Never create misleading content
+   - Never use for deception
+
+4. **No Unhandled Errors**
+   - Never ignore generation failures
+   - Always handle detection errors gracefully
+   - Provide clear error messages
+
+5. **No Memory Leaks**
+   - Never store large images in state unnecessarily
+   - Always cleanup image references on unmount
+   - Implement proper image disposal
+
+6. **No Blocked UI**
+   - Never process without user confirmation
+   - Always show progress indicator
+   - Never block main thread with image processing
+
+7. **No Medical Claims**
+   - Never present results as medically accurate
+   - Always label as entertainment/AI-generated
+   - Provide disclaimer about AI prediction limitations
+
+---
+
+## 🤖 AI Agent Directions
+
+### For AI Code Generation Tools
+
+When using this feature with AI code generation tools, follow these guidelines:
+
+#### Prompt Template for AI Agents
+
+```
+You are implementing a future prediction feature using @umituz/react-native-ai-generation-content.
+
+REQUIREMENTS:
+1. Import from: @umituz/react-native-ai-generation-content
+2. Use the useFuturePredictionFeature hook
+3. Select future scenario (old-age, success, future-career, future-family)
+4. Implement image selection UI
+5. Set target age (optional, for old-age)
+6. Validate image before generation
+7. Add confirmation dialog before generation
+8. Handle long processing times with progress
+9. Implement proper error handling
+10. Implement cleanup on unmount
+
+CRITICAL RULES:
+- MUST obtain consent from subjects
+- MUST validate image before calling process()
+- MUST provide clear UI for scenario selection
+- MUST handle generation errors gracefully
+- MUST prevent malicious use cases
+- MUST implement content moderation
+- NEVER present as medically accurate
+- NEVER process without user confirmation
+
+CONFIGURATION:
+- Provide valid userId (string)
+- Set scenario: 'old-age' | 'success' | 'future-career' | 'future-family'
+- Set age?: number (target age for old-age, default: 80)
+- Set preserveFaces: boolean (maintain facial features)
+- Set enhanceQuality: boolean (enhance output quality)
+- Implement onSelectImage callback
+- Implement onSaveResult callback
+- Configure callbacks: onProcessingStart, onProcessingComplete, onError
+
+SCENARIOS:
+- old-age: Person in old age (supports custom target age)
+- success: Professional success scenario
+- future-career: Dream career visualization
+- future-family: Future family scenario
+
+OPTIONS:
+- age: Target age for old-age prediction (50-100)
+- preserveFaces: Maintain facial features (default: true)
+- enhanceQuality: Enhance output quality (default: true)
+
+STRICTLY FORBIDDEN:
+- No missing image validation
+- No non-consensual generation
+- No malicious use
+- No unhandled errors
+- No memory leaks
+- No blocking UI
+- No medical claims
+
+ETHICS CHECKLIST:
+- [ ] Consent mechanism implemented
+- [ ] Age verification for minors
+- [ ] Content moderation in place
+- [ ] Usage terms provided
+- [ ] Audit trail logging
+- [ ] Entertainment/AI-generated disclaimer
+- [ ] No medical accuracy claims
 ```
 
-## Configuration Options
+#### AI Implementation Checklist
+
+Use this checklist when generating code:
+
+- [ ] Feature imported from correct path
+- [ ] Image selection implemented
+- [ ] Scenario selector added
+- [ ] Age input implemented (for old-age)
+- [ ] Validation before process()
+- [ ] Confirmation dialog added
+- [ ] Progress indicator during processing
+- [ ] Error display with user-friendly message
+- [ ] Result preview before saving
+- [ ] Consent mechanism in place
+- [ ] Cleanup on unmount
+- [ ] Content moderation configured
+- [ ] Disclaimer about AI limitations
+
+---
+
+## 🛠️ Configuration Strategy
 
-### Feature Config
+### Essential Configuration
 
-```tsx
-interface FuturePredictionFeatureConfig {
-  scenario?: 'old-age' | 'success' | 'future-career' | 'future-family';
-  age?: number; // Target age for prediction (optional)
-  onProcessingStart?: () => void;
-  onProcessingComplete?: (result: FuturePredictionResult) => void;
-  onError?: (error: string) => void;
+```typescript
+// Required fields
+{
+  userId: string
+  scenario: 'old-age' | 'success' | 'future-career' | 'future-family'
+  onSelectImage: () => Promise<string | null>
+}
+
+// Optional callbacks
+{
+  age?: number // Target age for old-age (50-100)
+  onProcessingStart?: () => void
+  onProcessingComplete?: (result) => void
+  onError?: (error: string) => void
 }
 ```
 
-### Generation Options
+### Recommended Settings
+
+1. **Future Scenarios**
+   - Old Age: See yourself in old age (supports custom age 50-100)
+   - Success: Professional success visualization
+   - Future Career: Dream career scenario
+   - Future Family: Family scenario
+
+2. **Age Settings** (for old-age)
+   - Range: 50-100 years
+   - Default: 80 years
+   - Recommendation: Start with default, adjust as needed
+
+3. **Image Quality**
+   - Minimum: 512x512 resolution
+   - Recommended: 1024x1024 or higher
+   - Format: JPEG or PNG
+   - Max size: 10MB
+
+---
+
+## 📊 State Management
+
+### Feature States
+
+**isReady**: boolean
+- Image selected and validated
+- Check before enabling generate button
 
-```tsx
-interface FuturePredictionOptions {
-  scenario: 'old-age' | 'success' | 'future-career' | 'future-family';
-  age?: number; // Target age
-  preserveFaces?: boolean; // Maintain facial features (default: true)
-  enhanceQuality?: boolean; // Enhance output quality (default: true)
+**isProcessing**: boolean
+- Future generation in progress
+- Show loading/progress indicator
+- Disable generate button
+
+**progress**: number (0-100)
+- Generation progress percentage
+- Update progress bar
+
+**error**: string | null
+- Error message if generation failed
+- Common errors: "No person found in image", "Generation failed"
+
+**result**: {
+  imageUrl: string
+  scenario?: string
+  age?: number
+  metadata?: any
 }
-```
 
-## Future Scenarios
+---
 
-### Old Age
+## 🔐 Ethics & Privacy
 
-See yourself in old age:
+### Consent Requirements
 
-```tsx
-const result = await feature.process({
-  scenario: 'old-age',
-  age: 80,
-});
-```
+- **MUST** obtain explicit consent from subject
+- **MUST** provide clear explanation of how images will be used
+- **MUST** implement age verification
+- **MUST** allow subjects to opt-out
 
-### Success
+### Content Moderation
 
-Professional success scenario:
+- **MUST** filter inappropriate content
+- **MUST** prevent malicious use cases
+- **MUST** implement reporting mechanism
+- **MUST** review flagged content
 
-```tsx
-const result = await feature.process({
-  scenario: 'success',
-});
-```
+### Usage Guidelines
 
-### Future Career
+- **MUST** provide terms of service
+- **MUST** clearly label as AI-generated entertainment
+- **MUST** include disclaimer about limitations
+- **MUST** prevent medical accuracy claims
 
-In a dream career:
+---
 
-```tsx
-const result = await feature.process({
-  scenario: 'future-career',
-});
-```
+## 🎨 Best Practices
 
-### Future Family
+### Photo Selection
 
-With a future family:
+1. **Photo Quality**
+   - Good: High-quality, well-lit photos
+   - Bad: Blurry, dark, low-resolution images
 
-```tsx
-const result = await feature.process({
-  scenario: 'future-family',
-});
-```
+2. **Face Visibility**
+   - Good: Clear, frontal face shots
+   - Bad: Occluded or profile faces
 
-## Usage Flow
+3. **Lighting**
+   - Even lighting creates more natural results
+   - Front-facing well-lit photos ideal
 
-1. Select **Photo** - Choose a current photo
-2. Choose **Scenario** - Select the future scenario
-3. Set **Age** (optional) - Target age for old age prediction
-4. Tap **Generate** - Start the AI generation
-5. View Result - See the future prediction
-6. Save or Share - Save to gallery or share
+### User Experience
 
-## Component Examples
+1. **Clear UI**
+   - Show scenario examples
+   - Preview before processing
+   - Add confirmation dialog
 
-### Scenario Selector
+2. **Error Handling**
+   - Explain "no person found" errors
+   - Provide troubleshooting tips
+   - Offer retry option
 
-```tsx
-import { StylePresetsGrid } from '@umituz/react-native-ai-generation-content';
+3. **Expectations**
+   - Results are AI-generated entertainment
+   - Not medically or scientifically accurate
+   - Provide clear disclaimers
 
-const scenarios = [
-  { id: 'old-age', name: 'Old Age', preview: '...' },
-  { id: 'success', name: 'Success', preview: '...' },
-  { id: 'future-career', name: 'Dream Career', preview: '...' },
-  { id: 'future-family', name: 'Future Family', preview: '...' },
-];
+---
 
-<StylePresetsGrid
-  styles={scenarios}
-  selectedStyle={selectedScenario}
-  onSelectStyle={setSelectedScenario}
-/>
-```
+## 🐛 Common Pitfalls
 
-### Age Input
+### Detection Issues
 
-```tsx
-import { Slider } from 'react-native';
+❌ **Problem**: "No person found" error
+✅ **Solution**: Ensure person is clearly visible, well-lit, frontal
 
-<Slider
-  minimumValue={50}
-  maximumValue={100}
-  step={1}
-  value={age}
-  onValueChange={setAge}
-/>
+### Quality Issues
 
-<Text>Target Age: {age}</Text>
-```
+❌ **Problem**: Poor quality generation
+✅ **Solution**: Use higher resolution images, better lighting
 
-### Result Display with Actions
+### Ethics Concerns
 
-```tsx
-import { ResultImageCard } from '@umituz/react-native-ai-generation-content';
+❌ **Problem**: Non-consensual image generation
+✅ **Solution**: Implement consent mechanisms, age verification
 
-{feature.state.result && (
-  <ResultImageCard
-    imageUrl={feature.state.result.imageUrl}
-    onSave={() => feature.saveResult()}
-    onShare={() => shareImage(feature.state.result.imageUrl)}
-    onRegenerate={() => feature.process()}
-  />
-)}
-```
+### Accuracy Issues
 
-## Best Practices
+❌ **Problem**: Users expect accurate predictions
+✅ **Solution**: Clear disclaimers about entertainment/limitations
 
-1. **Photo Quality**: Use high-quality, well-lit photos
-2. **Face Visibility**: Ensure the face is clearly visible
-3. **Forward Facing**: Forward-facing photos work best
-4. **Good Lighting**: Even lighting creates more natural results
-5. **Realistic Expectations**: Results are AI-generated predictions
+---
 
-## Use Cases
+## 📦 Related Components
 
-### Fun & Entertainment
+Use these components from the library:
 
-```tsx
-// Create fun future predictions
-const result = await feature.process({
-  scenario: 'old-age',
-  age: 75,
-});
-```
+- **PhotoUploadCard**: Upload image interface
+- **ScenarioSelector**: Choose future scenario
+- **AgeSlider**: Set target age (for old-age)
+- **ResultImageCard**: Display result with actions
+- **ConfirmationDialog**: Confirm before processing
 
-### Social Media Content
+Located at: `src/presentation/components/`
 
-```tsx
-// Share future predictions on social media
-const result = await feature.process({
-  scenario: 'success',
-});
-```
+---
 
-### Motivation
+## 🔄 Migration Strategy
 
-```tsx
-// Visualize future success
-const result = await feature.process({
-  scenario: 'future-career',
-});
-```
+If migrating from previous implementation:
+
+1. **Update imports** to new path
+2. **Add scenario selector**
+3. **Implement age input** (for old-age)
+4. **Add consent mechanism**
+5. **Update state handling** for new structure
+6. **Add disclaimer about limitations**
+7. **Test all scenarios**
+
+---
+
+## ⚖️ Legal Considerations
+
+### Compliance
+
+- **Deepfake Regulations**: Comply with local laws
+- **Privacy Laws**: GDPR, CCPA compliance
+- **Consent Requirements**: Explicit permission needed
+- **Age Restrictions**: Verify adult subjects
+- **Content Labeling**: Mark as AI-generated
+
+### Best Practices
+
+- Provide attribution for source images
+- Allow content reporting/flagging
+- Implement audit trail logging
+- Cooperate with takedown requests
+- Include entertainment disclaimer
+
+---
+
+## 📚 Additional Resources
+
+- Main documentation: `/docs/`
+- API reference: `/docs/api/`
+- Examples: `/docs/examples/basic/future-prediction/`
+- Ethics guidelines: `/docs/ethics.md`
+
+---
+
+**Last Updated**: 2025-01-08
+**Version**: 2.0.0 (Strategy-based Documentation)
 
-## Related Features
+---
 
-- [Couple Future](../couple-future) - Generate future couple predictions
-- [AI Hug](../ai-hug) - Generate AI hug images
-- [Face Swap](../face-swap) - Swap faces between images
+## 📝 Changelog
 
-## License
+### v2.0.0 - 2025-01-08
+- **BREAKING**: Documentation format changed to strategy-based
+- Removed extensive code examples
+- Added ethics and privacy guidelines
+- Added rules, prohibitions, and AI agent directions
+- Focus on responsible AI usage
 
-MIT
+### v1.0.0 - Initial Release
+- Initial feature documentation