MemoryOS 2.0.3__py3-none-any.whl

memos/api/context/dependencies.py

@@ -0,0 +1,50 @@
+import logging
+
+from memos.context.context import RequestContext, get_current_context
+
+
+logger = logging.getLogger(__name__)
+
+# Type alias for the RequestContext from context module
+G = RequestContext
+
+
+def get_g_object() -> G:
+    """
+    Get Flask g-like object for the current request.
+    Returns the context created by middleware.
+    """
+    ctx = get_current_context()
+    if ctx is None:
+        raise RuntimeError(
+            "No request context available. Make sure RequestContextMiddleware is properly configured."
+        )
+    return ctx
+
+
+def get_current_g() -> G | None:
+    """
+    Get the current request's g object from anywhere in the application.
+
+    Returns:
+        The current request's g object if available, None otherwise.
+    """
+    return get_current_context()
+
+
+def require_g() -> G:
+    """
+    Get the current request's g object, raising an error if not available.
+
+    Returns:
+        The current request's g object.
+
+    Raises:
+        RuntimeError: If called outside of a request context.
+    """
+    ctx = get_current_context()
+    if ctx is None:
+        raise RuntimeError(
+            "No request context available. This function must be called within a request handler."
+        )
+    return ctx

memos/api/exceptions.py

@@ -0,0 +1,53 @@
+import logging
+
+from fastapi.exceptions import HTTPException, RequestValidationError
+from fastapi.requests import Request
+from fastapi.responses import JSONResponse
+
+
+logger = logging.getLogger(__name__)
+
+
+class APIExceptionHandler:
+    """Centralized exception handling for MemOS APIs."""
+
+    @staticmethod
+    async def validation_error_handler(request: Request, exc: RequestValidationError):
+        """Handle request validation errors."""
+        logger.error(f"Validation error: {exc.errors()}")
+        return JSONResponse(
+            status_code=422,
+            content={
+                "code": 422,
+                "message": "Parameter validation error",
+                "detail": exc.errors(),
+                "data": None,
+            },
+        )
+
+    @staticmethod
+    async def value_error_handler(request: Request, exc: ValueError):
+        """Handle ValueError exceptions globally."""
+        logger.error(f"ValueError: {exc}")
+        return JSONResponse(
+            status_code=400,
+            content={"code": 400, "message": str(exc), "data": None},
+        )
+
+    @staticmethod
+    async def global_exception_handler(request: Request, exc: Exception):
+        """Handle all unhandled exceptions globally."""
+        logger.error(f"Exception: {exc}")
+        return JSONResponse(
+            status_code=500,
+            content={"code": 500, "message": str(exc), "data": None},
+        )
+
+    @staticmethod
+    async def http_error_handler(request: Request, exc: HTTPException):
+        """Handle HTTP exceptions globally."""
+        logger.error(f"HTTP error {exc.status_code}: {exc.detail}")
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={"code": exc.status_code, "message": str(exc.detail), "data": None},
+        )

memos/api/handlers/__init__.py

@@ -0,0 +1,62 @@
+"""
+Server handlers for MemOS API routers.
+
+This package contains modular handlers for the server_router, responsible for:
+- Building component configurations (config_builders)
+- Initializing server components (component_init)
+- Formatting data for API responses (formatters)
+- Handling search, add, scheduler, and chat operations
+"""
+
+# Lazy imports to avoid circular dependencies
+from memos.api.handlers import (
+    add_handler,
+    chat_handler,
+    memory_handler,
+    scheduler_handler,
+    search_handler,
+    suggestion_handler,
+)
+from memos.api.handlers.component_init import init_server
+from memos.api.handlers.config_builders import (
+    build_embedder_config,
+    build_graph_db_config,
+    build_internet_retriever_config,
+    build_llm_config,
+    build_mem_reader_config,
+    build_pref_adder_config,
+    build_pref_extractor_config,
+    build_pref_retriever_config,
+    build_reranker_config,
+    build_vec_db_config,
+)
+from memos.api.handlers.formatters_handler import (
+    format_memory_item,
+    post_process_pref_mem,
+    to_iter,
+)
+
+
+__all__ = [
+    "add_handler",
+    "build_embedder_config",
+    "build_graph_db_config",
+    "build_internet_retriever_config",
+    "build_llm_config",
+    "build_mem_reader_config",
+    "build_pref_adder_config",
+    "build_pref_extractor_config",
+    "build_pref_retriever_config",
+    "build_reranker_config",
+    "build_vec_db_config",
+    "chat_handler",
+    "format_memory_item",
+    "formatters_handler",
+    "init_server",
+    "memory_handler",
+    "post_process_pref_mem",
+    "scheduler_handler",
+    "search_handler",
+    "suggestion_handler",
+    "to_iter",
+]

memos/api/handlers/add_handler.py

@@ -0,0 +1,158 @@
+"""
+Add handler for memory addition functionality (Class-based version).
+
+This module provides a class-based implementation of add handlers,
+using dependency injection for better modularity and testability.
+"""
+
+from pydantic import validate_call
+
+from memos.api.handlers.base_handler import BaseHandler, HandlerDependencies
+from memos.api.product_models import APIADDRequest, APIFeedbackRequest, MemoryResponse
+from memos.memories.textual.item import (
+    list_all_fields,
+)
+from memos.multi_mem_cube.composite_cube import CompositeCubeView
+from memos.multi_mem_cube.single_cube import SingleCubeView
+from memos.multi_mem_cube.views import MemCubeView
+from memos.types import MessageList
+
+
+class AddHandler(BaseHandler):
+    """
+    Handler for memory addition operations.
+
+    Handles both text and preference memory additions with sync/async support.
+    """
+
+    def __init__(self, dependencies: HandlerDependencies):
+        """
+        Initialize add handler.
+
+        Args:
+            dependencies: HandlerDependencies instance
+        """
+        super().__init__(dependencies)
+        self._validate_dependencies(
+            "naive_mem_cube", "mem_reader", "mem_scheduler", "feedback_server"
+        )
+
+    def handle_add_memories(self, add_req: APIADDRequest) -> MemoryResponse:
+        """
+        Main handler for add memories endpoint.
+
+        Orchestrates the addition of both text and preference memories,
+        supporting concurrent processing.
+
+        Args:
+            add_req: Add memory request (deprecated fields are converted in model validator)
+
+        Returns:
+            MemoryResponse with added memory information
+        """
+        self.logger.info(
+            f"[DIAGNOSTIC] server_router -> add_handler.handle_add_memories called (Modified at 2025-11-29 18:46). Full request: {add_req.model_dump_json(indent=2)}"
+        )
+
+        if add_req.info:
+            exclude_fields = list_all_fields()
+            info_len = len(add_req.info)
+            add_req.info = {k: v for k, v in add_req.info.items() if k not in exclude_fields}
+            if len(add_req.info) < info_len:
+                self.logger.warning(f"[AddHandler] info fields can not contain {exclude_fields}.")
+
+        cube_view = self._build_cube_view(add_req)
+
+        @validate_call
+        def _check_messages(messages: MessageList) -> None:
+            pass
+
+        if add_req.is_feedback:
+            try:
+                messages = add_req.messages
+                _check_messages(messages)
+
+                chat_history = add_req.chat_history if add_req.chat_history else []
+                concatenate_chat = chat_history + messages
+
+                last_user_index = max(
+                    i for i, d in enumerate(concatenate_chat) if d["role"] == "user"
+                )
+                feedback_content = concatenate_chat[last_user_index]["content"]
+                feedback_history = concatenate_chat[:last_user_index]
+
+                feedback_req = APIFeedbackRequest(
+                    user_id=add_req.user_id,
+                    session_id=add_req.session_id,
+                    task_id=add_req.task_id,
+                    history=feedback_history,
+                    feedback_content=feedback_content,
+                    writable_cube_ids=add_req.writable_cube_ids,
+                    async_mode=add_req.async_mode,
+                    info=add_req.info,
+                )
+                process_record = cube_view.feedback_memories(feedback_req)
+
+                self.logger.info(
+                    f"[ADDFeedbackHandler] Final feedback results count={len(process_record)}"
+                )
+
+                return MemoryResponse(
+                    message="Memory feedback successfully",
+                    data=[process_record],
+                )
+            except Exception as e:
+                self.logger.warning(f"[ADDFeedbackHandler] Running error: {e}")
+
+        results = cube_view.add_memories(add_req)
+
+        self.logger.info(f"[AddHandler] Final add results count={len(results)}")
+
+        return MemoryResponse(
+            message="Memory added successfully",
+            data=results,
+        )
+
+    def _resolve_cube_ids(self, add_req: APIADDRequest) -> list[str]:
+        """
+        Normalize target cube ids from add_req.
+        Priority:
+        1) writable_cube_ids (deprecated mem_cube_id is converted to this in model validator)
+        2) fallback to user_id
+        """
+        if add_req.writable_cube_ids:
+            return list(dict.fromkeys(add_req.writable_cube_ids))
+
+        return [add_req.user_id]
+
+    def _build_cube_view(self, add_req: APIADDRequest) -> MemCubeView:
+        cube_ids = self._resolve_cube_ids(add_req)
+
+        if len(cube_ids) == 1:
+            cube_id = cube_ids[0]
+            return SingleCubeView(
+                cube_id=cube_id,
+                naive_mem_cube=self.naive_mem_cube,
+                mem_reader=self.mem_reader,
+                mem_scheduler=self.mem_scheduler,
+                logger=self.logger,
+                feedback_server=self.feedback_server,
+                searcher=None,
+            )
+        else:
+            single_views = [
+                SingleCubeView(
+                    cube_id=cube_id,
+                    naive_mem_cube=self.naive_mem_cube,
+                    mem_reader=self.mem_reader,
+                    mem_scheduler=self.mem_scheduler,
+                    logger=self.logger,
+                    feedback_server=self.feedback_server,
+                    searcher=None,
+                )
+                for cube_id in cube_ids
+            ]
+            return CompositeCubeView(
+                cube_views=single_views,
+                logger=self.logger,
+            )

memos/api/handlers/base_handler.py

@@ -0,0 +1,194 @@
+"""
+Base handler for MemOS API handlers.
+
+This module provides the base class for all API handlers, implementing
+dependency injection and common functionality.
+"""
+
+from typing import Any
+
+from memos.log import get_logger
+from memos.mem_scheduler.optimized_scheduler import OptimizedScheduler
+from memos.memories.textual.tree_text_memory.retrieve.advanced_searcher import AdvancedSearcher
+
+
+logger = get_logger(__name__)
+
+
+class HandlerDependencies:
+    """
+    Container for handler dependencies.
+
+    This class acts as a dependency injection container, holding all
+    shared resources needed by handlers.
+    """
+
+    def __init__(
+        self,
+        llm: Any | None = None,
+        naive_mem_cube: Any | None = None,
+        mem_reader: Any | None = None,
+        mem_scheduler: Any | None = None,
+        searcher: Any | None = None,
+        embedder: Any | None = None,
+        reranker: Any | None = None,
+        graph_db: Any | None = None,
+        vector_db: Any | None = None,
+        internet_retriever: Any | None = None,
+        memory_manager: Any | None = None,
+        mos_server: Any | None = None,
+        feedback_server: Any | None = None,
+        **kwargs,
+    ):
+        """
+        Initialize handler dependencies.
+
+        Args:
+            llm: Language model instance
+            naive_mem_cube: Memory cube instance
+            mem_reader: Memory reader instance
+            mem_scheduler: Scheduler instance
+            embedder: Embedder instance
+            reranker: Reranker instance
+            graph_db: Graph database instance
+            vector_db: Vector database instance
+            internet_retriever: Internet retriever instance
+            memory_manager: Memory manager instance
+            mos_server: MOS server instance
+            **kwargs: Additional dependencies
+        """
+        self.llm = llm
+        self.naive_mem_cube = naive_mem_cube
+        self.mem_reader = mem_reader
+        self.mem_scheduler = mem_scheduler
+        self.searcher = searcher
+        self.embedder = embedder
+        self.reranker = reranker
+        self.graph_db = graph_db
+        self.vector_db = vector_db
+        self.internet_retriever = internet_retriever
+        self.memory_manager = memory_manager
+        self.mos_server = mos_server
+        self.feedback_server = feedback_server
+
+        # Store any additional dependencies
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    @classmethod
+    def from_init_server(cls, components: dict[str, Any]):
+        """
+        Create dependencies from init_server() return values.
+
+        Args:
+            components: Dictionary of components returned by init_server().
+                       All components will be automatically unpacked as dependencies.
+
+        Returns:
+            HandlerDependencies instance
+
+        Note:
+            This method uses **kwargs unpacking, so any new components added to
+            init_server() will automatically become available as dependencies
+            without modifying this code.
+        """
+        return cls(**components)
+
+
+class BaseHandler:
+    """
+    Base class for all API handlers.
+
+    Provides common functionality and dependency injection for handlers.
+    All specific handlers should inherit from this class.
+    """
+
+    def __init__(self, dependencies: HandlerDependencies):
+        """
+        Initialize base handler.
+
+        Args:
+            dependencies: HandlerDependencies instance containing all shared resources
+        """
+        self.deps = dependencies
+        self.logger = get_logger(self.__class__.__name__)
+
+    @property
+    def llm(self):
+        """Get LLM instance."""
+        return self.deps.llm
+
+    @property
+    def naive_mem_cube(self):
+        """Get memory cube instance."""
+        return self.deps.naive_mem_cube
+
+    @property
+    def mem_reader(self):
+        """Get memory reader instance."""
+        return self.deps.mem_reader
+
+    @property
+    def mem_scheduler(self) -> OptimizedScheduler:
+        """Get scheduler instance."""
+        return self.deps.mem_scheduler
+
+    @property
+    def searcher(self) -> AdvancedSearcher:
+        """Get scheduler instance."""
+        return self.deps.searcher
+
+    @property
+    def embedder(self):
+        """Get embedder instance."""
+        return self.deps.embedder
+
+    @property
+    def reranker(self):
+        """Get reranker instance."""
+        return self.deps.reranker
+
+    @property
+    def graph_db(self):
+        """Get graph database instance."""
+        return self.deps.graph_db
+
+    @property
+    def vector_db(self):
+        """Get vector database instance."""
+        return self.deps.vector_db
+
+    @property
+    def mos_server(self):
+        """Get MOS server instance."""
+        return self.deps.mos_server
+
+    @property
+    def deepsearch_agent(self):
+        """Get deepsearch agent instance."""
+        return self.deps.deepsearch_agent
+
+    @property
+    def feedback_server(self):
+        """Get feedback server instance."""
+        return self.deps.feedback_server
+
+    def _validate_dependencies(self, *required_deps: str) -> None:
+        """
+        Validate that required dependencies are available.
+
+        Args:
+            *required_deps: Names of required dependency attributes
+
+        Raises:
+            ValueError: If any required dependency is None
+        """
+        missing = []
+        for dep_name in required_deps:
+            if not hasattr(self.deps, dep_name) or getattr(self.deps, dep_name) is None:
+                missing.append(dep_name)
+
+        if missing:
+            raise ValueError(
+                f"{self.__class__.__name__} requires the following dependencies: {', '.join(missing)}"
+            )