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.

​
Context-Centric

SimpleLLMFunc does not treat provider messages as something every component edits directly. Each LLM call is compiled into a provider-facing message list from three inputs:
  1. Invocation configuration — docstring prompt, template parameters, tool guidance, output contract, and SelfRef snapshot.
  2. Base transcript — the history/current messages for this invocation.
  3. Runtime transcript patches — internal typed edits produced by LLM calls, tool execution, SelfRef primitives, abort handling, and compaction.
This is the precise meaning of the context model: 
provider messages = render(invocation config, patch(base transcript, runtime patches))

​
The Problem

In many agent systems, the same mutable message list is edited from everywhere:
  • tools append results directly;
  • orchestration pushes assistant messages into the list;
  • memory systems inject or rewrite context in arbitrary places;
  • summarization overwrites history in place;
  • abort/cancel handling leaves partially valid messages behind.
The result is unpredictable context. It becomes difficult to answer: “what exactly will the model see next?”

​
The Runtime Patch Model

SimpleLLMFunc uses ContextMutation as an internal transcript patch protocol. A mutation is not the whole context and not the user’s main API. It is a typed incremental edit to the base transcript, produced by runtime side effects and applied at a compile boundary. 
runtime side effect → ContextMutation → [accumulate] → apply to transcript → render LLM request
Examples:
Runtime factInternal patch
LLM produced a final assistant messageAssistantMessageMutation
Tool returned textToolResultMutation
Tool returned multimodal contentMultimodalToolResultMutation
SelfRef compacted working contextContextSummaryMutation
User aborted streaming LLM outputAssistantTruncatedMutation
Tool execution was cancelledToolCancelledMutation
The rule is:
Runtime side effects do not directly mutate the live transcript. They produce typed patches, and the compile boundary applies those patches in order.
This keeps tool scheduling, LLM output handling, SelfRef, compaction, and abort behavior from racing over the same mutable list.

​
What Mutations Are Not

Mutations are deliberately narrower than “context”. They are not:
  • the source of the docstring/system prompt;
  • the source of template parameters;
  • the source of tool schemas or tool best-practice prompts;
  • the source of the initial history passed to @llm_chat;
  • the public event stream consumed by UIs;
  • the primary user-facing way to customize an agent.
Those belong to invocation configuration, transcript input, tools, SelfRef primitives, or event consumers.

​
Why This Still Matters

​
Safe concurrency

Parallel tools can finish in any order. Instead of each tool directly appending to a shared message list, tools produce result patches. The runtime collects them and applies them at the next compile boundary.

​
Controlled compaction

Context compaction is a transcript patch. It can replace stale working messages with a summary while preserving system prompt and durable experiences.

​
Valid abort/cancel state

Abort handling must leave a structurally valid transcript. AssistantTruncatedMutation and ToolCancelledMutation centralize this repair logic instead of scattering it across the loop.

​
Testable internals

Patch application can be tested separately from prompt rendering and provider transport.

​
The Compile Boundary

The compile boundary has two jobs:
  1. Patch the base transcript with pending runtime mutations.
  2. Render the provider request from the patched transcript plus invocation configuration.
┌─────────────────────────────────────────────┐
│  Inputs                                      │
│                                             │
│  Invocation config                           │
│    - docstring / prompt contract             │
│    - template params                         │
│    - tool guidance                           │
│    - SelfRef snapshot                        │
│                                             │
│  Base transcript / history                   │
│  Runtime patches (ContextMutation[])         │
├──────────── COMPILE BOUNDARY ────────────────┤
│                                             │
│  apply_mutations(transcript, patches)        │
│  → patched transcript                        │
│                                             │
│  convert_to_llm_request(...)                 │
│  → provider-facing messages[]                │
└─────────────────────────────────────────────┘
See Compile Pipeline for the technical walkthrough.

​
Practical Implication

For most users, mutations are invisible. You write functions, provide history, mount tools, consume events, and optionally use SelfRef primitives. If you are debugging framework internals, mutations explain how runtime effects become transcript edits. If you are building application code, your main surfaces are still:
  • @llm_function / @llm_chat signatures and docstrings;
  • history / chat_history;
  • tools and event streams;
  • SelfRef primitives such as remember(...) and compact(...).

Deep dive: Runtime Patches

See the internal mutation types and when the runtime produces them.