@umituz/react-native-ai-gemini-provider 2.0.13 → 2.0.15

package/src/infrastructure/telemetry/README.md

@@ -1,203 +0,0 @@
-# Telemetry Module
-
-Monitoring and logging system for AI operations. Tracks request, response, error, and retry events for observability and debugging.
-
-## 📍 Import Path
-
-```
-import { telemetryHooks } from '@umituz/react-native-ai-gemini-provider';
-```
-
-## 🎯 Purpose
-
-Use telemetry to monitor AI operations in real-time. Provides event-based system for tracking performance, errors, and usage patterns.
-
-**When to use:**
-- Monitor API call performance
-- Track error rates and types
-- Analyze usage patterns
-- Debug AI operations
-- Send events to analytics services
-- Implement custom monitoring
-- Track rate limiting
-- Generate metrics
-
-## 📌 Strategy
-
-Telemetry provides visibility into AI operations. This system:
-- Uses publish-subscribe pattern for events
-- Supports multiple listeners simultaneously
-- Emits events for all operations
-- Provides timing and metadata
-- Enables custom monitoring solutions
-- Integrates with analytics platforms
-
-**Key Decision**: Subscribe to telemetry events early in application lifecycle. Use events for monitoring, analytics, and debugging without modifying core services.
-
-## ⚠️ Rules
-
-### Usage Rules
-- **MUST** subscribe to events before operations
-- **SHOULD** unsubscribe when done
-- **MUST NOT** emit sensitive data in events
-- **SHOULD** aggregate metrics for performance
-- **MUST** handle listener errors gracefully
-
-### Event Subscription Rules
-- **SHOULD** subscribe at application startup
-- **MUST** store unsubscribe function
-- **SHOULD** handle all event types
-- **MUST NOT** block event emission
-- **SHOULD** filter events as needed
-
-### Data Privacy Rules
-- **MUST NOT** log API keys in events
-- **SHOULD NOT** include user data in metadata
-- **MUST** sanitize sensitive information
-- **SHOULD** use anonymized IDs
-- **MUST** comply with privacy policies
-
-### Performance Rules
-- **SHOULD** keep listeners lightweight
-- **MUST** avoid expensive operations in listeners
-- **SHOULD** batch event processing
-- **MUST NOT** block main thread
-- **SHOULD** use async operations for heavy processing
-
-## 🤖 AI Agent Guidelines
-
-### When Adding Telemetry
-1. **SUBSCRIBE** to telemetry events early
-2. **HANDLE** all event types appropriately
-3. **AGGREGATE** metrics for analysis
-4. **SEND** to monitoring/analytics service
-5. **UNSUBSCRIBE** on cleanup
-
-### When Creating Custom Monitoring
-1. **DEFINE** metrics to track
-2. **CREATE** data structures for aggregation
-3. **IMPLEMENT** event filtering
-4. **CALCULATE** statistics periodically
-5. **EXPORT** metrics for visualization
-
-### When Debugging with Telemetry
-1. **ADD** verbose logging for events
-2. **TRACK** request/response correlation
-3. **MONITOR** error patterns
-4. **ANALYZE** performance metrics
-5. **IDENTIFY** bottlenecks
-
-### Code Style Rules
-- **USE** unsubscribe pattern for cleanup
-- **FILTER** events by type or model
-- **AGGREGATE** metrics efficiently
-- **HANDLE** errors in listeners
-- **LOG** important state changes
-
-## 📦 Available Telemetry
-
-### TelemetryHooks
-
-**Refer to**: [`TelemetryHooks.ts`](./TelemetryHooks.ts)
-
-**Singleton instance**: `telemetryHooks`
-
-**Methods:**
-- `subscribe(listener)` - Add event listener
-- `emit(event)` - Emit custom event
-- `logRequest(model, feature?)` - Log request start
-- `logResponse(model, startTime, feature?, metadata?)` - Log response
-- `logError(model, error, feature?)` - Log error
-- `logRetry(model, attempt, feature?)` - Log retry
-- `clear()` - Clear all listeners
-- `getListenerCount()` - Get active listener count
-
-## 🔗 Related Modules
-
-- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
-- **Services**: [`../services/README.md`](../services/README.md)
-- **Interceptors**: [`../interceptors/README.md`](../interceptors/README.md)
-
-## 📋 Event Types
-
-### Request Event
-Emitted when operation starts.
-- Contains model and feature
-- Includes timestamp
-- No duration yet
-
-### Response Event
-Emitted when operation completes.
-- Contains model and feature
-- Includes duration in milliseconds
-- May include metadata (token count, finish reason)
-
-### Error Event
-Emitted when operation fails.
-- Contains model and feature
-- Includes error information
-- May include error type
-
-### Retry Event
-Emitted when retry is attempted.
-- Contains model and feature
-- Includes attempt number
-- Tracks retry behavior
-
-## 🎓 Usage Patterns
-
-### Basic Monitoring
-1. Import `telemetryHooks`
-2. Subscribe to events with listener function
-3. Handle different event types
-4. Store unsubscribe function
-5. Unsubscribe on cleanup
-
-### Analytics Integration
-1. Subscribe to telemetry events
-2. Transform events to analytics format
-3. Send to analytics service
-4. Filter sensitive information
-5. Handle errors gracefully
-
-### Performance Tracking
-1. Track response times by model
-2. Calculate statistics (avg, min, max)
-3. Monitor trends over time
-4. Alert on slow operations
-5. Generate performance reports
-
-### Error Tracking
-1. Subscribe to error events
-2. Categorize errors by type
-3. Track error rates
-4. Send to error tracking service
-5. Monitor for anomalies
-
-### Custom Dashboard
-1. Aggregate event data
-2. Calculate statistics
-3. Track model usage
-4. Monitor success rates
-5. Generate dashboard metrics
-
-## 🚨 Common Pitfalls
-
-### Don't
-- Forget to unsubscribe from events
-- Log sensitive data in events
-- Block event emission with heavy processing
-- Subscribe multiple times without cleanup
-- Emit custom events without proper format
-
-### Do
-- Subscribe early in application lifecycle
-- Clean up listeners when done
-- Keep listeners lightweight
-- Aggregate metrics efficiently
-- Handle all event types appropriately
-
----
-
-**Last Updated**: 2025-01-08
-**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/telemetry/TELEMETRY_SYSTEM.md

@@ -1,200 +0,0 @@
-# Telemetry System
-
-Monitoring and logging system for AI operations. Allows applications to track requests, responses, errors, and retries in real-time.
-
-## 📍 Import Path
-
-```
-import { telemetryHooks } from '@umituz/react-native-ai-gemini-provider';
-```
-
-## 🎯 Purpose
-
-Use telemetry to monitor AI operations in real-time. Provides event-based system for tracking performance, errors, and usage patterns.
-
-**When to use:**
-- Monitor API call performance
-- Track error rates and types
-- Analyze usage patterns
-- Debug AI operations
-- Send events to analytics services
-- Track rate limiting
-
-## 📌 Strategy
-
-Telemetry provides visibility into AI operations. This system:
-- Uses publish-subscribe pattern for events
-- Supports multiple listeners simultaneously
-- Emits events for all operations
-- Provides timing and metadata
-- Enables custom monitoring solutions
-
-**Key Decision**: Subscribe to telemetry events early in application lifecycle. Use events for monitoring, analytics, and debugging.
-
-## ⚠️ Rules
-
-### Usage Rules
-- **MUST** subscribe to events before operations
-- **SHOULD** unsubscribe when done
-- **MUST NOT** emit sensitive data in events
-- **SHOULD** aggregate metrics for performance
-- **MUST** handle listener errors gracefully
-
-### Event Subscription Rules
-- **SHOULD** subscribe at application startup
-- **MUST** store unsubscribe function
-- **SHOULD** handle all event types
-- **MUST NOT** block event emission
-- **SHOULD** filter events as needed
-
-### Data Privacy Rules
-- **MUST NOT** log API keys in events
-- **SHOULD NOT** include user data in metadata
-- **MUST** sanitize sensitive information
-- **SHOULD** use anonymized IDs
-- **MUST** comply with privacy policies
-
-### Performance Rules
-- **SHOULD** keep listeners lightweight
-- **MUST** avoid expensive operations in listeners
-- **SHOULD** batch event processing
-- **MUST NOT** block main thread
-- **SHOULD** use async operations for heavy processing
-
-## 🤖 AI Agent Guidelines
-
-### When Adding Telemetry
-1. **SUBSCRIBE** to telemetry events early
-2. **HANDLE** all event types appropriately
-3. **AGGREGATE** metrics for analysis
-4. **SEND** to monitoring/analytics service
-5. **UNSUBSCRIBE** on cleanup
-
-### When Creating Custom Monitoring
-1. **DEFINE** metrics to track
-2. **CREATE** data structures for aggregation
-3. **IMPLEMENT** event filtering
-4. **CALCULATE** statistics periodically
-5. **EXPORT** metrics for visualization
-
-### When Debugging with Telemetry
-1. **ADD** verbose logging for events
-2. **TRACK** request/response correlation
-3. **MONITOR** error patterns
-4. **ANALYZE** performance metrics
-5. **IDENTIFY** bottlenecks
-
-### Code Style Rules
-- **USE** unsubscribe pattern for cleanup
-- **FILTER** events by type or model
-- **AGGREGATE** metrics efficiently
-- **HANDLE** errors in listeners
-- **LOG** important state changes
-
-## 📦 Available System
-
-### telemetryHooks
-
-**Refer to**: [`TelemetryHooks.ts`](./TelemetryHooks.ts)
-
-**Singleton instance**
-
-**Methods:**
-- `subscribe(listener)` - Add event listener
-- `emit(event)` - Emit custom event
-- `logRequest(model, feature?)` - Log request start
-- `logResponse(model, startTime, feature?, metadata?)` - Log response
-- `logError(model, error, feature?)` - Log error
-- `logRetry(model, attempt, feature?)` - Log retry
-- `clear()` - Clear all listeners
-- `getListenerCount()` - Get active listener count
-
-## 🔗 Related Modules
-
-- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
-- **Services**: [`../services/README.md`](../services/README.md)
-- **Interceptors**: [`../interceptors/README.md`](../interceptors/README.md)
-
-## 📋 Event Types
-
-### Request Event
-Emitted when operation starts.
-- Contains model and feature
-- Includes timestamp
-- No duration yet
-
-### Response Event
-Emitted when operation completes.
-- Contains model and feature
-- Includes duration in milliseconds
-- May include metadata (token count, finish reason)
-
-### Error Event
-Emitted when operation fails.
-- Contains model and feature
-- Includes error information
-- May include error type
-
-### Retry Event
-Emitted when retry is attempted.
-- Contains model and feature
-- Includes attempt number
-- Tracks retry behavior
-
-## 🎓 Usage Patterns
-
-### Basic Monitoring
-1. Subscribe to telemetry events
-2. Track metrics in event handler
-3. Send to analytics/monitoring service
-4. Aggregate and analyze metrics
-5. Unsubscribe when done
-
-### Analytics Integration
-1. Subscribe to telemetry events
-2. Transform events to analytics format
-3. Send to analytics service
-4. Filter sensitive information
-5. Handle errors gracefully
-
-### Performance Tracking
-1. Track response times by model
-2. Calculate statistics (avg, min, max)
-3. Monitor trends over time
-4. Alert on slow operations
-5. Generate performance reports
-
-### Error Tracking
-1. Subscribe to error events
-2. Categorize errors by type
-3. Track error rates
-4. Send to error tracking service
-5. Monitor for anomalies
-
-### Custom Dashboard
-1. Aggregate event data
-2. Calculate statistics
-3. Track model usage
-4. Monitor success rates
-5. Generate dashboard metrics
-
-## 🚨 Common Pitfalls
-
-### Don't
-- Forget to unsubscribe from events
-- Log sensitive data in events
-- Block event emission with heavy processing
-- Subscribe multiple times without cleanup
-- Emit custom events without proper format
-
-### Do
-- Subscribe early in application lifecycle
-- Clean up listeners when done
-- Keep listeners lightweight
-- Aggregate telemetry metrics
-- Handle all event types appropriately
-
----
-
-**Last Updated**: 2025-01-08
-**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/presentation/README.md

@@ -1,187 +0,0 @@
-# Presentation Layer
-
-Bridge between UI layer and service layer. Contains React components and hooks for UI integration.
-
-## 📍 Import Path
-
-```
-import { useGemini } from '@umituz/react-native-ai-gemini-provider';
-```
-
-## 🎯 Purpose
-
-Use presentation layer to integrate AI functionality into React Native UI. Provides React hooks and state management.
-
-**When to use:**
-- Add AI features to React Native components
-- Manage AI operation state in UI
-- Handle loading and error states
-- Create AI-powered user interfaces
-- Build chat interfaces and forms
-
-## 📌 Strategy
-
-Presentation layer abstracts service complexity. This layer:
-- Provides React hooks for AI operations
-- Manages loading, error, and result states
-- Handles component lifecycle
-- Simplifies UI integration
-- Enables reactive AI interactions
-
-**Key Decision**: Use hooks for React Native UI components. They provide clean, declarative integration with AI services.
-
-## ⚠️ Rules
-
-### Usage Rules
-- **MUST** initialize provider before using hooks
-- **SHOULD** use hooks only in React components
-- **MUST** handle loading and error states
-- **SHOULD** implement cleanup on unmount
-- **MUST NOT** use hooks outside React functions
-
-### State Management Rules
-- **SHOULD** display loading indicators
-- **MUST** handle and display errors
-- **SHOULD** implement success callbacks
-- **MUST** reset state when appropriate
-- **SHOULD NOT** ignore state changes
-
-### UI Integration Rules
-- **MUST** provide user feedback during operations
-- **SHOULD** disable controls during loading
-- **MUST** handle all error states gracefully
-- **SHOULD** update UI progressively
-- **MUST NOT** block UI thread
-
-### Performance Rules
-- **SHOULD** implement cleanup on unmount
-- **MUST** cancel operations on unmount
-- **SHOULD** use memoization where appropriate
-- **MUST NOT** create memory leaks
-- **SHOULD** optimize re-renders
-
-## 🤖 AI Agent Guidelines
-
-### When Modifying Presentation Layer
-1. **READ** existing hooks first
-2. **UNDERSTAND** React patterns
-3. **MAINTAIN** backward compatibility
-4. **ADD** tests for new functionality
-5. **UPDATE** documentation
-
-### When Adding New Hooks
-1. **CHECK** if similar hook exists
-2. **FOLLOW** existing hook patterns
-3. **USE** established state management
-4. **DOCUMENT** in hook documentation
-5. **ADD** examples to tests (not docs)
-
-### When Creating Components
-1. **FOLLOW** React best practices
-2. **USE** hooks for state management
-3. **HANDLE** all edge cases
-4. **PROVIDE** TypeScript types
-5. **TEST** component behavior
-
-### Code Style Rules
-- **FOLLOW** React hooks rules
-- **USE** useMemo/useCallback for optimization
-- **VALIDATE** props
-- **HANDLE** errors gracefully
-- **COMMENT** complex logic only
-
-## 📦 Available Modules
-
-### React Hooks
-
-**useGemini**: Main hook for AI text generation
-
-**Refer to**: [`hooks/README.md`](./hooks/README.md)
-
-**Files:**
-- [`hooks/use-gemini.ts`](./hooks/use-gemini.ts) - Hook implementation
-- [`hooks/USE_GEMINI_HOOK.md`](./hooks/USE_GEMINI_HOOK.md) - Detailed documentation
-
-## 🔗 Related Modules
-
-- **Services**: [`../infrastructure/services/README.md`](../infrastructure/services/README.md)
-- **Domain Types**: [`../domain/README.md`](../domain/README.md)
-- **Providers**: [`../providers/README.md`](../providers/README.md)
-
-## 📋 Hook Features
-
-### State Management
-- `result`: Generated content
-- `isGenerating`: Loading state
-- `error`: Error message
-- `reset`: Clear all state
-
-### Methods
-- `generate(prompt)`: Generate text from prompt
-- `generateWithImage(prompt, image, mimeType)`: Generate with image context
-- `reset()`: Clear all state
-
-### Configuration
-- `model`: Model ID to use
-- `generationConfig`: Generation parameters
-- `onSuccess`: Success callback
-- `onError`: Error callback
-
-## 🎓 Usage Patterns
-
-### Basic Integration
-1. Import hook in component
-2. Call `useGemini()` hook
-3. Use returned methods and state
-4. Display loading, error, and result states
-5. Handle user interactions
-
-### Chat Interface
-1. Use hook for AI responses
-2. Maintain messages array in state
-3. Call `generate()` on user input
-4. Update messages with result
-5. Display conversation
-
-### Form Integration
-1. Integrate hook with form
-2. Call generation on form submit
-3. Disable form during generation
-4. Display errors appropriately
-5. Handle success/failure
-
-### Image Analysis
-1. Use `generateWithImage()` method
-2. Provide base64 image data
-3. Handle loading and result states
-4. Display analysis result
-5. Handle errors
-
-### State Resetting
-1. Use `reset()` to clear state
-2. Implement cleanup on unmount
-3. Reset before new operations
-4. Clear previous results
-5. Handle user actions
-
-## 🚨 Common Pitfalls
-
-### Don't
-- Use hooks outside React functions
-- Forget to handle loading states
-- Ignore error states
-- Skip cleanup on unmount
-- Block UI during operations
-
-### Do
-- Always handle loading and error states
-- Provide user feedback
-- Implement cleanup
-- Disable controls during loading
-- Reset state appropriately
-- Handle all edge cases
-
----
-
-**Last Updated**: 2025-01-08
-**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)