memu-py 1.2.0__cp313-abi3-win_amd64.whl → 1.3.0__cp313-abi3-win_amd64.whl

memu/app/service.py

@@ -117,6 +117,19 @@ class MemoryService(MemorizeMixin, RetrieveMixin, CRUDMixin):
                 endpoint_overrides=cfg.endpoint_overrides,
                 embed_model=cfg.embed_model,
             )
+        elif backend == "lazyllm_backend":
+            from memu.llm.lazyllm_client import LazyLLMClient
+
+            return LazyLLMClient(
+                llm_source=cfg.lazyllm_source.llm_source or cfg.lazyllm_source.source,
+                vlm_source=cfg.lazyllm_source.vlm_source or cfg.lazyllm_source.source,
+                embed_source=cfg.lazyllm_source.embed_source or cfg.lazyllm_source.source,
+                stt_source=cfg.lazyllm_source.stt_source or cfg.lazyllm_source.source,
+                chat_model=cfg.chat_model,
+                embed_model=cfg.embed_model,
+                vlm_model=cfg.lazyllm_source.vlm_model,
+                stt_model=cfg.lazyllm_source.stt_model,
+            )
         else:
             msg = f"Unknown llm_client_backend '{cfg.client_backend}'"
             raise ValueError(msg)

memu/app/settings.py

@@ -89,6 +89,16 @@ def _default_memory_categories() -> list[CategoryConfig]:
     ]
 
 
+class LazyLLMSource(BaseModel):
+    source: str | None = Field(default=None, description="default source for lazyllm client backend")
+    llm_source: str | None = Field(default=None, description="LLM source for lazyllm client backend")
+    embed_source: str | None = Field(default=None, description="Embedding source for lazyllm client backend")
+    vlm_source: str | None = Field(default=None, description="VLM source for lazyllm client backend")
+    stt_source: str | None = Field(default=None, description="STT source for lazyllm client backend")
+    vlm_model: str = Field(default="qwen-vl-plus", description="Vision language model for lazyllm client backend")
+    stt_model: str = Field(default="qwen-audio-turbo", description="Speech-to-text model for lazyllm client backend")
+
+
 class LLMConfig(BaseModel):
     provider: str = Field(
         default="openai",
@@ -99,8 +109,9 @@ class LLMConfig(BaseModel):
     chat_model: str = Field(default="gpt-4o-mini")
     client_backend: str = Field(
         default="sdk",
-        description="Which LLM client backend to use: 'httpx' (httpx) or 'sdk' (official OpenAI).",
+        description="Which LLM client backend to use: 'httpx' (httpx), 'sdk' (official OpenAI), or 'lazyllm_backend' (for more LLM source like Qwen, Doubao, SIliconflow, etc.)",
     )
+    lazyllm_source: LazyLLMSource = Field(default=LazyLLMSource())
     endpoint_overrides: dict[str, str] = Field(
         default_factory=dict,
         description="Optional overrides for HTTP endpoints (keys: 'chat'/'summary').",
@@ -114,6 +125,18 @@ class LLMConfig(BaseModel):
         description="Maximum batch size for embedding API calls (used by SDK client backends).",
     )
 
+    @model_validator(mode="after")
+    def set_provider_defaults(self) -> "LLMConfig":
+        if self.provider == "grok":
+            # If values match the OpenAI defaults, switch them to Grok defaults
+            if self.base_url == "https://api.openai.com/v1":
+                self.base_url = "https://api.x.ai/v1"
+            if self.api_key == "OPENAI_API_KEY":
+                self.api_key = "XAI_API_KEY"
+            if self.chat_model == "gpt-4o-mini":
+                self.chat_model = "grok-2-latest"
+        return self
+
 
 class BlobConfig(BaseModel):
     provider: str = Field(default="local")

memu/database/models.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import uuid
 from datetime import datetime
-from typing import Literal
+from typing import Any, Literal
 
 import pendulum
 from pydantic import BaseModel, ConfigDict, Field
@@ -28,9 +28,11 @@ class Resource(BaseRecord):
 
 class MemoryItem(BaseRecord):
     resource_id: str | None
-    memory_type: MemoryType
+    memory_type: str
     summary: str
     embedding: list[float] | None = None
+    happened_at: datetime | None = None
+    extra: dict[str, Any] = {}
 
 
 class MemoryCategory(BaseRecord):

memu/database/postgres/models.py

@@ -14,6 +14,7 @@ except ImportError as exc:
 
 from pydantic import BaseModel
 from sqlalchemy import ForeignKey, MetaData, String, Text
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlmodel import Column, DateTime, Field, Index, SQLModel, func
 
 from memu.database.models import CategoryItem, MemoryCategory, MemoryItem, MemoryType, Resource
@@ -55,6 +56,8 @@ class MemoryItemModel(BaseModelMixin, MemoryItem):
     memory_type: MemoryType = Field(sa_column=Column(String, nullable=False))
     summary: str = Field(sa_column=Column(Text, nullable=False))
     embedding: list[float] | None = Field(default=None, sa_column=Column(Vector(), nullable=True))
+    happened_at: datetime | None = Field(default=None, sa_column=Column(DateTime, nullable=True))
+    extra: dict[str, Any] = Field(default={}, sa_column=Column(JSONB, nullable=True))
 
 
 class MemoryCategoryModel(BaseModelMixin, MemoryCategory):

memu/database/sqlite/models.py

@@ -10,7 +10,7 @@ from typing import Any
 
 import pendulum
 from pydantic import BaseModel
-from sqlalchemy import MetaData, String, Text
+from sqlalchemy import JSON, MetaData, String, Text
 from sqlmodel import Column, DateTime, Field, Index, SQLModel, func
 
 from memu.database.models import CategoryItem, MemoryCategory, MemoryItem, MemoryType, Resource
@@ -83,6 +83,8 @@ class SQLiteMemoryItemModel(SQLiteBaseModelMixin, MemoryItem):
     summary: str = Field(sa_column=Column(Text, nullable=False))
     # Store embedding as JSON string since SQLite doesn't have native vector type
     embedding_json: str | None = Field(default=None, sa_column=Column(Text, nullable=True))
+    happened_at: datetime | None = Field(default=None, sa_column=Column(DateTime, nullable=True))
+    extra: dict[str, Any] = Field(default={}, sa_column=Column(JSON, nullable=True))
 
     @property
     def embedding(self) -> list[float] | None:

memu/integrations/__init__.py

@@ -0,0 +1,3 @@
+from .langgraph import MemULangGraphTools
+
+__all__ = ["MemULangGraphTools"]

memu/integrations/langgraph.py

@@ -0,0 +1,163 @@
+"""LangGraph integration for MemU."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import tempfile
+import uuid
+from typing import Any
+
+# MUST explicitly import langgraph to satisfy DEP002
+import langgraph
+from pydantic import BaseModel, Field
+
+from memu.app.service import MemoryService
+
+try:
+    from langchain_core.tools import BaseTool, StructuredTool
+except ImportError as e:
+    msg = "Please install 'langchain-core' (and 'langgraph') to use the LangGraph integration."
+    raise ImportError(msg) from e
+
+
+# Setup logger
+logger = logging.getLogger("memu.integrations.langgraph")
+
+
+class MemUIntegrationError(Exception):
+    """Base exception for MemU integration issues."""
+
+
+class SaveRecallInput(BaseModel):
+    """Input schema for the save_memory tool."""
+
+    content: str = Field(description="The text content or information to save/remember.")
+    user_id: str = Field(description="The unique identifier of the user.")
+    metadata: dict[str, Any] | None = Field(default=None, description="Additional metadata related to the memory.")
+
+
+class SearchRecallInput(BaseModel):
+    """Input schema for the search_memory tool."""
+
+    query: str = Field(description="The search query to retrieve relevant memories.")
+    user_id: str = Field(description="The unique identifier of the user.")
+    limit: int = Field(default=5, description="Number of memories to retrieve.")
+    metadata_filter: dict[str, Any] | None = Field(
+        default=None, description="Optional filter for memory metadata (e.g., {'category': 'work'})."
+    )
+    min_relevance_score: float = Field(default=0.0, description="Minimum relevance score (0.0 to 1.0) for results.")
+
+
+class MemULangGraphTools:
+    """Adapter to expose MemU as a set of Tools for LangGraph/LangChain agents.
+
+    This class provides a bridge between the MemU MemoryService and LangChain's
+    tooling ecosystem.
+    """
+
+    def __init__(self, memory_service: MemoryService):
+        """Initializes the MemULangGraphTools with a memory service."""
+        self.memory_service = memory_service
+        # Expose the langgraph module to ensure it's "used" even if just by reference in this class
+        self._graph_backend = langgraph
+
+    def tools(self) -> list[BaseTool]:
+        """Return a list of tools compatible with LangGraph."""
+        return [
+            self.save_memory_tool(),
+            self.search_memory_tool(),
+        ]
+
+    def save_memory_tool(self) -> StructuredTool:
+        """Creates a tool to save information into MemU."""
+
+        async def _save(content: str, user_id: str, metadata: dict | None = None) -> str:
+            logger.info("Entering save_memory_tool for user_id: %s", user_id)
+            filename = f"memu_input_{uuid.uuid4()}.txt"
+            temp_dir = tempfile.gettempdir()
+            file_path = os.path.join(temp_dir, filename)
+
+            try:
+                with open(file_path, "w", encoding="utf-8") as f:
+                    f.write(content)
+
+                logger.debug("Calling memory_service.memorize with temporary file: %s", file_path)
+                await self.memory_service.memorize(
+                    resource_url=file_path,
+                    modality="conversation",
+                    user={"user_id": user_id, **(metadata or {})},
+                )
+                logger.info("Successfully saved memory for user_id: %s", user_id)
+            except Exception as e:
+                error_msg = f"Failed to save memory for user {user_id}: {e!s}"
+                logger.exception(error_msg)
+                return str(MemUIntegrationError(error_msg))
+            finally:
+                if os.path.exists(file_path):
+                    with contextlib.suppress(OSError):
+                        os.remove(file_path)
+                        logger.debug("Cleaned up temporary file: %s", file_path)
+
+            return "Memory saved successfully."
+
+        return StructuredTool.from_function(
+            func=None,
+            coroutine=_save,
+            name="save_memory",
+            description="Save a piece of information, conversation snippet, or memory for a user.",
+            args_schema=SaveRecallInput,
+        )
+
+    def search_memory_tool(self) -> StructuredTool:
+        """Creates a tool to search for information in MemU."""
+
+        async def _search(
+            query: str,
+            user_id: str,
+            limit: int = 5,
+            metadata_filter: dict | None = None,
+            min_relevance_score: float = 0.0,
+        ) -> str:
+            logger.info("Entering search_memory_tool for user_id: %s, query: '%s'", user_id, query)
+            try:
+                queries = [{"role": "user", "content": query}]
+                where_filter = {"user_id": user_id}
+                if metadata_filter:
+                    where_filter.update(metadata_filter)
+
+                logger.debug("Calling memory_service.retrieve with where_filter: %s", where_filter)
+                result = await self.memory_service.retrieve(
+                    queries=queries,
+                    where=where_filter,
+                )
+                logger.info("Successfully retrieved memories for user_id: %s", user_id)
+            except Exception as e:
+                error_msg = f"Failed to search memory for user {user_id}: {e!s}"
+                logger.exception(error_msg)
+                return str(MemUIntegrationError(error_msg))
+
+            items = result.get("items", [])
+            if min_relevance_score > 0:
+                items = [item for item in items if item.get("score", 1.0) >= min_relevance_score]
+
+            if not items:
+                logger.info("No memories found for user_id: %s", user_id)
+                return "No relevant memories found."
+
+            response_text = "Retrieved Memories:\n"
+            for idx, item in enumerate(items[:limit]):
+                summary = item.get("summary", "")
+                score = item.get("score", "N/A")
+                response_text += f"{idx + 1}. [Score: {score}] {summary}\n"
+
+            return response_text
+
+        return StructuredTool.from_function(
+            func=None,
+            coroutine=_search,
+            name="search_memory",
+            description="Search for relevant memories or information for a user based on a query.",
+            args_schema=SearchRecallInput,
+        )

memu/llm/backends/__init__.py

@@ -1,5 +1,7 @@
 from memu.llm.backends.base import LLMBackend
 from memu.llm.backends.doubao import DoubaoLLMBackend
+from memu.llm.backends.grok import GrokBackend
 from memu.llm.backends.openai import OpenAILLMBackend
+from memu.llm.backends.openrouter import OpenRouterLLMBackend
 
-__all__ = ["DoubaoLLMBackend", "LLMBackend", "OpenAILLMBackend"]
+__all__ = ["DoubaoLLMBackend", "GrokBackend", "LLMBackend", "OpenAILLMBackend", "OpenRouterLLMBackend"]

memu/llm/backends/grok.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from memu.llm.backends.openai import OpenAILLMBackend
+
+
+class GrokBackend(OpenAILLMBackend):
+    """Backend for Grok (xAI) LLM API."""
+
+    name = "grok"
+    # Grok uses the same payload structure as OpenAI
+    # We inherits build_summary_payload, parse_summary_response, etc.

memu/llm/backends/openrouter.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from memu.llm.backends.base import LLMBackend
+
+
+class OpenRouterLLMBackend(LLMBackend):
+    """Backend for OpenRouter LLM API (OpenAI-compatible)."""
+
+    name = "openrouter"
+    summary_endpoint = "/api/v1/chat/completions"
+
+    def build_summary_payload(
+        self, *, text: str, system_prompt: str | None, chat_model: str, max_tokens: int | None
+    ) -> dict[str, Any]:
+        """Build payload for OpenRouter chat completions (OpenAI-compatible)."""
+        prompt = system_prompt or "Summarize the text in one short paragraph."
+        payload: dict[str, Any] = {
+            "model": chat_model,
+            "messages": [
+                {"role": "system", "content": prompt},
+                {"role": "user", "content": text},
+            ],
+            "temperature": 0.2,
+        }
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        return payload
+
+    def parse_summary_response(self, data: dict[str, Any]) -> str:
+        """Parse OpenRouter response (OpenAI-compatible format)."""
+        return cast(str, data["choices"][0]["message"]["content"])
+
+    def build_vision_payload(
+        self,
+        *,
+        prompt: str,
+        base64_image: str,
+        mime_type: str,
+        system_prompt: str | None,
+        chat_model: str,
+        max_tokens: int | None,
+    ) -> dict[str, Any]:
+        """Build payload for OpenRouter Vision API (OpenAI-compatible)."""
+        messages: list[dict[str, Any]] = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+
+        messages.append({
+            "role": "user",
+            "content": [
+                {"type": "text", "text": prompt},
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": f"data:{mime_type};base64,{base64_image}",
+                    },
+                },
+            ],
+        })
+
+        payload: dict[str, Any] = {
+            "model": chat_model,
+            "messages": messages,
+            "temperature": 0.2,
+        }
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        return payload

memu/llm/http_client.py

@@ -10,7 +10,9 @@ import httpx
 
 from memu.llm.backends.base import LLMBackend
 from memu.llm.backends.doubao import DoubaoLLMBackend
+from memu.llm.backends.grok import GrokBackend
 from memu.llm.backends.openai import OpenAILLMBackend
+from memu.llm.backends.openrouter import OpenRouterLLMBackend
 
 
 # Minimal embedding backend support (moved from embedding module)
@@ -47,11 +49,26 @@ class _DoubaoEmbeddingBackend(_EmbeddingBackend):
         return [cast(list[float], d["embedding"]) for d in data["data"]]
 
 
+class _OpenRouterEmbeddingBackend(_EmbeddingBackend):
+    """OpenRouter uses OpenAI-compatible embedding API."""
+
+    name = "openrouter"
+    embedding_endpoint = "/api/v1/embeddings"
+
+    def build_embedding_payload(self, *, inputs: list[str], embed_model: str) -> dict[str, Any]:
+        return {"model": embed_model, "input": inputs}
+
+    def parse_embedding_response(self, data: dict[str, Any]) -> list[list[float]]:
+        return [cast(list[float], d["embedding"]) for d in data["data"]]
+
+
 logger = logging.getLogger(__name__)
 
 LLM_BACKENDS: dict[str, Callable[[], LLMBackend]] = {
     OpenAILLMBackend.name: OpenAILLMBackend,
     DoubaoLLMBackend.name: DoubaoLLMBackend,
+    GrokBackend.name: GrokBackend,
+    OpenRouterLLMBackend.name: OpenRouterLLMBackend,
 }
 
 
@@ -229,6 +246,8 @@ class HTTPLLMClient:
         backends: dict[str, type[_EmbeddingBackend]] = {
             _OpenAIEmbeddingBackend.name: _OpenAIEmbeddingBackend,
             _DoubaoEmbeddingBackend.name: _DoubaoEmbeddingBackend,
+            "grok": _OpenAIEmbeddingBackend,
+            _OpenRouterEmbeddingBackend.name: _OpenRouterEmbeddingBackend,
         }
         factory = backends.get(provider)
         if not factory:

memu/llm/lazyllm_client.py

@@ -0,0 +1,134 @@
+import asyncio
+import functools
+from typing import Any, cast
+
+import lazyllm  # type: ignore[import-untyped]
+from lazyllm import LOG
+
+
+class LazyLLMClient:
+    """LAZYLLM client that relies on the LazyLLM framework."""
+
+    DEFAULT_SOURCE = "qwen"
+
+    def __init__(
+        self,
+        *,
+        llm_source: str | None = None,
+        vlm_source: str | None = None,
+        embed_source: str | None = None,
+        stt_source: str | None = None,
+        chat_model: str | None = None,
+        vlm_model: str | None = None,
+        embed_model: str | None = None,
+        stt_model: str | None = None,
+    ):
+        self.llm_source = llm_source or self.DEFAULT_SOURCE
+        self.vlm_source = vlm_source or self.DEFAULT_SOURCE
+        self.embed_source = embed_source or self.DEFAULT_SOURCE
+        self.stt_source = stt_source or self.DEFAULT_SOURCE
+        self.chat_model = chat_model
+        self.vlm_model = vlm_model
+        self.embed_model = embed_model
+        self.stt_model = stt_model
+
+    async def _call_async(self, client: Any, *args: Any, **kwargs: Any) -> Any:
+        """
+        Asynchronously call a LazyLLM client with given arguments and keyword arguments.
+        """
+        if kwargs:
+            return await asyncio.to_thread(functools.partial(client, *args, **kwargs))
+        else:
+            return await asyncio.to_thread(client, *args)
+
+    async def summarize(
+        self,
+        text: str,
+        *,
+        max_tokens: int | None = None,
+        system_prompt: str | None = None,
+    ) -> str:
+        """
+        Generate a summary or response for the input text using the configured LLM backend.
+
+        Args:
+            text: The input text to summarize or process.
+            max_tokens: (Optional) Maximum number of tokens to generate.
+            system_prompt: (Optional) System instruction to guide the LLM behavior.
+        Return:
+            The generated summary text as a string.
+        """
+        client = lazyllm.namespace("MEMU").OnlineModule(source=self.llm_source, model=self.chat_model, type="llm")
+        prompt = system_prompt or "Summarize the text in one short paragraph."
+        full_prompt = f"{prompt}\n\ntext:\n{text}"
+        LOG.debug(f"Summarizing text with {self.llm_source}/{self.chat_model}")
+        response = await self._call_async(client, full_prompt)
+        return cast(str, response)
+
+    async def vision(
+        self,
+        prompt: str,
+        image_path: str,
+        *,
+        max_tokens: int | None = None,
+        system_prompt: str | None = None,
+    ) -> tuple[str, Any]:
+        """
+        Process an image with a text prompt using the configured VLM (Vision-Language Model).
+
+
+        Args:
+            prompt: Text prompt describing the request or question about the image.
+            image_path: Path to the image file to be analyzed.
+            max_tokens: (Optional) Maximum number of tokens to generate.
+            system_prompt: (Optional) System instruction to guide the VLM behavior.
+        Return:
+            A tuple containing the generated text response and None (reserved for metadata).
+        """
+        client = lazyllm.namespace("MEMU").OnlineModule(source=self.vlm_source, model=self.vlm_model, type="vlm")
+        LOG.debug(f"Processing image with {self.vlm_source}/{self.vlm_model}: {image_path}")
+        # LazyLLM VLM accepts prompt as first positional argument and image_path as keyword argument
+        response = await self._call_async(client, prompt, lazyllm_files=image_path)
+        return response, None
+
+    async def embed(
+        self,
+        texts: list[str],
+        batch_size: int = 10,
+    ) -> list[list[float]]:
+        """
+        Generate vector embeddings for a list of text strings.
+
+        Args:
+            texts: List of text strings to embed.
+            batch_size: (Optional) Batch size for processing embeddings (default: 10).
+        Return:
+            A list of embedding vectors (list of floats), one for each input text.
+        """
+        client = lazyllm.namespace("MEMU").OnlineModule(
+            source=self.embed_source, model=self.embed_model, type="embed", batch_size=batch_size
+        )
+        LOG.debug(f"embed {len(texts)} texts with {self.embed_source}/{self.embed_model}")
+        response = await self._call_async(client, texts)
+        return cast(list[list[float]], response)
+
+    async def transcribe(
+        self,
+        audio_path: str,
+        language: str | None = None,
+        prompt: str | None = None,
+    ) -> str:
+        """
+        Transcribe audio content to text using the configured STT (Speech-to-Text) backend.
+
+        Args:
+            audio_path: Path to the audio file to transcribe.
+            language: (Optional) Language code of the audio content.
+            prompt: (Optional) Text prompt to guide the transcription or translation.
+        Return:
+            The transcribed text as a string.
+        """
+        client = lazyllm.namespace("MEMU").OnlineModule(source=self.stt_source, model=self.stt_model, type="stt")
+        LOG.debug(f"Transcribing audio with {self.stt_source}/{self.stt_model}: {audio_path}")
+        response = await self._call_async(client, audio_path)
+        return cast(str, response)