跳转到主要内容

​
PyRepl

PyRepl 是一个运行在子进程中的持久化 IPython REPL。它为模型提供了一个连续的执行环境，变量在多次调用间保持不变，且运行时原语无需导入即可访问。

​
核心特性

  • 持久化状态 —— 在一次 execute_code 调用中定义的变量可在下次调用中继续使用
  • 进程隔离 —— 运行在独立子进程中（multiprocessing spawn）。崩溃不会影响主进程
  • 运行时注入 —— runtime 对象全局可用，无需导入
  • 流式输出 —— stdout/stderr 通过自定义事件实时流式传输
  • 图片产物 —— display(Image(...)) 或最后表达式产生的图片会作为多模态工具结果返回给模型
  • 超时保护 —— 每次执行默认 600 秒超时，可配置

​
设置

from SimpleLLMFunc.builtin import PyRepl

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

# 在 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

​
提供的工具

​
execute_code

在持久化 REPL 中运行任意 Python 代码： 
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": ...}
返回值是最后一个表达式的 repr（与 IPython 行为一致）。

​
图片输出

当执行代码产生图片输出时，execute_code 会返回多模态工具结果，而不是把图片压平成文本。模型会同时收到正常的执行摘要和图片内容。 支持显式 display 调用： 
from IPython.display import Image, display

display(Image(filename="chart.png"))
也支持最后表达式为可渲染图片对象： 
from IPython.display import Image

Image(filename="chart.png")
对于生成图表，最清晰的模式是保存图片并返回图片 payload： 
import matplotlib.pyplot as plt
from SimpleLLMFunc.type import ImgPath

plt.plot([1, 2, 3])
path = "chart.png"
plt.savefig(path)
ImgPath(path)
直接调用 PyRepl.execute(...) 时，捕获到的图片会出现在返回值的 artifacts 列表里。作为 agent 工具使用的 execute_code 会把这些 artifact 转成 ImgPath / ImgUrl 多模态返回。

​
reset_repl

清除所有用户变量，但保留运行时 backend： 
await reset_repl()
# 执行后：`x` 已被清除，但 `runtime.selfref.context.inspect()` 仍可使用

​
Runtime 命名空间

在 execute_code 内部，runtime 对象提供以下能力： 
# 元原语（始终可用）
runtime.list_primitives()
runtime.list_primitive_specs()
runtime.get_primitive_spec("selfref.context.compact")
runtime.list_backends()

# SelfRef 原语（当 selfref 处于激活状态时）
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()

# 自定义 Pack 原语（如已安装）
runtime.metrics.increment_counter("files_read")

​
流式输出

PyRepl 通过自定义事件发送实时输出：
事件名称数据触发时机
kernel_stdout{"text": "..."}每次 stdout 刷新时
kernel_stderr{"text": "..."}每次 stderr 刷新时
在事件处理器中消费： 
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="")

​
输出截断

当工具结果超过约 20,000 个 token 时：
  1. 完整输出会写入临时文件
  2. 截断版本（前约 4,096 个 token）+ 文件路径返回给模型
  3. 模型可以使用 read_file 访问指定部分
通过 _too_long_to_file=True 按 Agent 粒度启用。

​
工作目录

repl = PyRepl(working_directory="/path/to/project")
REPL 在该目录下启动。execute_code 内部的 os.getcwd() 会返回此路径。

​
安装自定义 Primitive Pack

from SimpleLLMFunc.runtime import PrimitivePack

my_pack = PrimitivePack(namespace="mytools", backend=..., primitives=[...])
repl.install_primitive_pack(my_pack)
安装后，runtime.mytools.* 即可在 execute_code 中使用。

​
SelfRef 集成

在 Agent 上使用 self_reference_key 时，框架会自动：
  1. 创建 SelfReference backend
  2. 构建 selfref primitive pack
  3. 将其安装到 PyRepl 实例中
  4. 使 runtime.selfref.* 可用
@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

​
实用模式：CodeAct Agent

“CodeAct”模式将 PyRepl 作为主要行动面——模型通过编写 Python 代码来完成任务，而不是为每个操作使用单独的工具： 
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 参考：内置组件