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

agent_core/documents/splitters.py

@@ -0,0 +1,94 @@
+"""文档切分协议和轻量递归字符切分器。"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Protocol, runtime_checkable
+
+from agent_core.documents.types import Document, DocumentChunk, DocumentLocator
+
+
+@runtime_checkable
+class TextSplitter(Protocol):
+    """文本和文档切分协议。"""
+
+    def split_text(self, text: str) -> list[str]: ...
+
+    def split_documents(self, documents: list[Document]) -> list[DocumentChunk]: ...
+
+
+class RecursiveCharacterTextSplitter:
+    """按段落、换行和标点优先寻找边界的零依赖切分器。"""
+
+    def __init__(
+        self,
+        *,
+        chunk_size: int = 1000,
+        chunk_overlap: int = 100,
+        separators: tuple[str, ...] = ("\n\n", "\n", "。", "；", ". ", " "),
+    ) -> None:
+        if chunk_size <= 0:
+            raise ValueError("chunk_size 必须大于 0")
+        if chunk_overlap < 0 or chunk_overlap >= chunk_size:
+            raise ValueError("chunk_overlap 必须大于等于 0 且小于 chunk_size")
+        self._chunk_size = chunk_size
+        self._chunk_overlap = chunk_overlap
+        self._separators = tuple(separator for separator in separators if separator)
+
+    def split_text(self, text: str) -> list[str]:
+        return [text[start:end] for start, end in self._split_offsets(text)]
+
+    def split_documents(self, documents: list[Document]) -> list[DocumentChunk]:
+        chunks: list[DocumentChunk] = []
+        for document in documents:
+            base_offset = document.locator.start_offset if document.locator else 0
+            for chunk_index, (start, end) in enumerate(self._split_offsets(document.content)):
+                locator = DocumentLocator(
+                    uri=document.locator.uri if document.locator else document.source,
+                    page=document.locator.page if document.locator else None,
+                    block_id=document.locator.block_id if document.locator else None,
+                    start_offset=(base_offset or 0) + start,
+                    end_offset=(base_offset or 0) + end,
+                )
+                chunks.append(
+                    DocumentChunk(
+                        document_id=str(
+                            uuid.uuid5(
+                                uuid.NAMESPACE_URL,
+                                f"{document.document_id}:{chunk_index}:{start}:{end}",
+                            )
+                        ),
+                        content=document.content[start:end],
+                        parent_document_id=document.document_id,
+                        chunk_index=chunk_index,
+                        source=document.source,
+                        mime_type=document.mime_type,
+                        metadata=dict(document.metadata),
+                        locator=locator,
+                    )
+                )
+        return chunks
+
+    def _split_offsets(self, text: str) -> list[tuple[int, int]]:
+        if not text:
+            return []
+        offsets: list[tuple[int, int]] = []
+        start = 0
+        length = len(text)
+        while start < length:
+            hard_end = min(start + self._chunk_size, length)
+            end = hard_end
+            if hard_end < length:
+                minimum = start + max(1, self._chunk_size // 2)
+                for separator in self._separators:
+                    position = text.rfind(separator, minimum, hard_end)
+                    if position >= minimum:
+                        end = position + len(separator)
+                        break
+            if end <= start:
+                end = hard_end
+            offsets.append((start, end))
+            if end >= length:
+                break
+            start = max(start + 1, end - self._chunk_overlap)
+        return offsets

agent_core/documents/types.py

@@ -0,0 +1,197 @@
+"""与模型和存储实现无关的文档值对象。"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _sha256(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+@dataclass(frozen=True)
+class DocumentLocator:
+    """文档中的稳定位置，用于引用、续读和追踪切分来源。"""
+
+    uri: str | None = None
+    page: int | None = None
+    block_id: str | None = None
+    start_offset: int | None = None
+    end_offset: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "uri": self.uri,
+            "page": self.page,
+            "block_id": self.block_id,
+            "start_offset": self.start_offset,
+            "end_offset": self.end_offset,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> DocumentLocator:
+        return cls(
+            uri=value.get("uri"),
+            page=int(value["page"]) if value.get("page") is not None else None,
+            block_id=value.get("block_id"),
+            start_offset=(int(value["start_offset"]) if value.get("start_offset") is not None else None),
+            end_offset=int(value["end_offset"]) if value.get("end_offset") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class Blob:
+    """尚未解析的原始二进制内容。"""
+
+    data: bytes
+    source: str | None = None
+    mime_type: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    checksum: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.checksum:
+            object.__setattr__(self, "checksum", _sha256(self.data))
+
+    @classmethod
+    def from_text(
+        cls,
+        text: str,
+        *,
+        source: str | None = None,
+        mime_type: str = "text/plain",
+        metadata: dict[str, Any] | None = None,
+        encoding: str = "utf-8",
+    ) -> Blob:
+        return cls(
+            text.encode(encoding),
+            source=source,
+            mime_type=mime_type,
+            metadata=dict(metadata or {}),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Blob 的 JSON 编码由 serialization 模块负责，这里保留原始 bytes。"""
+
+        return {
+            "data": self.data,
+            "source": self.source,
+            "mime_type": self.mime_type,
+            "metadata": dict(self.metadata),
+            "checksum": self.checksum,
+        }
+
+
+@dataclass(frozen=True)
+class Document:
+    """解析后的文本及其来源信息。"""
+
+    content: str
+    document_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    source: str | None = None
+    mime_type: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    locator: DocumentLocator | None = None
+    checksum: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.document_id.strip():
+            raise ValueError("document_id 不能为空")
+        if not self.checksum:
+            object.__setattr__(self, "checksum", _sha256(self.content.encode("utf-8")))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "document_id": self.document_id,
+            "content": self.content,
+            "source": self.source,
+            "mime_type": self.mime_type,
+            "metadata": dict(self.metadata),
+            "locator": self.locator.to_dict() if self.locator else None,
+            "checksum": self.checksum,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> Document:
+        locator = value.get("locator")
+        return cls(
+            document_id=str(value["document_id"]),
+            content=str(value.get("content", "")),
+            source=value.get("source"),
+            mime_type=value.get("mime_type"),
+            metadata=dict(value.get("metadata") or {}),
+            locator=DocumentLocator.from_dict(locator) if isinstance(locator, dict) else None,
+            checksum=str(value.get("checksum", "")),
+        )
+
+
+@dataclass(frozen=True)
+class DocumentChunk:
+    """可索引的文档片段，保留父文档和字符区间。"""
+
+    content: str
+    parent_document_id: str
+    chunk_index: int
+    document_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    source: str | None = None
+    mime_type: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    locator: DocumentLocator | None = None
+    checksum: str = ""
+
+    def __post_init__(self) -> None:
+        if self.chunk_index < 0:
+            raise ValueError("chunk_index 不能小于 0")
+        if not self.parent_document_id.strip():
+            raise ValueError("parent_document_id 不能为空")
+        if not self.document_id.strip():
+            raise ValueError("document_id 不能为空")
+        if not self.checksum:
+            object.__setattr__(self, "checksum", _sha256(self.content.encode("utf-8")))
+
+    def to_document(self) -> Document:
+        metadata = {
+            **self.metadata,
+            "parent_document_id": self.parent_document_id,
+            "chunk_index": self.chunk_index,
+        }
+        return Document(
+            document_id=self.document_id,
+            content=self.content,
+            source=self.source,
+            mime_type=self.mime_type,
+            metadata=metadata,
+            locator=self.locator,
+            checksum=self.checksum,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "document_id": self.document_id,
+            "content": self.content,
+            "parent_document_id": self.parent_document_id,
+            "chunk_index": self.chunk_index,
+            "source": self.source,
+            "mime_type": self.mime_type,
+            "metadata": dict(self.metadata),
+            "locator": self.locator.to_dict() if self.locator else None,
+            "checksum": self.checksum,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> DocumentChunk:
+        locator = value.get("locator")
+        return cls(
+            document_id=str(value["document_id"]),
+            content=str(value.get("content", "")),
+            parent_document_id=str(value["parent_document_id"]),
+            chunk_index=int(value["chunk_index"]),
+            source=value.get("source"),
+            mime_type=value.get("mime_type"),
+            metadata=dict(value.get("metadata") or {}),
+            locator=DocumentLocator.from_dict(locator) if isinstance(locator, dict) else None,
+            checksum=str(value.get("checksum", "")),
+        )

agent_core/errors.py

@@ -0,0 +1,81 @@
+"""Agent Core 公共错误定义。"""
+
+from __future__ import annotations
+
+
+class AgentError(Exception):
+    """Agent 基础错误。"""
+
+
+class ConfigurationError(AgentError):
+    """配置错误。"""
+
+
+class ModelInvocationError(AgentError):
+    """模型调用错误。"""
+
+
+class ModelRateLimitError(ModelInvocationError):
+    """模型服务限流，适合按退避策略重试。"""
+
+
+class ModelTimeoutError(ModelInvocationError):
+    """模型调用超时，适合有限次数重试。"""
+
+
+class ModelUnavailableError(ModelInvocationError):
+    """模型服务暂时不可用，适合按退避策略重试。"""
+
+
+class ModelOutputValidationError(AgentError):
+    """模型输出验证错误。"""
+
+
+class ToolExecutionError(AgentError):
+    """工具执行错误。"""
+
+
+class StateMachineError(AgentError):
+    """状态机错误。"""
+
+
+class CheckpointError(AgentError):
+    """Checkpoint 持久化错误。"""
+
+
+class MiddlewareError(AgentError):
+    """中间件错误。"""
+
+
+class DocumentError(AgentError):
+    """文档加载或解析基础错误。"""
+
+
+class DocumentParsingError(DocumentError):
+    """文档内容或解析服务响应无法转换成 Core Document。"""
+
+
+class DocumentServiceError(DocumentError):
+    """外部文档解析服务调用失败。"""
+
+
+class MemoryConflictError(AgentError):
+    """长期记忆发生乐观并发冲突。"""
+
+    def __init__(self, memory_id: str, expected_version: int, actual_version: int) -> None:
+        super().__init__(f"记忆 {memory_id} 版本冲突：期望 {expected_version}，实际 {actual_version}")
+        self.memory_id = memory_id
+        self.expected_version = expected_version
+        self.actual_version = actual_version
+
+
+class SerializationError(AgentError):
+    """序列化或反序列化失败。"""
+
+
+class UnknownSerializedTypeError(SerializationError):
+    """序列化注册表中不存在指定类型。"""
+
+
+class UnsupportedSchemaVersionError(SerializationError):
+    """对象版本高于当前版本，或缺少必要迁移函数。"""

agent_core/guardrails/__init__.py

@@ -0,0 +1,19 @@
+"""输入输出护栏公共导出。"""
+
+from agent_core.guardrails.core import (
+    BlockedKeywordsGuard,
+    Guard,
+    GuardrailsMiddleware,
+    LengthGuard,
+    OutputFormatGuard,
+    PIIRedactionGuard,
+)
+
+__all__ = [
+    "BlockedKeywordsGuard",
+    "Guard",
+    "GuardrailsMiddleware",
+    "LengthGuard",
+    "OutputFormatGuard",
+    "PIIRedactionGuard",
+]

agent_core/guardrails/core.py

@@ -0,0 +1,186 @@
+"""与业务无关的输入、输出安全校验中间件。"""
+
+from __future__ import annotations
+
+import logging
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import ClassVar
+
+from agent_core.middleware.base import (
+    Middleware,
+    MiddlewareAction,
+    MiddlewareContext,
+    MiddlewareResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Guard(ABC):
+    """单个文本校验规则。"""
+
+    @abstractmethod
+    def check(self, text: str) -> tuple[bool, str]:
+        """返回 ``(是否通过, 原因)``。"""
+
+    @property
+    def name(self) -> str:
+        return self.__class__.__name__
+
+
+class BlockedKeywordsGuard(Guard):
+    """屏蔽指定关键词，默认大小写不敏感。"""
+
+    def __init__(self, keywords: Sequence[str] = (), case_sensitive: bool = False) -> None:
+        flags = 0 if case_sensitive else re.IGNORECASE
+        self._keywords = list(keywords)
+        self._patterns = [re.compile(re.escape(keyword), flags) for keyword in self._keywords]
+
+    def check(self, text: str) -> tuple[bool, str]:
+        for pattern, keyword in zip(self._patterns, self._keywords, strict=True):
+            if pattern.search(text):
+                return False, f"输入包含违禁词：{keyword}"
+        return True, ""
+
+
+class LengthGuard(Guard):
+    """限制输入或输出字符数。"""
+
+    def __init__(
+        self,
+        max_input_chars: int | None = 5000,
+        max_output_chars: int | None = None,
+    ) -> None:
+        self._max_input = max_input_chars
+        self._max_output = max_output_chars
+
+    def check(self, text: str) -> tuple[bool, str]:
+        limit = self._max_input or self._max_output
+        if limit and len(text) > limit:
+            return False, f"文本长度 {len(text)} 超出限制 {limit}"
+        return True, ""
+
+    def check_input(self, text: str) -> tuple[bool, str]:
+        if self._max_input and len(text) > self._max_input:
+            return False, f"输入长度 {len(text)} 超出限制 {self._max_input}"
+        return True, ""
+
+    def check_output(self, text: str) -> tuple[bool, str]:
+        if self._max_output and len(text) > self._max_output:
+            return False, f"输出长度 {len(text)} 超出限制 {self._max_output}"
+        return True, ""
+
+
+class PIIRedactionGuard(Guard):
+    """检测并脱敏常见手机号、身份证、邮箱和银行卡号。"""
+
+    _PATTERNS: ClassVar[list[tuple[str, re.Pattern[str], str]]] = [
+        ("手机号", re.compile(r"\b1[3-9]\d{9}\b"), "***手机号***"),
+        ("身份证", re.compile(r"\b\d{17}[\dXx]\b"), "***身份证***"),
+        ("邮箱", re.compile(r"\b[\w.+-]+@[\w-]+\.[a-z]{2,}\b", re.I), "***邮箱***"),
+        ("银行卡", re.compile(r"\b\d{16,19}\b"), "***银行卡***"),
+    ]
+
+    def __init__(self, block_on_detection: bool = False) -> None:
+        self._block = block_on_detection
+
+    def check(self, text: str) -> tuple[bool, str]:
+        detected = [name for name, pattern, _ in self._PATTERNS if pattern.search(text)]
+        if not detected:
+            return True, ""
+        if self._block:
+            return False, f"输入/输出包含 PII：{', '.join(detected)}"
+        logger.warning("[PII] 检测到 PII 类型：%s（已脱敏）", detected)
+        return True, f"PII detected: {detected}"
+
+    def redact(self, text: str) -> str:
+        for _, pattern, placeholder in self._PATTERNS:
+            text = pattern.sub(placeholder, text)
+        return text
+
+
+class OutputFormatGuard(Guard):
+    """拦截常见脚本、SQL 注入和 JavaScript 协议内容。"""
+
+    _INJECTION_PATTERNS: ClassVar[list[re.Pattern[str]]] = [
+        re.compile(r"(DROP\s+TABLE|DELETE\s+FROM|INSERT\s+INTO)", re.I),
+        re.compile(r"(<script[\s>])", re.I),
+        re.compile(r"(javascript\s*:)", re.I),
+    ]
+
+    def check(self, text: str) -> tuple[bool, str]:
+        if any(pattern.search(text) for pattern in self._INJECTION_PATTERNS):
+            return False, "输出包含潜在注入内容"
+        return True, ""
+
+
+class GuardrailsMiddleware(Middleware):
+    """在模型调用前检查用户输入、调用后检查模型输出。"""
+
+    def __init__(
+        self,
+        input_guards: Sequence[Guard] = (),
+        output_guards: Sequence[Guard] = (),
+        pii_redact: bool = False,
+    ) -> None:
+        self._input_guards = list(input_guards)
+        self._output_guards = list(output_guards)
+        self._pii_redact = pii_redact
+        self._pii_guard = PIIRedactionGuard() if pii_redact else None
+
+    async def before_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        user_text = next(
+            (message.content for message in reversed(ctx.messages) if message.role == "user"),
+            "",
+        )
+        if not user_text:
+            return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+        for guard in self._input_guards:
+            passed, reason = (
+                guard.check_input(user_text) if isinstance(guard, LengthGuard) else guard.check(user_text)
+            )
+            if not passed:
+                logger.warning("[Guard] 输入被拦截 [%s]: %s", guard.name, reason)
+                return MiddlewareResult(
+                    action=MiddlewareAction.STOP,
+                    data={"guard": guard.name, "reason": reason},
+                    error=reason,
+                )
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def after_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        if ctx.llm_response is None:
+            return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+        output_text = ctx.llm_response.content
+        if self._pii_redact and self._pii_guard and output_text:
+            redacted = self._pii_guard.redact(output_text)
+            if redacted != output_text:
+                logger.info("[Guard] 输出 PII 已脱敏")
+                ctx.llm_response.content = redacted
+                output_text = redacted
+        for guard in self._output_guards:
+            passed, reason = (
+                guard.check_output(output_text)
+                if isinstance(guard, LengthGuard)
+                else guard.check(output_text)
+            )
+            if not passed:
+                logger.warning("[Guard] 输出被拦截 [%s]: %s", guard.name, reason)
+                return MiddlewareResult(
+                    action=MiddlewareAction.STOP,
+                    data={"guard": guard.name, "reason": reason},
+                    error=reason,
+                )
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+
+__all__ = [
+    "BlockedKeywordsGuard",
+    "Guard",
+    "GuardrailsMiddleware",
+    "LengthGuard",
+    "OutputFormatGuard",
+    "PIIRedactionGuard",
+]

agent_core/hitl/__init__.py

@@ -0,0 +1,15 @@
+"""人机协同审批公共导出。"""
+
+from agent_core.hitl.core import (
+    ApprovalQueue,
+    ApprovalRequest,
+    ApprovalStatus,
+    HumanInTheLoopMiddleware,
+)
+
+__all__ = [
+    "ApprovalQueue",
+    "ApprovalRequest",
+    "ApprovalStatus",
+    "HumanInTheLoopMiddleware",
+]