air-agent 0.1.0__tar.gz

air_agent-0.1.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(uv run *)"
+    ]
+  }
+}

air_agent-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+
+.venv/
+venv/
+env/
+
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+.uv/
+uv.lock
+
+*.log
+.DS_Store
+.env

air_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chldu2000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

air_agent-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: air-agent
+Version: 0.1.0
+Summary: Lightweight Python AI agent with OpenAI tool calling, MCP support, and parallel subagents
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: openai>=1.30
+Requires-Dist: pydantic>=2.0

air_agent-0.1.0/README.md

@@ -0,0 +1,205 @@
+# vibe-agent
+
+轻量级 Python AI Agent 库。基于 OpenAI Chat Completions API，支持工具调用循环、MCP Server 连接、并行 Subagent 和流式输出。设计为可被其他 Python 项目直接引用。
+
+## 安装
+
+```bash
+uv add vibe-agent
+```
+
+或开发模式：
+
+```bash
+git clone https://github.com/chldu2000/vibe-agent.git
+cd vibe-agent
+uv sync --group dev
+```
+
+## 快速开始
+
+### 基础对话
+
+```python
+import asyncio
+from vibe_agent import Agent, AgentConfig
+
+async def main():
+    agent = Agent(AgentConfig(model="gpt-4o"))
+    response = await agent.run("用一句话解释量子计算")
+    print(response.content)
+
+asyncio.run(main())
+```
+
+### 注册本地工具
+
+```python
+agent = Agent(AgentConfig(model="gpt-4o", api_key="sk-xxx"))
+
+@agent.tool(name="add", description="计算两个数的和")
+async def add(a: int, b: int) -> int:
+    return a + b
+
+response = await agent.run("3 加 5 等于多少？")
+# Agent 会自动调用 add 工具并返回结果
+```
+
+参数类型从函数签名自动推导，生成 OpenAI tool calling 所需的 JSON Schema。
+
+### 流式输出
+
+```python
+async for event in await agent.run("写一首关于编程的诗", stream=True):
+    if event.type == "text":
+        print(event.content, end="", flush=True)
+    elif event.type == "tool_call":
+        print(f"\n[调用工具: {event.name}]")
+    elif event.type == "tool_result":
+        print(f"[工具结果: {event.content}]")
+    elif event.type == "done":
+        print(f"\n完成，token 用量: {event.usage}")
+```
+
+### 多轮对话
+
+```python
+response = await agent.run("你好", conversation_id="session-1")
+response = await agent.run("我刚才说了什么？", conversation_id="session-1")
+# 第二轮会带上第一轮的上下文
+```
+
+### 从 JSON 文件加载配置
+
+```json
+{
+  "model": "gpt-4o",
+  "system_prompt": "你是一个编程助手",
+  "mcp_servers": [
+    {"command": "npx", "args": ["-y", "@anthropic/mcp-server-filesystem", "/tmp"]},
+    {"url": "http://localhost:8080/sse"}
+  ]
+}
+```
+
+```python
+config = AgentConfig.from_json("agent-config.json")
+agent = Agent(config)
+```
+
+JSON 中 `mcp_servers` 根据 `command`（stdio）或 `url`（SSE）自动识别类型。
+
+### 从环境变量加载配置
+
+```bash
+export VIBE_MODEL=gpt-4o
+export VIBE_SYSTEM_PROMPT="你是一个助手"
+export VIBE_MAX_ITERATIONS=30
+export VIBE_MCP_SERVERS='[{"command":"npx","args":["server"]}]'
+```
+
+```python
+config = AgentConfig.from_env()          # 默认 VIBE_ 前缀
+config = AgentConfig.from_env(prefix="MYAPP_")  # 自定义前缀
+agent = Agent(config)
+```
+
+支持的环境变量：
+
+| 变量 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `VIBE_MODEL` | str | 模型名称 |
+| `VIBE_API_KEY` | str | API 密钥（优先级高于 `OPENAI_API_KEY`） |
+| `VIBE_BASE_URL` | str | 自定义 API endpoint |
+| `VIBE_SYSTEM_PROMPT` | str | 系统提示词 |
+| `VIBE_MAX_ITERATIONS` | int | 最大工具调用轮次 |
+| `VIBE_TOOL_TIMEOUT` | float | 工具调用超时（秒） |
+| `VIBE_MCP_SERVERS` | JSON | MCP server 列表 |
+| `VIBE_DEFAULT_HEADERS` | JSON | 自定义请求头 |
+
+### 连接 MCP Server
+
+```python
+from vibe_agent import MCPServerStdio, MCPServerSSE
+
+agent = Agent(AgentConfig(
+    model="gpt-4o",
+    mcp_servers=[
+        MCPServerStdio(command="npx", args=["-y", "@anthropic/mcp-server-filesystem", "/tmp"]),
+        MCPServerSSE(url="http://localhost:8080/mcp"),
+    ],
+))
+
+async with agent:  # 自动连接/断开 MCP server
+    response = await agent.run("列出 /tmp 下的文件")
+```
+
+支持 stdio 和 StreamableHTTP 两种 MCP transport。连接 MCP 后，server 暴露的工具会自动注册到 Agent 的工具列表中。
+
+### 并行 Subagent
+
+```python
+from vibe_agent import SubagentConfig
+
+results = await agent.delegate(
+    tasks=[
+        "分析 src/ 目录的代码结构",
+        "检查 tests/ 的测试覆盖率",
+        "生成 CHANGELOG",
+    ],
+    config=SubagentConfig(max_parallel=3, timeout=60),
+)
+
+for r in results:
+    print(f"[{r.status}] {r.content[:100]}")
+```
+
+每个 task 在独立的 Agent 实例中运行，互不干扰。
+
+## 配置
+
+```python
+AgentConfig(
+    model="gpt-4o",              # 模型名称
+    api_key="sk-xxx",            # 或设置 OPENAI_API_KEY 环境变量
+    base_url=None,               # 自定义 API endpoint
+    system_prompt="你是一个助手",  # 系统提示词
+    max_iterations=20,           # 工具调用最大轮次
+    tool_timeout=30.0,           # 单次工具调用超时（秒）
+    mcp_servers=[],              # MCP server 列表
+)
+```
+
+## 项目结构
+
+```text
+src/vibe_agent/
+├── __init__.py          # 公开 API 导出
+├── agent.py             # 核心 Agent（ReAct 循环 + 流式输出）
+├── config.py            # 配置数据类
+├── types.py             # Response, StreamEvent, SubagentResult
+├── tools/
+│   ├── base.py          # Tool 数据类
+│   └── registry.py      # 工具注册中心
+├── mcp/
+│   ├── client.py        # MCP 客户端（stdio + streamable_http）
+│   └── tool_adapter.py  # MCP tool → OpenAI 格式转换
+└── subagent.py          # 并行 subagent 管理器
+```
+
+## 依赖
+
+- `openai` — LLM 调用与 tool calling
+- `mcp` — MCP 协议客户端
+- `pydantic` — 数据校验
+
+## 开发
+
+```bash
+uv sync --group dev
+uv run pytest tests/ -v
+```
+
+## License
+
+MIT