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

agent_core/protocol/messages.py

@@ -0,0 +1,100 @@
+"""手写消息类型定义。"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass
+class Message:
+    """基础消息类型。"""
+
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str
+    name: str | None = None
+    tool_call_id: str | None = None
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """转换为 Core 内部的提供商无关格式。"""
+        result: dict[str, Any] = {
+            "role": self.role,
+            "content": self.content,
+        }
+        if self.name:
+            result["name"] = self.name
+        if self.tool_call_id:
+            result["tool_call_id"] = self.tool_call_id
+        if self.tool_calls:
+            # Core 内部保留扁平结构，具体模型适配器负责转换格式。
+            result["tool_calls"] = [dict(call) for call in self.tool_calls]
+        return result
+
+    def to_openai_dict(self) -> dict[str, Any]:
+        """转换为 OpenAI API 格式，保留给现有适配器和 Web API 使用。"""
+        result = self.to_dict()
+        if self.tool_calls:
+            result["tool_calls"] = [
+                {
+                    "id": call.get("id", ""),
+                    "type": "function",
+                    "function": {
+                        "name": call.get("name", ""),
+                        "arguments": json.dumps(call.get("args", {}), ensure_ascii=False),
+                    },
+                }
+                for call in self.tool_calls
+            ]
+        return result
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> Message:
+        """从 Core 内部格式恢复消息。"""
+
+        return cls(
+            role=value["role"],
+            content=str(value.get("content", "")),
+            name=value.get("name"),
+            tool_call_id=value.get("tool_call_id"),
+            tool_calls=[dict(call) for call in value.get("tool_calls", [])],
+        )
+
+
+def system_message(content: str) -> Message:
+    """创建系统消息。"""
+    return Message(role="system", content=content)
+
+
+def user_message(content: str) -> Message:
+    """创建用户消息。"""
+    return Message(role="user", content=content)
+
+
+def assistant_message(
+    content: str,
+    *,
+    tool_calls: list[dict[str, Any]] | None = None,
+) -> Message:
+    """创建助手消息。"""
+    return Message(
+        role="assistant",
+        content=content,
+        tool_calls=tool_calls or [],
+    )
+
+
+def tool_message(
+    content: str,
+    *,
+    tool_call_id: str,
+    name: str,
+) -> Message:
+    """创建工具消息。"""
+    return Message(
+        role="tool",
+        content=content,
+        tool_call_id=tool_call_id,
+        name=name,
+    )

agent_core/protocol/runtime.py

@@ -0,0 +1,293 @@
+"""Agent 运行时共享协议。
+
+这些类型是 ReAct、业务编排器、工作流和 HTTP runtime 之间的公共边界，
+避免每一层用不同的字典字段表示同一个运行状态。
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+RunStatus = Literal[
+    "queued",
+    "running",
+    "waiting_approval",
+    "waiting_clarification",
+    "interrupted",
+    "completed",
+    "failed",
+    "cancelled",
+]
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+@dataclass
+class RunEvent:
+    """一次运行中的生命周期事件。
+
+    CallbackManager、EventSink、WebSocket 和审计存储消费同一个事件对象，避免多套事件协议。
+    """
+
+    event_type: str
+    run_id: str
+    thread_id: str
+    sequence: int
+    payload: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=_now)
+    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    parent_run_id: str | None = None
+    component: str | None = None
+    tags: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    usage: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+    duration_ms: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_type": self.event_type,
+            "run_id": self.run_id,
+            "thread_id": self.thread_id,
+            "sequence": self.sequence,
+            "payload": self.payload,
+            "timestamp": self.timestamp,
+            "event_id": self.event_id,
+            "parent_run_id": self.parent_run_id,
+            "component": self.component,
+            "tags": list(self.tags),
+            "metadata": dict(self.metadata),
+            "usage": dict(self.usage),
+            "error": self.error,
+            "duration_ms": self.duration_ms,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> RunEvent:
+        return cls(
+            event_type=str(value["event_type"]),
+            run_id=str(value["run_id"]),
+            thread_id=str(value["thread_id"]),
+            sequence=int(value["sequence"]),
+            payload=dict(value.get("payload") or {}),
+            timestamp=str(value.get("timestamp") or _now()),
+            event_id=str(value.get("event_id") or uuid.uuid4()),
+            parent_run_id=value.get("parent_run_id"),
+            component=value.get("component"),
+            tags=[str(tag) for tag in value.get("tags", [])],
+            metadata=dict(value.get("metadata") or {}),
+            usage=dict(value.get("usage") or {}),
+            error=value.get("error"),
+            duration_ms=(float(value["duration_ms"]) if value.get("duration_ms") is not None else None),
+        )
+
+
+@dataclass
+class ApprovalRecord:
+    """可持久化的人机审批记录。"""
+
+    thread_id: str
+    run_id: str
+    action: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    user_id: str | None = None
+    tenant_id: str | None = None
+    approval_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    status: Literal["pending", "approved", "rejected", "expired"] = "pending"
+    reason: str | None = None
+    created_at: str = field(default_factory=_now)
+    expires_at: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "approval_id": self.approval_id,
+            "thread_id": self.thread_id,
+            "run_id": self.run_id,
+            "action": self.action,
+            "arguments": self.arguments,
+            "user_id": self.user_id,
+            "tenant_id": self.tenant_id,
+            "status": self.status,
+            "reason": self.reason,
+            "created_at": self.created_at,
+            "expires_at": self.expires_at,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> ApprovalRecord:
+        return cls(
+            approval_id=str(value.get("approval_id", "")),
+            thread_id=str(value.get("thread_id", "")),
+            run_id=str(value.get("run_id", "")),
+            action=str(value.get("action", "")),
+            arguments=dict(value.get("arguments") or {}),
+            user_id=value.get("user_id"),
+            tenant_id=value.get("tenant_id"),
+            status=value.get("status", "pending"),
+            reason=value.get("reason"),
+            created_at=str(value.get("created_at") or _now()),
+            expires_at=value.get("expires_at"),
+        )
+
+
+@dataclass
+class ToolResult:
+    """工具执行的结构化结果。"""
+
+    tool_name: str
+    success: bool
+    value: Any = None
+    error: str | None = None
+    error_kind: Literal["", "not_found", "invalid_arguments", "timeout", "approval", "execution"] = ""
+    retryable: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_text(self) -> str:
+        """转换成兼容旧 ReAct 消息的文本。"""
+        if self.success:
+            return str(self.value) if self.value is not None else ""
+        return f"[工具错误:{self.error_kind or 'execution'}] {self.error or '未知错误'}"
+
+    def to_dict(self) -> dict[str, Any]:
+        value = self.value
+        try:
+            json.dumps(value, ensure_ascii=False)
+        except (TypeError, ValueError):
+            value = str(value)
+        return {
+            "tool_name": self.tool_name,
+            "success": self.success,
+            "value": value,
+            "error": self.error,
+            "error_kind": self.error_kind,
+            "retryable": self.retryable,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> ToolResult:
+        return cls(
+            tool_name=str(value["tool_name"]),
+            success=bool(value.get("success", False)),
+            value=value.get("value"),
+            error=value.get("error"),
+            error_kind=value.get("error_kind", ""),
+            retryable=bool(value.get("retryable", False)),
+            metadata=dict(value.get("metadata") or {}),
+        )
+
+
+@dataclass
+class RunContext:
+    """一次 Agent run 的统一可恢复上下文。"""
+
+    thread_id: str
+    run_id: str
+    user_id: str | None = None
+    tenant_id: str | None = None
+    parent_run_id: str | None = None
+    tags: list[str] = field(default_factory=list)
+    status: RunStatus = "queued"
+    version: int = 0
+    idempotency_key: str | None = None
+    iteration: int = 0
+    tool_calls_used: int = 0
+    pending_approval: ApprovalRecord | None = None
+    pending_clarification: dict[str, Any] | None = None
+    state: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    # 最后一个可恢复的 Agent Loop 快照；回调只存在于进程内，不参与序列化。
+    checkpoint: dict[str, Any] = field(default_factory=dict)
+    checkpoint_callback: Any = field(default=None, repr=False, compare=False)
+    events: list[RunEvent] = field(default_factory=list)
+
+    def emit(
+        self,
+        event_type: str,
+        *,
+        component: str | None = None,
+        event_metadata: dict[str, Any] | None = None,
+        usage: dict[str, Any] | None = None,
+        error: str | None = None,
+        duration_ms: float | None = None,
+        **payload: Any,
+    ) -> RunEvent:
+        """追加有序事件，供 API、审计和调试读取。"""
+
+        inferred_component = component or event_type.partition("_")[0] or None
+        if error is not None:
+            # 兼容旧消费者读取 payload["error"]，同时提供统一顶层字段。
+            payload.setdefault("error", error)
+        event = RunEvent(
+            event_type=event_type,
+            run_id=self.run_id,
+            thread_id=self.thread_id,
+            sequence=len(self.events),
+            payload=payload,
+            parent_run_id=self.parent_run_id,
+            component=inferred_component,
+            tags=list(self.tags),
+            metadata=dict(event_metadata or {}),
+            usage=dict(usage or {}),
+            error=error,
+            duration_ms=duration_ms,
+        )
+        self.events.append(event)
+        return event
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "thread_id": self.thread_id,
+            "run_id": self.run_id,
+            "user_id": self.user_id,
+            "tenant_id": self.tenant_id,
+            "parent_run_id": self.parent_run_id,
+            "tags": list(self.tags),
+            "status": self.status,
+            "version": self.version,
+            "idempotency_key": self.idempotency_key,
+            "iteration": self.iteration,
+            "tool_calls_used": self.tool_calls_used,
+            "pending_approval": (self.pending_approval.to_dict() if self.pending_approval else None),
+            "pending_clarification": self.pending_clarification,
+            "state": self.state,
+            "metadata": self.metadata,
+            "checkpoint": self.checkpoint,
+            "events": [event.to_dict() for event in self.events],
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> RunContext:
+        """从持久化字典恢复上下文；进程内回调不会参与恢复。"""
+
+        pending_approval = value.get("pending_approval")
+        context = cls(
+            thread_id=str(value["thread_id"]),
+            run_id=str(value["run_id"]),
+            user_id=value.get("user_id"),
+            tenant_id=value.get("tenant_id"),
+            parent_run_id=value.get("parent_run_id"),
+            tags=[str(tag) for tag in value.get("tags", [])],
+            status=value.get("status", "queued"),
+            version=int(value.get("version", 0)),
+            idempotency_key=value.get("idempotency_key"),
+            iteration=int(value.get("iteration", 0)),
+            tool_calls_used=int(value.get("tool_calls_used", 0)),
+            pending_approval=(
+                ApprovalRecord.from_dict(pending_approval) if isinstance(pending_approval, dict) else None
+            ),
+            pending_clarification=value.get("pending_clarification"),
+            state=dict(value.get("state") or {}),
+            metadata=dict(value.get("metadata") or {}),
+            checkpoint=dict(value.get("checkpoint") or {}),
+        )
+        context.events = [
+            RunEvent.from_dict(item) for item in value.get("events", []) if isinstance(item, dict)
+        ]
+        return context

agent_core/py.typed

@@ -0,0 +1 @@
+

agent_core/retrieval/__init__.py

@@ -0,0 +1,40 @@
+"""Embedding、向量存储和检索协议。"""
+
+from agent_core.retrieval.chroma import ChromaVectorStore
+from agent_core.retrieval.core import (
+    Embeddings,
+    Reranker,
+    Retriever,
+    VectorStore,
+)
+from agent_core.retrieval.factory import VectorStoreBackend, create_vector_store
+from agent_core.retrieval.memory import EmbeddingRetriever, InMemoryVectorStore, KeywordRetriever
+from agent_core.retrieval.pgvector import PgVectorStore
+from agent_core.retrieval.types import (
+    RetrievalQuery,
+    RetrievalResult,
+    SearchType,
+    VectorQuery,
+    VectorRecord,
+    VectorSearchResult,
+)
+
+__all__ = [
+    "ChromaVectorStore",
+    "EmbeddingRetriever",
+    "Embeddings",
+    "InMemoryVectorStore",
+    "KeywordRetriever",
+    "PgVectorStore",
+    "Reranker",
+    "RetrievalQuery",
+    "RetrievalResult",
+    "Retriever",
+    "SearchType",
+    "VectorQuery",
+    "VectorRecord",
+    "VectorSearchResult",
+    "VectorStore",
+    "VectorStoreBackend",
+    "create_vector_store",
+]

agent_core/retrieval/_common.py

@@ -0,0 +1,121 @@
+"""向量存储适配器共享的序列化、权限和向量校验。"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import replace
+from typing import Any
+
+from agent_core.access import AccessContext
+from agent_core.documents import Document
+from agent_core.retrieval.types import VectorRecord
+
+
+def normalize_record(
+    record: VectorRecord,
+    access: AccessContext | None,
+    *,
+    require_access: bool,
+) -> VectorRecord:
+    """验证写入身份，并为未声明归属的新记录补齐用户和租户。"""
+    if require_access and access is None:
+        raise PermissionError("该 VectorStore 要求提供 AccessContext")
+    if access is None:
+        return record
+    if not access.can_access(record.user_id, record.tenant_id):
+        raise PermissionError(f"无权写入向量记录：{record.record_id}")
+    return replace(
+        record,
+        user_id=record.user_id or access.user_id,
+        tenant_id=record.tenant_id or access.tenant_id,
+    )
+
+
+def check_record_access(record: VectorRecord, access: AccessContext | None) -> None:
+    """拒绝覆盖或删除当前身份不可访问的既有记录。"""
+    if access is not None and not access.can_access(record.user_id, record.tenant_id):
+        raise PermissionError(f"无权访问向量记录：{record.record_id}")
+
+
+def record_accessible(record: VectorRecord, access: AccessContext | None) -> bool:
+    return access is None or access.can_access(record.user_id, record.tenant_id)
+
+
+def metadata_matches(metadata: dict[str, Any], expected: dict[str, Any]) -> bool:
+    return all(metadata.get(key) == value for key, value in expected.items())
+
+
+def validate_vector(vector: tuple[float, ...], *, dimension: int | None = None) -> None:
+    if not vector:
+        raise ValueError("vector 不能为空")
+    if dimension is not None and len(vector) != dimension:
+        raise ValueError(f"向量维度不一致：期望 {dimension}，实际 {len(vector)}")
+    if not all(math.isfinite(value) for value in vector):
+        raise ValueError("vector 只能包含有限数值")
+
+
+def vector_literal(vector: tuple[float, ...]) -> str:
+    """生成只包含已校验浮点数的 pgvector 文本表示。"""
+    validate_vector(vector)
+    return "[" + ",".join(repr(float(value)) for value in vector) + "]"
+
+
+def parse_vector(value: object) -> tuple[float, ...]:
+    if isinstance(value, str):
+        raw = json.loads(value)
+    elif isinstance(value, (list, tuple)):
+        raw = value
+    else:
+        raise ValueError("无法解析向量存储返回的 embedding")
+    if not isinstance(raw, (list, tuple)):
+        raise ValueError("embedding 必须是数组")
+    vector = tuple(float(item) for item in raw)
+    validate_vector(vector)
+    return vector
+
+
+def encode_record_payload(record: VectorRecord) -> str:
+    """把文档和适配器 metadata 编码成可跨后端保存的 JSON。"""
+    try:
+        return json.dumps(
+            {
+                "document": record.document.to_dict(),
+                "metadata": record.metadata,
+            },
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"向量记录 {record.record_id} 包含不可 JSON 序列化的 metadata") from exc
+
+
+def decode_record_payload(
+    payload: object,
+    *,
+    record_id: str,
+    vector: tuple[float, ...],
+    namespace: str,
+    user_id: str | None,
+    tenant_id: str | None,
+) -> VectorRecord:
+    if isinstance(payload, str):
+        raw = json.loads(payload)
+    elif isinstance(payload, dict):
+        raw = payload
+    else:
+        raise ValueError(f"向量记录 {record_id} 的 payload 格式无效")
+    if not isinstance(raw, dict) or not isinstance(raw.get("document"), dict):
+        raise ValueError(f"向量记录 {record_id} 缺少 document payload")
+    metadata = raw.get("metadata") or {}
+    if not isinstance(metadata, dict):
+        raise ValueError(f"向量记录 {record_id} 的 metadata 必须是对象")
+    return VectorRecord(
+        record_id=record_id,
+        vector=vector,
+        document=Document.from_dict(raw["document"]),
+        namespace=namespace,
+        user_id=user_id,
+        tenant_id=tenant_id,
+        metadata=dict(metadata),
+    )