Skip to main content

​
Builtins API Reference

​
SelfReference

from SimpleLLMFunc.builtin import SelfReference
Durable backend for agent memory, context management, and fork orchestration.

​
Constructor

SelfReference()

​
Key Methods

MethodDescription
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
Persistent IPython REPL in a subprocess with runtime primitive support.

​
Constructor

PyRepl(working_directory: Optional[Path | str] = None)
ParameterDefaultDescription
working_directoryNone (cwd)Working directory for the REPL process

​
Properties

PropertyTypeDescription
.toolsetList[Tool]The two tools: execute_code + reset_repl

​
Methods

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

​
Tools Provided

​
execute_code

async def execute_code(code: str, event_emitter=None) -> dict:
    """Run Python code in the persistent REPL."""
Returns: 
{
    "stdout": str,          # Captured stdout
    "stderr": str,          # Captured stderr
    "return_value": str,    # Repr of last expression (or None)
    "artifacts": list,      # Captured image artifacts for direct PyRepl.execute calls
    "error": str | None,    # Error message if failed
    "execution_time_ms": float,
}
When used through the agent toolset, execute_code returns a natural-language summary. If code outputs images through display(Image(...)), an image-rich last expression, or ImgPath(...) / ImgUrl(...), the tool result becomes multimodal so the model can inspect the image.

​
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 NameDataDescription
kernel_stdout{"text": str}Real-time stdout line
kernel_stderr{"text": str}Real-time stderr line

​
Execution Limits

SettingDefault
Execution timeout600 seconds
Input idle timeout300 seconds
Output truncation~20,000 tokens → temp file

​
FileToolset

from SimpleLLMFunc.builtin import FileToolset
Workspace-scoped file operations with stale-write protection.

​
Constructor

FileToolset(workspace: Path | str)
All paths are resolved relative to workspace. Path traversal above workspace is rejected.

​
Properties

PropertyTypeDescription
.toolsetList[Tool]The 5 file tools

​
Tools Provided

​
read_file

async def read_file(path: str, start_line: int = None, end_line: int = None) -> str
Returns line-numbered content: <lineno> | <content>.

​
read_image

async def read_image(path: str) -> ImgPath
Returns image as multimodal content (detail=“high”).

​
grep

async def grep(pattern: str, path_pattern: str) -> str
Regex search over workspace files. 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
Regex find-and-replace within a line range. Protected by hash-based stale detection.

​
echo_into

async def echo_into(path: str, content: str) -> str
Overwrite entire file. Protected by hash-based stale detection (file must be read first).

​
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