MemoryOS 0.0.1__py3-none-any.whl → 0.1.13__py3-none-any.whl

memos/configs/memory.py

@@ -0,0 +1,195 @@
+from typing import Any, ClassVar
+
+from pydantic import Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+from memos.configs.embedder import EmbedderConfigFactory
+from memos.configs.graph_db import GraphDBConfigFactory
+from memos.configs.internet_retriever import InternetRetrieverConfigFactory
+from memos.configs.llm import LLMConfigFactory
+from memos.configs.vec_db import VectorDBConfigFactory
+from memos.exceptions import ConfigurationError
+
+
+# ─── 1. Global Base Memory Config ─────────────────────────────────────────────
+
+
+class BaseMemoryConfig(BaseConfig):
+    """Base configuration class for memories."""
+
+    cube_id: str | None = Field(
+        None,
+        description="Unique identifier for a MemCube that contains this memory",
+    )
+
+
+class UninitializedMemoryConfig(BaseMemoryConfig):
+    """Uninitialized memory configuration class."""
+
+
+# ─── 2.1. Activation Memory Configs ───────────────────────────────────────────
+
+
+class BaseActMemoryConfig(BaseMemoryConfig):
+    """Base configuration class for activation memories."""
+
+    memory_filename: str = Field(
+        "activation_memory.pickle",
+        description="Filename for storing memories",
+    )
+
+
+class KVCacheMemoryConfig(BaseActMemoryConfig):
+    """LLM KV Cache Memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+
+    @field_validator("extractor_llm")
+    @classmethod
+    def validate_extractor_llm(cls, extractor_llm: LLMConfigFactory) -> LLMConfigFactory:
+        """Validate the extractor_llm field."""
+        if extractor_llm.backend != "huggingface":
+            raise ConfigurationError(
+                f"KVCacheMemoryConfig requires extractor_llm backend to be 'huggingface', got '{extractor_llm.backend}'"
+            )
+        return extractor_llm
+
+
+# ─── 2.2. Parametric Memory Configs ───────────────────────────────────────────
+
+
+class BaseParaMemoryConfig(BaseMemoryConfig):
+    """Base configuration class for parametric memories."""
+
+    memory_filename: str = Field(
+        "parametric_memory.adapter",
+        description="Filename for storing memories",
+    )
+
+
+class LoRAMemoryConfig(BaseParaMemoryConfig):
+    """LoRA memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+
+    @field_validator("extractor_llm")
+    @classmethod
+    def validate_extractor_llm(cls, extractor_llm: LLMConfigFactory) -> LLMConfigFactory:
+        """Validate the extractor_llm field."""
+        if extractor_llm.backend not in ["huggingface"]:
+            raise ConfigurationError(
+                f"LoRAMemoryConfig requires extractor_llm backend to be 'huggingface', got '{extractor_llm.backend}'"
+            )
+        return extractor_llm
+
+
+# ─── 2.3. Textual Memory Configs ──────────────────────────────────────────────
+
+
+class BaseTextMemoryConfig(BaseMemoryConfig):
+    """Base configuration class for textual memories."""
+
+    memory_filename: str = Field(
+        "textual_memory.json",
+        description="Filename for storing memories",
+    )
+
+
+class NaiveTextMemoryConfig(BaseTextMemoryConfig):
+    """Naive textual memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+
+
+class GeneralTextMemoryConfig(BaseTextMemoryConfig):
+    """General memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+    vector_db: VectorDBConfigFactory = Field(
+        ...,
+        default_factory=VectorDBConfigFactory,
+        description="Vector database configuration for the memory storage",
+    )
+    embedder: EmbedderConfigFactory = Field(
+        ...,
+        default_factory=EmbedderConfigFactory,
+        description="Embedder configuration for the memory embedding",
+    )
+
+
+class TreeTextMemoryConfig(BaseTextMemoryConfig):
+    """Tree text memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+    dispatcher_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory dispatcher_llm in retrieve module",
+    )
+    embedder: EmbedderConfigFactory = Field(
+        ...,
+        default_factory=EmbedderConfigFactory,
+        description="Embedder configuration for the memory embedding",
+    )
+    graph_db: GraphDBConfigFactory = Field(
+        ...,
+        default_factory=GraphDBConfigFactory,
+        description="Graph database configuration for the tree-memory storage",
+    )
+    internet_retriever: InternetRetrieverConfigFactory | None = Field(
+        None,
+        description="Internet retriever configuration (optional)",
+    )
+
+
+# ─── 3. Global Memory Config Factory ──────────────────────────────────────────
+
+
+class MemoryConfigFactory(BaseConfig):
+    """Factory class for creating memory configurations."""
+
+    backend: str = Field("uninitialized", description="Backend for memory")
+    config: dict[str, Any] = Field({}, description="Configuration for the memory backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "naive_text": NaiveTextMemoryConfig,
+        "general_text": GeneralTextMemoryConfig,
+        "tree_text": TreeTextMemoryConfig,
+        "kv_cache": KVCacheMemoryConfig,
+        "lora": LoRAMemoryConfig,
+        "uninitialized": UninitializedMemoryConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ConfigurationError(f"Invalid backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "MemoryConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/parser.py

@@ -0,0 +1,38 @@
+from typing import Any, ClassVar
+
+from pydantic import Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+
+
+class BaseParserConfig(BaseConfig):
+    """Base configuration class for parser models."""
+
+
+class MarkItDownParserConfig(BaseParserConfig):
+    pass
+
+
+class ParserConfigFactory(BaseConfig):
+    """Factory class for creating Parser configurations."""
+
+    backend: str = Field(..., description="Backend for parser")
+    config: dict[str, Any] = Field(..., description="Configuration for the parser backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "markitdown": MarkItDownParserConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "ParserConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/utils.py

@@ -0,0 +1,8 @@
+import json
+
+
+def get_json_file_model_schema(json_path: str) -> str:
+    """Retrieve the model schema from a JSON file."""
+    with open(json_path, encoding="utf-8") as f:
+        data = json.load(f)
+    return data.get("model_schema", None)

memos/configs/vec_db.py

@@ -0,0 +1,64 @@
+from typing import Any, ClassVar, Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from memos import settings
+from memos.configs.base import BaseConfig
+from memos.log import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class BaseVecDBConfig(BaseConfig):
+    """Base class for all vector database configurations."""
+
+    collection_name: str = Field(..., description="Name of the collection")
+    vector_dimension: int | None = Field(default=None, description="Dimension of the vectors")
+    distance_metric: Literal["cosine", "euclidean", "dot"] | None = Field(
+        default=None,
+        description="Distance metric for vector similarity calculation. Options: 'cosine', 'euclidean', 'dot'",
+    )
+
+
+class QdrantVecDBConfig(BaseVecDBConfig):
+    """Configuration for Qdrant vector database."""
+
+    host: str | None = Field(default=None, description="Host for Qdrant")
+    port: int | None = Field(default=None, description="Port for Qdrant")
+    path: str | None = Field(default=None, description="Path for Qdrant")
+
+    @model_validator(mode="after")
+    def set_default_path(self):
+        if all(x is None for x in (self.host, self.port, self.path)):
+            logger.warning(
+                "No host, port, or path provided for Qdrant. Defaulting to local path: %s",
+                settings.MEMOS_DIR / "qdrant",
+            )
+            self.path = str(settings.MEMOS_DIR / "qdrant")
+        return self
+
+
+class VectorDBConfigFactory(BaseConfig):
+    """Factory class for creating vector database configurations."""
+
+    backend: str = Field(..., description="Backend for vector database")
+    config: dict[str, Any] = Field(..., description="Configuration for the vector database backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "qdrant": QdrantVecDBConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid vector database backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "VectorDBConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/deprecation.py

@@ -0,0 +1,262 @@
+"""
+This module provides utilities for marking functions, classes, and parameters
+as deprecated. It includes decorators for deprecation, a function to issue
+warnings, and utilities to check deprecation status.
+"""
+
+import functools
+import warnings
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+
+warnings.simplefilter("default", DeprecationWarning)
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+C = TypeVar("C", bound=type)
+
+
+def deprecated(
+    reason: str | None = None,
+    version: str | None = None,
+    alternative: str | None = None,
+    category: type[Warning] = DeprecationWarning,
+    stacklevel: int = 2,
+) -> Callable[[F], F]:
+    """
+    Decorator to mark functions as deprecated.
+
+    Args:
+        reason: Optional reason for deprecation
+        version: Version when the function was deprecated
+        alternative: Suggested alternative function/method
+        category: Warning category to use
+        stacklevel: Stack level for the warning
+
+    Example:
+        @deprecated(reason="Use new_function instead", version="1.2.0")
+        def old_function():
+            pass
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Build deprecation message
+            msg_parts = [f"Function '{func.__name__}' is deprecated"]
+
+            if version:
+                msg_parts.append(f"since version {version}")
+
+            if reason:
+                msg_parts.append(f"- {reason}")
+
+            if alternative:
+                msg_parts.append(f"Use '{alternative}' instead")
+
+            message = ". ".join(msg_parts) + "."
+
+            warnings.warn(message, category=category, stacklevel=stacklevel)
+            return func(*args, **kwargs)
+
+        # Mark the wrapper as deprecated for introspection
+        wrapper.__deprecated__ = True
+        wrapper.__deprecation_info__ = {
+            "reason": reason,
+            "version": version,
+            "alternative": alternative,
+            "category": category,
+        }
+
+        return wrapper
+
+    return decorator
+
+
+def deprecated_class(
+    reason: str | None = None,
+    version: str | None = None,
+    alternative: str | None = None,
+    category: type[Warning] = DeprecationWarning,
+    stacklevel: int = 2,
+) -> Callable[[C], C]:
+    """
+    Decorator to mark classes as deprecated.
+
+    Args:
+        reason: Optional reason for deprecation
+        version: Version when the class was deprecated
+        alternative: Suggested alternative class
+        category: Warning category to use
+        stacklevel: Stack level for the warning
+
+    Example:
+        @deprecated_class(reason="Use NewClass instead", version="1.2.0")
+        class OldClass:
+            pass
+    """
+
+    def decorator(cls: C) -> C:
+        # Store original __init__
+        original_init = cls.__init__
+
+        @functools.wraps(original_init)
+        def new_init(self, *args, **kwargs):
+            # Build deprecation message
+            msg_parts = [f"Class '{cls.__name__}' is deprecated"]
+
+            if version:
+                msg_parts.append(f"since version {version}")
+
+            if reason:
+                msg_parts.append(f"- {reason}")
+
+            if alternative:
+                msg_parts.append(f"Use '{alternative}' instead")
+
+            message = ". ".join(msg_parts) + "."
+
+            warnings.warn(message, category=category, stacklevel=stacklevel)
+            original_init(self, *args, **kwargs)
+
+        # Replace __init__
+        cls.__init__ = new_init
+
+        # Mark the class as deprecated for introspection
+        cls.__deprecated__ = True
+        cls.__deprecation_info__ = {
+            "reason": reason,
+            "version": version,
+            "alternative": alternative,
+            "category": category,
+        }
+
+        return cls
+
+    return decorator
+
+
+def deprecated_parameter(
+    parameter_name: str,
+    reason: str | None = None,
+    version: str | None = None,
+    alternative: str | None = None,
+    category: type[Warning] = DeprecationWarning,
+    stacklevel: int = 2,
+) -> Callable[[F], F]:
+    """
+    Decorator to mark specific parameters as deprecated.
+
+    Args:
+        parameter_name: Name of the deprecated parameter
+        reason: Optional reason for deprecation
+        version: Version when the parameter was deprecated
+        alternative: Suggested alternative parameter
+        category: Warning category to use
+        stacklevel: Stack level for the warning
+
+    Example:
+        @deprecated_parameter("old_param", alternative="new_param", version="1.2.0")
+        def my_function(new_param=None, old_param=None):
+            pass
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Check if deprecated parameter is used
+            if parameter_name in kwargs:
+                # Build deprecation message
+                msg_parts = [
+                    f"Parameter '{parameter_name}' in function '{func.__name__}' is deprecated"
+                ]
+
+                if version:
+                    msg_parts.append(f"since version {version}")
+
+                if reason:
+                    msg_parts.append(f"- {reason}")
+
+                if alternative:
+                    msg_parts.append(f"Use parameter '{alternative}' instead")
+
+                message = ". ".join(msg_parts) + "."
+
+                warnings.warn(message, category=category, stacklevel=stacklevel)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def warn_deprecated(
+    item_name: str,
+    item_type: str = "feature",
+    reason: str | None = None,
+    version: str | None = None,
+    alternative: str | None = None,
+    category: type[Warning] = DeprecationWarning,
+    stacklevel: int = 2,
+) -> None:
+    """
+    Issue a deprecation warning for any item.
+
+    Args:
+        item_name: Name of the deprecated item
+        item_type: Type of item (e.g., "function", "class", "parameter", "feature")
+        reason: Optional reason for deprecation
+        version: Version when the item was deprecated
+        alternative: Suggested alternative
+        category: Warning category to use
+        stacklevel: Stack level for the warning
+
+    Example:
+        warn_deprecated("old_method", "method", version="1.2.0", alternative="new_method")
+    """
+    # Build deprecation message
+    msg_parts = [f"{item_type.capitalize()} '{item_name}' is deprecated"]
+
+    if version:
+        msg_parts.append(f"since version {version}")
+
+    if reason:
+        msg_parts.append(f"- {reason}")
+
+    if alternative:
+        msg_parts.append(f"Use '{alternative}' instead")
+
+    message = ". ".join(msg_parts) + "."
+
+    warnings.warn(message, category=category, stacklevel=stacklevel)
+
+
+def is_deprecated(obj: Any) -> bool:
+    """
+    Check if an object is marked as deprecated.
+
+    Args:
+        obj: Object to check
+
+    Returns:
+        True if the object is deprecated, False otherwise
+    """
+    return getattr(obj, "__deprecated__", False)
+
+
+def get_deprecation_info(obj: Any) -> dict | None:
+    """
+    Get deprecation information for an object.
+
+    Args:
+        obj: Object to get deprecation info for
+
+    Returns:
+        Dictionary with deprecation info or None if not deprecated
+    """
+    if is_deprecated(obj):
+        return getattr(obj, "__deprecation_info__", None)
+    return None

memos/embedders/base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+
+from memos.configs.embedder import BaseEmbedderConfig
+
+
+class BaseEmbedder(ABC):
+    """Base class for all Embedding models."""
+
+    @abstractmethod
+    def __init__(self, config: BaseEmbedderConfig):
+        """Initialize the embedding model with the given configuration."""
+
+    @abstractmethod
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for the given texts."""

memos/embedders/factory.py

@@ -0,0 +1,23 @@
+from typing import Any, ClassVar
+
+from memos.configs.embedder import EmbedderConfigFactory
+from memos.embedders.base import BaseEmbedder
+from memos.embedders.ollama import OllamaEmbedder
+from memos.embedders.sentence_transformer import SenTranEmbedder
+
+
+class EmbedderFactory(BaseEmbedder):
+    """Factory class for creating embedder instances."""
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "ollama": OllamaEmbedder,
+        "sentence_transformer": SenTranEmbedder,
+    }
+
+    @classmethod
+    def from_config(cls, config_factory: EmbedderConfigFactory) -> BaseEmbedder:
+        backend = config_factory.backend
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        embedder_class = cls.backend_to_class[backend]
+        return embedder_class(config_factory.config)

memos/embedders/ollama.py

@@ -0,0 +1,74 @@
+from ollama import Client
+
+from memos.configs.embedder import OllamaEmbedderConfig
+from memos.embedders.base import BaseEmbedder
+from memos.log import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class OllamaEmbedder(BaseEmbedder):
+    """Ollama Embedder class."""
+
+    def __init__(self, config: OllamaEmbedderConfig):
+        self.config = config
+        self.api_base = config.api_base
+
+        if self.config.embedding_dims is not None:
+            logger.warning(
+                "Ollama does not support specifying embedding dimensions. "
+                "The embedding dimensions is determined by the model."
+                "`embedding_dims` will be set to None."
+            )
+            self.config.embedding_dims = None
+
+        # Default model if not specified
+        if not self.config.model_name_or_path:
+            self.config.model_name_or_path = "nomic-embed-text:latest"
+
+        # Initialize ollama client
+        self.client = Client(host=self.api_base)
+
+        # Ensure the model exists locally
+        self._ensure_model_exists()
+
+    def _list_models(self) -> list[str]:
+        """
+        List all models available in the Ollama client.
+
+        Returns:
+            List of model names.
+        """
+        local_models = self.client.list()["models"]
+        return [model.model for model in local_models]
+
+    def _ensure_model_exists(self):
+        """
+        Ensure the specified model exists locally. If not, pull it from Ollama.
+        """
+        try:
+            local_models = self._list_models()
+            if self.config.model_name_or_path not in local_models:
+                logger.warning(
+                    f"Model {self.config.model_name_or_path} not found locally. Pulling from Ollama..."
+                )
+                self.client.pull(self.config.model_name_or_path)
+        except Exception as e:
+            logger.warning(f"Could not verify model existence: {e}")
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """
+        Generate embeddings for the given texts.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of embeddings, each represented as a list of floats.
+        """
+        response = self.client.embed(
+            model=self.config.model_name_or_path,
+            input=texts,
+        )
+        return response.embeddings