rlm-cli 0.2.0

package/dist/main.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+/**
+ * rlm — Recursive Language Model CLI
+ *
+ * Entry point for the `rlm` command.
+ *
+ *   rlm              → interactive terminal (default)
+ *   rlm run          → single-shot CLI run
+ *   rlm help         → show help
+ */
+export {};

package/dist/main.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env tsx
+/**
+ * rlm — Recursive Language Model CLI
+ *
+ * Entry point for the `rlm` command.
+ *
+ *   rlm              → interactive terminal (default)
+ *   rlm run          → single-shot CLI run
+ *   rlm help         → show help
+ */
+const HELP = `
+\x1b[36m╔══════════════════════════════════════════════════════════════╗
+║               rlm — Recursive Language Models                ║
+║          CLI for large-context LLM processing                ║
+║              arXiv:2512.24601                                ║
+╚══════════════════════════════════════════════════════════════╝\x1b[0m
+
+\x1b[1mUSAGE\x1b[0m
+  \x1b[33mrlm\x1b[0m                          Interactive terminal (default)
+  \x1b[33mrlm run\x1b[0m [options] "<query>"  Run a single query
+  \x1b[33mrlm viewer\x1b[0m                    Browse saved trajectory files
+  \x1b[33mrlm benchmark\x1b[0m <name> [--idx]  Run benchmark (direct LLM vs RLM)
+
+\x1b[1mRUN OPTIONS\x1b[0m
+  --model <id>     Override model (default: RLM_MODEL from .env)
+  --file <path>    Read context from a file
+  --url <url>      Fetch context from a URL
+  --stdin          Read context from stdin
+  --verbose        Show iteration progress
+
+\x1b[1mCONFIGURATION\x1b[0m
+  .env file:
+    ANTHROPIC_API_KEY=sk-ant-...
+    RLM_MODEL=claude-sonnet-4-5-20250929
+
+  rlm_config.yaml:
+    max_iterations: 20
+    max_depth: 3
+    max_sub_queries: 50
+    truncate_len: 5000
+`.trim();
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0] || "interactive";
+    switch (command) {
+        case "interactive":
+        case "i": {
+            await import("./interactive.js");
+            break;
+        }
+        case "viewer":
+        case "view": {
+            // Strip the subcommand from argv so viewer.ts doesn't see it as a file path
+            process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
+            await import("./viewer.js");
+            break;
+        }
+        case "run": {
+            process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
+            await import("./cli.js");
+            break;
+        }
+        case "benchmark":
+        case "bench": {
+            const benchName = args[1];
+            const benchArgs = args.slice(2);
+            const benchScripts = {
+                oolong: "benchmarks/oolong_synth.ts",
+                longbench: "benchmarks/longbench_narrativeqa.ts",
+            };
+            if (benchName && benchScripts[benchName]) {
+                const { spawn } = await import("node:child_process");
+                const { dirname, join } = await import("node:path");
+                const { fileURLToPath } = await import("node:url");
+                const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+                const script = join(root, benchScripts[benchName]);
+                const tsxBin = join(root, "node_modules", ".bin", "tsx");
+                await new Promise((resolve, reject) => {
+                    const child = spawn(tsxBin, [script, ...benchArgs], {
+                        stdio: "inherit",
+                        cwd: root,
+                    });
+                    child.on("exit", (code) => {
+                        process.exitCode = code ?? 1;
+                        resolve();
+                    });
+                    child.on("error", (err) => {
+                        reject(new Error(`Failed to spawn benchmark: ${err.message}`));
+                    });
+                });
+            }
+            else {
+                console.log(`\x1b[36m\x1b[1mrlm benchmark\x1b[0m — Run direct LLM vs RLM comparison\n`);
+                console.log(`\x1b[1mUSAGE\x1b[0m`);
+                console.log(`  \x1b[33mrlm benchmark oolong\x1b[0m    [--idx N]  Oolong Synth (synthetic long-context)`);
+                console.log(`  \x1b[33mrlm benchmark longbench\x1b[0m [--idx N]  LongBench NarrativeQA (reading comprehension)\n`);
+                console.log(`Python dependencies are auto-installed into .venv on first run.\n`);
+                console.log(`Each benchmark loads a dataset example, runs it through both direct LLM`);
+                console.log(`and RLM, then prints a side-by-side comparison with timing.`);
+            }
+            break;
+        }
+        case "help":
+        case "--help":
+        case "-h": {
+            console.log(HELP);
+            break;
+        }
+        case "version":
+        case "--version":
+        case "-v": {
+            try {
+                const { readFileSync } = await import("node:fs");
+                const { dirname, join } = await import("node:path");
+                const { fileURLToPath } = await import("node:url");
+                const __dir = dirname(fileURLToPath(import.meta.url));
+                const pkgPath = join(__dir, "..", "package.json");
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+                console.log(`rlm v${pkg.version}`);
+            }
+            catch {
+                console.log("rlm v0.1.0");
+            }
+            break;
+        }
+        default: {
+            if (command.startsWith("--")) {
+                // Flags without subcommand → assume "run"
+                await import("./cli.js");
+            }
+            else {
+                console.error(`Unknown command: ${command}`);
+                console.error('Run "rlm help" for usage information.');
+                process.exit(1);
+            }
+        }
+    }
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+export {};
+//# sourceMappingURL=main.js.map

package/dist/repl.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Persistent Python REPL manager for the RLM CLI.
+ *
+ * Spawns a single Python subprocess running `runtime.py` and keeps it alive
+ * across multiple RLM iterations. Communication uses line-delimited JSON
+ * over stdin/stdout.
+ */
+/** Result of executing a code snippet in the REPL. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    hasFinal: boolean;
+    finalValue: string | null;
+}
+/** Callback the host provides to handle llm_query() calls from Python. */
+export type LlmQueryHandler = (subContext: string, instruction: string) => Promise<string>;
+export declare class PythonRepl {
+    private proc;
+    private rl;
+    private llmQueryHandler;
+    /**
+     * Pending resolvers for messages we're waiting on from Python.
+     * Each entry maps a message type to a one-shot resolve/reject pair.
+     */
+    private pending;
+    /** Whether the REPL subprocess is alive. */
+    get isAlive(): boolean;
+    /**
+     * Start the Python subprocess and wait for it to signal readiness.
+     */
+    start(signal?: AbortSignal): Promise<void>;
+    /** Register the callback that handles llm_query() calls from Python. */
+    setLlmQueryHandler(handler: LlmQueryHandler): void;
+    /** Inject the full context string into the Python REPL. */
+    setContext(text: string): Promise<void>;
+    /** Reset the Final sentinel variable. */
+    resetFinal(): Promise<void>;
+    /** Execute a code snippet and return the result. */
+    execute(code: string): Promise<ExecResult>;
+    /** Gracefully shut down the Python subprocess. */
+    shutdown(): void;
+    private send;
+    private handleLine;
+    private handleLlmQueryMessage;
+    private waitForMessage;
+    private cleanup;
+}

package/dist/repl.js

@@ -0,0 +1,183 @@
+/**
+ * Persistent Python REPL manager for the RLM CLI.
+ *
+ * Spawns a single Python subprocess running `runtime.py` and keeps it alive
+ * across multiple RLM iterations. Communication uses line-delimited JSON
+ * over stdin/stdout.
+ */
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import * as readline from "node:readline";
+// ── REPL class ──────────────────────────────────────────────────────────────
+export class PythonRepl {
+    proc = null;
+    rl = null;
+    llmQueryHandler = null;
+    /**
+     * Pending resolvers for messages we're waiting on from Python.
+     * Each entry maps a message type to a one-shot resolve/reject pair.
+     */
+    pending = new Map();
+    /** Whether the REPL subprocess is alive. */
+    get isAlive() {
+        return this.proc !== null && this.proc.exitCode === null;
+    }
+    /**
+     * Start the Python subprocess and wait for it to signal readiness.
+     */
+    async start(signal) {
+        if (this.isAlive)
+            return;
+        const runtimePath = path.join(path.dirname(new URL(import.meta.url).pathname), "runtime.py");
+        this.proc = spawn("python3", [runtimePath], {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                // Only pass what Python actually needs — not API keys or secrets
+                PATH: process.env.PATH,
+                HOME: process.env.HOME,
+                PYTHONUNBUFFERED: "1",
+            },
+        });
+        this.rl = readline.createInterface({ input: this.proc.stdout });
+        this.rl.on("line", (line) => this.handleLine(line));
+        this.proc.stderr.on("data", (chunk) => {
+            const text = chunk.toString();
+            if (text.trim()) {
+                process.stderr.write(`[rlm-repl-python] ${text}`);
+            }
+        });
+        this.proc.on("close", () => {
+            this.cleanup();
+        });
+        if (signal) {
+            signal.addEventListener("abort", () => {
+                this.shutdown();
+            }, { once: true });
+        }
+        await this.waitForMessage("ready");
+    }
+    /** Register the callback that handles llm_query() calls from Python. */
+    setLlmQueryHandler(handler) {
+        this.llmQueryHandler = handler;
+    }
+    /** Inject the full context string into the Python REPL. */
+    async setContext(text) {
+        this.send({ type: "set_context", value: text });
+        await this.waitForMessage("context_set");
+    }
+    /** Reset the Final sentinel variable. */
+    async resetFinal() {
+        this.send({ type: "reset_final" });
+        await this.waitForMessage("final_reset");
+    }
+    /** Execute a code snippet and return the result. */
+    async execute(code) {
+        this.send({ type: "exec", code });
+        const msg = (await this.waitForMessage("exec_done"));
+        return {
+            stdout: msg.stdout,
+            stderr: msg.stderr,
+            hasFinal: msg.has_final,
+            finalValue: msg.final_value,
+        };
+    }
+    /** Gracefully shut down the Python subprocess. */
+    shutdown() {
+        if (this.proc && this.proc.exitCode === null) {
+            try {
+                this.send({ type: "shutdown" });
+            }
+            catch {
+                // stdin may already be closed
+            }
+            this.proc.kill("SIGTERM");
+        }
+        this.cleanup();
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    send(msg) {
+        if (!this.proc || !this.proc.stdin || this.proc.stdin.destroyed) {
+            throw new Error("REPL subprocess is not running");
+        }
+        this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
+    }
+    handleLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        if (msg.type === "llm_query") {
+            this.handleLlmQueryMessage(msg);
+            return;
+        }
+        const entry = this.pending.get(msg.type);
+        if (entry) {
+            this.pending.delete(msg.type);
+            entry.resolve(msg);
+        }
+    }
+    async handleLlmQueryMessage(msg) {
+        if (!this.llmQueryHandler) {
+            this.send({
+                type: "llm_result",
+                id: msg.id,
+                result: "[ERROR] No LLM query handler registered",
+            });
+            return;
+        }
+        try {
+            const result = await this.llmQueryHandler(msg.sub_context, msg.instruction);
+            this.send({ type: "llm_result", id: msg.id, result });
+        }
+        catch (err) {
+            const errorText = err instanceof Error ? err.message : String(err);
+            this.send({
+                type: "llm_result",
+                id: msg.id,
+                result: `[ERROR] LLM query failed: ${errorText}`,
+            });
+        }
+    }
+    waitForMessage(type) {
+        return new Promise((resolve, reject) => {
+            if (!this.isAlive) {
+                reject(new Error(`REPL subprocess is not running (waiting for "${type}")`));
+                return;
+            }
+            const timeout = setTimeout(() => {
+                if (this.pending.has(type)) {
+                    this.pending.delete(type);
+                    reject(new Error(`Timeout waiting for "${type}" from Python REPL`));
+                }
+            }, 300_000);
+            this.pending.set(type, {
+                resolve: (msg) => {
+                    clearTimeout(timeout);
+                    resolve(msg);
+                },
+                reject: (err) => {
+                    clearTimeout(timeout);
+                    reject(err);
+                },
+            });
+        });
+    }
+    cleanup() {
+        this.rl?.close();
+        this.rl = null;
+        this.proc = null;
+        // Reject all pending promises so callers unblock immediately
+        const abortError = new Error("REPL shut down");
+        for (const [, entry] of this.pending) {
+            entry.reject(abortError);
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=repl.js.map

package/dist/rlm.d.ts

@@ -0,0 +1,55 @@
+/**
+ * RLM Loop — implements Algorithm 1 from "Recursive Language Models" (arXiv:2512.24601).
+ *
+ * The loop works as follows:
+ *   1. Inject the full context into a persistent Python REPL as a variable.
+ *   2. Send the LLM metadata about the context plus the user's query.
+ *      The LLM writes Python code that can inspect/slice/query `context`,
+ *      call `llm_query()` recursively, and call FINAL() when done.
+ *   3. Execute the code, capture stdout.
+ *   4. If FINAL is set, return it. Otherwise loop.
+ */
+import { type Api, type Model } from "@mariozechner/pi-ai";
+import type { PythonRepl } from "./repl.js";
+export interface RlmOptions {
+    context: string;
+    query: string;
+    model: Model<Api>;
+    repl: PythonRepl;
+    signal?: AbortSignal;
+    onProgress?: (info: RlmProgress) => void;
+    onSubQueryStart?: (info: SubQueryStartInfo) => void;
+    onSubQuery?: (info: SubQueryInfo) => void;
+}
+export interface RlmProgress {
+    iteration: number;
+    maxIterations: number;
+    subQueries: number;
+    phase: "generating_code" | "executing" | "checking_final";
+    code?: string;
+    stdout?: string;
+    stderr?: string;
+    userMessage?: string;
+    rawResponse?: string;
+    systemPrompt?: string;
+}
+export interface SubQueryStartInfo {
+    index: number;
+    contextLength: number;
+    instruction: string;
+}
+export interface SubQueryInfo {
+    index: number;
+    contextLength: number;
+    instruction: string;
+    resultLength: number;
+    resultPreview: string;
+    elapsedMs: number;
+}
+export interface RlmResult {
+    answer: string;
+    iterations: number;
+    totalSubQueries: number;
+    completed: boolean;
+}
+export declare function runRlmLoop(options: RlmOptions): Promise<RlmResult>;