llm-toolforge 0.3.0__py3-none-any.whl

llm_toolforge/__init__.py

@@ -0,0 +1,47 @@
+"""
+llm-toolforge
+
+工具开发只需从这里导入：
+
+    from llm_toolforge import (
+        Plugin, InputField, BaseGenerator,
+        GenerateResult, GenerateProgress, ResultStatus,
+        LLMServiceError, UploadError,
+        AIClient, OSSClient,
+        load_tool_config,
+    )
+"""
+
+from .core.base import (
+    BaseGenerator,
+    GenerateProgress,
+    GenerateResult,
+    GeneratorError,
+    InputField,
+    LLMServiceError,
+    Plugin,
+    ResultStatus,
+    UploadError,
+)
+from .core.ai_client import AIClient
+from .core.oss_client import OSSClient
+from .config import load_tool_config, load_config, find_config
+from .discovery import discover_plugins
+
+__all__ = [
+    "Plugin",
+    "BaseGenerator",
+    "InputField",
+    "GenerateResult",
+    "GenerateProgress",
+    "ResultStatus",
+    "GeneratorError",
+    "LLMServiceError",
+    "UploadError",
+    "AIClient",
+    "OSSClient",
+    "load_tool_config",
+    "load_config",
+    "find_config",
+    "discover_plugins",
+]

llm_toolforge/cli.py

@@ -0,0 +1,403 @@
+"""
+toolforge CLI 入口
+
+命令：
+    toolforge run [--config FILE] [--api-only | --mcp-only]
+    toolforge list [--config FILE]
+    toolforge new project <dest>
+    toolforge new tool <name>
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+
+# ── 模板内容 ────────────────────────────────────────────────────────────────────
+
+_CONFIG_TEMPLATE = """\
+# ============================================================
+# llm-toolforge 配置
+# ============================================================
+
+# 扫描哪些目录下的工具子包（相对于本文件所在目录）
+plugins_dirs: [tools]
+
+# ── 服务标识 ──────────────────────────────────────────────────
+# name 用于日志/心跳/统计的 service_name 隔离，多部署时必须唯一
+service:
+  name: "my-toolset"
+  version: "v1.0.0"
+
+# ── HTTP / MCP 服务 ───────────────────────────────────────────
+server:
+  host: "0.0.0.0"
+  port: 12345
+  mcp_port: 12346
+
+  # Web 测试台（访问 http://host:port/）
+  enable_web_ui: true
+
+  # API 鉴权：enable_auth=true 时所有接口需要 Authorization 头
+  enable_auth: false
+  authorization: "Bearer change-me"
+
+  # Worker 数量：auto = min(cpu_count * worker_multiplier, max_api_workers)
+  api_workers: auto
+  mcp_workers: 1
+  # max_api_workers: 8        # auto 模式的上限（默认 8）
+  # max_mcp_workers: 4        # MCP auto 模式的上限（默认 4）
+  # worker_multiplier: 1      # auto 模式的 CPU 倍数（默认 1）
+
+  # 单请求并发限制（0 = 不限制）
+  max_concurrency: 4
+  # overload_timeout_ms: 1000 # 等待并发许可的超时，超时返回 503（默认 1000ms）
+
+  # 单次请求超时（秒，0 = 不限制）
+  request_timeout_s: 180
+
+  # 文件上传大小限制（MB，0 = 不限制）
+  max_upload_mb: 50
+
+  # 多 Pod 部署时手动指定实例 ID（不填则自动取 POD_NAME / HOSTNAME / gethostname）
+  # instance_id: "pod-0"
+
+  # 跨 service 全局视图的管理员 Token（不填则禁用 scope=global 接口）
+  # global_admin_token: "your-admin-token"
+
+# ── 调用日志 ──────────────────────────────────────────────────
+logging:
+  # storage: mysql | sqlite | disabled
+  storage: sqlite
+  sqlite_path: logs.db
+
+  # 日志保留天数（0 = 永久保留）
+  retention_days: 90
+
+  # 心跳配置（用于 /load 接口的 worker 存活检测，依赖 Redis）
+  heartbeat_interval_s: 5    # 写心跳的间隔（秒）
+  heartbeat_ttl_s: 15        # 心跳在 Redis 中的过期时间（秒）
+
+  # 日志批量写入配置
+  # batch_size: 100           # 攒够多少条触发一次批量写（默认 100）
+  # batch_flush_ms: 1000      # 最长等待多少毫秒强制 flush（默认 1000）
+
+  # 单条日志 output 字段的最大字节数（0 = 不截断）
+  # max_output_size: 0
+
+# ── MySQL 日志后端（logging.storage: mysql 时填写）──────────────
+# mysql:
+#   host: "127.0.0.1"
+#   port: 3306
+#   username: "root"
+#   password: "your-password"
+#   database: "toolforge"
+#   pool_max: 10              # 连接池最大连接数（默认 10）
+#   events_table: "tool_call_events"  # 日志表名（默认 tool_call_events）
+
+# ── Redis（可选，用于心跳/实时流/统计缓存）──────────────────────────
+# 不配置时对应功能自动降级：/load 心跳检测、/logs/stream 实时流、统计缓存不可用，
+# 其余功能（工具调用、日志落库）不受影响。
+# redis_config:
+#   host: "127.0.0.1"
+#   port: 6379
+#   password: ""
+#   database: 0
+#   key_prefix: "toolforge"  # Redis key 前缀，多部署共用同一 Redis 时用于隔离
+
+# ── 大模型渠道（按需填写，工具内通过 provider 名称引用）────────
+# 支持 alibaba / doubao / openai / gemini，按需取消注释并填入密钥
+ai_providers:
+  openai:
+    key: "your-api-key"
+    base_url: "https://api.openai.com/v1"
+    timeout_s: 120
+  # alibaba:
+  #   key: "your-dashscope-api-key"
+  #   base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+  #   timeout_s: 120
+  # doubao:
+  #   key: "your-ark-api-key"
+  #   base_url: "https://ark.cn-beijing.volces.com/api/v3"
+  #   timeout_s: 120
+  # gemini:
+  #   key: "your-gemini-api-key"
+  #   base_url: "https://generativelanguage.googleapis.com"
+  #   timeout_s: 120
+
+# ── 对象存储（文件上传 / 产物托管，按需启用）────────────────────
+# storage:
+#   provider: aliyun          # aliyun | tencent（默认 aliyun）
+#
+#   # ── 阿里云 OSS（provider: aliyun）──
+#   access_key_id: ""
+#   access_key_secret: ""
+#   endpoint: "http://oss-cn-hangzhou.aliyuncs.com"
+#   bucket_host: "https://your-bucket.oss-cn-hangzhou.aliyuncs.com"
+#   bucket: "your-bucket"
+#   region: "cn-hangzhou"
+#   path_prefix: "toolforge"
+#
+#   # ── 腾讯云 COS（provider: tencent）──
+#   secret_id: "your-secret-id"
+#   secret_key: "your-secret-key"
+#   bucket: "your-bucket-1234567890"
+#   region: "ap-guangzhou"
+#   path_prefix: "toolforge"
+#   cdn_endpoint: ""          # 留空则使用默认 COS 域名
+
+# ── 工具私有配置（key 与 tools/ 下子目录同名）────────────────────
+tools: {}
+"""
+
+_TOOL_INIT_TEMPLATE = '''\
+from pathlib import Path
+from llm_toolforge import Plugin, InputField, load_tool_config
+from .generator import {ClassName}Generator
+
+_DIR = Path(__file__).parent
+_CFG = load_tool_config("{tool_name}")
+
+plugin = Plugin(
+    name="{display_name}",
+    description="TODO: 描述这个工具的功能",
+    generator={ClassName}Generator(),
+    route_path="/{route_path}",
+    operation_id="{operation_id}",
+    route_summary="TODO: 一句话接口摘要",
+    inputs=[
+        InputField(
+            name="input_text",
+            description="输入内容",
+            examples=["示例输入"],
+        ),
+    ],
+)
+'''
+
+_TOOL_GENERATOR_TEMPLATE = '''\
+from llm_toolforge import BaseGenerator, GenerateResult, ResultStatus
+
+
+class {ClassName}Generator(BaseGenerator):
+    """TODO: 工具的业务实现"""
+
+    def generate(self, **kwargs) -> GenerateResult:
+        input_text = kwargs.get("input_text", "")
+
+        # TODO: 实现你的业务逻辑
+        result = f"处理结果：{{input_text}}"
+
+        return GenerateResult(
+            status=ResultStatus.SUCCESS,
+            outputs={{"result": result}},
+        )
+'''
+
+_REQUIREMENTS_TEMPLATE = """\
+llm-toolforge
+"""
+
+_DOCKERFILE_TEMPLATE = """\
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# 按需取消注释（qr_recognize 需要 libzbar0 / libgl1）
+# RUN apt-get update && \\
+#     apt-get install -y --no-install-recommends libglib2.0-0 libgl1 libzbar0 && \\
+#     rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 12345 12346
+
+CMD ["toolforge", "run"]
+"""
+
+_README_TEMPLATE = """\
+# {project_name}
+
+基于 [llm-toolforge](https://github.com/xxx/llm-toolforge) 构建的工具集。
+
+## 快速开始
+
+```bash
+pip install -r requirements.txt
+toolforge run
+```
+
+访问 http://localhost:12345 查看 Web 测试台。
+
+## 添加新工具
+
+```bash
+toolforge new tool my_tool
+```
+
+然后编辑 `tools/my_tool/generator.py` 实现业务逻辑。
+"""
+
+
+# ── 子命令实现 ──────────────────────────────────────────────────────────────────
+
+def cmd_run(args) -> int:
+    from .server.runner import run
+    return run(
+        config_path=args.config,
+        api_only=args.api_only,
+        mcp_only=args.mcp_only,
+    )
+
+
+def cmd_list(args) -> int:
+    from .config import load_config
+    from .discovery import discover_plugins
+    try:
+        config = load_config(args.config)
+        plugins = discover_plugins(config)
+    except Exception as e:
+        print(f"错误：{e}", file=sys.stderr)
+        return 1
+    if not plugins:
+        print("（没有发现任何插件）")
+        return 0
+    print(f"发现 {len(plugins)} 个插件：\n")
+    for p in plugins:
+        print(f"  [{p.operation_id}]  {p.name}")
+        print(f"    路由: POST {p.route_path}")
+        print(f"    描述: {p.description[:80]}{'...' if len(p.description) > 80 else ''}")
+        print()
+    return 0
+
+
+def cmd_new_project(args) -> int:
+    dest = Path(args.dest).resolve()
+    dest.mkdir(parents=True, exist_ok=True)
+
+    cfg = dest / "config.yaml"
+    if cfg.exists():
+        print(f"config.yaml 已存在，跳过：{cfg}")
+    else:
+        cfg.write_text(_CONFIG_TEMPLATE, encoding="utf-8")
+        print(f"已创建：{cfg}")
+
+    tools_dir = dest / "tools"
+    tools_dir.mkdir(exist_ok=True)
+    (tools_dir / ".gitkeep").touch()
+    print(f"已创建：{tools_dir}/")
+
+    req = dest / "requirements.txt"
+    if not req.exists():
+        req.write_text(_REQUIREMENTS_TEMPLATE, encoding="utf-8")
+        print(f"已创建：{req}")
+
+    readme = dest / "README.md"
+    if not readme.exists():
+        project_name = dest.name
+        readme.write_text(_README_TEMPLATE.format(project_name=project_name), encoding="utf-8")
+        print(f"已创建：{readme}")
+
+    dockerfile = dest / "Dockerfile"
+    if not dockerfile.exists():
+        dockerfile.write_text(_DOCKERFILE_TEMPLATE, encoding="utf-8")
+        print(f"已创建：{dockerfile}")
+
+    print(f"\n项目初始化完成！下一步：")
+    print(f"  1. 编辑 {dest}/config.yaml，填入 Redis / AI provider 等配置")
+    print(f"  2. toolforge new tool <name>  添加第一个工具")
+    print(f"  3. toolforge run              启动服务")
+    return 0
+
+
+def cmd_new_tool(args) -> int:
+    tool_name: str = args.name.strip().replace("-", "_").lower()
+    class_name = "".join(w.capitalize() for w in tool_name.split("_"))
+    display_name = tool_name.replace("_", " ").title()
+    route_path = tool_name.replace("_", "-")
+    operation_id = "".join(
+        (w[0].upper() + w[1:] if i > 0 else w) for i, w in enumerate(tool_name.split("_"))
+    )
+
+    # 目标目录：优先放在 ./tools/，其次 CWD/tool_name
+    tools_root = Path.cwd() / "tools"
+    if tools_root.exists():
+        tool_dir = tools_root / tool_name
+    else:
+        tool_dir = Path.cwd() / tool_name
+
+    if tool_dir.exists():
+        print(f"目录已存在：{tool_dir}，请手动检查是否需要覆盖。", file=sys.stderr)
+        return 1
+
+    tool_dir.mkdir(parents=True)
+    (tool_dir / "__init__.py").write_text(
+        _TOOL_INIT_TEMPLATE.format(
+            ClassName=class_name,
+            tool_name=tool_name,
+            display_name=display_name,
+            route_path=route_path,
+            operation_id=operation_id,
+        ),
+        encoding="utf-8",
+    )
+    (tool_dir / "generator.py").write_text(
+        _TOOL_GENERATOR_TEMPLATE.format(ClassName=class_name),
+        encoding="utf-8",
+    )
+    print(f"已创建工具骨架：{tool_dir}/")
+    print(f"  {tool_dir}/__init__.py   — 插件声明（Plugin）")
+    print(f"  {tool_dir}/generator.py  — 业务逻辑（{class_name}Generator）")
+    print(f"\n下一步：")
+    print(f"  1. 编辑 {tool_dir}/generator.py 实现业务逻辑")
+    print(f"  2. 运行 toolforge list 确认工具已被发现")
+    print(f"  3. 运行 toolforge run 启动服务并在 Web 测试台验证")
+    return 0
+
+
+# ── 参数解析 ────────────────────────────────────────────────────────────────────
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="toolforge",
+        description="llm-toolforge 命令行工具",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # run
+    p_run = sub.add_parser("run", help="启动 API + MCP 服务")
+    p_run.add_argument("--config", "-c", metavar="FILE", help="config.yaml 路径（默认：自动查找）")
+    g = p_run.add_mutually_exclusive_group()
+    g.add_argument("--api-only", action="store_true", help="只启动 HTTP API")
+    g.add_argument("--mcp-only", action="store_true", help="只启动 MCP SSE 服务")
+    p_run.set_defaults(func=cmd_run)
+
+    # list
+    p_list = sub.add_parser("list", help="列出已发现的工具")
+    p_list.add_argument("--config", "-c", metavar="FILE")
+    p_list.set_defaults(func=cmd_list)
+
+    # new
+    p_new = sub.add_parser("new", help="生成脚手架")
+    new_sub = p_new.add_subparsers(dest="new_type", metavar="<type>")
+    new_sub.required = True
+
+    p_new_project = new_sub.add_parser("project", help="初始化新项目")
+    p_new_project.add_argument("dest", nargs="?", default=".", help="目标目录（默认：当前目录）")
+    p_new_project.set_defaults(func=cmd_new_project)
+
+    p_new_tool = new_sub.add_parser("tool", help="在 tools/ 目录下生成工具骨架")
+    p_new_tool.add_argument("name", help="工具目录名（如 my_tool）")
+    p_new_tool.set_defaults(func=cmd_new_tool)
+
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+    sys.exit(args.func(args))

llm_toolforge/config.py

@@ -0,0 +1,88 @@
+"""
+配置加载
+
+所有 config.yaml 相关的 I/O 都在这个模块，框架其余部分不直接读文件。
+
+查找优先级（find_config）：
+  1. 环境变量 TOOLFORGE_CONFIG（绝对路径或相对于 CWD）
+  2. CWD/config.yaml
+  3. 从 CWD 向上逐级搜索（兼容 cd 到子目录运行的场景）
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+def find_config(path: Optional[str] = None) -> Path:
+    """定位 config.yaml 并返回其绝对路径。
+
+    Args:
+        path: 明确指定的路径（优先级最高），None 则自动查找。
+
+    Raises:
+        FileNotFoundError: 找不到配置文件时抛出，消息包含修复建议。
+    """
+    if path:
+        p = Path(path)
+        if not p.is_absolute():
+            p = Path.cwd() / p
+        if not p.exists():
+            raise FileNotFoundError(f"指定的配置文件不存在：{p}")
+        return p.resolve()
+
+    env = os.environ.get("TOOLFORGE_CONFIG")
+    if env:
+        p = Path(env)
+        if not p.is_absolute():
+            p = Path.cwd() / p
+        if p.exists():
+            return p.resolve()
+        raise FileNotFoundError(
+            f"环境变量 TOOLFORGE_CONFIG 指向的文件不存在：{p}\n"
+            "请检查路径是否正确。"
+        )
+
+    cwd_cfg = Path.cwd() / "config.yaml"
+    if cwd_cfg.exists():
+        return cwd_cfg
+
+    d = Path.cwd()
+    for _ in range(4):
+        d = d.parent
+        cfg = d / "config.yaml"
+        if cfg.exists():
+            return cfg
+
+    raise FileNotFoundError(
+        "找不到 config.yaml。\n"
+        "请在项目根目录创建配置文件，或通过 TOOLFORGE_CONFIG 环境变量指定路径。\n"
+        "可以用 `toolforge new project .` 生成配置模板。"
+    )
+
+
+def load_config(path: Optional[str] = None) -> dict:
+    """加载并返回 config.yaml 的内容（dict）。"""
+    return yaml.safe_load(find_config(path).read_text(encoding="utf-8")) or {}
+
+
+def load_tool_config(name: str, config: Optional[dict] = None) -> dict:
+    """加载工具私有配置段 tools.<name>。
+
+    工具在 __init__.py 中调用（不需要知道文件路径）：
+
+        from llm_toolforge import load_tool_config
+        _CFG = load_tool_config("my_tool")
+
+    Args:
+        name:   工具注册名（与 tools/ 下子目录名一致）。
+        config: 已加载的 config dict，传入可避免重复读文件。
+
+    Returns:
+        dict，没有对应配置段时返回 {}。
+    """
+    if config is None:
+        config = load_config()
+    return (config.get("tools") or {}).get(name) or {}

llm_toolforge/core/__init__.py

@@ -0,0 +1,11 @@
+from .base import (
+    BaseGenerator,
+    GenerateProgress,
+    GenerateResult,
+    GeneratorError,
+    InputField,
+    LLMServiceError,
+    Plugin,
+    ResultStatus,
+    UploadError,
+)