Skip to main content

Documentation Index

Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt

Use this file to discover all available pages before exploring further.

​
Runtime Patches

ContextMutation is SimpleLLMFunc’s internal typed patch protocol for transcript edits produced by runtime side effects. Mutations do not define the whole context. The final LLM request is compiled from:
  1. invocation configuration — docstring prompt, template parameters, tool guidance, output contract, SelfRef snapshot;
  2. a base transcript/message list — history, current user input, previous assistant/tool messages;
  3. runtime patches — the ContextMutation objects described on this page.
Understanding mutations is useful when debugging framework internals, but application code usually interacts with higher-level surfaces such as tools, event streams, history, and SelfRef primitives.

​
The Mutation Union

ContextMutation = Union[
    AssistantMessageMutation,
    ToolResultMutation,
    MultimodalToolResultMutation,
    UserMessageMutation,
    ContextReplaceMutation,
    ContextSummaryMutation,
    ExperienceRememberMutation,
    ExperienceForgetMutation,
    AssistantTruncatedMutation,
    ToolCancelledMutation,
]

​
Standard Flow Patches

These are produced during normal ReAct loop operation.

​
AssistantMessageMutation

Emitted when the LLM produces a response (text, tool calls, or both). 
@dataclass
class AssistantMessageMutation:
    role: Literal["assistant"] = "assistant"
    content: Optional[str] = None
    tool_calls: List[Dict[str, Any]] = field(default_factory=list)
    reasoning_details: List[Dict[str, Any]] = field(default_factory=list)
When: After every successful LLM call.
Effect: Appends an assistant message to the transcript.
Producer: execute_single_llm_phase() in the ReAct loop.

​
ToolResultMutation

Emitted when a tool finishes execution with a text result. 
@dataclass
class ToolResultMutation:
    tool_call_id: str
    content: str
    role: Literal["tool"] = "tool"
When: After each tool in a batch completes.
Effect: Appends a tool result message linked to its call by tool_call_id.
Producer: schedule_tool_batch() → tool execution.

​
MultimodalToolResultMutation

Emitted when a tool returns images or mixed content that can’t be represented as a simple string. 
@dataclass
class MultimodalToolResultMutation:
    tool_call_id: str
    tool_name: str
    arguments: str
    user_messages: List[Dict[str, Any]]
When: Tool returns ImgPath, ImgUrl, or a tuple containing multimodal content.
Effect: Replaces the tool call with an assistant summary message + user messages containing the multimodal content. This restructuring is required because most providers only support images in user messages.
Producer: schedule_tool_batch() with multimodal tool returns.

​
UserMessageMutation

Emitted when a new user message needs to be injected mid-loop. 
@dataclass
class UserMessageMutation:
    message: Dict[str, Any]
When: Rare in normal flow. Used by input routing (e.g., TUI tool-input) or custom hooks.
Effect: Appends a user message to the transcript.
Producer: Custom hooks, AgentInputRouter.

​
Context Reset Patches

These replace or restructure the working transcript.

​
ContextReplaceMutation

Hard reset — replaces the entire message list. 
@dataclass
class ContextReplaceMutation:
    messages: List[Dict[str, Any]]
When: External history override, fork context injection.
Effect: Discards the current transcript entirely, replaces with messages.
Producer: SelfRef fork spawn (to set child context), custom hooks.

​
ContextSummaryMutation

Context compaction — replaces transcript with a summary and optionally stores new experiences. 
@dataclass
class ContextSummaryMutation:
    summary_message: Dict[str, Any]
    remember: List[Dict[str, str]] = field(default_factory=list)
When: runtime.selfref.context.compact(...) is called from a tool.
Effect:
  1. Preserves the system prompt message
  2. Replaces the working transcript with summary_message
  3. Stores any items in remember as durable experiences
Producer: SelfRef compact primitive.

​
Experience Patches

These update durable experiences stored in the system context (via SelfRef).

​
ExperienceRememberMutation

Store a new durable experience. 
@dataclass
class ExperienceRememberMutation:
    text: str
When: runtime.selfref.context.remember(...) is called.
Effect: Adds the text as a new experience entry in the system context’s experience section.
Producer: SelfRef remember primitive.

​
ExperienceForgetMutation

Remove a stored experience by ID. 
@dataclass
class ExperienceForgetMutation:
    experience_id: str
When: runtime.selfref.context.forget(...) is called.
Effect: Removes the experience with the matching ID from the system context.
Producer: SelfRef forget primitive.

​
Abort Patches

These handle interruption and cancellation.

​
AssistantTruncatedMutation

Records a partially-received assistant response that was interrupted. 
@dataclass
class AssistantTruncatedMutation:
    partial_content: str
    abort_reason: str = ""
When: AbortSignal fires while the LLM is streaming.
Effect: Appends the partial content as an assistant message with truncation metadata.
Producer: execute_single_llm_phase() on abort.

​
ToolCancelledMutation

Records a tool call that was aborted before completion. 
@dataclass
class ToolCancelledMutation:
    tool_call_id: str
    tool_name: str
    abort_reason: str = ""
When: AbortSignal fires while tools are executing.
Effect: Appends a cancelled-tool result message so the transcript remains structurally valid (every tool call has a corresponding result).
Producer: schedule_tool_batch() on abort.

​
Mutation Application Order

Mutations are applied sequentially in the order they were produced. Within a single ReAct iteration:
  1. Hook mutations (from SelfRef session collect_context_mutations) — applied first
  2. LLM mutations (AssistantMessage) — from the LLM call
  3. Tool mutations (ToolResult, MultimodalToolResult, Experience*) — from tool execution
  4. Abort mutations (AssistantTruncated, ToolCancelled) — if interruption occurred
Experience mutations (Remember/Forget) are accumulated and committed as a batch before the next non-experience mutation is applied. This ensures experiences are stored before any context replacement that might reference them.

​
The Guarantee

Runtime-produced transcript edits go through this patch protocol. This means LLM calls, tool execution, SelfRef primitives, and abort handling do not directly mutate the live transcript. This does not mean every LLM-visible input comes from a mutation. The initial transcript, docstring/system prompt, template parameters, tool guidance, and SelfRef snapshot are separate compile inputs.

Next: Compile Pipeline

How invocation config, transcript, and runtime patches are transformed into the final LLM request.