uss-aigent 0.1.1__py3-none-any.whl

aigent/__init__.py

@@ -0,0 +1,68 @@
+# Copyright 2026 樊少冰
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Aigent — 渐进式 LLM API 库
+
+用法速览：
+
+    from aigent import Aigent, tool, Message
+
+    # ── 第一层：聊天 ──
+    agent = Aigent(api_type="openai", system="你是专业翻译")
+    with agent.session() as s:
+        s.chat("翻成英文")
+
+    # ── 第二层：工具 ──
+    @tool
+    def get_weather(city: str) -> str:
+        \"\"\"查询天气\"\"\"
+        ...
+
+    with agent.session(tools=[get_weather]) as s:
+        s.chat("北京天气怎么样？")
+
+    # ── 第三层：完全控制 ──
+    resp = agent.raw([Message.user("你好")], max_tokens=100)
+"""
+
+from .agent import Aigent
+from .tool import tool, Tool, ToolParam, ToolCall
+from .message import Message
+from .response import Response, Usage
+from .exceptions import (
+    LLMError,
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+    ConnectionError,
+    TimeoutError,
+)
+
+__all__ = [
+    "Aigent",
+    "tool",
+    "Tool",
+    "ToolParam",
+    "ToolCall",
+    "Message",
+    "Response",
+    "Usage",
+    "LLMError",
+    "AuthenticationError",
+    "RateLimitError",
+    "APIError",
+    "ConnectionError",
+    "TimeoutError",
+]

aigent/agent.py

@@ -0,0 +1,192 @@
+# Copyright 2026 樊少冰
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Aigent 入口类
+
+    from aigent import Aigent
+
+    agent = Aigent(api_type="openai")
+    with agent.session() as s:
+        s.chat("你好")
+"""
+
+import os
+import json
+from typing import Iterator
+
+import httpx
+
+from .session import Session
+from .response import Response
+from .backends import get_backend
+from .exceptions import ConnectionError, TimeoutError
+
+
+class Aigent:
+    """LLM 助手入口。
+
+    持有 API 配置（api_type、api_key、model 等），
+    通过 session() 创建对话，通过 raw() 发送底层请求。
+    """
+
+    def __init__(
+        self,
+        api_type: str = "openai",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str | None = None,
+        system: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        default_headers: dict | None = None,
+    ):
+        """
+        参数：
+        - api_type: "openai" | "anthropic"
+        - api_key: 不传时自动从环境变量读取（OPENAI_API_KEY / ANTHROPIC_API_KEY）
+        - base_url: 不传时按 api_type 取默认值
+        - model: 不传时按 api_type 取默认值
+        - system: 系统提示词，绑定到 agent 级别，所有 session 继承
+        - timeout: HTTP 请求超时（秒）
+        - max_retries: 失败重试次数
+        - default_headers: 附加的 HTTP 请求头（如 Azure 的 api-key）
+        """
+        self._api_type = api_type
+        self._backend_cls = get_backend(api_type)
+        env_map = self._backend_cls.env_key_map
+
+        self._api_key = api_key or os.environ.get(env_map["api_key"])
+        self._base_url = (
+            base_url
+            or os.environ.get(env_map.get("base_url", ""))
+            or self._backend_cls.default_base_url
+        )
+        self._model = (
+            model
+            or os.environ.get(env_map.get("model", ""))
+            or self._backend_cls.default_model
+        )
+        self._system = system
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+
+        self._client = httpx.Client(timeout=self._timeout)
+
+    def session(self, **overrides) -> Session:
+        """创建对话 Session，返回上下文管理器。
+
+        用法：
+            with agent.session() as s:
+                s.chat("你好")
+
+            with agent.session(temperature=0.7, tools=[...]) as s:
+                ...
+
+        可通过 overrides 覆盖 agent 级别的任何配置。
+        """
+        system = overrides.pop("system", self._system)
+        return Session(self, system=system, **overrides)
+
+    def raw(self, messages: list[dict], **kwargs) -> Response:
+        """直接发送消息列表，返回结构化 Response。
+
+        供高级用户手动编排消息时使用：
+            resp = agent.raw([Message.user("你好")], max_tokens=100)
+        """
+        backend = self._backend_cls()
+        tools = kwargs.pop("_tools", None)
+        body = backend.build_request(messages, tools=tools, model=self._model, **kwargs)
+        resp_data = self._send(body)
+        return backend.parse_response(resp_data)
+
+    def _build_headers(self) -> dict:
+        """构造 HTTP 请求头"""
+        headers = {"Content-Type": "application/json"}
+        headers.update(self._default_headers)
+        if self._api_type == "openai":
+            if self._api_key:
+                headers["Authorization"] = f"Bearer {self._api_key}"
+        elif self._api_type == "anthropic":
+            if self._api_key:
+                headers["x-api-key"] = self._api_key
+            headers["anthropic-version"] = "2023-06-01"
+        return headers
+
+    def _send(self, body: dict) -> dict:
+        """发送非流式 HTTP 请求，返回解析后的 JSON"""
+        backend = self._backend_cls()
+        url = f"{self._base_url.rstrip('/')}{backend.endpoint}"
+        headers = self._build_headers()
+
+        try:
+            resp = self._client.post(url, json=body, headers=headers)
+        except httpx.TimeoutException:
+            raise TimeoutError("请求超时")
+        except httpx.NetworkError as e:
+            raise ConnectionError(str(e))
+
+        if resp.status_code >= 400:
+            err_body = {}
+            try:
+                err_body = resp.json()
+            except Exception:
+                pass
+            raise backend.map_error(resp.status_code, err_body)
+
+        return resp.json()
+
+    def _send_stream(self, body: dict) -> Iterator[str]:
+        """发送流式 HTTP 请求，逐 token yield"""
+        backend = self._backend_cls()
+        url = f"{self._base_url.rstrip('/')}{backend.endpoint}"
+        headers = self._build_headers()
+
+        try:
+            with self._client.stream("POST", url, json=body, headers=headers) as resp:
+                if resp.status_code >= 400:
+                    err_body = {}
+                    try:
+                        err_body = resp.json()
+                    except Exception:
+                        pass
+                    raise backend.map_error(resp.status_code, err_body)
+
+                for line in resp.iter_lines():
+                    line = line.strip()
+                    if not line:
+                        continue
+                    # OpenAI: "data: {...}"  or "data: [DONE]"
+                    # Anthropic: "data: {...}"  (event type in JSON)
+                    if not line.startswith("data: "):
+                        continue
+                    data = line[6:]
+                    if data == "[DONE]":
+                        break
+                    try:
+                        chunk = json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+                    token = backend.parse_stream_chunk(chunk)
+                    if token:
+                        yield token
+        except httpx.TimeoutException:
+            raise TimeoutError("请求超时")
+        except httpx.NetworkError as e:
+            raise ConnectionError(str(e))
+
+    def close(self) -> None:
+        """关闭 HTTP 客户端"""
+        self._client.close()

aigent/backends/__init__.py

@@ -0,0 +1,33 @@
+# Copyright 2026 樊少冰
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""后端适配器注册表"""
+
+from .openai import OpenAIBackend
+from .anthropic import AnthropicBackend
+
+_registry: dict[str, type] = {
+    "openai": OpenAIBackend,
+    "anthropic": AnthropicBackend,
+}
+
+
+def get_backend(api_type: str):
+    """根据 api_type 获取后端类；未注册时抛出 ValueError"""
+    if api_type not in _registry:
+        raise ValueError(
+            f"不支持的 api_type: '{api_type}'，可选值: {list(_registry.keys())}"
+        )
+    return _registry[api_type]

aigent/backends/anthropic.py

@@ -0,0 +1,190 @@
+# Copyright 2026 樊少冰
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Anthropic Messages API 适配器"""
+
+from .base import BaseBackend
+from ..response import Response, Usage
+from ..tool import ToolCall
+from ..exceptions import (
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+)
+
+
+class AnthropicBackend(BaseBackend):
+    """适配 Anthropic Messages API"""
+
+    api_type = "anthropic"
+    default_base_url = "https://api.anthropic.com/v1"
+    default_model = "claude-sonnet-4-6"
+    env_key_map = {
+        "api_key": "ANTHROPIC_API_KEY",
+        "base_url": "ANTHROPIC_BASE_URL",
+        "model": "ANTHROPIC_MODEL",
+    }
+    endpoint = "/messages"
+
+    def build_request(self, messages, tools=None, **kwargs) -> dict:
+        """构造 /messages 请求体（需转换消息格式）"""
+        anthropic_messages: list[dict] = []
+        system_parts: list[str] = []
+
+        for msg in messages:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+
+            if role == "system":
+                system_parts.append(content)
+                continue
+
+            if role == "tool":
+                # 工具结果 → user message with tool_result content block
+                anthropic_messages.append({
+                    "role": "user",
+                    "content": [{
+                        "type": "tool_result",
+                        "tool_use_id": msg.get("tool_call_id", ""),
+                        "content": content,
+                    }],
+                })
+                continue
+
+            if role == "assistant" and msg.get("tool_calls"):
+                # Assistant 请求工具调用 → content blocks with tool_use
+                content_blocks: list[dict] = []
+                # 保留 thinking 块（扩展思考模式必须回传）
+                for tb in msg.get("thinking_blocks", []):
+                    content_blocks.append(tb)
+                if content:
+                    content_blocks.append({"type": "text", "text": content})
+                for tc in msg["tool_calls"]:
+                    content_blocks.append({
+                        "type": "tool_use",
+                        "id": tc["id"],
+                        "name": tc["name"],
+                        "input": tc["arguments"],
+                    })
+                anthropic_messages.append({"role": "assistant", "content": content_blocks})
+                continue
+
+            if role == "assistant":
+                content_blocks = []
+                for tb in msg.get("thinking_blocks", []):
+                    content_blocks.append(tb)
+                content_blocks.append({"type": "text", "text": content})
+                anthropic_messages.append({
+                    "role": "assistant",
+                    "content": content_blocks,
+                })
+                continue
+
+            # user or other roles — pass through
+            anthropic_messages.append({"role": role, "content": content})
+
+        body: dict = {
+            "model": kwargs.pop("model", self.default_model),
+            "max_tokens": kwargs.pop("max_tokens", 4096),
+            "messages": anthropic_messages,
+            **kwargs,
+        }
+
+        if system_parts:
+            body["system"] = "\n\n".join(system_parts)
+
+        if tools:
+            body["tools"] = [self._convert_tool(t) for t in tools]
+
+        return body
+
+    @staticmethod
+    def _convert_tool(t) -> dict:
+        """将 Tool.to_dict() (OpenAI 格式) 转为 Anthropic 格式"""
+        od = t.to_dict()
+        func = od["function"]
+        params = func["parameters"]
+        return {
+            "name": func["name"],
+            "description": func["description"],
+            "input_schema": {
+                "type": "object",
+                "properties": params.get("properties", {}),
+                "required": params.get("required", []),
+            },
+        }
+
+    def parse_response(self, raw: dict) -> Response:
+        """解析 Anthropic message 响应为 Response"""
+        content_blocks = raw.get("content", [])
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+        thinking_blocks: list[dict] = []
+
+        for block in content_blocks:
+            block_type = block.get("type", "")
+            if block_type == "text":
+                text_parts.append(block.get("text", ""))
+            elif block_type == "thinking":
+                thinking_blocks.append(block)
+            elif block_type == "tool_use":
+                tool_calls.append(
+                    ToolCall(
+                        id=block.get("id", ""),
+                        name=block.get("name", ""),
+                        arguments=block.get("input", {}),
+                    )
+                )
+
+        content = "\n".join(text_parts) if text_parts else None
+
+        usage = None
+        if "usage" in raw:
+            u = raw["usage"]
+            usage = Usage(
+                prompt_tokens=u.get("input_tokens", 0),
+                completion_tokens=u.get("output_tokens", 0),
+                total_tokens=u.get("input_tokens", 0) + u.get("output_tokens", 0),
+            )
+
+        return Response(
+            content=content,
+            tool_calls=tool_calls,
+            thinking_blocks=thinking_blocks,
+            usage=usage,
+            model=raw.get("model", ""),
+            finish_reason=raw.get("stop_reason"),
+            raw=raw,
+        )
+
+    def parse_stream_chunk(self, chunk: dict) -> str | None:
+        """从 SSE event 中提取 text delta"""
+        event_type = chunk.get("type", "")
+        if event_type == "content_block_delta":
+            delta = chunk.get("delta", {})
+            if delta.get("type") == "text_delta":
+                return delta.get("text")
+        return None
+
+    def map_error(self, status_code: int, body: dict) -> Exception:
+        """映射 Anthropic 错误码"""
+        err = body.get("error", {})
+        msg = err.get("message", str(body))
+        if status_code == 401:
+            return AuthenticationError(msg)
+        elif status_code == 429:
+            return RateLimitError(msg)
+        else:
+            return APIError(status_code, msg, body)

aigent/backends/base.py

@@ -0,0 +1,55 @@
+# Copyright 2026 樊少冰
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""后端适配器抽象基类"""
+
+from abc import ABC, abstractmethod
+
+from ..response import Response
+
+
+class BaseBackend(ABC):
+    """API 后端的抽象基类。
+
+    每个子类负责：
+    - 将统一的消息格式转换为 API 特定的请求格式
+    - 将 API 特定的响应转换为统一的 Response
+    - 将 API 特定的错误码转换为 LLMError 子类
+    """
+
+    api_type: str
+    default_base_url: str
+    default_model: str
+    env_key_map: dict  # {"api_key": "OPENAI_API_KEY", "base_url": "OPENAI_BASE_URL", "model": "OPENAI_MODEL"}
+
+    @abstractmethod
+    def build_request(self, messages: list[dict], tools: list | None = None, **kwargs) -> dict:
+        """将统一消息列表 + 工具转换为 API 请求体"""
+        ...
+
+    @abstractmethod
+    def parse_response(self, raw: dict) -> Response:
+        """将 API 原始响应转换为统一的 Response"""
+        ...
+
+    @abstractmethod
+    def parse_stream_chunk(self, chunk: dict) -> str | None:
+        """从 SSE chunk 中提取 token 文本；无内容时返回 None"""
+        ...
+
+    @abstractmethod
+    def map_error(self, status_code: int, body: dict) -> Exception:
+        """将 HTTP 状态码 + 响应体映射为对应的 LLMError 子类"""
+        ...

aigent/backends/openai.py

@@ -0,0 +1,147 @@
+# Copyright 2026 樊少冰
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""OpenAI Chat Completions API 适配器"""
+
+import json
+from .base import BaseBackend
+from ..response import Response, Usage
+from ..tool import ToolCall
+from ..exceptions import (
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+)
+
+
+class OpenAIBackend(BaseBackend):
+    """适配 OpenAI Chat Completions API（及所有兼容服务，如 Ollama、DeepSeek 等）"""
+
+    api_type = "openai"
+    default_base_url = "https://api.openai.com/v1"
+    default_model = "gpt-4o"
+    env_key_map = {
+        "api_key": "OPENAI_API_KEY",
+        "base_url": "OPENAI_BASE_URL",
+        "model": "OPENAI_MODEL",
+    }
+    endpoint = "/chat/completions"
+
+    def build_request(self, messages, tools=None, **kwargs) -> dict:
+        """构造 /chat/completions 请求体（需转换消息格式）"""
+        openai_messages: list[dict] = []
+
+        for msg in messages:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+
+            if role == "assistant" and msg.get("tool_calls"):
+                # 转换 tool_calls：内部格式 → OpenAI 格式
+                openai_tool_calls: list[dict] = []
+                for tc in msg["tool_calls"]:
+                    openai_tool_calls.append({
+                        "id": tc["id"],
+                        "type": "function",
+                        "function": {
+                            "name": tc["name"],
+                            "arguments": json.dumps(tc["arguments"], ensure_ascii=False),
+                        },
+                    })
+                assistant_msg: dict = {
+                    "role": "assistant",
+                    "content": content or None,
+                    "tool_calls": openai_tool_calls,
+                }
+                if msg.get("reasoning_content"):
+                    assistant_msg["reasoning_content"] = msg["reasoning_content"]
+                openai_messages.append(assistant_msg)
+                continue
+
+            # 剥离 Anthropic 专属字段
+            clean_msg = dict(msg)
+            clean_msg.pop("thinking_blocks", None)
+            openai_messages.append(clean_msg)
+
+        body: dict = {
+            "model": kwargs.pop("model", self.default_model),
+            "messages": openai_messages,
+            **kwargs,
+        }
+        if tools:
+            body["tools"] = [t.to_dict() for t in tools]
+        return body
+
+    def parse_response(self, raw: dict) -> Response:
+        """解析 OpenAI chat completion 响应为 Response"""
+        choice = raw.get("choices", [{}])[0]
+        message = choice.get("message", {})
+
+        content = message.get("content")
+        finish_reason = choice.get("finish_reason")
+
+        tool_calls: list[ToolCall] = []
+        raw_tool_calls = message.get("tool_calls", [])
+        for tc in raw_tool_calls:
+            func = tc.get("function", {})
+            try:
+                arguments = json.loads(func.get("arguments", "{}"))
+            except json.JSONDecodeError:
+                arguments = {}
+            tool_calls.append(
+                ToolCall(
+                    id=tc.get("id", ""),
+                    name=func.get("name", ""),
+                    arguments=arguments,
+                )
+            )
+
+        usage = None
+        if "usage" in raw:
+            u = raw["usage"]
+            usage = Usage(
+                prompt_tokens=u.get("prompt_tokens", 0),
+                completion_tokens=u.get("completion_tokens", 0),
+                total_tokens=u.get("total_tokens", 0),
+            )
+
+        reasoning_content = message.get("reasoning_content")
+
+        return Response(
+            content=content,
+            tool_calls=tool_calls,
+            reasoning_content=reasoning_content,
+            usage=usage,
+            model=raw.get("model", ""),
+            finish_reason=finish_reason,
+            raw=raw,
+        )
+
+    def parse_stream_chunk(self, chunk: dict) -> str | None:
+        """从 SSE delta 中提取 content"""
+        choices = chunk.get("choices", [])
+        if not choices:
+            return None
+        delta = choices[0].get("delta", {})
+        return delta.get("content")
+
+    def map_error(self, status_code: int, body: dict) -> Exception:
+        """映射 OpenAI 错误码"""
+        msg = body.get("error", {}).get("message", str(body))
+        if status_code == 401:
+            return AuthenticationError(msg)
+        elif status_code == 429:
+            return RateLimitError(msg)
+        else:
+            return APIError(status_code, msg, body)