feat: add debug logger

Author: ankaisen

.gitignore

@@ -1,3 +1,4 @@
+data/
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

pyproject.toml

@@ -18,6 +18,10 @@ classifiers = [
 ]
 keywords = ["ai", "memory", "conversation", "llm", "chatbot", "agent"]
 dependencies = [
+    "httpx>=0.28.1",
+    "numpy>=2.3.4",
+    "openai>=2.8.0",
+    "pydantic>=2.12.4",
 ]
 
 [build-system]

src/memu/app/service.py

@@ -2,11 +2,12 @@
 
 import asyncio
 import json
-import os
 import re
 from collections.abc import Sequence
 from typing import Any, cast
 
+from pydantic import BaseModel
+
 from memu.app.settings import AppSettings
 from memu.llm.http_client import HTTPLLMClient
 from memu.memory.repo import InMemoryStore
@@ -27,9 +28,9 @@ def __init__(self, settings: AppSettings):
         self.store = InMemoryStore()
         backend = (settings.llm_client_backend or "httpx").lower()
         self.openai: Any
-        client_kwargs = {
+        client_kwargs: dict[str, Any] = {
             "base_url": settings.openai_base,
-            "api_key": os.getenv(settings.openai_api_key_env, ""),
+            "api_key": settings.openai_api_key,
             "chat_model": settings.chat_model,
             "embed_model": settings.embed_model,
         }
@@ -39,9 +40,9 @@ def __init__(self, settings: AppSettings):
             self.openai = OpenAISDKClient(**client_kwargs)
         elif backend == "httpx":
             self.openai = HTTPLLMClient(
-                **client_kwargs,
                 provider=self.settings.llm_http_provider,
                 endpoint_overrides=self.settings.llm_http_endpoints,
+                **client_kwargs,
             )
         else:
             msg = f"Unknown llm_client_backend '{settings.llm_client_backend}'"
@@ -89,9 +90,9 @@ async def memorize(self, *, resource_url: str, modality: str, summary_prompt: st
         await self._update_category_summaries(category_memory_updates)
 
         return {
-            "resource": res.model_dump(),
-            "items": [item.model_dump() for item in items],
-            "categories": [self.store.categories[c].model_dump() for c in cat_ids],
+            "resource": self._model_dump_without_embeddings(res),
+            "items": [self._model_dump_without_embeddings(item) for item in items],
+            "categories": [self._model_dump_without_embeddings(self.store.categories[c]) for c in cat_ids],
             "relations": [r.model_dump() for r in rels],
         }
 
@@ -110,7 +111,7 @@ async def _create_resource_with_caption(
             caption_text = caption.strip()
             if caption_text:
                 res.caption = caption_text
-                res.caption_embedding = (await self.openai.embed([caption_text]))[0]
+                res.embedding = (await self.openai.embed([caption_text]))[0]
         return res
 
     def _resolve_memory_types(self) -> list[MemoryType]:
@@ -365,6 +366,11 @@ def _extract_json_blob(raw: str) -> str:
     def _escape_prompt_value(value: str) -> str:
         return value.replace("{", "{{").replace("}", "}}")
 
+    def _model_dump_without_embeddings(self, obj: BaseModel) -> dict[str, Any]:
+        data = obj.model_dump()
+        data.pop("embedding", None)
+        return data
+
     async def retrieve(self, query: str, *, top_k: int = 5) -> dict[str, Any]:
         qvec = (await self.openai.embed([query]))[0]
         response: dict[str, list[dict[str, Any]]] = {"resources": [], "items": [], "categories": []}
@@ -413,7 +419,7 @@ def _materialize_hits(self, hits: Sequence[tuple[str, float]], pool: dict[str, A
             obj = pool.get(_id)
             if not obj:
                 continue
-            data = obj.model_dump()
+            data = self._model_dump_without_embeddings(obj)
             data["score"] = float(score)
             out.append(data)
         return out
@@ -450,8 +456,8 @@ def _format_resource_content(self, hits: list[tuple[str, float]]) -> str:
     def _resource_caption_corpus(self) -> list[tuple[str, list[float]]]:
         corpus: list[tuple[str, list[float]]] = []
         for rid, res in self.store.resources.items():
-            if res.caption_embedding:
-                corpus.append((rid, res.caption_embedding))
+            if res.embedding:
+                corpus.append((rid, res.embedding))
         return corpus
 
     async def _judge_retrieval_sufficient(self, query: str, content: str) -> bool:

src/memu/app/settings.py

@@ -32,12 +32,12 @@ class AppSettings(BaseModel):
     resources_dir: str = Field(default="./resources")
     # openai base
     openai_base: str = Field(default="https://api.openai.com/v1")
-    openai_api_key_env: str = Field(default="OPENAI_API_KEY")
+    openai_api_key: str = Field(default="OPENAI_API_KEY")
     # models
-    chat_model: str = Field(default="gpt-4o-mini")
+    chat_model: str = Field(default="gpt-5-nano")
     embed_model: str = Field(default="text-embedding-3-small")
     llm_client_backend: str = Field(
-        default="httpx",
+        default="sdk",
         description="Which OpenAI client backend to use: 'httpx' (httpx) or 'sdk' (official OpenAI).",
     )
     llm_http_provider: str = Field(

src/memu/llm/backends/base.py

@@ -11,7 +11,7 @@ class HTTPBackend:
     embedding_endpoint: str = "/embeddings"
 
     def build_summary_payload(
-        self, *, text: str, system_prompt: str | None, chat_model: str, max_tokens: int
+        self, *, text: str, system_prompt: str | None, chat_model: str, max_tokens: int | None
     ) -> dict[str, Any]:
         raise NotImplementedError
 

src/memu/llm/backends/openai.py

@@ -11,7 +11,7 @@ class OpenAIHTTPBackend(HTTPBackend):
     embedding_endpoint = "/embeddings"
 
     def build_summary_payload(
-        self, *, text: str, system_prompt: str | None, chat_model: str, max_tokens: int
+        self, *, text: str, system_prompt: str | None, chat_model: str, max_tokens: int | None
     ) -> dict[str, Any]:
         prompt = system_prompt or "Summarize the text in one short paragraph."
         return {

src/memu/llm/http_client.py

@@ -1,15 +1,15 @@
 from __future__ import annotations
 
-import os
+import logging
 from collections.abc import Callable
-from typing import cast
 
 import httpx
-import numpy as np
 
 from memu.llm.backends.base import HTTPBackend
 from memu.llm.backends.openai import OpenAIHTTPBackend
 
+logger = logging.getLogger(__name__)
+
 HTTP_BACKENDS: dict[str, Callable[[], HTTPBackend]] = {
     OpenAIHTTPBackend.name: OpenAIHTTPBackend,
 }
@@ -41,46 +41,31 @@ def __init__(
             or overrides.get("embed")
             or self.backend.embedding_endpoint
         )
-        self.fake = bool(os.getenv("MEMUFLOW_FAKE_OPENAI")) or not bool(self.api_key)
         self.timeout = timeout
 
-    async def summarize(self, text: str, max_tokens: int = 160, system_prompt: str | None = None) -> str:
-        if self.fake:
-            s = " ".join(text.strip().split())
-            return s[:200] + ("..." if len(s) > 200 else "")
-
+    async def summarize(self, text: str, max_tokens: int | None = None, system_prompt: str | None = None) -> str:
         payload = self.backend.build_summary_payload(
             text=text, system_prompt=system_prompt, chat_model=self.chat_model, max_tokens=max_tokens
         )
         async with httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout) as client:
             resp = await client.post(self.summary_endpoint, json=payload, headers=self._headers())
             resp.raise_for_status()
             data = resp.json()
+        logger.debug("HTTP LLM summarize response: %s", data)
         return self.backend.parse_summary_response(data)
 
     async def embed(self, inputs: list[str]) -> list[list[float]]:
-        if self.fake:
-            return [self._fake_vec(x) for x in inputs]
         payload = self.backend.build_embedding_payload(inputs=inputs, embed_model=self.embed_model)
         async with httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout) as client:
             resp = await client.post(self.embedding_endpoint, json=payload, headers=self._headers())
             resp.raise_for_status()
             data = resp.json()
+        logger.debug("HTTP LLM embedding response: %s", data)
         return self.backend.parse_embedding_response(data)
 
     def _headers(self) -> dict[str, str]:
         return {"Authorization": f"Bearer {self.api_key}"}
 
-    def _fake_vec(self, s: str, dim: int = 256) -> list[float]:
-        import hashlib
-
-        h = hashlib.sha256(s.encode("utf-8")).digest()
-        b = (h * (dim // len(h) + 1))[:dim]
-        arr = np.frombuffer(b, dtype=np.uint8).astype(np.float32)
-        arr = (arr - arr.mean()) / (arr.std() + 1e-6)
-        arr = arr / (np.linalg.norm(arr) + 1e-9)
-        return cast(list[float], arr.tolist())
-
     def _load_backend(self, provider: str) -> HTTPBackend:
         factory = HTTP_BACKENDS.get(provider)
         if not factory:

src/memu/llm/openai_sdk.py

@@ -1,15 +1,9 @@
-import os
-from typing import TYPE_CHECKING, cast
+import logging
+from typing import cast
 
-import numpy as np
+from openai import AsyncOpenAI
 
-if TYPE_CHECKING:
-    from openai import AsyncOpenAI  # 只给类型检查用
-
-try:
-    import openai
-except ImportError:
-    openai = None  # 运行时用来判断有没有这个库
+logger = logging.getLogger(__name__)
 
 
 class OpenAISDKClient:
@@ -20,58 +14,30 @@ def __init__(self, *, base_url: str, api_key: str, chat_model: str, embed_model:
         self.api_key = api_key or ""
         self.chat_model = chat_model
         self.embed_model = embed_model
-        self.fake = bool(os.getenv("MEMUFLOW_FAKE_OPENAI")) or not bool(self.api_key)
-        self.client: AsyncOpenAI | None = None
-        if self.fake:
-            self.client = None
-        else:
-            if openai is None:
-                msg = "The 'openai' Python package is required for the SDK client. Install it via `pip install openai` or switch to the httpx backend."
-                raise RuntimeError(msg)
-            self.client = openai.AsyncOpenAI(api_key=self.api_key, base_url=self.base_url)
+        self.client = AsyncOpenAI(api_key=self.api_key, base_url=self.base_url)
 
     async def summarize(
         self,
         text: str,
         *,
-        max_tokens: int = 160,
+        max_tokens: int | None = None,
         system_prompt: str | None = None,
     ) -> str:
         prompt = system_prompt or "Summarize the text in one short paragraph."
-        if self.fake:
-            s = " ".join(text.strip().split())
-            return s[:200] + ("..." if len(s) > 200 else "")
-        if self.client is None:
-            msg = "The 'openai' Python package is required for the SDK client. Install it via `pip install openai` or switch to the httpx backend."
-            raise RuntimeError(msg)
+
         response = await self.client.chat.completions.create(
             model=self.chat_model,
             messages=[
                 {"role": "system", "content": prompt},
                 {"role": "user", "content": text},
             ],
-            temperature=0.2,
-            max_tokens=max_tokens,
+            temperature=1,
+            max_completion_tokens=max_tokens,
         )
         content = response.choices[0].message.content
+        logger.debug("OpenAI summarize response: %s", response)
         return content or ""
 
     async def embed(self, inputs: list[str]) -> list[list[float]]:
-        if self.fake:
-            return [self._fake_vec(x) for x in inputs]
-        if self.client is None:
-            msg = "The 'openai' Python package is required for the SDK client. Install it via `pip install openai` or switch to the httpx backend."
-            raise RuntimeError(msg)
         response = await self.client.embeddings.create(model=self.embed_model, input=inputs)
         return [cast(list[float], d.embedding) for d in response.data]
-
-    def _fake_vec(self, s: str, dim: int = 256) -> list[float]:
-        # deterministic pseudo-embedding for offline demo
-        import hashlib
-
-        h = hashlib.sha256(s.encode("utf-8")).digest()
-        b = (h * (dim // len(h) + 1))[:dim]
-        arr = np.frombuffer(b, dtype=np.uint8).astype(np.float32)
-        arr = (arr - arr.mean()) / (arr.std() + 1e-6)
-        arr = arr / (np.linalg.norm(arr) + 1e-9)
-        return arr.tolist()

src/memu/models.py

@@ -13,7 +13,7 @@ class Resource(BaseModel):
     modality: str
     local_path: str
     caption: str | None = None
-    caption_embedding: list[float] | None = None
+    embedding: list[float] | None = None
 
 
 class MemoryItem(BaseModel):