MemoryOS 2.0.3__py3-none-any.whl

memos/memos_tools/notification_utils.py

@@ -0,0 +1,142 @@
+"""
+Notification utilities for MemOS product.
+"""
+
+import asyncio
+import logging
+
+from collections.abc import Callable
+from typing import Any
+
+
+logger = logging.getLogger(__name__)
+
+
+def send_online_bot_notification(
+    online_bot: Callable | None,
+    header_name: str,
+    sub_title_name: str,
+    title_color: str,
+    other_data1: dict[str, Any],
+    other_data2: dict[str, Any],
+    emoji: dict[str, str],
+) -> None:
+    """
+    Send notification via online_bot if available.
+
+    Args:
+        online_bot: The online_bot function or None
+        header_name: Header name for the report
+        sub_title_name: Subtitle for the report
+        title_color: Title color
+        other_data1: First data dict
+        other_data2: Second data dict
+        emoji: Emoji configuration dict
+    """
+    if online_bot is None:
+        return
+
+    try:
+        online_bot(
+            header_name=header_name,
+            sub_title_name=sub_title_name,
+            title_color=title_color,
+            other_data1=other_data1,
+            other_data2=other_data2,
+            emoji=emoji,
+        )
+
+        logger.info(f"Online bot notification sent successfully: {header_name}")
+
+    except Exception as e:
+        logger.warning(f"Failed to send online bot notification: {e}")
+
+
+async def send_online_bot_notification_async(
+    online_bot: Callable | None,
+    header_name: str,
+    sub_title_name: str,
+    title_color: str,
+    other_data1: dict[str, Any],
+    other_data2: dict[str, Any],
+    emoji: dict[str, str],
+) -> None:
+    """
+    Send notification via online_bot asynchronously if available.
+
+    Args:
+        online_bot: The online_bot function or None
+        header_name: Header name for the report
+        sub_title_name: Subtitle for the report
+        title_color: Title color
+        other_data1: First data dict
+        other_data2: Second data dict
+        emoji: Emoji configuration dict
+    """
+    if online_bot is None:
+        return
+
+    try:
+        # Run the potentially blocking notification in a thread pool
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            None,
+            lambda: online_bot(
+                header_name=header_name,
+                sub_title_name=sub_title_name,
+                title_color=title_color,
+                other_data1=other_data1,
+                other_data2=other_data2,
+                emoji=emoji,
+            ),
+        )
+
+        logger.info(f"Online bot notification sent successfully (async): {header_name}")
+
+    except Exception as e:
+        logger.warning(f"Failed to send online bot notification (async): {e}")
+
+
+def send_error_bot_notification(
+    error_bot: Callable | None,
+    err: str,
+    title: str = "MemOS Error",
+    level: str = "P2",
+    user_ids: list | None = None,
+) -> None:
+    """
+    Send error alert if error_bot is available.
+
+    Args:
+        error_bot: The error_bot function or None
+        err: Error message
+        title: Alert title
+        level: Alert level (P0, P1, P2)
+        user_ids: List of user IDs to notify
+    """
+    if error_bot is None:
+        return
+
+    try:
+        error_bot(
+            err=err,
+            title=title,
+            level=level,
+            user_ids=user_ids or [],
+        )
+        logger.info(f"Error alert sent successfully: {title}")
+    except Exception as e:
+        logger.warning(f"Failed to send error alert: {e}")
+
+
+# Keep backward compatibility
+def send_error_alert(
+    error_bot: Callable | None,
+    error_message: str,
+    title: str = "MemOS Error",
+    level: str = "P2",
+) -> None:
+    """
+    Send error alert if error_bot is available (backward compatibility).
+    """
+    send_error_bot_notification(error_bot, error_message, title, level)

memos/memos_tools/singleton.py

@@ -0,0 +1,174 @@
+"""
+Singleton decorator module for caching factory instances to avoid excessive memory usage
+from repeated initialization.
+"""
+
+import hashlib
+import json
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+from weakref import WeakValueDictionary
+
+
+T = TypeVar("T")
+
+
+class FactorySingleton:
+    """Factory singleton manager that caches instances based on configuration parameters"""
+
+    def __init__(self):
+        # Use weak reference dictionary for automatic cleanup when instances are no longer referenced
+        self._instances: dict[str, WeakValueDictionary] = {}
+
+    def _generate_cache_key(self, config: Any, *args, **kwargs) -> str:
+        """Generate cache key based on configuration only (ignoring other parameters)"""
+
+        # Handle configuration objects - only use the config parameter
+        if hasattr(config, "model_dump"):  # Pydantic model
+            config_data = config.model_dump()
+        elif hasattr(config, "dict"):  # Legacy Pydantic model
+            config_data = config.dict()
+        elif isinstance(config, dict):
+            config_data = config
+        else:
+            # For other types, try to convert to string
+            config_data = str(config)
+
+        # Filter out time-related fields that shouldn't affect caching
+        filtered_config = self._filter_temporal_fields(config_data)
+
+        # Generate hash key based only on config
+        try:
+            cache_str = json.dumps(filtered_config, sort_keys=True, ensure_ascii=False, default=str)
+        except (TypeError, ValueError):
+            # If JSON serialization fails, convert the entire config to string
+            cache_str = str(filtered_config)
+
+        return hashlib.md5(cache_str.encode("utf-8")).hexdigest()
+
+    def _filter_temporal_fields(self, config_data: Any) -> Any:
+        """Filter out temporal fields that shouldn't affect instance caching"""
+        if isinstance(config_data, dict):
+            filtered = {}
+            for key, value in config_data.items():
+                # Skip common temporal field names
+                if key.lower() in {
+                    "created_at",
+                    "updated_at",
+                    "timestamp",
+                    "time",
+                    "date",
+                    "created_time",
+                    "updated_time",
+                    "last_modified",
+                    "modified_at",
+                    "start_time",
+                    "end_time",
+                    "execution_time",
+                    "run_time",
+                }:
+                    continue
+                # Recursively filter nested dictionaries
+                filtered[key] = self._filter_temporal_fields(value)
+            return filtered
+        elif isinstance(config_data, list):
+            # Recursively filter lists
+            return [self._filter_temporal_fields(item) for item in config_data]
+        else:
+            # For primitive types, return as-is
+            return config_data
+
+    def get_or_create(self, factory_class: type, cache_key: str, creator_func: Callable) -> Any:
+        """Get or create instance"""
+        class_name = factory_class.__name__
+
+        if class_name not in self._instances:
+            self._instances[class_name] = WeakValueDictionary()
+
+        class_cache = self._instances[class_name]
+
+        if cache_key in class_cache:
+            return class_cache[cache_key]
+
+        # Create new instance
+        instance = creator_func()
+        class_cache[cache_key] = instance
+        return instance
+
+    def clear_cache(self, factory_class: type | None = None):
+        """Clear cache"""
+        if factory_class:
+            class_name = factory_class.__name__
+            if class_name in self._instances:
+                self._instances[class_name].clear()
+        else:
+            for cache in self._instances.values():
+                cache.clear()
+
+
+# Global singleton manager
+_factory_singleton = FactorySingleton()
+
+
+def singleton_factory(factory_class: type | str | None = None):
+    """
+    Factory singleton decorator
+
+    Usage:
+    @singleton_factory()
+    def from_config(cls, config):
+        return SomeClass(config)
+
+    Or specify factory class:
+    @singleton_factory(EmbedderFactory)
+    def from_config(cls, config):
+        return SomeClass(config)
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> T:
+            # Determine factory class and config parameter
+            target_factory_class = factory_class
+            config = None
+
+            # Simple logic: check if first parameter is a class or config
+            if args:
+                if hasattr(args[0], "__name__") and hasattr(args[0], "__module__"):
+                    # First parameter is a class (cls), so this is a @classmethod
+                    if target_factory_class is None:
+                        target_factory_class = args[0]
+                    config = args[1] if len(args) > 1 else None
+                else:
+                    # First parameter is config, so this is a @staticmethod
+                    if target_factory_class is None:
+                        raise ValueError(
+                            "Factory class must be explicitly specified for static methods"
+                        )
+                    if isinstance(target_factory_class, str):
+                        # Convert string to a mock class for caching purposes
+                        class MockFactoryClass:
+                            __name__ = target_factory_class
+
+                        target_factory_class = MockFactoryClass
+                    config = args[0]
+
+            if config is None:
+                # If no configuration parameter, call original function directly
+                return func(*args, **kwargs)
+
+            # Generate cache key based only on config
+            cache_key = _factory_singleton._generate_cache_key(config)
+
+            # Function to create instance
+            def creator():
+                return func(*args, **kwargs)
+
+            # Get or create instance
+            return _factory_singleton.get_or_create(target_factory_class, cache_key, creator)
+
+        return wrapper
+
+    return decorator

memos/memos_tools/thread_safe_dict.py

@@ -0,0 +1,310 @@
+"""
+Thread-safe dictionary wrapper for concurrent access with optimized read-write locks.
+"""
+
+import threading
+
+from collections.abc import ItemsView, Iterator, KeysView, ValuesView
+from typing import Generic, TypeVar
+
+from memos.log import get_logger
+from memos.utils import timed
+
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+logger = get_logger(__name__)
+
+
+class ReadWriteLock:
+    """A simple read-write lock implementation. use for product-server scenario"""
+
+    def __init__(self):
+        self._read_ready = threading.Condition(threading.RLock())
+        self._readers = 0
+
+    @timed
+    def acquire_read(self):
+        """Acquire a read lock. Multiple readers can hold the lock simultaneously."""
+        self._read_ready.acquire()
+        try:
+            self._readers += 1
+        finally:
+            self._read_ready.release()
+
+    def release_read(self):
+        """Release a read lock."""
+        self._read_ready.acquire()
+        try:
+            self._readers -= 1
+            if self._readers == 0:
+                self._read_ready.notify_all()
+        finally:
+            self._read_ready.release()
+
+    @timed
+    def acquire_write(self):
+        """Acquire a write lock. Only one writer can hold the lock."""
+        self._read_ready.acquire()
+        while self._readers > 0:
+            self._read_ready.wait()
+
+    def release_write(self):
+        """Release a write lock."""
+        self._read_ready.release()
+
+
+class ThreadSafeDict(Generic[K, V]):
+    """
+    A thread-safe dictionary wrapper with optimized read-write locks.
+
+    This class allows multiple concurrent readers while ensuring exclusive access for writers.
+    Read operations (get, contains, iteration) can happen concurrently.
+    Write operations (set, delete, update) are exclusive.
+    """
+
+    def __init__(self, initial_dict: dict[K, V] | None = None):
+        """
+        Initialize the thread-safe dictionary.
+
+        Args:
+            initial_dict: Optional initial dictionary to copy from
+        """
+        self._dict: dict[K, V] = initial_dict.copy() if initial_dict else {}
+        self._lock = ReadWriteLock()
+
+    @timed
+    def __getitem__(self, key: K) -> V:
+        """Get item by key."""
+        self._lock.acquire_read()
+        try:
+            return self._dict[key]
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def __setitem__(self, key: K, value: V) -> None:
+        """Set item by key."""
+        self._lock.acquire_write()
+        try:
+            self._dict[key] = value
+        finally:
+            self._lock.release_write()
+
+    @timed
+    def __delitem__(self, key: K) -> None:
+        """Delete item by key."""
+        self._lock.acquire_write()
+        try:
+            del self._dict[key]
+        finally:
+            self._lock.release_write()
+
+    @timed
+    def __contains__(self, key: K) -> bool:
+        """Check if key exists in dictionary."""
+        self._lock.acquire_read()
+        try:
+            return key in self._dict
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def __len__(self) -> int:
+        """Get length of dictionary."""
+        self._lock.acquire_read()
+        try:
+            return len(self._dict)
+        finally:
+            self._lock.release_read()
+
+    def __bool__(self) -> bool:
+        """Check if dictionary is not empty."""
+        self._lock.acquire_read()
+        try:
+            return bool(self._dict)
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def __iter__(self) -> Iterator[K]:
+        """Iterate over keys. Returns a snapshot to avoid iteration issues."""
+        self._lock.acquire_read()
+        try:
+            # Return a snapshot of keys to avoid iteration issues
+            return iter(list(self._dict.keys()))
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def get(self, key: K, default: V | None = None) -> V:
+        """Get item by key with optional default."""
+        self._lock.acquire_read()
+        try:
+            return self._dict.get(key, default)
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def pop(self, key: K, *args) -> V:
+        """Pop item by key."""
+        self._lock.acquire_write()
+        try:
+            return self._dict.pop(key, *args)
+        finally:
+            self._lock.release_write()
+
+    @timed
+    def update(self, *args, **kwargs) -> None:
+        """Update dictionary."""
+        self._lock.acquire_write()
+        try:
+            self._dict.update(*args, **kwargs)
+        finally:
+            self._lock.release_write()
+
+    @timed
+    def clear(self) -> None:
+        """Clear all items."""
+        self._lock.acquire_write()
+        try:
+            self._dict.clear()
+        finally:
+            self._lock.release_write()
+
+    @timed
+    def keys(self) -> KeysView[K]:
+        """Get dictionary keys view (snapshot)."""
+        self._lock.acquire_read()
+        try:
+            return list(self._dict.keys())
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def values(self) -> ValuesView[V]:
+        """Get dictionary values view (snapshot)."""
+        self._lock.acquire_read()
+        try:
+            return list(self._dict.values())
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def items(self) -> ItemsView[K, V]:
+        """Get dictionary items view (snapshot)."""
+        self._lock.acquire_read()
+        try:
+            return list(self._dict.items())
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def copy(self) -> dict[K, V]:
+        """Create a copy of the dictionary."""
+        self._lock.acquire_read()
+        try:
+            return self._dict.copy()
+        finally:
+            self._lock.release_read()
+
+    @timed
+    def setdefault(self, key: K, default: V | None = None) -> V:
+        """Set default value for key if not exists."""
+        self._lock.acquire_write()
+        try:
+            return self._dict.setdefault(key, default)
+        finally:
+            self._lock.release_write()
+
+    def __repr__(self) -> str:
+        """String representation."""
+        self._lock.acquire_read()
+        try:
+            return f"ThreadSafeDict({self._dict})"
+        finally:
+            self._lock.release_read()
+
+    def __str__(self) -> str:
+        """String representation."""
+        self._lock.acquire_read()
+        try:
+            return str(self._dict)
+        finally:
+            self._lock.release_read()
+
+
+class SimpleThreadSafeDict(Generic[K, V]):
+    """
+    Simple thread-safe dictionary with exclusive locks for all operations.
+    Use this if you prefer simplicity over performance.
+    """
+
+    def __init__(self, initial_dict: dict[K, V] | None = None):
+        self._dict: dict[K, V] = initial_dict.copy() if initial_dict else {}
+        self._lock = threading.RLock()
+
+    def __getitem__(self, key: K) -> V:
+        with self._lock:
+            return self._dict[key]
+
+    def __setitem__(self, key: K, value: V) -> None:
+        with self._lock:
+            self._dict[key] = value
+
+    def __delitem__(self, key: K) -> None:
+        with self._lock:
+            del self._dict[key]
+
+    def __contains__(self, key: K) -> bool:
+        with self._lock:
+            return key in self._dict
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._dict)
+
+    def __bool__(self) -> bool:
+        with self._lock:
+            return bool(self._dict)
+
+    def __iter__(self) -> Iterator[K]:
+        with self._lock:
+            return iter(list(self._dict.keys()))
+
+    def get(self, key: K, default: V | None = None) -> V:
+        with self._lock:
+            return self._dict.get(key, default)
+
+    def pop(self, key: K, *args) -> V:
+        with self._lock:
+            return self._dict.pop(key, *args)
+
+    def update(self, *args, **kwargs) -> None:
+        with self._lock:
+            self._dict.update(*args, **kwargs)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._dict.clear()
+
+    def keys(self):
+        with self._lock:
+            return list(self._dict.keys())
+
+    def values(self):
+        with self._lock:
+            return list(self._dict.values())
+
+    def items(self):
+        with self._lock:
+            return list(self._dict.items())
+
+    def copy(self) -> dict[K, V]:
+        with self._lock:
+            return self._dict.copy()
+
+    def setdefault(self, key: K, default: V | None = None) -> V:
+        with self._lock:
+            return self._dict.setdefault(key, default)