mem-llm 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

mem_llm/llm_client_factory.py

@@ -0,0 +1,277 @@
+"""
+LLM Client Factory
+==================
+
+Factory pattern for creating LLM clients.
+Supports multiple backends with automatic detection.
+
+Supported Backends:
+- Ollama: Local Ollama service
+- LM Studio: Local LM Studio server
+- Gemini: Google Gemini API (cloud)
+
+Usage:
+    # Create specific backend
+    client = LLMClientFactory.create('ollama', model='llama3')
+    
+    # Auto-detect available backend
+    client = LLMClientFactory.auto_detect()
+    
+    # Get all available backends
+    backends = LLMClientFactory.get_available_backends()
+
+Author: C. Emre Karataş
+Version: 1.3.0
+"""
+
+from typing import Optional, Dict, List, Any
+import logging
+
+from .clients.ollama_client import OllamaClient
+from .clients.lmstudio_client import LMStudioClient
+from .clients.gemini_client import GeminiClient
+from .base_llm_client import BaseLLMClient
+
+
+class LLMClientFactory:
+    """
+    Factory for creating LLM clients
+    
+    Provides unified interface for creating different LLM backends.
+    Supports auto-detection of available local services.
+    """
+    
+    # Registry of supported backends
+    BACKENDS = {
+        'ollama': {
+            'class': OllamaClient,
+            'description': 'Local Ollama service',
+            'type': 'local',
+            'default_url': 'http://localhost:11434',
+            'default_model': 'granite4:tiny-h'
+        },
+        'lmstudio': {
+            'class': LMStudioClient,
+            'description': 'LM Studio local server (OpenAI-compatible)',
+            'type': 'local',
+            'default_url': 'http://localhost:1234',
+            'default_model': 'local-model'
+        },
+        'gemini': {
+            'class': GeminiClient,
+            'description': 'Google Gemini API (cloud)',
+            'type': 'cloud',
+            'default_model': 'gemini-2.5-flash',
+            'requires_api_key': True
+        }
+    }
+    
+    @staticmethod
+    def create(backend: str, model: Optional[str] = None, **kwargs) -> BaseLLMClient:
+        """
+        Create LLM client for specified backend
+        
+        Args:
+            backend: Backend name ('ollama', 'lmstudio', 'gemini')
+            model: Model name (uses default if None)
+            **kwargs: Backend-specific configuration
+                     - base_url: API endpoint (for local backends)
+                     - api_key: API key (for cloud backends)
+                     - temperature: Default temperature
+                     - max_tokens: Default max tokens
+            
+        Returns:
+            Configured LLM client
+            
+        Raises:
+            ValueError: If backend is not supported
+            
+        Examples:
+            # Ollama
+            client = LLMClientFactory.create('ollama', model='llama3')
+            
+            # LM Studio
+            client = LLMClientFactory.create(
+                'lmstudio',
+                model='llama-3-8b',
+                base_url='http://localhost:1234'
+            )
+            
+            # Gemini
+            client = LLMClientFactory.create(
+                'gemini',
+                model='gemini-2.5-flash',
+                api_key='your-api-key'
+            )
+        """
+        backend = backend.lower()
+        
+        if backend not in LLMClientFactory.BACKENDS:
+            available = ', '.join(LLMClientFactory.BACKENDS.keys())
+            raise ValueError(
+                f"Unsupported backend: '{backend}'. "
+                f"Available backends: {available}"
+            )
+        
+        backend_info = LLMClientFactory.BACKENDS[backend]
+        client_class = backend_info['class']
+        
+        # Use default model if not specified
+        if not model:
+            model = backend_info.get('default_model')
+        
+        # Add default base_url for local backends if not provided
+        if backend_info['type'] == 'local' and 'base_url' not in kwargs:
+            kwargs['base_url'] = backend_info.get('default_url')
+        
+        # Create and return client
+        try:
+            return client_class(model=model, **kwargs)
+        except Exception as e:
+            raise ValueError(f"Failed to create {backend} client: {str(e)}") from e
+    
+    @staticmethod
+    def auto_detect(preferred_backends: Optional[List[str]] = None) -> Optional[BaseLLMClient]:
+        """
+        Auto-detect available LLM service
+        
+        Checks common local services and returns the first available one.
+        Useful for applications that should work with any available backend.
+        
+        Args:
+            preferred_backends: List of backends to check in order
+                              (if None, checks all in default order)
+        
+        Returns:
+            First available LLM client, or None if none available
+            
+        Example:
+            # Try to find any available backend
+            client = LLMClientFactory.auto_detect()
+            if client:
+                print(f"Using {client.get_info()['backend']}")
+            else:
+                print("No LLM service found")
+            
+            # Try specific backends in order
+            client = LLMClientFactory.auto_detect(['lmstudio', 'ollama'])
+        """
+        logger = logging.getLogger('LLMClientFactory')
+        
+        # Default check order: local services first
+        if preferred_backends is None:
+            preferred_backends = ['ollama', 'lmstudio']
+        
+        for backend_name in preferred_backends:
+            if backend_name not in LLMClientFactory.BACKENDS:
+                logger.warning(f"Unknown backend in auto-detect: {backend_name}")
+                continue
+            
+            backend_info = LLMClientFactory.BACKENDS[backend_name]
+            
+            # Skip cloud services in auto-detect (they require API keys)
+            if backend_info['type'] == 'cloud':
+                logger.debug(f"Skipping cloud backend in auto-detect: {backend_name}")
+                continue
+            
+            try:
+                # Try to create client with defaults
+                client = LLMClientFactory.create(backend_name)
+                
+                # Check if service is actually running
+                if client.check_connection():
+                    logger.info(f"✅ Detected {backend_name} at {backend_info.get('default_url')}")
+                    return client
+                else:
+                    logger.debug(f"Service not running: {backend_name}")
+                    
+            except Exception as e:
+                logger.debug(f"Failed to detect {backend_name}: {e}")
+                continue
+        
+        logger.warning("⚠️  No local LLM service detected")
+        return None
+    
+    @staticmethod
+    def get_available_backends() -> List[Dict[str, Any]]:
+        """
+        Get list of all supported backends with their info
+        
+        Returns:
+            List of backend information dictionaries
+            
+        Example:
+            backends = LLMClientFactory.get_available_backends()
+            for backend in backends:
+                print(f"{backend['name']}: {backend['description']}")
+        """
+        result = []
+        
+        for name, info in LLMClientFactory.BACKENDS.items():
+            backend_dict = {
+                'name': name,
+                'description': info['description'],
+                'type': info['type'],
+                'default_model': info.get('default_model'),
+                'requires_api_key': info.get('requires_api_key', False)
+            }
+            
+            if info['type'] == 'local':
+                backend_dict['default_url'] = info.get('default_url')
+            
+            result.append(backend_dict)
+        
+        return result
+    
+    @staticmethod
+    def check_backend_availability(backend: str, **kwargs) -> bool:
+        """
+        Check if a specific backend is available
+        
+        Args:
+            backend: Backend name
+            **kwargs: Configuration for creating the client
+            
+        Returns:
+            True if backend is available and responding
+            
+        Example:
+            # Check if Ollama is running
+            if LLMClientFactory.check_backend_availability('ollama'):
+                print("Ollama is available")
+            
+            # Check custom LM Studio URL
+            if LLMClientFactory.check_backend_availability(
+                'lmstudio',
+                base_url='http://localhost:5000'
+            ):
+                print("LM Studio is available")
+        """
+        try:
+            client = LLMClientFactory.create(backend, **kwargs)
+            return client.check_connection()
+        except Exception:
+            return False
+    
+    @staticmethod
+    def get_backend_info(backend: str) -> Dict[str, Any]:
+        """
+        Get information about a specific backend
+        
+        Args:
+            backend: Backend name
+            
+        Returns:
+            Backend information dictionary
+            
+        Raises:
+            ValueError: If backend not found
+        """
+        if backend not in LLMClientFactory.BACKENDS:
+            raise ValueError(f"Unknown backend: {backend}")
+        
+        info = LLMClientFactory.BACKENDS[backend].copy()
+        # Remove class reference for JSON serialization
+        info.pop('class', None)
+        return info
+

mem_llm/mem_agent.py

@@ -37,7 +37,9 @@ import os
 
 # Core dependencies
 from .memory_manager import MemoryManager
-from .llm_client import OllamaClient
+from .llm_client import OllamaClient  # Backward compatibility
+from .llm_client_factory import LLMClientFactory
+from .base_llm_client import BaseLLMClient
 
 # Advanced features (optional)
 try:
@@ -61,23 +63,48 @@ class MemAgent:
 
     def __init__(self,
                  model: str = "granite4:tiny-h",
+                 backend: str = "ollama",
                  config_file: Optional[str] = None,
                  use_sql: bool = True,
                  memory_dir: Optional[str] = None,
+                 db_path: Optional[str] = None,
                  load_knowledge_base: bool = True,
                  ollama_url: str = "http://localhost:11434",
+                 base_url: Optional[str] = None,
+                 api_key: Optional[str] = None,
+                 auto_detect_backend: bool = False,
                  check_connection: bool = False,
-                 enable_security: bool = False):
+                 enable_security: bool = False,
+                 **llm_kwargs):
         """
         Args:
             model: LLM model to use
+            backend: LLM backend ('ollama', 'lmstudio', 'gemini') - NEW in v1.3.0
             config_file: Configuration file (optional)
             use_sql: Use SQL database (True) or JSON (False)
-            memory_dir: Memory directory
+            memory_dir: Memory directory (for JSON mode or if db_path not specified)
+            db_path: SQLite database path (for SQL mode, e.g., ":memory:" or "path/to/db.db")
             load_knowledge_base: Automatically load knowledge base
-            ollama_url: Ollama API URL
-            check_connection: Verify Ollama connection on startup (default: False)
+            ollama_url: Ollama API URL (backward compatibility, use base_url instead)
+            base_url: Backend API URL (for local backends) - NEW in v1.3.0
+            api_key: API key (for cloud backends like Gemini) - NEW in v1.3.0
+            auto_detect_backend: Auto-detect available LLM backend - NEW in v1.3.0
+            check_connection: Verify LLM connection on startup (default: False)
             enable_security: Enable prompt injection protection (v1.1.0+, default: False for backward compatibility)
+            **llm_kwargs: Additional backend-specific parameters
+        
+        Examples:
+            # Default Ollama
+            agent = MemAgent()
+            
+            # LM Studio
+            agent = MemAgent(backend='lmstudio', model='llama-3-8b')
+            
+            # Gemini
+            agent = MemAgent(backend='gemini', model='gemini-1.5-flash', api_key='your-key')
+            
+            # Auto-detect
+            agent = MemAgent(auto_detect_backend=True)
         """
         
         # Setup logging first
@@ -120,12 +147,29 @@ class MemAgent:
         self.has_knowledge_base: bool = False  # Track KB status
         self.has_tools: bool = False  # Track tools status
 
-        # Memory system selection
+        # Memory system
         if use_sql and ADVANCED_AVAILABLE:
             # SQL memory (advanced)
-            db_path = memory_dir or self.config.get("memory.db_path", "memories.db") if self.config else "memories.db"
-            self.memory = SQLMemoryManager(db_path)
-            self.logger.info(f"SQL memory system active: {db_path}")
+            # Determine database path
+            if db_path:
+                # Use provided db_path (can be ":memory:" for in-memory DB)
+                final_db_path = db_path
+            elif memory_dir:
+                final_db_path = memory_dir
+            elif self.config:
+                final_db_path = self.config.get("memory.db_path", "memories/memories.db")
+            else:
+                final_db_path = "memories/memories.db"
+            
+            # Ensure memories directory exists (skip for :memory:)
+            import os
+            if final_db_path != ":memory:":
+                db_dir = os.path.dirname(final_db_path)
+                if db_dir and not os.path.exists(db_dir):
+                    os.makedirs(db_dir, exist_ok=True)
+            
+            self.memory = SQLMemoryManager(final_db_path)
+            self.logger.info(f"SQL memory system active: {final_db_path}")
         else:
             # JSON memory (simple)
             json_dir = memory_dir or self.config.get("memory.json_dir", "memories") if self.config else "memories"
@@ -139,48 +183,109 @@ class MemAgent:
         # LLM client
         self.model = model  # Store model name
         self.use_sql = use_sql  # Store SQL usage flag
-        self.llm = OllamaClient(model, ollama_url)
+        
+        # Initialize LLM client (v1.3.0: Multi-backend support)
+        # Prepare backend configuration
+        llm_config = llm_kwargs.copy()
+        
+        # Handle backward compatibility: ollama_url -> base_url
+        if base_url is None and backend == "ollama":
+            base_url = ollama_url
+        
+        # Add base_url for local backends
+        if base_url and backend in ['ollama', 'lmstudio']:
+            llm_config['base_url'] = base_url
+        
+        # Add api_key for cloud backends
+        if api_key and backend in ['gemini']:
+            llm_config['api_key'] = api_key
+        
+        # Auto-detect backend if requested
+        if auto_detect_backend:
+            self.logger.info("🔍 Auto-detecting available LLM backend...")
+            self.llm = LLMClientFactory.auto_detect()
+            if self.llm:
+                detected_backend = self.llm.__class__.__name__
+                self.logger.info(f"✅ Detected and using: {detected_backend}")
+            else:
+                self.logger.error("❌ No LLM backend available.")
+                raise RuntimeError(
+                    "No LLM backend detected. Please start a local LLM service (Ollama/LM Studio) "
+                    "or provide Gemini API key."
+                )
+        else:
+            # Create client using factory
+            try:
+                self.llm = LLMClientFactory.create(
+                    backend=backend,
+                    model=model,
+                    **llm_config
+                )
+                self.logger.info(f"✅ Initialized {backend} backend with model: {model}")
+            except Exception as e:
+                self.logger.error(f"❌ Failed to initialize {backend} backend: {e}")
+                raise
         
         # Optional connection check on startup
         if check_connection:
-            self.logger.info("Checking Ollama connection...")
+            backend_name = backend if not auto_detect_backend else "LLM service"
+            self.logger.info(f"Checking {backend_name} connection...")
             if not self.llm.check_connection():
-                error_msg = (
-                    "❌ ERROR: Cannot connect to Ollama service!\n"
-                    "   \n"
-                    "   Solutions:\n"
-                    "   1. Start Ollama: ollama serve\n"
-                    "   2. Check if Ollama is running: http://localhost:11434\n"
-                    "   3. Verify ollama_url parameter is correct\n"
-                    "   \n"
-                    "   To skip this check, use: MemAgent(check_connection=False)"
-                )
+                error_msg = f"❌ ERROR: Cannot connect to {backend_name}!\n"
+                
+                if backend == "ollama":
+                    error_msg += (
+                        "   \n"
+                        "   Solutions:\n"
+                        "   1. Start Ollama: ollama serve\n"
+                        "   2. Check if Ollama is running: http://localhost:11434\n"
+                        "   3. Verify base_url parameter is correct\n"
+                    )
+                elif backend == "lmstudio":
+                    error_msg += (
+                        "   \n"
+                        "   Solutions:\n"
+                        "   1. Start LM Studio\n"
+                        "   2. Load a model in LM Studio\n"
+                        "   3. Start local server (default: http://localhost:1234)\n"
+                        "   4. Verify base_url parameter is correct\n"
+                    )
+                elif backend == "gemini":
+                    error_msg += (
+                        "   \n"
+                        "   Solutions:\n"
+                        "   1. Check your internet connection\n"
+                        "   2. Verify Gemini API key is correct\n"
+                        "   3. Check API quota/billing status\n"
+                        "   Get key: https://makersuite.google.com/app/apikey\n"
+                    )
+                
+                error_msg += "   \n   To skip this check, use: MemAgent(check_connection=False)"
                 self.logger.error(error_msg)
-                raise ConnectionError("Ollama service not available")
+                raise ConnectionError(f"{backend_name} not available")
             
-            # Check if model exists
-            available_models = self.llm.list_models()
-            if model not in available_models:
-                error_msg = (
-                    f"❌ ERROR: Model '{model}' not found!\n"
-                    f"   \n"
-                    f"   Solutions:\n"
-                    f"   1. Download model: ollama pull {model}\n"
-                    f"   2. Use an available model: {', '.join(available_models[:3])}\n"
-                    f"   \n"
-                    f"   Available models: {len(available_models)} found\n"
-                    f"   To skip this check, use: MemAgent(check_connection=False)"
-                )
-                self.logger.error(error_msg)
-                raise ValueError(f"Model '{model}' not available")
+            # Check if model exists (for backends that support listing)
+            try:
+                available_models = self.llm.list_models()
+                if available_models and model not in available_models:
+                    error_msg = (
+                        f"❌ ERROR: Model '{model}' not found in {backend}!\n"
+                        f"   \n"
+                        f"   Available models: {', '.join(available_models[:5])}\n"
+                        f"   Total: {len(available_models)} models available\n"
+                        f"   \n"
+                        f"   To skip this check, use: MemAgent(check_connection=False)"
+                    )
+                    self.logger.error(error_msg)
+                    raise ValueError(f"Model '{model}' not available")
+            except:
+                # Some backends may not support list_models, skip check
+                pass
             
-            self.logger.info(f"✅ Ollama connection verified, model '{model}' ready")
+            self.logger.info(f"✅ {backend_name} connection verified, model '{model}' ready")
         
-        self.logger.info(f"LLM client ready: {model}")
+        self.logger.info(f"LLM client ready: {model} on {backend}")
 
-        # Initialize state variables FIRST
-        self.current_user: Optional[str] = None
-        self.current_system_prompt: Optional[str] = None
 
         # Advanced features (if available)
         if ADVANCED_AVAILABLE:
@@ -203,10 +308,13 @@ class MemAgent:
         if ADVANCED_AVAILABLE and hasattr(self, 'config') and self.config:
             log_config = self.config.get("logging", {})
 
+        # Default to WARNING level to keep console clean (users can override in config)
+        default_level = "WARNING"
+        
         if log_config.get("enabled", True):
             # Only console logging (no file) - keep workspace clean
             logging.basicConfig(
-                level=getattr(logging, log_config.get("level", "INFO")),
+                level=getattr(logging, log_config.get("level", default_level)),
                 format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                 handlers=[
                     logging.StreamHandler()  # Console only
@@ -214,6 +322,9 @@ class MemAgent:
             )
 
         self.logger = logging.getLogger("MemAgent")
+        
+        # Set default level for mem_llm loggers
+        logging.getLogger("mem_llm").setLevel(getattr(logging, log_config.get("level", default_level)))
 
     def _setup_advanced_features(self, load_knowledge_base: bool) -> None:
         """Setup advanced features"""

mem_llm/memory_db.py

@@ -14,12 +14,18 @@ from pathlib import Path
 class SQLMemoryManager:
     """SQLite-based memory management system with thread-safety"""
     
-    def __init__(self, db_path: str = "memories.db"):
+    def __init__(self, db_path: str = "memories/memories.db"):
         """
         Args:
             db_path: SQLite database file path
         """
         self.db_path = Path(db_path)
+        
+        # Ensure directory exists
+        db_dir = self.db_path.parent
+        if not db_dir.exists():
+            db_dir.mkdir(parents=True, exist_ok=True)
+        
         self.conn = None
         self._lock = threading.RLock()  # Reentrant lock for thread safety
         self._init_database()

mem_llm/thread_safe_db.py

@@ -124,7 +124,7 @@ class ConnectionPool:
 class ThreadSafeSQLMemory:
     """Thread-safe wrapper for SQL memory operations"""
     
-    def __init__(self, db_path: str = "memories.db", pool_size: int = 5):
+    def __init__(self, db_path: str = "memories/memories.db", pool_size: int = 5):
         """
         Initialize thread-safe SQL memory
         
@@ -133,6 +133,12 @@ class ThreadSafeSQLMemory:
             pool_size: Connection pool size
         """
         self.db_path = Path(db_path)
+        
+        # Ensure directory exists
+        db_dir = self.db_path.parent
+        if not db_dir.exists():
+            db_dir.mkdir(parents=True, exist_ok=True)
+        
         self.pool = ConnectionPool(str(db_path), pool_size)
         self.logger = logging.getLogger(__name__)
         self._init_database()