vfbquery 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

vfbquery/cache_enhancements.py

@@ -0,0 +1,465 @@
+"""
+VFBquery Caching Enhancements
+
+This module implements caching optimizations inspired by VFB_connect 
+to improve VFBquery performance for repeated queries.
+
+Features:
+1. Term info result caching (similar to VFB_connect's VFBTerm cache)
+2. SOLR query result caching
+3. Query result caching for get_instances and other functions
+4. Configurable cache expiry and size limits
+5. Memory-based and disk-based caching options
+"""
+
+import os
+import json
+import time
+import pickle
+import hashlib
+from pathlib import Path
+from typing import Dict, Any, Optional, Union
+from functools import lru_cache, wraps
+from dataclasses import dataclass, asdict
+import threading
+
+# Custom JSON encoder for caching
+from .vfb_queries import NumpyEncoder
+
+@dataclass
+class CacheConfig:
+    """Configuration for VFBquery caching system."""
+    enabled: bool = True
+    memory_cache_size_mb: int = 2048  # Max memory cache size in MB (2GB default)
+    max_items: int = 10000  # Max items in memory cache (fallback limit)
+    disk_cache_enabled: bool = True
+    disk_cache_dir: Optional[str] = None
+    cache_ttl_hours: int = 2160  # Cache time-to-live in hours (3 months = 90 days * 24 hours)
+    solr_cache_enabled: bool = True
+    term_info_cache_enabled: bool = True
+    query_result_cache_enabled: bool = True
+
+class VFBQueryCache:
+    """
+    Enhanced caching system for VFBquery inspired by VFB_connect optimizations.
+    
+    Provides multiple layers of caching:
+    - Memory cache for frequently accessed items (size-limited)
+    - Disk cache for persistence across sessions  
+    - Query result caching for expensive operations
+    """
+    
+    def __init__(self, config: Optional[CacheConfig] = None):
+        self.config = config or CacheConfig()
+        self._memory_cache: Dict[str, Dict[str, Any]] = {}
+        self._cache_stats = {'hits': 0, 'misses': 0, 'memory_size_bytes': 0}
+        self._lock = threading.RLock()
+        
+        # Set up disk cache directory
+        if self.config.disk_cache_enabled:
+            if self.config.disk_cache_dir:
+                self.cache_dir = Path(self.config.disk_cache_dir)
+            else:
+                # Use similar location to VFB_connect
+                self.cache_dir = Path.home() / '.vfbquery_cache'
+            self.cache_dir.mkdir(exist_ok=True)
+        
+        # Enable caching based on environment variable (like VFB_connect)
+        env_enabled = os.getenv('VFBQUERY_CACHE_ENABLED', '').lower()
+        if env_enabled in ('false', '0', 'no'):
+            self.config.enabled = False
+    
+    def _generate_cache_key(self, prefix: str, *args, **kwargs) -> str:
+        """Generate a cache key from function arguments."""
+        # Create deterministic hash from arguments
+        key_data = f"{prefix}:{args}:{sorted(kwargs.items())}"
+        return hashlib.md5(key_data.encode()).hexdigest()
+    
+    def _is_cache_valid(self, cache_entry: Dict[str, Any]) -> bool:
+        """Check if cache entry is still valid based on TTL."""
+        if not cache_entry or 'timestamp' not in cache_entry:
+            return False
+        
+        age_hours = (time.time() - cache_entry['timestamp']) / 3600
+        return age_hours < self.config.cache_ttl_hours
+    
+    def _get_from_memory(self, cache_key: str) -> Optional[Any]:
+        """Get item from memory cache."""
+        with self._lock:
+            if cache_key in self._memory_cache:
+                entry = self._memory_cache[cache_key]
+                if self._is_cache_valid(entry):
+                    self._cache_stats['hits'] += 1
+                    return entry['data']
+                else:
+                    # Remove expired entry and update memory size tracking
+                    expired_entry = self._memory_cache.pop(cache_key)
+                    self._cache_stats['memory_size_bytes'] -= expired_entry.get('size_bytes', 0)
+            
+            self._cache_stats['misses'] += 1
+            return None
+    
+    def _get_object_size(self, obj: Any) -> int:
+        """Estimate memory size of an object in bytes."""
+        try:
+            import sys
+            if isinstance(obj, (str, bytes)):
+                return len(obj)
+            elif isinstance(obj, dict):
+                return sum(self._get_object_size(k) + self._get_object_size(v) for k, v in obj.items())
+            elif isinstance(obj, (list, tuple)):
+                return sum(self._get_object_size(item) for item in obj)
+            else:
+                # Fallback: use sys.getsizeof for other objects
+                return sys.getsizeof(obj)
+        except:
+            # If size estimation fails, assume 1KB
+            return 1024
+
+    def _store_in_memory(self, cache_key: str, data: Any):
+        """Store item in memory cache with size-based LRU eviction."""
+        with self._lock:
+            entry = {
+                'data': data,
+                'timestamp': time.time(),
+                'size_bytes': self._get_object_size(data)
+            }
+            
+            # Check if we need to evict items to stay under memory limit
+            max_size_bytes = self.config.memory_cache_size_mb * 1024 * 1024
+            
+            # If this single item is larger than the cache limit, don't cache it
+            if entry['size_bytes'] > max_size_bytes:
+                return
+            
+            # Evict items if adding this one would exceed memory limit or max items
+            while (len(self._memory_cache) >= self.config.max_items or
+                   self._cache_stats['memory_size_bytes'] + entry['size_bytes'] > max_size_bytes):
+                if not self._memory_cache:
+                    break
+                # Remove oldest item (first in dict)
+                oldest_key = next(iter(self._memory_cache))
+                old_entry = self._memory_cache.pop(oldest_key)
+                self._cache_stats['memory_size_bytes'] -= old_entry.get('size_bytes', 0)
+            
+            # Add new entry
+            self._memory_cache[cache_key] = entry
+            self._cache_stats['memory_size_bytes'] += entry['size_bytes']
+    
+    def _get_from_disk(self, cache_key: str) -> Optional[Any]:
+        """Get item from disk cache."""
+        if not self.config.disk_cache_enabled:
+            return None
+        
+        cache_file = self.cache_dir / f"{cache_key}.pkl"
+        if cache_file.exists():
+            try:
+                with open(cache_file, 'rb') as f:
+                    entry = pickle.load(f)
+                    if self._is_cache_valid(entry):
+                        return entry['data']
+                    else:
+                        # Remove expired file
+                        cache_file.unlink()
+            except Exception:
+                # If file is corrupted, remove it
+                cache_file.unlink(missing_ok=True)
+        
+        return None
+    
+    def _store_on_disk(self, cache_key: str, data: Any):
+        """Store item on disk cache."""
+        if not self.config.disk_cache_enabled:
+            return
+        
+        cache_file = self.cache_dir / f"{cache_key}.pkl"
+        try:
+            entry = {
+                'data': data,
+                'timestamp': time.time()
+            }
+            with open(cache_file, 'wb') as f:
+                pickle.dump(entry, f)
+        except Exception as e:
+            print(f"Warning: Could not save to disk cache: {e}")
+    
+    def get(self, cache_key: str) -> Optional[Any]:
+        """Get item from cache (memory first, then disk)."""
+        if not self.config.enabled:
+            return None
+        
+        # Try memory cache first
+        result = self._get_from_memory(cache_key)
+        if result is not None:
+            return result
+        
+        # Try disk cache
+        result = self._get_from_disk(cache_key)
+        if result is not None:
+            # Store in memory for future access
+            self._store_in_memory(cache_key, result)
+            return result
+        
+        return None
+    
+    def set(self, cache_key: str, data: Any):
+        """Store item in cache (both memory and disk)."""
+        if not self.config.enabled:
+            return
+        
+        self._store_in_memory(cache_key, data)
+        self._store_on_disk(cache_key, data)
+    
+    def clear(self):
+        """Clear all caches."""
+        with self._lock:
+            self._memory_cache.clear()
+            self._cache_stats['memory_size_bytes'] = 0
+            
+        if self.config.disk_cache_enabled and hasattr(self, 'cache_dir') and self.cache_dir.exists():
+            for cache_file in self.cache_dir.glob("*.pkl"):
+                cache_file.unlink()
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        total_requests = self._cache_stats['hits'] + self._cache_stats['misses']
+        hit_rate = (self._cache_stats['hits'] / total_requests * 100) if total_requests > 0 else 0
+        memory_size_mb = self._cache_stats.get('memory_size_bytes', 0) / (1024 * 1024)
+        
+        return {
+            'enabled': self.config.enabled,
+            'memory_cache_items': len(self._memory_cache),
+            'memory_cache_size_mb': round(memory_size_mb, 2),
+            'memory_cache_limit_mb': self.config.memory_cache_size_mb,
+            'max_items': self.config.max_items,
+            'hits': self._cache_stats['hits'],
+            'misses': self._cache_stats['misses'],
+            'hit_rate_percent': round(hit_rate, 2),
+            'disk_cache_enabled': self.config.disk_cache_enabled,
+            'cache_ttl_hours': self.config.cache_ttl_hours,
+            'cache_ttl_days': round(self.config.cache_ttl_hours / 24, 1)
+        }
+
+
+# Global cache instance
+_global_cache = VFBQueryCache()
+
+def configure_cache(config: CacheConfig):
+    """Configure the global cache instance."""
+    global _global_cache
+    _global_cache = VFBQueryCache(config)
+
+def get_cache() -> VFBQueryCache:
+    """Get the global cache instance."""
+    return _global_cache
+
+def cache_result(cache_prefix: str, enabled_check: Optional[str] = None):
+    """
+    Decorator to cache function results.
+    
+    Args:
+        cache_prefix: Prefix for cache keys
+        enabled_check: Config attribute to check if this cache type is enabled
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            cache = get_cache()
+            
+            # Check if this specific cache type is enabled
+            if enabled_check and not getattr(cache.config, enabled_check, True):
+                return func(*args, **kwargs)
+            
+            # Generate cache key
+            cache_key = cache._generate_cache_key(cache_prefix, *args, **kwargs)
+            
+            # Try to get from cache
+            cached_result = cache.get(cache_key)
+            if cached_result is not None:
+                return cached_result
+            
+            # Execute function and cache result
+            result = func(*args, **kwargs)
+            if result is not None:  # Only cache non-None results
+                cache.set(cache_key, result)
+            
+            return result
+        
+        return wrapper
+    return decorator
+
+
+def enable_vfbquery_caching(
+    cache_ttl_hours: int = 2160,  # 3 months default
+    memory_cache_size_mb: int = 2048,  # 2GB default
+    max_items: int = 10000,
+    disk_cache_enabled: bool = True,
+    disk_cache_dir: Optional[str] = None
+):
+    """
+    Enable VFBquery caching with specified configuration.
+    
+    Args:
+        cache_ttl_hours: Cache time-to-live in hours (default: 2160 = 3 months)
+        memory_cache_size_mb: Maximum memory cache size in MB (default: 2048 = 2GB)  
+        max_items: Maximum number of items in memory cache (default: 10000)
+        disk_cache_enabled: Enable persistent disk caching (default: True)
+        disk_cache_dir: Custom cache directory path (optional)
+    
+    Usage:
+        from vfbquery.cache_enhancements import enable_vfbquery_caching
+        enable_vfbquery_caching()  # Use defaults: 3 months TTL, 2GB memory
+        enable_vfbquery_caching(cache_ttl_hours=720, memory_cache_size_mb=1024)  # 1 month, 1GB
+    """
+    config = CacheConfig(
+        enabled=True,
+        cache_ttl_hours=cache_ttl_hours,
+        memory_cache_size_mb=memory_cache_size_mb,
+        max_items=max_items,
+        disk_cache_enabled=disk_cache_enabled,
+        disk_cache_dir=disk_cache_dir
+    )
+    configure_cache(config)
+    print(f"VFBquery caching enabled: TTL={cache_ttl_hours}h ({cache_ttl_hours//24} days), Memory={memory_cache_size_mb}MB")
+
+def disable_vfbquery_caching():
+    """Disable VFBquery caching."""
+    config = CacheConfig(enabled=False)
+    configure_cache(config)
+    print("VFBquery caching disabled")
+
+def clear_vfbquery_cache():
+    """Clear all VFBquery caches."""
+    get_cache().clear()
+    print("VFBquery cache cleared")
+
+def get_vfbquery_cache_stats() -> Dict[str, Any]:
+    """Get VFBquery cache statistics."""
+    return get_cache().get_stats()
+
+def set_cache_ttl(hours: int):
+    """
+    Update the cache TTL (time-to-live) for new cache entries.
+    
+    Args:
+        hours: New TTL in hours (e.g., 24 for 1 day, 720 for 1 month, 2160 for 3 months)
+        
+    Examples:
+        set_cache_ttl(24)    # 1 day
+        set_cache_ttl(168)   # 1 week  
+        set_cache_ttl(720)   # 1 month
+        set_cache_ttl(2160)  # 3 months (default)
+    """
+    cache = get_cache()
+    cache.config.cache_ttl_hours = hours
+    days = hours / 24
+    print(f"Cache TTL updated to {hours} hours ({days:.1f} days)")
+
+def set_cache_memory_limit(size_mb: int):
+    """
+    Update the memory cache size limit.
+    
+    Args:
+        size_mb: Maximum memory cache size in MB (e.g., 512, 1024, 2048)
+        
+    Examples:
+        set_cache_memory_limit(512)   # 512MB
+        set_cache_memory_limit(1024)  # 1GB
+        set_cache_memory_limit(2048)  # 2GB (default)
+    """
+    cache = get_cache()
+    old_limit = cache.config.memory_cache_size_mb
+    cache.config.memory_cache_size_mb = size_mb
+    
+    # If reducing size, trigger eviction if needed
+    if size_mb < old_limit:
+        with cache._lock:
+            max_size_bytes = size_mb * 1024 * 1024
+            while cache._cache_stats.get('memory_size_bytes', 0) > max_size_bytes:
+                if not cache._memory_cache:
+                    break
+                # Remove oldest item
+                oldest_key = next(iter(cache._memory_cache))
+                old_entry = cache._memory_cache.pop(oldest_key)
+                cache._cache_stats['memory_size_bytes'] -= old_entry.get('size_bytes', 0)
+    
+    print(f"Memory cache limit updated from {old_limit}MB to {size_mb}MB")
+
+def set_cache_max_items(max_items: int):
+    """
+    Update the maximum number of items in memory cache.
+    
+    Args:
+        max_items: Maximum number of cached items (e.g., 1000, 5000, 10000)
+        
+    Examples:
+        set_cache_max_items(1000)   # 1K items
+        set_cache_max_items(5000)   # 5K items  
+        set_cache_max_items(10000)  # 10K items (default)
+    """
+    cache = get_cache()
+    old_limit = cache.config.max_items
+    cache.config.max_items = max_items
+    
+    # If reducing count, trigger eviction if needed
+    if max_items < old_limit:
+        with cache._lock:
+            while len(cache._memory_cache) > max_items:
+                if not cache._memory_cache:
+                    break
+                # Remove oldest item
+                oldest_key = next(iter(cache._memory_cache))
+                old_entry = cache._memory_cache.pop(oldest_key)
+                cache._cache_stats['memory_size_bytes'] -= old_entry.get('size_bytes', 0)
+    
+    print(f"Max cache items updated from {old_limit} to {max_items}")
+
+def enable_disk_cache(cache_dir: Optional[str] = None):
+    """
+    Enable persistent disk caching.
+    
+    Args:
+        cache_dir: Optional custom cache directory path
+        
+    Examples:
+        enable_disk_cache()                          # Use default location
+        enable_disk_cache('/tmp/my_vfbquery_cache')  # Custom location
+    """
+    cache = get_cache()
+    cache.config.disk_cache_enabled = True
+    
+    if cache_dir:
+        cache.config.disk_cache_dir = cache_dir
+        cache.cache_dir = Path(cache_dir)
+        cache.cache_dir.mkdir(exist_ok=True)
+    
+    print(f"Disk caching enabled: {getattr(cache, 'cache_dir', 'default location')}")
+
+def disable_disk_cache():
+    """Disable persistent disk caching (memory cache only)."""
+    cache = get_cache()
+    cache.config.disk_cache_enabled = False
+    print("Disk caching disabled (memory cache only)")
+
+def get_cache_config() -> Dict[str, Any]:
+    """
+    Get current cache configuration settings.
+    
+    Returns:
+        Dictionary with current cache configuration
+    """
+    cache = get_cache()
+    config = cache.config
+    
+    return {
+        'enabled': config.enabled,
+        'cache_ttl_hours': config.cache_ttl_hours,
+        'cache_ttl_days': config.cache_ttl_hours / 24,
+        'memory_cache_size_mb': config.memory_cache_size_mb,
+        'max_items': config.max_items,
+        'disk_cache_enabled': config.disk_cache_enabled,
+        'disk_cache_dir': config.disk_cache_dir,
+        'solr_cache_enabled': config.solr_cache_enabled,
+        'term_info_cache_enabled': config.term_info_cache_enabled,
+        'query_result_cache_enabled': config.query_result_cache_enabled
+    }

vfbquery/cached_functions.py

@@ -0,0 +1,227 @@
+"""
+Cached VFBquery Functions
+
+Enhanced versions of VFBquery functions with integrated caching
+inspired by VFB_connect optimizations.
+"""
+
+from typing import Dict, Any, Optional
+from .cache_enhancements import cache_result, get_cache
+
+
+def is_valid_term_info_result(result):
+    """Check if a term_info result has the essential fields and valid query structure"""
+    if not result or not isinstance(result, dict):
+        return False
+    
+    # Check for essential fields
+    if not (result.get('Id') and result.get('Name')):
+        return False
+    
+    # Additional validation for query results
+    if 'Queries' in result:
+        for query in result['Queries']:
+            # Check if query has invalid count (-1) which indicates failed execution
+            # Note: count=0 is valid if preview_results structure is correct
+            count = query.get('count', 0)
+            
+            # Check if preview_results has the correct structure
+            preview_results = query.get('preview_results')
+            if not isinstance(preview_results, dict):
+                print(f"DEBUG: Invalid preview_results type {type(preview_results)} detected")
+                return False
+                
+            headers = preview_results.get('headers', [])
+            if not headers:
+                print(f"DEBUG: Empty headers detected in preview_results")
+                return False
+            
+            # Only reject if count is -1 (failed execution) or if count is 0 but preview_results is missing/empty
+            if count < 0:
+                print(f"DEBUG: Invalid query count {count} detected")
+                return False
+    
+    return True
+from .vfb_queries import (
+    get_term_info as _original_get_term_info,
+    get_instances as _original_get_instances,
+    vfb_solr,
+    term_info_parse_object as _original_term_info_parse_object,
+    fill_query_results as _original_fill_query_results
+)
+
+@cache_result("solr_search", "solr_cache_enabled")
+def cached_solr_search(query: str):
+    """Cached version of SOLR search."""
+    return vfb_solr.search(query)
+
+@cache_result("term_info_parse", "term_info_cache_enabled")
+def cached_term_info_parse_object(results, short_form: str):
+    """Cached version of term_info_parse_object."""
+    return _original_term_info_parse_object(results, short_form)
+
+@cache_result("query_results", "query_result_cache_enabled")
+def cached_fill_query_results(term_info: Dict[str, Any]):
+    """Cached version of fill_query_results."""
+    return _original_fill_query_results(term_info)
+
+@cache_result("get_instances", "query_result_cache_enabled")
+def cached_get_instances(short_form: str, return_dataframe=True, limit: int = -1):
+    """Cached version of get_instances."""
+    return _original_get_instances(short_form, return_dataframe, limit)
+
+def get_term_info_cached(short_form: str, preview: bool = False):
+    """
+    Enhanced get_term_info with multi-layer caching.
+    
+    This version uses caching at multiple levels:
+    1. Final result caching (entire term_info response)
+    2. SOLR query result caching 
+    3. Term info parsing caching
+    4. Query result caching
+    
+    Args:
+        short_form: Term short form (e.g., 'FBbt_00003748')
+        preview: Whether to include preview results
+        
+    Returns:
+        Term info dictionary or None if not found
+    """
+    cache = get_cache()
+    
+    # Check for complete result in cache first
+    cache_key = cache._generate_cache_key("term_info_complete", short_form, preview)
+    cached_result = cache.get(cache_key)
+    print(f"DEBUG: Cache lookup for {short_form}: {'HIT' if cached_result is not None else 'MISS'}")
+    if cached_result is not None:
+        # Validate that cached result has essential fields
+        if not is_valid_term_info_result(cached_result):
+            print(f"DEBUG: Cached result incomplete for {short_form}, falling back to original function")
+            print(f"DEBUG: cached_result keys: {list(cached_result.keys()) if cached_result else 'None'}")
+            print(f"DEBUG: cached_result Id: {cached_result.get('Id', 'MISSING') if cached_result else 'None'}")
+            print(f"DEBUG: cached_result Name: {cached_result.get('Name', 'MISSING') if cached_result else 'None'}")
+            
+            # Fall back to original function and cache the complete result
+            fallback_result = _original_get_term_info(short_form, preview)
+            if is_valid_term_info_result(fallback_result):
+                print(f"DEBUG: Fallback successful, caching complete result for {short_form}")
+                cache.set(cache_key, fallback_result)
+            return fallback_result
+        else:
+            print(f"DEBUG: Using valid cached result for {short_form}")
+            return cached_result
+    
+    parsed_object = None
+    try:
+        # Use cached SOLR search
+        results = cached_solr_search('id:' + short_form)
+        
+        # Use cached term info parsing
+        parsed_object = cached_term_info_parse_object(results, short_form)
+        
+        if parsed_object:
+            # Use cached query result filling (skip if queries would fail)
+            if parsed_object.get('Queries') and len(parsed_object['Queries']) > 0:
+                try:
+                    term_info = cached_fill_query_results(parsed_object)
+                    if term_info:
+                        # Validate result before caching
+                        if term_info.get('Id') and term_info.get('Name'):
+                            # Cache the complete result
+                            cache.set(cache_key, term_info)
+                            return term_info
+                        else:
+                            print(f"Query result for {short_form} is incomplete, falling back to original function...")
+                            return _original_get_term_info(short_form, preview)
+                    else:
+                        print("Failed to fill query preview results!")
+                        # Validate result before caching
+                        if parsed_object.get('Id') and parsed_object.get('Name'):
+                            # Cache the complete result
+                            cache.set(cache_key, parsed_object)
+                            return parsed_object
+                        else:
+                            print(f"Parsed object for {short_form} is incomplete, falling back to original function...")
+                            return _original_get_term_info(short_form, preview)
+                except Exception as e:
+                    print(f"Error filling query results (continuing without query data): {e}")
+                    # Validate result before caching
+                    if is_valid_term_info_result(parsed_object):
+                        cache.set(cache_key, parsed_object)
+                        return parsed_object
+                    else:
+                        print(f"DEBUG: Exception case - parsed object incomplete for {short_form}, falling back to original function")
+                        fallback_result = _original_get_term_info(short_form, preview)
+                        if is_valid_term_info_result(fallback_result):
+                            cache.set(cache_key, fallback_result)
+                        return fallback_result
+            else:
+                # No queries to fill, validate result before caching
+                if parsed_object.get('Id') and parsed_object.get('Name'):
+                    # Cache and return parsed object directly
+                    cache.set(cache_key, parsed_object)
+                    return parsed_object
+                else:
+                    print(f"DEBUG: No queries case - parsed object incomplete for {short_form}, falling back to original function...")
+                    fallback_result = _original_get_term_info(short_form, preview)
+                    if is_valid_term_info_result(fallback_result):
+                        cache.set(cache_key, fallback_result)
+                    return fallback_result
+        else:
+            print(f"No valid term info found for ID '{short_form}'")
+            return None
+            
+    except Exception as e:
+        print(f"Error in cached get_term_info: {type(e).__name__}: {e}")
+        # Fall back to original function if caching fails
+        return _original_get_term_info(short_form, preview)
+
+def get_instances_cached(short_form: str, return_dataframe=True, limit: int = -1):
+    """
+    Enhanced get_instances with caching.
+    
+    This cached version can provide dramatic speedup for repeated queries,
+    especially useful for:
+    - UI applications with repeated browsing
+    - Data analysis workflows
+    - Testing and development
+    
+    Args:
+        short_form: Class short form
+        return_dataframe: Whether to return DataFrame or formatted dict
+        limit: Maximum number of results (-1 for all)
+        
+    Returns:
+        Instances data (DataFrame or formatted dict based on return_dataframe)
+    """
+    return cached_get_instances(short_form, return_dataframe, limit)
+
+# Convenience function to replace original functions
+def patch_vfbquery_with_caching():
+    """
+    Replace original VFBquery functions with cached versions.
+    
+    This allows existing code to benefit from caching without changes.
+    """
+    import vfbquery.vfb_queries as vfb_queries
+    
+    # Store original functions for fallback
+    setattr(vfb_queries, '_original_get_term_info', vfb_queries.get_term_info)
+    setattr(vfb_queries, '_original_get_instances', vfb_queries.get_instances)
+    
+    # Replace with cached versions
+    vfb_queries.get_term_info = get_term_info_cached
+    vfb_queries.get_instances = get_instances_cached
+    
+    print("VFBquery functions patched with caching support")
+
+def unpatch_vfbquery_caching():
+    """Restore original VFBquery functions."""
+    import vfbquery.vfb_queries as vfb_queries
+    
+    if hasattr(vfb_queries, '_original_get_term_info'):
+        vfb_queries.get_term_info = getattr(vfb_queries, '_original_get_term_info')
+    if hasattr(vfb_queries, '_original_get_instances'):
+        vfb_queries.get_instances = getattr(vfb_queries, '_original_get_instances')
+    
+    print("VFBquery functions restored to original (non-cached) versions")