entari-plugin-llm 0.1.0__tar.gz

entari_plugin_llm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ARCLET
+
+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.

entari_plugin_llm-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.1
+Name: entari-plugin-llm
+Version: 0.1.0
+Summary: An Entari Plugin for LLM Chat with Function Call
+Author-Email: RF-Tar-Railt <rf_tar_railt@qq.com>, KomoriDev <mute231010@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: arclet.entari[cron,dotenv,reload,yaml]>=0.18.0rc2
+Requires-Dist: docstring-parser>=0.17.0
+Requires-Dist: litellm>=1.83.7
+Requires-Dist: entari-plugin-database>=0.3.1
+Provides-Extra: browser
+Requires-Dist: entari-plugin-browser>=0.5.4; extra == "browser"
+Provides-Extra: google
+Requires-Dist: litellm[google]>=1.83.7; extra == "google"
+Description-Content-Type: text/markdown
+
+# 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-0.1.0/README.md

@@ -0,0 +1 @@
+.\src\entari_plugin_llm\README.md

entari_plugin_llm-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "entari-plugin-llm"
+version = "0.1.0"
+description = "An Entari Plugin for LLM Chat with Function Call"
+authors = [
+    { name = "RF-Tar-Railt", email = "rf_tar_railt@qq.com" },
+    { name = "KomoriDev", email = "mute231010@gmail.com" },
+]
+dependencies = [
+    "arclet.entari[yaml,cron,reload,dotenv]>=0.18.0rc2",
+    "docstring-parser>=0.17.0",
+    "litellm>=1.83.7",
+    "entari-plugin-database>=0.3.1",
+]
+requires-python = ">=3.10"
+readme = "README.md"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+browser = [
+    "entari-plugin-browser>=0.5.4",
+]
+google = [
+    "litellm[google]>=1.83.7",
+]
+
+[dependency-groups]
+dev = [
+    "entari-plugin-server>=0.6.2",
+    "satori-python-adapter-onebot11>=0.4.2",
+    "ruff>=0.14.10",
+    "satori-python-adapter-console>=0.5.1",
+    "agno>=2.5.8",
+    "ddgs>=9.11.2",
+    "satori-python-adapter-milky>=0.3.1",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "UP",
+    "C",
+    "T",
+    "PYI",
+    "PT",
+    "Q",
+    "I",
+]
+ignore = [
+    "C901",
+    "T201",
+    "E731",
+    "E402",
+    "PYI055",
+]
+
+[tool.pyright]
+pythonVersion = "3.10"
+pythonPlatform = "All"
+typeCheckingMode = "basic"
+
+[tool.pdm]
+distribution = true
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"

entari_plugin_llm-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/entari_plugin_llm/exception.py

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

entari_plugin_llm-0.1.0/src/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-0.1.0/src/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}")