Metadata-Version: 2.4
Name: llm-toolforge
Version: 0.5.2
Summary: LLM工具调用框架，同时提供 HTTP API 和 MCP Server 两种接入方式
License: MIT License
        
        Copyright (c) 2026 kuon
        
        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.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<0.120.0,>=0.111.0
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]>=1.2.0
Requires-Dist: starlette<1.0,>=0.40.0
Requires-Dist: tzdata
Requires-Dist: oss2
Requires-Dist: cos-python-sdk-v5
Requires-Dist: aiomysql
Requires-Dist: aiosqlite
Requires-Dist: redis==6.2.0
Provides-Extra: aliyun
Provides-Extra: tencent
Provides-Extra: mysql
Provides-Extra: sqlite
Provides-Extra: redis
Provides-Extra: all-storage
Provides-Extra: all-infra
Provides-Extra: all
Dynamic: license-file

# llm-toolforge

用语大模型的工具的框架，同时提供 **HTTP API**（FastAPI）和 **MCP Server**（SSE transport）两种接入方式。

---

## 快速开始

### 安装框架

```bash
pip install llm-toolforge

# 如果是克隆的代码安装，则在根目录执行
pip install -e .

# 验证
toolforge --help
```

### 安装示例工具环境
```bash
cd examples
pip install -r requirements.txt
```

* 编辑示例工具的配置文件
```
cp config.example.yaml config.yaml
# 根据注释填写配置即可
```

* 运行：
```bash
toolforge run
```
打开页面`http://localhost:12345`进行测试。

### 部署

`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
```

同一套基础设施（Redis / MySQL）跑多个 toolset 时，**必须**为每个 Deployment 设置唯一的 `SERVICE_NAME`，否则日志、统计、心跳会串在一起。

**优先级：环境变量 > config.yaml**，两者都缺失时启动直接报错。

**方式 1（推荐）：环境变量**

```yaml
env:
  - name: SERVICE_NAME
    value: my-toolset
  - name: SERVICE_VERSION
    value: v1.0.0
```

**方式 2：config.yaml**

```yaml
service:
  name: my-toolset
  version: v1.0.0
```



## 框架安装说明

一条命令即可安装全部组件（日志后端、对象存储等都已默认包含）：
```bash
pip install llm-toolforge
```

默认包含的可选后端：

- 日志后端（由 config.yaml 的 `infra_mode` 决定）：MySQL + Redis（`mysql_redis` 模式）、SQLite（`sqlite_standalone` 模式）
- 对象存储（工具上传文件时用）：阿里云 OSS（`oss2`）、腾讯云 COS（`cos-python-sdk-v5`）

> 旧的 `pip install llm-toolforge[all]` 等命令仍可用，extra 现已为空别名，效果与直接安装一致。

## 框架命令

```bash
toolforge new project my-app   # 创建 ./my-app/ 并生成项目初始文件
toolforge new project .        # 在当前目录初始化项目（目录已存在时使用）
toolforge new tool <name>      # 在 tools/<name>/ 下生成工具骨架
toolforge list                 # 列出已发现的工具（确认插件加载正常）
toolforge run                  # 启动 HTTP API（默认 :12345）+ MCP SSE（默认 :12346）
toolforge run --api-only       # 只启动 HTTP API
toolforge run --mcp-only       # 只启动 MCP SSE 服务
toolforge run -c path/cfg.yaml # 指定配置文件路径
```


---

## 文档

| 文档 | 内容 |
|---|---|
| [工具开发指南](docs/plugin-authoring.md) | 从零创建工具 + Generator / Plugin / InputField 完整说明 |
| [接口参考](docs/api-reference.md) | HTTP API / MCP 协议 |
| [运行观测](docs/observability.md) | 日志 / 统计 / 负载监控 / 并发调优 |

## 环境变量

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

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

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

---
