boxcars 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ffc107602f3a2ae47bdb5b5410f6abc8c2ea2c3a13f350630e4d3ece92768f7
-  data.tar.gz: d4fcc08768de5f512a15bf0ca929d50b2a7296937c27c0f1b390189bf0956782
+  metadata.gz: d5ecef1207a69d835d18b96f8d3412c58c84faaf15c5f783c5a8722aafd88ba0
+  data.tar.gz: ac308f23b0b98a733ac24f364caac8e724d3c319e550e35d1b7eef2b8477fd03
 SHA512:
-  metadata.gz: b89e78ce7fec471c8c4f03d32a37bdffd5d1371ac474d14f7e1c90e653ccce62b30a95a845c5c1c1013f5a028c00bb3c87c35cc1394add0554bb33e232b6de63
-  data.tar.gz: 9007dcd0b5dfc8d3b886579cd563b085c04c471ffc3bb167f5d80adb74f85ceacdd5d40942f1772bd59ce4da5903deec2262420e28eba430394d0f831d6cd751
+  metadata.gz: 132bddb5d37af596a9da1e91902fb64d3df55e626806ab56b76d958d7a83ef65625a3ed2fa974dcb24a2b2cba31b858d7830b4b02fe07d27cf31f264e8ae78c8
+  data.tar.gz: 64a536a7d5e8c3f93e186bfab8d638d27c4077f6f67851461d6d01fe6d9d166e7b648d7d83ba205fbd8d45e60bd3312202632a12fe1e378341d95f3b4571c54c

data/CHANGELOG.md

@@ -1,5 +1,13 @@
-## [0.1.1] - 2o23-02-16
-Changed
+## [0.1.2] - 2023-02-16
+
+Changes
+- cleaned up and added more yard docs
+- required open ai gem and logger inside gem to simplify use
+- updated README with examples
+
+## [0.1.1] - 2023-02-16
+
+Changes
 - updated to OpenAI gem 3.0
 
 ## [0.1.0] - 2023-02-15

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    boxcars (0.1.1)
+    boxcars (0.1.2)
       google_search_results (~> 2.2)
       ruby-openai (~> 3.0)
 
@@ -89,6 +89,7 @@ GEM
       httparty (>= 0.18.1)
     ruby-progressbar (1.11.0)
     sqlite3 (1.6.0-x86_64-darwin)
+    sqlite3 (1.6.0-x86_64-linux)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.4.2)
@@ -100,6 +101,8 @@ GEM
 
 PLATFORMS
   x86_64-darwin-21
+  x86_64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   activerecord (~> 7.0)
@@ -116,4 +119,4 @@ DEPENDENCIES
   webmock (~> 3.18.1)
 
 BUNDLED WITH
-   2.2.32
+   2.4.7

data/README.md

@@ -1,8 +1,16 @@
 # Boxcars
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/boxcars`. To experiment with that code, run `bin/console` for an interactive prompt.
+This gem lets you compose new systems with composability using systems like OpenAI, Search, and SQL (and many more).
 
-TODO: Delete this and the text above, and describe your gem
+The popular python library langchain is a precursor to this work, but we wanted to put a ruby spin on things and make it easier to get started.
+
+## Concepts
+All of these concepts are in a module named Boxcars:
+- Prompt: a prompt is used by an Engine to generate text results.
+- Engine: an entity that generates text from a Prompt.
+- Boxcar: an encapsulation that does one thing (search, math, SQL, etc) and a many use an Engine to get their work accomplished.
+- Conductor: given a list of Boxcars and an Engine, an answer if found by breaking the promlem into peices for an indvidual Boxcar to solve. This is all joined back together to yield a final result. There is currently only one implementation - ZeroShot.
+- ConductorExecutor: manages the running of a Conductor.
 
 ## Installation
 
@@ -22,7 +30,45 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+We will document many more examples soon, but here are a couple. The first step is to setup your environment variables for OpenAI and Serp (OPENAI_ACCESS_TOKEN, SERPAPI_API_KEY). If you don't want to set them in your environment, they can be passed in as well to the API.
+
+In the examples below, we added one rubygem to load the environment at the first line, but depending on what you want, you might not need this.
+```ruby
+require "dotenv/load"
+```
+
+### Direct Boxcar Use
+
+```ruby
+# run the calculator
+require "dotenv/load"
+require "boxcars"
+
+engine = Boxcars::Openai.new
+calc = Boxcars::Calculator.new(engine: engine)
+puts calc.run "what is pi to the forth power divided by 22.1?"
+```
+
+### Boxcars currently implemmented
+
+Here is what we have so far, but please put up a PR with your new ideas.
+- Search: uses the SERP API to do seaches
+- Calculator: uses an Engine to generate ruby code to do math
+- SQL: given an ActiveRecord connection, it will generate and run sql statments from a prompt.
+
+### Run a list of Boxcars
+```ruby
+# run a Conductor for a calculator, and search 
+require "dotenv/load"
+require "boxcars"
+
+engine = Boxcars::Openai.new
+calc = Boxcars::Calculator.new(engine: engine)
+search = Boxcars::Serp.new
+cond = Boxcars::ZeroShot.new(engine: engine, boxcars: [calc, search])
+cexe = Boxcars::ConductorExecuter.new(conductor: cond)
+puts cexe.run "What is pi times the square root of the average temperature in Austin TX in January?"
+```
 
 ## Development
 

data/lib/boxcars/boxcar/calculator.rb

@@ -4,15 +4,15 @@
 module Boxcars
   # A Boxcar that interprets a prompt and executes ruby code to do math
   class Calculator < EngineBoxcar
+    # the description of this engine boxcar
     CALCDESC = "useful for when you need to answer questions about math"
     attr_accessor :input_key
 
-    # @param prompt [Boxcars::Prompt] The prompt to use for this boxcar.
-    # @param name [String] The name of the boxcar. Defaults to classname.
-    # @param description [String] A description of the boxcar.
     # @param engine [Boxcars::Engine] The engine to user for this boxcar. Can be inherited from a conductor if nil.
+    # @param prompt [Boxcars::Prompt] The prompt to use for this boxcar. Defaults to built-in prompt.
     # @param input_key [Symbol] The key to use for the input. Defaults to :question.
     # @param output_key [Symbol] The key to use for the output. Defaults to :answer.
+    # @param kwargs [Hash] Any other keyword arguments to pass to the parent class.
     def initialize(engine: nil, prompt: nil, input_key: :question, output_key: :answer, **kwargs)
       # def initialize(engine:, prompt: my_prompt, input_key: :question, output_key: :answer, **kwargs)
       @input_key = input_key
@@ -24,14 +24,19 @@ module Boxcars
             output_key: output_key)
     end
 
+    # the prompt input keys
     def input_keys
       [input_key]
     end
 
+    # the output keys
     def output_keys
       [output_key]
     end
 
+    # call the calculator
+    # @param inputs [Hash] The inputs to the boxcar.
+    # @return [Hash] The outputs from the boxcar.
     def call(inputs:)
       t = predict(question: inputs[input_key], stop: ["```output"]).strip
       answer = get_answer(t)

data/lib/boxcars/boxcar/engine_boxcar.rb

@@ -3,7 +3,6 @@
 # Boxcars is a framework for running a series of tools to get an answer to a question.
 module Boxcars
   # For Boxcars that use an engine to do their work.
-  # @abstract
   class EngineBoxcar < Boxcars::Boxcar
     attr_accessor :prompt, :engine, :output_key
 
@@ -19,28 +18,19 @@ module Boxcars
       super(name: name, description: description)
     end
 
+    # input keys for the prompt
     def input_keys
       prompt.input_variables
     end
 
+    # output keys
     def output_keys
       [output_key]
     end
 
-    # # Check that all inputs are present.
-    # def validate_inputs(inputs:)
-    #   missing_keys = input_keys - inputs.keys
-    #   raise Boxcars::ArgumentError, "Missing some input keys: #{missing_keys}" if missing_keys.any?
-
-    #   inputs
-    # end
-
-    # def validate_outputs(outputs:)
-    #   return if outputs.sort == output_keys.sort
-
-    #   raise Boxcars::ArgumentError, "Did not get out keys that were expected, got: #{outputs}. Expected: #{output_keys}"
-    # end
-
+    # generate a response from the engine
+    # @param input_list [Array<Hash>] A list of hashes of input values to use for the prompt.
+    # @return [Boxcars::EngineResult] The result from the engine.
     def generate(input_list:)
       stop = input_list[0][:stop]
       prompts = []
@@ -52,6 +42,9 @@ module Boxcars
       engine.generate(prompts: prompts, stop: stop)
     end
 
+    # apply a response from the engine
+    # @param input_list [Array<Hash>] A list of hashes of input values to use for the prompt.
+    # @return [Hash] A hash of the output key and the output value.
     def apply(input_list:)
       response = generate(input_list: input_list)
       response.generations.to_h do |generation|
@@ -59,10 +52,16 @@ module Boxcars
       end
     end
 
+    # predict a response from the engine
+    # @param kwargs [Hash] A hash of input values to use for the prompt.
+    # @return [String] The output value.
     def predict(**kwargs)
       apply(input_list: [kwargs])[output_key]
     end
 
+    # predict a response from the engine and parse it
+    # @param kwargs [Hash] A hash of input values to use for the prompt.
+    # @return [String] The output value.
     def predict_and_parse(**kwargs)
       result = predict(**kwargs)
       if prompt.output_parser
@@ -72,6 +71,9 @@ module Boxcars
       end
     end
 
+    # apply a response from the engine and parse it
+    # @param input_list [Array<Hash>] A list of hashes of input values to use for the prompt.
+    # @return [Array<String>] The output values.
     def apply_and_parse(input_list:)
       result = apply(input_list: input_list)
       if prompt.output_parser
@@ -81,6 +83,8 @@ module Boxcars
       end
     end
 
+    # check that there is exactly one output key
+    # @raise [Boxcars::ArgumentError] if there is not exactly one output key.
     def check_output_keys
       return unless output_keys.length != 1
 

data/lib/boxcars/boxcar/serp.rb

@@ -4,14 +4,14 @@ require 'google_search_results'
 module Boxcars
   # A Boxcar that uses the Google SerpAPI to get answers to questions.
   class Serp < Boxcar
+    # the description of this boxcar
     SERPDESC = "useful for when you need to answer questions about current events." \
                "You should ask targeted questions"
 
     # implements a boxcar that uses the Google SerpAPI to get answers to questions.
     # @param name [String] The name of the boxcar. Defaults to classname.
     # @param description [String] A description of the boxcar. Defaults to SERPDESC.
-    # @param engine [Boxcars::Engine] The engine to user for this boxcar. Can be inherited from a Conductor if nil.
-    #
+    # @param serpapi_api_key [String] The API key to use for the SerpAPI. Defaults to Boxcars.configuration.serpapi_api_key.
     def initialize(name: "Search", description: SERPDESC, serpapi_api_key: "not set")
       super(name: name, description: description)
       api_key = Boxcars.configuration.serpapi_api_key(serpapi_api_key: serpapi_api_key)

data/lib/boxcars/boxcar/sql.rb

@@ -4,16 +4,16 @@
 module Boxcars
   # A Boxcar that interprets a prompt and executes SQL code to get answers
   class SQL < EngineBoxcar
+    # the description of this engine boxcar
     SQLDESC = "useful for when you need to query a SQL database"
     attr_accessor :connection, :input_key
 
     # @param connection [ActiveRecord::Connection] The SQL connection to use for this boxcar.
-    # @param prompt [Boxcars::Prompt] The prompt to use for this boxcar.
-    # @param name [String] The name of the boxcar. Defaults to classname.
-    # @param description [String] A description of the boxcar.
     # @param engine [Boxcars::Engine] The engine to user for this boxcar. Can be inherited from a conductor if nil.
     # @param input_key [Symbol] The key to use for the input. Defaults to :question.
     # @param output_key [Symbol] The key to use for the output. Defaults to :answer.
+    # @param kwargs [Hash] Any other keyword arguments to pass to the parent class. This can include
+    #   :name, :description and :prompt
     def initialize(connection:, engine: nil, input_key: :question, output_key: :answer, **kwargs)
       @connection = connection
       @input_key = input_key
@@ -25,14 +25,21 @@ module Boxcars
             output_key: output_key)
     end
 
+    # the input keys for the prompt
+    # @return [Array<Symbol>] The input keys for the prompt.
     def input_keys
       [input_key]
     end
 
+    # the output keys for the prompt
+    # @return [Array<Symbol>] The output keys for the prompt.
     def output_keys
       [output_key]
     end
 
+    # call the boxcar
+    # @param inputs [Hash] The inputs to the boxcar.
+    # @return [Hash] The outputs from the boxcar.
     def call(inputs:)
       t = predict(question: inputs[input_key], dialect: dialect, top_k: 5, table_info: schema, stop: ["Answer:"]).strip
       answer = get_answer(t)

data/lib/boxcars/boxcar.rb

@@ -26,6 +26,8 @@ module Boxcars
     end
 
     # Check that all inputs are present.
+    # @param inputs [Hash] The inputs.
+    # @raise [RuntimeError] If the inputs are not the same.
     def validate_inputs(inputs:)
       missing_keys = input_keys - inputs.keys
       raise "Missing some input keys: #{missing_keys}" if missing_keys.any?
@@ -33,6 +35,9 @@ module Boxcars
       inputs
     end
 
+    # check that all outputs are present
+    # @param outputs [Array<String>] The output keys.
+    # @raise [RuntimeError] If the outputs are not the same.
     def validate_outputs(outputs:)
       return if outputs.sort == output_keys.sort
 
@@ -44,6 +49,28 @@ module Boxcars
       raise NotImplementedError
     end
 
+    # Apply the boxcar to a list of inputs.
+    # @param input_list [Array<Hash>] The list of inputs.
+    # @return [Array<Boxcars::Boxcar>] The list of outputs.
+    def apply(input_list:)
+      input_list.map { |inputs| new(**inputs) }
+    end
+
+    # Get an 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 [String] The answer to the question.
+    def run(*args, **kwargs)
+      puts "> Enterning #{name} boxcar#run".colorize(:gray, style: :bold)
+      rv = do_run(*args, **kwargs)
+      puts "< Exiting #{name} boxcar#run".colorize(:gray, style: :bold)
+      rv
+    end
+
+    private
+
+    # Get an answer from the boxcar.
     def do_call(inputs:, return_only_outputs: false)
       inputs = our_inputs(inputs)
       output = nil
@@ -60,22 +87,6 @@ module Boxcars
       inputs.merge(output)
     end
 
-    def apply(input_list:)
-      input_list.map { |inputs| new(**inputs) }
-    end
-
-    # Get an answer from the boxcar.
-    # @param question [String] The question to ask the boxcar.
-    # @return [String] The answer to the question.
-    def run(*args, **kwargs)
-      puts "> Enterning #{name} boxcar#run".colorize(:gray, style: :bold)
-      rv = do_run(*args, **kwargs)
-      puts "< Exiting #{name} boxcar#run".colorize(:gray, style: :bold)
-      rv
-    end
-
-    private
-
     def do_run(*args, **kwargs)
       if kwargs.empty?
         raise Boxcars::ArgumentError, "run supports only one positional argument." if args.length != 1

data/lib/boxcars/conductor/conductor_executer.rb

@@ -10,10 +10,10 @@ module Boxcars
     # @param return_intermediate_steps [Boolean] Whether to return the intermediate steps. Defaults to false.
     # @param max_iterations [Integer] The maximum number of iterations to run. Defaults to nil.
     # @param early_stopping_method [String] The early stopping method to use. Defaults to "force".
-    def initialize(conductor:, boxcars:, return_intermediate_steps: false, max_iterations: nil,
+    def initialize(conductor:, boxcars: nil, return_intermediate_steps: false, max_iterations: nil,
                    early_stopping_method: "force")
       @conductor = conductor
-      @boxcars = boxcars
+      @boxcars = boxcars || conductor.boxcars
       @return_intermediate_steps = return_intermediate_steps
       @max_iterations = max_iterations
       @early_stopping_method = early_stopping_method
@@ -21,10 +21,15 @@ module Boxcars
       super(prompt: conductor.prompt, engine: conductor.engine, name: conductor.name, description: conductor.description)
     end
 
+    # is this the same list of boxcars?
+    # @param boxcar_names [Array<String>] The boxcar names to compare.
+    # @return [Boolean] Whether the boxcars are the same.
     def same_boxcars?(boxcar_names)
       conductor.allowed_boxcars.sort == boxcar_names
     end
 
+    # validate the boxcars
+    # @raise [RuntimeError] If the boxcars are not the same.
     def validate_boxcars
       boxcar_names = boxcars.map(&:name).sort
       return if same_boxcars?(boxcar_names)
@@ -32,16 +37,21 @@ module Boxcars
       raise "Allowed boxcars (#{conductor.allowed_boxcars}) different than provided boxcars (#{boxcar_names})"
     end
 
+    # the input keys
     def input_keys
       conductor.input_keys
     end
 
+    # the output keys
     def output_keys
       return conductor.return_values + ["intermediate_steps"] if return_intermediate_steps
 
       conductor.return_values
     end
 
+    # should we continue to run?
+    # @param iterations [Integer] The number of iterations.
+    # @return [Boolean] Whether to continue.
     def should_continue?(iterations)
       return true if max_iterations.nil?
 
@@ -49,6 +59,9 @@ module Boxcars
     end
 
     # handler before returning
+    # @param output [Boxcars::ConductorFinish] The output.
+    # @param intermediate_steps [Array<Hash>] The intermediate steps.
+    # @return [Hash] The final output.
     def pre_return(output, intermediate_steps)
       puts output.log.colorize(:yellow)
       final_output = output.return_values
@@ -56,10 +69,16 @@ module Boxcars
       final_output
     end
 
+    # the prefix for the engine
+    # @param return_direct [Boolean] Whether to return directly.
+    # @return [String] The prefix.
     def engine_prefix(return_direct)
       return_direct ? "" : conductor.engine_prefix
     end
 
+    # call the conductor
+    # @param inputs [Hash] The inputs.
+    # @return [Hash] The output.
     def call(inputs:)
       conductor.prepare_for_new_call
       name_to_boxcar_map = boxcars.to_h { |boxcar| [boxcar.name, boxcar] }

data/lib/boxcars/conductor/zero_shot.rb

@@ -4,7 +4,10 @@ module Boxcars
   class ZeroShot < Conductor
     attr_reader :boxcars, :observation_prefix, :engine_prefix
 
+    # default prompt prefix
     PREFIX = "Answer the following questions as best you can. You have access to the following actions:".freeze
+
+    # default prompt instructions
     FORMAT_INSTRUCTIONS = <<~FINPUT.freeze
       Use the following format:
 
@@ -18,6 +21,7 @@ module Boxcars
       Final Answer: the final answer to the original input question
     FINPUT
 
+    # default prompt suffix
     SUFFIX = <<~SINPUT.freeze
       Begin!
 
@@ -25,6 +29,10 @@ module Boxcars
       Thought:%<agent_scratchpad>s
     SINPUT
 
+    # @param boxcars [Array<Boxcars::Boxcar>] The boxcars to run.
+    # @param engine [Boxcars::Engine] The engine to use for this conductor.
+    # @param name [String] The name of the conductor. Defaults to 'Zero Shot'.
+    # @param description [String] The description of the conductor. Defaults to 'Zero Shot Conductor'.
     def initialize(boxcars:, engine:, name: 'Zero Shot', description: 'Zero Shot Conductor')
       @observation_prefix = 'Observation: '
       @engine_prefix = 'Thought:'
@@ -33,16 +41,11 @@ module Boxcars
     end
 
     # Create prompt in the style of the zero shot agent.
-
-    #   Args:
-    #     boxcars: List of boxcars the agent will have access to, used to format the prompt.
-    #     prefix: String to put before the list of boxcars.
-    #     suffix: String to put after the list of boxcars.
-    #     input_variables: List of input variables the final prompt will expect.
-
-    #   Returns:
-    #     A Prompt with the template assembled from the pieces here.
-
+    # @param boxcars [Array<Boxcars::Boxcar>] List of boxcars the agent will have access to, used to format the prompt.
+    # @param prefix [String] String to put before the main prompt.
+    # @param suffix [String] String to put after the main prompt.
+    # @param input_variables [Array<Symbol>] List of input variables the final prompt will expect.
+    # @return [Boxcars::Prompt] A Prompt with the template assembled from the pieces here.
     def self.create_prompt(boxcars:, prefix: PREFIX, suffix: SUFFIX, input_variables: [:input, :agent_scratchpad])
       boxcar_strings = boxcars.map { |boxcar| "#{boxcar.name}: #{boxcar.description}" }.join("\n")
       boxcar_names = boxcars.map(&:name)
@@ -51,9 +54,12 @@ module Boxcars
       Prompt.new(template: template, input_variables: input_variables)
     end
 
+    # the final answer action string
     FINAL_ANSWER_ACTION = "Final Answer:".freeze
 
     # Parse out the action and input from the engine output.
+    # @param engine_output [String] The output from the engine.
+    # @return [Array<String>] The action and input.
     def get_action_and_input(engine_output:)
       # NOTE: if you're specifying a custom prompt for the ZeroShotAgent,
       #   you will need to ensure that it meets the following Regex requirements.
@@ -74,6 +80,9 @@ module Boxcars
       end
     end
 
+    # Extract the boxcar and input from the engine output.
+    # @param text [String] The output from the engine.
+    # @return [Array<Boxcars::Boxcar, String>] The boxcar and input.
     def extract_boxcar_and_input(text)
       get_action_and_input(engine_output: text)
     end

data/lib/boxcars/conductor.rb

@@ -27,13 +27,18 @@ module Boxcars
     end
 
     # Extract the boxcar name and input from the text.
+    # @param text [String] The text to extract from.
     def extract_boxcar_and_input(text)
     end
 
+    # the stop strings list
     def stop
       ["\n#{observation_prefix}"]
     end
 
+    # build the scratchpad for the engine
+    # @param intermediate_steps [Array] The intermediate steps to build the scratchpad from.
+    # @return [String] The scratchpad.
     def construct_scratchpad(intermediate_steps)
       thoughts = ""
       intermediate_steps.each do |action, observation|
@@ -43,6 +48,9 @@ module Boxcars
       thoughts
     end
 
+    # determine the next action
+    # @param full_inputs [Hash] The inputs to the engine.
+    # @return [Boxcars::Action] The next action.
     def get_next_action(full_inputs)
       full_output = engine_boxcar.predict(**full_inputs)
       parsed_output = extract_boxcar_and_input(full_output)
@@ -79,20 +87,27 @@ module Boxcars
       "Final Answer"
     end
 
+    # the input keys
+    # @return [Array<Symbol>] The input keys.
     def input_keys
-      # Return the input keys
       list = prompt.input_variables
       list.delete(:agent_scratchpad)
       list
     end
 
     # Check that all inputs are present.
+    # @param inputs [Hash] The inputs to check.
+    # @raise [RuntimeError] If any inputs are missing.
     def validate_inputs(inputs:)
       missing_keys = input_keys - inputs.keys
       raise "Missing some input keys: #{missing_keys}" if missing_keys.any?
     end
 
-    def validate_prompt(values: Dict)
+    # validate the prompt
+    # @param values [Hash] The values to validate.
+    # @return [Hash] The validated values.
+    # @raise [RuntimeError] If the prompt is invalid.
+    def validate_prompt(values:)
       prompt = values["engine_chain"].prompt
       unless prompt.input_variables.include?(:agent_scratchpad)
         logger.warning("`agent_scratchpad` should be a variable in prompt.input_variables. Not found, adding it at the end.")
@@ -109,6 +124,11 @@ module Boxcars
       values
     end
 
+    # get the stopped response
+    # @param early_stopping_method [String] The early stopping method.
+    # @param intermediate_steps [Array] The intermediate steps.
+    # @param kwargs [Hash] extra keword arguments.
+    # @return [Boxcars::Action] The action to take.
     def return_stopped_response(early_stopping_method, intermediate_steps, **kwargs)
       case early_stopping_method
       when "force"

data/lib/boxcars/engine/openai.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
 
+require 'openai'
 # Boxcars is a framework for running a series of tools to get an answer to a question.
 module Boxcars
   # A engine that uses OpenAI's API.
   class Openai < Engine
     attr_reader :prompts, :open_ai_params, :model_kwargs, :batch_size
 
+    # The default parameters to use when asking the engine.
     DEFAULT_PARAMS = {
       model: "text-davinci-003",
       temperature: 0.7,
       max_tokens: 256
     }.freeze
 
+    # the default name of the engine
     DEFAULT_NAME = "OpenAI engine"
+    # the default description of the engine
     DEFAULT_DESCRIPTION = "useful for when you need to use AI to answer questions. " \
                           "You should ask targeted questions"
 
@@ -30,7 +34,9 @@ module Boxcars
     end
 
     # Get an answer from the engine.
-    # @param question [String] The question to ask the engine.
+    # @param prompt [String] The prompt to use when asking the engine.
+    # @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: 'not set', **kwargs)
       access_token = Boxcars.configuration.openai_access_token(openai_access_token: openai_access_token)
@@ -51,15 +57,20 @@ module Boxcars
     end
 
     # Build extra kwargs from additional params that were passed in.
+    # @param values [Hash] The values to build extra kwargs from.
     def build_extra(values:)
       values[:model_kw_args] = @open_ai_params.merge(values)
       values
     end
 
+    # Get the default parameters for the engine.
     def default_params
       open_ai_params
     end
 
+    # Get generation informaton
+    # @param sub_choices [Array<Hash>] The choices to get generation info for.
+    # @return [Array<Generation>] The generation information.
     def generation_info(sub_choices)
       sub_choices.map do |choice|
         Generation.new(
@@ -73,18 +84,9 @@ module Boxcars
     end
 
     # Call out to OpenAI's endpoint with k unique prompts.
-
-    #   Args:
-    #     prompts: The prompts to pass into the model.
-    #     stop: Optional list of stop words to use when generating.
-
-    #   Returns:
-    #     The full engine output.
-
-    #   Example:
-    #     .. code-block:: ruby
-
-    #       response = openai.generate(["Tell me a joke."])
+    # @param prompts [Array<String>] The prompts to pass into the model.
+    # @param stop [Array<String>] Optional list of stop words to use when generating.
+    # @return [EngineResult] The full engine output.
     def generate(prompts:, stop: nil)
       params = {}
       params[:stop] = stop if stop
@@ -112,21 +114,25 @@ module Boxcars
     # rubocop:enable Metrics/AbcSize
   end
 
+  # the identifying parameters for the engine
   def identifying_params
     params = { model_name: model_name }
     params.merge!(default_params)
     params
   end
 
+  # the engine type
   def engine_type
     "openai"
   end
 
   # calculate the number of tokens used
   def get_num_tokens(text:)
-    text.split.length
+    text.split.length # TODO: hook up to token counting gem
   end
 
+  # lookup the context size for a model by name
+  # @param modelname [String] The name of the model to lookup.
   def modelname_to_contextsize(modelname)
     model_lookup = {
       'text-davinci-003': 4097,
@@ -140,14 +146,10 @@ module Boxcars
   end
 
   # Calculate the maximum number of tokens possible to generate for a prompt.
-
-  #   Args:
-  #     prompt: The prompt to use.
-
-  #   Returns:
-  #     The maximum number of tokens possible to generate for a prompt.
-  def max_tokens_for_prompt(prompt)
-    num_tokens = get_num_tokens(prompt)
+  # @param prompt_text [String] The prompt text to use.
+  # @return [Integer] the number of tokens possible to generate.
+  def max_tokens_for_prompt(prompt_text)
+    num_tokens = get_num_tokens(prompt_text)
 
     # get max context size for model by name
     max_size = modelname_to_contextsize(model_name)

data/lib/boxcars/ruby_repl.rb

@@ -3,6 +3,8 @@
 module Boxcars
   # used by Boxcars to run ruby code
   class RubyREPL
+    # Execute ruby code
+    # @param code [String] The code to run
     def call(code:)
       puts "RubyREPL: #{code}".colorize(:red)
       output = ""
@@ -15,6 +17,8 @@ module Boxcars
       output
     end
 
+    # Execute ruby code
+    # @param command [String] The code to run
     def run(command)
       call(code: command)
     end

data/lib/boxcars/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Boxcars
-  VERSION = "0.1.1"
+  # The current version of the gem.
+  VERSION = "0.1.2"
 end

data/lib/boxcars.rb

@@ -6,12 +6,21 @@ require 'logger'
 module Boxcars
   # Error class for all Boxcars errors.
   class Error < StandardError; end
+
+  # Error class for all Boxcars configuration errors.
   class ConfigurationError < Error; end
+
+  # Error class for all Boxcars argument errors.
   class ArgumentError < Error; end
+
+  # Error class for all Boxcars value errors.
   class ValueError < Error; end
 
   # simple string colorization
   class ::String
+    # colorize a string
+    # @param color [Symbol] The color to use.
+    # @param options [Hash] The options to use.
     def colorize(color, options = {})
       background = options[:background] || options[:bg] || false
       style = options[:style]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boxcars
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Francis Sullivan
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-16 00:00:00.000000000 Z
+date: 2023-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: debug