Trampoline-AI/predict-rlm

📚 predict‑rlm 的功能

predict‑rlm 是一个 Python 库，为大型语言模型 (LLM) 提供了一个执行环境——一个沙盒化的 REPL，让模型在执行任务时可以编写、执行并迭代 Python 代码。与其将所有内容塞入单一提示词中，您可以描述：

• 输入 (文件、字符串、图片等)
• 输出 (类型化的结果、生成的文件)
• 工具/技能 模型可能会调用的项目 (例如 PDF 阅读器、电子表格库、自定义 CLI 工具)
• 高阶程序 (作为合约的 DSPy 签名)

在执行时，外部 LLM 会接收合约，然后在沙盒内启动 Python REPL (JSPI/Deno、Pyodide 或选用的 Docker 沙盒)。它可以：

• 检查文件、维护可变状态，并进行分支/重试。
• 通过 predict() 调用具有精确类型 DSPy 签名的子模型——甚至是包含图片的多模态调用。
• 使用异步工具调用，管理大型上下文而不会产生“上下文衰退”，并产生类型化、可重现的输出。
• 发出完整的追踪信息 (代码、工具调用、时间、Token 使用量、错误)，可供人类检查或馈送至如 GEPA 等优化工具。

何时使用它

• 复杂的文件或代码库调查 (审计、合规性、事件分析)。
• 多文件数据提取、遮蔽或转换管线。
• 电子表格密集的财务模型工作流程。
• 任何在最终答案前需要推理、分支或验证的任务。

它不适用于简单的单次对话或单一 LLM 调用即可完成的确定性 ETL。

---

🛠️ 核心功能 (如 README 所述)

功能	意义
执行环境 REPL	模型在沙盒内编写并执行 Python，在迭代过程中保留状态。
类型化合约	DSPy 签名 (或简单的 question -> answer 字符串) 定义输入输出类型；子模型调用通过 Pydantic/DSPy 进行类型检查。
多模态支持	图片与渲染后的文档页面可使用原生供应商 API 发送给子模型。
异步工具调用	在 WASM 沙盒内进行并发子模型或外部工具调用。
技能与工具	RLM 可以导入并使用的领域特定指令、PyPI 套件与主机端工具集合。
可观察性	每次执行都会产生包含代码、输出、时间、Token 使用量与错误的 trace.json 与 evidence.json。
优化就绪	追踪信息可馈送至 GEPA，从评分范例中自动改进 RLM 策略。
沙盒后端	默认 JSPI/Deno/Pyodide 沙盒；选用的 Docker sbx 后端用于明确的 Linux Python 执行器。
电子表格技能	内置技能，加载 openpyxl、pandas 与公式评估辅助工具，用于电子表格相关任务。
生命周期回调	链接至迭代开始/结束 (同步或异步) 以广播进度、记录日志或与 UI 管线整合。

---

🚀 快速入门示例 (来自 README)

import dspy
from predict_rlm import CtxStr, File, PredictRLM

class AnalyzeImages(dspy.Signature):
    """Analyze images and answer the query. Load each image as a base64 data
    URI and use predict() with dspy.Image to extract visual information."""
    images: list[File] = dspy.InputField()
    query: CtxStr = dspy.InputField()
    answer: str = dspy.OutputField()

rlm = PredictRLM(
    AnalyzeImages,
    lm="openai/gpt-5.4",
    sub_lm="openai/gpt-5.1",
)

result = rlm(
    images=[File(path="page.png")],
    query="Extract all visible text, then count each letter A‑Z (case‑insensitive).",
)

print(result.answer)

外部模型 (gpt‑5.4) 驱动 REPL，而较窄的子模型 (gpt‑5.1) 用于图像分析调用。

---

📂 项目结构 (高阶，根据 README 推断)

• predict_rlm/ – 核心库 (执行环境、沙盒适配器、DSPy 集成、追踪处理)。
• examples/ – 端到端演示：文档分析、遮蔽、发票处理、合约比较。每个示例将每次执行的追踪存储在 .run/<timestamp>/ 下。
• skills/ – 可重复使用的技能套件 (例如 pdf, spreadsheet, rlm)。
• tests/ – 广泛的单元、集成与后端特定测试套件 (执行环境合约、GEPA、Codex LM、Docker 沙盒)。
• docs/ – 更深入的设计文档 (架构、可观察性、自定义路径输入)。
• CI / 打包 – GitHub Actions, Codecov, PyPI 发布, 选用扩展功能 (gepa, codex‑lm, sbx)。

---

🎯 谁会使用它？

• AI 工程师 构建复杂的 RAG 风格管线，其中单一 LLM 调用无法处理分支逻辑。
• 数据运营/合规团队 需要可审计、可重现的文档处理工作流程。
• 研究人员 探索 递归语言模型 范式 (项目引用的论文)。
• 产品团队 希望将“技能”(例如电子表格更新) 暴露给如 Claude Code, Cursor 或 Codex 等编码代理。

---

📦 安装与扩展功能

uv add predict-rlm                 # core package
uv add "predict-rlm[gepa]"        # GEPA optimisation support
uv add "predict-rlm[codex-lm]"   # Codex‑backed LM and CLI
uv add "predict-rlm[sbx]"        # Docker sandbox backend

该库适用于 Codex LM 后端 (gpt‑5.6‑terra 等)，但也可以通过 lm/sub_lm 参数指向任何 OpenAI 兼容模型。

---

🧩 可扩展性

• 新增技能 – 打包 PyPI 套件、自定义工具或提示词模板，并在构建 PredictRLM 时列在 skills= 中。
• 自定义沙盒 – 实现后端合约 (参阅 ARCHITECTURE.md) 并通过 sandbox_backend= 插入。
• 回调 – 继承 BaseCallback 并实现 on_rlm_iteration_start / on_rlm_iteration_end 以进行 UI 更新、记录日志或外部可观察性管线。

---

📊 可观察性与调试

• 人类可读的彩色追踪 打印至 stderr (使用 verbose=False 禁用)。
• 可导出 JSON：prediction.trace.to_exportable_json("trace.json") 与 prediction.evidence.to_exportable_json("evidence.json")。
• 实时事件接收器 – 回调实时接收相同的结构化数据。

---

✅ 总结

predict‑rlm 是一个真正且积极维护的开源框架，将 LLM 转变为可编程、具状态的执行环境。它针对新兴的“递归语言模型”工作流程，模型在此流程中迭代编写并执行代码、调用更窄的子模型，并产生完全可追踪、类型化的结果。README 提供了演示、扎实的测试套件、选用的 Docker 沙盒以及优化工具的集成点，使其成为任何需要复杂、可审计 LLM 驱动管线的人员的坚实选择。