zero-agent-core 0.2.0__py3-none-any.whl

agent_core/ports/model_selection.py

@@ -0,0 +1,64 @@
+"""模型选择值对象与存储端口。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol
+
+ModelSelectionScope = Literal["user", "tenant"]
+
+
+@dataclass(frozen=True)
+class ModelSelection:
+    """一个按用户或租户保存的模型选择。"""
+
+    provider: str
+    model: str
+    scope: ModelSelectionScope
+    user_id: str | None = None
+    tenant_id: str | None = None
+    version: int = 1
+    updated_at: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "provider": self.provider,
+            "model": self.model,
+            "scope": self.scope,
+            "user_id": self.user_id,
+            "tenant_id": self.tenant_id,
+            "version": self.version,
+            "updated_at": self.updated_at,
+        }
+
+
+class ModelSelectionStore(Protocol):
+    """按用户优先、租户其次保存和解析模型选择。"""
+
+    async def resolve(
+        self,
+        *,
+        user_id: str | None,
+        tenant_id: str | None,
+    ) -> ModelSelection | None: ...
+
+    async def save(
+        self,
+        provider: str,
+        model: str,
+        *,
+        scope: ModelSelectionScope,
+        user_id: str | None,
+        tenant_id: str | None,
+    ) -> ModelSelection: ...
+
+    async def clear(
+        self,
+        *,
+        scope: ModelSelectionScope,
+        user_id: str | None,
+        tenant_id: str | None,
+    ) -> None: ...
+
+
+__all__ = ["ModelSelection", "ModelSelectionScope", "ModelSelectionStore"]

agent_core/ports/storage.py

@@ -0,0 +1,114 @@
+"""Agent Core 的可替换存储端口。
+
+协议描述运行时需要的最小能力；内置 SQLite/PostgreSQL 实现位于
+``agent_core.storage``，Redis 或业务自己的存储也可以实现这些协议。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Protocol
+
+from agent_core.access import AccessContext
+from agent_core.protocol.messages import Message
+from agent_core.protocol.runtime import ApprovalRecord, RunContext, RunEvent
+
+
+class ApprovalStore(Protocol):
+    """审批记录持久化协议。"""
+
+    async def save_approval(self, approval: ApprovalRecord) -> None: ...
+
+    async def load_approval(self, approval_id: str) -> ApprovalRecord | None: ...
+
+    async def transition_approval(
+        self,
+        approval: ApprovalRecord,
+        *,
+        expected_status: str = "pending",
+    ) -> bool:
+        """仅当记录仍处于预期状态时保存新状态。"""
+        ...
+
+
+class RunStore(Protocol):
+    """运行实例持久化协议。
+
+    实现应按 ``RunContext`` 中的 tenant/user/thread 作用域隔离数据，并在保存时
+    处理版本冲突和幂等键。Core 只要求最小的读取、保存和恢复能力。
+    """
+
+    async def save_run(self, context: RunContext) -> None:
+        """保存运行上下文。实现可以在这里递增并回写 ``context.version``。"""
+        ...
+
+    async def load_run(self, thread_id: str, run_id: str) -> RunContext | None:
+        """按会话和运行 ID读取运行上下文。"""
+        ...
+
+    async def find_run_by_idempotency(
+        self,
+        tenant_id: str | None,
+        user_id: str | None,
+        idempotency_key: str,
+    ) -> RunContext | None:
+        """查找同一作用域内已经存在的幂等请求。"""
+        ...
+
+
+class SessionStore(Protocol):
+    """对话消息历史存储协议。"""
+
+    async def load_messages(
+        self, thread_id: str, *, access: AccessContext | None = None
+    ) -> list[Message]: ...
+
+    async def append_messages(
+        self,
+        thread_id: str,
+        messages: Sequence[Message],
+        *,
+        access: AccessContext | None = None,
+    ) -> None: ...
+
+    async def replace_messages(
+        self,
+        thread_id: str,
+        messages: Sequence[Message],
+        *,
+        access: AccessContext | None = None,
+    ) -> None: ...
+
+    async def delete_thread(self, thread_id: str, *, access: AccessContext | None = None) -> None: ...
+
+    async def list_threads(self, *, access: AccessContext | None = None) -> list[str]: ...
+
+
+class ContextStore(Protocol):
+    """结构化长期上下文存储协议。"""
+
+    async def get_context(self, thread_id: str, *, access: AccessContext | None = None) -> dict[str, Any]: ...
+
+    async def update_context(
+        self,
+        thread_id: str,
+        values: dict[str, Any],
+        *,
+        access: AccessContext | None = None,
+    ) -> dict[str, Any]: ...
+
+    async def clear_context(self, thread_id: str, *, access: AccessContext | None = None) -> None: ...
+
+
+class WorkflowStore(Protocol):
+    """工作流执行实例存储协议。"""
+
+    async def save_execution(self, execution: Any) -> None: ...
+
+    async def load_execution(self, execution_id: str) -> Any | None: ...
+
+
+class EventSink(Protocol):
+    """运行事件发布协议，可接 SSE、WebSocket、日志或消息队列。"""
+
+    async def publish(self, event: RunEvent) -> None: ...

agent_core/prompts/__init__.py

@@ -0,0 +1,19 @@
+"""提示词注册和版本管理公共导出。"""
+
+from agent_core.prompts.registry import PromptEntry, PromptRegistry, PromptVersion
+from agent_core.prompts.templates import (
+    ChatPromptTemplate,
+    MessagesPlaceholder,
+    MessageTemplate,
+    PromptTemplate,
+)
+
+__all__ = [
+    "ChatPromptTemplate",
+    "MessageTemplate",
+    "MessagesPlaceholder",
+    "PromptEntry",
+    "PromptRegistry",
+    "PromptTemplate",
+    "PromptVersion",
+]

agent_core/prompts/registry.py

@@ -0,0 +1,236 @@
+"""与业务无关的提示词版本注册表。
+
+Core 只负责提示词的版本、渲染、回滚和 JSON 文件持久化；具体 Agent 的默认
+提示词由应用包注册，避免把某个业务领域的文案带入公共框架。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from agent_core.prompts.templates import PromptTemplate
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PromptVersion:
+    """单个提示词版本。"""
+
+    version: int
+    content: str
+    description: str
+    defaults: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    @property
+    def variables(self) -> tuple[str, ...]:
+        """返回模板声明的变量。"""
+
+        return PromptTemplate(self.content, defaults=self.defaults).variables
+
+    def render(self, **kwargs: Any) -> str:
+        """使用 ``str.format`` 渲染模板变量。"""
+        return PromptTemplate(self.content, defaults=self.defaults).render(**kwargs)
+
+
+@dataclass
+class PromptEntry:
+    """一个提示词的全部版本。"""
+
+    name: str
+    current_version: int
+    versions: list[PromptVersion] = field(default_factory=list)
+
+    @property
+    def current(self) -> PromptVersion:
+        for version in self.versions:
+            if version.version == self.current_version:
+                return version
+        raise ValueError(f"找不到版本 {self.current_version}")
+
+    def get_version(self, version: int) -> PromptVersion | None:
+        return next((item for item in self.versions if item.version == version), None)
+
+
+class PromptRegistry:
+    """支持版本管理和文件持久化的提示词注册表。"""
+
+    def __init__(self, storage_path: str | Path = "./prompts.json") -> None:
+        self._path = Path(storage_path)
+        self._entries: dict[str, PromptEntry] = {}
+        self._load()
+
+    def register(
+        self,
+        name: str,
+        content: str,
+        description: str = "",
+        *,
+        defaults: dict[str, Any] | None = None,
+    ) -> PromptVersion:
+        """注册提示词；同名提示词会创建新版本。"""
+        if name in self._entries:
+            return self.update(name, content, description=description, defaults=defaults)
+        version = PromptVersion(
+            version=1,
+            content=content,
+            description=description,
+            defaults=dict(defaults or {}),
+        )
+        self._entries[name] = PromptEntry(name=name, current_version=1, versions=[version])
+        self._save()
+        logger.info("[Prompt] 注册：%s v1", name)
+        return version
+
+    def update(
+        self,
+        name: str,
+        content: str,
+        description: str = "",
+        *,
+        defaults: dict[str, Any] | None = None,
+    ) -> PromptVersion:
+        """创建同一提示词的新版本并切换为当前版本。"""
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(f"提示词不存在：{name}，请先调用 register()")
+        version = PromptVersion(
+            version=max(item.version for item in entry.versions) + 1,
+            content=content,
+            description=description,
+            defaults=dict(defaults or {}),
+        )
+        entry.versions.append(version)
+        entry.current_version = version.version
+        self._save()
+        logger.info("[Prompt] 更新：%s v%d", name, version.version)
+        return version
+
+    def rollback(self, name: str, version: int) -> PromptVersion:
+        """切换到已有版本，不删除版本历史。"""
+        entry = self._get_entry(name)
+        target = entry.get_version(version)
+        if target is None:
+            raise KeyError(f"提示词 {name} 不存在版本 {version}")
+        entry.current_version = version
+        self._save()
+        logger.info("[Prompt] 回滚：%s -> v%d", name, version)
+        return target
+
+    def render(self, prompt_name: str, **kwargs: Any) -> str:
+        """渲染当前版本。"""
+        return self._get_entry(prompt_name).current.render(**kwargs)
+
+    def get(self, prompt_name: str) -> str:
+        """读取当前版本的原始模板。"""
+        return self._get_entry(prompt_name).current.content
+
+    def get_history(self, prompt_name: str) -> list[dict[str, Any]]:
+        """返回版本历史摘要。"""
+        entry = self._get_entry(prompt_name)
+        return [
+            {
+                "version": item.version,
+                "description": item.description,
+                "created_at": item.created_at,
+                "variables": list(item.variables),
+                "is_current": item.version == entry.current_version,
+                "content_preview": item.content[:100] + "..." if len(item.content) > 100 else item.content,
+            }
+            for item in entry.versions
+        ]
+
+    def list_prompts(self) -> list[str]:
+        """列出已注册的提示词名称。"""
+        return list(self._entries)
+
+    def delete(self, name: str) -> bool:
+        """删除提示词及其历史。"""
+        if name not in self._entries:
+            return False
+        del self._entries[name]
+        self._save()
+        logger.info("[Prompt] 删除：%s", name)
+        return True
+
+    def _save(self) -> None:
+        data = {
+            name: {
+                "name": entry.name,
+                "current_version": entry.current_version,
+                "versions": [
+                    {
+                        "version": item.version,
+                        "content": item.content,
+                        "description": item.description,
+                        "defaults": item.defaults,
+                        "created_at": item.created_at,
+                    }
+                    for item in entry.versions
+                ],
+            }
+            for name, entry in self._entries.items()
+        }
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        temporary_path: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                dir=self._path.parent,
+                prefix=f".{self._path.name}.",
+                suffix=".tmp",
+                delete=False,
+            ) as temporary:
+                temporary_path = Path(temporary.name)
+                json.dump(data, temporary, ensure_ascii=False, indent=2)
+                temporary.flush()
+                os.fsync(temporary.fileno())
+            os.replace(temporary_path, self._path)
+        finally:
+            if temporary_path is not None and temporary_path.exists():
+                temporary_path.unlink(missing_ok=True)
+
+    def _load(self) -> None:
+        if not self._path.exists():
+            return
+        data = json.loads(self._path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            raise ValueError(f"提示词注册表根节点必须是对象：{self._path}")
+        loaded: dict[str, PromptEntry] = {}
+        for name, raw in data.items():
+            versions = [
+                PromptVersion(
+                    version=item["version"],
+                    content=item["content"],
+                    description=item.get("description", ""),
+                    defaults=dict(item.get("defaults") or {}),
+                    created_at=item.get("created_at", ""),
+                )
+                for item in raw["versions"]
+            ]
+            loaded[name] = PromptEntry(
+                name=raw.get("name", name),
+                current_version=raw["current_version"],
+                versions=versions,
+            )
+        # 全量解析成功后再替换内存状态，损坏文件不会变成“空注册表”。
+        self._entries = loaded
+        logger.info("[Prompt] 从文件加载 %d 个提示词：%s", len(self._entries), self._path)
+
+    def _get_entry(self, name: str) -> PromptEntry:
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(f"提示词不存在：{name}")
+        return entry
+
+
+__all__ = ["PromptEntry", "PromptRegistry", "PromptVersion"]

agent_core/prompts/templates.py

@@ -0,0 +1,166 @@
+"""轻量、安全且不依赖第三方模板引擎的 Prompt 模板。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from string import Formatter
+from typing import Any, Literal
+
+from agent_core.protocol.messages import Message
+
+
+class _SafeFormatter(Formatter):
+    """只允许简单变量名，禁止属性和下标访问。"""
+
+    def variables(self, template: str) -> tuple[str, ...]:
+        values: list[str] = []
+        try:
+            parts = list(self.parse(template))
+        except ValueError as exc:
+            raise ValueError(f"Prompt 模板语法错误：{exc}") from exc
+        for _literal, name, format_spec, _conversion in parts:
+            if name is None:
+                continue
+            if not name.isidentifier() or "." in name or "[" in name or "]" in name:
+                raise ValueError(f"Prompt 模板只允许简单变量名：{name!r}")
+            if format_spec and ("{" in format_spec or "}" in format_spec):
+                raise ValueError("Prompt 模板的格式说明不允许嵌套变量")
+            if name not in values:
+                values.append(name)
+        return tuple(values)
+
+
+_FORMATTER = _SafeFormatter()
+
+
+@dataclass(frozen=True)
+class PromptTemplate:
+    """单段文本模板，支持默认变量和 partial。"""
+
+    content: str
+    defaults: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        variables = set(self.variables)
+        unknown_defaults = set(self.defaults) - variables
+        if unknown_defaults:
+            raise ValueError(f"默认变量未在模板中声明：{sorted(unknown_defaults)}")
+
+    @property
+    def variables(self) -> tuple[str, ...]:
+        return _FORMATTER.variables(self.content)
+
+    @property
+    def required_variables(self) -> tuple[str, ...]:
+        return tuple(name for name in self.variables if name not in self.defaults)
+
+    def render(self, **kwargs: Any) -> str:
+        values = {**self.defaults, **kwargs}
+        missing = [name for name in self.required_variables if name not in values]
+        if missing:
+            raise ValueError(f"Prompt 模板变量缺失：{', '.join(missing)}")
+        try:
+            return _FORMATTER.vformat(self.content, (), values)
+        except (KeyError, ValueError) as exc:
+            raise ValueError(f"Prompt 模板渲染失败：{exc}") from exc
+
+    def partial(self, **kwargs: Any) -> PromptTemplate:
+        unknown = set(kwargs) - set(self.variables)
+        if unknown:
+            raise ValueError(f"partial 包含未声明变量：{sorted(unknown)}")
+        return PromptTemplate(self.content, defaults={**self.defaults, **kwargs})
+
+
+@dataclass(frozen=True)
+class MessageTemplate:
+    """一条带角色的消息模板。"""
+
+    role: Literal["system", "user", "assistant", "tool"]
+    template: PromptTemplate | str
+    name: str | None = None
+
+    def render(self, **kwargs: Any) -> Message:
+        template = (
+            self.template if isinstance(self.template, PromptTemplate) else PromptTemplate(self.template)
+        )
+        return Message(role=self.role, content=template.render(**kwargs), name=self.name)
+
+
+@dataclass(frozen=True)
+class MessagesPlaceholder:
+    """在聊天模板中插入一段已经构造好的消息列表。"""
+
+    variable_name: str
+    optional: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.variable_name.strip():
+            raise ValueError("MessagesPlaceholder 变量名不能为空")
+
+
+@dataclass(frozen=True)
+class ChatPromptTemplate:
+    """由消息模板和消息占位符组成的聊天 Prompt。"""
+
+    parts: tuple[MessageTemplate | MessagesPlaceholder, ...]
+    defaults: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_messages(
+        cls,
+        parts: list[
+            MessageTemplate | MessagesPlaceholder | tuple[Literal["system", "user", "assistant", "tool"], str]
+        ],
+    ) -> ChatPromptTemplate:
+        normalized: list[MessageTemplate | MessagesPlaceholder] = []
+        for part in parts:
+            if isinstance(part, tuple):
+                normalized.append(MessageTemplate(role=part[0], template=part[1]))
+            else:
+                normalized.append(part)
+        return cls(tuple(normalized))
+
+    @property
+    def variables(self) -> tuple[str, ...]:
+        names: list[str] = []
+        for part in self.parts:
+            values: tuple[str, ...]
+            if isinstance(part, MessagesPlaceholder):
+                values = (part.variable_name,)
+            else:
+                template = (
+                    part.template
+                    if isinstance(part.template, PromptTemplate)
+                    else PromptTemplate(part.template)
+                )
+                values = template.variables
+            for name in values:
+                if name not in names:
+                    names.append(name)
+        return tuple(names)
+
+    def partial(self, **kwargs: Any) -> ChatPromptTemplate:
+        unknown = set(kwargs) - set(self.variables)
+        if unknown:
+            raise ValueError(f"partial 包含未声明变量：{sorted(unknown)}")
+        return ChatPromptTemplate(self.parts, defaults={**self.defaults, **kwargs})
+
+    def render(self, **kwargs: Any) -> list[Message]:
+        values = {**self.defaults, **kwargs}
+        messages: list[Message] = []
+        for part in self.parts:
+            if isinstance(part, MessagesPlaceholder):
+                if part.variable_name not in values:
+                    if part.optional:
+                        continue
+                    raise ValueError(f"消息占位符变量缺失：{part.variable_name}")
+                inserted = values[part.variable_name]
+                if not isinstance(inserted, list) or not all(isinstance(item, Message) for item in inserted):
+                    raise TypeError(f"消息占位符 {part.variable_name} 必须是 list[Message]")
+                messages.extend(inserted)
+                continue
+            messages.append(part.render(**values))
+        return messages
+
+
+__all__ = ["ChatPromptTemplate", "MessageTemplate", "MessagesPlaceholder", "PromptTemplate"]

agent_core/protocol/__init__.py

@@ -0,0 +1,31 @@
+"""Agent Core 公共协议。"""
+
+from agent_core.protocol.capabilities import AgentCapabilities
+from agent_core.protocol.messages import (
+    Message,
+    assistant_message,
+    system_message,
+    tool_message,
+    user_message,
+)
+from agent_core.protocol.runtime import (
+    ApprovalRecord,
+    RunContext,
+    RunEvent,
+    RunStatus,
+    ToolResult,
+)
+
+__all__ = [
+    "AgentCapabilities",
+    "ApprovalRecord",
+    "Message",
+    "RunContext",
+    "RunEvent",
+    "RunStatus",
+    "ToolResult",
+    "assistant_message",
+    "system_message",
+    "tool_message",
+    "user_message",
+]

agent_core/protocol/capabilities.py

@@ -0,0 +1,49 @@
+"""Agent HTTP 能力协议。
+
+能力声明放在 Core 的协议层，Web API 只负责把它序列化返回。
+这样前端可以先探测能力，再决定是否使用流式输出、审批、恢复和事件接口。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AgentCapabilities:
+    """一个 Agent 服务对外暴露的通用运行能力。"""
+
+    protocol_version: str = "1.0"
+    agent_id: str = "agent"
+    runtime: str = "agent-core"
+    transports: tuple[str, ...] = ("http",)
+    features: frozenset[str] = field(
+        default_factory=lambda: frozenset(
+            {
+                "threads",
+                "runs",
+                "run_events",
+                "run_stream",
+                "run_cancel",
+                "run_resume",
+                "checkpoint_recovery",
+                "approval",
+                "client_actions",
+                "context_usage",
+            }
+        )
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """返回稳定的 JSON 字段，供 HTTP 层直接使用。"""
+        return {
+            "protocol_version": self.protocol_version,
+            "agent_id": self.agent_id,
+            "runtime": self.runtime,
+            "transports": list(self.transports),
+            "features": sorted(self.features),
+        }
+
+
+__all__ = ["AgentCapabilities"]