Metadata-Version: 2.4
Name: llm-toolforge
Version: 0.8.0
Summary: LLM工具调用框架，同时提供 HTTP API 和 MCP Server 两种接入方式
Author: kuon
License-Expression: MIT
Project-URL: Homepage, https://github.com/lissettecarlr/llm-toolforge
Project-URL: Documentation, https://github.com/lissettecarlr/llm-toolforge/tree/main/docs
Project-URL: Issues, https://github.com/lissettecarlr/llm-toolforge/issues
Keywords: llm,tool-calling,mcp,fastapi,agent
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: src/llm_toolforge/fonts/OFL.txt
Requires-Dist: fastapi>=0.139.2
Requires-Dist: uvicorn>=0.29.0
Requires-Dist: aiofiles
Requires-Dist: pydantic>=2.0
Requires-Dist: loguru
Requires-Dist: pyyaml
Requires-Dist: ruamel.yaml
Requires-Dist: mcp[cli]<3.0.0,>=2.0.0
Requires-Dist: starlette>=1.3.1
Requires-Dist: tzdata
Requires-Dist: psutil
Requires-Dist: aiomysql
Requires-Dist: PyMySQL
Requires-Dist: aiosqlite
Requires-Dist: redis==6.2.0
Requires-Dist: oss2
Requires-Dist: cos-python-sdk-v5
Requires-Dist: boto3
Provides-Extra: mysql
Provides-Extra: sqlite
Provides-Extra: redis
Provides-Extra: all
Provides-Extra: ai-openai
Requires-Dist: openai; extra == "ai-openai"
Provides-Extra: ai-doubao
Requires-Dist: volcengine-python-sdk[ark]; extra == "ai-doubao"
Provides-Extra: ai-gemini
Requires-Dist: google-genai; extra == "ai-gemini"
Provides-Extra: ai
Requires-Dist: openai; extra == "ai"
Requires-Dist: volcengine-python-sdk[ark]; extra == "ai"
Requires-Dist: google-genai; extra == "ai"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Dynamic: license-file

# llm-toolforge

> 面向大模型与 Agent 的 Python 工具服务框架：编写一次工具逻辑，同时提供 HTTP API、流式调用、异步任务、MCP Server 和 Web 测试台。
---

## 为什么使用 LLM ToolForge

LLM ToolForge 用于把 Python 能力快速封装成可被大模型、Agent、业务系统和 MCP 客户端调用的工具服务。框架负责接口、校验、执行、日志和部署，工具作者主要关注输入定义与业务逻辑。

主要能力：

- **一份工具实现，多种接入方式**：HTTP API 与 MCP Streamable HTTP。
- **同步、SSE 流式与异步调用**：适配短任务、长任务和后台任务。
- **Generator 执行隔离**：同步工具进入有界线程池，异步工具进入独立持久运行域，
  不占用 API/MCP 主事件循环。
- **自动接口契约**：根据工具输入和输出模型生成校验模型、OpenAPI 与 MCP Schema。
- **Web 测试台**：浏览器中查看工具、填写参数、测试 HTTP/MCP、查看日志与负载。
- **基础设施集成**：内置 MySQL、SQLite、Redis、对象存储，以及 Alibaba、豆包、OpenAI、Gemini 的统一 AI Chat 能力。
- **生产运行能力**：并发限制、排队与过载保护、请求超时、健康检查、调用日志和多副本配置。
- **项目脚手架**：通过 CLI 创建项目和可直接运行的示例工具。

## 框架图

![LLM ToolForge 架构概览](docs/images/architecture-overview.png)

## 安装

```bash
python -m pip install llm-toolforge
```

从源码参与开发：

```bash
git clone https://github.com/lissettecarlr/llm-toolforge.git
cd llm-toolforge
python -m pip install -e ".[test]"
```

验证安装：

```bash
toolforge --help
```


## 快速开始

### 1. 创建项目

```bash
toolforge new project my-tool-service
cd my-tool-service
```

脚手架会生成：

```text
my-tool-service/
├── config.yaml
├── Dockerfile
├── requirements.txt
├── README.md
├── docs/
└── tools/
```

`config.yaml` 默认开启 HTTP 与 MCP 鉴权，并为当前项目生成独立的随机 `Authorization` token。请妥善保管该文件，不要将真实 token 提交到公共仓库。

### 2. 创建第一个工具

```bash
toolforge new tool current_time
```

生成的工具可以直接运行，默认功能是查询指定时区的当前时间。之后可以修改：

```text
tools/current_time/
├── __init__.py
├── generator.py
└── static/tester.html
```

### 3. 校验并启动

```bash
toolforge config validate
toolforge run
```

默认地址：

| 服务 | 地址 |
|---|---|
| Web 测试台 / HTTP API | `http://localhost:12345` |
| MCP Streamable HTTP | `http://localhost:12346/mcp` |
| HTTP 健康检查 | `http://localhost:12345/healthz` |
| MCP 健康检查 | `http://localhost:12346/healthz` |

打开 Web 测试台后，将 `config.yaml` 中完整的 `authorization` 值粘贴到页面右上角的“API 密钥”输入框。

### 4. 调用 HTTP 工具

假设 `config.yaml` 中的值为：

```yaml
authorization: "Bearer your-generated-token"
```

调用脚手架生成的时间工具：

```bash
curl -X POST "http://localhost:12345/current-time" \
  -H "Authorization: Bearer your-generated-token" \
  -H "Content-Type: application/json" \
  -d '{"timezone":"Asia/Shanghai"}'
```

流式调用只需增加 `stream=true`：

```bash
curl -N -X POST "http://localhost:12345/current-time?stream=true" \
  -H "Authorization: Bearer your-generated-token" \
  -H "Content-Type: application/json" \
  -d '{"timezone":"Asia/Shanghai"}'
```

## 部署

`toolforge new project` 会在项目目录下生成 `Dockerfile`

```bash
docker build -t llm-toolforge-example:v0.1.0 .

docker run --rm \
  -v "$(pwd)/config.yaml:/app/config.yaml" \
  -e SERVICE_NAME=llm-toolforge-example \
  -p 12345:12345 \
  -p 12346:12346 \
  llm-toolforge-example:v0.1.0
```

## 运行自动化测试

参与框架开发时，先在项目根目录安装源码及测试依赖：
```bash
python -m pip install -e ".[test]"
```
以后每次修改代码后，在项目根目录运行：
```bash
python -m pytest
```


## 环境变量

少量字段可由环境变量覆盖（**优先级高于 `config.yaml`**）：

| 变量 | 覆盖字段 |
|---|---|
| `SERVICE_NAME` | `service.name` |
| `SERVICE_VERSION` | `service.version` |

K8s 多实例部署时推荐通过 Deployment 注入 `SERVICE_NAME`，避免镜像里写死。

---
