rubyrlm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be38bd741250692279b5207395414b43c3d473dd00dd8835e208a8a5ffe3fb43
+  data.tar.gz: 8d8facc2f1c7b0773345bd6930f361501a0f75fb7017a5f45d905bd9614098fb
+SHA512:
+  metadata.gz: d53be5b4873058dec0dbdb564806d66fdcc63555365613e3df19e8eca49e356ec78df3fd72eca503bba3d12411172b71d3f66061f7ac84c41f05411dc9cfebac
+  data.tar.gz: e33f04262ccd83d8f867e49d98d6b8b93a64f1eb5745c0a54a97c45f61e0a51c4e4abfd996c49dc77483c223624de59205150adeb08a51a02e1842c3916583e6

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-12
+
+### Added
+- Core RLM client with Gemini backend, multi-turn conversation, and streaming support
+- Local and Docker-isolated REPL runtimes with configurable execution timeout
+- AST-based code validation (Ripper syntax checking + dangerous call detection)
+- Sub-call caching with SHA256-keyed deduplication for `llm_query`
+- Patch tracking with undo support (`undo_last_patch` / `undo_all_patches`)
+- Per-model USD cost tracking with cache-aware billing
+- Shared backend client for child RLMs to reduce per-subcall overhead
+- Web UI with session management, streaming timeline, and Mermaid diagram rendering
+- Theme-aware HTML and PNG exports with glassmorphism styling
+- Session continuation and Controller view with inline prompt
+- Time-scoped filtering and cache tracking in analytics dashboard
+- Docker session reuse and keep-alive configuration options
+- LocalRepl helper primitives for common agent workflows
+- JSONL structured logging
+- `rlm` CLI executable
+- Custom Night Owl syntax highlighting theme
+
+### Fixed
+- Docker container DNS resolution and `network_mode` wiring
+- Docker agent symbol/string key mismatch for `allow_network`
+- Session continuation logic and UI display
+- Kramdown rendering with GFM parser dependency
+- CSS specificity for headless Chrome export rendering
+- UI pivot masking during live stream execution tracking
+- Cache-busting for static assets

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taylor Weibley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,300 @@
+# RubyRLM
+
+RubyRLM is an MVP Ruby implementation of Recursive Language Models (RLMs) that uses Gemini as the model backend and a Ruby REPL for iterative reasoning.
+
+## What This MVP Includes
+
+- `RubyRLM::Client` API similar to `rlm.completion(...)`.
+- Gemini backend via direct REST (`generateContent`).
+- Local and Docker-isolated REPL backends with iterative `exec` actions and `final` answer action.
+- Recursive sub-calls with `llm_query(...)` up to `max_depth`.
+- **AST code validation** — Ripper-based syntax checking and dangerous call detection before eval.
+- **Sub-call caching** — SHA256-keyed deduplication of `llm_query` calls within a session.
+- **Patch tracking** — Audit trail for all `patch_file` operations with undo support.
+- JSONL trajectory logging for iteration debugging.
+- Web UI with session replay, continuation, and environment selection.
+- RSpec test suite for parser, loop, REPL, recursion, and backend retries.
+
+## Safety Model
+
+RubyRLM executes model-produced Ruby code. Choose execution environment based on your trust boundary.
+
+- `environment: "local"` runs code directly on the host process (unsafe for untrusted prompts).
+- `environment: "docker"` runs code in a Docker container with isolation defaults.
+- Keep side effects disabled unless intentionally requested.
+
+### Code Validation
+
+Before executing any LLM-generated code, RubyRLM validates it using Ruby's `Ripper` parser:
+
+- **Syntax errors** are caught immediately without running the code, saving an iteration.
+- **Dangerous calls** (`system`, `exec`, `fork`, `exit`, `File.delete`, `Kernel.exit`, etc.) are detected and surfaced as warnings in the `ExecutionResult`. These are non-blocking since the REPL intentionally provides safe wrappers like `sh()`, but they alert you when the model bypasses those wrappers.
+
+Warnings appear in iteration metadata:
+
+```ruby
+result.metadata[:iterations].each do |it|
+  puts it[:execution][:warnings] if it.dig(:execution, :warnings)&.any?
+end
+```
+
+## Requirements
+
+- Ruby `>= 3.1`
+- `GEMINI_API_KEY` in your shell environment
+- Docker (optional, required only for `environment: "docker"`)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rubyrlm"
+```
+
+Or install directly:
+
+```bash
+gem install rubyrlm
+```
+
+### Development Setup
+
+```bash
+git clone https://github.com/tweibley/rubyrlm.git
+cd rubyrlm
+bundle install
+bundle exec rspec
+```
+
+If you plan to use Docker execution, build the REPL image once:
+
+```bash
+docker build -t rubyrlm/repl:latest -f docker/Dockerfile.repl docker/
+```
+
+## Quickstart
+
+```ruby
+require "rubyrlm"
+
+client = RubyRLM::Client.new(
+  backend: "gemini",
+  model_name: "gemini-3.1-pro-preview",
+  api_key: ENV["GEMINI_API_KEY"],
+  max_depth: 1,
+  max_iterations: 20,
+  logger: RubyRLM::Logger::JsonlLogger.new(log_dir: "./logs"),
+  verbose: true
+)
+
+result = client.completion(prompt: "Calculate 2^(2^(2^2)) with Ruby and explain the result.")
+puts result.response
+puts result.usage_summary.to_h
+```
+
+Run in Docker-isolated mode:
+
+```ruby
+client = RubyRLM::Client.new(
+  backend: "gemini",
+  model_name: "gemini-3.1-pro-preview",
+  api_key: ENV["GEMINI_API_KEY"],
+  environment: "docker",
+  environment_options: {
+    memory_limit: "256m",
+    allow_network: true
+  }
+)
+```
+
+You can also run:
+
+```bash
+ruby examples/quickstart.rb
+```
+
+For an interactive session with a preloaded client:
+
+```bash
+bundle exec bin/console
+```
+
+Inside console:
+
+```ruby
+ask(client, "What is the latency to google.com from this machine?")
+```
+
+With `verbose: true`, you'll now see each iteration's actual `exec` Ruby code plus execution output/error summaries, not just the action names.
+
+## CLI
+
+RubyRLM ships with a `rubyrlm` command:
+
+```bash
+rubyrlm "Calculate 2^(2^(2^2)) with Ruby and explain the result."
+```
+
+Options:
+
+```
+-m, --model MODEL          Model name (default: gemini-3.1-pro-preview)
+-e, --env ENV              Execution environment: local or docker (default: local)
+    --max-iterations NUM   Maximum iterations (default: 30)
+    --max-depth NUM        Maximum recursion depth (default: 1)
+    --timeout SECS         Iteration execution timeout (default: 60)
+    --thinking LEVEL       Thinking level: low|medium|high (default: medium)
+    --keep-alive           Keep docker container alive after run
+    --reuse-container-id ID  Reuse existing docker container
+    --allow-network        Allow docker container to access host networking
+-v, --verbose              Enable verbose debug output
+```
+
+Prompts can also be piped via stdin:
+
+```bash
+echo "What is 1+1?" | rubyrlm
+```
+
+## How the Action Protocol Works
+
+The model must return exactly one JSON object per turn:
+
+- `{"action":"exec","code":"<ruby code>"}` to run code in REPL
+- `{"action":"final","answer":"<final answer>"}` to finish
+
+If model output is malformed, RubyRLM issues one repair re-prompt. If `max_iterations` is reached, RubyRLM forces a final response.
+
+## REPL Variables and Helpers
+
+Within `exec` code:
+
+- `context` is the original prompt/context
+- `llm_query(sub_prompt, model_name: nil)` launches a recursive sub-call
+- `fetch(url, headers: {})` performs HTTP GET with redirect following
+- `sh(command, timeout: 5)` runs a shell command safely
+- `patch_file(path, old_text, new_text)` replaces text exactly once (tracked for undo)
+- `grep(pattern, path: ".")` searches with ripgrep
+- `chunk_text(text, max_length: 2000)` splits long text semantically
+
+RubyRLM sends a compact context summary to the model and keeps full data in REPL memory. This significantly reduces repeated prompt tokens for large datasets.
+
+For state between iterations, prefer instance variables (for example `@memo`) or helper methods.
+
+## Sub-Call Caching
+
+Identical `llm_query` calls within a session are automatically deduplicated. The cache keys on `SHA256(model_name + prompt)`, so the same question to the same model returns the cached result.
+
+Cache stats are included in the completion result:
+
+```ruby
+result = client.completion(prompt: data)
+puts result.metadata[:sub_call_cache]
+# => { hits: 3, misses: 2, size: 2 }
+```
+
+## Patch Tracking & Undo
+
+Every `patch_file` call is recorded with old/new text and a timestamp. The modification log is surfaced in the completion result:
+
+```ruby
+result = client.completion(prompt: "Fix the typo in config.yml")
+puts result.metadata[:file_modifications]
+# => [{ path: "config.yml", timestamp: "2026-02-28T12:34:56-05:00" }]
+```
+
+Patches can be undone programmatically through the REPL:
+
+```ruby
+# Inside exec code
+undo_result = undo_last_patch   # reverses the most recent patch_file
+undo_all   = undo_all_patches  # reverses all patches in LIFO order
+```
+
+## Docker Environment Options
+
+When `environment: "docker"` is selected, `environment_options` supports:
+
+- `image` (default: `"rubyrlm/repl:latest"`)
+- `memory_limit` (default: `"256m"`)
+- `cpu_quota` (default: `50000`)
+- `network_mode` (`"none"` by default, `"bridge"` to allow outbound)
+- `allow_network` (boolean shorthand for bridge networking)
+- `keep_alive` (optional boolean to bypass container teardown on completion)
+- `reuse_container_id` (optional Docker container ID to eagerly attach to instead of spinning up a new instance)
+- `connect_timeout` (default: `10` seconds)
+- `gemini_api_key_secret` (default: `"gemini_api_key"`)
+- `gemini_api_key_secret_path` (optional absolute path to a host secret file)
+
+Notes:
+
+- Docker mode is strict isolation by default (no project workspace mount).
+- `llm_query`, `fetch`, `sh`, and `chunk_text` run inside the container.
+- `patch_file` and `grep` are intentionally disabled in strict Docker mode.
+- Gemini credentials are read in-container from `GEMINI_API_KEY_FILE` (mounted from your secret file).
+
+Example secret-file setup for Docker mode:
+
+```bash
+mkdir -p .secrets
+printf '%s\n' "$GEMINI_API_KEY" > .secrets/gemini_api_key
+chmod 600 .secrets/gemini_api_key
+```
+
+```ruby
+client = RubyRLM::Client.new(
+  backend: "gemini",
+  model_name: "gemini-3.1-pro-preview",
+  environment: "docker",
+  environment_options: {
+    gemini_api_key_secret_path: File.expand_path(".secrets/gemini_api_key")
+  }
+)
+```
+
+## Web UI
+
+Start the web UI:
+
+```bash
+ruby viewer.rb -p 8080
+```
+
+or in dev mode:
+
+```bash
+bin/dev -p 8080
+```
+
+In the **Controller** sidebar you can select:
+
+- **Execution Environment**: Local or Docker
+- **Allow Docker Network Access**: enable outbound networking in Docker mode
+- **Keep Container Alive**: prevents Docker from terminating and removing the instance when the run completes
+- **Reuse Container Instance**: actively queries running isolate workers and allows you to submit queries directly into persistent host environments
+
+## Logging
+
+Pass `RubyRLM::Logger::JsonlLogger.new(log_dir: "./logs")` to the client.
+
+Events are written per-run as JSONL and include:
+
+- run start/end
+- per-iteration actions and execution results
+- parent-child run relationship for recursive sub-calls
+
+## Examples
+
+- `examples/quickstart.rb`: single prompt run with logger
+- `examples/needle_in_haystack.rb`: synthetic long-context retrieval task
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+## Future Extensions
+
+- More backend adapters

data/bin/rubyrlm

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "rubyrlm"
+require "optparse"
+
+options = {
+  model_name: "gemini-3.1-pro-preview",
+  environment: "local",
+  max_iterations: 30,
+  max_depth: 1,
+  iteration_timeout: 60,
+  thinking_level: "medium",
+  environment_options: {},
+  verbose: false,
+  log_dir: File.expand_path("../logs", __dir__)
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: rubyrlm [options] \"<prompt>\""
+
+  opts.on("-m", "--model MODEL", "Model name (default: gemini-3.1-pro-preview)") do |v|
+    options[:model_name] = v
+  end
+
+  opts.on("-e", "--env ENV", "Execution environment: local or docker (default: local)") do |v|
+    options[:environment] = v
+  end
+
+  opts.on("--max-iterations NUM", Integer, "Maximum iterations (default: 30)") do |v|
+    options[:max_iterations] = v
+  end
+
+  opts.on("--max-depth NUM", Integer, "Maximum recursion depth (default: 1)") do |v|
+    options[:max_depth] = v
+  end
+
+  opts.on("--timeout SECS", Integer, "Iteration execution timeout (default: 60)") do |v|
+    options[:iteration_timeout] = v
+  end
+
+  opts.on("--thinking LEVEL", "Thinking level: low|medium|high (default: medium)") do |v|
+    options[:thinking_level] = v
+  end
+
+  opts.on("--keep-alive", "Keep docker container alive after run") do
+    options[:environment_options][:keep_alive] = true
+  end
+
+  opts.on("--reuse-container-id ID", "Reuse existing docker container by its ID") do |v|
+    options[:environment_options][:reuse_container_id] = v
+  end
+
+  opts.on("--allow-network", "Allow docker container to access host networking") do
+    options[:environment_options][:allow_network] = true
+  end
+
+  opts.on("-v", "--verbose", "Enable verbose debug output") do
+    options[:verbose] = true
+  end
+
+  opts.on("-h", "--help", "Prints this help") do
+    puts opts
+    exit
+  end
+end
+
+parser.parse!
+
+prompt = ARGV.join(" ").strip
+if prompt.empty? && !STDIN.tty?
+  prompt = STDIN.read.strip
+end
+
+if prompt.empty?
+  puts parser.help
+  exit 1
+end
+
+api_key = ENV["GEMINI_API_KEY"]
+if api_key.to_s.strip.empty?
+  warn "Error: GEMINI_API_KEY is missing in environment."
+  exit 1
+end
+
+class MultiLogger
+  def initialize(*loggers)
+    @loggers = loggers.compact
+  end
+
+  def log(payload)
+    @loggers.each { |l| l.log(payload) }
+  rescue => e
+    warn "Logger error: #{e.message}"
+  end
+end
+
+class CliStreamer
+  def initialize
+    @in_chunk = false
+  end
+
+  def log(payload)
+    case payload[:type]
+    when "chunk"
+      print payload[:chunk]
+      @in_chunk = true
+    when "iteration"
+      puts "" if @in_chunk
+      @in_chunk = false
+      data = payload[:data]
+      if data && data[:action] == "exec"
+        puts "\n\n[Executing Ruby Code] ->"
+        puts "```ruby\n#{data[:code]}\n```"
+        if data[:execution]
+          puts "[Result: #{data[:execution][:ok] ? 'Success' : 'Failed'}]"
+          puts data[:execution][:output]
+          puts data[:execution][:error] if data[:execution][:error]
+        end
+        puts "-" * 40
+      end
+    when "run_error"
+      puts "" if @in_chunk
+      @in_chunk = false
+      puts "\n[Error] #{payload[:error]}"
+    end
+  end
+end
+
+cli_streamer = CliStreamer.new
+jsonl_logger = RubyRLM::Logger::JsonlLogger.new(log_dir: options[:log_dir])
+multi_logger = MultiLogger.new(cli_streamer, jsonl_logger)
+
+generation_config = {}
+if %w[low medium high].include?(options[:thinking_level].to_s.downcase)
+  generation_config[:thinking_config] = { thinkingLevel: options[:thinking_level].to_s.downcase }
+end
+
+client_kwargs = {
+  backend: "gemini",
+  api_key: api_key,
+  model_name: options[:model_name],
+  environment: options[:environment],
+  max_iterations: options[:max_iterations],
+  max_depth: options[:max_depth],
+  iteration_timeout: options[:iteration_timeout],
+  generation_config: generation_config,
+  verbose: options[:verbose],
+  streaming: true,
+  logger: multi_logger
+}
+client_kwargs[:environment_options] = options[:environment_options] unless options[:environment_options].empty?
+
+begin
+  client = RubyRLM::Client.new(**client_kwargs)
+rescue => e
+  warn "Failed to initialize client: #{e.message}"
+  exit 1
+end
+
+puts "=> Starting query..."
+
+result = client.completion(prompt: prompt)
+
+puts "\n\n=== Final Result ==="
+puts result.response
+puts "\n[Usage Summary: #{result.usage_summary.total_tokens} tokens | Cached: #{result.usage_summary.cached_content_tokens} | Cost: $#{'%.4f' % result.usage_summary.compute_total_usd_cost}]"

data/lib/rubyrlm/backends/base.rb

@@ -0,0 +1,9 @@
+module RubyRLM
+  module Backends
+    class Base
+      def complete(messages:, generation_config: {})
+        raise NotImplementedError, "#{self.class} must implement #complete"
+      end
+    end
+  end
+end