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

agent_core/__init__.py

@@ -0,0 +1,525 @@
+"""零外部平台绑定的 Python Agent 运行时内核。"""
+
+from agent_core.access import AccessContext
+from agent_core.acp import (
+    AcpBackend,
+    AcpProtocolError,
+    AcpSession,
+    AcpSessionNotFoundError,
+    AcpStdioServer,
+    AcpUpdate,
+    run_acp_stdio,
+)
+from agent_core.callbacks import (
+    BaseCallbackHandler,
+    CallableCallbackHandler,
+    CallbackFailure,
+    CallbackHandler,
+    CallbackManager,
+)
+from agent_core.checkpoint import (
+    Checkpointer,
+    CheckpointVersion,
+    FileCheckpointer,
+    MemoryCheckpointer,
+    TimeTravelCheckpointer,
+)
+from agent_core.compaction import (
+    DEFAULT_COMPACTION_INSTRUCTION,
+    DEFAULT_SUMMARY_SECTIONS,
+    CompactionConfig,
+    CompactionError,
+    CompactionMiddleware,
+    CompactionResult,
+    PruneConfig,
+    SpillStore,
+    build_spill_tool,
+)
+from agent_core.documents import (
+    Blob,
+    BlobParser,
+    Document,
+    DocumentChunk,
+    DocumentLoader,
+    DocumentLocator,
+    RecursiveCharacterTextSplitter,
+    TextBlobParser,
+    TextLoader,
+    TextSplitter,
+)
+from agent_core.errors import (
+    AgentError,
+    CheckpointError,
+    ConfigurationError,
+    DocumentError,
+    DocumentParsingError,
+    DocumentServiceError,
+    MemoryConflictError,
+    MiddlewareError,
+    ModelInvocationError,
+    ModelOutputValidationError,
+    ModelRateLimitError,
+    ModelTimeoutError,
+    ModelUnavailableError,
+    SerializationError,
+    StateMachineError,
+    ToolExecutionError,
+    UnknownSerializedTypeError,
+    UnsupportedSchemaVersionError,
+)
+from agent_core.guardrails import (
+    BlockedKeywordsGuard,
+    Guard,
+    GuardrailsMiddleware,
+    LengthGuard,
+    OutputFormatGuard,
+    PIIRedactionGuard,
+)
+from agent_core.hitl import (
+    ApprovalQueue,
+    ApprovalRequest,
+    ApprovalStatus,
+    HumanInTheLoopMiddleware,
+)
+from agent_core.mcp import (
+    JsonObject,
+    McpConnectionError,
+    McpError,
+    McpTimeoutError,
+    McpToolCaller,
+    McpToolClient,
+    McpToolError,
+)
+from agent_core.middleware import (
+    LoggingMiddleware,
+    Middleware,
+    MiddlewareAction,
+    MiddlewareContext,
+    MiddlewareManager,
+    MiddlewareResult,
+    RetryMiddleware,
+    TokenLimitMiddleware,
+)
+from agent_core.model import (
+    MODEL_PROVIDER_REGISTRY,
+    AnthropicProvider,
+    ContextUsage,
+    GeminiProvider,
+    GovernedModelAdapter,
+    ModelAdapter,
+    ModelExecutionPolicy,
+    ModelOption,
+    ModelProviderFactory,
+    ModelProviderRegistry,
+    OllamaProvider,
+    OpenAIProvider,
+    SlidingWindowRateLimiter,
+    StreamChunk,
+    StructuredOutputResult,
+    StructuredOutputSpec,
+    build_tool_definition,
+    catalog_payload,
+    chat_structured,
+    create_llm_provider,
+    create_model_provider,
+    default_model_catalog,
+    default_model_provider_registry,
+    known_context_window,
+    model_execution_scope,
+    parse_structured_output,
+    register_model_provider,
+    validate_json_schema,
+)
+from agent_core.observability import (
+    AgentStats,
+    CallRecord,
+    ObservabilityMiddleware,
+    ThreadStats,
+    ToolRecord,
+    agent_stats,
+    setup_tracing,
+)
+from agent_core.ports import (
+    ApprovalStore,
+    ContextStore,
+    EventSink,
+    MemoryRecord,
+    MemorySearchResult,
+    MemoryStore,
+    ModelSelection,
+    ModelSelectionScope,
+    ModelSelectionStore,
+    RunStore,
+    SessionStore,
+    WorkflowStore,
+)
+from agent_core.prompts import (
+    ChatPromptTemplate,
+    MessagesPlaceholder,
+    MessageTemplate,
+    PromptEntry,
+    PromptRegistry,
+    PromptTemplate,
+    PromptVersion,
+)
+from agent_core.protocol import (
+    AgentCapabilities,
+    ApprovalRecord,
+    Message,
+    RunContext,
+    RunEvent,
+    RunStatus,
+    ToolResult,
+    assistant_message,
+    system_message,
+    tool_message,
+    user_message,
+)
+from agent_core.retrieval import (
+    ChromaVectorStore,
+    EmbeddingRetriever,
+    Embeddings,
+    InMemoryVectorStore,
+    KeywordRetriever,
+    PgVectorStore,
+    Reranker,
+    RetrievalQuery,
+    RetrievalResult,
+    Retriever,
+    SearchType,
+    VectorQuery,
+    VectorRecord,
+    VectorSearchResult,
+    VectorStore,
+    VectorStoreBackend,
+    create_vector_store,
+)
+from agent_core.runtime import (
+    AgentRuntime,
+    MemoryEventSink,
+    MemoryRunStore,
+    ReActAgent,
+    RunExecutor,
+    RunRecord,
+    RuntimeRun,
+    ThreadRecord,
+    content_text,
+    extract_prompt,
+    message_json,
+    now_iso,
+)
+from agent_core.serialization import (
+    SerializedEnvelope,
+    SerializerRegistry,
+    default_serializer_registry,
+    dumpd,
+    dumps,
+    load,
+    loads,
+)
+from agent_core.skills import (
+    SkillActivation,
+    SkillBindingError,
+    SkillError,
+    SkillLoader,
+    SkillLoadError,
+    SkillRegistrationError,
+    SkillRegistry,
+    SkillSpec,
+    SkillToolKind,
+    SkillToolSpec,
+)
+from agent_core.storage import (
+    BaseSessionStore,
+    InMemoryMemoryStore,
+    MemoryContextStore,
+    MemoryModelSelectionStore,
+    MemoryRunLeaseStore,
+    MemoryRuntimeStore,
+    MemorySessionStore,
+    MemoryWorkflowExecutionStore,
+    PostgresContextStore,
+    PostgresMemoryStore,
+    PostgresModelSelectionStore,
+    PostgresRunLeaseStore,
+    PostgresRuntimeStore,
+    PostgresSessionStore,
+    PostgresWorkflowExecutionStore,
+    RunLease,
+    RunLeaseStore,
+    RuntimeConcurrencyError,
+    RuntimeStore,
+    SessionManager,
+    SqliteContextStore,
+    SqliteMemoryStore,
+    SqliteModelSelectionStore,
+    SqliteRunLeaseStore,
+    SqliteRuntimeStore,
+    SqliteSessionStore,
+    SqliteWorkflowExecutionStore,
+    WorkflowConcurrencyError,
+    WorkflowExecution,
+    WorkflowExecutionStore,
+    create_context_store,
+    create_memory_store,
+    create_model_selection_store,
+    create_run_lease_store,
+    create_runtime_store,
+    create_session_store,
+    create_workflow_execution_store,
+)
+from agent_core.tools import ToolExecutor, ToolRegistry, ToolSpec
+from agent_core.workflow import (
+    END,
+    START,
+    DurableWorkflowRunner,
+    NodeExecutionContext,
+    NodeExecutionPolicy,
+    StateMachine,
+    StateMachineBuilder,
+    WorkflowPause,
+    current_node_execution,
+)
+
+__all__ = [
+    "DEFAULT_COMPACTION_INSTRUCTION",
+    "DEFAULT_SUMMARY_SECTIONS",
+    "END",
+    "MODEL_PROVIDER_REGISTRY",
+    "START",
+    "AccessContext",
+    "AcpBackend",
+    "AcpProtocolError",
+    "AcpSession",
+    "AcpSessionNotFoundError",
+    "AcpStdioServer",
+    "AcpUpdate",
+    "AgentCapabilities",
+    "AgentError",
+    "AgentRuntime",
+    "AgentStats",
+    "AnthropicProvider",
+    "ApprovalQueue",
+    "ApprovalRecord",
+    "ApprovalRequest",
+    "ApprovalStatus",
+    "ApprovalStore",
+    "BaseCallbackHandler",
+    "BaseSessionStore",
+    "Blob",
+    "BlobParser",
+    "BlockedKeywordsGuard",
+    "CallRecord",
+    "CallableCallbackHandler",
+    "CallbackFailure",
+    "CallbackHandler",
+    "CallbackManager",
+    "ChatPromptTemplate",
+    "CheckpointError",
+    "CheckpointVersion",
+    "Checkpointer",
+    "ChromaVectorStore",
+    "CompactionConfig",
+    "CompactionError",
+    "CompactionMiddleware",
+    "CompactionResult",
+    "ConfigurationError",
+    "ContextStore",
+    "ContextUsage",
+    "Document",
+    "DocumentChunk",
+    "DocumentError",
+    "DocumentLoader",
+    "DocumentLocator",
+    "DocumentParsingError",
+    "DocumentServiceError",
+    "DurableWorkflowRunner",
+    "EmbeddingRetriever",
+    "Embeddings",
+    "EventSink",
+    "FileCheckpointer",
+    "GeminiProvider",
+    "GovernedModelAdapter",
+    "Guard",
+    "GuardrailsMiddleware",
+    "HumanInTheLoopMiddleware",
+    "InMemoryMemoryStore",
+    "InMemoryVectorStore",
+    "JsonObject",
+    "KeywordRetriever",
+    "LengthGuard",
+    "LoggingMiddleware",
+    "McpConnectionError",
+    "McpError",
+    "McpTimeoutError",
+    "McpToolCaller",
+    "McpToolClient",
+    "McpToolError",
+    "MemoryCheckpointer",
+    "MemoryConflictError",
+    "MemoryContextStore",
+    "MemoryEventSink",
+    "MemoryModelSelectionStore",
+    "MemoryRecord",
+    "MemoryRunLeaseStore",
+    "MemoryRunStore",
+    "MemoryRuntimeStore",
+    "MemorySearchResult",
+    "MemorySessionStore",
+    "MemoryStore",
+    "MemoryWorkflowExecutionStore",
+    "Message",
+    "MessageTemplate",
+    "MessagesPlaceholder",
+    "Middleware",
+    "MiddlewareAction",
+    "MiddlewareContext",
+    "MiddlewareError",
+    "MiddlewareManager",
+    "MiddlewareResult",
+    "ModelAdapter",
+    "ModelExecutionPolicy",
+    "ModelInvocationError",
+    "ModelOption",
+    "ModelOutputValidationError",
+    "ModelProviderFactory",
+    "ModelProviderRegistry",
+    "ModelRateLimitError",
+    "ModelSelection",
+    "ModelSelectionScope",
+    "ModelSelectionStore",
+    "ModelTimeoutError",
+    "ModelUnavailableError",
+    "NodeExecutionContext",
+    "NodeExecutionPolicy",
+    "ObservabilityMiddleware",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "OutputFormatGuard",
+    "PIIRedactionGuard",
+    "PgVectorStore",
+    "PostgresContextStore",
+    "PostgresMemoryStore",
+    "PostgresModelSelectionStore",
+    "PostgresRunLeaseStore",
+    "PostgresRuntimeStore",
+    "PostgresSessionStore",
+    "PostgresWorkflowExecutionStore",
+    "PromptEntry",
+    "PromptRegistry",
+    "PromptTemplate",
+    "PromptVersion",
+    "PruneConfig",
+    "ReActAgent",
+    "RecursiveCharacterTextSplitter",
+    "Reranker",
+    "RetrievalQuery",
+    "RetrievalResult",
+    "Retriever",
+    "RetryMiddleware",
+    "RunContext",
+    "RunEvent",
+    "RunExecutor",
+    "RunLease",
+    "RunLeaseStore",
+    "RunRecord",
+    "RunStatus",
+    "RunStore",
+    "RuntimeConcurrencyError",
+    "RuntimeRun",
+    "RuntimeStore",
+    "SearchType",
+    "SerializationError",
+    "SerializedEnvelope",
+    "SerializerRegistry",
+    "SessionManager",
+    "SessionStore",
+    "SkillActivation",
+    "SkillBindingError",
+    "SkillError",
+    "SkillLoadError",
+    "SkillLoader",
+    "SkillRegistrationError",
+    "SkillRegistry",
+    "SkillSpec",
+    "SkillToolKind",
+    "SkillToolSpec",
+    "SlidingWindowRateLimiter",
+    "SpillStore",
+    "SqliteContextStore",
+    "SqliteMemoryStore",
+    "SqliteModelSelectionStore",
+    "SqliteRunLeaseStore",
+    "SqliteRuntimeStore",
+    "SqliteSessionStore",
+    "SqliteWorkflowExecutionStore",
+    "StateMachine",
+    "StateMachineBuilder",
+    "StateMachineError",
+    "StreamChunk",
+    "StructuredOutputResult",
+    "StructuredOutputSpec",
+    "TextBlobParser",
+    "TextLoader",
+    "TextSplitter",
+    "ThreadRecord",
+    "ThreadStats",
+    "TimeTravelCheckpointer",
+    "TokenLimitMiddleware",
+    "ToolExecutionError",
+    "ToolExecutor",
+    "ToolRecord",
+    "ToolRegistry",
+    "ToolResult",
+    "ToolSpec",
+    "UnknownSerializedTypeError",
+    "UnsupportedSchemaVersionError",
+    "VectorQuery",
+    "VectorRecord",
+    "VectorSearchResult",
+    "VectorStore",
+    "VectorStoreBackend",
+    "WorkflowConcurrencyError",
+    "WorkflowExecution",
+    "WorkflowExecutionStore",
+    "WorkflowPause",
+    "WorkflowStore",
+    "agent_stats",
+    "assistant_message",
+    "build_spill_tool",
+    "build_tool_definition",
+    "catalog_payload",
+    "chat_structured",
+    "content_text",
+    "create_context_store",
+    "create_llm_provider",
+    "create_memory_store",
+    "create_model_provider",
+    "create_model_selection_store",
+    "create_run_lease_store",
+    "create_runtime_store",
+    "create_session_store",
+    "create_vector_store",
+    "create_workflow_execution_store",
+    "current_node_execution",
+    "default_model_catalog",
+    "default_model_provider_registry",
+    "default_serializer_registry",
+    "dumpd",
+    "dumps",
+    "extract_prompt",
+    "known_context_window",
+    "load",
+    "loads",
+    "message_json",
+    "model_execution_scope",
+    "now_iso",
+    "parse_structured_output",
+    "register_model_provider",
+    "run_acp_stdio",
+    "setup_tracing",
+    "system_message",
+    "tool_message",
+    "user_message",
+    "validate_json_schema",
+]

agent_core/access/__init__.py

@@ -0,0 +1,6 @@
+"""访问上下文公共导出。"""
+
+from agent_core.access.context import AccessContext
+from agent_core.access.guard import enforce_access
+
+__all__ = ["AccessContext", "enforce_access"]

agent_core/access/context.py

@@ -0,0 +1,45 @@
+"""通用访问上下文。
+
+Core 只表达一次运行所携带的用户、租户和角色边界，不负责 JWT 校验、HTTP
+Header 解析或具体认证系统。存储适配器可以使用 ``can_access`` 做资源归属检查。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AccessContext:
+    """一次请求的访问身份。"""
+
+    user_id: str = "anonymous"
+    tenant_id: str = "default"
+    roles: frozenset[str] = field(default_factory=lambda: frozenset({"user"}))
+
+    @property
+    def is_admin(self) -> bool:
+        """判断是否拥有当前租户范围内的管理权限。"""
+        return bool({"admin", "tenant_admin"} & self.roles)
+
+    def can_access(
+        self,
+        owner_user_id: str | None,
+        owner_tenant_id: str | None,
+    ) -> bool:
+        """判断当前身份是否可以访问资源。"""
+        if self.is_admin and owner_tenant_id in (None, self.tenant_id):
+            return True
+        return owner_user_id in (None, self.user_id) and owner_tenant_id in (None, self.tenant_id)
+
+    def to_dict(self) -> dict[str, Any]:
+        """转换为可持久化或写入事件的字典。"""
+        return {
+            "user_id": self.user_id,
+            "tenant_id": self.tenant_id,
+            "roles": sorted(self.roles),
+        }
+
+
+__all__ = ["AccessContext"]

agent_core/access/guard.py

@@ -0,0 +1,40 @@
+"""访问校验的共享实现。
+
+``AgentRuntime`` 与 ``DurableWorkflowRunner`` 都在读取/恢复入口执行同一套
+三类校验：严格模式必须提供身份、资源必须绑定归属、访问者必须有权。
+这里把判定顺序与错误文案固定在唯一实现处，避免两份拷贝各自漂移。
+"""
+
+from __future__ import annotations
+
+from agent_core.access.context import AccessContext
+
+
+def enforce_access(
+    *,
+    strict: bool,
+    accessor: str,
+    subject: str,
+    owner_user_id: str | None,
+    owner_tenant_id: str | None,
+    access: AccessContext | None,
+) -> None:
+    """统一执行三类访问校验，任一不通过时抛出 ``PermissionError``。
+
+    Args:
+        strict: 严格模式开关（``require_access``）。
+        accessor: 严格模式错误文案中的执行体名称，如 "AgentRuntime"。
+        subject: 资源对象文案，如 "run" / "工作流执行实例"。
+        owner_user_id: 资源绑定的用户 ID。
+        owner_tenant_id: 资源绑定的租户 ID。
+        access: 调用方身份；None 表示匿名访问（严格模式下不允许）。
+    """
+    if strict and access is None:
+        raise PermissionError(f"该 {accessor} 要求提供 AccessContext")
+    if strict and (owner_user_id is None or owner_tenant_id is None):
+        raise PermissionError(f"该 {subject} 尚未绑定用户和租户")
+    if access is not None and not access.can_access(owner_user_id, owner_tenant_id):
+        raise PermissionError(f"无权访问该 {subject}")
+
+
+__all__ = ["enforce_access"]