装饰器 API 参考

@llm_function

from SimpleLLMFunc import llm_function

@llm_function(
    llm_interface: LLM_Interface,
    toolkit: Optional[List[Tool]] = None,
    max_tool_calls: Optional[int] = None,
    system_prompt_template: Optional[str] = None,
    user_prompt_template: Optional[str] = None,
    **llm_kwargs: Any,
)

将一个异步函数转换为 LLMFunction callable instance。await fn(...) 返回解析后的类型化结果；fn.stream(...) 产出 ReactOutput。对于多模态输入，llm_function 保持普通 Python 函数风格：显式把图片参数标注为 ImgUrl、ImgPath，或包含这些类型的列表/Union。ImgUrl 支持 http(s) URL 与 data: URL；ImgPath 会在 provider 边界编码为图片 data URL。

参数

参数	类型	默认值	描述
`llm_interface`	`LLM_Interface`	必填	要调用的模型
`toolkit`	`List[Tool] \| None`	`None`	模型可用的工具列表
`max_tool_calls`	`int \| None`	`None`	强制返回最终答案前的最大工具调用次数。`None` = 无限制
`system_prompt_template`	`str \| None`	`None`	覆盖系统提示词模板
`user_prompt_template`	`str \| None`	`None`	覆盖用户提示词模板
`**llm_kwargs`	`Any`	—	转发给 LLM 的参数（temperature、max_tokens 等）

特殊调用时参数

参数	类型	描述
`_template_params`	`Dict[str, Any]`	文档字符串中 `{占位符}` 的模板值
`_abort_signal`	`AbortSignal`	取消信号

示例

from pydantic import BaseModel, Field
from SimpleLLMFunc import llm_function, OpenAICompatible

llm = OpenAICompatible.load_from_json_file("provider.json")["openrouter"]["gpt-4o"]

class Sentiment(BaseModel):
    label: str = Field(description="positive, negative, or neutral")
    score: float = Field(description="confidence 0.0–1.0")

@llm_function(llm_interface=llm)
async def classify(text: str) -> Sentiment:
    """Classify the sentiment of the text."""
    pass

# Usage
result = await classify("I love this!")
print(result)  # Sentiment(label="positive", score=0.95)

@llm_chat

from SimpleLLMFunc import llm_chat

@llm_chat(
    llm_interface: LLM_Interface,
    toolkit: Optional[List[Tool]] = None,
    max_tool_calls: Optional[int] = DEFAULT_MAX_TOOL_CALLS,
    stream: bool = False,
    strict_signature: bool = False,
    self_reference: Optional[SelfReference] = None,
    self_reference_key: Optional[str] = None,
    **llm_kwargs: Any,
)

创建一个 LLMChat callable instance。调用它会产出 AsyncGenerator[ReactOutput, None]，并为 SelfRef 提供稳定的 agent identity。对于多模态 chat 输入，推荐使用单个显式的 message: UserChatMessage 参数。UserChatMessage 兼容 OpenAI Chat Completions user message，可以包含 text 与 image_url content parts。

参数

参数	类型	默认值	描述
`llm_interface`	`LLM_Interface`	必填	要调用的模型
`toolkit`	`List[Tool] \| None`	`None`	可用的工具列表
`max_tool_calls`	`int \| None`	框架默认值	每次调用的工具调用上限
`stream`	`bool`	`False`	启用流式输出
`strict_signature`	`bool`	`False`	强制严格的参数验证
`self_reference`	`SelfReference \| None`	`None`	显式 SelfReference（自引用）后端
`self_reference_key`	`str \| None`	`None`	为此键自动创建 SelfReference
`**llm_kwargs`	`Any`	—	转发给 LLM 的参数

特殊调用时参数

参数	类型	描述
`_template_params`	`Dict[str, Any]`	模板值
`_abort_signal`	`AbortSignal`	取消信号
`_too_long_to_file`	`bool`	将过长的工具结果截断到临时文件

History 参数

函数必须具有名为 history 或 chat_history 的参数（类型：list | None）。框架使用该参数来承载对话状态。

示例

from SimpleLLMFunc import llm_chat, tool

@tool
async def search(query: str) -> str:
    """Search for information."""
    return f"Result for: {query}"

@llm_chat(llm_interface=llm, toolkit=[search], stream=True)
async def agent(message: str, history: list | None = None):
    """A helpful research assistant."""
    pass

# Usage
history = []
async for output in agent("What is SimpleLLMFunc?", history):
    if is_response_yield(output):
        print(output.response)
        history = output.messages

多模态 Chat 示例

from SimpleLLMFunc import llm_chat
from SimpleLLMFunc.type import UserChatMessage, ImgUrl

@llm_chat(llm_interface=llm)
async def vision_agent(message: UserChatMessage, history: list | None = None):
    """回答用户图片相关的问题。"""
    pass

async for output in vision_agent(
    UserChatMessage.multimodal(
        "这张图里有什么？",
        ImgUrl("https://example.com/cat.jpg", detail="high"),
    ),
    history=[],
):
    ...

@tool

from SimpleLLMFunc import tool

@tool(
    name: Optional[str] = None,
    description: Optional[str] = None,
    best_practices: Optional[Sequence[str]] = None,
    prompt_injection_builder: Optional[Callable] = None,
    too_long_to_file: bool = False,
)

将一个异步函数注册为可被 LLM 调用的工具。可不带参数使用，也可带参数使用。

参数

参数	类型	默认值	描述
`name`	`str \| None`	函数名	覆盖工具名称
`description`	`str \| None`	来自文档字符串	覆盖工具描述
`best_practices`	`Sequence[str] \| None`	来自文档字符串	覆盖最佳实践列表
`prompt_injection_builder`	`Callable \| None`	`None`	动态系统提示词注入
`too_long_to_file`	`bool`	`False`	将超过 20k token 的结果写入临时文件

要求

被装饰的函数必须是 async def
文档字符串应包含 Args、Returns 和 Best Practices 部分
参数类型将成为工具的 JSON schema

示例

from SimpleLLMFunc import tool

@tool
async def calculate(expression: str) -> float:
    """
    Evaluate a math expression.

    Args:
        expression: Python math expression (e.g., "2 ** 10").

    Returns:
        Numeric result.

    Best Practices:
        - Use Python syntax.
        - Keep expressions simple.
    """
    return float(eval(expression))

# Used without parentheses (simple form)
@tool
async def simple_tool(x: str) -> str:
    """Do something."""
    return x.upper()

Tool 类

from SimpleLLMFunc import Tool

tool_instance = Tool(
    name: str,
    description: str,
    func: Callable[..., Awaitable[Any]],
    best_practices: Optional[Sequence[str]] = None,
    prompt_injection_builder: Optional[Callable] = None,
    too_long_to_file: bool = False,
)

用于不使用装饰器的方式以编程方式创建工具。

方法

方法	返回值	描述
`.tool_spec()`	`Dict`	工具规格字典
`.to_openai_tool()`	`Dict`	OpenAI 格式的工具定义
`.serialize_tools(tools)`	`List[Dict]`	类方法：序列化工具列表
`.build_system_prompt_injection(context)`	`str \| None`	动态提示词注入

属性

属性	类型	描述
`.name`	`str`	工具名称
`.description`	`str`	工具描述
`.parameters`	`List[Parameter]`	提取的参数列表
`.func`	`Callable`	底层异步函数

​装饰器 API 参考

​@llm_function

​参数

​特殊调用时参数

​示例

​@llm_chat

​参数

​特殊调用时参数

​History 参数

​示例

​多模态 Chat 示例

​@tool

​参数

​要求

​示例

​Tool 类

​方法

​属性

装饰器 API 参考

@llm_function

参数

特殊调用时参数

示例

@llm_chat

参数

特殊调用时参数

History 参数

示例

多模态 Chat 示例

@tool

参数

要求

示例

Tool 类

方法

属性