mem-llm 1.0.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

mem_llm/base_llm_client.py

@@ -0,0 +1,201 @@
+"""
+Base LLM Client Interface
+==========================
+
+Abstract base class for all LLM client implementations.
+Ensures consistent interface across different backends (Ollama, LM Studio)
+
+Author: C. Emre Karataş
+Version: 1.3.0
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Optional, Any, Iterator, Union
+import logging
+
+
+class BaseLLMClient(ABC):
+    """
+    Abstract base class for LLM clients
+    
+    All LLM backends must implement these methods to ensure
+    compatibility with MemAgent and other components.
+    """
+    
+    def __init__(self, model: str = None, **kwargs):
+        """
+        Initialize LLM client
+        
+        Args:
+            model: Model name/identifier
+            **kwargs: Backend-specific configuration
+        """
+        self.model = model
+        self.logger = logging.getLogger(self.__class__.__name__)
+    
+    @abstractmethod
+    def chat(self, messages: List[Dict[str, str]], 
+             temperature: float = 0.7, 
+             max_tokens: int = 2000,
+             **kwargs) -> str:
+        """
+        Send chat request and return response
+        
+        Args:
+            messages: List of messages in format:
+                     [{"role": "system/user/assistant", "content": "..."}]
+            temperature: Sampling temperature (0.0-1.0)
+            max_tokens: Maximum tokens in response
+            **kwargs: Additional backend-specific parameters
+            
+        Returns:
+            Model response text
+            
+        Raises:
+            ConnectionError: If cannot connect to service
+            ValueError: If invalid parameters
+        """
+        pass
+    
+    @abstractmethod
+    def check_connection(self) -> bool:
+        """
+        Check if LLM service is available and responding
+        
+        Returns:
+            True if service is available, False otherwise
+        """
+        pass
+    
+    def chat_stream(self, messages: List[Dict[str, str]], 
+                    temperature: float = 0.7, 
+                    max_tokens: int = 2000,
+                    **kwargs) -> Iterator[str]:
+        """
+        Send chat request and stream response chunks (optional, not all backends support)
+        
+        Args:
+            messages: List of messages in format:
+                     [{"role": "system/user/assistant", "content": "..."}]
+            temperature: Sampling temperature (0.0-1.0)
+            max_tokens: Maximum tokens in response
+            **kwargs: Additional backend-specific parameters
+            
+        Yields:
+            Response text chunks as they arrive
+            
+        Raises:
+            NotImplementedError: If backend doesn't support streaming
+            ConnectionError: If cannot connect to service
+            ValueError: If invalid parameters
+        """
+        # Default implementation: fall back to non-streaming
+        response = self.chat(messages, temperature, max_tokens, **kwargs)
+        yield response
+    
+    def generate(self, prompt: str, 
+                 system_prompt: Optional[str] = None,
+                 temperature: float = 0.7, 
+                 max_tokens: int = 500,
+                 **kwargs) -> str:
+        """
+        Generate text from a simple prompt (convenience method)
+        
+        Args:
+            prompt: User prompt
+            system_prompt: Optional system prompt
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens
+            **kwargs: Additional parameters
+            
+        Returns:
+            Generated text
+        """
+        # Convert to chat format
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+        
+        return self.chat(messages, temperature, max_tokens, **kwargs)
+    
+    def list_models(self) -> List[str]:
+        """
+        List available models (optional, not all backends support this)
+        
+        Returns:
+            List of model names
+        """
+        return [self.model] if self.model else []
+    
+    def _format_messages_to_text(self, messages: List[Dict]) -> str:
+        """
+        Helper: Convert message list to text format
+        
+        Useful for backends that don't support chat format natively.
+        
+        Args:
+            messages: Message list
+            
+        Returns:
+            Formatted text prompt
+        """
+        result = []
+        for msg in messages:
+            role = msg.get('role', 'user').upper()
+            content = msg.get('content', '').strip()
+            if content:
+                result.append(f"{role}: {content}")
+        return "\n\n".join(result)
+    
+    def _validate_messages(self, messages: List[Dict]) -> bool:
+        """
+        Validate message format
+        
+        Args:
+            messages: Messages to validate
+            
+        Returns:
+            True if valid
+            
+        Raises:
+            ValueError: If invalid format
+        """
+        if not isinstance(messages, list):
+            raise ValueError("Messages must be a list")
+        
+        if not messages:
+            raise ValueError("Messages list cannot be empty")
+        
+        for i, msg in enumerate(messages):
+            if not isinstance(msg, dict):
+                raise ValueError(f"Message {i} must be a dictionary")
+            
+            if 'role' not in msg:
+                raise ValueError(f"Message {i} missing 'role' field")
+            
+            if 'content' not in msg:
+                raise ValueError(f"Message {i} missing 'content' field")
+            
+            if msg['role'] not in ['system', 'user', 'assistant']:
+                raise ValueError(f"Message {i} has invalid role: {msg['role']}")
+        
+        return True
+    
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Get client information
+        
+        Returns:
+            Dictionary with client metadata
+        """
+        return {
+            'backend': self.__class__.__name__,
+            'model': self.model,
+            'available': self.check_connection()
+        }
+    
+    def __repr__(self) -> str:
+        """String representation"""
+        return f"{self.__class__.__name__}(model='{self.model}')"
+

mem_llm/builtin_tools.py

@@ -0,0 +1,311 @@
+"""
+Built-in Tools
+==============
+
+Common tools that are available by default.
+
+Author: C. Emre Karataş
+Version: 2.0.0
+"""
+
+import math
+import os
+import json
+from datetime import datetime
+from typing import List, Dict, Any
+from .tool_system import tool
+
+
+# ============================================================================
+# Math & Calculation Tools
+# ============================================================================
+
+@tool(name="calculate", description="Evaluate mathematical expressions", category="math")
+def calculate(expression: str) -> float:
+    """
+    Evaluate a mathematical expression safely.
+    
+    Args:
+        expression: Mathematical expression (e.g., "2 + 2", "sqrt(16)", "pi * 2", "(25 * 4) + 10")
+    
+    Returns:
+        Result of the calculation
+    
+    Examples:
+        calculate("2 + 2") -> 4.0
+        calculate("sqrt(16)") -> 4.0
+        calculate("pi * 2") -> 6.283185307179586
+        calculate("(25 * 4) + 10") -> 110.0
+    """
+    # Safe eval with math functions
+    allowed_names = {
+        k: v for k, v in math.__dict__.items() if not k.startswith("__")
+    }
+    allowed_names["abs"] = abs
+    allowed_names["round"] = round
+    allowed_names["min"] = min
+    allowed_names["max"] = max
+    allowed_names["sum"] = sum
+    
+    try:
+        # Clean up expression - replace common text with symbols
+        clean_expr = expression.strip()
+        clean_expr = clean_expr.replace(" divided by ", " / ")
+        clean_expr = clean_expr.replace(" times ", " * ")
+        clean_expr = clean_expr.replace(" plus ", " + ")
+        clean_expr = clean_expr.replace(" minus ", " - ")
+        
+        result = eval(clean_expr, {"__builtins__": {}}, allowed_names)
+        return float(result)
+    except Exception as e:
+        raise ValueError(f"Invalid expression '{expression}': {str(e)}")
+
+
+# ============================================================================
+# Text Processing Tools
+# ============================================================================
+
+@tool(name="count_words", description="Count words in text", category="text")
+def count_words(text: str) -> int:
+    """
+    Count the number of words in a text.
+    
+    Args:
+        text: Text to count words in
+    
+    Returns:
+        Number of words
+    """
+    return len(text.split())
+
+
+@tool(name="reverse_text", description="Reverse a text string", category="text")
+def reverse_text(text: str) -> str:
+    """
+    Reverse the order of characters in text.
+    
+    Args:
+        text: Text to reverse
+    
+    Returns:
+        Reversed text
+    """
+    return text[::-1]
+
+
+@tool(name="to_uppercase", description="Convert text to uppercase", category="text")
+def to_uppercase(text: str) -> str:
+    """
+    Convert text to uppercase.
+    
+    Args:
+        text: Text to convert
+    
+    Returns:
+        Uppercase text
+    """
+    return text.upper()
+
+
+@tool(name="to_lowercase", description="Convert text to lowercase", category="text")
+def to_lowercase(text: str) -> str:
+    """
+    Convert text to lowercase.
+    
+    Args:
+        text: Text to convert
+    
+    Returns:
+        Lowercase text
+    """
+    return text.lower()
+
+
+# ============================================================================
+# File System Tools
+# ============================================================================
+
+@tool(name="read_file", description="Read contents of a text file", category="file")
+def read_file(filepath: str) -> str:
+    """
+    Read and return the contents of a text file.
+    
+    Args:
+        filepath: Path to the file to read
+    
+    Returns:
+        File contents as string
+    """
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            return f.read()
+    except Exception as e:
+        raise ValueError(f"Error reading file: {e}")
+
+
+@tool(name="write_file", description="Write text to a file", category="file")
+def write_file(filepath: str, content: str) -> str:
+    """
+    Write text content to a file.
+    
+    Args:
+        filepath: Path to the file to write
+        content: Content to write to the file
+    
+    Returns:
+        Success message
+    """
+    try:
+        with open(filepath, 'w', encoding='utf-8') as f:
+            f.write(content)
+        return f"Successfully wrote {len(content)} characters to {filepath}"
+    except Exception as e:
+        raise ValueError(f"Error writing file: {e}")
+
+
+@tool(name="list_files", description="List files in a directory", category="file")
+def list_files(directory: str) -> List[str]:
+    """
+    List all files in a directory.
+    
+    Args:
+        directory: Path to the directory
+    
+    Returns:
+        List of filenames
+    """
+    try:
+        return os.listdir(directory)
+    except Exception as e:
+        raise ValueError(f"Error listing directory: {e}")
+
+
+# ============================================================================
+# Utility Tools
+# ============================================================================
+
+@tool(name="get_current_time", description="Get current date and time", category="utility")
+def get_current_time() -> str:
+    """
+    Get the current date and time.
+    
+    Returns:
+        Current datetime as string
+    """
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+@tool(name="create_json", description="Create JSON from text", category="utility")
+def create_json(data: str) -> str:
+    """
+    Parse and format text as JSON.
+    
+    Args:
+        data: Text to convert to JSON
+    
+    Returns:
+        Formatted JSON string
+    """
+    try:
+        parsed = json.loads(data)
+        return json.dumps(parsed, indent=2)
+    except:
+        # Try to create simple key-value JSON
+        lines = data.strip().split('\n')
+        result = {}
+        for line in lines:
+            if ':' in line:
+                key, value = line.split(':', 1)
+                result[key.strip()] = value.strip()
+        return json.dumps(result, indent=2)
+
+
+# ============================================================================
+# Memory & Context Tools (NEW in v2.0.0)
+# ============================================================================
+
+@tool(name="search_memory", description="Search through conversation history", category="memory")
+def search_memory(keyword: str) -> str:
+    """
+    Search through conversation history for a keyword.
+    
+    Args:
+        keyword: The keyword to search for in conversation history
+    
+    Returns:
+        Search results or error message
+    
+    Examples:
+        search_memory("weather") -> "Found 2 conversations about weather..."
+    
+    Note:
+        This tool requires MemAgent context. Will return instructions if called standalone.
+    """
+    # This is a placeholder - actual implementation happens in MemAgent._execute_tool_calls
+    return f"MEMORY_SEARCH:{keyword}"
+
+
+@tool(name="get_user_info", description="Get current user profile information", category="memory")
+def get_user_info() -> str:
+    """
+    Get information about the current user.
+    
+    Returns:
+        User profile information
+    
+    Examples:
+        get_user_info() -> "Current user: john_doe (active since 2025-01-15)"
+    
+    Note:
+        This tool requires MemAgent context. Will return instructions if called standalone.
+    """
+    # This is a placeholder - actual implementation happens in MemAgent._execute_tool_calls
+    return "MEMORY_USER_INFO"
+
+
+@tool(name="list_conversations", description="List recent conversations", category="memory")
+def list_conversations(limit: int = 5) -> str:
+    """
+    List recent conversation sessions.
+    
+    Args:
+        limit: Maximum number of conversations to list (default: 5)
+    
+    Returns:
+        List of recent conversations
+    
+    Examples:
+        list_conversations(3) -> "Last 3 conversations: ..."
+    
+    Note:
+        This tool requires MemAgent context. Will return instructions if called standalone.
+    """
+    # This is a placeholder - actual implementation happens in MemAgent._execute_tool_calls
+    return f"MEMORY_LIST_CONVERSATIONS:{limit}"
+
+
+# ============================================================================
+# Export all tools
+# ============================================================================
+
+BUILTIN_TOOLS = [
+    # Math
+    calculate,
+    # Text
+    count_words,
+    reverse_text,
+    to_uppercase,
+    to_lowercase,
+    # File
+    read_file,
+    write_file,
+    list_files,
+    # Utility
+    get_current_time,
+    create_json,
+    # Memory (v2.0.0+)
+    search_memory,
+    get_user_info,
+    list_conversations,
+]
+

mem_llm/builtin_tools_async.py

@@ -0,0 +1,170 @@
+"""
+Built-in Async Tools (v2.1.0+)
+==============================
+
+Async versions of common tools for I/O-bound operations.
+
+Author: C. Emre Karataş
+Version: 2.1.0
+"""
+
+import asyncio
+import aiohttp
+from typing import Dict, Any
+from .tool_system import tool
+
+# ============================================================================
+# Async Web & API Tools
+# ============================================================================
+
+@tool(
+    name="fetch_url",
+    description="Fetch content from a URL asynchronously",
+    category="web",
+    pattern={"url": r'^https?://'},
+    max_length={"url": 2048}
+)
+async def fetch_url(url: str, timeout: int = 10) -> str:
+    """
+    Fetch content from a URL.
+    
+    Args:
+        url: The URL to fetch (must start with http:// or https://)
+        timeout: Request timeout in seconds (default: 10)
+    
+    Returns:
+        Response text or error message
+    """
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, timeout=timeout) as response:
+                if response.status == 200:
+                    text = await response.text()
+                    return text[:5000]  # Limit to 5000 chars
+                return f"HTTP {response.status}: {response.reason}"
+    except asyncio.TimeoutError:
+        return f"Request timed out after {timeout}s"
+    except Exception as e:
+        return f"Error fetching URL: {e}"
+
+
+@tool(
+    name="post_json",
+    description="Post JSON data to an API endpoint",
+    category="web",
+    pattern={"url": r'^https?://'}
+)
+async def post_json(url: str, data: Dict[str, Any], timeout: int = 10) -> str:
+    """
+    Post JSON data to an API endpoint.
+    
+    Args:
+        url: The API endpoint URL
+        data: JSON data to post
+        timeout: Request timeout in seconds
+    
+    Returns:
+        Response text or error message
+    """
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, json=data, timeout=timeout) as response:
+                text = await response.text()
+                return f"Status {response.status}: {text[:500]}"
+    except Exception as e:
+        return f"Error posting data: {e}"
+
+
+# ============================================================================
+# Async File Operations
+# ============================================================================
+
+@tool(
+    name="read_file_async",
+    description="Read a file asynchronously",
+    category="file",
+    max_length={"filepath": 260}
+)
+async def read_file_async(filepath: str) -> str:
+    """
+    Read a file asynchronously.
+    
+    Args:
+        filepath: Path to the file
+    
+    Returns:
+        File contents or error message
+    """
+    try:
+        loop = asyncio.get_event_loop()
+        with open(filepath, 'r', encoding='utf-8') as f:
+            content = await loop.run_in_executor(None, f.read)
+        return content
+    except FileNotFoundError:
+        return f"File not found: {filepath}"
+    except Exception as e:
+        return f"Error reading file: {e}"
+
+
+@tool(
+    name="write_file_async",
+    description="Write to a file asynchronously",
+    category="file"
+)
+async def write_file_async(filepath: str, content: str) -> str:
+    """
+    Write to a file asynchronously.
+    
+    Args:
+        filepath: Path to the file
+        content: Content to write
+    
+    Returns:
+        Success message or error
+    """
+    try:
+        loop = asyncio.get_event_loop()
+        with open(filepath, 'w', encoding='utf-8') as f:
+            await loop.run_in_executor(None, f.write, content)
+        return f"Successfully wrote {len(content)} chars to {filepath}"
+    except Exception as e:
+        return f"Error writing file: {e}"
+
+
+# ============================================================================
+# Async Utility Tools
+# ============================================================================
+
+@tool(
+    name="sleep",
+    description="Asynchronously wait for specified seconds",
+    category="utility",
+    min_value={"seconds": 0},
+    max_value={"seconds": 60}
+)
+async def async_sleep(seconds: float) -> str:
+    """
+    Wait asynchronously for specified seconds.
+    
+    Args:
+        seconds: Number of seconds to wait (0-60)
+    
+    Returns:
+        Completion message
+    """
+    await asyncio.sleep(seconds)
+    return f"Waited for {seconds} seconds"
+
+
+# ============================================================================
+# Export Async Tools
+# ============================================================================
+
+ASYNC_TOOLS = [
+    fetch_url,
+    post_json,
+    read_file_async,
+    write_file_async,
+    async_sleep,
+]
+