neobot-memory 1.0.0a6__tar.gz

neobot_memory-1.0.0a6/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: neobot-memory
+Version: 1.0.0a6
+Summary: Add your description here
+Author: wsrsq, tangtian
+Author-email: wsrsq <wsrsq001@163.com>, tangtian <a14b@126.com>
+Requires-Dist: neobot-contracts
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

neobot_memory-1.0.0a6/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "neobot-memory"
+version = "1.0.0-alpha.6"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "wsrsq", email = "wsrsq001@163.com" },
+    { name = "tangtian", email = "a14b@126.com" },
+]
+requires-python = ">=3.13"
+dependencies = ["neobot-contracts"]
+
+[tool.uv.sources]
+neobot-contracts = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_memory-1.0.0a6/src/neobot_memory/__init__.py

@@ -0,0 +1,25 @@
+"""neobot_memory — 记忆包公共 API"""
+
+from neobot_memory.archive_service import ArchiveMemoryService
+from neobot_memory.defaults import (
+    InMemoryArchiveMemoryAccess,
+    InMemoryImageAnalysisAccess,
+    InMemoryMemoryRepository,
+    NullLogger,
+    SystemClock,
+)
+from neobot_memory.image_service import ImageAnalysisService
+from neobot_memory.reader import MemoryReader
+from neobot_memory.service import MemoryService
+
+__all__ = [
+    "ArchiveMemoryService",
+    "ImageAnalysisService",
+    "MemoryService",
+    "MemoryReader",
+    "InMemoryMemoryRepository",
+    "InMemoryArchiveMemoryAccess",
+    "InMemoryImageAnalysisAccess",
+    "NullLogger",
+    "SystemClock",
+]

neobot_memory-1.0.0a6/src/neobot_memory/archive_service.py

@@ -0,0 +1,77 @@
+"""Archive memory service."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from neobot_contracts.models.memory import ArchiveMemory
+from neobot_contracts.ports.logging import Logger
+from neobot_contracts.ports.unit_of_work import UnitOfWorkFactory
+
+
+class ArchiveMemoryService:
+    """Service for archive memory CRUD and query operations."""
+
+    def __init__(self, uow_factory: UnitOfWorkFactory, logger: Logger) -> None:
+        self._uow_factory = uow_factory
+        self._logger = logger
+
+    async def get(self, table_name: str, key: str) -> Optional[ArchiveMemory]:
+        async with self._uow_factory() as uow:
+            item = await uow.archive.get(table_name, key)
+        self._logger.debug("存档记忆已获取", table_name=table_name, key=key, found=item is not None)
+        return item
+
+    async def exists(self, table_name: str, key: str) -> bool:
+        async with self._uow_factory() as uow:
+            exists = await uow.archive.exists(table_name, key)
+        self._logger.debug("存档记忆存在检查", table_name=table_name, key=key, exists=exists)
+        return exists
+
+    async def list(
+        self,
+        table_name: str,
+        *,
+        tags: Optional[list[str]] = None,
+        key_query: Optional[str] = None,
+        value_query: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ArchiveMemory]:
+        async with self._uow_factory() as uow:
+            items = await uow.archive.list(
+                table_name,
+                tags=tags,
+                key_query=key_query,
+                value_query=value_query,
+                limit=limit,
+                offset=offset,
+            )
+        self._logger.debug(
+            "存档记忆列表已获取",
+            table_name=table_name,
+            count=len(items),
+            limit=limit,
+            offset=offset,
+        )
+        return items
+
+    async def set(self, table_name: str, key: str, value: str, tags: list[str]) -> ArchiveMemory:
+        async with self._uow_factory() as uow:
+            item = await uow.archive.set(table_name, key, value, tags)
+            await uow.commit()
+        self._logger.debug(
+            "存档记忆已保存",
+            table_name=table_name,
+            key=key,
+            version=item.version,
+        )
+        return item
+
+    async def delete(self, table_name: str, key: str) -> bool:
+        async with self._uow_factory() as uow:
+            deleted = await uow.archive.delete(table_name, key)
+            if deleted:
+                await uow.commit()
+        self._logger.debug("存档记忆已删除", table_name=table_name, key=key, deleted=deleted)
+        return deleted

neobot_memory-1.0.0a6/src/neobot_memory/defaults.py

@@ -0,0 +1,264 @@
+"""Defaults — 开箱即用的默认实现"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from neobot_contracts.models import ConversationRef, MemoryRecord
+from neobot_contracts.models.memory import ArchiveMemory, ImageAnalysis
+from neobot_contracts.ports.archive_memory_access import ArchiveMemoryAccess
+from neobot_contracts.time_context import now_utc
+from neobot_contracts.ports.image_analysis_access import ImageAnalysisAccess
+from neobot_contracts.ports.clock import SystemClock as SystemClock  # re-export
+from neobot_contracts.ports.logging import NullLogger as NullLogger  # re-export
+
+
+class InMemoryMemoryRepository:
+    """纯内存记忆存储，用于测试或独立运行"""
+
+    def __init__(self) -> None:
+        self._records: list[MemoryRecord] = []
+
+    async def save(self, record: MemoryRecord) -> None:
+        self._records.append(record)
+
+    async def search(
+        self, conversation: ConversationRef, query: str, limit: int = 5
+    ) -> list[MemoryRecord]:
+        matches = [
+            r for r in self._records
+            if r.conversation == conversation and query.lower() in r.content.lower()
+        ]
+        return matches[-limit:]
+
+
+class InMemoryArchiveMemoryAccess:
+    """内存档案式记忆存储，用于测试或独立运行"""
+
+    def __init__(self) -> None:
+        self._storage: dict[tuple[str, str], ArchiveMemory] = {}
+        self._id_counter = 0
+
+    async def get(self, table_name: str, key: str) -> Optional[ArchiveMemory]:
+        """根据表名和键名获取档案式记忆条目"""
+        entry = self._storage.get((table_name, key))
+        if entry is None:
+            return None
+        return self._clone(entry)
+
+    async def set(
+        self,
+        table_name: str,
+        key: str,
+        value: str,
+        tags: list[str],
+    ) -> ArchiveMemory:
+        """创建或更新档案式记忆条目"""
+        entry_key = (table_name, key)
+
+        if entry_key in self._storage:
+            # 更新现有条目
+            existing = self._storage[entry_key]
+            updated = ArchiveMemory(
+                id=existing.id,
+                table_name=table_name,
+                key=key,
+                value=value,
+                tags=tags.copy(),  # 创建副本避免外部修改
+                created_at=existing.created_at,  # 保留原始创建时间
+                updated_at=now_utc(),
+                version=existing.version + 1,
+            )
+        else:
+            # 创建新条目
+            self._id_counter += 1
+            now = now_utc()
+            updated = ArchiveMemory(
+                id=self._id_counter,
+                table_name=table_name,
+                key=key,
+                value=value,
+                tags=tags.copy(),
+                created_at=now,
+                updated_at=now,
+                version=1,
+            )
+
+        self._storage[entry_key] = self._clone(updated)
+        return self._clone(updated)
+
+    async def delete(self, table_name: str, key: str) -> bool:
+        """删除档案式记忆条目"""
+        entry_key = (table_name, key)
+        if entry_key in self._storage:
+            del self._storage[entry_key]
+            return True
+        return False
+
+    async def exists(self, table_name: str, key: str) -> bool:
+        """检查档案式记忆条目是否存在"""
+        return (table_name, key) in self._storage
+
+    async def list(
+        self,
+        table_name: str,
+        *,
+        tags: Optional[list[str]] = None,
+        key_query: Optional[str] = None,
+        value_query: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ArchiveMemory]:
+        """列出符合条件的档案式记忆条目"""
+        rows = [
+            self._clone(entry)
+            for (stored_table_name, _), entry in self._storage.items()
+            if stored_table_name == table_name
+        ]
+
+        if tags:
+            rows = [row for row in rows if all(tag in row.tags for tag in tags)]
+        if key_query:
+            lowered_key_query = key_query.lower()
+            rows = [row for row in rows if lowered_key_query in row.key.lower()]
+        if value_query:
+            lowered_value_query = value_query.lower()
+            rows = [row for row in rows if lowered_value_query in row.value.lower()]
+
+        rows.sort(key=lambda row: (row.updated_at, row.id), reverse=True)
+        return rows[offset : offset + limit]
+
+    # Type check: ensure class implements the protocol
+    def __init_subclass__(cls) -> None:
+        super().__init_subclass__()
+        # Verify that this class implements the ArchiveMemoryAccess protocol
+        if not issubclass(cls, ArchiveMemoryAccess):  # type: ignore
+            raise TypeError(f"{cls.__name__} does not implement ArchiveMemoryAccess protocol")
+
+    @staticmethod
+    def _clone(entry: ArchiveMemory) -> ArchiveMemory:
+        return ArchiveMemory(
+            id=entry.id,
+            table_name=entry.table_name,
+            key=entry.key,
+            value=entry.value,
+            tags=entry.tags.copy(),
+            created_at=entry.created_at,
+            updated_at=entry.updated_at,
+            version=entry.version,
+        )
+
+
+class InMemoryImageAnalysisAccess:
+    """In-memory image analysis cache for tests and standalone runs."""
+
+    def __init__(self) -> None:
+        self._storage: dict[str, ImageAnalysis] = {}
+        self._id_counter = 0
+
+    async def get(self, file_hash: str) -> Optional[ImageAnalysis]:
+        entry = self._storage.get(file_hash)
+        if entry is None:
+            return None
+        return self._clone(entry)
+
+    async def set(
+        self,
+        file_hash: str,
+        *,
+        source: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        original_width: Optional[int] = None,
+        original_height: Optional[int] = None,
+        processed_width: Optional[int] = None,
+        processed_height: Optional[int] = None,
+        analysis_text: Optional[str] = None,
+    ) -> ImageAnalysis:
+        if file_hash in self._storage:
+            existing = self._storage[file_hash]
+            updated = ImageAnalysis(
+                id=existing.id,
+                file_hash=file_hash,
+                source=source if source is not None else existing.source,
+                mime_type=mime_type if mime_type is not None else existing.mime_type,
+                original_width=original_width if original_width is not None else existing.original_width,
+                original_height=original_height if original_height is not None else existing.original_height,
+                processed_width=processed_width if processed_width is not None else existing.processed_width,
+                processed_height=processed_height if processed_height is not None else existing.processed_height,
+                analysis_text=analysis_text if analysis_text is not None else existing.analysis_text,
+                created_at=existing.created_at,
+                updated_at=now_utc(),
+                version=existing.version + 1,
+            )
+        else:
+            self._id_counter += 1
+            now = now_utc()
+            updated = ImageAnalysis(
+                id=self._id_counter,
+                file_hash=file_hash,
+                source=source,
+                mime_type=mime_type,
+                original_width=original_width,
+                original_height=original_height,
+                processed_width=processed_width,
+                processed_height=processed_height,
+                analysis_text=analysis_text,
+                created_at=now,
+                updated_at=now,
+                version=1,
+            )
+
+        self._storage[file_hash] = self._clone(updated)
+        return self._clone(updated)
+
+    async def delete(self, file_hash: str) -> bool:
+        if file_hash in self._storage:
+            del self._storage[file_hash]
+            return True
+        return False
+
+    async def exists(self, file_hash: str) -> bool:
+        return file_hash in self._storage
+
+    async def list(
+        self,
+        *,
+        source_query: Optional[str] = None,
+        has_analysis_text: Optional[bool] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ImageAnalysis]:
+        rows = [self._clone(entry) for entry in self._storage.values()]
+
+        if source_query:
+            lowered = source_query.lower()
+            rows = [row for row in rows if row.source and lowered in row.source.lower()]
+        if has_analysis_text is True:
+            rows = [row for row in rows if row.analysis_text]
+        elif has_analysis_text is False:
+            rows = [row for row in rows if not row.analysis_text]
+
+        rows.sort(key=lambda row: (row.updated_at, row.id), reverse=True)
+        return rows[offset : offset + limit]
+
+    def __init_subclass__(cls) -> None:
+        super().__init_subclass__()
+        if not issubclass(cls, ImageAnalysisAccess):  # type: ignore[arg-type]
+            raise TypeError(f"{cls.__name__} does not implement ImageAnalysisAccess protocol")
+
+    @staticmethod
+    def _clone(entry: ImageAnalysis) -> ImageAnalysis:
+        return ImageAnalysis(
+            id=entry.id,
+            file_hash=entry.file_hash,
+            source=entry.source,
+            mime_type=entry.mime_type,
+            original_width=entry.original_width,
+            original_height=entry.original_height,
+            processed_width=entry.processed_width,
+            processed_height=entry.processed_height,
+            analysis_text=entry.analysis_text,
+            created_at=entry.created_at,
+            updated_at=entry.updated_at,
+            version=entry.version,
+        )

neobot_memory-1.0.0a6/src/neobot_memory/image_service.py

@@ -0,0 +1,92 @@
+"""Image analysis cache service."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from neobot_contracts.models.memory import ImageAnalysis
+from neobot_contracts.ports.logging import Logger
+from neobot_contracts.ports.unit_of_work import UnitOfWorkFactory
+
+
+class ImageAnalysisService:
+    """Service for cached image analysis CRUD and lookup operations."""
+
+    def __init__(self, uow_factory: UnitOfWorkFactory, logger: Logger) -> None:
+        self._uow_factory = uow_factory
+        self._logger = logger
+
+    async def get(self, file_hash: str) -> Optional[ImageAnalysis]:
+        async with self._uow_factory() as uow:
+            item = await uow.images.get(file_hash)
+        self._logger.debug("图像分析已获取", file_hash=file_hash, found=item is not None)
+        return item
+
+    async def exists(self, file_hash: str) -> bool:
+        async with self._uow_factory() as uow:
+            exists = await uow.images.exists(file_hash)
+        self._logger.debug("图像分析存在检查", file_hash=file_hash, exists=exists)
+        return exists
+
+    async def list(
+        self,
+        *,
+        source_query: Optional[str] = None,
+        has_analysis_text: Optional[bool] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ImageAnalysis]:
+        async with self._uow_factory() as uow:
+            items = await uow.images.list(
+                source_query=source_query,
+                has_analysis_text=has_analysis_text,
+                limit=limit,
+                offset=offset,
+            )
+        self._logger.debug(
+            "图像分析列表已获取",
+            count=len(items),
+            limit=limit,
+            offset=offset,
+            has_analysis_text=has_analysis_text,
+        )
+        return items
+
+    async def set(
+        self,
+        file_hash: str,
+        *,
+        source: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        original_width: Optional[int] = None,
+        original_height: Optional[int] = None,
+        processed_width: Optional[int] = None,
+        processed_height: Optional[int] = None,
+        analysis_text: Optional[str] = None,
+    ) -> ImageAnalysis:
+        async with self._uow_factory() as uow:
+            item = await uow.images.set(
+                file_hash,
+                source=source,
+                mime_type=mime_type,
+                original_width=original_width,
+                original_height=original_height,
+                processed_width=processed_width,
+                processed_height=processed_height,
+                analysis_text=analysis_text,
+            )
+            await uow.commit()
+        self._logger.debug(
+            "图像分析已保存",
+            file_hash=file_hash,
+            version=item.version,
+        )
+        return item
+
+    async def delete(self, file_hash: str) -> bool:
+        async with self._uow_factory() as uow:
+            deleted = await uow.images.delete(file_hash)
+            if deleted:
+                await uow.commit()
+        self._logger.debug("图像分析已删除", file_hash=file_hash, deleted=deleted)
+        return deleted

neobot_memory-1.0.0a6/src/neobot_memory/reader.py

@@ -0,0 +1,13 @@
+"""MemoryReader Protocol — 记忆读取抽象"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class MemoryReader(Protocol):
+    """记忆读取接口，MemoryService 结构性满足此接口"""
+
+    async def recall(
+        self, conversation_id: str, query: str, limit: int = 5
+    ) -> list[str]: ...

neobot_memory-1.0.0a6/src/neobot_memory/service.py

@@ -0,0 +1,46 @@
+"""MemoryService — 记忆读写服务"""
+
+from __future__ import annotations
+
+from neobot_contracts.models import ConversationRef, MemoryRecord
+from neobot_contracts.ports.clock import Clock
+from neobot_contracts.ports.logging import Logger
+from neobot_contracts.ports.repository import MemoryRepository
+
+
+class MemoryService:
+    """记忆服务，负责存储和检索记忆条目"""
+
+    def __init__(
+        self,
+        repository: MemoryRepository,
+        logger: Logger,
+        clock: Clock,
+    ) -> None:
+        self._repository = repository
+        self._logger = logger
+        self._clock = clock
+
+    async def remember(
+        self, conversation_id: str, speaker_id: str, content: str
+    ) -> None:
+        record = MemoryRecord(
+            conversation=ConversationRef(kind="private", id=conversation_id),
+            speaker_id=speaker_id,
+            content=content,
+            created_at=self._clock.now(),
+        )
+        await self._repository.save(record)
+        self._logger.debug("短期记忆已保存", conversation_id=conversation_id, speaker_id=speaker_id)
+
+    async def recall(
+        self, conversation_id: str, query: str, limit: int = 5
+    ) -> list[str]:
+        ref = ConversationRef(kind="private", id=conversation_id)
+        records = await self._repository.search(ref, query, limit)
+        self._logger.debug(
+            "memory recalled",
+            conversation_id=conversation_id,
+            count=len(records),
+        )
+        return [r.content for r in records]