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

agent_core/model/structured.py

@@ -0,0 +1,200 @@
+"""提供商无关的结构化输出约束、解析和校验。"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, cast
+
+from agent_core.errors import ModelOutputValidationError
+from agent_core.model.core import ModelAdapter
+from agent_core.protocol.messages import Message, system_message, user_message
+
+_JSON_FENCE = re.compile(r"^```(?:json)?\s*(.*?)\s*```$", re.DOTALL | re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class StructuredOutputSpec[T]:
+    """一次结构化输出调用的 Schema 和解析规则。"""
+
+    name: str
+    schema: dict[str, Any]
+    decoder: Callable[[Any], T] | None = None
+    max_retries: int = 1
+    instruction: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ValueError("结构化输出名称不能为空")
+        if self.max_retries < 0:
+            raise ValueError("max_retries 不能小于 0")
+        if not isinstance(self.schema, dict):
+            raise TypeError("schema 必须是 JSON Schema 字典")
+
+
+@dataclass(frozen=True)
+class StructuredOutputResult[T]:
+    """结构化输出结果及其原始模型消息。"""
+
+    value: T
+    raw_message: Message
+    attempts: int
+
+
+def _extract_json(content: str) -> Any:
+    text = content.strip()
+    fenced = _JSON_FENCE.match(text)
+    if fenced:
+        text = fenced.group(1).strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ModelOutputValidationError(
+            f"模型输出不是有效 JSON：第 {exc.lineno} 行第 {exc.colno} 列，{exc.msg}"
+        ) from exc
+
+
+def _matches_type(value: Any, expected: str) -> bool:
+    if expected == "object":
+        return isinstance(value, dict)
+    if expected == "array":
+        return isinstance(value, list)
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "number":
+        return isinstance(value, int | float) and not isinstance(value, bool)
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected == "null":
+        return value is None
+    raise ModelOutputValidationError(f"暂不支持的 JSON Schema type：{expected}")
+
+
+def validate_json_schema(value: Any, schema: dict[str, Any], *, path: str = "$") -> None:
+    """校验 Core 支持的 JSON Schema 子集。
+
+    支持 type、required、properties、additionalProperties、items、enum、
+    minLength、maxLength、minimum 和 maximum。复杂组合规则可由 decoder 做二次校验。
+    """
+
+    expected = schema.get("type")
+    if isinstance(expected, list):
+        if not any(_matches_type(value, item) for item in expected):
+            raise ModelOutputValidationError(f"{path} 类型不匹配，期望 {expected}")
+    elif isinstance(expected, str) and not _matches_type(value, expected):
+        raise ModelOutputValidationError(f"{path} 类型不匹配，期望 {expected}")
+
+    if "enum" in schema and value not in schema["enum"]:
+        raise ModelOutputValidationError(f"{path} 不在允许值 {schema['enum']} 中")
+
+    if isinstance(value, dict):
+        required = schema.get("required", [])
+        missing = [name for name in required if name not in value]
+        if missing:
+            raise ModelOutputValidationError(f"{path} 缺少必填字段：{', '.join(missing)}")
+        properties = schema.get("properties", {})
+        for name, item in value.items():
+            child_schema = properties.get(name)
+            if child_schema is not None:
+                validate_json_schema(item, child_schema, path=f"{path}.{name}")
+            elif schema.get("additionalProperties") is False:
+                raise ModelOutputValidationError(f"{path} 包含未声明字段：{name}")
+
+    if isinstance(value, list) and isinstance(schema.get("items"), dict):
+        for index, item in enumerate(value):
+            validate_json_schema(item, schema["items"], path=f"{path}[{index}]")
+
+    if isinstance(value, str):
+        if "minLength" in schema and len(value) < int(schema["minLength"]):
+            raise ModelOutputValidationError(f"{path} 长度小于 {schema['minLength']}")
+        if "maxLength" in schema and len(value) > int(schema["maxLength"]):
+            raise ModelOutputValidationError(f"{path} 长度大于 {schema['maxLength']}")
+
+    if isinstance(value, int | float) and not isinstance(value, bool):
+        if "minimum" in schema and value < schema["minimum"]:
+            raise ModelOutputValidationError(f"{path} 小于最小值 {schema['minimum']}")
+        if "maximum" in schema and value > schema["maximum"]:
+            raise ModelOutputValidationError(f"{path} 大于最大值 {schema['maximum']}")
+
+
+def parse_structured_output[T](message: Message, spec: StructuredOutputSpec[T]) -> T:
+    """解析并校验一个模型消息。"""
+
+    if message.tool_calls:
+        raise ModelOutputValidationError("结构化输出阶段不允许返回工具调用")
+    value = _extract_json(message.content)
+    validate_json_schema(value, spec.schema)
+    if spec.decoder is None:
+        return cast(T, value)
+    try:
+        return spec.decoder(value)
+    except ModelOutputValidationError:
+        raise
+    except Exception as exc:
+        raise ModelOutputValidationError(f"结构化输出 decoder 校验失败：{exc}") from exc
+
+
+def _instruction(spec: StructuredOutputSpec[Any]) -> str:
+    if spec.instruction:
+        return spec.instruction
+    schema = json.dumps(spec.schema, ensure_ascii=False, separators=(",", ":"))
+    return (
+        f"请只输出符合 JSON Schema 的 JSON 对象，不要使用 Markdown 代码块。"
+        f"输出名称：{spec.name}。JSON Schema：{schema}"
+    )
+
+
+async def chat_structured[T](
+    model: ModelAdapter,
+    messages: list[Message],
+    spec: StructuredOutputSpec[T],
+    *,
+    tools: list[dict[str, Any]] | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+) -> StructuredOutputResult[T]:
+    """调用模型并在解析失败时携带错误信息进行有限重试。"""
+
+    # 合并为一条 system 消息，避免 Anthropic 等单 system Provider 丢失应用原提示词。
+    system_parts = [message.content for message in messages if message.role == "system"]
+    system_parts.append(_instruction(spec))
+    working = [
+        system_message("\n\n".join(part for part in system_parts if part)),
+        *(message for message in messages if message.role != "system"),
+    ]
+    last_error: ModelOutputValidationError | None = None
+    for attempt in range(1, spec.max_retries + 2):
+        kwargs: dict[str, Any] = {"tools": tools}
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+        raw = await model.chat(working, **kwargs)
+        try:
+            value = parse_structured_output(raw, spec)
+            return StructuredOutputResult(value=value, raw_message=raw, attempts=attempt)
+        except ModelOutputValidationError as exc:
+            last_error = exc
+            if attempt > spec.max_retries:
+                break
+            working.extend(
+                [
+                    raw,
+                    user_message(f"上一次输出校验失败：{exc}。请重新输出完整且合法的 JSON。"),
+                ]
+            )
+    assert last_error is not None
+    raise last_error
+
+
+__all__ = [
+    "StructuredOutputResult",
+    "StructuredOutputSpec",
+    "chat_structured",
+    "parse_structured_output",
+    "validate_json_schema",
+]

agent_core/observability/__init__.py

@@ -0,0 +1,21 @@
+"""可观测性公共导出。"""
+
+from agent_core.observability.core import (
+    AgentStats,
+    CallRecord,
+    ObservabilityMiddleware,
+    ThreadStats,
+    ToolRecord,
+    agent_stats,
+    setup_tracing,
+)
+
+__all__ = [
+    "AgentStats",
+    "CallRecord",
+    "ObservabilityMiddleware",
+    "ThreadStats",
+    "ToolRecord",
+    "agent_stats",
+    "setup_tracing",
+]

agent_core/observability/core.py

@@ -0,0 +1,311 @@
+"""零依赖可观测性中间件和进程内统计。"""
+
+from __future__ import annotations
+
+import logging
+import time
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any
+
+from agent_core.middleware.base import (
+    Middleware,
+    MiddlewareAction,
+    MiddlewareContext,
+    MiddlewareResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CallRecord:
+    """单次模型调用记录。"""
+
+    timestamp: float
+    iteration: int
+    latency_ms: float
+    input_messages: int
+    tool_calls: int
+    finish_reason: str = "unknown"
+
+
+@dataclass
+class ToolRecord:
+    """单次工具调用记录。"""
+
+    timestamp: float
+    tool_name: str
+    latency_ms: float
+    success: bool = True
+
+
+@dataclass
+class ThreadStats:
+    """单个会话的累计统计。"""
+
+    thread_id: str
+    total_llm_calls: int = 0
+    total_tool_calls: int = 0
+    total_latency_ms: float = 0.0
+    llm_records: list[CallRecord] = field(default_factory=list)
+    tool_records: list[ToolRecord] = field(default_factory=list)
+
+    @property
+    def avg_latency_ms(self) -> float:
+        return self.total_latency_ms / len(self.llm_records) if self.llm_records else 0.0
+
+
+class AgentStats:
+    """进程级统计注册表；生产环境可通过事件 sink 转发到外部系统。"""
+
+    def __init__(self, *, max_threads: int = 1000, max_records_per_thread: int = 1000) -> None:
+        if max_threads <= 0 or max_records_per_thread <= 0:
+            raise ValueError("统计容量必须大于 0")
+        self._stats: dict[str, ThreadStats] = {}
+        self._max_threads = max_threads
+        self._max_records_per_thread = max_records_per_thread
+
+    def get_stats(self, thread_id: str) -> ThreadStats:
+        if thread_id not in self._stats:
+            if len(self._stats) >= self._max_threads:
+                oldest_thread = next(iter(self._stats))
+                del self._stats[oldest_thread]
+            self._stats[thread_id] = ThreadStats(thread_id=thread_id)
+        else:
+            # dict 保持插入顺序，用重新插入实现轻量 LRU。
+            self._stats[thread_id] = self._stats.pop(thread_id)
+        return self._stats[thread_id]
+
+    def record_llm_call(
+        self,
+        thread_id: str,
+        iteration: int,
+        latency_ms: float,
+        input_messages: int,
+        tool_calls: int,
+        finish_reason: str = "unknown",
+    ) -> None:
+        stats = self.get_stats(thread_id)
+        stats.total_llm_calls += 1
+        stats.total_latency_ms += latency_ms
+        stats.llm_records.append(
+            CallRecord(
+                timestamp=time.time(),
+                iteration=iteration,
+                latency_ms=latency_ms,
+                input_messages=input_messages,
+                tool_calls=tool_calls,
+                finish_reason=finish_reason,
+            )
+        )
+        if len(stats.llm_records) > self._max_records_per_thread:
+            del stats.llm_records[: len(stats.llm_records) - self._max_records_per_thread]
+
+    def record_tool_call(
+        self,
+        thread_id: str,
+        tool_name: str,
+        latency_ms: float,
+        success: bool = True,
+    ) -> None:
+        stats = self.get_stats(thread_id)
+        stats.total_tool_calls += 1
+        stats.tool_records.append(
+            ToolRecord(
+                timestamp=time.time(),
+                tool_name=tool_name,
+                latency_ms=latency_ms,
+                success=success,
+            )
+        )
+        if len(stats.tool_records) > self._max_records_per_thread:
+            del stats.tool_records[: len(stats.tool_records) - self._max_records_per_thread]
+
+    def all_threads(self) -> list[str]:
+        return list(self._stats)
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            thread_id: {
+                "llm_calls": stats.total_llm_calls,
+                "tool_calls": stats.total_tool_calls,
+                "avg_latency_ms": round(stats.avg_latency_ms, 1),
+                "total_latency_ms": round(stats.total_latency_ms, 1),
+            }
+            for thread_id, stats in self._stats.items()
+        }
+
+
+agent_stats = AgentStats()
+
+
+class ObservabilityMiddleware(Middleware):
+    """记录模型和工具调用耗时，并可选地创建 OpenTelemetry span。"""
+
+    def __init__(
+        self,
+        thread_id: str = "default",
+        log_level: int = logging.INFO,
+        enable_otel: bool = False,
+    ) -> None:
+        self._thread_id = thread_id
+        self._log_level = log_level
+        # 同一个 Agent 可被多个会话并发复用，计时状态必须按异步任务隔离。
+        self._model_state: ContextVar[tuple[float, Any | None]] = ContextVar(
+            f"agent_core_observability_model_{id(self)}",
+            default=(0.0, None),
+        )
+        self._tool_start: ContextVar[float] = ContextVar(
+            f"agent_core_observability_tool_{id(self)}",
+            default=0.0,
+        )
+        self._tracer = _get_tracer() if enable_otel else None
+
+    def _context_thread_id(self, ctx: MiddlewareContext) -> str:
+        return str(ctx.metadata.get("thread_id") or self._thread_id)
+
+    async def before_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        call_start = time.perf_counter()
+        span = None
+        if self._tracer:
+            span = self._tracer.start_span(f"llm.call.iter{ctx.iteration}")
+            span.set_attribute("iteration", ctx.iteration)
+            span.set_attribute("message_count", len(ctx.messages))
+        self._model_state.set((call_start, span))
+        thread_id = self._context_thread_id(ctx)
+        logger.log(
+            self._log_level,
+            "[Obs] LLM call start: thread=%s iter=%d msgs=%d",
+            thread_id,
+            ctx.iteration,
+            len(ctx.messages),
+        )
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def after_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        call_start, span = self._model_state.get()
+        latency_ms = (time.perf_counter() - call_start) * 1000 if call_start else 0.0
+        response = ctx.llm_response
+        tool_calls = len(response.tool_calls) if response else 0
+        thread_id = self._context_thread_id(ctx)
+        agent_stats.record_llm_call(
+            thread_id=thread_id,
+            iteration=ctx.iteration,
+            latency_ms=latency_ms,
+            input_messages=len(ctx.messages),
+            tool_calls=tool_calls,
+        )
+        logger.log(
+            self._log_level,
+            "[Obs] LLM call done: thread=%s iter=%d latency=%.0fms content=%d tool_calls=%d",
+            thread_id,
+            ctx.iteration,
+            latency_ms,
+            len(response.content) if response else 0,
+            tool_calls,
+        )
+        if span:
+            span.set_attribute("latency_ms", latency_ms)
+            span.set_attribute("tool_calls", tool_calls)
+            span.end()
+        self._model_state.set((0.0, None))
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def handle_exception(self, exc: Exception, ctx: MiddlewareContext) -> bool:
+        """关闭失败模型调用的 span；观测中间件本身不决定是否重试。"""
+        del ctx
+        call_start, span = self._model_state.get()
+        if span is not None:
+            record_exception = getattr(span, "record_exception", None)
+            if record_exception is not None:
+                record_exception(exc)
+            if call_start:
+                span.set_attribute("latency_ms", (time.perf_counter() - call_start) * 1000)
+            span.end()
+        self._model_state.set((0.0, None))
+        return False
+
+    async def before_tool(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        self._tool_start.set(time.perf_counter())
+        logger.log(self._log_level, "[Obs] Tool call start: %s args=%s", ctx.tool_name, ctx.tool_args)
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def after_tool(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        tool_start = self._tool_start.get()
+        latency_ms = (time.perf_counter() - tool_start) * 1000 if tool_start else 0.0
+        agent_stats.record_tool_call(
+            thread_id=self._context_thread_id(ctx),
+            tool_name=ctx.tool_name or "unknown",
+            latency_ms=latency_ms,
+            success=bool(ctx.metadata.get("tool_success", True)),
+        )
+        logger.log(
+            self._log_level,
+            "[Obs] Tool call done: %s latency=%.0fms result_len=%d",
+            ctx.tool_name,
+            latency_ms,
+            len(ctx.tool_result) if ctx.tool_result else 0,
+        )
+        self._tool_start.set(0.0)
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+
+def _get_tracer() -> Any:
+    """按需获取 OTel tracer，未安装依赖时返回 None。"""
+    try:
+        from opentelemetry import trace
+
+        return trace.get_tracer("zero-agent-core")
+    except ImportError:
+        logger.warning("opentelemetry-sdk 未安装，OTel 追踪已禁用")
+        return None
+
+
+def setup_tracing(
+    service_name: str = "handwritten-agent",
+    otlp_endpoint: str | None = None,
+    console_export: bool = False,
+) -> bool:
+    """配置可选的 OpenTelemetry 导出器。"""
+    try:
+        from opentelemetry import trace
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import (
+            BatchSpanProcessor,
+            SimpleSpanProcessor,
+        )
+    except ImportError:
+        logger.warning("opentelemetry-sdk 未安装，跳过 tracing 配置")
+        return False
+
+    provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+    if console_export:
+        from opentelemetry.sdk.trace.export import ConsoleSpanExporter
+
+        provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
+    if otlp_endpoint:
+        try:
+            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                OTLPSpanExporter,
+            )
+
+            provider.add_span_processor(
+                BatchSpanProcessor(OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True))
+            )
+        except ImportError:
+            logger.warning("OTLP 导出依赖未安装，跳过远端 tracing")
+    trace.set_tracer_provider(provider)
+    return True
+
+
+__all__ = [
+    "AgentStats",
+    "CallRecord",
+    "ObservabilityMiddleware",
+    "ThreadStats",
+    "ToolRecord",
+    "agent_stats",
+    "setup_tracing",
+]

agent_core/ports/__init__.py

@@ -0,0 +1,31 @@
+"""Agent Core 的可替换外部端口。"""
+
+from agent_core.ports.memory import MemoryRecord, MemorySearchResult, MemoryStore
+from agent_core.ports.model_selection import (
+    ModelSelection,
+    ModelSelectionScope,
+    ModelSelectionStore,
+)
+from agent_core.ports.storage import (
+    ApprovalStore,
+    ContextStore,
+    EventSink,
+    RunStore,
+    SessionStore,
+    WorkflowStore,
+)
+
+__all__ = [
+    "ApprovalStore",
+    "ContextStore",
+    "EventSink",
+    "MemoryRecord",
+    "MemorySearchResult",
+    "MemoryStore",
+    "ModelSelection",
+    "ModelSelectionScope",
+    "ModelSelectionStore",
+    "RunStore",
+    "SessionStore",
+    "WorkflowStore",
+]

agent_core/ports/memory.py

@@ -0,0 +1,130 @@
+"""跨会话长期记忆的值对象和存储端口。"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Protocol, runtime_checkable
+
+from agent_core.access import AccessContext
+
+
+def memory_now() -> str:
+    """返回可排序的 UTC ISO 时间。"""
+
+    return datetime.now(UTC).isoformat()
+
+
+@dataclass
+class MemoryRecord:
+    """一条可跨会话检索的长期记忆。"""
+
+    namespace: str
+    content: str
+    memory_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    key: str | None = None
+    user_id: str | None = None
+    tenant_id: str | None = None
+    source: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    expires_at: str | None = None
+    version: int = 0
+    created_at: str = field(default_factory=memory_now)
+    updated_at: str = field(default_factory=memory_now)
+
+    def __post_init__(self) -> None:
+        if not self.namespace.strip():
+            raise ValueError("记忆 namespace 不能为空")
+        if not self.memory_id.strip():
+            raise ValueError("memory_id 不能为空")
+
+    def is_expired(self, *, now: datetime | None = None) -> bool:
+        if self.expires_at is None:
+            return False
+        expires = datetime.fromisoformat(self.expires_at.replace("Z", "+00:00"))
+        if expires.tzinfo is None:
+            expires = expires.replace(tzinfo=UTC)
+        return expires <= (now or datetime.now(UTC))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "memory_id": self.memory_id,
+            "namespace": self.namespace,
+            "key": self.key,
+            "content": self.content,
+            "user_id": self.user_id,
+            "tenant_id": self.tenant_id,
+            "source": self.source,
+            "metadata": self.metadata,
+            "expires_at": self.expires_at,
+            "version": self.version,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> MemoryRecord:
+        return cls(
+            memory_id=str(value["memory_id"]),
+            namespace=str(value["namespace"]),
+            key=value.get("key"),
+            content=str(value.get("content", "")),
+            user_id=value.get("user_id"),
+            tenant_id=value.get("tenant_id"),
+            source=value.get("source"),
+            metadata=dict(value.get("metadata") or {}),
+            expires_at=value.get("expires_at"),
+            version=int(value.get("version", 0)),
+            created_at=str(value.get("created_at") or memory_now()),
+            updated_at=str(value.get("updated_at") or memory_now()),
+        )
+
+
+@dataclass(frozen=True)
+class MemorySearchResult:
+    """长期记忆检索结果。"""
+
+    record: MemoryRecord
+    score: float
+
+
+@runtime_checkable
+class MemoryStore(Protocol):
+    """跨会话记忆存储协议，语义向量适配器也实现该端口。"""
+
+    async def put(
+        self,
+        record: MemoryRecord,
+        *,
+        expected_version: int | None = None,
+        access: AccessContext | None = None,
+    ) -> MemoryRecord: ...
+
+    async def get(
+        self,
+        memory_id: str,
+        *,
+        access: AccessContext | None = None,
+    ) -> MemoryRecord | None: ...
+
+    async def delete(
+        self,
+        memory_id: str,
+        *,
+        expected_version: int | None = None,
+        access: AccessContext | None = None,
+    ) -> bool: ...
+
+    async def search(
+        self,
+        namespace: str,
+        *,
+        query: str = "",
+        metadata: dict[str, Any] | None = None,
+        limit: int = 20,
+        access: AccessContext | None = None,
+    ) -> list[MemorySearchResult]: ...
+
+
+__all__ = ["MemoryRecord", "MemorySearchResult", "MemoryStore", "memory_now"]