entari-plugin-llm 0.1.0__py3-none-any.whl

entari_plugin_llm/README.md

@@ -0,0 +1,92 @@
+# entari-plugin-llm
+
+entari-plugin-llm 是一个用于 Entari 框架的 LLM（大语言模型）插件，提供基于 litellm 的对话能力、函数调用（Tool Call）支持、会话管理以及若干内置实用工具（如图像识别、网页处理等）。
+
+插件目标是为基于 Arclet Entari 的机器人/服务提供一个可配置、可拓展的 LLM 工具箱，便于在对话中调用函数以完成复杂任务，并支持结构化 JSON 输出、视觉识别等能力。
+
+主要特性
+- 基于 litellm 的聊天能力（支持流式与非流式）。
+- 支持“函数调用”机制（Tool Call），可以把插件内的订阅函数自动注册为 LLM 可调用的工具。
+- 会话与上下文持久化（使用 `entari-plugin-database` 提供的数据库模型）。
+- 支持视觉（image）输入的模型调用（当模型支持 vision 时）。
+- 可配置的模型/提示/工具调用策略，通过 `Config` 加载与热重载（ConfigReload）。
+
+要求
+- Python >= 3.10
+- 依赖见 `pyproject.toml` 中的 `dependencies`（推荐使用 pdm 或 uv 等现代包管理器）。
+
+## 快速开始
+
+1. 克隆仓库：
+
+  ```powershell
+  git clone https://github.com/ArcletProject/entari-plugin-llm.git
+  cd entari-plugin-llm
+  ```
+
+2. 安装依赖（使用 pdm，或使用 pip 在虚拟环境中安装）：
+
+  ```powershell
+  pdm sync
+  # 或者使用 uv：
+  uv sync
+  ```
+
+3. 运行本地示例（运行 Entari 应用）：
+
+  ```powershell
+  python main.py
+  ```
+
+说明：`main.py` 通过 `Entari.load("")` 加载当前目录下的 Entari 配置并启动服务 —— 在实际部署时请提供合适的配置文件与环境变量（例如模型的 API key、base_url 等）。
+
+## 基本用法（示例）
+
+作为插件使用时，包会在导入时通过 `metadata()` 注册插件信息，并在运行时加载配置、工具与服务。你可以在代码中直接引用导出的服务：
+
+```python
+from entari_plugin_llm import llm
+
+# 在异步上下文中调用
+resp = await llm.generate("Hello world")
+```
+
+### 工具与函数调用（Tool）
+- 插件将符合 arclet.letoderea 订阅器规范的函数自动注册为可被 LLM 调用的工具。
+- 工具的参数与文档由函数的 docstring 与类型注解自动生成 JSON Schema，以便 LLM 在函数调用时进行参数填充。
+
+### 配置与热重载
+
+插件使用 `Config` 对象管理模型、提示词、上下文长度以及工具调用的最大循环步数。修改 Entari 插件配置并触发 `ConfigReload` 事件可以热重载这些设置。
+
+## 项目结构（重要文件与目录）
+
+- `src/entari_plugin_llm/` - 插件实现代码
+  - `__init__.py` - 插件元信息与自动注册
+  - `service.py` - LLM 服务实现（封装了 litellm 的调用、工具调用处理、vision 等）
+  - `model.py` - 数据库 ORM 模型（会话与上下文）
+  - `handlers/` - Entari 事件处理器（chat、command、check 等）
+  - `tools/` - 插件提供的工具注册逻辑与内置工具（如 image_vision、webpage_processor）
+- `main.py` - 一个简单的启动示例
+- `pyproject.toml` - 项目与依赖配置
+
+## 开发与调试
+
+在开发过程中你可以编辑 `entari.yml` 或插件配置，并使用 Entari 的配置热重载来应用更改。
+
+## 贡献
+
+欢迎提交 issue 与 PR。请遵循仓库的编码风格与测试规范，尽量在 PR 中包含说明与复现步骤。
+
+## 许可证
+
+本项目遵循 MIT 许可证（见 `pyproject.toml` 中的 license 字段）。
+
+## 联系方式
+
+作者: RF-Tar-Railt, KomoriDev（详见 `src/entari_plugin_llm/__init__.py` 中的作者信息）
+
+## 更多信息
+
+请参阅 `pyproject.toml` 中的依赖与可选依赖（如浏览器、Google provider 等）以获取额外功能支持。
+

entari_plugin_llm/__init__.py

@@ -0,0 +1,35 @@
+from arclet.entari import declare_static, metadata, plugin
+
+from .config import Config, _conf
+from .log import _suppress_litellm_logging
+from .tools import LLMToolEvent as LLMToolEvent
+
+metadata(
+    name="LLM 工具箱",
+    author=[
+        {"name": "RF-Tar-Railt", "email": "rf_tar_railt@qq.com"},
+        {"name": "KomoriDev", "email": "mute231010@gmail.com"},
+    ],
+    version="0.1.0",
+    description="一个通用的 LLM 工具箱插件，提供了丰富的工具和模型配置选项，支持多种 LLM 模型，并且可以轻松集成到各种应用场景中。",
+    urls={
+        "homepage": "https://github.com/ArcletProject/entari-plugin-llm",
+    },
+    config=Config,
+    readme="README.md",
+)
+declare_static()
+_suppress_litellm_logging()
+
+for tool in _conf.tools:
+    plugin.load_plugin(tool)
+
+from .handlers import chat as chat
+from .handlers import check as check
+from .handlers import command as command
+from .service import llm as llm
+
+__all__ = [
+    "llm",
+    "LLMToolEvent",
+]

entari_plugin_llm/_callback.py

@@ -0,0 +1,21 @@
+from typing import TYPE_CHECKING
+
+from litellm.integrations.custom_logger import CustomLogger
+
+if TYPE_CHECKING:
+    from .service import LLMService
+
+
+class TokenUsageHandler(CustomLogger):
+    def __init__(self, service: "LLMService"):
+        self.service = service
+
+    async def async_log_success_event(self, kwargs, response_obj, start_time, end_time):
+        if "usage" in response_obj:
+            self.service.total_tokens += response_obj["usage"].get("total_tokens", 0)
+            self.service.total_calls += 1
+
+    async def async_log_stream_event(self, kwargs, response_obj, start_time, end_time):
+        if "usage" in response_obj:
+            self.service.total_tokens += response_obj["usage"].get("total_tokens", 0)
+            self.service.total_calls += 1

entari_plugin_llm/_jsondata.py

@@ -0,0 +1,52 @@
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from arclet.entari import local_data
+
+
+@dataclass(slots=True)
+class LLMState:
+    default_model: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "LLMState":
+        value = data.get("default_model")
+        default_model = value if isinstance(value, str) and value else None
+        return cls(default_model=default_model)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _state_path() -> Path:
+    return local_data.get_data_file("entari_plugin_llm", "state.json")
+
+
+def _read_state() -> LLMState:
+    path = _state_path()
+    if not path.exists():
+        return LLMState()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return LLMState()
+    if not isinstance(data, dict):
+        return LLMState()
+    return LLMState.from_dict(data)
+
+
+def _write_state(data: LLMState) -> None:
+    path = _state_path()
+    path.write_text(json.dumps(data.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def get_default_model() -> str | None:
+    return _read_state().default_model
+
+
+def set_default_model(model_name: str | None) -> None:
+    state = _read_state()
+    state.default_model = model_name if model_name else None
+    _write_state(state)

entari_plugin_llm/_types.py

@@ -0,0 +1,35 @@
+from typing import Any, Literal, TypeAlias, TypedDict
+
+from typing_extensions import NotRequired
+
+JSON_VALUE: TypeAlias = str | int | float | bool | None
+JSON_TYPE: TypeAlias = dict[str, "JSON_TYPE"] | list["JSON_TYPE"] | JSON_VALUE
+
+
+class SystemMessage(TypedDict):
+    role: Literal["system"]
+    content: str
+    name: NotRequired[str | None]
+
+
+class UserMessage(TypedDict):
+    role: Literal["user"]
+    content: str | list[dict[str, Any]]
+    name: NotRequired[str | None]
+
+
+class AssistantMessage(TypedDict):
+    role: Literal["assistant"]
+    content: str | None
+    tool_calls: NotRequired[list[dict[str, Any]] | None]
+    reasoning_content: NotRequired[str | None]
+
+
+class ToolMessage(TypedDict):
+    role: Literal["tool"]
+    content: str
+    tool_call_id: str
+    name: NotRequired[str | None]
+
+
+Message: TypeAlias = SystemMessage | UserMessage | AssistantMessage | ToolMessage

entari_plugin_llm/config.py

@@ -0,0 +1,105 @@
+from typing import Any
+
+from arclet.entari import BasicConfModel, plugin_config
+from arclet.entari.config import model_field
+
+from ._jsondata import get_default_model
+from .exception import ModelNotFoundError
+
+
+class ScopedModel(BasicConfModel):
+    name: str
+    """用于 OpenAI API 的模型"""
+    alias: str | None = None
+    """模型的别名"""
+    api_key: str | None = None
+    """用于使用 OpenAI API 进行身份验证的 API 密钥。如果未设置，则回退到全局 api_key"""
+    base_url: str = "https://api.openai.com/v1"
+    """OpenAI API 的接口地址。如果未设置，则回退到全局 base_url"""
+    prompt: str = ""
+    """该模型使用的提示词。如果未设置，则回退到全局 prompt"""
+    extra: dict[str, Any] = model_field(default_factory=dict)
+    """传递给 LLM API 调用的额外参数"""
+
+
+class Config(BasicConfModel, extra="allow"):
+    api_key: str | None = None
+    """用于使用 OpenAI API 进行身份验证的全局 API 密钥。用作没有特定键的模型的后备"""
+    base_url: str = "https://api.openai.com/v1"
+    """OpenAI API 的全局接口地址。用作没有特定接口地址的模型的后备"""
+    prompt: str = ""
+    """全局提示词。用作没有特定提示词的模型的后备"""
+    models: list[ScopedModel] = model_field(default_factory=list)
+    """配置模型及其各自设置的列表"""
+    toolcall_max_steps: int = 8
+    """单个会话中工具调用的最大步骤数"""
+    context_length: int = 50
+    """上下文长度"""
+    tools: dict[str, dict[str, Any]] = model_field(default_factory=dict)
+    """工具"""
+
+    def _reload_tools(self):
+        loaded_tools: dict[str, dict[str, Any]] = {}
+
+        for key, value in self.tools.items():
+            if key.startswith("$"):
+                loaded_tools[key] = value
+                continue
+
+            tool_config = dict(value)
+            new_key = key
+
+            if key.startswith("~"):
+                new_key = key[1:]
+                if "$disable" not in tool_config or isinstance(tool_config["$disable"], bool):
+                    tool_config["$disable"] = True
+            elif key.startswith("?"):
+                new_key = key[1:]
+                tool_config["$optional"] = True
+
+            if key.startswith("::"):
+                new_key = new_key.replace("::", "entari_plugin_llm.tools.builtins.")
+
+            if tool_config.get("$disable"):
+                continue
+
+            loaded_tools[new_key] = tool_config
+
+        self.tools = loaded_tools
+
+    def __post_init__(self):
+        self._reload_tools()
+
+
+_conf = plugin_config(Config)
+
+
+def get_model_config(model_name: str | None = None) -> ScopedModel:
+    if model_name is None:
+        if not _conf.models:
+            raise ModelNotFoundError("No models configured.")
+
+        model_name = get_default_model()
+
+    for model in _conf.models:
+        if model.name == model_name or model.alias == model_name:
+            model_cp = ScopedModel(
+                name=model.name,
+                alias=model.alias,
+                api_key=model.api_key,
+                base_url=model.base_url,
+                prompt=model.prompt,
+                extra=model.extra,
+            )
+            if not model.api_key and _conf.api_key:
+                model_cp.api_key = _conf.api_key
+            if model.base_url == "https://api.openai.com/v1" and _conf.base_url != "https://api.openai.com/v1":
+                model_cp.base_url = _conf.base_url
+            if not model.prompt and _conf.prompt:
+                model_cp.prompt = _conf.prompt
+            return model_cp
+    raise ModelNotFoundError(f"Model {model_name} not found in config.")
+
+
+def get_model_list() -> set[str]:
+    return {m.name for m in _conf.models} | {m.alias for m in _conf.models if m.alias}

entari_plugin_llm/exception.py

@@ -0,0 +1 @@
+class ModelNotFoundError(Exception): ...

entari_plugin_llm/handlers/chat.py

@@ -0,0 +1,53 @@
+from collections import deque
+
+from arclet.entari import MessageChain, MessageCreatedEvent, Session, filter_
+from arclet.entari.config import config_model_validate
+from arclet.entari.event.config import ConfigReload
+from arclet.entari.event.send import SendResponse
+from arclet.letoderea import BLOCK, on
+from arclet.letoderea.context import Contexts
+
+from ..config import Config, _conf
+from ..exception import ModelNotFoundError
+from .manager import LLMSessionManager
+
+RECORD = deque(maxlen=16)
+
+
+@on(SendResponse)
+async def _record(event: SendResponse):
+    if event.result and event.session:
+        RECORD.append(event.session.event.sn)
+
+
+@on(MessageCreatedEvent, priority=1000).if_(filter_.to_me)
+async def run_conversation(session: Session, ctx: Contexts):
+    if session.event.sn in RECORD:
+        return BLOCK
+
+    try:
+        answer = await LLMSessionManager.chat(
+            session.elements,
+            session=session,
+            ctx=ctx,
+        )
+        if answer != "[END_OF_RESPONSE]":
+            await session.send(answer)
+    except ModelNotFoundError as e:
+        await session.send(MessageChain(str(e)))
+    except Exception as e:
+        await session.send(MessageChain(str(e)))
+    return BLOCK
+
+
+@on(ConfigReload)
+async def reload_config(event: ConfigReload):
+    if event.scope != "plugin":
+        return
+    if event.key not in ("entari_plugin_llm", "llm"):
+        return
+    new_conf = config_model_validate(Config, event.value)
+    _conf.models = new_conf.models
+    _conf.prompt = new_conf.prompt
+    _conf.context_length = new_conf.context_length
+    _conf.toolcall_max_steps = new_conf.toolcall_max_steps

entari_plugin_llm/handlers/check.py

@@ -0,0 +1,36 @@
+from arclet.entari.event.lifespan import Ready
+from arclet.letoderea import on
+
+from .._jsondata import get_default_model, set_default_model
+from ..config import _conf
+from ..log import logger
+
+
+@on(Ready)
+async def _():
+    if not _conf.models:
+        set_default_model(None)
+        logger.warning("未配置任何模型，已清空本地默认模型配置")
+        return
+
+    first_model = _conf.models[0].name
+    default_model = get_default_model()
+    if not default_model:
+        set_default_model(first_model)
+        logger.info(f"未检测到本地默认模型，已设置为首个模型: {first_model}")
+        return
+
+    matched = next(
+        (m for m in _conf.models if m.name == default_model or m.alias == default_model),
+        None,
+    )
+    if matched is None:
+        set_default_model(first_model)
+        logger.warning(
+            f"本地默认模型不存在于当前配置: {default_model}，已重置为: {first_model}",
+        )
+        return
+
+    if matched.name != default_model:
+        set_default_model(matched.name)
+        logger.info(f"已将本地默认模型标准化为模型名: {matched.name}")

entari_plugin_llm/handlers/command.py

@@ -0,0 +1,188 @@
+from arclet.alconna import Alconna, Args, MultiVar, Option, Subcommand, store_true
+from arclet.entari import MessageChain, Session, command
+from arclet.entari.const import ITEM_MESSAGE_REPLY
+from arclet.letoderea import BLOCK, Contexts
+
+from .._jsondata import set_default_model
+from ..config import get_model_config, get_model_list
+from ..exception import ModelNotFoundError
+from .manager import LLMSessionManager
+from .utils import render_model_list, render_session_list, select_session
+
+llm_alc = Alconna(
+    "llm",
+    Args["content?#内容", MultiVar(str)],
+    Option("-m|--model", Args["model?#模型名称", str], help_text="指定模型"),
+    Option(
+        "-n|--new",
+        dest="new_opt",
+        default=False,
+        action=store_true,
+        help_text="创建新会话",
+    ),
+    Subcommand("new", dest="new_cmd", help_text="创建新会话"),
+    Subcommand("switch", Args["session_id?#会话ID", str], help_text="切换会话"),
+    Subcommand("delete", Args["session_id?#会话ID", str], help_text="删除会话"),
+    Subcommand(
+        "session",
+        Option("-l|--list", help_text="查看会话列表"),
+        help_text="查看当前会话信息",
+    ),
+    Subcommand(
+        "model",
+        Args["model?#模型名称", str],
+        Option("-l|--list", help_text="查看模型列表"),
+        help_text="查看当前模型信息",
+    ),
+)
+
+llm_alc.shortcut("ai", {"command": "llm", "fuzzy": True, "prefix": True})
+
+llm_disp = command.mount(llm_alc)
+
+
+@llm_disp.handle(priority=25)
+async def _(
+    ctx: Contexts,
+    session: Session,
+    content: command.Match[MessageChain],
+    new_opt: command.Query[bool] = command.Query("new_opt.value"),
+    model: command.Query[str] = command.Query("model.model"),
+):
+    user_prompt = MessageChain([])
+
+    if reply := ctx.get(ITEM_MESSAGE_REPLY):
+        user_prompt += reply.origin.message
+
+    if content.available:
+        user_prompt += content.result
+
+    if not user_prompt:
+        resp = await session.prompt("需要我为你做些什么？")
+        if not resp:
+            await session.send("等待超时")
+            return BLOCK
+        user_prompt = resp
+
+    try:
+        answer = await LLMSessionManager.chat(
+            user_prompt,
+            session=session,
+            ctx=ctx,
+            model=model.result if model.available else None,
+            new=new_opt.result,
+        )
+        if answer != "[END_OF_RESPONSE]":
+            await session.send(answer)
+    except ModelNotFoundError as e:
+        await session.send(MessageChain(str(e)))
+    except Exception as e:
+        await session.send(MessageChain(str(e)))
+
+    return BLOCK
+
+
+@llm_disp.assign("new_cmd")
+async def _(session: Session):
+    new_session = await LLMSessionManager.create_new_session(f"{session.account.platform}@{session.user.id}")
+    await session.send(f"以创建并切换到新会话\n会话ID: {new_session.session_id}")
+    return BLOCK
+
+
+@llm_disp.assign("switch")
+async def _(session: Session, session_id: command.Match[str]):
+    if not session_id.available:
+        selected = await select_session(session)
+        if selected is None:
+            return BLOCK
+
+        session_id.result = selected
+
+    switched = await LLMSessionManager.switch(f"{session.account.platform}@{session.user.id}", session_id.result)
+    await session.send("切换成功" if switched else "未找到对应会话")
+    return BLOCK
+
+
+@llm_disp.assign("delete")
+async def _(session: Session, session_id: command.Match[str]):
+    if not session_id.available:
+        selected = await select_session(session)
+        if selected is None:
+            return BLOCK
+
+        session_id.result = selected
+    info = await LLMSessionManager.get_current_session_info(f"{session.account.platform}@{session.user.id}")
+    deleted = await LLMSessionManager.delete(f"{session.account.platform}@{session.user.id}", session_id.result)
+    if deleted:
+        rows = await LLMSessionManager.list_sessions(f"{session.account.platform}@{session.user.id}")
+        if not rows:
+            await LLMSessionManager.create_new_session(f"{session.account.platform}@{session.user.id}")
+            await session.send("删除成功，已自动创建新会话")
+        elif info and info["session_id"] == session_id.result:
+            switched = await LLMSessionManager.switch(
+                f"{session.account.platform}@{session.user.id}", rows[0].session_id
+            )
+            await session.send("删除成功，已切换到最近的会话" if switched else "删除成功，但未找到对应会话")
+        else:
+            await session.send("删除成功，当前会话列表：\n" + render_session_list(rows))
+    else:
+        await session.send("未找到对应会话")
+    return BLOCK
+
+
+@llm_disp.assign("session", priority=20)
+async def _(session: Session):
+    info = await LLMSessionManager.get_current_session_info(f"{session.account.platform}@{session.user.id}")
+    if info is None:
+        await session.send("当前没有活动会话")
+        return BLOCK
+
+    created_at = info["created_at"].strftime("%Y-%m-%d %H:%M:%S")
+    await session.send(
+        "\n".join(
+            [
+                f"会话ID: {info['session_id']}",
+                f"话题: {info['topic']}",
+                f"消息数: {info['message_count']}",
+                f"累计 Token: {info['total_tokens']}",
+                f"创建时间: {created_at}",
+            ]
+        )
+    )
+    return BLOCK
+
+
+@llm_disp.assign("session.list")
+async def _(session: Session):
+    rows = await LLMSessionManager.list_sessions(f"{session.account.platform}@{session.user.id}")
+
+    if not rows:
+        await session.send("暂无会话")
+        return BLOCK
+
+    await session.send(render_session_list(rows))
+    return BLOCK
+
+
+@llm_disp.assign("model", priority=20)
+async def _(session: Session, model: command.Match[str]):
+    if model.available:
+        if model.result not in get_model_list():
+            await session.send(render_model_list())
+            return BLOCK
+
+        conf = get_model_config(model.result)
+        set_default_model(conf.name)
+
+        await session.send(f"已切换默认模型: {conf.name}")
+        return BLOCK
+
+    conf = get_model_config()
+    await session.send(render_model_list())
+    return BLOCK
+
+
+@llm_disp.assign("model.list")
+async def _(session: Session):
+    await session.send(render_model_list())
+    return BLOCK