boxcars 0.2.0 → 0.2.2

data/lib/boxcars/boxcar/sql.rb

@@ -6,21 +6,21 @@ module Boxcars
   class SQL < EngineBoxcar
     # the description of this engine 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
 
     # @param connection [ActiveRecord::Connection] The SQL connection to use for this boxcar.
-    # @param engine [Boxcars::Engine] The engine to user for this boxcar. Can be inherited from a train if nil.
+    # @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 kwargs [Hash] Any other keyword arguments to pass to the parent class. This can include
-    #   :name, :description, :prompt and :top_k
-    def initialize(connection: nil, engine: nil, **kwargs)
+    #   :name, :description, :prompt, :top_k, :stop, and :engine
+    def initialize(connection: nil, tables: nil, except_tables: nil, **kwargs)
       @connection = connection || ::ActiveRecord::Base.connection
-      the_prompt = kwargs[prompt] || my_prompt
-      kwargs[:stop] ||= ["Answer:"]
-      name = kwargs[:name] || "database"
-      super(name: name,
-            description: kwargs[:description] || format(SQLDESC, name: name),
-            engine: engine,
-            prompt: the_prompt)
+      check_tables(tables, except_tables)
+      kwargs[:name] ||= "Database"
+      kwargs[:description] ||= format(SQLDESC, name: name)
+      kwargs[:prompt] ||= my_prompt
+      super(**kwargs)
     end
 
     # @return Hash The additional variables for this boxcar.
@@ -30,6 +30,19 @@ module Boxcars
 
     private
 
+    def check_tables(rtables, exceptions)
+      if rtables.is_a?(Array) && tables.length.positive?
+        @requested_tables = rtables
+        all_tables = tables
+        rtables.each do |t|
+          raise ArgumentError, "table #{t} needs to be an Active Record model" unless all_tables.include?(t)
+        end
+      elsif rtables
+        raise ArgumentError, "tables needs to be an array of Strings"
+      end
+      @except_models = LOCKED_OUT_TABLES + exceptions.to_a
+    end
+
     def tables
       connection&.tables
     end
@@ -49,14 +62,22 @@ module Boxcars
       connection.class.name.split("::").last.sub("Adapter", "")
     end
 
-    def get_embedded_sql_answer(text)
-      code = text[/^SQLQuery: (.*)/, 1]
-      Boxcars.debug code, :yellow
-      output = connection.exec_query(code)
+    def clean_up_output(output)
+      output = output.as_json if output.is_a?(::ActiveRecord::Result)
       output = 0 if output.is_a?(Array) && output.empty?
       output = output.first if output.is_a?(Array) && output.length == 1
       output = output[output.keys.first] if output.is_a?(Hash) && output.length == 1
-      "Answer: #{output.to_json}"
+      output = output.as_json if output.is_a?(::ActiveRecord::Relation)
+      output
+    end
+
+    def get_embedded_sql_answer(text)
+      code = text[/^SQLQuery: (.*)/, 1]
+      Boxcars.debug code, :yellow
+      output = clean_up_output(connection.exec_query(code))
+      Result.new(status: :ok, answer: output, explanation: "Answer: #{output.to_json}", code: code)
+    rescue StandardError => e
+      Result.new(status: :error, answer: nil, explanation: "Error: #{e.message}", code: code)
     end
 
     def get_answer(text)
@@ -64,43 +85,38 @@ module Boxcars
       when /^SQLQuery:/
         get_embedded_sql_answer(text)
       when /^Answer:/
-        text
+        Result.from_text(text)
       else
-        raise Boxcars::Error "Unknown format from engine: #{text}"
+        Result.from_error("Try answering again. Expected your answer to start with 'SQLQuery:'. You gave me:\n#{text}")
       end
     end
 
-    TEMPLATE = <<~IPT
-      Given an input question, first create a syntactically correct %<dialect>s query to run,
-      then look at the results of the query and return the answer. Unless the user specifies
-      in his question a specific number of examples he wishes to obtain, always limit your query
-      to at most %<top_k>s results using a LIMIT clause. You can order the results by a relevant column
-      to return the most interesting examples in the database.
-
-      Never query for all the columns from a specific table, only ask for a the few relevant columns given the question.
-
-      Pay attention to use only the column names that you can see in the schema description. Be careful to not query for columns that do not exist.
-      Also, pay attention to which column is in which table.
-
-      Use the following format:
-      Question: "Question here"
-      SQLQuery: "SQL Query to run"
-      SQLResult: "Result of the SQLQuery"
-      Answer: "Final answer here"
-
-      Only use the following tables:
-      %<schema>s
-
-      Question: %<question>s
-    IPT
+    CTEMPLATE = [
+      syst("Given an input question, first create a syntactically correct %<dialect>s SQL query to run, ",
+           "then look at the results of the query and return the answer. Unless the user specifies ",
+           "in her question a specific number of examples he wishes to obtain, always limit your query ",
+           "to at most %<top_k>s results using a LIMIT clause. You can order the results by a relevant column ",
+           "to return the most interesting examples in the database.\n",
+           "Never query for all the columns from a specific table, only ask for the elevant columns given the question.\n",
+           "Pay attention to use only the column names that you can see in the schema description. Be careful to ",
+           "not query for columns that do not exist. Also, pay attention to which column is in which table."),
+      syst("Use the following format:\n",
+           "Question: 'Question here'\n",
+           "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"),
+      user("Question: %<question>s")
+    ].freeze
 
     # The prompt to use for the engine.
     def my_prompt
-      @my_prompt ||= Prompt.new(
+      @conversation ||= Conversation.new(lines: CTEMPLATE)
+      @my_prompt ||= ConversationPrompt.new(
+        conversation: @conversation,
         input_variables: [:question],
         other_inputs: [:top_k, :dialect, :table_info],
-        output_variables: [:answer],
-        template: TEMPLATE)
+        output_variables: [:answer])
     end
   end
 end

data/lib/boxcars/boxcar.rb

@@ -62,16 +62,42 @@ module Boxcars
     # you can pass one or the other, but not both.
     # @return [String] The answer to the question.
     def run(*args, **kwargs)
+      rv = conduct(*args, **kwargs)
+      rv.is_a?(Result) ? rv.to_answer : rv
+    end
+
+    # Get an extended answer from the boxcar.
+    # @param args [Array] The positional arguments to pass to the boxcar.
+    # @param kwargs [Hash] The keyword arguments to pass to the boxcar.
+    # you can pass one or the other, but not both.
+    # @return [Boxcars::Result] The answer to the question.
+    def conduct(*args, **kwargs)
       Boxcars.info "> Entering #{name}#run", :gray, style: :bold
-      rv = do_run(*args, **kwargs)
+      rv = depart(*args, **kwargs)
       Boxcars.info "< Exiting #{name}#run", :gray, style: :bold
       rv
     end
 
+    # helpers for conversation prompt building
+    # assistant message
+    def self.assi(*strs)
+      [:assistant, strs.join]
+    end
+
+    # system message
+    def self.syst(*strs)
+      [:system, strs.join]
+    end
+
+    # user message
+    def self.user(*strs)
+      [:user, strs.join]
+    end
+
     private
 
     # Get an answer from the boxcar.
-    def do_call(inputs:, return_only_outputs: false)
+    def run_boxcar(inputs:, return_only_outputs: false)
       inputs = our_inputs(inputs)
       output = nil
       begin
@@ -81,19 +107,19 @@ module Boxcars
         raise e
       end
       validate_outputs(outputs: output.keys)
-      # memory&.save_convext(inputs: inputs, outputs: outputs)
       return output if return_only_outputs
 
       inputs.merge(output)
     end
 
-    def do_run(*args, **kwargs)
+    # line up parameters and run boxcar
+    def depart(*args, **kwargs)
       if kwargs.empty?
         raise Boxcars::ArgumentError, "run supports only one positional argument." if args.length != 1
 
-        return do_call(inputs: args[0])[output_keys.first]
+        return run_boxcar(inputs: args[0])[output_keys.first]
       end
-      return do_call(**kwargs)[output_keys].first if args.empty?
+      return run_boxcar(**kwargs)[output_keys].first if args.empty?
 
       raise Boxcars::ArgumentError, "run supported with either positional or keyword arguments but not both. Got args" \
                                     ": #{args} and kwargs: #{kwargs}."
@@ -114,11 +140,12 @@ module Boxcars
 
     # the default answer is the text passed in
     def get_answer(text)
-      text
+      Result.from_text(text)
     end
   end
 end
 
+require "boxcars/result"
 require "boxcars/boxcar/engine_boxcar"
 require "boxcars/boxcar/calculator"
 require "boxcars/boxcar/google_search"

data/lib/boxcars/conversation.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Boxcars
+  # used to keep track of the conversation
+  class Conversation
+    attr_reader :lines, :show_roles
+
+    PEOPLE = %i[system user assistant].freeze
+
+    def initialize(lines: [], show_roles: false)
+      @lines = lines
+      check_lines(@lines)
+      @show_roles = show_roles
+    end
+
+    # check the lines
+    def check_lines(lines)
+      raise ArgumentError, "Lines must be an array" unless lines.is_a?(Array)
+
+      lines.each do |ln|
+        raise ArgumentError, "Conversation item must be a array" unless ln.is_a?(Array)
+        raise ArgumentError, "Conversation item must have 2 items, role and text" unless ln.size == 2
+        raise ArgumentError, "Conversation item must have a role #{ln} in (#{PEOPLE})" unless PEOPLE.include? ln[0]
+        raise ArgumentError, "Conversation value must be a string" unless ln[1].is_a?(String)
+      end
+    end
+
+    # @return [Array] The result as a convesation array
+    def to_a
+      lines
+    end
+
+    # @return [String] A conversation string
+    def to_s
+      lines.map { |ln| "#{ln[0]}: #{ln[1]}" }.join("\n")
+    end
+
+    # add assistant text to the conversation at the end
+    # @param text [String] The text to add
+    def add_assistant(text)
+      @lines << [:assistant, text]
+    end
+
+    # add user text to the conversation at the end
+    # @param text [String] The text to add
+    def add_user(text)
+      @lines << [:user, text]
+    end
+
+    # add system text to the conversation at the end
+    # @param text [String] The text to add
+    def add_system(text)
+      @lines << [:system, text]
+    end
+
+    # add multiple lines to the conversation
+    def add_lines(lines)
+      check_lines(lines)
+      @lines += lines
+    end
+
+    # add a conversation to the conversation
+    def add_conversation(conversation)
+      @lines += conversation.lines
+    end
+
+    # return just the messages for the conversation
+    def message_text
+      lines.map(&:last).join("\n")
+    end
+
+    # compute the prompt parameters with input substitutions (used for chatGPT)
+    # @param inputs [Hash] The inputs to use for the prompt.
+    # @return [Hash] The formatted prompt { messages: ...}
+    def as_messages(inputs = nil)
+      { messages: lines.map { |ln| { role: ln.first, content: ln.last % inputs } } }
+    rescue ::KeyError => e
+      first_line = e.message.to_s.split("\n").first
+      Boxcars.error "Missing prompt input key: #{first_line}"
+      raise KeyError, "Prompt format error: #{first_line}"
+    end
+
+    # compute the prompt parameters with input substitutions
+    # @param inputs [Hash] The inputs to use for the prompt.
+    # @return [Hash] The formatted prompt { prompt: "..."}
+    def as_prompt(inputs = nil)
+      if show_roles
+        lines.map { |ln| format("#{ln.first}: #{ln.last}", inputs) }.join("\n\n")
+      else
+        lines.map { |ln| format(ln.last, inputs) }.join("\n\n")
+      end
+    rescue ::KeyError => e
+      first_line = e.message.to_s.split("\n").first
+      Boxcars.error "Missing prompt input key: #{first_line}"
+      raise KeyError, "Prompt format error: #{first_line}"
+    end
+  end
+end

data/lib/boxcars/conversation_prompt.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Boxcars
+  # used by Boxcars that have engine's to create a conversation prompt.
+  class ConversationPrompt < Prompt
+    attr_reader :conversation
+
+    # @param conversation [Boxcars::Conversation] The conversation to use for the prompt.
+    # @param input_variables [Array<Symbol>] The input vars to use for the prompt. Defaults to [:input]
+    # @param other_inputs [Array<Symbol>] The other input vars to use for the prompt. Defaults to []
+    # @param output_variables [Array<Symbol>] The output vars to use for the prompt. Defaults to [:output]
+    def initialize(conversation:, input_variables: nil, other_inputs: nil, output_variables: nil)
+      @conversation = conversation
+      super(template: template, input_variables: input_variables, other_inputs: other_inputs, output_variables: output_variables)
+    end
+
+    # prompt for chatGPT params
+    # @param inputs [Hash] The inputs to use for the prompt.
+    # @return [Hash] The formatted prompt.
+    def as_messages(inputs)
+      conversation.as_messages(inputs)
+    end
+
+    # prompt for non chatGPT params
+    # @param inputs [Hash] The inputs to use for the prompt.
+    # @return [Hash] The formatted prompt.
+    def as_prompt(inputs)
+      { prompt: conversation.as_prompt(inputs) }
+    end
+
+    # tack on the ongoing conversation if present to the prompt
+    def with_conversation(conversation)
+      return self unless conversation
+
+      new_prompt = dup
+      new_prompt.conversation.add_conversation(conversation)
+      new_prompt
+    end
+  end
+end

data/lib/boxcars/engine/openai.rb

@@ -10,7 +10,7 @@ module Boxcars
     # The default parameters to use when asking the engine.
     DEFAULT_PARAMS = {
       model: "gpt-3.5-turbo",
-      temperature: 0.7,
+      temperature: 0.2,
       max_tokens: 512
     }.freeze
 
@@ -38,17 +38,22 @@ module Boxcars
     # @param openai_access_token [String] The access token to use when asking the engine.
     #   Defaults to Boxcars.configuration.openai_access_token.
     # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
-    def client(prompt:, openai_access_token: nil, **kwargs)
+    def client(prompt:, inputs: {}, openai_access_token: nil, **kwargs)
       access_token = Boxcars.configuration.openai_access_token(openai_access_token: openai_access_token)
       organization_id = Boxcars.configuration.organization_id
       clnt = ::OpenAI::Client.new(access_token: access_token, organization_id: organization_id)
-      the_params = { prompt: prompt }.merge(open_ai_params).merge(kwargs)
-      if the_params[:model] == "gpt-3.5-turbo"
+      params = open_ai_params.merge(kwargs)
+      if params[:model] == "gpt-3.5-turbo"
         prompt = prompt.first if prompt.is_a?(Array)
-        the_params = { messages: [{ role: "user", content: prompt }] }.merge(open_ai_params).merge(kwargs)
-        clnt.chat(parameters: the_params)
+        params = prompt.as_messages(inputs).merge(params)
+        if Boxcars.configuration.log_prompts
+          Boxcars.debug(params[:messages].map { |p| ">>>>>> Role: #{p[:role]} <<<<<<\n#{p[:content]}" }.join("\n"), :cyan)
+        end
+        clnt.chat(parameters: params)
       else
-        clnt.completions(parameters: the_params)
+        params = prompt.as_prompt(inputs).merge(params)
+        Boxcars.debug("Prompt after formatting:\n#{params[:prompt]}", :cyan) if Boxcars.configuration.log_prompts
+        clnt.completions(parameters: params)
       end
     end
 
@@ -56,7 +61,8 @@ module Boxcars
     # @param question [String] The question to ask the engine.
     # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
     def run(question, **kwargs)
-      response = client(prompt: question, **kwargs)
+      prompt = Prompt.new(template: question)
+      response = client(prompt: prompt, **kwargs)
       answer = response["choices"].map { |c| c.dig("message", "content") || c["text"] }.join("\n").strip
       puts answer
       answer
@@ -110,6 +116,7 @@ module Boxcars
 
     # Call out to OpenAI's endpoint with k unique prompts.
     # @param prompts [Array<String>] The prompts to pass into the model.
+    # @param inputs [Array<String>] The inputs to subsitite into the prompt.
     # @param stop [Array<String>] Optional list of stop words to use when generating.
     # @return [EngineResult] The full engine output.
     def generate(prompts:, stop: nil)
@@ -120,13 +127,14 @@ module Boxcars
       # Get the token usage from the response.
       # Includes prompt, completion, and total tokens used.
       inkeys = %w[completion_tokens prompt_tokens total_tokens].freeze
-      sub_prompts = prompts.each_slice(batch_size).to_a
-      sub_prompts.each do |sprompts|
-        response = client(prompt: sprompts, **params)
-        check_response(response)
-        choices.concat(response["choices"])
-        keys_to_use = inkeys & response["usage"].keys
-        keys_to_use.each { |key| token_usage[key] = token_usage[key].to_i + response["usage"][key] }
+      prompts.each_slice(batch_size) do |sub_prompts|
+        sub_prompts.each do |sprompts, inputs|
+          response = client(prompt: sprompts, inputs: inputs, **params)
+          check_response(response)
+          choices.concat(response["choices"])
+          usage_keys = inkeys & response["usage"].keys
+          usage_keys.each { |key| token_usage[key] = token_usage[key].to_i + response["usage"][key] }
+        end
       end
 
       n = params.fetch(:n, 1)

data/lib/boxcars/prompt.rb

@@ -16,6 +16,31 @@ module Boxcars
       @output_variables = output_variables || [:output]
     end
 
+    # compute the prompt parameters with input substitutions (used for chatGPT)
+    # @param inputs [Hash] The inputs to use for the prompt.
+    # @return [Hash] The formatted prompt { messages: ...}
+    def as_prompt(inputs)
+      { prompt: format(inputs) }
+    end
+
+    # compute the prompt parameters with input substitutions
+    # @param inputs [Hash] The inputs to use for the prompt.
+    # @return [Hash] The formatted prompt { prompt: "..."}
+    def as_messages(inputs)
+      { messages: [{ role: :assistant, content: format(inputs) }] }
+    end
+
+    # tack on the ongoing conversation if present to the prompt
+    def with_conversation(conversation)
+      return self unless conversation
+
+      new_prompt = dup
+      new_prompt.template += "\n\n#{conversation.message_text}"
+      new_prompt
+    end
+
+    private
+
     # format the prompt with the input variables
     # @param inputs [Hash] The inputs to use for the prompt.
     # @return [String] The formatted prompt.
@@ -27,43 +52,5 @@ module Boxcars
       Boxcars.error "Missing prompt input key: #{first_line}"
       raise KeyError, "Prompt format error: #{first_line}"
     end
-
-    # check if the template is valid
-    def template_is_valid?
-      all_vars = (input_variables + other_inputs + output_variables).sort
-      template_vars = @template.scan(/%<(\w+)>s/).flatten.map(&:to_sym).sort
-      all_vars == template_vars
-    end
-
-    # missing variables in the template
-    def missing_variables?(inputs)
-      input_vars = [input_variables, other_inputs].flatten.sort
-      return if inputs.keys.sort == input_vars
-
-      raise ArgumentError, "Missing expected input keys, got: #{inputs.keys}. Expected: #{input_vars}"
-    end
-
-    # create a prompt template from examples
-    # @param examples [String] or [Array<String>] The example(s) to use for the template.
-    # @param input_variables [Array<Symbol>] The input variables to use for the prompt.
-    # @param example_separator [String] The separator to use between the examples. Defaults to "\n\n"
-    # @param prefix [String] The prefix to use for the template. Defaults to ""
-    def self.from_examples(examples:, suffix:, input_variables:, example_separator: "\n\n", prefix: "", **kwargs)
-      template = [prefix, examples, suffix].join(example_separator)
-      other_inputs = kwargs[:other_inputs] || []
-      output_variables = kwargs[:output_variables] || [:output]
-      Prompt.new(template: template, input_variables: input_variables, other_inputs: other_inputs,
-                 output_variables: output_variables)
-    end
-
-    # create a prompt template from a file
-    # @param path [String] The path to the file to use for the template.
-    # @param input_variables [Array<Symbol>] The input variables to use for the prompt. Defaults to [:input]
-    # @param output_variables [Array<Symbol>] The output variables to use for the prompt. Defaults to [:output]
-    def self.from_file(path:, input_variables: nil, other_inputs: nil, output_variables: nil)
-      template = File.read(path)
-      Prompt.new(template: template, input_variables: input_variables, other_inputs: other_inputs,
-                 output_variables: output_variables)
-    end
   end
 end

data/lib/boxcars/result.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Boxcars
+  # used by Boxcars to return structured result and additional context
+  class Result
+    attr_reader :status, :answer, :explanation, :suggestions, :added_context
+
+    # @param status [Symbol] :ok or :error
+    # @param answer [String] The answer to the question
+    # @param explanation [String] The explanation of the answer
+    # @param suggestions [Array<String>] The next suggestions for the user
+    # @param added_context [Hash] Any additional context to add to the result
+    def initialize(status:, answer: nil, explanation: nil, suggestions: nil, **added_context)
+      @status = status
+      @answer = answer || explanation
+      @explanation = explanation
+      @suggestions = suggestions
+      @added_context = added_context
+    end
+
+    # @return [Hash] The result as a hash
+    def to_h
+      {
+        status: status,
+        answer: answer,
+        explanation: explanation,
+        suggestions: suggestions
+      }.merge(added_context).compact
+    end
+
+    # @return [String] The result as a json string
+    def to_json(*args)
+      JSON.generate(to_h, *args)
+    end
+
+    # @return [String] An explanation of the result
+    def to_s
+      explanation
+    end
+
+    # @return [String] The answer data to the question
+    def to_answer
+      answer
+    end
+
+    # create a new Result from a text string
+    # @param text [String] The text to use for the result
+    # @param kwargs [Hash] Any additional kwargs to pass to the result
+    # @return [Boxcars::Result] The result
+    def self.from_text(text, **kwargs)
+      answer = text.delete_prefix('"').delete_suffix('"').strip
+      answer = Regexp.last_match(:answer) if answer =~ /^Answer:\s*(?<answer>.*)$/
+      explanation = "Answer: #{answer}"
+      new(status: :ok, answer: answer, explanation: explanation, **kwargs)
+    end
+
+    # create a new Result from an error string
+    # @param error [String] The error to use for the result
+    # @param kwargs [Hash] Any additional kwargs to pass to the result
+    # @return [Boxcars::Result] The error result
+    def self.from_error(error, **kwargs)
+      answer = error
+      answer = Regexp.last_match(:answer) if answer =~ /^Error:\s*(?<answer>.*)$/
+      explanation = "Error: #{answer}"
+      new(status: :error, answer: answer, explanation: explanation, **kwargs)
+    end
+  end
+end

data/lib/boxcars/ruby_repl.rb

@@ -9,19 +9,20 @@ module Boxcars
       Boxcars.debug "RubyREPL: #{code}", :yellow
 
       # wrap the code in an excption block so we can catch errors
-      code = "begin\n#{code}\nrescue Exception => e\n  puts 'Error: ' + e.message\nend"
+      wrapped = "begin\n#{code}\nrescue Exception => e\n  puts 'Error: ' + e.message\nend"
       output = ""
       IO.popen("ruby", "r+") do |io|
-        io.puts code
+        io.puts wrapped
         io.close_write
         output = io.read
       end
       if output =~ /^Error: /
-        Boxcars.error output
-        output
+        Boxcars.debug output, :red
+        Result.from_error(output, code: code)
+      else
+        Boxcars.debug "Answer: #{output}", :yellow, style: :bold
+        Result.from_text(output, code: code)
       end
-      Boxcars.debug "Answer: #{output}", :yellow, style: :bold
-      output
     end
 
     # Execute ruby code

data/lib/boxcars/train/train_action.rb

@@ -5,10 +5,24 @@ module Boxcars
   class TrainAction
     attr_accessor :boxcar, :boxcar_input, :log
 
-    def initialize(boxcar: nil, boxcar_input: nil, log: nil)
-      @boxcar = boxcar
+    # record for a train action
+    # @param boxcar [String] The boxcar to run.
+    # @param log [String] The log of the action.
+    # @param boxcar_input [String] The input to the boxcar.
+    # @return [Boxcars::TrainAction] The train action.
+    def initialize(boxcar:, log:, boxcar_input: nil)
       @boxcar_input = boxcar_input
+      @boxcar = boxcar
       @log = log
     end
+
+    # build a train action from a result
+    # @param result [Boxcars::Result] The result to build from.
+    # @param boxcar [String] The boxcar to run.
+    # @param log [String] The log of the action.
+    # @return [Boxcars::TrainAction] The train action.
+    def self.from_result(result:, boxcar:, log:)
+      new(boxcar: boxcar, boxcar_input: result.to_answer, log: log)
+    end
   end
 end