rlm-cli 0.2.0

package/README.md

@@ -0,0 +1,184 @@
+# rlm-cli
+
+```
+                     ██████╗ ██╗     ███╗   ███╗
+                     ██╔══██╗██║     ████╗ ████║
+                     ██████╔╝██║     ██╔████╔██║
+                     ██╔══██╗██║     ██║╚██╔╝██║
+                     ██║  ██║███████╗██║ ╚═╝ ██║
+                     ╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝
+```
+
+CLI for **Recursive Language Models** — based on the [RLM paper](https://arxiv.org/abs/2512.24601).
+
+Instead of dumping a huge context into a single LLM call, RLM lets the model write Python code to process it — slicing, chunking, running sub-queries on pieces, and building up an answer across multiple iterations.
+
+## Quick Start
+
+```bash
+git clone https://github.com/viplismism/rlm-cli.git
+cd rlm-cli
+npm install
+npm run build
+npm link   # makes `rlm` available globally
+```
+
+Then create a `.env` file with your API key:
+
+```bash
+cp .env.example .env
+```
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+# or
+OPENAI_API_KEY=sk-...
+
+# Optional: override default model
+# RLM_MODEL=claude-sonnet-4-5-20250929
+```
+
+That's it. Run `rlm` and you're in.
+
+## Usage
+
+### Interactive Terminal
+
+```bash
+rlm
+```
+
+This is the main way to use it. You get a persistent session where you can:
+
+- Load context from a file, URL, or by pasting text directly
+- Ask questions and watch the RLM loop run — you'll see the code it writes, the output, sub-queries, everything in real-time
+- All runs are saved as trajectory files you can browse later
+
+You don't even need to load context first — just type a query directly and RLM will use your question as the context:
+
+```bash
+> what are the top 5 sorting algorithms and their time complexities?
+```
+
+Load context and ask in one shot:
+
+```bash
+> @path/to/file.txt what are the main functions here?
+```
+
+Or set context first, then ask multiple questions:
+
+```bash
+> /file big-codebase.py
+> what does the main class do?
+> find all the error handling patterns
+```
+
+**Ctrl+C** stops the current query. **Ctrl+C twice** exits.
+
+Type `/help` inside the terminal for all commands.
+
+### Single-Shot Mode
+
+For scripting or one-off queries:
+
+```bash
+rlm run --file large-file.txt "List all classes and their methods"
+rlm run --url https://example.com/data.txt "Summarize this"
+cat data.txt | rlm run --stdin "Count the errors"
+```
+
+Answer goes to stdout, progress to stderr — pipe-friendly.
+
+### Trajectory Viewer
+
+```bash
+rlm viewer
+```
+
+Browse saved runs in a TUI. Navigate iterations, inspect the code and output at each step, drill into individual sub-queries.
+
+## Benchmarks
+
+Compare direct LLM vs RLM on the same query from standard long-context datasets. This runs both approaches side-by-side so you can see the difference.
+
+### Available Benchmarks
+
+| Benchmark | Dataset | What it tests |
+|-----------|---------|---------------|
+| `oolong` | [Oolong Synth](https://huggingface.co/datasets/oolongbench/oolong-synth) | Synthetic long-context tasks: timeline ordering, user tracking, counting |
+| `longbench` | [LongBench NarrativeQA](https://huggingface.co/datasets/THUDM/LongBench) | Reading comprehension over long narratives |
+
+### Running
+
+```bash
+rlm benchmark oolong          # default: index 4743 (14.7MB timeline+subset counting)
+rlm benchmark longbench       # default: index 182 (205KB multi-hop narrative reasoning)
+
+# Pick a specific example from the dataset
+rlm benchmark oolong --idx 10
+rlm benchmark longbench --idx 50
+```
+
+Python dependencies are auto-installed into a `.venv` on first run.
+
+Each run:
+1. Loads one example from the dataset
+2. Runs direct LLM (single prompt, no RLM)
+3. Runs RLM (iterative code execution with sub-queries)
+4. Prints both answers side-by-side with the expected answer, timing, and stats
+5. Saves a trajectory file for later inspection with `rlm viewer`
+
+## How It Works
+
+1. Your full context is loaded into a persistent Python REPL as a `context` variable
+2. The LLM gets metadata about the context (size, preview of first/last lines) plus your query
+3. It writes Python code that can slice `context`, call `llm_query(chunk, instruction)` to ask sub-questions about pieces, and call `FINAL(answer)` when it has the answer
+4. Code runs, output is captured and fed back for the next iteration
+5. Loop continues until `FINAL()` is called or max iterations are reached
+
+For large documents, the model typically chunks the text and runs parallel sub-queries with `async_llm_query()` + `asyncio.gather()`, then aggregates the results.
+
+## Configuration
+
+Edit `rlm_config.yaml` in the project root:
+
+```yaml
+max_iterations: 20       # Max iterations before giving up
+max_depth: 3             # Max recursive sub-agent depth
+max_sub_queries: 50      # Max total sub-queries
+truncate_len: 5000       # Truncate REPL output beyond this
+metadata_preview_lines: 20
+```
+
+## Project Structure
+
+```
+src/
+  main.ts          CLI entry point and command router
+  interactive.ts   Interactive terminal REPL
+  rlm.ts           Core RLM loop
+  repl.ts          Python REPL subprocess manager
+  runtime.py       Python runtime (FINAL, llm_query, async_llm_query)
+  cli.ts           Single-shot CLI mode
+  viewer.ts        Trajectory viewer TUI
+  config.ts        Config loader
+  env.ts           .env file loader
+benchmarks/
+  oolong_synth.ts           Oolong Synth benchmark
+  longbench_narrativeqa.ts  LongBench NarrativeQA benchmark
+  requirements.txt          Python deps for benchmarks
+bin/
+  rlm.mjs          Global CLI shim
+```
+
+## Requirements
+
+- Node.js >= 20
+- Python 3
+- An API key (Anthropic, OpenAI, or OpenRouter)
+
+## License
+
+MIT

package/bin/rlm.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+/**
+ * rlm — Recursive Language Model CLI
+ *
+ * This shim boots the CLI entry point. It tries the compiled dist first,
+ * then falls back to tsx for development.
+ */
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distEntry = join(__dirname, "..", "dist", "main.js");
+
+if (existsSync(distEntry)) {
+	// Production: use compiled JS
+	await import(distEntry);
+} else {
+	// Development: use tsx to run TypeScript directly
+	const srcEntry = join(__dirname, "..", "src", "main.ts");
+	const { register } = await import("node:module");
+
+	// Try to register tsx loader, then import
+	try {
+		const tsxPath = join(__dirname, "..", "node_modules", "tsx", "dist", "esm", "index.mjs");
+		if (existsSync(tsxPath)) {
+			register(tsxPath);
+		}
+		await import(srcEntry);
+	} catch {
+		// Fallback: spawn tsx as a child process
+		const { spawn } = await import("node:child_process");
+		const tsxBin = join(__dirname, "..", "node_modules", ".bin", "tsx");
+		const child = spawn(tsxBin, [srcEntry, ...process.argv.slice(2)], {
+			stdio: "inherit",
+		});
+		child.on("exit", (code) => process.exit(code ?? 1));
+		child.on("error", (err) => {
+			console.error(`Failed to start rlm: ${err.message}`);
+			process.exit(1);
+		});
+	}
+}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+/**
+ * Standalone RLM CLI — run Recursive Language Model queries from the terminal.
+ *
+ * Usage:
+ *   npx tsx src/cli.ts --model claude-sonnet-4-20250514 --file large-file.txt "What are the main themes?"
+ *   npx tsx src/cli.ts --model claude-sonnet-4-20250514 --url https://example.com/big.txt "Summarize this"
+ *   cat data.txt | npx tsx src/cli.ts --model claude-sonnet-4-20250514 --stdin "Count the errors"
+ *
+ * Environment:
+ *   ANTHROPIC_API_KEY — required for Anthropic models
+ *   OPENAI_API_KEY    — required for OpenAI models
+ *   (etc. per @mariozechner/pi-ai provider)
+ */
+import "./env.js";

package/dist/cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env tsx
+/**
+ * Standalone RLM CLI — run Recursive Language Model queries from the terminal.
+ *
+ * Usage:
+ *   npx tsx src/cli.ts --model claude-sonnet-4-20250514 --file large-file.txt "What are the main themes?"
+ *   npx tsx src/cli.ts --model claude-sonnet-4-20250514 --url https://example.com/big.txt "Summarize this"
+ *   cat data.txt | npx tsx src/cli.ts --model claude-sonnet-4-20250514 --stdin "Count the errors"
+ *
+ * Environment:
+ *   ANTHROPIC_API_KEY — required for Anthropic models
+ *   OPENAI_API_KEY    — required for OpenAI models
+ *   (etc. per @mariozechner/pi-ai provider)
+ */
+import "./env.js";
+import * as fs from "node:fs";
+// Dynamic imports — ensures env.js has set process.env BEFORE pi-ai loads
+const { getModels, getProviders } = await import("@mariozechner/pi-ai");
+const { PythonRepl } = await import("./repl.js");
+const { runRlmLoop } = await import("./rlm.js");
+// ── Arg parsing ─────────────────────────────────────────────────────────────
+function usage() {
+    console.error(`
+rlm-cli — Recursive Language Model CLI (arXiv:2512.24601)
+
+USAGE
+  rlm run [OPTIONS] "<query>"
+
+OPTIONS
+  --model <id>     Model ID (default: RLM_MODEL from .env)
+  --file <path>    Read context from a file
+  --url <url>      Fetch context from a URL
+  --stdin          Read context from stdin (pipe data in)
+  --verbose        Show iteration progress
+
+EXAMPLES
+  rlm run --file big.txt "List all classes"
+  curl -s https://example.com/large.py | rlm run --stdin "Summarize"
+  rlm run --url https://raw.githubusercontent.com/.../typing.py "Count public classes"
+`.trim());
+    process.exit(1);
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let modelId;
+    let file;
+    let url;
+    let useStdin = false;
+    let verbose = false;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--model" && i + 1 < args.length) {
+            modelId = args[++i];
+        }
+        else if (arg === "--file" && i + 1 < args.length) {
+            file = args[++i];
+        }
+        else if (arg === "--url" && i + 1 < args.length) {
+            url = args[++i];
+        }
+        else if (arg === "--stdin") {
+            useStdin = true;
+        }
+        else if (arg === "--verbose") {
+            verbose = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            usage();
+        }
+        else if (!arg.startsWith("--")) {
+            positional.push(arg);
+        }
+        else {
+            console.error(`Unknown option: ${arg}`);
+            usage();
+        }
+    }
+    if (!modelId) {
+        modelId = process.env.RLM_MODEL || "claude-sonnet-4-5-20250929";
+    }
+    if (positional.length === 0) {
+        console.error("Error: query argument is required");
+        usage();
+    }
+    const query = positional.join(" ");
+    if (!file && !url && !useStdin) {
+        console.error("Error: one of --file, --url, or --stdin is required");
+        usage();
+    }
+    return { modelId, file, url, useStdin, verbose, query };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+async function fetchUrl(url) {
+    const resp = await fetch(url);
+    if (!resp.ok) {
+        throw new Error(`Failed to fetch ${url}: ${resp.status} ${resp.statusText}`);
+    }
+    return resp.text();
+}
+// ── Main ────────────────────────────────────────────────────────────────────
+async function main() {
+    const args = parseArgs();
+    // Resolve model by scanning all providers
+    let model;
+    const allModelIds = [];
+    for (const provider of getProviders()) {
+        const providerModels = getModels(provider);
+        for (const m of providerModels) {
+            allModelIds.push(m.id);
+            if (m.id === args.modelId) {
+                model = m;
+            }
+        }
+    }
+    if (!model) {
+        console.error(`Error: unknown model "${args.modelId}"`);
+        console.error(`Available models: ${allModelIds.join(", ")}`);
+        process.exit(1);
+    }
+    // Load context
+    let context;
+    if (args.file) {
+        console.error(`Reading context from file: ${args.file}`);
+        context = fs.readFileSync(args.file, "utf-8");
+    }
+    else if (args.url) {
+        console.error(`Fetching context from URL: ${args.url}`);
+        context = await fetchUrl(args.url);
+    }
+    else {
+        console.error("Reading context from stdin...");
+        context = await readStdin();
+    }
+    console.error(`Context loaded: ${context.length.toLocaleString()} characters`);
+    console.error(`Model: ${model.id}`);
+    console.error(`Query: ${args.query}`);
+    console.error("---");
+    // Start REPL
+    const repl = new PythonRepl();
+    const ac = new AbortController();
+    process.on("SIGINT", () => {
+        console.error("\nAborting...");
+        ac.abort();
+    });
+    try {
+        await repl.start(ac.signal);
+        const startTime = Date.now();
+        const result = await runRlmLoop({
+            context,
+            query: args.query,
+            model,
+            repl,
+            signal: ac.signal,
+            onProgress: args.verbose
+                ? (info) => {
+                    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+                    console.error(`[${elapsed}s] Iteration ${info.iteration}/${info.maxIterations} | ` +
+                        `Sub-queries: ${info.subQueries} | Phase: ${info.phase}`);
+                }
+                : undefined,
+        });
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        console.error("---");
+        console.error(`Completed in ${elapsed}s | ${result.iterations} iterations | ${result.totalSubQueries} sub-queries | ${result.completed ? "success" : "incomplete"}`);
+        console.error("---");
+        // Write the answer to stdout (not stderr) so it can be piped
+        console.log(result.answer);
+    }
+    finally {
+        repl.shutdown();
+    }
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Configuration loader for RLM CLI.
+ *
+ * Reads rlm_config.yaml from the project root (or cwd), with sensible defaults.
+ */
+export interface RlmConfig {
+    max_iterations: number;
+    max_depth: number;
+    max_sub_queries: number;
+    truncate_len: number;
+    metadata_preview_lines: number;
+}
+export declare function loadConfig(): RlmConfig;

package/dist/config.js

@@ -0,0 +1,73 @@
+/**
+ * Configuration loader for RLM CLI.
+ *
+ * Reads rlm_config.yaml from the project root (or cwd), with sensible defaults.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const DEFAULTS = {
+    max_iterations: 20,
+    max_depth: 3,
+    max_sub_queries: 50,
+    truncate_len: 5000,
+    metadata_preview_lines: 20,
+};
+function parseYaml(text) {
+    // Minimal YAML parser for flat key:value files (no nested objects, no arrays)
+    const result = {};
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const colonIdx = trimmed.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const key = trimmed.slice(0, colonIdx).trim();
+        const rawVal = trimmed.slice(colonIdx + 1).trim();
+        // Strip inline comments
+        const val = rawVal.replace(/\s+#.*$/, "");
+        // Parse number
+        const num = Number(val);
+        if (!isNaN(num) && val !== "") {
+            result[key] = num;
+        }
+        else if (val === "true") {
+            result[key] = true;
+        }
+        else if (val === "false") {
+            result[key] = false;
+        }
+        else {
+            // Strip quotes
+            result[key] = val.replace(/^["']|["']$/g, "");
+        }
+    }
+    return result;
+}
+export function loadConfig() {
+    // Search order: cwd, then package root
+    const candidates = [
+        path.resolve(process.cwd(), "rlm_config.yaml"),
+        path.resolve(new URL(".", import.meta.url).pathname, "..", "rlm_config.yaml"),
+    ];
+    for (const configPath of candidates) {
+        if (fs.existsSync(configPath)) {
+            try {
+                const raw = fs.readFileSync(configPath, "utf-8");
+                const parsed = parseYaml(raw);
+                return {
+                    max_iterations: typeof parsed.max_iterations === "number" ? parsed.max_iterations : DEFAULTS.max_iterations,
+                    max_depth: typeof parsed.max_depth === "number" ? parsed.max_depth : DEFAULTS.max_depth,
+                    max_sub_queries: typeof parsed.max_sub_queries === "number" ? parsed.max_sub_queries : DEFAULTS.max_sub_queries,
+                    truncate_len: typeof parsed.truncate_len === "number" ? parsed.truncate_len : DEFAULTS.truncate_len,
+                    metadata_preview_lines: typeof parsed.metadata_preview_lines === "number" ? parsed.metadata_preview_lines : DEFAULTS.metadata_preview_lines,
+                };
+            }
+            catch {
+                // Fall through to defaults
+            }
+        }
+    }
+    return { ...DEFAULTS };
+}
+//# sourceMappingURL=config.js.map

package/dist/env.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Load .env file into process.env.
+ * Must be imported BEFORE any module that reads env vars (e.g. pi-ai).
+ *
+ * Supports:
+ * - ANTHROPIC_API_KEY
+ * - RLM_MODEL (model name, e.g. claude-sonnet-4-5-20250929)
+ */
+export {};

package/dist/env.js

@@ -0,0 +1,34 @@
+/**
+ * Load .env file into process.env.
+ * Must be imported BEFORE any module that reads env vars (e.g. pi-ai).
+ *
+ * Supports:
+ * - ANTHROPIC_API_KEY
+ * - RLM_MODEL (model name, e.g. claude-sonnet-4-5-20250929)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+// Load .env file from the package root (not CWD, which could be untrusted)
+const __dir = path.dirname(new URL(import.meta.url).pathname);
+const envPath = path.resolve(__dir, "..", ".env");
+if (fs.existsSync(envPath)) {
+    const content = fs.readFileSync(envPath, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        const value = trimmed.slice(eqIndex + 1).trim();
+        if (key) {
+            process.env[key] = value;
+        }
+    }
+}
+// Default model
+if (!process.env.RLM_MODEL) {
+    process.env.RLM_MODEL = "claude-sonnet-4-5-20250929";
+}
+//# sourceMappingURL=env.js.map

package/dist/interactive.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env tsx
+/**
+ * RLM Interactive — Production-quality interactive terminal REPL.
+ *
+ * Launch with `rlm` and get a persistent session where you can:
+ *   - Set context (file/URL/paste)
+ *   - Type queries and watch the RLM loop run with smooth, real-time output
+ *   - Browse previous trajectories
+ */
+import "./env.js";