@hicaru/pi-rlm 0.3.15 → 0.3.17

package/README.md

@@ -1,6 +1,6 @@
-<p align="center">
-  <img src="https://github.com/openzebra/rlm.pi/blob/master/assets/plugin-cover.png?raw=true" width="100%" alt="pi-rlm — Recursive Language Model plugin for Pi">
-</p>
+# rlm.pi PI plugin
+
+> pi-rlm — Large contexts on cheap models: Recursive Language Model (RLM) for Pi
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@hicaru/pi-rlm"><img src="https://img.shields.io/npm/v/@hicaru/pi-rlm?color=cb3837&logo=npm" alt="npm version"></a>
@@ -14,45 +14,74 @@
   <a href="https://www.npmjs.com/package/@hicaru/pi-rlm">📦 npm</a>
 </p>
 
----
+## Install
+
+```bash
+pi install npm:@hicaru/pi-rlm
+```
+
+Run `/reload` in Pi — `/rlm`, `/rlm-config`, `/rlm-stop` appear under **[Extensions]**.
+Toggle with `Ctrl+Shift+R` or `/rlm`.
 
-**The ONLY Recursive Language Model plugin for Pi.** No new agent to learn, no
-separate CLI, no YAML workflows — just `/rlm` and your existing Pi session becomes a
-recursive orchestration engine — your best model orchestrates, cheap worker models
-do the reading.
+To remove it later:
 
-> **One install. One toggle. Infinite context.**
+```bash
+pi uninstall npm:@hicaru/pi-rlm
+```
+
+<p align="center">
+  <img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" width="100%" alt="rlm.pi — OOLONG benchmark results">
+</p>
 
-## Why pi-rlm?
+## What is pi-rlm?
 
-| Advantage | What it means |
-|-----------|---------------|
-| 🔌 **Plugin, not a new agent** | Stays inside Pi. You keep your keybindings, your theme, your tools, your muscle memory. |
-| 📄 **Reads ANY document** | `.pdf` `.docx` `.pptx` `.xlsx` `.epub` `.rtf` `.odt` `.csv` `.html` `.xml` — drop them in, they become Markdown in `context`. |
-| 🪶 **Unix-style — tiny & composable** | Does ONE thing (RLM orchestration). Pair it with any other Pi plugin. No lock-in. |
-| 🧠 **Smartest model orchestrates, cheapest model researches** | Root uses your best model; workers auto-pick the cheapest. Recursive children inherit the full `context` for free. |
-| ⏳ **Long-running with goals** | Toggle `/rlm` on, set a goal, let it loop. Runs survive across chat turns — go make coffee. |
-| 🔒 **100% local, 100% private** | No servers. Your API keys never leave your machine. One `python3` subprocess — that's it. |
+A Pi plugin that turns your session into a **Recursive Language Model (RLM)**: instead of
+stuffing a huge document into the prompt, the context lives in a Python REPL and your best
+model orchestrates it — searching, decomposing, and delegating leaf reads to cheap worker
+models, recursively. Same Pi session, same tools, same keys: `/rlm` and go. Reads
+`.pdf` `.docx` `.xlsx` `.epub` and more, works with any OpenRouter model, 100% local.
 
-## See it in action
+## Benchmarks
 
-<div align="center">
+**OOLONG (oolong-synth)** — paper-tier long-context suite; latest journal per model,
+cost per task from real `costUsd` (older journals estimated at OpenRouter list prices):
 
-<video src="https://github.com/openzebra/rlm.pi/raw/refs/heads/master/animation/rlm_pi_explainer.mp4" controls width="854" poster="https://raw.githubusercontent.com/openzebra/rlm.pi/master/assets/hero.png"></video>
+| Model | Score | Avg. cost/task |
+|-------|-------|----------------|
+| `qwen/qwen3.8-27b` | **100%** | $0.0127 |
+| `google/gemma-3-27b-it` | 83.3% | $0.0013 |
+| `qwen/qwen3-30b-a3b-instruct-2507` | 66.7% | $0.0009 |
+| `mistralai/mistral-small-3.2-24b-instruct` | 66.7% | $0.0025 |
 
-</div>
+Lite suite — `needle` multi-needle recall, `codeqa` repo-QA, `coding` fix task
+(7 tasks × 2 passes per model, deterministic graders, no LLM-as-judge):
 
-## Install (30 seconds)
+| Model | Score | Accuracy |
+|-------|-------|----------|
+| `qwen/qwen3-30b-a3b-instruct-2507` | **14/14** | **100%** |
+| `google/gemma-3-27b-it` | 12/14 | 86% |
+| `mistralai/mistral-small-3.2-24b-instruct` | 12/14 | 86% |
+
+Raw per-task rows (correct, recall, latency, tokens, cost) live in
+`bench/runs/*.jsonl` — one JSONL row per task, committed as history.
+
+### Run the benchmarks
 
 ```bash
-pi install npm:@hicaru/pi-rlm
-```
+export OPENROUTER_API_KEY=sk-or-...        # required — env vars are the only key transport
 
-Run `/reload` in Pi. Done. `/rlm`, `/rlm-config`, `/rlm-stop` appear under **[Extensions]**.
+bun run bench                              # lite suite: needle + codeqa + coding
+bun run bench --suite needle --limit 1     # one suite, first task only
+bun run bench --model openrouter/qwen/qwen3-30b-a3b-instruct-2507
+bun run bench --list                       # print tasks, no engine / no key
+bun run bench --suite paper                # paper tier: s_niah, oolong, browsecomp, codeqa_lb (downloads datasets)
+```
 
-Toggle with `Ctrl+Shift+R` or `/rlm` — plain prompts now route through the RLM engine.
+Suites: `all` (lite, default) · `needle` · `codeqa` · `coding` · `paper` · `s_niah` ·
+`oolong` · `browsecomp` · `codeqa_lb`. Regenerate the hero chart:
+`python3 bench/hero.py` (needs `matplotlib`).
 
-## What you get
+## How it works
 
 ```
           ┌─────────────────────────┐
@@ -106,10 +135,6 @@ A **Recursive Language Model (RLM)** replaces `llm.completion(prompt)` with
 launch sub-LLM and sub-RLM calls as ordinary Python functions — decomposing,
 delegating, and synthesizing across a tree of models, not a single context window.
 
-**This is the only plugin that brings true RLM recursion to Pi.** Prime Agent and
-the reference Python library are separate agents you must switch to. pi-rlm lives
-inside Pi — same session, same tools, same everything.
-
 ## Commands
 
 | Command | Shortcut | What it does |
@@ -129,6 +154,45 @@ inside Pi — same session, same tools, same everything.
 | REPL timeout | `120`s | Bump for slow computations |
 | Max concurrent subs | `16` | More parallelism (costs RAM) |
 
+## Sampling & reproducibility
+
+The r3 bench showed the biggest capability lever is not the model — it is the sampling:
+temperature 0 took OOLONG from 71% pooled / 40% flips to 91.7–100% all-stable for $1.74
+total. Those knobs are first-class in `rlm.json` (`~/.pi/agent/rlm.json`) and on the
+`/rlm-config` panel:
+
+| Field | Where | Default | What it governs |
+|-------|-------|---------|-----------------|
+| `rootSampling.maxTokens` | rlm.json, panel | `16384` | Output cap per root-model turn (finalize included) |
+| `rootSampling.temperature` | rlm.json, panel | provider default | Root + finalize sampling temperature; `0` = deterministic |
+| `smartReasoning` | rlm.json, panel | none | Thinking effort for the root model |
+| `subSampling.maxTokens` | rlm.json, panel | `8192` | Output cap per leaf sub-call (`llm_query`, `llm_batch`, `map_files`) |
+| `subSampling.temperature` | rlm.json, panel | provider default | Leaf sampling temperature |
+| `enableVerificationNudge` | rlm.json | off | One coached redo when the root finalizes early with a bare number / short label |
+
+**Reproducibility recipe (validated by r3):**
+
+```json
+{
+  "config": {
+    "rootSampling": { "maxTokens": 8192, "temperature": 0, "reasoning": "high" }
+  }
+}
+```
+
+Reasoning tokens share the completion budget with the answer — with thinking on, keep
+`maxTokens` generous (the bench doubles it to 8192; the engine warns once on turn 0 when it
+is tight).
+
+**Scope boundary:** `rlm.json` sampling applies to RLM-mode runs, `rlm()` delegation, and
+child recursion at any depth (same engine function). The native Pi agent loop follows Pi's
+own session settings — rlm.json never touches it.
+
+**Model capability:** reasoning requires a model whose registry entry has `reasoning: true`.
+Anything else has the level dropped before it reaches the provider (pi-ai clamps unsupported
+levels to off); capability comes from the registry, so OpenRouter hybrids like
+`qwen/qwen3.8-27b` just work.
+
 ## Prompt Architecture
 
 The system prompt follows a **contract / routing / examples / rules** pattern
@@ -142,38 +206,6 @@ The system prompt follows a **contract / routing / examples / rules** pattern
 **Key insight:** children see `Recursion depth: N` and calibrate ambition —
 delegating only when their task genuinely decomposes further.
 
-## Benchmarks
-
-E2E runs of the real engine against OpenRouter chat models — the lite suite
-(`needle` multi-needle recall, `codeqa` repo-QA, `coding` fix task; 7 tasks × 2 passes
-per model). Deterministic graders (recall / gold containment / regex), no LLM-as-judge.
-
-Latest results — small models (≤32B parameters, paid tier):
-
-| Model | Params | Score | Accuracy | Latency/task |
-|-------|--------|-------|----------|--------------|
-| `qwen/qwen3-30b-a3b-instruct-2507` | MoE 30B / 3B active | **14/14** | **100%** | ~15s |
-| `google/gemma-3-27b-it` | dense 27B | 12/14 | 86% | ~26s |
-| `mistralai/mistral-small-3.2-24b-instruct` | dense 24B | 12/14 | 86% | ~28s |
-
-Raw per-task rows (correct, recall, latency, tokens, cost) live in
-`bench/runs/bench-<ts>.jsonl` — one JSONL row per task, committed as history.
-
-### Run the benchmarks
-
-```bash
-export OPENROUTER_API_KEY=sk-or-...        # required — env vars are the only key transport
-
-bun run bench                              # lite suite: needle + codeqa + coding
-bun run bench --suite needle --limit 1     # one suite, first task only
-bun run bench --model openrouter/qwen/qwen3-30b-a3b-instruct-2507
-bun run bench --list                       # print tasks, no engine / no key
-bun run bench --suite paper                # paper tier: s_niah, oolong, browsecomp, codeqa_lb (downloads datasets)
-```
-
-Suites: `all` (lite, default) · `needle` · `codeqa` · `coding` · `paper` · `s_niah` ·
-`oolong` · `browsecomp` · `codeqa_lb`.
-
 ## Security
 
 - **Key isolation** — provider keys live in TypeScript only; sandbox receives prompts, returns text.
@@ -182,12 +214,6 @@ Suites: `all` (lite, default) · `needle` · `codeqa` · `coding` · `paper` ·
 - **Per-block timeout** — SIGALRM + parent watchdog (SIGKILL on hang).
 - **Trust** — project-local install requires Pi project trust.
 
-## Uninstall
-
-```bash
-pi uninstall npm:@hicaru/pi-rlm
-```
-
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/README.ru.md

@@ -1,11 +1,5 @@
 <div align="center">
 
-<img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" alt="pi-rlm">
-
-</div>
-
-<div align="center">
-
 <sub>
 <a href="README.md">English</a> &nbsp;·&nbsp; <a href="README.zh-CN.md">中文</a> &nbsp;·&nbsp; **Русский**
 </sub>
@@ -14,33 +8,68 @@
 
 ---
 
-# pi-rlm — рекурсивные языковые модели для кодинг-агента [Pi](https://github.com/earendil-works)
+# rlm.pi PI plugin
 
-<div align="center">
+> pi-rlm — большие контексты на дешёвых моделях: рекурсивная языковая модель (RLM) для Pi
 
-**Рекурсивные языковые модели (RLMs)**, реализованные нативно как расширение Pi —
-ПОЛНОСТЬЮ ЛОКАЛЬНО.
+## Установка
 
-</div>
+```bash
+pi install npm:@hicaru/pi-rlm
+```
 
----
+Чтобы удалить позже:
+
+```bash
+pi uninstall npm:@hicaru/pi-rlm
+```
+
+Затем выполните `/reload` или перезапустите Pi — `/rlm`, `/rlm-config` и `/rlm-stop` появятся в разделе **[Extensions]**. Переключение — `Ctrl+Shift+R` или `/rlm`.
 
-**Рекурсивная языковая модель (RLM)** — это универсальная (task-agnostic) парадигма инференса, в которой корневая языковая модель управляет почти бесконечным контекстом, *программно* исследуя, декомпозируя и **рекурсивно вызывая саму себя** для обработки входных данных. RLM заменяют канонический вызов `llm.completion(prompt, model)` на вызов `rlm.completion(prompt, model)`: промпт/контекст передается как переменная в среде REPL, с которой взаимодействует модель, а модель может запускать вызовы sub-LLM и sub-RLM как обычные функции в коде.
+<p align="center">
+  <img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" width="100%" alt="rlm.pi — результаты OOLONG">
+</p>
 
-Это ставка на архитектуру в стиле [CodeAct](https://arxiv.org/abs/2402.01030): каждая языковая модель получает доступ к среде выполнения кода, вызовы sub-(R)LM являются функциями, а контекст/промпты — объектами в коде, что является уходом от стандарта вызова инструментов через JSON. Система, построенная таким образом, *сама по себе* является языковой моделью, которая полагается на рекурсивные вызовы sub-LLM, отсюда и название.
+## Что такое pi-rlm?
 
-`pi-rlm` переносит эту парадигму **нативно в Pi**:
+Плагин, который превращает сессию Pi в **рекурсивную языковую модель (RLM)**: вместо того чтобы заталкивать огромный документ в промпт, контекст живёт в Python REPL, а ваша лучшая модель им управляет — ищет, декомпозирует и делегирует чтения дешёвым worker-моделям, рекурсивно. Та же сессия Pi, те же инструменты, те же ключи — включите `/rlm` и вперёд. По методу [RLM paper](https://arxiv.org/abs/2512.24601); подробности — в разделе **Как это работает**.
 
-- **Модель-оркестратор** управляет постоянным Python REPL пошагово.
-- Работа с длинным контекстом **делегируется** дешевым worker-моделям через `llm_query` / `llm_query_batched`.
-- Сложные подзадачи **рекурсивно** передаются в дочерние RLM через `rlm_query` (с ограничением глубины).
-  Дочерний RLM наследует `context` родителя — репозиторий и все библиотеки, загруженные через
-  `add_context()`, — и работает с теми же путями. Наследование не стоит дополнительных токенов:
-  содержимое живёт в песочнице, модель видит только строку с размером.
-- Все работает **in-process** — единственным внешним процессом является локальный worker `python3`.
+## Бенчмарки
+
+**OOLONG (oolong-synth)** — paper-tier сюит длинного контекста; последний журнал каждой модели, цена за задачу из реального `costUsd` (старые журналы оценены по прайс-листу OpenRouter):
+
+| Модель | Счёт | Цена/задача |
+|--------|------|-------------|
+| `qwen/qwen3.8-27b` | **100%** | $0.0127 |
+| `google/gemma-3-27b-it` | 83.3% | $0.0013 |
+| `qwen/qwen3-30b-a3b-instruct-2507` | 66.7% | $0.0009 |
+| `mistralai/mistral-small-3.2-24b-instruct` | 66.7% | $0.0025 |
+
+Lite-сьют — `needle` (поиск игл в куче), `codeqa` (вопросы по коду), `coding` (задача-фикс; 7 задач × 2 прохода на модель, детерминированные грейдеры, без LLM-судьи):
 
-> This is a Pi-plugin reimplementation of the RLM method (see the [RLM paper](https://arxiv.org/abs/2512.24601)).
-> It is **not** the Python library.
+| Модель | Счёт | Точность |
+|--------|------|----------|
+| `qwen/qwen3-30b-a3b-instruct-2507` | **14/14** | **100%** |
+| `google/gemma-3-27b-it` | 12/14 | 86% |
+| `mistralai/mistral-small-3.2-24b-instruct` | 12/14 | 86% |
+
+Построчные результаты (correct, recall, latency, токены, цена) — в
+`bench/runs/*.jsonl`, одна JSONL-строка на задачу.
+
+### Как запустить
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...        # обязателен — ключи ходят только через env
+
+bun run bench                              # lite-сьют: needle + codeqa + coding
+bun run bench --suite needle --limit 1     # один сьют, первая задача
+bun run bench --model openrouter/qwen/qwen3-30b-a3b-instruct-2507
+bun run bench --list                       # показать задачи, без движка и ключа
+bun run bench --suite paper                # paper-сьют: s_niah, oolong, browsecomp, codeqa_lb (скачивает датасеты)
+```
+
+Сьюты: `all` (lite, по умолчанию) · `needle` · `codeqa` · `coding` · `paper` · `s_niah` ·
+`oolong` · `browsecomp` · `codeqa_lb`.
 
 ## Как это работает
 
@@ -60,24 +89,17 @@ pi process (TypeScript)
   `rlm_query_batched`, `SHOW_VARS()`, `ask_user_question()` и словарь `answer`.
   Модель отправляет окончательный результат, устанавливая `answer["ready"] = True`.
 
-## Установка
+## Установка из исходников (для разработки)
 
 `pi-rlm` — это пакет Pi. Pi предоставляет peer-зависимости `@earendil-works/pi-*` и `typebox`; **не** устанавливайте их отдельную копию в этот пакет. Требуется `python3` в `PATH` (только стандартная библиотека).
 
-Рекомендуемая локальная установка при разработке:
+Локальная установка при разработке:
 
 ```bash
 pi install /path/to/this-repo/pi-plugin/rlm
 ```
 
-Установка опубликованного npm-пакета:
-
-```bash
-npm publish                       # например, как @<you>/pi-rlm
-pi install npm:@<you>/pi-rlm
-```
-
-> **Установка через Git** требует, чтобы манифест пакета находился в корне устанавливаемого репозитория. Для поддиректорий монорепозитория, таких как эта, предпочтительнее использовать локальный путь или npm, как указано выше.
+> **Установка через Git** требует, чтобы манифест пакета находился в корне устанавливаемого репозитория. Для поддиректорий монорепозитория, таких как эта, предпочтительнее использовать локальный путь, как указано выше.
 
 Если вы ранее копировали папку расширения напрямую, удалите ее, чтобы она не перекрывала пакет:
 
@@ -132,40 +154,45 @@ rm -rf ~/.pi/agent/extensions/rlm
 
 > **Примечание по параллелизму:** каждый дочерний `rlm_query` запускает собственного worker `python3` (~50–150 мс «холодного старта»). В худшем случае количество параллельных интерпретаторов ≈ `maxConcurrentSubcalls`^(depth−1); при настройках по умолчанию (глубина 4, параллелизм 4) это 4³ = 64 в патологическом случае. Лимиты бюджета и ошибок (см. выше) ограничивают общие затраты независимо от степени разветвления.
 
-## Логи запусков
+## Сэмплинг и воспроизводимость
 
+Бенчмарк r3 показал: самый большой рычаг качества — не модель, а сэмплинг. Temperature 0
+перевела OOLONG с 71% (pooled) / 40% (flips) на 91.7–100% all-stable за $1.74 суммарно.
+Эти ручки — полноправные поля `rlm.json` (`~/.pi/agent/rlm.json`) и панели `/rlm-config`:
 
-## Бенчмарки
-
-E2E-прогоны реального движка против моделей OpenRouter — lite-сьют (`needle` поиск игл в
-куче, `codeqa` вопросы по коду, `coding` задача-фикс; 7 задач × 2 прохода на модель).
-Детерминированные грейдеры (recall / вхождение эталона / regex), без LLM-судьи.
+| Поле | Где | По умолчанию | За что отвечает |
+|---|---|---|---|
+| `rootSampling.maxTokens` | rlm.json, панель | `16384` | Лимит вывода на ход корневой модели (включая finalize) |
+| `rootSampling.temperature` | rlm.json, панель | провайдер | Температура корневых ходов и finalize; `0` = детерминированно |
+| `smartReasoning` | rlm.json, панель | нет | Усилие «размышления» корневой модели |
+| `subSampling.maxTokens` | rlm.json, панель | `8192` | Лимит вывода одного листового вызова (`llm_query`, `llm_batch`, `map_files`) |
+| `subSampling.temperature` | rlm.json, панель | провайдер | Температура листовых вызовов |
+| `enableVerificationNudge` | rlm.json | выкл | Один повтор с подсказкой, если корень рано финализирует «голым числом» |
 
-Актуальные результаты — маленькие модели (≤32B параметров, платный тариф):
+**Рецепт воспроизводимости (проверен r3):**
 
-| Модель | Параметры | Счёт | Точность | Latency/задача |
-|--------|-----------|------|----------|----------------|
-| `qwen/qwen3-30b-a3b-instruct-2507` | MoE 30B / 3B активных | **14/14** | **100%** | ~15s |
-| `google/gemma-3-27b-it` | dense 27B | 12/14 | 86% | ~26s |
-| `mistralai/mistral-small-3.2-24b-instruct` | dense 24B | 12/14 | 86% | ~28s |
+```json
+{
+  "config": {
+    "rootSampling": { "maxTokens": 8192, "temperature": 0, "reasoning": "high" }
+  }
+}
+```
 
-Построчные результаты (correct, recall, latency, токены, цена) — в
-`bench/runs/bench-<ts>.jsonl`, одна JSONL-строка на задачу.
+Токены размышлений делят бюджет завершения с ответом — при включённом thinking держите
+`maxTokens` щедрым (бенчмарк удваивает его до 8192; движок один раз предупредит на ходе 0,
+если лимит тесный).
 
-### Как запустить
+**Граница действия:** сэмплинг из `rlm.json` управляет запусками RLM-режима, делегированием
+`rlm()` и рекурсией на любой глубине (тот же движок). Собственный цикл агента Pi следует
+настройкам сессии Pi — rlm.json его не касается.
 
-```bash
-export OPENROUTER_API_KEY=sk-or-...        # обязателен — ключи ходят только через env
+**Возможности модели:** reasoning требует модель с `reasoning: true` в записи реестра.
+Для остальных уровень отбрасывается до отправки провайдеру (pi-ai приводит его к off);
+возможность берётся из реестра, а не из конфига.
 
-bun run bench                              # lite-сьют: needle + codeqa + coding
-bun run bench --suite needle --limit 1     # один сьют, первая задача
-bun run bench --model openrouter/qwen/qwen3-30b-a3b-instruct-2507
-bun run bench --list                       # показать задачи, без движка и ключа
-bun run bench --suite paper                # paper-сьют: s_niah, oolong, browsecomp, codeqa_lb (скачивает датасеты)
-```
+## Логи запусков
 
-Сьюты: `all` (lite, по умолчанию) · `needle` · `codeqa` · `coding` · `paper` · `s_niah` ·
-`oolong` · `browsecomp` · `codeqa_lb`.
 
 ## Безопасность
 

package/README.zh-CN.md

@@ -1,11 +1,5 @@
 <div align="center">
 
-<img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" alt="pi-rlm">
-
-</div>
-
-<div align="center">
-
 <sub>
 <a href="README.md">English</a> &nbsp;·&nbsp; **中文** &nbsp;·&nbsp; <a href="README.ru.md">Русский</a>
 </sub>
@@ -14,32 +8,73 @@
 
 ---
 
-# pi-rlm — 为 [Pi](https://github.com/earendil-works) 编程代理提供的递归语言模型 (Recursive Language Models)
+# rlm.pi PI plugin
 
-<div align="center">
+> pi-rlm — 大上下文，廉价模型：为 Pi 提供的递归语言模型 (RLM)
 
-**递归语言模型 (RLMs)** 作为 Pi 扩展原生实现 ——
-完全本地。
+## 安装
 
-</div>
+```bash
+pi install npm:@hicaru/pi-rlm
+```
 
----
+以后要移除：
+
+```bash
+pi uninstall npm:@hicaru/pi-rlm
+```
+
+然后在 Pi 中运行 `/reload` —— `/rlm`、`/rlm-config` 和 `/rlm-stop` 会出现在 **[Extensions]** 下。使用 `Ctrl+Shift+R` 或 `/rlm` 切换。
 
-**递归语言模型 (RLM)** 是一种与任务无关的推理范式，其中根语言模型通过对输入进行*编程式*的检查、分解并**递归调用自身**，从而在近乎无限的上下文中进行编排。RLM 将典型的 `llm.completion(prompt, model)` 调用替换为 `rlm.completion(prompt, model)` 调用：提示词/上下文作为 REPL 环境中的一个变量进行卸载，模型与其进行交互，并且模型可以将子 LLM 和子 RLM 调用作为代码中的普通函数启动。
+<p align="center">
+  <img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" width="100%" alt="rlm.pi — OOLONG 基准测试结果">
+</p>
+
+## 什么是 pi-rlm？
+
+一个把 Pi 会话变成**递归语言模型 (RLM)** 的插件：不必把庞大的文档塞进提示词，上下文
+驻留在 Python REPL 中，由你最好的模型编排 —— 检索、分解，并把叶子读取递归地委派给
+廉价的工作模型。同一个 Pi 会话、同样的工具、同样的密钥 —— 打开 `/rlm` 即可。
+方法基于 [RLM 论文](https://arxiv.org/abs/2512.24601)；详见下方的**工作原理**。
+
+## 基准测试
 
-这是对 [CodeAct](https://arxiv.org/abs/2402.01030) 风格框架的一种尝试 —— 每个语言模型都能访问代码环境，子 (R)LM 调用是函数，而上下文/提示词是代码中的对象 —— 从而脱离了 JSON 工具调用 (tool-calling) 标准。以此方式构建的系统*本身*就是一个依赖于递归子 LLM 调用的语言模型，因此得名。
+**OOLONG (oolong-synth)** —— paper 级长上下文套件；取每个模型最新的日志，每任务成本
+来自真实 `costUsd`（旧日志按 OpenRouter 牌价估算）：
 
-`pi-rlm` 将该范式**原生引入 Pi**：
+| 模型 | 得分 | 每任务成本 |
+|------|------|------------|
+| `qwen/qwen3.8-27b` | **100%** | $0.0127 |
+| `google/gemma-3-27b-it` | 83.3% | $0.0013 |
+| `qwen/qwen3-30b-a3b-instruct-2507` | 66.7% | $0.0009 |
+| `mistralai/mistral-small-3.2-24b-instruct` | 66.7% | $0.0025 |
 
-- **根编排器**模型逐轮驱动一个**持久化的 Python REPL**。
-- 长上下文工作通过 `llm_query` / `llm_query_batched` **委派**给廉价的工作模型。
-- 困难的子问题通过 `rlm_query` **递归**到子 RLM 中（设有深度限制）。子 RLM 继承父级的 `context`
-  ——已加载的文件以及通过 `add_context()` 追加的来源——因此可以在相同的路径上使用相同的检索原语。
-  继承不消耗额外的 token：内容存放在沙箱中，模型只看到一行大小信息。
-- 所有内容均**在进程内**运行 —— 唯一的外部进程是一个本地的 `python3` worker。
+精简套件 —— `needle`（多针召回）、`codeqa`（代码库问答）、`coding`（修复任务；
+每模型 7 个任务 × 2 轮，确定性评分，无 LLM 评审）：
 
-> 这是 RLM 方法的 Pi 插件重新实现（参见 [RLM 论文](https://arxiv.org/abs/2512.24601)）。
-> 它**不是**那个 Python 库。
+| 模型 | 得分 | 准确率 |
+|------|------|--------|
+| `qwen/qwen3-30b-a3b-instruct-2507` | **14/14** | **100%** |
+| `google/gemma-3-27b-it` | 12/14 | 86% |
+| `mistralai/mistral-small-3.2-24b-instruct` | 12/14 | 86% |
+
+逐任务原始数据（正确性、召回率、延迟、token、成本）位于 `bench/runs/*.jsonl`
+—— 每个任务一行 JSONL，作为历史记录提交。
+
+### 运行基准测试
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...        # 必需 —— 密钥仅通过环境变量传递
+
+bun run bench                              # 精简套件：needle + codeqa + coding
+bun run bench --suite needle --limit 1     # 单个套件，仅第一个任务
+bun run bench --model openrouter/qwen/qwen3-30b-a3b-instruct-2507
+bun run bench --list                       # 仅列出任务，无需引擎和密钥
+bun run bench --suite paper                # paper 套件：s_niah, oolong, browsecomp, codeqa_lb（需下载数据集）
+```
+
+套件：`all`（精简版，默认） · `needle` · `codeqa` · `coding` · `paper` · `s_niah` ·
+`oolong` · `browsecomp` · `codeqa_lb`。
 
 ## 工作原理
 
@@ -61,26 +96,19 @@ pi 进程 (TypeScript)
   `rlm_query_batched`, `SHOW_VARS()`, `ask_user_question()` 以及一个 `answer` 字典。
   模型通过设置 `answer["ready"] = True` 来提交最终结果。
 
-## 安装
+## 从源码安装（开发）
 
 `pi-rlm` 是一个 Pi 包。Pi 提供了 `@earendil-works/pi-*` 和 `typebox` peer
 依赖；请**不要**在该包中安装它们的独立副本。要求 `PATH` 中有 `python3` (仅限标准库)。
 
-开发时的推荐本地安装方式：
+开发时的本地安装方式：
 
 ```bash
 pi install /path/to/this-repo/pi-plugin/rlm
 ```
 
-已发布的 npm 包安装方式：
-
-```bash
-npm publish                       # 例如 as @<you>/pi-rlm
-pi install npm:@<you>/pi-rlm
-```
-
 > **Git 安装**要求包清单位于安装的仓库根目录下。
-> 对于像这样一个 monorepo 子目录，请优先使用上述的本地路径或 npm 流程。
+> 对于像这样一个 monorepo 子目录，请优先使用上述的本地路径流程。
 
 如果您之前直接复制了扩展文件夹，请将其删除，以免遮蔽 (shadow) 该包：
 
@@ -141,6 +169,40 @@ rm -rf ~/.pi/agent/extensions/rlm
 > 默认设置下 (深度 4, 并发 4)，极端情况下为 4³ = 64。预算和错误
 > 上限 (见上文) 无论扇出 (fan-out) 如何都会限制总支出。
 
+## 采样与可复现性
+
+r3 基准测试表明：最大的能力杠杆不是模型，而是采样。仅 temperature 0 就让 OOLONG 从
+71% (pooled) / 40% (flips) 提升到 91.7–100% all-stable，总计仅花费 $1.74。这些旋钮在
+`rlm.json` (`~/.pi/agent/rlm.json`) 和 `/rlm-config` 面板中都是一等公民：
+
+| 字段 | 位置 | 默认值 | 作用范围 |
+|---|---|---|---|
+| `rootSampling.maxTokens` | rlm.json, 面板 | `16384` | 根模型每轮的输出上限 (包括 finalize) |
+| `rootSampling.temperature` | rlm.json, 面板 | 提供商默认 | 根轮次与 finalize 的采样温度；`0` = 确定性 |
+| `smartReasoning` | rlm.json, 面板 | 无 | 根模型的思考强度 |
+| `subSampling.maxTokens` | rlm.json, 面板 | `8192` | 每个叶子子调用 (`llm_query`, `llm_batch`, `map_files`) 的输出上限 |
+| `subSampling.temperature` | rlm.json, 面板 | 提供商默认 | 叶子调用的采样温度 |
+| `enableVerificationNudge` | rlm.json | 关 | 当根节点过早以“裸数字”定稿时，给予一次带提示的重做 |
+
+**可复现性配方 (经 r3 验证)：**
+
+```json
+{
+  "config": {
+    "rootSampling": { "maxTokens": 8192, "temperature": 0, "reasoning": "high" }
+  }
+}
+```
+
+思考 token 与答案共享补全预算——开启 thinking 时请保持充裕的 `maxTokens`
+(基准测试将其翻倍至 8192；若过紧，引擎会在第 0 轮警告一次)。
+
+**作用边界：** `rlm.json` 的采样适用于 RLM 模式运行、`rlm()` 委托以及任意深度的子递归
+(同一个引擎函数)。Pi 原生代理循环遵循 Pi 自身的会话设置——rlm.json 不会触及它。
+
+**模型能力：** reasoning 要求模型的注册表条目为 `reasoning: true`。其他情况会在发送给
+提供商之前丢弃该级别 (pi-ai 会将不支持的级别钳制为 off)；能力来自注册表，而非配置。
+
 ## 运行日志
 
 - **密钥隔离**：供应商密钥仅存在于 TypeScript (`AuthStorage`) 中；沙箱
@@ -157,38 +219,6 @@ rm -rf ~/.pi/agent/extensions/rlm
   连续错误上限。
 - **信任**：本地安装需要 Pi 项目信任。
 
-## 基准测试
-
-针对 OpenRouter 聊天模型对真实引擎进行端到端测试 —— 精简套件（`needle` 多针召回、
-`codeqa` 代码库问答、`coding` 修复任务；每个模型 7 个任务 × 2 轮）。确定性评分
-（召回率 / 标准答案包含 / 正则），无 LLM 评审。
-
-最新结果 —— 小型模型（≤32B 参数，付费额度）：
-
-| 模型 | 参数 | 得分 | 准确率 | 每任务延迟 |
-|------|------|------|--------|------------|
-| `qwen/qwen3-30b-a3b-instruct-2507` | MoE 30B / 3B 激活 | **14/14** | **100%** | ~15s |
-| `google/gemma-3-27b-it` | dense 27B | 12/14 | 86% | ~26s |
-| `mistralai/mistral-small-3.2-24b-instruct` | dense 24B | 12/14 | 86% | ~28s |
-
-逐任务原始数据（正确性、召回率、延迟、token、成本）位于 `bench/runs/bench-<ts>.jsonl`
-—— 每个任务一行 JSONL，作为历史记录提交。
-
-### 运行基准测试
-
-```bash
-export OPENROUTER_API_KEY=sk-or-...        # 必需 —— 密钥仅通过环境变量传递
-
-bun run bench                              # 精简套件：needle + codeqa + coding
-bun run bench --suite needle --limit 1     # 单个套件，仅第一个任务
-bun run bench --model openrouter/qwen/qwen3-30b-a3b-instruct-2507
-bun run bench --list                       # 仅列出任务，无需引擎和密钥
-bun run bench --suite paper                # paper 套件：s_niah, oolong, browsecomp, codeqa_lb（需下载数据集）
-```
-
-套件：`all`（精简版，默认） · `needle` · `codeqa` · `coding` · `paper` · `s_niah` ·
-`oolong` · `browsecomp` · `codeqa_lb`。
-
 ## 项目布局
 
 ```