pagent 0.1.0__py3-none-any.whl

pagent/__init__.py

@@ -0,0 +1,17 @@
+from .agent import Agent, AgentStats
+from .llm import LLM, RunResult
+from .session import Session
+from .tool import FunctionTool, to_openai_tools, tool
+
+__all__ = [
+    "Agent",
+    "AgentStats",
+    "FunctionTool",
+    "LLM",
+    "RunResult",
+    "Session",
+    "to_openai_tools",
+    "tool",
+]
+
+__version__ = "0.1.0"

pagent/agent.py

@@ -0,0 +1,91 @@
+from .llm import RunResult
+from .tool import to_openai_tools
+
+
+class AgentStats:
+    def __init__(self):
+        self.usage = None
+        self.prompt_tokens = 0
+        self.completion_tokens = 0
+        self.total_tokens = 0
+        self.turns = 0
+
+    def add_usage(self, usage):
+        self.usage = usage
+        self.turns += 1
+        if usage:
+            self.prompt_tokens += usage.prompt_tokens
+            self.completion_tokens += usage.completion_tokens
+            self.total_tokens += usage.total_tokens
+
+    def __str__(self):
+        return (
+            f"turns={self.turns}, "
+            f"prompt_tokens={self.prompt_tokens}, "
+            f"completion_tokens={self.completion_tokens}, "
+            f"total_tokens={self.total_tokens}"
+        )
+
+
+class Agent:
+    def __init__(self, llm, session, tools=None, max_turns=8):
+        self.llm = llm
+        self.session = session
+        self.tools = tools or []
+        self.tool_schemas = to_openai_tools(self.tools)
+        names = [t.name for t in self.tools]
+        if len(names) != len(set(names)):
+            raise ValueError(f"duplicate tool names: {names}")
+        self.tool_map = {t.name: t for t in self.tools}
+        if max_turns < 1:
+            raise ValueError("max_turns must be >= 1")
+        self.max_turns = max_turns
+        self.stats = AgentStats()
+
+    def _execute_tool_calls(self, tool_calls):
+        for tool_call in tool_calls:
+            function_call = tool_call["function"]
+            name = function_call["name"]
+            tc = self.tool_map.get(name)
+            if tc is None:
+                self.session += {
+                    "role": "tool",
+                    "content": f"error: unknown tool {name!r}; available: {sorted(self.tool_map)}",
+                    "tool_call_id": tool_call["id"],
+                }
+                continue
+            tool_result = tc.call(function_call["arguments"])
+            self.session += {
+                "role": "tool",
+                "content": tool_result,
+                "tool_call_id": tool_call["id"],
+            }
+
+    def reset(self):
+        self.session.reset()
+        self.stats = AgentStats()
+
+    async def run(self, user_input):
+        self.session += {"role": "user", "content": user_input}
+        result = RunResult(content="")
+
+        for _ in range(self.max_turns):
+            result = await self.llm.invoke(
+                self.session.messages, tools=self.tool_schemas
+            )
+            if result.tool_calls:
+                self.session += {
+                    "role": "assistant",
+                    "content": result.content or None,
+                    "tool_calls": result.tool_calls,
+                }
+            else:
+                self.session += {"role": "assistant", "content": result.content}
+            self.stats.add_usage(result.usage)
+
+            if not result.has_tool_calls:
+                return result
+
+            self._execute_tool_calls(result.tool_calls)
+
+        return result

pagent/llm.py

@@ -0,0 +1,67 @@
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RunResult:
+    content: str
+    tool_calls: list = field(default_factory=list)
+    usage: object | None = None
+
+    @property
+    def has_tool_calls(self):
+        return len(self.tool_calls) > 0
+
+
+class LLM:
+    """Stateless wrapper: forwards to the model; no history (caller builds ``messages``)."""
+
+    API_KEY_ENV_VAR = "OPENAI_API_KEY"
+    BASE_URL = "https://api.openai.com"
+
+    def __init__(self, model_id, base_url=None, apikey=None, request_kwargs=None):
+        from openai import AsyncOpenAI
+
+        resolved_base_url = (base_url or self.BASE_URL).strip()
+        resolved_apikey = (apikey or self.get_api_key() or "").strip()
+
+        self.base_url = resolved_base_url
+        self.apikey = resolved_apikey
+        self.client = AsyncOpenAI(api_key=self.apikey, base_url=self.base_url)
+        self.model_id = model_id
+        self.request_kwargs = request_kwargs or {}
+
+    def get_api_key(self):
+        return os.getenv(self.API_KEY_ENV_VAR)
+
+    async def invoke(self, messages, tools=None):
+        kwargs = {
+            "model": self.model_id,
+            "messages": messages,
+            "stream": False,
+            **self.request_kwargs,
+        }
+        if tools:
+            kwargs["tools"] = tools
+
+        response = await self.client.chat.completions.create(**kwargs)
+        if not response.choices:
+            return RunResult(content="", tool_calls=[], usage=response.usage)
+        message = response.choices[0].message
+
+        content = message.content or ""
+        tool_calls = []
+        if message.tool_calls:
+            for tool_call in message.tool_calls:
+                tool_calls.append(
+                    {
+                        "id": tool_call.id,
+                        "type": tool_call.type,
+                        "function": {
+                            "name": tool_call.function.name,
+                            "arguments": tool_call.function.arguments,
+                        },
+                    }
+                )
+
+        return RunResult(content=content, tool_calls=tool_calls, usage=response.usage)

pagent/session.py

@@ -0,0 +1,27 @@
+class Session:
+    """Conversation buffer: Chat Completions-shaped message dicts in ``messages``.
+
+    Append: ``session += {"role": "user", "content": "..."}`` or ``session += [msg, ...]``.
+    """
+
+    def __init__(self, system_prompt="You are a helpful assistant."):
+        self.system_prompt = system_prompt
+        self.messages = []
+        if not system_prompt:
+            return
+        self.messages.append({"role": "system", "content": system_prompt})
+
+    def __iadd__(self, other):
+        if isinstance(other, dict):
+            self.messages.append(dict(other))
+        elif isinstance(other, (str, bytes, bytearray)):
+            raise TypeError("session += expects message dict(s), not str/bytes")
+        else:
+            self.messages.extend(dict(m) for m in other)
+        return self
+
+    def reset(self):
+        self.messages.clear()
+        if not self.system_prompt:
+            return
+        self.messages.append({"role": "system", "content": self.system_prompt})

pagent/tool.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import inspect
+import json
+from functools import reduce
+from typing import Any, Union, get_args, get_origin, get_type_hints
+
+from docstring_parser import parse
+
+
+class FunctionTool:
+    def __init__(self, name, description, parameters, func=None):
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self.func = func
+
+    def to_dict(self):
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def call(self, arguments=None):
+        if self.func is None:
+            raise ValueError(f"tool {self.name} has no bound function")
+
+        if arguments is None:
+            payload = {}
+        elif isinstance(arguments, str):
+            if not arguments.strip():
+                payload = {}
+            else:
+                try:
+                    payload = json.loads(arguments)
+                except json.JSONDecodeError as e:
+                    return f"Invalid JSON in tool arguments: {e}"
+        else:
+            payload = arguments
+
+        return str(self.func(**payload))
+
+
+def unwrap_optional(type_hint):
+    origin = get_origin(type_hint)
+    if origin is Union:
+        args = get_args(type_hint)
+        if type(None) in args:
+            non_none_args = [arg for arg in args if arg is not type(None)]
+            if len(non_none_args) == 1:
+                return True, non_none_args[0]
+            return True, reduce(lambda x, y: x | y, non_none_args)
+    return False, type_hint
+
+
+def type_to_schema(type_hint):
+    origin = get_origin(type_hint)
+    if origin is list:
+        args = get_args(type_hint)
+        item_type = args[0] if args else Any
+        return {"type": "array", "items": type_to_schema(item_type)}
+    if origin is dict:
+        return {"type": "object"}
+    if type_hint is str:
+        return {"type": "string"}
+    if type_hint is int:
+        return {"type": "integer"}
+    if type_hint is float:
+        return {"type": "number"}
+    if type_hint is bool:
+        return {"type": "boolean"}
+    return {"type": "string"}
+
+
+def extract_function_schema(func, name_override=None, description_override=None):
+    func_name = name_override or func.__name__
+    sig = inspect.signature(func)
+    docstring = parse(func.__doc__ or "")
+    description = description_override or docstring.short_description
+    param_docs = {param.arg_name: param.description for param in docstring.params}
+    type_hints = get_type_hints(func)
+
+    properties = {}
+    required = []
+    for param_name, param in sig.parameters.items():
+        if param_name in ("self", "cls", "context"):
+            continue
+
+        param_type = type_hints.get(param_name, Any)
+        param_desc = param_docs.get(param_name)
+        is_optional, base_type = unwrap_optional(param_type)
+        schema = type_to_schema(base_type)
+        if param_desc:
+            schema["description"] = param_desc
+        properties[param_name] = schema
+
+        if param.default == inspect.Parameter.empty and not is_optional:
+            required.append(param_name)
+
+    json_schema = {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False,
+    }
+    return func_name, description, json_schema
+
+
+def tool(name=None, description=None):
+    def decorator(func):
+        func_name, func_description, parameters = extract_function_schema(
+            func,
+            name_override=name,
+            description_override=description,
+        )
+        return FunctionTool(
+            name=func_name,
+            description=func_description or "",
+            parameters=parameters,
+            func=func,
+        )
+
+    return decorator
+
+
+def to_openai_tools(tools):
+    return [ft.to_dict() for ft in tools]

pagent-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.3
+Name: pagent
+Version: 0.1.0
+Summary: Minimal OpenAI Chat Completions agent (session + tools).
+Author: gongyulei
+Author-email: gongyulei <gongyulei@stu.xmu.edu.cn>
+Requires-Dist: docstring-parser>=0.18.0
+Requires-Dist: openai>=2.31.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# pagent
+
+基于 **OpenAI 兼容 Chat Completions** 的轻量 **async** agent 核心：
+
+- `Session`：对话缓冲 `messages`，用 `session += {...}` 追加消息，`reset()` 清空
+- `LLM`：对 `AsyncOpenAI` 的薄封装，只负责单次 `invoke`；历史由 `Session` 组装
+- `@tool()` / `FunctionTool`：把 Python 函数变成 function-calling 的 schema
+- `Agent`：多轮循环，直到模型不再调用工具或达到 `max_turns`
+
+## 安装
+
+```bash
+pip install pagent
+```
+
+从源码目录：
+
+```bash
+cd pagent
+uv sync
+pip install -e .
+```
+
+## 环境变量（API Key）
+
+默认 `LLM` 会读 **`OPENAI_API_KEY`**（与 OpenAI 官方一致）。
+
+在终端里（当前 shell 有效）：
+
+```bash
+export OPENAI_API_KEY="sk-..."   # macOS / Linux
+# Windows (cmd):  set OPENAI_API_KEY=sk-...
+# Windows (PowerShell): $env:OPENAI_API_KEY="sk-..."
+```
+
+长期生效可写进 `~/.zshrc` / `~/.bashrc`，或用 [direnv](https://direnv.net)、`.env` + 你自己的加载方式（本库不读 `.env` 文件）。
+
+若既没设置环境变量、调用时也没传 `apikey=`，请求会带着空 key 发出，一般会认证失败——请至少满足其一。
+
+## 完整示例：工具调用 + 查看用量
+
+下面假设已设置 `OPENAI_API_KEY`，模型名按你账号可用模型修改（示例用 `gpt-4o-mini`）。
+
+将以下内容保存为 `demo.py` 后执行：`python demo.py`。
+
+```python
+import asyncio
+import os
+
+from pagent import Agent, LLM, Session, tool
+
+
+@tool()
+def get_weather(city: str) -> str:
+    """Return a short fake weather line for the city.
+
+    Args:
+        city: City name in English or Chinese.
+    """
+    return f"It's sunny in {city} today."
+
+
+async def main() -> None:
+    if not os.getenv("OPENAI_API_KEY"):
+        raise SystemExit("请先设置环境变量 OPENAI_API_KEY")
+
+    llm = LLM("gpt-4o-mini")
+    session = Session("You are a concise assistant. Use tools when needed.")
+    agent = Agent(llm=llm, session=session, tools=[get_weather], max_turns=8)
+
+    result = await agent.run("厦门今天天气怎样？用工具查。")
+    print("--- reply ---")
+    print(result.content)
+    print("--- stats ---")
+    print(agent.stats)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`agent.stats` 上会累计 `turns`、token 用量等；`result` 为最后一轮模型返回（`result.usage` 等为该轮信息，具体以 SDK 为准）。
+
+## 接入自己的供应商（任意 OpenAI 兼容网关）
+
+思路：**同一个 `LLM` 类**，换 `base_url`、`model_id`，以及 key 的来源。
+
+### 方式一：显式传参（推荐，最直观）
+
+把网关文档里的 **Base URL**（通常带 `/v1`）、**模型 id**、**API Key** 填进去即可：
+
+```python
+import os
+
+from pagent import LLM
+
+llm = LLM(
+    "your-model-id-on-that-host",
+    base_url="https://your-gateway.example.com/v1",
+    apikey=os.environ["MY_LLM_API_KEY"],
+)
+```
+
+也可以继续用环境变量存 key，变量名你自己定，只要在代码里 `os.environ["..."]` 或 `os.getenv("...")` 读出来传给 `apikey` 即可。
+
+### 方式二：子类固定「自家」默认地址和 key 环境变量
+
+适合团队内封装：把 `BASE_URL`、`API_KEY_ENV_VAR` 写在子类上，`get_api_key()` 会自动读对应环境变量。
+
+```python
+import os
+
+from pagent import LLM
+
+
+class AcmeChat(LLM):
+    """示例：公司统一网关。"""
+
+    API_KEY_ENV_VAR = "ACME_LLM_API_KEY"
+    BASE_URL = "https://llm.acme.internal/v1"
+
+    def __init__(self, model_id="acme-default", **kwargs):
+        super().__init__(model_id, **kwargs)
+
+
+# 使用前: export ACME_LLM_API_KEY=...
+llm = AcmeChat("acme-default")
+```
+
+`kwargs` 仍可传 `base_url` / `apikey` / `request_kwargs`，用于临时覆盖默认（与基类 `LLM.__init__` 行为一致）。
+
+### `request_kwargs`：额外请求参数
+
+若网关要求温度、顶层 `extra_body` 等，可挂在构造函数的第四项：
+
+```python
+LLM(
+    "some-model",
+    base_url="https://.../v1",
+    apikey=os.environ["MY_KEY"],
+    request_kwargs={"temperature": 0.2},
+)
+```
+
+这些键会并入每次 `chat.completions.create(...)`（本库固定 `stream=False`）。
+
+---
+
+**说明**：只要对方实现的是 **OpenAI Chat Completions** 兼容接口（路径、字段与官方相近），上述方式即可；若对方 API 形状完全不同，需要在网关侧做适配，或自行改写 `LLM.invoke`，那已超出本库的默认假设。

pagent-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pagent/__init__.py,sha256=w8oh3XXsGAuZ9hmgoyG9xPHLS5DpTg8tl4RTcTA4x5k,319
+pagent/agent.py,sha256=nXDfVGbObBj-o8gLg4iuuEtl015JRD8TtZTX-Crb1jI,3003
+pagent/llm.py,sha256=hmfzWeoknf4UI7VBPKVwSJP6E_UCpL_Of3NXIcunEWc,2146
+pagent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pagent/session.py,sha256=yquxM2yb76kQRu8JbiMOkPQVlWdfcCl3QdsPrPLlesk,993
+pagent/tool.py,sha256=Mm6dUTy9YG1nsrBVZsIW7lkzDCDP42Q1Q74UNY4AJQs,3957
+pagent-0.1.0.dist-info/WHEEL,sha256=lh7MMMfiuFQLQaR9J7pNBODdWf-aa5UOeuuDAol3xps,79
+pagent-0.1.0.dist-info/METADATA,sha256=dHA-pbQXnMejLiEwtdYAH198Hhq4O82vbsCObGf_13I,4740
+pagent-0.1.0.dist-info/RECORD,,

pagent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.20
+Root-Is-Purelib: true
+Tag: py3-none-any