Skip to main content

​
PyRepl

PyRepl is a persistent IPython REPL running in a subprocess. It gives the model a continuous execution environment where variables persist across calls and runtime primitives are accessible without imports. In 0.8.1, PyRepl remains the public facade while its internals are split into focused components: worker lifecycle (pyrepl_worker_client.py), execute/reset orchestration (pyrepl_execution.py), primitive host integration (pyrepl_primitive_host.py), tool factory/output formatting (pyrepl_tools.py), audit logging (pyrepl_audit.py), and input bridging (pyrepl_input_bridge.py / pyrepl_input_mixin.py). This is an internal architecture cleanup; user-facing usage stays the same.

​
Core Properties

  • Persistent state — Variables defined in one execute_code call are available in the next
  • Isolated process — Runs in a separate subprocess (multiprocessing spawn). Crashes don’t kill the main process
  • Runtime injection — The runtime object is globally available. No imports needed
  • Streaming output — stdout/stderr stream in real-time via custom events
  • Image artifacts — images produced by display(Image(...)) or image-rich last expressions are returned to the model as multimodal tool results
  • Timeout protection — Default 600s per execution. Configurable

​
Setup

from SimpleLLMFunc.builtin import PyRepl

repl = PyRepl(working_directory="/path/to/workspace")

# Use as toolkit in an agent
@llm_chat(llm_interface=llm, toolkit=repl.toolset, stream=True)
async def agent(message: str, history: list | None = None):
    """A code-executing agent."""
    pass

​
Tools Provided

​
execute_code

Run arbitrary Python code in the persistent REPL: 
result = await execute_code(code="""
import math
x = math.sqrt(144)
print(f"Result: {x}")
x
""")
# Returns: {"stdout": "Result: 12.0\n", "return_value": "12.0", "execution_time_ms": ...}
Return value is the last expression’s repr (like IPython).

​
Image Output

When executed code produces image output, execute_code returns a multimodal tool result instead of flattening the image to text. The model receives the normal execution summary plus the image content. Supported patterns include explicit display calls: 
from IPython.display import Image, display

display(Image(filename="chart.png"))
And image-rich last expressions: 
from IPython.display import Image

Image(filename="chart.png")
For generated plots, saving the figure and returning an image payload is the clearest pattern: 
import matplotlib.pyplot as plt
from SimpleLLMFunc.type import ImgPath

plt.plot([1, 2, 3])
path = "chart.png"
plt.savefig(path)
ImgPath(path)
Direct PyRepl.execute(...) calls expose captured images in the returned artifacts list. The execute_code tool converts those artifacts into ImgPath / ImgUrl multimodal returns for the agent loop.

​
reset_repl

Clear all user variables but keep runtime backends: 
await reset_repl()
# After this: `x` is gone, but `runtime.selfref.context.inspect()` still works

​
Runtime Namespace

Inside execute_code, the runtime object provides: 
# Meta-primitives (always available)
runtime.list_primitives()
runtime.list_primitive_specs()
runtime.get_primitive_spec("selfref.context.compact")
runtime.list_backends()

# SelfRef primitives (when selfref is active)
runtime.selfref.context.inspect()
runtime.selfref.context.remember("important fact")
runtime.selfref.context.forget("exp_001")
runtime.selfref.context.compact(goal=..., instruction=..., ...)
runtime.selfref.fork.spawn(task=..., instruction=...)
runtime.selfref.fork.gather_all()

# Custom pack primitives (if installed)
runtime.metrics.increment_counter("files_read")

​
Streaming Output

PyRepl emits custom events for real-time output:
Event NameDataWhen
kernel_stdout{"text": "..."}Each stdout flush
kernel_stderr{"text": "..."}Each stderr flush
Consume in your event handler: 
from SimpleLLMFunc.hooks import is_event_yield, CustomEvent

async for output in agent("run some code", history):
    if is_event_yield(output):
        if isinstance(output.event, CustomEvent):
            if output.event.event_name == "kernel_stdout":
                print(output.event.data["text"], end="")

​
Output Truncation

If a tool result exceeds ~20,000 tokens:
  1. Full output is written to a temporary file
  2. Truncated version (first ~4,096 tokens) + file path is returned to the model
  3. The model can use read_file to access specific parts
Enable per-agent with _too_long_to_file=True.

​
Working Directory

repl = PyRepl(working_directory="/path/to/project")
The REPL starts in this directory. os.getcwd() inside execute_code returns this path.

​
Installing Custom Primitive Packs

from SimpleLLMFunc.runtime import PrimitivePack

my_pack = PrimitivePack(namespace="mytools", backend=..., primitives=[...])
repl.install_primitive_pack(my_pack)
After installation, runtime.mytools.* is available in execute_code.

​
SelfRef Integration

When using self_reference_key on the agent, the framework automatically:
  1. Creates a SelfReference backend
  2. Builds the selfref primitive pack
  3. Installs it in the PyRepl instance
  4. Makes runtime.selfref.* available
@llm_chat(
    llm_interface=llm,
    toolkit=repl.toolset,
    self_reference_key="agent_main",
)
async def agent(message: str, history: list | None = None):
    """Agent with code execution + self-reference."""
    pass

​
Practical Pattern: CodeAct Agent

The “CodeAct” pattern uses PyRepl as the primary action surface — the model writes Python to accomplish tasks instead of using separate tools for each operation: 
repl = PyRepl(working_directory=workspace)
file_tools = FileToolset(workspace).toolset

@llm_chat(
    llm_interface=llm,
    toolkit=[*repl.toolset, *file_tools],
    self_reference_key="agent_main",
    stream=True,
)
async def coding_agent(message: str, history: list | None = None):
    """
    Solve coding tasks by writing and executing Python.
    Use execute_code for inspection, computation, and verification.
    Use file tools for reading and editing project files.
    Use runtime.selfref.context.compact(...) when context grows large.
    """
    pass
→ API Reference: Builtins