boxcars 0.10.3 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e1257a3e6a1d95041ec565a3861f037a83b3d97f8854950fcd4d349f75c21d3
-  data.tar.gz: ca4b9b0e72f10964e221910f530bc5e2aaa361820e4ee817b232613f7af32147
+  metadata.gz: 91d8243a75d34977c339725329556f657706266926f307f86fb0051ed1ab13fb
+  data.tar.gz: da944b8f37d3d0a2f51f8ff2a42486b6ec7efbf8204f27dc0c323f3bbe28746e
 SHA512:
-  metadata.gz: 52667c34002a5a9c533dec1605f4242935bd16f69da9c717c12114d9a76b9b31395ae47ab3b26f4aa9eebe474a5a42487125eaaf774ce8690fc90a3c361ea907
-  data.tar.gz: fa3e322f2e50a450ea9feb39472c621b4917f38c4f69ca39571345597e0bab7d05decbf78faa82f5de7f0af218d4099eb600d2cf4a2d49392cae4fe4640fa106
+  metadata.gz: 5c0eaac090cdb3ae28856000fa3b57b850d942e9fb61fe3b86fbe2c2e6702c82dcc9016c09f577132ef997d328eaf1b9aab1a9808a195f3a99444f3709e47eeb
+  data.tar.gz: 725ca632b6281c7c76b8c83382bb0f0bf13dd0cecd39a575fd7ea5ba8d8f093faecb1a2e0facfeadbb63db89412361a84b6982a978af087e5a9de55428ad8d9f

data/.rubocop_todo.yml

@@ -51,11 +51,12 @@ Metrics/MethodLength:
     - 'lib/boxcars/engines.rb'
     - 'lib/boxcars/train/tool_train.rb'
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: Max, CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Exclude:
     - 'lib/boxcars/boxcar/json_engine_boxcar.rb'
+    - 'lib/boxcars/boxcar/sql_base.rb'
     - 'lib/boxcars/engine.rb'
     - 'lib/boxcars/engine/openai_compatible_chat_helpers.rb'
     - 'lib/boxcars/mcp/stdio_client.rb'

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+### Added
+
+- **`context:` parameter for ActiveRecord and SQL boxcars** — Pass runtime context (current user, tenant, permissions) into prompts so the LLM generates properly scoped queries. Available as a constructor keyword and an `attr_accessor` for per-request updates.
+- **Read-only mode for SQL boxcars** — `SQLBase` (and subclasses `SQLActiveRecord`, `SQLSequel`) now default to read-only, rejecting write SQL (`INSERT`, `UPDATE`, `DELETE`, `DROP`, etc.) with `Boxcars::SecurityError`. Pass `read_only: false` to allow writes, or provide an `approval_callback:` proc that receives the SQL string for custom approval logic.
+
 ## [0.10.3] - 2026-03-02
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    boxcars (0.10.3)
+    boxcars (0.10.4)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -68,6 +68,25 @@ All of these concepts are in a module named Boxcars:
 ## Security
 Currently, our system is designed for individuals who already possess administrative privileges for their project. It is likely possible to manipulate the system's prompts to carry out malicious actions, but if you already have administrative access, you can perform such actions without requiring boxcars in the first place.
 
+### Read-Only Defaults for Data Boxcars
+
+Both `ActiveRecord` and the SQL boxcars (`SQLActiveRecord`, `SQLSequel`) default to **read-only mode**, rejecting write operations (INSERT, UPDATE, DELETE, DROP, etc.) with a `Boxcars::SecurityError`. This prevents LLM-generated code or SQL from accidentally modifying your database.
+
+To allow writes, either disable read-only mode or provide an approval callback:
+
+```ruby
+# Option 1: disable read-only (use with caution)
+sql = Boxcars::SQLActiveRecord.new(read_only: false)
+
+# Option 2: approval callback for write SQL
+sql = Boxcars::SQLActiveRecord.new(approval_callback: ->(sql) { puts "Approve? #{sql}"; true })
+
+# Option 3: approval callback for ActiveRecord (receives change count and code)
+ar = Boxcars::ActiveRecord.new(approval_callback: ->(changes, code) { changes < 5 })
+```
+
+When an `approval_callback` is provided, read-only defaults to `false` so the callback can decide. You can combine `read_only: true` with a callback to enforce read-only regardless.
+
 *Note:* We are actively seeking ways to improve our system's ability to identify and prevent any nefarious attempts from occurring. If you have any suggestions or recommendations, please feel free to share them with us by either finding an existing issue or creating a new one and providing us with your feedback.
 
 ## Installation
@@ -196,11 +215,29 @@ Boxcars ships with high-leverage tools you can compose immediately, and you can
 - `GoogleSearch`: uses SERP API for live web lookup.
 - `WikipediaSearch`: uses Wikipedia API for fast factual retrieval.
 - `Calculator`: uses an engine to produce/execute Ruby math logic.
-- `SQL`: generates and executes SQL from prompts using your ActiveRecord connection.
-- `ActiveRecord`: generates and executes ActiveRecord code from prompts.
+- `SQL`: generates and executes SQL from prompts using your ActiveRecord connection. Read-only by default.
+- `ActiveRecord`: generates and executes ActiveRecord code from prompts. Read-only by default.
 - `Swagger`: consumes OpenAPI (YAML/JSON) to answer questions about and run against API endpoints. See [Swagger notebook examples](https://github.com/BoxcarsAI/boxcars/blob/main/notebooks/swagger_examples.ipynb).
 - `VectorStore` workflows: embed, persist, and retrieve context for RAG-like retrieval flows (see vector notebooks).
 
+#### Scoping ActiveRecord and SQL Queries with `context:`
+
+The `ActiveRecord` and `SQL` boxcars accept an optional `context:` parameter that injects runtime information (current user, tenant, permissions) into the LLM prompt so generated queries are properly scoped:
+
+```ruby
+ar = Boxcars::ActiveRecord.new(
+  models: [Ticket, Comment],
+  context: "The current user is User#42 (admin). Only return this user's records."
+)
+ar.run("How many open tickets do I have?")
+
+# Update context per-request
+ar.context = "The current user is User#99 (viewer)."
+ar.run("Show my recent comments")
+```
+
+When `context` is `nil` or blank, nothing extra is added to the prompt.
+
 ### Run a list of Boxcars
 ```ruby
 # run a Train for a calculator, and search using default Engine

data/UPGRADING.md

@@ -16,6 +16,22 @@ v1.0 is expected to:
 - Remove deprecated model aliases
 - Prefer explicit model names (with a small curated alias set)
 
+## SQL Boxcars Now Default to Read-Only (v0.10.x)
+
+`SQLBase`, `SQLActiveRecord`, and `SQLSequel` now default to **read-only mode**, matching the existing `ActiveRecord` boxcar behavior. LLM-generated write SQL (`INSERT`, `UPDATE`, `DELETE`, `DROP`, etc.) raises `Boxcars::SecurityError` unless explicitly allowed.
+
+If your app relies on SQL boxcars executing write statements, update your initialization:
+
+```ruby
+# Allow all writes (no approval gate)
+sql = Boxcars::SQLActiveRecord.new(read_only: false)
+
+# Or gate writes through a callback (read_only defaults to false when a callback is provided)
+sql = Boxcars::SQLActiveRecord.new(approval_callback: ->(sql) { your_approval_logic(sql) })
+```
+
+**Note:** The SQL approval callback receives a single `(sql)` argument (the SQL string), unlike the ActiveRecord callback which receives `(changes, code)`.
+
 ## Provider Model Refresh Notes (v0.10.x)
 
 - Cohere retired legacy `command-r*` model IDs. Boxcars now defaults Cohere to `command-a-03-2025`.

data/boxcars.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/boxcars/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "boxcars"
+  spec.version = Boxcars::VERSION
+  spec.authors = ["Francis Sullivan", "Tabrez Syed"]
+  spec.email = ["hi@boxcars.ai"]
+
+  spec.summary = "Boxcars is a gem that enables you to create new systems with AI composability. Inspired by python langchain."
+  spec.description = "You simply set an OpenAI key, give a number of Boxcars to a Train, and magic ensues when you run it."
+  spec.homepage = "https://github.com/BoxcarsAI/boxcars"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/BoxcarsAI/boxcars/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features|notebooks)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # runtime dependencies
+  # Provider/tooling gems are optional and loaded on use.
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/boxcars/boxcar/active_record.rb

@@ -8,7 +8,7 @@ module Boxcars
     # Default description for this boxcar.
     ARDESC = "useful for when you need to query a database for an application named %<name>s."
     LOCKED_OUT_MODELS = %w[ActiveRecord::SchemaMigration ActiveRecord::InternalMetadata ApplicationRecord].freeze
-    attr_accessor :connection, :requested_models, :read_only, :approval_callback, :code_only
+    attr_accessor :connection, :requested_models, :read_only, :approval_callback, :code_only, :context
     attr_reader :except_models
 
     # @param models [Array<ActiveRecord::Model>] The models to use for this boxcar. Will use all if nil.
@@ -17,7 +17,8 @@ module Boxcars
     # @param approval_callback [Proc] A function to call to approve changes. Defaults to nil.
     # @param kwargs [Hash] Any other keyword arguments. These can include:
     #   :name, :description, :prompt, :except_models, :top_k, :stop, :code_only and :engine
-    def initialize(models: nil, except_models: nil, read_only: nil, approval_callback: nil, **kwargs)
+    def initialize(models: nil, except_models: nil, read_only: nil, approval_callback: nil, context: nil, **kwargs)
+      @context = context
       Boxcars::OptionalDependency.require!(
         "activerecord",
         feature: "Boxcars::ActiveRecord",
@@ -35,7 +36,9 @@ module Boxcars
 
     # @return [Hash] The additional variables for this boxcar.
     def prediction_additional(_inputs)
-      { model_info: }.merge super
+      ctx = @context.to_s.strip
+      context_str = ctx.empty? ? "" : "\n\nAdditional context:\n#{ctx}"
+      { model_info:, context: context_str }.merge super
     end
 
     CTEMPLATE = [
@@ -57,7 +60,8 @@ module Boxcars
            "Pay attention to use only the attribute names that you can see in the model description.\n",
            "Do not make up variable or attribute names, and do not share variables between the code in ARChanges and ARCode\n",
            "Be careful to not query for attributes that do not exist, and to use the format specified above.\n",
-           "Finally, try not to use print or puts in your code"
+           "Finally, try not to use print or puts in your code",
+           "%<context>s"
           ),
       user("Question: %<question>s")
     ].freeze
@@ -280,7 +284,7 @@ module Boxcars
       @my_prompt ||= ConversationPrompt.new(
         conversation: @conversation,
         input_variables: [:question],
-        other_inputs: [:top_k, :model_info],
+        other_inputs: [:top_k, :model_info, :context],
         output_variables: [:answer])
     end
   end

data/lib/boxcars/boxcar/sql_base.rb

@@ -9,15 +9,25 @@ module Boxcars
     # Default description for this boxcar.
     SQLDESC = "useful for when you need to query a database for %<name>s."
     LOCKED_OUT_TABLES = %w[schema_migrations ar_internal_metadata].freeze
-    attr_accessor :connection, :the_tables
+    # SQL keywords that indicate a write operation.
+    WRITE_SQL_KEYWORDS = %w[INSERT UPDATE DELETE DROP ALTER CREATE TRUNCATE REPLACE MERGE UPSERT
+                            GRANT REVOKE LOCK CALL EXEC EXECUTE].freeze
+
+    attr_accessor :connection, :the_tables, :context, :read_only, :approval_callback
 
     # @param connection [ActiveRecord::Connection] or [Sequel Object] The SQL connection to use for this boxcar.
     # @param tables [Array<String>] The tables to use for this boxcar. Will use all if nil.
     # @param except_tables [Array<String>] The tables to exclude from this boxcar. Will exclude none if nil.
+    # @param read_only [Boolean] Whether to restrict to read-only SQL. Defaults to true unless approval_callback is given.
+    # @param approval_callback [Proc] A function to call to approve write SQL. Receives the SQL string. Defaults to nil.
     # @param kwargs [Hash] Any other keyword arguments to pass to the parent class. This can include
     #   :name, :description, :prompt, :top_k, :stop, and :engine
-    def initialize(connection: nil, tables: nil, except_tables: nil, **kwargs)
+    def initialize(connection: nil, tables: nil, except_tables: nil, context: nil, read_only: nil,
+                   approval_callback: nil, **kwargs)
+      @context = context
       @connection = connection
+      @approval_callback = approval_callback
+      @read_only = read_only.nil? ? !approval_callback : read_only
       check_tables(tables, except_tables)
       kwargs[:name] ||= "Database"
       kwargs[:description] ||= format(SQLDESC, name:)
@@ -29,7 +39,9 @@ module Boxcars
 
     # @return [Hash] The additional variables for this boxcar.
     def prediction_additional(_inputs)
-      { schema:, dialect: }.merge super
+      ctx = @context.to_s.strip
+      context_str = ctx.empty? ? "" : "\n\nAdditional context:\n#{ctx}"
+      { schema:, dialect:, context: context_str }.merge super
     end
 
     CTEMPLATE = [
@@ -46,12 +58,43 @@ module Boxcars
            "SQLQuery: 'SQL Query to run'\n",
            "SQLResult: 'Result of the SQLQuery'\n",
            "Answer: 'Final answer here'"),
-      syst("Only use the following tables:\n%<schema>s"),
+      syst("Only use the following tables:\n%<schema>s%<context>s"),
       user("Question: %<question>s")
     ].freeze
 
+    # @return [Boolean] Whether this boxcar is in read-only mode.
+    def read_only?
+      read_only
+    end
+
     private
 
+    # Check if a SQL statement is safe (read-only) to run.
+    # Strips string literals first to avoid false positives on values like 'DELETE ME'.
+    # @param sql [String] The SQL statement to check.
+    # @return [Boolean] true if the SQL appears to be a read-only statement.
+    def sql_safe_to_run?(sql)
+      without_strings = sql.gsub(/'([^'\\]*(\\.[^'\\]*)*)'/, "''")
+      upper = without_strings.upcase
+      WRITE_SQL_KEYWORDS.none? { |kw| upper.match?(/\b#{kw}\b/) }
+    end
+
+    # Check if the SQL is approved for execution.
+    # @param sql [String] The SQL statement to check.
+    # @return [Boolean] true if approved.
+    def approved?(sql)
+      return true if sql_safe_to_run?(sql)
+
+      if read_only?
+        Boxcars.error("Cannot execute write SQL in read-only mode: #{sql}", :red)
+        return false
+      end
+
+      return approval_callback.call(sql) if approval_callback.is_a?(Proc)
+
+      true
+    end
+
     def check_tables(rtables, exceptions)
       requested_tables = nil
       if rtables.is_a?(Array)
@@ -106,8 +149,12 @@ module Boxcars
       code = text[/^SQLQuery: (.*)/, 1]
       code = extract_code text.split('SQLQuery:').last.strip
       Boxcars.debug code, :yellow
+      raise Boxcars::SecurityError, "Permission to execute write SQL denied" unless approved?(code)
+
       output = clean_up_output(code)
       Result.new(status: :ok, answer: output, explanation: "Answer: #{output.to_json}", code:)
+    rescue Boxcars::SecurityError => e
+      raise e
     rescue StandardError => e
       Result.new(status: :error, answer: nil, explanation: "Error: #{e.message}", code:)
     end
@@ -130,7 +177,7 @@ module Boxcars
       @my_prompt ||= ConversationPrompt.new(
         conversation: @conversation,
         input_variables: [:question],
-        other_inputs: [:top_k, :dialect, :schema],
+        other_inputs: [:top_k, :dialect, :schema, :context],
         output_variables: [:answer])
     end
   end

data/lib/boxcars/version.rb

@@ -2,5 +2,5 @@
 
 module Boxcars
   # The current version of the gem.
-  VERSION = "0.10.3"
+  VERSION = "0.10.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boxcars
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.10.4
 platform: ruby
 authors:
 - Francis Sullivan
@@ -36,6 +36,8 @@ files:
 - USER_CONTEXT_GUIDE.md
 - bin/console
 - bin/setup
+- boxcars-0.10.3.gem
+- boxcars.gemspec
 - lib/boxcars.rb
 - lib/boxcars/boxcar.rb
 - lib/boxcars/boxcar/active_record.rb