MemoryOS 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

memos/api/product_models.py

@@ -0,0 +1,163 @@
+import uuid
+
+from typing import Generic, Literal, TypeAlias, TypeVar
+
+from pydantic import BaseModel, Field
+from typing_extensions import TypedDict
+
+
+T = TypeVar("T")
+
+
+# ─── Message Types ──────────────────────────────────────────────────────────────
+
+# Chat message roles
+MessageRole: TypeAlias = Literal["user", "assistant", "system"]
+
+
+# Message structure
+class MessageDict(TypedDict):
+    """Typed dictionary for chat message dictionaries."""
+
+    role: MessageRole
+    content: str
+
+
+class BaseRequest(BaseModel):
+    """Base model for all requests."""
+
+
+class BaseResponse(BaseModel, Generic[T]):
+    """Base model for all responses."""
+
+    code: int = Field(200, description="Response status code")
+    message: str = Field(..., description="Response message")
+    data: T | None = Field(None, description="Response data")
+
+
+# Product API Models
+class UserRegisterRequest(BaseRequest):
+    """Request model for user registration."""
+
+    user_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()), description="User ID for registration"
+    )
+    user_name: str | None = Field(None, description="User name for registration")
+    interests: str | None = Field(None, description="User interests")
+
+
+class GetMemoryRequest(BaseRequest):
+    """Request model for getting memories."""
+
+    user_id: str = Field(..., description="User ID")
+    memory_type: Literal["text_mem", "act_mem", "param_mem", "para_mem"] = Field(
+        ..., description="Memory type"
+    )
+    mem_cube_ids: list[str] | None = Field(None, description="Cube IDs")
+    search_query: str | None = Field(None, description="Search query")
+
+
+# Start API Models
+class Message(BaseModel):
+    role: str = Field(..., description="Role of the message (user or assistant).")
+    content: str = Field(..., description="Message content.")
+
+
+class MemoryCreate(BaseRequest):
+    user_id: str = Field(..., description="User ID")
+    messages: list[Message] | None = Field(None, description="List of messages to store.")
+    memory_content: str | None = Field(None, description="Content to store as memory")
+    doc_path: str | None = Field(None, description="Path to document to store")
+    mem_cube_id: str | None = Field(None, description="ID of the memory cube")
+
+
+class MemCubeRegister(BaseRequest):
+    mem_cube_name_or_path: str = Field(..., description="Name or path of the MemCube to register.")
+    mem_cube_id: str | None = Field(None, description="ID for the MemCube")
+
+
+class ChatRequest(BaseRequest):
+    """Request model for chat operations."""
+
+    user_id: str = Field(..., description="User ID")
+    query: str = Field(..., description="Chat query message")
+    mem_cube_id: str | None = Field(None, description="Cube ID to use for chat")
+    history: list[MessageDict] | None = Field(None, description="Chat history")
+    internet_search: bool = Field(True, description="Whether to use internet search")
+
+
+class UserCreate(BaseRequest):
+    user_name: str | None = Field(None, description="Name of the user")
+    role: str = Field("USER", description="Role of the user")
+    user_id: str = Field(..., description="User ID")
+
+
+class CubeShare(BaseRequest):
+    target_user_id: str = Field(..., description="Target user ID to share with")
+
+
+# Response Models
+class SimpleResponse(BaseResponse[None]):
+    """Simple response model for operations without data return."""
+
+
+class UserRegisterResponse(BaseResponse[dict]):
+    """Response model for user registration."""
+
+
+class MemoryResponse(BaseResponse[list]):
+    """Response model for memory operations."""
+
+
+class SuggestionResponse(BaseResponse[list]):
+    """Response model for suggestion operations."""
+
+    data: dict[str, list[str]] | None = Field(None, description="Response data")
+
+
+class ConfigResponse(BaseResponse[None]):
+    """Response model for configuration endpoint."""
+
+
+class SearchResponse(BaseResponse[dict]):
+    """Response model for search operations."""
+
+
+class ChatResponse(BaseResponse[str]):
+    """Response model for chat operations."""
+
+
+class UserResponse(BaseResponse[dict]):
+    """Response model for user operations."""
+
+
+class UserListResponse(BaseResponse[list]):
+    """Response model for user list operations."""
+
+
+class MemoryCreateRequest(BaseRequest):
+    """Request model for creating memories."""
+
+    user_id: str = Field(..., description="User ID")
+    messages: list[MessageDict] | None = Field(None, description="List of messages to store.")
+    memory_content: str | None = Field(None, description="Memory content to store")
+    doc_path: str | None = Field(None, description="Path to document to store")
+    mem_cube_id: str | None = Field(None, description="Cube ID")
+    source: str | None = Field(None, description="Source of the memory")
+    user_profile: bool = Field(False, description="User profile memory")
+
+
+class SearchRequest(BaseRequest):
+    """Request model for searching memories."""
+
+    user_id: str = Field(..., description="User ID")
+    query: str = Field(..., description="Search query")
+    mem_cube_id: str | None = Field(None, description="Cube ID to search in")
+    top_k: int = Field(10, description="Number of results to return")
+
+
+class SuggestionRequest(BaseRequest):
+    """Request model for getting suggestion queries."""
+
+    user_id: str = Field(..., description="User ID")
+    language: Literal["zh", "en"] = Field("zh", description="Language for suggestions")

memos/api/routers/__init__.py

@@ -0,0 +1 @@
+# API routers module

memos/api/routers/product_router.py

@@ -0,0 +1,386 @@
+import json
+import logging
+import traceback
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+
+from memos.api.config import APIConfig
+from memos.api.context.dependencies import G, get_g_object
+from memos.api.product_models import (
+    BaseResponse,
+    ChatRequest,
+    GetMemoryRequest,
+    MemoryCreateRequest,
+    MemoryResponse,
+    SearchRequest,
+    SearchResponse,
+    SimpleResponse,
+    SuggestionRequest,
+    SuggestionResponse,
+    UserRegisterRequest,
+    UserRegisterResponse,
+)
+from memos.configs.mem_os import MOSConfig
+from memos.mem_os.product import MOSProduct
+from memos.memos_tools.notification_service import get_error_bot_function, get_online_bot_function
+
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/product", tags=["Product API"])
+
+# Initialize MOSProduct instance with lazy initialization
+MOS_PRODUCT_INSTANCE = None
+
+
+def get_mos_product_instance():
+    """Get or create MOSProduct instance."""
+    global MOS_PRODUCT_INSTANCE
+    if MOS_PRODUCT_INSTANCE is None:
+        default_config = APIConfig.get_product_default_config()
+        logger.info(f"*********init_default_mos_config********* {default_config}")
+        from memos.configs.mem_os import MOSConfig
+
+        mos_config = MOSConfig(**default_config)
+
+        # Get default cube config from APIConfig (may be None if disabled)
+        default_cube_config = APIConfig.get_default_cube_config()
+        logger.info(f"*********initdefault_cube_config******** {default_cube_config}")
+
+        # Get DingDing bot functions
+        dingding_enabled = APIConfig.is_dingding_bot_enabled()
+        online_bot = get_online_bot_function() if dingding_enabled else None
+        error_bot = get_error_bot_function() if dingding_enabled else None
+
+        MOS_PRODUCT_INSTANCE = MOSProduct(
+            default_config=mos_config,
+            default_cube_config=default_cube_config,
+            online_bot=online_bot,
+            error_bot=error_bot,
+        )
+        logger.info("MOSProduct instance created successfully with inheritance architecture")
+    return MOS_PRODUCT_INSTANCE
+
+
+get_mos_product_instance()
+
+
+@router.post("/configure", summary="Configure MOSProduct", response_model=SimpleResponse)
+def set_config(config):
+    """Set MOSProduct configuration."""
+    global MOS_PRODUCT_INSTANCE
+    MOS_PRODUCT_INSTANCE = MOSProduct(default_config=config)
+    return SimpleResponse(message="Configuration set successfully")
+
+
+@router.post("/users/register", summary="Register a new user", response_model=UserRegisterResponse)
+def register_user(user_req: UserRegisterRequest, g: Annotated[G, Depends(get_g_object)]):
+    """Register a new user with configuration and default cube."""
+    try:
+        # Set request-related information in g object
+        g.user_id = user_req.user_id
+        g.action = "user_register"
+        g.timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+        logger.info(f"Starting user registration for user_id: {user_req.user_id}")
+        logger.info(f"Request trace_id: {g.trace_id}")
+        logger.info(f"Request timestamp: {g.timestamp}")
+
+        # Get configuration for the user
+        user_config, default_mem_cube = APIConfig.create_user_config(
+            user_name=user_req.user_id, user_id=user_req.user_id
+        )
+        logger.info(f"user_config: {user_config.model_dump(mode='json')}")
+        logger.info(f"default_mem_cube: {default_mem_cube.config.model_dump(mode='json')}")
+        mos_product = get_mos_product_instance()
+
+        # Register user with default config and mem cube
+        result = mos_product.user_register(
+            user_id=user_req.user_id,
+            user_name=user_req.user_name,
+            interests=user_req.interests,
+            config=user_config,
+            default_mem_cube=default_mem_cube,
+        )
+
+        if result["status"] == "success":
+            return UserRegisterResponse(
+                message="User registered successfully",
+                data={"user_id": result["user_id"], "mem_cube_id": result["default_cube_id"]},
+            )
+        else:
+            raise HTTPException(status_code=400, detail=result["message"])
+
+    except Exception as err:
+        logger.error(f"Failed to register user: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get(
+    "/suggestions/{user_id}", summary="Get suggestion queries", response_model=SuggestionResponse
+)
+def get_suggestion_queries(user_id: str):
+    """Get suggestion queries for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        suggestions = mos_product.get_suggestion_query(user_id)
+        return SuggestionResponse(
+            message="Suggestions retrieved successfully", data={"query": suggestions}
+        )
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get suggestions: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post(
+    "/suggestions",
+    summary="Get suggestion queries with language",
+    response_model=SuggestionResponse,
+)
+def get_suggestion_queries_post(suggestion_req: SuggestionRequest):
+    """Get suggestion queries for a specific user with language preference."""
+    try:
+        mos_product = get_mos_product_instance()
+        suggestions = mos_product.get_suggestion_query(
+            user_id=suggestion_req.user_id, language=suggestion_req.language
+        )
+        return SuggestionResponse(
+            message="Suggestions retrieved successfully", data={"query": suggestions}
+        )
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get suggestions: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/get_all", summary="Get all memories for user", response_model=MemoryResponse)
+def get_all_memories(memory_req: GetMemoryRequest):
+    """Get all memories for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        if memory_req.search_query:
+            result = mos_product.get_subgraph(
+                user_id=memory_req.user_id,
+                query=memory_req.search_query,
+                mem_cube_ids=memory_req.mem_cube_ids,
+            )
+            return MemoryResponse(message="Memories retrieved successfully", data=result)
+        else:
+            result = mos_product.get_all(
+                user_id=memory_req.user_id,
+                memory_type=memory_req.memory_type,
+                mem_cube_ids=memory_req.mem_cube_ids,
+            )
+            return MemoryResponse(message="Memories retrieved successfully", data=result)
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get memories: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/add", summary="add a new memory", response_model=SimpleResponse)
+def create_memory(memory_req: MemoryCreateRequest):
+    """Create a new memory for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        mos_product.add(
+            user_id=memory_req.user_id,
+            memory_content=memory_req.memory_content,
+            messages=memory_req.messages,
+            doc_path=memory_req.doc_path,
+            mem_cube_id=memory_req.mem_cube_id,
+            source=memory_req.source,
+            user_profile=memory_req.user_profile,
+        )
+        return SimpleResponse(message="Memory created successfully")
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to create memory: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/search", summary="Search memories", response_model=SearchResponse)
+def search_memories(search_req: SearchRequest):
+    """Search memories for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        result = mos_product.search(
+            query=search_req.query,
+            user_id=search_req.user_id,
+            install_cube_ids=[search_req.mem_cube_id] if search_req.mem_cube_id else None,
+            top_k=search_req.top_k,
+        )
+        return SearchResponse(message="Search completed successfully", data=result)
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to search memories: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/chat", summary="Chat with MemOS")
+def chat(chat_req: ChatRequest):
+    """Chat with MemOS for a specific user. Returns SSE stream."""
+    try:
+        mos_product = get_mos_product_instance()
+
+        def generate_chat_response():
+            """Generate chat response as SSE stream."""
+            try:
+                # Directly yield from the generator without async wrapper
+                yield from mos_product.chat_with_references(
+                    query=chat_req.query,
+                    user_id=chat_req.user_id,
+                    cube_id=chat_req.mem_cube_id,
+                    history=chat_req.history,
+                    internet_search=chat_req.internet_search,
+                )
+
+            except Exception as e:
+                logger.error(f"Error in chat stream: {e}")
+                error_data = f"data: {json.dumps({'type': 'error', 'content': str(traceback.format_exc())})}\n\n"
+                yield error_data
+
+        return StreamingResponse(
+            generate_chat_response(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Content-Type": "text/event-stream",
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Headers": "*",
+                "Access-Control-Allow-Methods": "*",
+            },
+        )
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to start chat: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get("/users", summary="List all users", response_model=BaseResponse[list])
+def list_users():
+    """List all registered users."""
+    try:
+        mos_product = get_mos_product_instance()
+        users = mos_product.list_users()
+        return BaseResponse(message="Users retrieved successfully", data=users)
+    except Exception as err:
+        logger.error(f"Failed to list users: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get("/users/{user_id}", summary="Get user info", response_model=BaseResponse[dict])
+async def get_user_info(user_id: str):
+    """Get user information including accessible cubes."""
+    try:
+        mos_product = get_mos_product_instance()
+        user_info = mos_product.get_user_info(user_id)
+        return BaseResponse(message="User info retrieved successfully", data=user_info)
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get user info: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get(
+    "/configure/{user_id}", summary="Get MOSProduct configuration", response_model=SimpleResponse
+)
+def get_config(user_id: str):
+    """Get MOSProduct configuration."""
+    global MOS_PRODUCT_INSTANCE
+    config = MOS_PRODUCT_INSTANCE.default_config
+    return SimpleResponse(message="Configuration retrieved successfully", data=config)
+
+
+@router.get(
+    "/users/{user_id}/config", summary="Get user configuration", response_model=BaseResponse[dict]
+)
+def get_user_config(user_id: str):
+    """Get user-specific configuration."""
+    try:
+        mos_product = get_mos_product_instance()
+        config = mos_product.get_user_config(user_id)
+        if config:
+            return BaseResponse(
+                message="User configuration retrieved successfully",
+                data=config.model_dump(mode="json"),
+            )
+        else:
+            raise HTTPException(
+                status_code=404, detail=f"Configuration not found for user {user_id}"
+            )
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get user config: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.put(
+    "/users/{user_id}/config", summary="Update user configuration", response_model=SimpleResponse
+)
+def update_user_config(user_id: str, config_data: dict):
+    """Update user-specific configuration."""
+    try:
+        mos_product = get_mos_product_instance()
+
+        # Create MOSConfig from the provided data
+        config = MOSConfig(**config_data)
+
+        # Update the configuration
+        success = mos_product.update_user_config(user_id, config)
+        if success:
+            return SimpleResponse(message="User configuration updated successfully")
+        else:
+            raise HTTPException(status_code=500, detail="Failed to update user configuration")
+
+    except ValueError as err:
+        raise HTTPException(status_code=400, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to update user config: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get(
+    "/instances/status", summary="Get user configuration status", response_model=BaseResponse[dict]
+)
+def get_instance_status():
+    """Get information about active user configurations in memory."""
+    try:
+        mos_product = get_mos_product_instance()
+        status_info = mos_product.get_user_instance_info()
+        return BaseResponse(
+            message="User configuration status retrieved successfully", data=status_info
+        )
+    except Exception as err:
+        logger.error(f"Failed to get user configuration status: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get("/instances/count", summary="Get active user count", response_model=BaseResponse[int])
+def get_active_user_count():
+    """Get the number of active user configurations in memory."""
+    try:
+        mos_product = get_mos_product_instance()
+        count = mos_product.get_active_user_count()
+        return BaseResponse(message="Active user count retrieved successfully", data=count)
+    except Exception as err:
+        logger.error(f"Failed to get active user count: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err

memos/chunkers/sentence_chunker.py

@@ -1,6 +1,5 @@
-from chonkie import SentenceChunker as ChonkieSentenceChunker
-
 from memos.configs.chunker import SentenceChunkerConfig
+from memos.dependency import require_python_package
 from memos.log import get_logger
 
 from .base import BaseChunker, Chunk
@@ -12,7 +11,14 @@ logger = get_logger(__name__)
 class SentenceChunker(BaseChunker):
     """Sentence-based text chunker."""
 
+    @require_python_package(
+        import_name="chonkie",
+        install_command="pip install chonkie",
+        install_link="https://docs.chonkie.ai/python-sdk/getting-started/installation",
+    )
     def __init__(self, config: SentenceChunkerConfig):
+        from chonkie import SentenceChunker as ChonkieSentenceChunker
+
         self.config = config
         self.chunker = ChonkieSentenceChunker(
             tokenizer_or_token_counter=config.tokenizer_or_token_counter,

memos/cli.py

@@ -0,0 +1,113 @@
+"""
+MemOS CLI Tool
+This script provides command-line interface for MemOS operations.
+"""
+
+import argparse
+import json
+import os
+import zipfile
+
+from io import BytesIO
+
+
+def export_openapi(output: str) -> bool:
+    """Export OpenAPI schema to JSON file."""
+    from memos.api.start_api import app
+
+    # Create directory if it doesn't exist
+    if os.path.dirname(output):
+        os.makedirs(os.path.dirname(output), exist_ok=True)
+
+    with open(output, "w") as f:
+        json.dump(app.openapi(), f, indent=2)
+        f.write("\n")
+
+    print(f"✅ OpenAPI schema exported to: {output}")
+    return True
+
+
+def download_examples(dest: str) -> bool:
+    import requests
+
+    """Download examples from the MemOS repository."""
+    zip_url = "https://github.com/MemTensor/MemOS/archive/refs/heads/main.zip"
+    print(f"📥 Downloading examples from {zip_url}...")
+
+    try:
+        response = requests.get(zip_url)
+        response.raise_for_status()
+
+        with zipfile.ZipFile(BytesIO(response.content)) as z:
+            extracted_files = []
+            for file in z.namelist():
+                if "MemOS-main/examples/" in file and not file.endswith("/"):
+                    # Remove the prefix and extract to dest
+                    relative_path = file.replace("MemOS-main/examples/", "")
+                    extract_path = os.path.join(dest, relative_path)
+
+                    # Create directory if it doesn't exist
+                    os.makedirs(os.path.dirname(extract_path), exist_ok=True)
+
+                    # Extract the file
+                    with z.open(file) as source, open(extract_path, "wb") as target:
+                        target.write(source.read())
+                    extracted_files.append(extract_path)
+
+        print(f"✅ Examples downloaded to: {dest}")
+        print(f"📁 {len(extracted_files)} files extracted")
+
+    except requests.RequestException as e:
+        print(f"❌ Error downloading examples: {e}")
+        return False
+    except Exception as e:
+        print(f"❌ Error extracting examples: {e}")
+        return False
+
+    return True
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="memos",
+        description="MemOS Command Line Interface",
+    )
+
+    # Create subparsers for different commands
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Download examples command
+    examples_parser = subparsers.add_parser("download_examples", help="Download example files")
+    examples_parser.add_argument(
+        "--dest",
+        type=str,
+        default="./examples",
+        help="Destination directory for examples (default: ./examples)",
+    )
+
+    # Export API command
+    api_parser = subparsers.add_parser("export_openapi", help="Export OpenAPI schema to JSON file")
+    api_parser.add_argument(
+        "--output",
+        type=str,
+        default="openapi.json",
+        help="Output path for OpenAPI schema (default: openapi.json)",
+    )
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    # Handle commands
+    if args.command == "download_examples":
+        success = download_examples(args.dest)
+        exit(0 if success else 1)
+    elif args.command == "export_openapi":
+        success = export_openapi(args.output)
+        exit(0 if success else 1)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()