Decorators

API reference for @llm_function, @llm_chat, and @tool

Decorators API Reference

@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,
)

Transforms an async function into an LLMFunction callable instance. await fn(...) returns the parsed typed result; fn.stream(...) yields ReactOutput.

For multimodal input, keep the normal Python-function style: explicitly type image parameters as ImgUrl, ImgPath, or lists/unions containing those types. ImgUrl accepts http(s) URLs and data: URLs; ImgPath is encoded as an image data URL at the provider boundary.

Parameters

Parameter	Type	Default	Description
llm_interface	LLM_Interface	required	Model to call
toolkit	List[Tool] | None	None	Tools available to the model
max_tool_calls	int | None	None	Maximum tool calls before forcing final answer. None = unlimited
system_prompt_template	str | None	None	Override the system prompt template
user_prompt_template	str | None	None	Override the user prompt template
**llm_kwargs	Any	—	Forwarded to LLM (temperature, max_tokens, etc.)

Special Call-Time Parameters

Parameter	Type	Description
_template_params	Dict[str, Any]	Template values for docstring {placeholders}
_abort_signal	AbortSignal	Cancellation signal

Example

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,
)

Creates an LLMChat callable instance. Calling it yields AsyncGenerator[ReactOutput, None] and gives SelfRef a stable agent identity.

For multimodal chat input, prefer a single explicit message: UserChatMessage argument. UserChatMessage is OpenAI Chat Completions-compatible and can contain text and image_url content parts.

Parameters

Parameter	Type	Default	Description
llm_interface	LLM_Interface	required	Model to call
toolkit	List[Tool] | None	None	Available tools
max_tool_calls	int | None	framework default	Tool call limit per invocation
stream	bool	False	Enable streaming chunks
strict_signature	bool	False	Enforce strict parameter validation
self_reference	SelfReference | None	None	Explicit SelfReference backend
self_reference_key	str | None	None	Auto-create SelfReference for this key
**llm_kwargs	Any	—	Forwarded to LLM

Special Call-Time Parameters

Parameter	Type	Description
_template_params	Dict[str, Any]	Template values
_abort_signal	AbortSignal	Cancellation signal
_too_long_to_file	bool	Truncate long tool results to temp file

History Parameter

The function must have a parameter named history or chat_history (type: list | None). The framework uses it to carry conversation state.

Example

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

Multimodal Chat Example

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):
    """Answer questions about user-provided images."""
    pass

async for output in vision_agent(
    UserChatMessage.multimodal(
        "What is in this image?",
        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,
)

Registers an async function as a tool callable by the LLM. Can be used with or without arguments.

Parameters

Parameter	Type	Default	Description
name	str | None	function name	Override tool name
description	str | None	from docstring	Override tool description
best_practices	Sequence[str] | None	from docstring	Override best practices list
prompt_injection_builder	Callable | None	None	Dynamic system prompt injection
too_long_to_file	bool	False	Write results > 20k tokens to temp file

Requirements

• Decorated function must be async def
• Docstring should include Args, Returns, and Best Practices sections
• Parameter types become the tool’s JSON schema

Example

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 Class

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,
)

For programmatic tool creation without the decorator.

Methods

Method	Returns	Description
.tool_spec()	Dict	Tool specification dict
.to_openai_tool()	Dict	OpenAI-format tool definition
.serialize_tools(tools)	List[Dict]	Class method: serialize tool list
.build_system_prompt_injection(context)	str | None	Dynamic prompt injection

Properties

Property	Type	Description
.name	str	Tool name
.description	str	Tool description
.parameters	List[Parameter]	Extracted parameters
.func	Callable	The underlying async function