neobot-contracts 1.0.0__tar.gz

neobot_contracts-1.0.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: neobot-contracts
+Version: 1.0.0
+Summary: Cross-module domain models and port interfaces for NeoBot
+Author: wsrsq, tangtian
+Author-email: wsrsq <wsrsq001@163.com>, tangtian <a14b@126.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# neobot-contracts
+
+Cross-module domain models and port interfaces for NeoBot.

neobot_contracts-1.0.0/README.md

@@ -0,0 +1,3 @@
+# neobot-contracts
+
+Cross-module domain models and port interfaces for NeoBot.

neobot_contracts-1.0.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "neobot-contracts"
+version = "1.0.0"
+description = "Cross-module domain models and port interfaces for NeoBot"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[[project.authors]]
+name = "wsrsq"
+email = "wsrsq001@163.com"
+
+[[project.authors]]
+name = "tangtian"
+email = "a14b@126.com"
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_contracts-1.0.0/pyproject.toml.orig

@@ -0,0 +1,15 @@
+[project]
+name = "neobot-contracts"
+version = "1.0.0"
+description = "Cross-module domain models and port interfaces for NeoBot"
+readme = "README.md"
+authors = [
+    { name = "wsrsq", email = "wsrsq001@163.com" },
+    { name = "tangtian", email = "a14b@126.com" },
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_contracts-1.0.0/src/neobot_contracts/__init__.py

@@ -0,0 +1,9 @@
+"""NeoBot 跨模块共享的领域模型与 Port 接口"""
+
+from neobot_contracts.errors import NeoBotError
+from neobot_contracts.events import DomainEvent
+
+__all__ = [
+    "NeoBotError",
+    "DomainEvent",
+]

neobot_contracts-1.0.0/src/neobot_contracts/errors.py

@@ -0,0 +1,5 @@
+"""跨模块错误基类"""
+
+
+class NeoBotError(Exception):
+    """NeoBot 所有自定义异常的基类"""

neobot_contracts-1.0.0/src/neobot_contracts/events.py

@@ -0,0 +1,13 @@
+"""领域事件基类（预留）"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class DomainEvent:
+    """所有领域事件的基类"""
+
+    occurred_at: datetime

neobot_contracts-1.0.0/src/neobot_contracts/models/__init__.py

@@ -0,0 +1,34 @@
+"""领域模型"""
+
+from __future__ import annotations
+
+from neobot_contracts.models.base import ConversationRef, IncomingMessage, MemoryRecord
+from neobot_contracts.models.memory import (
+    ArchiveMemory,
+    CreatorImageRecord,
+    ImageAnalysis,
+    TopicNode,
+)
+from neobot_contracts.models.scheduled_task import (
+    CompletedScheduledTaskRecord,
+    ScheduledTaskRecord,
+    ScheduledTaskRecurrence,
+    ScheduledTaskState,
+)
+from neobot_contracts.models.trigger import KeywordConfig, TriggerResult
+
+__all__ = [
+    "ConversationRef",
+    "IncomingMessage",
+    "MemoryRecord",
+    "ArchiveMemory",
+    "CreatorImageRecord",
+    "ImageAnalysis",
+    "TopicNode",
+    "CompletedScheduledTaskRecord",
+    "ScheduledTaskRecord",
+    "ScheduledTaskRecurrence",
+    "ScheduledTaskState",
+    "KeywordConfig",
+    "TriggerResult",
+]

neobot_contracts-1.0.0/src/neobot_contracts/models/base.py

@@ -0,0 +1,38 @@
+"""基础模型"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal
+
+
+@dataclass(frozen=True, slots=True)
+class ConversationRef:
+    """会话引用，标识一个私聊或群聊"""
+
+    kind: Literal["private", "group"]
+    id: str
+
+
+@dataclass(frozen=True, slots=True)
+class IncomingMessage:
+    """从适配器接收到的消息，与协议无关的统一表示"""
+
+    event_id: str
+    conversation: ConversationRef
+    sender_id: str
+    sender_name: str
+    text: str
+    occurred_at: datetime
+    raw_payload: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryRecord:
+    """记忆条目"""
+
+    conversation: ConversationRef
+    speaker_id: str
+    content: str
+    created_at: datetime

neobot_contracts-1.0.0/src/neobot_contracts/models/memory.py

@@ -0,0 +1,102 @@
+"""记忆模型"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class TopicNodeType(str, Enum):
+    """话题节点类型"""
+
+    RAW = "raw"
+    SUMMARY = "summary"
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveMemory:
+    """档案式记忆"""
+
+    id: int
+    table_name: str  # 表名，用于区分不同类别的记忆
+    key: str  # 键名，在表内唯一标识一个条目
+    value: str
+    tags: list[str]
+    created_at: datetime
+    updated_at: datetime
+    version: int
+
+
+@dataclass(frozen=True, slots=True)
+class TopicNode:
+    """话题向量树节点"""
+
+    id: int
+    title: str
+    content: str
+    embedding: list[float]
+    node_type: TopicNodeType
+    tags: list[str]
+    parent_id: int | None
+    children_ids: list[int]
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class ImageAnalysis:
+    """缓存的图片分析元数据与文本结果。"""
+
+    id: int
+    file_hash: str
+    source: str | None
+    mime_type: str | None
+    original_width: int | None
+    original_height: int | None
+    processed_width: int | None
+    processed_height: int | None
+    analysis_text: str | None
+    created_at: datetime
+    updated_at: datetime
+    version: int
+
+
+@dataclass(frozen=True, slots=True)
+class EmojiRecord:
+    """表情包记录 — 解析后的表情包图片元数据与描述"""
+
+    id: int
+    file_hash: str
+    file_name: str
+    file_path: str
+    mime_type: str | None
+    original_width: int | None
+    original_height: int | None
+    analysis_text: str | None
+    use_count: int
+    created_at: datetime
+    updated_at: datetime
+    version: int
+    image_source: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CreatorImageRecord:
+    """Creator Agent 图片元数据。"""
+
+    id: int
+    image_id: str
+    source: str
+    file_hash: str
+    file_path: str
+    prompt: str | None
+    description: str | None
+    mime_type: str | None
+    original_width: int | None
+    original_height: int | None
+    created_at: datetime
+    updated_at: datetime
+    version: int
+    image_source: str | None = None
+    #: 图库固定编号（只在入库时分配一次，不随排序/更新变化）；非图库记录为 None
+    gallery_no: int | None = None

neobot_contracts-1.0.0/src/neobot_contracts/models/scheduled_task.py

@@ -0,0 +1,58 @@
+"""定时任务领域模型。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from neobot_contracts.models.base import ConversationRef
+from neobot_contracts.time_context import now_utc
+
+
+class ScheduledTaskRecurrence(StrEnum):
+    ONCE = "once"
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+    YEARLY = "yearly"
+
+
+class ScheduledTaskState(StrEnum):
+    ACTIVE = "active"
+    DISABLED = "disabled"
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledTaskRecord:
+    id: int
+    task_uuid: str
+    title: str
+    detail: str
+    recurrence: ScheduledTaskRecurrence
+    start_at: datetime
+    end_at: datetime
+    bindings: tuple[ConversationRef, ...]
+    metadata: dict[str, Any] = field(default_factory=dict)
+    completed_window_keys: tuple[str, ...] = ()
+    state: ScheduledTaskState = ScheduledTaskState.ACTIVE
+    created_at: datetime = field(default_factory=now_utc)
+    updated_at: datetime = field(default_factory=now_utc)
+    version: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class CompletedScheduledTaskRecord:
+    id: int
+    task_uuid: str
+    title: str
+    detail: str
+    recurrence: ScheduledTaskRecurrence
+    start_at: datetime
+    end_at: datetime
+    bindings: tuple[ConversationRef, ...]
+    metadata: dict[str, Any]
+    completed_at: datetime
+    completion_reason: str
+    archived_payload: dict[str, Any]

neobot_contracts-1.0.0/src/neobot_contracts/models/trigger.py

@@ -0,0 +1,22 @@
+"""触发器模型"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class KeywordConfig:
+    """关键词配置"""
+
+    keyword: str
+    weight: float
+
+
+@dataclass(frozen=True, slots=True)
+class TriggerResult:
+    """触发结果"""
+
+    should_reply: bool
+    probability: float
+    matched_keywords: list[str]

neobot_contracts-1.0.0/src/neobot_contracts/ports/__init__.py

@@ -0,0 +1,116 @@
+"""Port 接口集合"""
+
+from neobot_contracts.ports.logging import Logger, NullLogger
+from neobot_contracts.ports.output import CapturingOutput, NullOutput, OutputMessage, OutputPort
+from neobot_contracts.ports.runtime_event import RuntimeEnvelope, RuntimeInterceptionRegistry
+from neobot_contracts.ports.clock import Clock, SystemClock, now_utc
+from neobot_contracts.ports.event_source import EventSource, Subscription
+from neobot_contracts.ports.plugin import (
+    Plugin,
+    PluginCapability,
+    PluginHandle,
+    PluginLoader,
+    PluginManager,
+    PluginRegistry,
+    PluginState,
+    RuntimePluginContext,
+)
+from neobot_contracts.ports.repository import MemoryRepository, MessageRepository, ProfileRepository
+from neobot_contracts.ports.provider import Provider
+from neobot_contracts.ports.unit_of_work import UnitOfWork, UnitOfWorkFactory
+from neobot_contracts.ports.creator_image_access import CreatorImageAccess
+from neobot_contracts.ports.archive_memory_access import (
+    ArchiveMemoryAccess,
+    ArchiveMemoryAccessWrapper,
+    ensure_optional_str,
+    ensure_str,
+)
+from neobot_contracts.ports.image_analysis_access import ImageAnalysisAccess
+from neobot_contracts.ports.host import (
+    CapabilityRegistry,
+    CapabilitySpec,
+    CommandRegistry,
+    CommandSpec,
+    HostRuntimeFacade,
+    LifecycleHooks,
+    QueryRegistry,
+    QuerySpec,
+)
+from neobot_contracts.ports.scheduled_task_access import ScheduledTaskAccess
+from neobot_contracts.ports.sandbox import SandboxDataPort
+from neobot_contracts.ports.screenshot import (
+    FontFace,
+    FontFormat,
+    FontLoadError,
+    ImageFormat,
+    InvalidScreenshotOptions,
+    RenderOptions,
+    ScreenshotError,
+    ScreenshotMode,
+    ScreenshotOptions,
+    ScreenshotPort,
+    ScreenshotResult,
+    ScreenshotTargetNotFound,
+    ScreenshotTimeout,
+    ScreenshotUnavailable,
+)
+
+__all__ = [
+    "Logger",
+    "NullLogger",
+    "OutputMessage",
+    "OutputPort",
+    "NullOutput",
+    "CapturingOutput",
+    "RuntimeEnvelope",
+    "RuntimeInterceptionRegistry",
+    "Clock",
+    "SystemClock",
+    "now_utc",
+    "EventSource",
+    "Subscription",
+    "Plugin",
+    "PluginCapability",
+    "PluginHandle",
+    "PluginLoader",
+    "PluginManager",
+    "PluginRegistry",
+    "PluginState",
+    "RuntimePluginContext",
+    "MemoryRepository",
+    "MessageRepository",
+    "ProfileRepository",
+    "Provider",
+    "UnitOfWork",
+    "UnitOfWorkFactory",
+    "CreatorImageAccess",
+    "ArchiveMemoryAccess",
+    "ArchiveMemoryAccessWrapper",
+    "ensure_optional_str",
+    "ensure_str",
+    "ImageAnalysisAccess",
+    "ScheduledTaskAccess",
+    "CapabilityRegistry",
+    "CapabilitySpec",
+    "CommandRegistry",
+    "CommandSpec",
+    "HostRuntimeFacade",
+    "LifecycleHooks",
+    "QueryRegistry",
+    "QuerySpec",
+    "SandboxDataPort",
+    "FontFace",
+    "FontFormat",
+    "FontLoadError",
+    "ImageFormat",
+    "InvalidScreenshotOptions",
+    "RenderOptions",
+    "ScreenshotError",
+    "ScreenshotMode",
+    "ScreenshotOptions",
+    "ScreenshotPort",
+    "ScreenshotResult",
+    "ScreenshotTargetNotFound",
+    "ScreenshotTimeout",
+    "ScreenshotUnavailable",
+]

neobot_contracts-1.0.0/src/neobot_contracts/ports/archive_memory_access.py

@@ -0,0 +1,220 @@
+"""Archive Memory Access Port — 档案式记忆读写接口
+
+提供通过表名和键名获取和更新档案式记忆条目的函数接口。
+如果输入的表名或键名是 int、float、bool 等类型，会自动转换成 str。
+
+示例：
+    ```python
+    from neobot_contracts.ports import ArchiveMemoryAccess
+
+    class MyArchiveMemoryAccess(ArchiveMemoryAccess):
+        async def get(self, table_name: str, key: str):
+            # 实现获取逻辑
+            ...
+        # 其他方法...
+
+    # 使用包装器自动类型转换
+    from neobot_contracts.ports import ArchiveMemoryAccessWrapper, ensure_str
+
+    access = MyArchiveMemoryAccess()
+    wrapper = ArchiveMemoryAccessWrapper(access)
+
+    # 自动将整数键转换为字符串
+    memory = await wrapper.get("users", 123)
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Protocol, runtime_checkable, Union
+
+if TYPE_CHECKING:
+    from neobot_contracts.models.memory import ArchiveMemory
+
+
+@runtime_checkable
+class ArchiveMemoryAccess(Protocol):
+    """档案式记忆读写接口
+    
+    提供通过表名和键名获取和更新档案式记忆条目的功能。
+    如果输入的表名或键名是 int 等类型，会自动转换成 str。
+    """
+
+    async def get(
+        self, 
+        table_name: str, 
+        key: str
+    ) -> Optional[ArchiveMemory]:
+        """根据表名和键名获取档案式记忆条目
+        
+        Args:
+            table_name: 表名，用于区分不同类别的记忆
+            key: 键名，在表内唯一标识一个条目
+            
+        Returns:
+            如果找到则返回 ArchiveMemory 对象，否则返回 None
+        """
+        ...
+
+    async def set(
+        self,
+        table_name: str,
+        key: str,
+        value: str,
+        tags: list[str],
+    ) -> ArchiveMemory:
+        """创建或更新档案式记忆条目
+        
+        如果指定的表名和键名已存在，则更新该条目；
+        如果不存在，则创建新条目。
+        
+        Args:
+            table_name: 表名
+            key: 键名
+            value: 值
+            tags: 标签列表
+            
+        Returns:
+            创建或更新后的 ArchiveMemory 对象
+        """
+        ...
+
+    async def delete(
+        self,
+        table_name: str,
+        key: str,
+    ) -> bool:
+        """删除档案式记忆条目
+        
+        Args:
+            table_name: 表名
+            key: 键名
+            
+        Returns:
+            如果成功删除返回 True，如果条目不存在返回 False
+        """
+        ...
+
+    async def exists(
+        self,
+        table_name: str,
+        key: str,
+    ) -> bool:
+        """检查档案式记忆条目是否存在
+        
+        Args:
+            table_name: 表名
+            key: 键名
+            
+        Returns:
+            如果条目存在返回 True，否则返回 False
+        """
+        ...
+
+    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]:
+        """按条件列出给定表的档案式记忆条目"""
+        ...
+
+
+def ensure_str(value: Union[str, int, float, bool, None]) -> str:
+    """确保输入值为字符串类型
+    
+    如果输入值是 int、float、bool 等类型，会自动转换为 str。
+    如果输入值是 None，会抛出 ValueError。
+    
+    Args:
+        value: 输入值
+        
+    Returns:
+        字符串表示
+    """
+    if value is None:
+        raise ValueError("table_name and key cannot be None")
+    return str(value)
+
+
+def ensure_optional_str(value: Union[str, int, float, bool, None]) -> Optional[str]:
+    """确保输入值为可选字符串类型"""
+    if value is None:
+        return None
+    return str(value)
+
+
+class ArchiveMemoryAccessWrapper:
+    """ArchiveMemoryAccess 包装器，自动处理类型转换"""
+    
+    def __init__(self, access: ArchiveMemoryAccess):
+        self._access = access
+    
+    async def get(
+        self,
+        table_name: Union[str, int, float, bool, None],
+        key: Union[str, int, float, bool, None],
+    ) -> Optional[ArchiveMemory]:
+        """根据表名和键名获取档案式记忆条目（自动类型转换）"""
+        table_name_str = ensure_str(table_name)
+        key_str = ensure_str(key)
+        return await self._access.get(table_name_str, key_str)
+    
+    async def set(
+        self,
+        table_name: Union[str, int, float, bool, None],
+        key: Union[str, int, float, bool, None],
+        value: str,
+        tags: list[str],
+    ) -> ArchiveMemory:
+        """创建或更新档案式记忆条目（自动类型转换）"""
+        table_name_str = ensure_str(table_name)
+        key_str = ensure_str(key)
+        return await self._access.set(table_name_str, key_str, value, tags)
+    
+    async def delete(
+        self,
+        table_name: Union[str, int, float, bool, None],
+        key: Union[str, int, float, bool, None],
+    ) -> bool:
+        """删除档案式记忆条目（自动类型转换）"""
+        table_name_str = ensure_str(table_name)
+        key_str = ensure_str(key)
+        return await self._access.delete(table_name_str, key_str)
+    
+    async def exists(
+        self,
+        table_name: Union[str, int, float, bool, None],
+        key: Union[str, int, float, bool, None],
+    ) -> bool:
+        """检查档案式记忆条目是否存在（自动类型转换）"""
+        table_name_str = ensure_str(table_name)
+        key_str = ensure_str(key)
+        return await self._access.exists(table_name_str, key_str)
+
+    async def list(
+        self,
+        table_name: Union[str, int, float, bool, None],
+        *,
+        tags: Optional[list[Union[str, int, float, bool, None]]] = None,
+        key_query: Union[str, int, float, bool, None] = None,
+        value_query: Union[str, int, float, bool, None] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ArchiveMemory]:
+        """列出档案式记忆条目（自动类型转换）"""
+        table_name_str = ensure_str(table_name)
+        normalized_tags = [ensure_str(tag) for tag in tags] if tags is not None else None
+        return await self._access.list(
+            table_name_str,
+            tags=normalized_tags,
+            key_query=ensure_optional_str(key_query),
+            value_query=ensure_optional_str(value_query),
+            limit=limit,
+            offset=offset,
+        )