@souscheflabs/ml-vision 0.1.0

package/dist/core/CacheManager.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * CacheManager - MMKV-based caching for ML Vision results
+ *
+ * Provides fast, synchronous caching for:
+ * - Barcode to product lookups
+ * - Product recognition results
+ * - Receipt parsing results
+ * - Model metadata
+ *
+ * Uses react-native-mmkv for ~30x faster access than AsyncStorage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheManager = exports.CACHE_TTL = void 0;
+exports.createCacheManager = createCacheManager;
+// ============================================================================
+// Cache Configuration
+// ============================================================================
+/**
+ * Default TTL values (in milliseconds)
+ */
+exports.CACHE_TTL = {
+    /** Barcode lookups - 7 days */
+    BARCODE: 7 * 24 * 60 * 60 * 1000,
+    /** Product recognition - 24 hours */
+    PRODUCT: 24 * 60 * 60 * 1000,
+    /** Receipt parsing - 1 hour */
+    RECEIPT: 60 * 60 * 1000,
+    /** Model metadata - until manually cleared */
+    MODEL: Infinity,
+    /** Server responses - 5 minutes */
+    SERVER: 5 * 60 * 1000,
+};
+/**
+ * Cache key prefixes for namespacing
+ */
+const CACHE_PREFIX = {
+    BARCODE: 'mlv_barcode_',
+    PRODUCT: 'mlv_product_',
+    RECEIPT: 'mlv_receipt_',
+    MODEL: 'mlv_model_',
+    CONFIG: 'mlv_config_',
+};
+// ============================================================================
+// CacheManager Class
+// ============================================================================
+/**
+ * CacheManager provides fast key-value caching using MMKV
+ *
+ * @example
+ * ```typescript
+ * const cache = new CacheManager(mmkvInstance);
+ *
+ * // Cache a barcode lookup
+ * cache.setBarcode('0123456789012', {
+ *   barcode: '0123456789012',
+ *   format: 'ean-13',
+ *   productId: 'prod_123',
+ *   productName: 'Example Product',
+ *   found: true,
+ * });
+ *
+ * // Retrieve later
+ * const product = cache.getBarcode('0123456789012');
+ * ```
+ */
+class CacheManager {
+    constructor(storage, customTTL) {
+        this.storage = storage;
+        this.defaultTTL = { ...exports.CACHE_TTL, ...customTTL };
+    }
+    // ==========================================================================
+    // Barcode Cache Methods
+    // ==========================================================================
+    /**
+     * Cache a barcode lookup result
+     */
+    setBarcode(barcode, data, ttl) {
+        const entry = {
+            data,
+            timestamp: Date.now(),
+            ttl: ttl ?? this.defaultTTL.BARCODE,
+        };
+        const key = `${CACHE_PREFIX.BARCODE}${barcode}`;
+        this.storage.set(key, JSON.stringify(entry));
+    }
+    /**
+     * Get a cached barcode lookup
+     * @returns The cached data or null if not found/expired
+     */
+    getBarcode(barcode) {
+        const key = `${CACHE_PREFIX.BARCODE}${barcode}`;
+        const cached = this.storage.getString(key);
+        if (!cached)
+            return null;
+        try {
+            const entry = JSON.parse(cached);
+            if (this.isExpired(entry)) {
+                this.storage.delete(key);
+                return null;
+            }
+            return entry.data;
+        }
+        catch {
+            this.storage.delete(key);
+            return null;
+        }
+    }
+    /**
+     * Check if a barcode is cached
+     */
+    hasBarcode(barcode) {
+        return this.getBarcode(barcode) !== null;
+    }
+    /**
+     * Delete a cached barcode
+     */
+    deleteBarcode(barcode) {
+        const key = `${CACHE_PREFIX.BARCODE}${barcode}`;
+        this.storage.delete(key);
+    }
+    // ==========================================================================
+    // Product Recognition Cache Methods
+    // ==========================================================================
+    /**
+     * Cache product recognition results for an image
+     * @param imageHash - Hash of the image (e.g., MD5 or perceptual hash)
+     */
+    setProductRecognition(imageHash, data, ttl) {
+        const entry = {
+            data,
+            timestamp: Date.now(),
+            ttl: ttl ?? this.defaultTTL.PRODUCT,
+        };
+        const key = `${CACHE_PREFIX.PRODUCT}${imageHash}`;
+        this.storage.set(key, JSON.stringify(entry));
+    }
+    /**
+     * Get cached product recognition for an image
+     */
+    getProductRecognition(imageHash) {
+        const key = `${CACHE_PREFIX.PRODUCT}${imageHash}`;
+        const cached = this.storage.getString(key);
+        if (!cached)
+            return null;
+        try {
+            const entry = JSON.parse(cached);
+            if (this.isExpired(entry)) {
+                this.storage.delete(key);
+                return null;
+            }
+            return entry.data;
+        }
+        catch {
+            this.storage.delete(key);
+            return null;
+        }
+    }
+    // ==========================================================================
+    // Model Metadata Cache Methods
+    // ==========================================================================
+    /**
+     * Store model metadata
+     */
+    setModelMetadata(modelId, metadata) {
+        const key = `${CACHE_PREFIX.MODEL}${modelId}`;
+        this.storage.set(key, JSON.stringify(metadata));
+    }
+    /**
+     * Get model metadata
+     */
+    getModelMetadata(modelId) {
+        const key = `${CACHE_PREFIX.MODEL}${modelId}`;
+        const cached = this.storage.getString(key);
+        if (!cached)
+            return null;
+        try {
+            return JSON.parse(cached);
+        }
+        catch {
+            return null;
+        }
+    }
+    // ==========================================================================
+    // Config Cache Methods
+    // ==========================================================================
+    /**
+     * Store a configuration value
+     */
+    setConfig(key, value) {
+        const fullKey = `${CACHE_PREFIX.CONFIG}${key}`;
+        this.storage.set(fullKey, JSON.stringify(value));
+    }
+    /**
+     * Get a configuration value
+     */
+    getConfig(key, defaultValue) {
+        const fullKey = `${CACHE_PREFIX.CONFIG}${key}`;
+        const cached = this.storage.getString(fullKey);
+        if (!cached)
+            return defaultValue;
+        try {
+            return JSON.parse(cached);
+        }
+        catch {
+            return defaultValue;
+        }
+    }
+    // ==========================================================================
+    // Cache Management Methods
+    // ==========================================================================
+    /**
+     * Clear all expired entries from the cache
+     * Call this periodically (e.g., on app start)
+     */
+    cleanupExpired() {
+        let removed = 0;
+        const allKeys = this.storage.getAllKeys();
+        for (const key of allKeys) {
+            // Only process our prefixed keys
+            const isOurKey = Object.values(CACHE_PREFIX).some((prefix) => key.startsWith(prefix));
+            if (!isOurKey)
+                continue;
+            // Skip model metadata (no TTL)
+            if (key.startsWith(CACHE_PREFIX.MODEL))
+                continue;
+            const value = this.storage.getString(key);
+            if (!value)
+                continue;
+            try {
+                const entry = JSON.parse(value);
+                if (this.isExpired(entry)) {
+                    this.storage.delete(key);
+                    removed++;
+                }
+            }
+            catch {
+                // Invalid entry, remove it
+                this.storage.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Clear all ML Vision cache entries
+     */
+    clearAll() {
+        const allKeys = this.storage.getAllKeys();
+        for (const key of allKeys) {
+            const isOurKey = Object.values(CACHE_PREFIX).some((prefix) => key.startsWith(prefix));
+            if (isOurKey) {
+                this.storage.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear cache by type
+     */
+    clearByType(type) {
+        const prefix = CACHE_PREFIX[type];
+        const allKeys = this.storage.getAllKeys();
+        for (const key of allKeys) {
+            if (key.startsWith(prefix)) {
+                this.storage.delete(key);
+            }
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const allKeys = this.storage.getAllKeys();
+        let barcodeEntries = 0;
+        let productEntries = 0;
+        let receiptEntries = 0;
+        let totalSizeBytes = 0;
+        for (const key of allKeys) {
+            if (key.startsWith(CACHE_PREFIX.BARCODE)) {
+                barcodeEntries++;
+            }
+            else if (key.startsWith(CACHE_PREFIX.PRODUCT)) {
+                productEntries++;
+            }
+            else if (key.startsWith(CACHE_PREFIX.RECEIPT)) {
+                receiptEntries++;
+            }
+            // Estimate size
+            const value = this.storage.getString(key);
+            if (value) {
+                totalSizeBytes += key.length + value.length;
+            }
+        }
+        return {
+            barcodeEntries,
+            productEntries,
+            receiptEntries,
+            totalSizeBytes,
+        };
+    }
+    // ==========================================================================
+    // Private Helper Methods
+    // ==========================================================================
+    /**
+     * Check if a cache entry has expired
+     */
+    isExpired(entry) {
+        if (entry.ttl === Infinity)
+            return false;
+        return Date.now() - entry.timestamp > entry.ttl;
+    }
+}
+exports.CacheManager = CacheManager;
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a CacheManager instance
+ * This is the recommended way to create a CacheManager
+ *
+ * @example
+ * ```typescript
+ * import { MMKV } from 'react-native-mmkv';
+ *
+ * const storage = new MMKV({ id: 'ml-vision-cache' });
+ * const cache = createCacheManager(storage);
+ * ```
+ */
+function createCacheManager(storage, customTTL) {
+    return new CacheManager(storage, customTTL);
+}

package/dist/core/MLVisionProvider.d.ts

@@ -0,0 +1,90 @@
+/**
+ * MLVisionProvider - Context provider for ML Vision functionality
+ *
+ * Provides:
+ * - Configuration management
+ * - Cache manager instance
+ * - Server client for fallback inference
+ * - Model manager for TFLite models
+ *
+ * @example
+ * ```typescript
+ * import { MLVisionProvider } from '@souschef/ml-vision';
+ *
+ * function App() {
+ *   return (
+ *     <MLVisionProvider
+ *       config={{
+ *         serverUrl: 'http://192.168.1.100:8000',
+ *         cacheEnabled: true,
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </MLVisionProvider>
+ *   );
+ * }
+ * ```
+ */
+import React, { type ReactNode } from 'react';
+import type { MMKV } from 'react-native-mmkv';
+import { CacheManager } from './CacheManager';
+import { ServerClient } from './ServerClient';
+import type { MLVisionConfig, ServerHealthResponse } from '../types';
+/**
+ * Context value provided by MLVisionProvider
+ */
+export interface MLVisionContextValue {
+    /** Merged configuration */
+    config: Required<MLVisionConfig>;
+    /** Whether the provider is fully initialized */
+    isInitialized: boolean;
+    /** Cache manager instance (null if caching disabled) */
+    cacheManager: CacheManager | null;
+    /** Server client for fallback inference (null if no serverUrl) */
+    serverClient: ServerClient | null;
+    /** Whether the server is available */
+    serverAvailable: boolean;
+    /** Server health info */
+    serverHealth: ServerHealthResponse | null;
+    /** Check server health */
+    checkServerHealth: () => Promise<ServerHealthResponse | null>;
+    /** Update configuration at runtime */
+    updateConfig: (updates: Partial<MLVisionConfig>) => void;
+}
+export interface MLVisionProviderProps {
+    children: ReactNode;
+    /** Configuration options */
+    config?: MLVisionConfig;
+    /** MMKV storage instance for caching (required if cacheEnabled) */
+    storage?: MMKV;
+    /** Callback when initialization completes */
+    onInitialized?: () => void;
+    /** Callback on initialization error */
+    onError?: (error: Error) => void;
+}
+/**
+ * MLVisionProvider - Wrap your app with this provider to use ML Vision hooks
+ */
+export declare function MLVisionProvider({ children, config: userConfig, storage, onInitialized, onError, }: MLVisionProviderProps): React.ReactElement;
+/**
+ * Hook to access the MLVision context
+ *
+ * @throws Error if used outside of MLVisionProvider
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { config, serverAvailable, cacheManager } = useMLVisionContext();
+ *
+ *   if (!serverAvailable) {
+ *     console.log('Running in offline mode');
+ *   }
+ * }
+ * ```
+ */
+export declare function useMLVisionContext(): MLVisionContextValue;
+/**
+ * Hook to check if MLVision is initialized
+ * Returns false if used outside provider (won't throw)
+ */
+export declare function useMLVisionReady(): boolean;

package/dist/core/MLVisionProvider.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MLVisionProvider = MLVisionProvider;
+exports.useMLVisionContext = useMLVisionContext;
+exports.useMLVisionReady = useMLVisionReady;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * MLVisionProvider - Context provider for ML Vision functionality
+ *
+ * Provides:
+ * - Configuration management
+ * - Cache manager instance
+ * - Server client for fallback inference
+ * - Model manager for TFLite models
+ *
+ * @example
+ * ```typescript
+ * import { MLVisionProvider } from '@souschef/ml-vision';
+ *
+ * function App() {
+ *   return (
+ *     <MLVisionProvider
+ *       config={{
+ *         serverUrl: 'http://192.168.1.100:8000',
+ *         cacheEnabled: true,
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </MLVisionProvider>
+ *   );
+ * }
+ * ```
+ */
+const react_1 = require("react");
+const CacheManager_1 = require("./CacheManager");
+const ServerClient_1 = require("./ServerClient");
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_CONFIG = {
+    serverUrl: '',
+    serverTimeout: 5000,
+    cacheEnabled: true,
+    cacheTTL: 24 * 60 * 60 * 1000, // 24 hours
+    modelUpdateCheck: true,
+    enableGPUDelegate: true,
+};
+// ============================================================================
+// Context
+// ============================================================================
+const MLVisionContext = (0, react_1.createContext)(null);
+// ============================================================================
+// Provider Component
+// ============================================================================
+/**
+ * MLVisionProvider - Wrap your app with this provider to use ML Vision hooks
+ */
+function MLVisionProvider({ children, config: userConfig, storage, onInitialized, onError, }) {
+    // Merge user config with defaults
+    const [config, setConfig] = (0, react_1.useState)(() => ({
+        ...DEFAULT_CONFIG,
+        ...userConfig,
+    }));
+    const [isInitialized, setIsInitialized] = (0, react_1.useState)(false);
+    const [serverAvailable, setServerAvailable] = (0, react_1.useState)(false);
+    const [serverHealth, setServerHealth] = (0, react_1.useState)(null);
+    // Create cache manager
+    const cacheManager = (0, react_1.useMemo)(() => {
+        if (!config.cacheEnabled || !storage) {
+            return null;
+        }
+        return (0, CacheManager_1.createCacheManager)(storage);
+    }, [config.cacheEnabled, storage]);
+    // Create server client
+    const serverClient = (0, react_1.useMemo)(() => {
+        if (!config.serverUrl) {
+            return null;
+        }
+        return (0, ServerClient_1.createServerClient)(config.serverUrl, config.serverTimeout);
+    }, [config.serverUrl, config.serverTimeout]);
+    // Check server health
+    const checkServerHealth = (0, react_1.useCallback)(async () => {
+        if (!serverClient) {
+            setServerAvailable(false);
+            setServerHealth(null);
+            return null;
+        }
+        try {
+            const health = await serverClient.checkHealth();
+            setServerAvailable(health.status === 'healthy');
+            setServerHealth(health);
+            return health;
+        }
+        catch {
+            setServerAvailable(false);
+            setServerHealth(null);
+            return null;
+        }
+    }, [serverClient]);
+    // Update config at runtime
+    const updateConfig = (0, react_1.useCallback)((updates) => {
+        setConfig((prev) => ({ ...prev, ...updates }));
+    }, []);
+    // Initialize on mount
+    (0, react_1.useEffect)(() => {
+        async function initialize() {
+            try {
+                // Clean up expired cache entries
+                if (cacheManager) {
+                    const removed = cacheManager.cleanupExpired();
+                    if (removed > 0) {
+                        console.log(`[MLVision] Cleaned up ${removed} expired cache entries`);
+                    }
+                }
+                // Check server health if configured
+                if (serverClient) {
+                    await checkServerHealth();
+                }
+                setIsInitialized(true);
+                onInitialized?.();
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error('Initialization failed');
+                console.error('[MLVision] Initialization error:', err);
+                onError?.(err);
+                // Still mark as initialized so the app can work in offline mode
+                setIsInitialized(true);
+            }
+        }
+        initialize();
+    }, [cacheManager, serverClient, checkServerHealth, onInitialized, onError]);
+    // Context value
+    const contextValue = (0, react_1.useMemo)(() => ({
+        config,
+        isInitialized,
+        cacheManager,
+        serverClient,
+        serverAvailable,
+        serverHealth,
+        checkServerHealth,
+        updateConfig,
+    }), [
+        config,
+        isInitialized,
+        cacheManager,
+        serverClient,
+        serverAvailable,
+        serverHealth,
+        checkServerHealth,
+        updateConfig,
+    ]);
+    return ((0, jsx_runtime_1.jsx)(MLVisionContext.Provider, { value: contextValue, children: children }));
+}
+// ============================================================================
+// Hook
+// ============================================================================
+/**
+ * Hook to access the MLVision context
+ *
+ * @throws Error if used outside of MLVisionProvider
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { config, serverAvailable, cacheManager } = useMLVisionContext();
+ *
+ *   if (!serverAvailable) {
+ *     console.log('Running in offline mode');
+ *   }
+ * }
+ * ```
+ */
+function useMLVisionContext() {
+    const context = (0, react_1.useContext)(MLVisionContext);
+    if (!context) {
+        throw new Error('useMLVisionContext must be used within an MLVisionProvider. ' +
+            'Wrap your app with <MLVisionProvider> to use ML Vision hooks.');
+    }
+    return context;
+}
+/**
+ * Hook to check if MLVision is initialized
+ * Returns false if used outside provider (won't throw)
+ */
+function useMLVisionReady() {
+    const context = (0, react_1.useContext)(MLVisionContext);
+    return context?.isInitialized ?? false;
+}