Documentation Index
Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt
Use this file to discover all available pages before exploring further.
Builtins API Reference
SelfReference
from SimpleLLMFunc.builtin import SelfReference
Constructor
Key Methods
| Method | Description |
|---|
bind_history(key, history) | Bind a conversation history to a memory key |
get_history(key) | Get the current history for a key |
get_experiences(key) | Get stored experiences for a key |
Memory Key Isolation
Each key has independent state:
- History (conversation transcript)
- Experiences (durable facts)
- Summary state (compaction checkpoints)
- Fork handles (child agent state)
Usage with @llm_chat
# Automatic (recommended)
@llm_chat(llm_interface=llm, self_reference_key="agent_main", ...)
async def agent(...):
...
# Explicit backend
selfref = SelfReference()
selfref.bind_history("my_key", initial_history)
@llm_chat(llm_interface=llm, self_reference=selfref, self_reference_key="my_key", ...)
async def agent(...):
...
Runtime Primitives (via PyRepl)
When SelfRef is active, these are available in execute_code:
# Context
runtime.selfref.context.inspect() -> dict
runtime.selfref.context.remember(text: str) -> dict # {id, text}
runtime.selfref.context.forget(experience_id: str) -> bool
runtime.selfref.context.compact(
goal: str,
instruction: str,
discoveries: list[str],
completed: list[str],
current_status: str,
likely_next_work: str,
relevant_files_directories: list[str],
remember: list[str] = [],
) -> dict # {assistant_message, ...}
# Fork
runtime.selfref.fork.spawn(
task: str,
instruction: str,
...
) -> dict # {fork_id, status}
runtime.selfref.fork.gather_all(include_history: bool = False) -> dict # {fork_id: ForkResult}
PyRepl
from SimpleLLMFunc.builtin import PyRepl
Constructor
PyRepl(working_directory: Optional[Path | str] = None)
| Parameter | Default | Description |
|---|
working_directory | None (cwd) | Working directory for the REPL process |
Properties
| Property | Type | Description |
|---|
.toolset | List[Tool] | The two tools: execute_code + reset_repl |
Methods
| Method | Description |
|---|
install_primitive_pack(pack) | Register a PrimitivePack in this REPL |
get_runtime_backend(name) | Get an installed backend by pack namespace |
reset() | Clear REPL variables (preserves backends) |
execute_code
async def execute_code(code: str, event_emitter=None) -> dict:
"""Run Python code in the persistent REPL."""
{
"stdout": str, # Captured stdout
"stderr": str, # Captured stderr
"return_value": str, # Repr of last expression (or None)
"error": str | None, # Error message if failed
"execution_time_ms": float,
}
reset_repl
async def reset_repl() -> str:
"""Clear REPL variables. Preserves runtime backends."""
Example
from SimpleLLMFunc.builtin import PyRepl
repl = PyRepl(working_directory="/path/to/project")
@llm_chat(llm_interface=llm, toolkit=repl.toolset, stream=True)
async def code_agent(message: str, history: list | None = None):
"""Execute Python to solve problems."""
pass
Custom Events
| Event Name | Data | Description |
|---|
kernel_stdout | {"text": str} | Real-time stdout line |
kernel_stderr | {"text": str} | Real-time stderr line |
Execution Limits
| Setting | Default |
|---|
| Execution timeout | 600 seconds |
| Input idle timeout | 300 seconds |
| Output truncation | ~20,000 tokens → temp file |
from SimpleLLMFunc.builtin import FileToolset
Constructor
FileToolset(workspace: Path | str)
workspace. Path traversal above workspace is rejected.
Properties
| Property | Type | Description |
|---|
.toolset | List[Tool] | The 5 file tools |
read_file
async def read_file(path: str, start_line: int = None, end_line: int = None) -> str
<lineno> | <content>.
read_image
async def read_image(path: str) -> ImgPath
grep
async def grep(pattern: str, path_pattern: str) -> str
path_pattern scopes which files to search.
sed
async def sed(path: str, start_line: int, end_line: int, pattern_to_be_replaced: str, new_string: str) -> str
echo_into
async def echo_into(path: str, content: str) -> str
Stale-Write Protection
FileToolset tracks file hashes on read. If a file was modified externally between read and write, sed and echo_into will reject the write and ask the agent to re-read.
Example
from SimpleLLMFunc.builtin import FileToolset
files = FileToolset("/path/to/workspace")
@llm_chat(llm_interface=llm, toolkit=files.toolset, stream=True)
async def file_agent(message: str, history: list | None = None):
"""An agent that can read and edit files in the workspace."""
pass