rlm-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e52a1acbaea2c8a9955a4a75058e6e4d4780c16b327a9b28b68bb620c1ddb406
+  data.tar.gz: 75c6d410914cd74a4d949658acf9d2c747cf0a87b9ad4c43c80d6a7cbf9a417f
+SHA512:
+  metadata.gz: 9e5a488efd6e4ddbd0bb7e9b6df4df2624dd0c127244069120cc78b4e260432fd2e66453c2526734a5114f2c2cdb13220bfaffdc6cca3876282698b77a1c1c92
+  data.tar.gz: ee9901f38ffdc87df153319c7a723b801e441da54696118512dee03d5dcef22ccd1adb13f17db6bb785c99aeaa95b315bcd6bd017c2b3051928ab7c33c34d64f

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-12
+
+Skeleton release. Establishes the public types, configuration surface, sandbox
+interface, and error hierarchy that the runtime milestone will build on.
+`RLM::Predict#call` raises `NotImplementedError` until the runtime loop lands in
+v0.2.
+
+### Added
+
+- `RLM::VERSION`, `RLM.configure`, `RLM.config`, `RLM.reset_configuration!`.
+- Error hierarchy (`RLM::Error`, `ConfigurationError`, `BudgetExceededError`, `SandboxError`,
+  `ValidationError`, `ProviderError`, `ToolError`, `ParseError`, `NoProgressError`).
+- `RLM::Limits` with PRD defaults and validation.
+- `RLM::File` with `from_path`, `from_text`, `from_io`, and `from_active_storage` constructors.
+- `RLM::Context` with file handles and sandbox-safe manifest.
+- `RLM::Trace` with typed events, NDJSON/JSON export, and basic counters.
+- `RLM::Result` with the documented status enum and predicates.
+- `RLM::Sandbox::Base` interface plus `Sandbox::ExecutionResult` and `Sandbox::Mock` for tests.
+- `RLM::Tool` base class with category DSL.
+- `RLM::Predict` skeleton (`#call` raises `NotImplementedError` until the runtime loop lands).
+
+### Not yet implemented (tracked for v0.2+)
+
+- Runtime execution loop, code extractor, runtime bridge, recursive `predict(...)`.
+- RubyLLM root/sub-LM adapters.
+- dspy.rb signature adapter and output validation.
+- `RLM::Sandbox::Subprocess` backend.
+- Rails integration (Railtie, generator, migrations, ActiveStorage adapter).
+- PDF/CSV/Directory skills.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Paluy
+
+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,233 @@
+# RLM.rb
+
+[![Gem Version](https://badge.fury.io/rb/rlm-rb.svg)](https://badge.fury.io/rb/rlm-rb)
+[![CI](https://github.com/dpaluy/rlm/actions/workflows/ci.yml/badge.svg)](https://github.com/dpaluy/rlm/actions/workflows/ci.yml)
+
+Recursive Language Models for Ruby and Rails.
+
+RLM.rb is a Ruby/Rails-native runtime for typed, sandboxed, auditable AI jobs over large application context.
+It depends on [RubyLLM](https://github.com/crmne/ruby_llm) for provider access and [dspy.rb](https://github.com/vicentereig/dspy.rb)
+for typed signatures, and adds the missing recursive execution runtime: sandbox, REPL loop, file and context mounting,
+recursive sub-LM calls, typed final output, budget controls, and durable trajectories.
+
+> **Status: v0.1.0 skeleton.** Core types are in place. The runtime loop, provider adapters, signature adapter,
+> subprocess sandbox, and Rails integration are not yet implemented and are tracked in the v0.2 milestone in
+> `docs/prd.md`. `RLM::Predict#call` raises `NotImplementedError` in this release.
+
+## Why
+
+1. Large context breaks simple prompting.
+2. Manual chunking and summarization are brittle.
+3. Hand-rolled agent loops have unclear state, unclear cost, and poor auditability.
+
+RLM.rb replaces those with a bounded Ruby runtime where the model explores context programmatically, calls smaller
+typed LLM functions only when needed, and returns validated Ruby objects with a full execution trace.
+
+## Install
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "rlm-rb"
+```
+
+Or install directly:
+
+```bash
+gem install rlm-rb
+```
+
+## Configuration
+
+```ruby
+RLM.configure do |config|
+  # Provider adapters land in the next milestone.
+  # config.root_lm = RubyLLM.chat(model: "anthropic/claude-sonnet-4")
+  # config.sub_lm  = RubyLLM.chat(model: "openai/gpt-5-mini")
+
+  config.sandbox = RLM::Sandbox::Mock.new
+
+  config.default_limits = RLM::Limits.new(
+    max_iterations: 8,
+    max_llm_calls: 25,
+    max_tool_calls: 20,
+    max_runtime_seconds: 120,
+    max_cost_cents: 100,
+    max_recursion_depth: 1
+  )
+end
+```
+
+## Intended API (not yet executable)
+
+```ruby
+class InvoiceExtraction < DSPy::Signature
+  description "Extract normalized invoice fields from a vendor invoice."
+
+  input do
+    const :invoice_pdf, RLM::File
+    const :vendor_id, Integer
+  end
+
+  output do
+    const :vendor_name, String
+    const :invoice_number, String
+    const :total_cents, Integer
+    const :confidence, Float
+    const :needs_review, T::Boolean
+  end
+end
+
+result = RLM.predict(
+  InvoiceExtraction,
+  input: {
+    invoice_pdf: RLM::File.from_path("invoice.pdf"),
+    vendor_id: 123
+  },
+  max_iterations: 10,
+  max_llm_calls: 30,
+  max_cost_cents: 150
+)
+
+result.output           # typed object
+result.trace            # readable steps, llm calls, tool calls
+result.cost_cents       # accumulated cost
+result.status           # :completed, :needs_review, :budget_exceeded, ...
+```
+
+## What's in this skeleton today
+
+| Component | Status |
+|-----------|--------|
+| `RLM.configure` / `RLM.config` | Ready |
+| `RLM::Limits` with PRD defaults | Ready |
+| `RLM::File` (path / text / io / ActiveStorage blob) | Ready |
+| `RLM::Context` with sandbox-safe manifest | Ready |
+| `RLM::Trace` with NDJSON / JSON export | Ready |
+| `RLM::Result` with full status enum | Ready |
+| `RLM::Sandbox::Base` interface + `Mock` backend | Ready |
+| `RLM::Tool` base class with category DSL | Ready |
+| Error hierarchy | Ready |
+| `RLM::Predict` skeleton | Stub, raises on `#call` |
+| RubyLLM provider adapter | Not yet |
+| dspy.rb signature adapter | Not yet |
+| Runtime execution loop + recursive `predict` | Not yet |
+| `RLM::Sandbox::Subprocess` | Not yet |
+| Rails Railtie, generator, migrations, ActiveStorage adapter | Not yet |
+
+See `docs/prd.md` for the full product spec and v0.2 milestone list.
+
+## Rails setup (intended, lands in v0.3)
+
+The Rails integration is not yet implemented, but the intended setup is:
+
+```ruby
+# config/initializers/rlm.rb
+RLM.configure do |config|
+  config.root_lm = RubyLLM.chat(model: Rails.application.credentials.dig(:rlm, :root_model))
+  config.sub_lm  = RubyLLM.chat(model: Rails.application.credentials.dig(:rlm, :sub_model))
+
+  config.sandbox = RLM::Sandbox::Subprocess.new   # development
+  # config.sandbox = RLM::Sandbox::Docker.new     # production (v0.4)
+
+  config.cache  = Rails.cache
+  config.logger = Rails.logger
+
+  config.default_limits = RLM::Limits.new(
+    max_iterations: 8,
+    max_llm_calls: 25,
+    max_tool_calls: 20,
+    max_runtime_seconds: 120,
+    max_cost_cents: 100,
+    max_recursion_depth: 1
+  )
+end
+```
+
+API keys belong in `Rails.application.credentials`, not env files. Per RubyLLM's
+[Rails integration](https://rubyllm.com/rails/), provider keys are picked up automatically when set there.
+
+## Error handling
+
+All RLM errors inherit from `RLM::Error`. Rescue the parent to catch every variant, or rescue specific classes
+to handle distinct failure modes.
+
+```ruby
+begin
+  result = RLM.predict(InvoiceExtraction, input: { invoice_pdf: file })
+rescue RLM::BudgetExceededError => e
+  # Hard limits hit: max_iterations, max_llm_calls, max_cost_cents, max_runtime_seconds.
+  logger.warn("RLM budget exceeded: #{e.message}")
+rescue RLM::ValidationError => e
+  # Final output failed signature validation after repair attempts were exhausted.
+  invoice.update!(needs_review: true, review_reasons: ["validation_failed"])
+rescue RLM::SandboxError => e
+  # Generated code violated sandbox policy or the sandbox backend crashed.
+  raise
+rescue RLM::ProviderError => e
+  # RubyLLM provider call failed (transient retries already exhausted).
+  raise
+rescue RLM::ToolError => e
+  # A registered tool raised an exception or was called with invalid input.
+  raise
+rescue RLM::ParseError => e
+  # Root LM response could not be parsed into <rlm-code>/<rlm-final>.
+  raise
+rescue RLM::NoProgressError => e
+  # The model emitted no new progress across iterations.
+  raise
+rescue RLM::ConfigurationError => e
+  # Missing signature, missing root LM, invalid sandbox, etc.
+  raise
+rescue RLM::Error => e
+  # Catch-all for any other RLM-originated failure.
+  raise
+end
+```
+
+Soft failures land on `result.status` instead of raising. Inspect `result.success?`, `result.needs_review?`,
+`result.failed?`, and `result.validation_errors` to branch.
+
+| Status | Predicate | Meaning |
+|--------|-----------|---------|
+| `:completed` | `success?` | Output valid, ready to use. |
+| `:needs_review` | `needs_review?` | Output present but validation flagged it or budget policy is `:needs_review`. |
+| `:failed_validation` | `failed?` | Output invalid after repair attempts. |
+| `:budget_exceeded` | `failed?` | Hit a hard limit and policy is `:fail`. |
+| `:sandbox_error` | `failed?` | Sandbox violation or crash. |
+| `:tool_error` | `failed?` | Tool raised or returned invalid output. |
+| `:provider_error` | `failed?` | RubyLLM provider failure. |
+| `:aborted` | `failed?` | Run cancelled by caller. |
+
+## Production safety (when the runtime loop ships)
+
+- The subprocess sandbox planned for v0.2 is intended for local development and low-risk internal use.
+- Production deployments should use the Docker sandbox (v0.4) or a remote isolated runner.
+- Generated code must not execute inside the host Ruby process. The codebase will hold this invariant.
+- Mounted files are data, not instructions. Prompt injection mitigations are documented in the PRD.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test       # 58 runs / 139 assertions / 0 failures
+bundle exec rubocop         # lint
+bundle exec rake            # test + rubocop
+```
+
+## Contributing
+
+Issues and pull requests welcome at https://github.com/dpaluy/rlm.
+
+## API reference
+
+RLM.rb sits on top of two upstream libraries. When you need provider or signature details, go to source:
+
+- [RubyLLM](https://github.com/crmne/ruby_llm), [Rails integration guide](https://rubyllm.com/rails/) for provider/chat/file API.
+- [dspy.rb](https://github.com/vicentereig/dspy.rb), [Signatures guide](https://vicentereig.github.io/dspy.rb/core-concepts/signatures/) for typed input/output contracts.
+- The [Recursive Language Models](https://github.com/alexzhang13/rlm) reference implementation and the
+  [DSPy RLM module](https://dspy.ai/api/modules/RLM/) for the underlying idea.
+
+## License
+
+MIT, see `LICENSE.txt`.

data/lib/rlm/config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RLM
+  class Config
+    attr_accessor :root_lm, :sub_lm, :sandbox, :cache, :default_limits, :trace_store
+    attr_writer :logger
+
+    def initialize
+      @root_lm = nil
+      @sub_lm = nil
+      @sandbox = Sandbox::Mock.new
+      @cache = nil
+      @default_limits = Limits.new
+      @trace_store = nil
+      @logger = nil
+    end
+
+    def logger
+      @logger ||= default_logger
+    end
+
+    private
+
+    def default_logger
+      if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+        ::Rails.logger
+      else
+        require "logger"
+        ::Logger.new($stderr)
+      end
+    end
+  end
+end

data/lib/rlm/context.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RLM
+  class Context
+    SANDBOX_FILES_ROOT = "/mnt/rlm/files"
+
+    attr_reader :inputs, :files
+
+    def initialize(inputs: {}, files: [])
+      @inputs = inputs.dup.freeze
+      @files = Array(files).dup.freeze
+      @handles = build_handles(@files)
+    end
+
+    def manifest
+      {
+        files: @files.map do |file|
+          handle = handle_for(file)
+          {
+            handle: handle,
+            filename: file.filename,
+            content_type: file.content_type,
+            size_bytes: file.size_bytes,
+            sandbox_path: ::File.join(SANDBOX_FILES_ROOT, file.filename)
+          }
+        end,
+        inputs: serializable_inputs
+      }
+    end
+
+    def file_for(handle)
+      @handles[handle]
+    end
+
+    def handle_for(file)
+      @handles.key(file)
+    end
+
+    private
+
+    def build_handles(files)
+      files.each_with_index.to_h { |file, i| ["file_#{i + 1}", file] }
+    end
+
+    def serializable_inputs
+      @inputs.each_with_object({}) do |(key, value), acc|
+        acc[key] = value.is_a?(File) ? { file_handle: handle_for(value) } : value
+      end
+    end
+  end
+end

data/lib/rlm/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RLM
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class BudgetExceededError < Error; end
+  class SandboxError < Error; end
+  class ValidationError < Error; end
+  class ProviderError < Error; end
+  class ToolError < Error; end
+  class ParseError < Error; end
+  class NoProgressError < Error; end
+end

data/lib/rlm/file.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RLM
+  class File
+    CONTENT_TYPES = {
+      ".txt" => "text/plain",
+      ".md" => "text/markdown",
+      ".markdown" => "text/markdown",
+      ".csv" => "text/csv",
+      ".json" => "application/json",
+      ".pdf" => "application/pdf",
+      ".html" => "text/html",
+      ".htm" => "text/html",
+      ".xml" => "application/xml",
+      ".yml" => "application/yaml",
+      ".yaml" => "application/yaml",
+      ".rb" => "application/x-ruby"
+    }.freeze
+
+    DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+    attr_reader :filename, :content_type, :size_bytes, :source
+
+    def self.from_path(path)
+      pathname = Pathname.new(path)
+      raise ArgumentError, "File not found: #{path}" unless pathname.file?
+
+      new(
+        filename: pathname.basename.to_s,
+        content_type: content_type_for(pathname.extname),
+        size_bytes: pathname.size,
+        source: { kind: :path, path: pathname.expand_path.to_s }
+      )
+    end
+
+    def self.from_text(filename, text)
+      raise ArgumentError, "filename is required" if filename.to_s.empty?
+
+      new(
+        filename: filename,
+        content_type: content_type_for(::File.extname(filename)),
+        size_bytes: text.bytesize,
+        source: { kind: :text, text: text }
+      )
+    end
+
+    def self.from_io(io, filename:, content_type: nil)
+      raise ArgumentError, "filename is required" if filename.to_s.empty?
+
+      data = io.read
+      new(
+        filename: filename,
+        content_type: content_type || content_type_for(::File.extname(filename)),
+        size_bytes: data.bytesize,
+        source: { kind: :io, text: data }
+      )
+    end
+
+    def self.from_active_storage(blob)
+      raise ArgumentError, "blob cannot be nil" if blob.nil?
+
+      new(
+        filename: blob.filename.to_s,
+        content_type: blob.content_type,
+        size_bytes: blob.byte_size,
+        source: { kind: :active_storage, blob: blob }
+      )
+    end
+
+    def self.content_type_for(extname)
+      CONTENT_TYPES[extname.to_s.downcase] || DEFAULT_CONTENT_TYPE
+    end
+
+    def initialize(filename:, content_type:, size_bytes:, source:)
+      @filename = filename
+      @content_type = content_type
+      @size_bytes = size_bytes
+      @source = source
+    end
+
+    def read
+      case source[:kind]
+      when :path then ::File.read(source[:path])
+      when :text, :io then source[:text]
+      when :active_storage then source[:blob].download
+      else raise SandboxError, "Unknown file source kind: #{source[:kind].inspect}"
+      end
+    end
+
+    def to_h
+      {
+        filename: filename,
+        content_type: content_type,
+        size_bytes: size_bytes,
+        source_kind: source[:kind]
+      }
+    end
+  end
+end

data/lib/rlm/limits.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RLM
+  class Limits
+    INTEGER_DEFAULTS = {
+      max_iterations: 8,
+      max_llm_calls: 25,
+      max_sub_lm_calls: 20,
+      max_tool_calls: 20,
+      max_runtime_seconds: 120,
+      max_cost_cents: 100,
+      max_input_bytes: 25 * 1024 * 1024,
+      max_output_bytes: 1 * 1024 * 1024,
+      max_stdout_bytes: 256 * 1024,
+      max_files: 50,
+      max_file_bytes: 25 * 1024 * 1024,
+      max_recursion_depth: 1
+    }.freeze
+
+    BUDGET_POLICIES = %i[fail return_partial needs_review].freeze
+    DEFAULT_POLICY = :needs_review
+
+    DEFAULTS = INTEGER_DEFAULTS.merge(on_budget_exceeded: DEFAULT_POLICY).freeze
+
+    attr_reader(*DEFAULTS.keys)
+
+    def initialize(**overrides)
+      unknown = overrides.keys - DEFAULTS.keys
+      raise ArgumentError, "Unknown limit keys: #{unknown.join(", ")}" if unknown.any?
+
+      DEFAULTS.merge(overrides).each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+      validate!
+    end
+
+    def merge(**overrides)
+      self.class.new(**to_h, **overrides)
+    end
+
+    def to_h
+      DEFAULTS.keys.to_h { |k| [k, public_send(k)] }
+    end
+
+    private
+
+    def validate!
+      INTEGER_DEFAULTS.each_key do |key|
+        value = public_send(key)
+        next if value.is_a?(Integer) && value >= 0
+
+        raise ArgumentError, "#{key} must be a non-negative integer, got #{value.inspect}"
+      end
+
+      return if BUDGET_POLICIES.include?(on_budget_exceeded)
+
+      raise ArgumentError,
+            "on_budget_exceeded must be one of #{BUDGET_POLICIES.inspect}, got #{on_budget_exceeded.inspect}"
+    end
+  end
+end

data/lib/rlm/predict.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RLM
+  class Predict
+    attr_reader :signature, :lm, :sub_lm, :tools, :skills, :sandbox,
+                :limits, :trace_store, :validators
+
+    def initialize(
+      signature,
+      lm: nil,
+      sub_lm: nil,
+      tools: [],
+      skills: [],
+      sandbox: nil,
+      limits: nil,
+      trace_store: nil,
+      validators: []
+    )
+      raise ConfigurationError, "signature is required" if signature.nil?
+
+      @signature = signature
+      @lm = lm || RLM.config.root_lm
+      @sub_lm = sub_lm || RLM.config.sub_lm
+      @tools = Array(tools)
+      @skills = Array(skills)
+      @sandbox = sandbox || RLM.config.sandbox
+      @limits = limits || RLM.config.default_limits
+      @trace_store = trace_store || RLM.config.trace_store
+      @validators = Array(validators)
+    end
+
+    def call(_input = {})
+      raise NotImplementedError,
+            "RLM::Predict#call is not implemented in v0.1.0. " \
+            "The runtime loop, RubyLLM root/sub-LM adapters, and dspy.rb " \
+            "signature adapter land in v0.2. The skeleton exists so that " \
+            "downstream code can wire up signatures, tools, sandboxes, and " \
+            "limits against a stable API."
+    end
+  end
+end

data/lib/rlm/result.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RLM
+  class Result
+    STATUSES = %i[
+      completed
+      needs_review
+      failed_validation
+      budget_exceeded
+      sandbox_error
+      tool_error
+      provider_error
+      aborted
+    ].freeze
+
+    FAILURE_STATUSES = %i[
+      failed_validation
+      budget_exceeded
+      sandbox_error
+      tool_error
+      provider_error
+      aborted
+    ].freeze
+
+    attr_reader :output, :trace, :status, :error, :cost_cents,
+                :duration_ms, :llm_calls, :iterations, :validation_errors
+
+    def initialize(
+      trace:,
+      status:,
+      output: nil,
+      error: nil,
+      cost_cents: 0,
+      duration_ms: 0,
+      llm_calls: 0,
+      iterations: 0,
+      validation_errors: []
+    )
+      raise ArgumentError, "Unknown status: #{status.inspect}" unless STATUSES.include?(status)
+
+      @output = output
+      @trace = trace
+      @status = status
+      @error = error
+      @cost_cents = cost_cents
+      @duration_ms = duration_ms
+      @llm_calls = llm_calls
+      @iterations = iterations
+      @validation_errors = validation_errors
+    end
+
+    def success?
+      status == :completed
+    end
+
+    def needs_review?
+      status == :needs_review
+    end
+
+    def failed?
+      FAILURE_STATUSES.include?(status)
+    end
+
+    def to_h
+      {
+        output: output,
+        status: status,
+        error: error&.message,
+        cost_cents: cost_cents,
+        duration_ms: duration_ms,
+        llm_calls: llm_calls,
+        iterations: iterations,
+        validation_errors: validation_errors,
+        trace_id: trace&.id
+      }
+    end
+  end
+end

data/lib/rlm/sandbox/execution_result.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RLM
+  module Sandbox
+    class ExecutionResult
+      STATUSES = %i[ok error timeout budget_exceeded].freeze
+
+      attr_reader :stdout, :stderr, :exit_code, :duration_ms, :events, :status, :error
+
+      def initialize(
+        stdout: "",
+        stderr: "",
+        exit_code: 0,
+        duration_ms: 0,
+        events: [],
+        status: :ok,
+        error: nil
+      )
+        raise ArgumentError, "Unknown status: #{status.inspect}" unless STATUSES.include?(status)
+
+        @stdout = stdout
+        @stderr = stderr
+        @exit_code = exit_code
+        @duration_ms = duration_ms
+        @events = events
+        @status = status
+        @error = error
+      end
+
+      def ok?
+        status == :ok
+      end
+
+      def to_h
+        {
+          status: status,
+          exit_code: exit_code,
+          duration_ms: duration_ms,
+          stdout: stdout,
+          stderr: stderr,
+          events: events,
+          error: error&.message
+        }
+      end
+    end
+  end
+end

data/lib/rlm/sandbox/mock.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RLM
+  module Sandbox
+    class Mock < Base
+      attr_reader :executed_code, :context, :tools, :skills, :runtime_bridge
+
+      def initialize(handler: nil)
+        super()
+        @handler = handler
+        @executed_code = []
+        @prepared = false
+      end
+
+      def prepared?
+        @prepared
+      end
+
+      def prepare(context:, tools:, skills:, runtime_bridge:)
+        @prepared = true
+        @context = context
+        @tools = tools
+        @skills = skills
+        @runtime_bridge = runtime_bridge
+        ExecutionResult.new(status: :ok)
+      end
+
+      def exec(code)
+        raise SandboxError, "Sandbox not prepared" unless @prepared
+
+        @executed_code << code
+        return ExecutionResult.new(status: :ok, stdout: "") if @handler.nil?
+
+        result = @handler.call(code, context: @context, bridge: @runtime_bridge)
+        result.is_a?(ExecutionResult) ? result : ExecutionResult.new(stdout: result.to_s)
+      end
+
+      def cleanup
+        @prepared = false
+        @executed_code.clear
+        @context = nil
+        @tools = nil
+        @skills = nil
+        @runtime_bridge = nil
+      end
+    end
+  end
+end

data/lib/rlm/sandbox.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RLM
+  module Sandbox
+    class Base
+      def prepare(context:, tools:, skills:, runtime_bridge:)
+        raise NotImplementedError, "#{self.class} must implement #prepare"
+      end
+
+      def exec(code)
+        raise NotImplementedError, "#{self.class} must implement #exec"
+      end
+
+      def cleanup
+        raise NotImplementedError, "#{self.class} must implement #cleanup"
+      end
+    end
+  end
+end

data/lib/rlm/tool.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RLM
+  class Tool
+    CATEGORIES = %i[read_only write_requires_approval write_allowed dangerous_disabled].freeze
+
+    class << self
+      def description(text = nil)
+        return @description if text.nil?
+
+        @description = text
+      end
+
+      def category(value = nil)
+        return @category || :read_only if value.nil?
+        raise ArgumentError, "Unknown category: #{value.inspect}" unless CATEGORIES.include?(value)
+
+        @category = value
+      end
+
+      def registry_name
+        @registry_name ||= name.to_s.split("::").last
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@description, nil)
+        subclass.instance_variable_set(:@category, nil)
+      end
+    end
+
+    def call(**kwargs)
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+  end
+end

data/lib/rlm/trace.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+module RLM
+  class Trace
+    EVENT_TYPES = %i[
+      run_started
+      root_prompt_created
+      root_lm_called
+      code_generated
+      code_executed
+      file_read
+      tool_called
+      sub_lm_called
+      validation_attempted
+      validation_failed
+      budget_checked
+      run_completed
+      run_failed
+    ].freeze
+
+    attr_reader :id, :events, :started_at
+
+    def initialize(id: SecureRandom.uuid, clock: Time.method(:now))
+      @id = id
+      @events = []
+      @clock = clock
+      @started_at = clock.call
+    end
+
+    def record(type, payload = {})
+      raise ArgumentError, "Unknown trace event type: #{type.inspect}" unless EVENT_TYPES.include?(type)
+
+      events << { type: type, payload: payload, at: @clock.call.iso8601(6) }
+      self
+    end
+
+    def steps
+      events.select { |e| %i[code_generated code_executed].include?(e[:type]) }
+    end
+
+    def llm_calls
+      events.select { |e| %i[root_lm_called sub_lm_called].include?(e[:type]) }
+    end
+
+    def tool_calls
+      events.select { |e| e[:type] == :tool_called }
+    end
+
+    def files_read
+      events.select { |e| e[:type] == :file_read }
+    end
+
+    def validation_errors
+      events.select { |e| e[:type] == :validation_failed }
+    end
+
+    def cost_cents
+      llm_calls.sum { |e| e[:payload][:cost_cents].to_i }
+    end
+
+    def duration_ms
+      return 0 if events.empty?
+
+      ((@clock.call - @started_at) * 1000).to_i
+    end
+
+    def to_h
+      {
+        id: id,
+        started_at: started_at.iso8601(6),
+        events: events
+      }
+    end
+
+    def to_json(*)
+      JSON.generate(to_h, *)
+    end
+
+    def to_ndjson
+      events.map { |e| JSON.generate(e) }.join("\n")
+    end
+  end
+end

data/lib/rlm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RLM
+  VERSION = "0.1.0"
+end

data/lib/rlm.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "rlm/version"
+require_relative "rlm/errors"
+require_relative "rlm/limits"
+require_relative "rlm/file"
+require_relative "rlm/context"
+require_relative "rlm/trace"
+require_relative "rlm/result"
+require_relative "rlm/sandbox"
+require_relative "rlm/sandbox/execution_result"
+require_relative "rlm/sandbox/mock"
+require_relative "rlm/tool"
+require_relative "rlm/config"
+require_relative "rlm/predict"
+
+module RLM
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_configuration!
+      @config = nil
+    end
+
+    def predict(signature, input:, **)
+      Predict.new(signature, **).call(input)
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: rlm-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Paluy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: |-
+  RLM.rb is a Ruby/Rails-native runtime for Recursive Language Models. It runs bounded, typed, auditable AI jobs
+  over large files, records, and application context. RLM.rb uses RubyLLM for provider access and dspy.rb for
+  typed signatures, and adds the missing recursive execution runtime: sandbox, REPL loop, file/context mounting,
+  recursive sub-LM calls, typed final output, budget controls, and durable trajectories.
+email:
+- dpaluy@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rlm.rb
+- lib/rlm/config.rb
+- lib/rlm/context.rb
+- lib/rlm/errors.rb
+- lib/rlm/file.rb
+- lib/rlm/limits.rb
+- lib/rlm/predict.rb
+- lib/rlm/result.rb
+- lib/rlm/sandbox.rb
+- lib/rlm/sandbox/execution_result.rb
+- lib/rlm/sandbox/mock.rb
+- lib/rlm/tool.rb
+- lib/rlm/trace.rb
+- lib/rlm/version.rb
+homepage: https://github.com/dpaluy/rlm-rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dpaluy/rlm-rb
+  changelog_uri: https://github.com/dpaluy/rlm-rb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dpaluy/rlm-rb/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby/Rails-native runtime for typed, sandboxed, auditable AI jobs over large
+  application context.
+test_files: []