my-pi-agent 0.1.0

package/src/my_agent_llm/models.py

@@ -0,0 +1,195 @@
+"""统一数据模型：保证内部数据流通，屏蔽 provider 差异。"""
+
+import json
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class TurnOutcome(str, Enum):
+    """Provider 中立的单轮终止原因（对标 pig-llm）。"""
+
+    COMPLETED = "completed"
+    TOOL_CALLS = "tool_calls"
+    LENGTH = "length"
+    CONTENT_FILTER = "content_filter"
+    ABORTED = "aborted"
+    PROVIDER_ERROR = "provider_error"
+    UNKNOWN = "unknown"
+
+
+_COMPLETED_REASONS = {
+    "stop",
+    "end_turn",
+    "complete",
+    "completed",
+    "stop_sequence",
+    "natural",
+    "success",
+    "done",
+}
+_TOOL_REASONS = {"tool_calls", "tool_use", "function_call", "function_calls"}
+_LENGTH_REASONS = {
+    "length",
+    "max_tokens",
+    "max_output_tokens",
+    "model_length",
+    "token_limit",
+}
+_FILTER_REASONS = {"content_filter", "safety", "blocked", "recitation", "prohibited"}
+_ABORT_REASONS = {"aborted", "cancelled", "canceled", "interrupt", "interrupted"}
+_ERROR_REASONS = {"error", "failed", "failure", "provider_error"}
+
+
+def normalize_finish_reason(
+    reason: str | None, has_tool_calls: bool = False
+) -> TurnOutcome:
+    """归一化各厂商私有 finish_reason 为中立枚举。"""
+    if reason is None:
+        return TurnOutcome.TOOL_CALLS if has_tool_calls else TurnOutcome.COMPLETED
+    norm = reason.strip().lower().rsplit(".", maxsplit=1)[-1]
+    if norm in _COMPLETED_REASONS:
+        return TurnOutcome.TOOL_CALLS if has_tool_calls else TurnOutcome.COMPLETED
+    if norm in _TOOL_REASONS:
+        return TurnOutcome.TOOL_CALLS
+    if norm in _LENGTH_REASONS:
+        return TurnOutcome.LENGTH
+    if norm in _FILTER_REASONS:
+        return TurnOutcome.CONTENT_FILTER
+    if norm in _ABORT_REASONS:
+        return TurnOutcome.ABORTED
+    if norm in _ERROR_REASONS:
+        return TurnOutcome.PROVIDER_ERROR
+    return TurnOutcome.TOOL_CALLS if has_tool_calls else TurnOutcome.UNKNOWN
+
+
+class Message(BaseModel):
+    """统一消息：role + content + 附加元数据（tool_calls / tool_call_id 等）。"""
+
+    role: Literal["system", "developer", "user", "assistant", "tool"]
+    content: str
+    metadata: dict[str, Any] | None = None
+
+
+class ToolCallFunction(BaseModel):
+    """tool_call 的 function 子对象（保留以兼容历史导入）。"""
+
+    name: str
+    arguments: str
+
+
+class ToolCall(BaseModel):
+    """统一结构化工具调用对象（对标 Tau / Pi）。
+
+    参数在模型层完成反序列化，核心层直接消费字典，彻底告别四重 JSON 编解码。
+    """
+
+    id: str
+    name: str
+    args: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_wire_dict(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "function" in data and "name" not in data:
+            fn = data.get("function")
+            if isinstance(fn, dict):
+                name = fn.get("name", "")
+                raw_args = fn.get("arguments", "{}")
+            else:
+                name = getattr(fn, "name", "")
+                raw_args = getattr(fn, "arguments", "{}")
+            error = None
+            if isinstance(raw_args, str):
+                try:
+                    if raw_args.strip():
+                        parsed = json.loads(raw_args)
+                        if isinstance(parsed, dict):
+                            args = parsed
+                        else:
+                            error = f"Tool arguments must be a dict, got {type(parsed).__name__}"
+                            args = {}
+                    else:
+                        error = "Malformed JSON arguments: empty string"
+                        args = {}
+                except Exception as exc:
+                    args = {}
+                    error = f"Malformed JSON arguments: {exc}"
+            elif isinstance(raw_args, dict):
+                args = raw_args
+            else:
+                args = {}
+            return {
+                "id": data.get("id", ""),
+                "name": name,
+                "args": args,
+                "error": error,
+            }
+        return data
+
+    def to_wire_dict(self) -> dict[str, Any]:
+        """兼容 OpenAI wire 形状 dict（用于对外导出或与旧协议对接）。"""
+        return {
+            "id": self.id,
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "arguments": json.dumps(self.args, ensure_ascii=False),
+            },
+        }
+
+
+class Response(BaseModel):
+    """统一响应：文本 + 工具调用 + usage + reasoning。"""
+
+    content: str
+    model: str
+    tool_calls: list[ToolCall] | None = None
+    reasoning_content: str | None = None
+    usage: dict[str, int] | None = None
+    finish_reason: str | None = None
+
+    @property
+    def outcome(self) -> TurnOutcome:
+        """中立化的终止状态。"""
+        return normalize_finish_reason(self.finish_reason, bool(self.tool_calls))
+
+    def to_message(
+        self,
+        role: Literal["system", "developer", "user", "assistant", "tool"] = "assistant",
+        stop_reason: str | None = None,
+    ) -> Message:
+        """将模型层完整响应直接转换为标准 Message 实体，彻底消除调度层手动累加拼装。"""
+        meta: dict[str, Any] = {}
+        if self.tool_calls:
+            meta["tool_calls"] = [
+                tc.model_dump() if hasattr(tc, "model_dump") else tc
+                for tc in self.tool_calls
+            ]
+        if self.usage:
+            meta["usage"] = self.usage
+        if self.reasoning_content:
+            meta["reasoning_content"] = self.reasoning_content
+        effective_stop = stop_reason or self.outcome.value
+        if effective_stop:
+            meta["stop_reason"] = effective_stop
+        return Message(role=role, content=self.content, metadata=meta if meta else None)
+
+
+class StreamChunk(BaseModel):
+    """流式增量块：文本增量 + 末块携带完整 tool_calls 与终态已拼装好的 Response。"""
+
+    content: str
+    finish_reason: str | None = None
+    tool_calls: list[ToolCall] | None = None
+    usage: dict[str, int] | None = None
+    metadata: dict[str, Any] | None = None
+    response: Response | None = None
+
+    @property
+    def outcome(self) -> TurnOutcome | None:
+        if self.finish_reason is None and not self.tool_calls:
+            return None
+        return normalize_finish_reason(self.finish_reason, bool(self.tool_calls))

package/src/my_agent_llm/providers/__init__.py

@@ -0,0 +1,4 @@
+"""Provider 实现集合。"""
+from ._base import Provider
+
+__all__ = ["Provider"]

package/src/my_agent_llm/providers/_base.py

@@ -0,0 +1,94 @@
+"""Provider 抽象基类：统一接口，翻译全在子类内部。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from ..config import Config  # pyright: ignore[reportMissingImports]
+from ..events import StreamEvent  # pyright: ignore[reportMissingImports]
+from ..models import (  # pyright: ignore[reportMissingImports]
+    Message,
+    Response,
+    StreamChunk,
+)
+
+
+class Provider(ABC):
+    """各 provider 的统一接口。"""
+
+    @abstractmethod
+    def __init__(self, config: Config):
+        """统一构造契约：所有 provider 都收 Config。"""
+
+    @abstractmethod
+    def chat(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict] | None = None,
+        **kwargs,
+    ) -> Response:
+        """同步对话。"""
+
+    @abstractmethod
+    def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict] | None = None,
+        **kwargs,
+    ) -> Iterator[StreamChunk]:
+        """同步流式。"""
+
+    @abstractmethod
+    async def achat(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict] | None = None,
+        **kwargs,
+    ) -> Response:
+        """异步对话。"""
+
+    @abstractmethod
+    async def achat_stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict] | None = None,
+        **kwargs,
+    ) -> AsyncIterator[StreamChunk]:
+        """异步流式。"""
+        yield StreamChunk(
+            content=""
+        )  # 抽象标记：子类必须实现为异步生成器（基类永不执行）
+
+    async def astream_events(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict] | None = None,
+        signal: Any | None = None,
+        **kwargs,
+    ) -> AsyncIterator[StreamEvent]:
+        """异步高阶流式事件流（对标 Tau stream_response）。
+
+        默认实现：使用 StreamAccumulator 包装底层 achat_stream 原始流。
+        """
+        from ..stream import (  # pyright: ignore[reportMissingImports]
+            StreamAccumulator,
+        )
+
+        acc = StreamAccumulator()
+        async for ev in acc.stream(
+            self.achat_stream(messages, model=model, tools=tools, **kwargs),
+            signal=signal,
+        ):
+            yield ev

package/src/my_agent_llm/providers/anthropic.py

@@ -0,0 +1,298 @@
+# pyright: reportArgumentType=false, reportCallIssue=false
+"""Anthropic provider：block 双向翻译 + 原生 web_search 增强。"""
+
+import json
+from collections.abc import AsyncIterator, Iterator
+
+import anthropic
+
+from ..config import Config
+from ..models import Message, Response, StreamChunk, ToolCall
+from ._base import Provider
+
+
+class AnthropicProvider(Provider):
+    """Anthropic (Claude) provider 实现。"""
+
+    def __init__(self, config: Config, client=None, async_client=None):
+        """初始化。client/async_client 可注入（测试缝隙）。"""
+        self.config = config
+        if client is not None:
+            self.client = client
+            self.async_client = async_client
+            return
+        kwargs = {
+            "api_key": config.api_key,
+            "timeout": config.timeout,
+            "max_retries": config.max_retries,
+        }
+        if config.base_url:
+            kwargs["base_url"] = config.base_url
+        self.client = anthropic.Anthropic(**kwargs)
+        self.async_client = anthropic.AsyncAnthropic(**kwargs)
+
+    def _convert_messages(self, messages: list[Message]) -> tuple[str | None, list[dict]]:
+        """Message → Anthropic 格式。返回 (system, messages)。"""
+        system_message = None
+        anthropic_messages = []
+        for msg in messages:
+            if msg.role == "system":
+                system_message = msg.content
+            elif msg.role == "assistant" and msg.metadata and "tool_calls" in msg.metadata:
+                content = []
+                if msg.content:
+                    content.append({"type": "text", "text": msg.content})
+                for tc in msg.metadata["tool_calls"]:
+                    if isinstance(tc, ToolCall):
+                        tc_id = tc.id
+                        tc_name = tc.name
+                        tc_args = tc.args
+                    elif isinstance(tc, dict):
+                        tc_id = tc.get("id", "")
+                        if "name" in tc and "args" in tc:
+                            tc_name = tc["name"]
+                            tc_args = tc["args"]
+                        elif "function" in tc:
+                            tc_name = tc["function"].get("name", "")
+                            raw = tc["function"].get("arguments", "{}")
+                            try:
+                                tc_args = (
+                                    json.loads(raw)
+                                    if isinstance(raw, str) and raw.strip()
+                                    else (raw if isinstance(raw, dict) else {})
+                                )
+                            except Exception:
+                                tc_args = {}
+                        else:
+                            tc_name = tc.get("name", "")
+                            tc_args = tc.get("args", {})
+                    else:
+                        tc_id = getattr(tc, "id", "")
+                        tc_name = getattr(tc, "name", "")
+                        tc_args = getattr(tc, "args", {})
+                    content.append(
+                        {
+                            "type": "tool_use",
+                            "id": tc_id,
+                            "name": tc_name,
+                            "input": tc_args,
+                        }
+                    )
+                anthropic_messages.append({"role": "assistant", "content": content})
+            elif msg.role == "tool" and msg.metadata:
+                anthropic_messages.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": msg.metadata.get("tool_call_id"),
+                                "content": msg.content,
+                            }
+                        ],
+                    }
+                )
+            else:
+                anthropic_messages.append({"role": msg.role, "content": msg.content})
+        return system_message, anthropic_messages
+
+    def _convert_tools(self, tools: list[dict] | None) -> list[dict] | None:
+        """OpenAI 形状 tools → Anthropic 格式。"""
+        if not tools:
+            return None
+        out = []
+        for tool in tools:
+            if tool.get("type") == "function":
+                func = tool["function"]
+                out.append(
+                    {
+                        "name": func["name"],
+                        "description": func.get("description", ""),
+                        "input_schema": func.get("parameters", {}),
+                    }
+                )
+        return out or None
+
+    def _resolve_tools(self, tools, kwargs) -> list[dict] | None:
+        """function tools + 可选原生 web_search。"""
+        enable_web = kwargs.pop("enable_web_search", False)
+        max_uses = kwargs.pop("web_search_max_uses", 5)
+        out = self._convert_tools(tools) or []
+        if enable_web:
+            out = list(out)
+            out.append(
+                {
+                    "type": "web_search_20250305",
+                    "name": "web_search",
+                    "max_uses": max_uses,
+                }
+            )
+        return out or None
+
+    @staticmethod
+    def _extract_content(blocks) -> str:
+        """text blocks → content。"""
+        return "".join(b.text for b in blocks if getattr(b, "type", None) == "text")
+
+    @staticmethod
+    def _extract_reasoning(blocks) -> str | None:
+        """thinking blocks → reasoning_content。"""
+        parts = [b.thinking for b in blocks if getattr(b, "type", None) == "thinking" and getattr(b, "thinking", None)]
+        return "".join(parts) or None
+
+    @staticmethod
+    def _extract_tool_calls(blocks) -> list[ToolCall] | None:
+        """tool_use blocks → 统一 ToolCall。原生使用 block.input (dict)，消灭冗余 dumps。"""
+        out = []
+        for block in blocks:
+            if getattr(block, "type", None) == "tool_use":
+                input_args = getattr(block, "input", None)
+                args = input_args if isinstance(input_args, dict) else {}
+                out.append(
+                    ToolCall(
+                        id=getattr(block, "id", ""),
+                        name=getattr(block, "name", ""),
+                        args=args,
+                    )
+                )
+        return out or None
+
+    @staticmethod
+    def _extract_usage(response) -> dict[str, int] | None:
+        """从 Anthropic 响应提取完整 usage（含 Prompt 缓存读取与写入）。"""
+        u = getattr(response, "usage", None)
+        if u is None:
+            return None
+        try:
+            in_t = int(getattr(u, "input_tokens", 0) or 0)
+            out_t = int(getattr(u, "output_tokens", 0) or 0)
+            cache_read = int(getattr(u, "cache_read_input_tokens", 0) or 0)
+            cache_write = int(getattr(u, "cache_creation_input_tokens", 0) or 0)
+        except (TypeError, ValueError):
+            in_t, out_t, cache_read, cache_write = 0, 0, 0, 0
+        res = {
+            "prompt_tokens": in_t,
+            "completion_tokens": out_t,
+            "total_tokens": in_t + out_t + cache_read,
+        }
+        if cache_read > 0:
+            res["cache_read_tokens"] = cache_read
+        if cache_write > 0:
+            res["cache_write_tokens"] = cache_write
+        return res
+
+    def chat(self, messages, *, model, tools=None, **kwargs) -> Response:
+        system, ant_messages = self._convert_messages(messages)
+        ant_tools = self._resolve_tools(tools, kwargs)
+        kwargs.pop("tools", None)
+        response = self.client.messages.create(
+            model=model,
+            messages=ant_messages,
+            system=system,
+            max_tokens=kwargs.pop("max_tokens", 4096),
+            **({"tools": ant_tools} if ant_tools else {}),
+            **kwargs,
+        )
+        return Response(
+            content=self._extract_content(response.content),
+            model=response.model,
+            reasoning_content=self._extract_reasoning(response.content),
+            usage=self._extract_usage(response),
+            finish_reason=response.stop_reason,
+            tool_calls=self._extract_tool_calls(response.content),
+        )
+
+    def stream(self, messages, *, model, tools=None, **kwargs) -> Iterator[StreamChunk]:
+        system, ant_messages = self._convert_messages(messages)
+        ant_tools = self._resolve_tools(tools, kwargs)
+        kwargs.pop("tools", None)
+        with self.client.messages.stream(
+            model=model,
+            messages=ant_messages,
+            system=system,
+            max_tokens=kwargs.pop("max_tokens", 4096),
+            **({"tools": ant_tools} if ant_tools else {}),
+            **kwargs,
+        ) as stream:
+            for text in stream.text_stream:
+                yield StreamChunk(content=text, finish_reason=None)
+            final = stream.get_final_message()
+            tool_calls = self._extract_tool_calls(final.content)
+            reasoning = self._extract_reasoning(final.content)
+            usage = self._extract_usage(final)
+            final_response = Response(
+                content=self._extract_content(final.content),
+                model=final.model,
+                reasoning_content=reasoning,
+                usage=usage,
+                finish_reason=final.stop_reason,
+                tool_calls=tool_calls,
+            )
+            yield StreamChunk(
+                content="",
+                tool_calls=tool_calls,
+                usage=usage,
+                finish_reason=final.stop_reason,
+                metadata={"reasoning_content": reasoning} if reasoning else None,
+                response=final_response,
+            )
+
+    async def achat(self, messages, *, model, tools=None, **kwargs) -> Response:
+        if self.async_client is None:
+            raise RuntimeError("async_client not provided; cannot run async methods")
+        system, ant_messages = self._convert_messages(messages)
+        ant_tools = self._resolve_tools(tools, kwargs)
+        kwargs.pop("tools", None)
+        response = await self.async_client.messages.create(  # pyright: ignore[reportCallIssue, reportArgumentType]
+            model=model,
+            messages=ant_messages,
+            system=system,
+            max_tokens=kwargs.pop("max_tokens", 4096),
+            **({"tools": ant_tools} if ant_tools else {}),
+            **kwargs,
+        )
+        return Response(
+            content=self._extract_content(response.content),
+            model=response.model,
+            reasoning_content=self._extract_reasoning(response.content),
+            usage=self._extract_usage(response),
+            finish_reason=response.stop_reason,
+            tool_calls=self._extract_tool_calls(response.content),
+        )
+
+    async def achat_stream(self, messages, *, model, tools=None, **kwargs) -> AsyncIterator[StreamChunk]:
+        if self.async_client is None:
+            raise RuntimeError("async_client not provided; cannot run async methods")
+        system, ant_messages = self._convert_messages(messages)
+        ant_tools = self._resolve_tools(tools, kwargs)
+        kwargs.pop("tools", None)
+        async with self.async_client.messages.stream(  # pyright: ignore[reportCallIssue, reportArgumentType]
+            model=model,
+            messages=ant_messages,
+            system=system,
+            max_tokens=kwargs.pop("max_tokens", 4096),
+            **({"tools": ant_tools} if ant_tools else {}),
+            **kwargs,
+        ) as stream:
+            async for text in stream.text_stream:
+                yield StreamChunk(content=text, finish_reason=None)
+            final = await stream.get_final_message()
+            tool_calls = self._extract_tool_calls(final.content)
+            reasoning = self._extract_reasoning(final.content)
+            usage = self._extract_usage(final)
+            final_response = Response(
+                content=self._extract_content(final.content),
+                model=final.model,
+                reasoning_content=reasoning,
+                usage=usage,
+                finish_reason=final.stop_reason,
+                tool_calls=tool_calls,
+            )
+            yield StreamChunk(
+                content="",
+                tool_calls=tool_calls,
+                usage=usage,
+                finish_reason=final.stop_reason,
+                metadata={"reasoning_content": reasoning} if reasoning else None,
+                response=final_response,
+            )