boxcars 0.7.7 → 0.8.0

data/lib/boxcars/observability_backends/posthog_backend.rb

@@ -0,0 +1,89 @@
+# Ensure the base module is available
+require_relative '../observability_backend'
+
+module Boxcars
+  # An observability backend for sending events to PostHog.
+  #
+  # This backend requires the `posthog-ruby` gem.
+  # Add `gem 'posthog-ruby'` to your Gemfile to use this backend.
+  #
+  # Example Usage:
+  #   require 'boxcars/observability_backends/posthog_backend'
+  #   Boxcars::Observability.backend = Boxcars::PosthogBackend.new(
+  #     api_key: 'YOUR_POSTHOG_API_KEY',
+  #     host: 'https://app.posthog.com' # or your self-hosted instance
+  #   )
+  #
+  #   # To track user-specific events, ensure :user_id is present in properties
+  #   Boxcars::Observability.track(
+  #     event: 'my_event',
+  #     properties: { user_id: 'user_123', custom_data: 'value' }
+  #   )
+  class PosthogBackend
+    include Boxcars::ObservabilityBackend
+
+    # Initializes the PosthogBackend.
+    # Configures the PostHog client with the provided API key and host.
+    #
+    # @param api_key [String] Your PostHog project API key.
+    # @param host [String] The PostHog API host. Defaults to 'https://app.posthog.com'.
+    # @param _personal_api_key [String, nil] Optional: A personal API key for server-side operations if needed.
+    # @param on_error [Proc, nil] Optional: A lambda/proc to call when an error occurs during event capture.
+    #   It receives the error code and error body as arguments.
+    #   Defaults to a proc that logs the error to stderr.
+    # @raise [LoadError] if the 'posthog-ruby' gem is not available.
+    def initialize(api_key:, host: 'https://app.posthog.com', _personal_api_key: nil, on_error: nil)
+      begin
+        require 'posthog'
+      rescue LoadError
+        raise LoadError, "The 'posthog-ruby' gem is required to use PosthogBackend. Please add it to your Gemfile."
+      end
+
+      @on_error_proc = on_error || proc do |status, body|
+        Boxcars.error("PostHog error: Status #{status}, Body: #{body}", :red)
+      end
+
+      # The posthog-ruby gem uses a simpler API
+      @posthog_client = PostHog::Client.new(
+        api_key:,
+        host:,
+        on_error: @on_error_proc
+      )
+    end
+
+    # Tracks an event with PostHog.
+    #
+    # The `:user_id` property is used as PostHog's `distinct_id`. If not provided,
+    # events might be tracked anonymously or associated with a default/server ID
+    # depending on PostHog's SDK behavior.
+    #
+    # All other properties are passed as event properties to PostHog.
+    #
+    # @param event [String, Symbol] The name of the event to track.
+    # @param properties [Hash] A hash of properties for the event.
+    #   It's recommended to include a `:user_id` for user-specific tracking.
+    def track(event:, properties:)
+      # Ensure properties is a hash, duplicate to avoid mutation by PostHog or other backends
+      tracking_properties = properties.is_a?(Hash) ? properties.dup : {}
+
+      distinct_id = tracking_properties.delete(:user_id) || tracking_properties.delete('user_id') || "anonymous_user"
+
+      # The PostHog gem's capture method handles distinct_id and properties.
+      # It's important that distinct_id is a string.
+      @posthog_client.capture(
+        distinct_id: distinct_id.to_s, # Ensure distinct_id is a string
+        event: event.to_s, # Ensure event name is a string
+        properties: tracking_properties
+      )
+      # The posthog-ruby client handles flushing events asynchronously.
+      # If immediate flushing is needed for testing or specific scenarios:
+      # @posthog_client.flush
+    end
+
+    # Flushes any pending events to PostHog immediately.
+    # This is useful for testing or when you need to ensure events are sent before the process exits.
+    def flush
+      @posthog_client.flush if @posthog_client.respond_to?(:flush)
+    end
+  end
+end

data/lib/boxcars/observation.rb

@@ -17,14 +17,14 @@ module Boxcars
     # @return [Hash] The result as a hash
     def to_h
       {
-        note: note,
-        status: status
+        note:,
+        status:
       }.merge(added_context).compact
     end
 
     # @return [String] The result as a json string
-    def to_json(*args)
-      JSON.generate(to_h, *args)
+    def to_json(*)
+      JSON.generate(to_h, *)
     end
 
     # @return [String] An explanation of the result
@@ -41,16 +41,16 @@ module Boxcars
     # @param note [String] The text to use for the observation
     # @param added_context [Hash] Any additional context to add to the result
     # @return [Boxcars::Observation] The observation
-    def self.ok(note, **kwargs)
-      new(note: note, status: :ok, **kwargs)
+    def self.ok(note, **)
+      new(note:, status: :ok, **)
     end
 
     # create a new Observaton from a text string with a status of :error
     # @param note [String] The text to use for the observation
     # @param added_context [Hash] Any additional context to add to the result
     # @return [Boxcars::Observation] The observation
-    def self.err(note, **kwargs)
-      new(note: note, status: :error, **kwargs)
+    def self.err(note, **)
+      new(note:, status: :error, **)
     end
   end
 end

data/lib/boxcars/prompt.rb

@@ -56,18 +56,30 @@ module Boxcars
       conversation
     end
 
-    private
-
     # format the prompt with the input variables
     # @param inputs [Hash] The inputs to use for the prompt.
     # @return [String] The formatted prompt.
     # @raise [Boxcars::KeyError] if the template has extra keys.
     def format(inputs)
-      @template % inputs
+      # Ensure all input keys are symbols for consistent lookup
+      symbolized_inputs = inputs.transform_keys(&:to_sym)
+
+      # Use sprintf for templates like "hi %<name>s"
+      # Ensure that all keys expected by the template are present in symbolized_inputs
+      template_keys = @template.scan(/%<(\w+)>s/).flatten.map(&:to_sym)
+      missing_keys = template_keys - symbolized_inputs.keys
+      raise ::KeyError, "missing keys: #{missing_keys.join(', ')}" if missing_keys.any?
+
+      # Perform the substitution
+      @template % symbolized_inputs
     rescue ::KeyError => e
       first_line = e.message.to_s.split("\n").first
-      Boxcars.error "Missing prompt input key: #{first_line}"
+      Boxcars.error "Prompt format error: #{first_line}" # Changed message slightly for clarity
       raise KeyError, "Prompt format error: #{first_line}"
+    rescue ArgumentError => e # Catch sprintf errors e.g. "too many arguments for format string"
+      first_line = e.message.to_s.split("\n").first
+      Boxcars.error "Prompt format error: #{first_line}"
+      raise ArgumentError, "Prompt format error: #{first_line}"
     end
   end
 end

data/lib/boxcars/result.rb

@@ -20,17 +20,12 @@ module Boxcars
 
     # @return [Hash] The result as a hash
     def to_h
-      {
-        status: status,
-        answer: answer,
-        explanation: explanation,
-        suggestions: suggestions
-      }.merge(added_context).compact
+      { status:, answer:, explanation:, suggestions: }.merge(added_context).compact
     end
 
     # @return [String] The result as a json string
-    def to_json(*args)
-      JSON.generate(to_h, *args)
+    def to_json(*)
+      JSON.generate(to_h, *)
     end
 
     # @return [String] An explanation of the result
@@ -47,22 +42,22 @@ module Boxcars
     # @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)
+    def self.from_text(text, **)
       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)
+      new(status: :ok, answer:, explanation:, **)
     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)
+    def self.from_error(error, **)
       answer = error
       answer = Regexp.last_match(:answer) if answer =~ /^Error:\s*(?<answer>.*)$/
       explanation = "Error: #{answer}"
-      new(status: :error, answer: answer, explanation: explanation, **kwargs)
+      new(status: :error, answer:, explanation:, **)
     end
   end
 end

data/lib/boxcars/ruby_repl.rb

@@ -19,7 +19,7 @@ module Boxcars
       if output =~ /^Error: /
         Boxcars.debug output, :red
         Result.from_error(output, code: code)
-      elsif output.blank?
+      elsif output.nil? || output.strip.empty?
         Result.from_error("The code you gave me did not print a result", code: code)
       else
         output = ::Regexp.last_match(1) if output =~ /^\s*Answer:\s*(.*)$/m

data/lib/boxcars/train/train_action.rb

@@ -22,7 +22,7 @@ module Boxcars
     # @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)
+      new(boxcar:, boxcar_input: result.to_answer, log:)
     end
   end
 end

data/lib/boxcars/train/xml_train.rb

@@ -38,7 +38,7 @@ module Boxcars
 
     # @return Hash The additional variables for this boxcar.
     def prediction_additional(_inputs)
-      { boxcars_xml: boxcars_xml, next_actions: next_actions }.merge super
+      { boxcars_xml:, next_actions: }.merge super
     end
 
     def build_output(text)
@@ -87,11 +87,11 @@ module Boxcars
       # the thought should be the frist line here if it doesn't start with "Action:"
       Boxcars.debug("Thought: #{thought}", :yellow)
 
-      if final_answer.present?
+      if final_answer && !final_answer.to_s.strip.empty?
         Result.new(status: :ok, answer: final_answer, explanation: final_answer)
       else
         # we have an unexpected output from the engine
-        unless action.present? && action_input.present?
+        unless action && !action.to_s.strip.empty? && action_input && !action_input.to_s.strip.empty?
           return [:error, "You gave me an improperly formatted answer or didn't use tags."]
         end
 

data/lib/boxcars/train/xml_zero_shot.rb

@@ -19,7 +19,7 @@ module Boxcars
       @engine_prefix = ''
       @wants_next_actions = kwargs.fetch(:wants_next_actions, false)
       prompt ||= my_prompt
-      super(engine: engine, boxcars: boxcars, prompt: prompt, name: name, description: description, **kwargs)
+      super(engine:, boxcars:, prompt:, name:, description:, **kwargs)
     end
 
     CTEMPLATE = [

data/lib/boxcars/train/zero_shot.rb

@@ -16,12 +16,12 @@ module Boxcars
     def initialize(boxcars:, engine: nil, name: 'Zero Shot', description: 'Zero Shot Train', prompt: nil, **kwargs)
       @wants_next_actions = kwargs.fetch(:wants_next_actions, false)
       prompt ||= my_prompt
-      super(engine: engine, boxcars: boxcars, prompt: prompt, name: name, description: description, **kwargs)
+      super(engine:, boxcars:, prompt:, name:, description:, **kwargs)
     end
 
     # @return Hash The additional variables for this boxcar.
     def prediction_additional(_inputs)
-      { boxcar_names: boxcar_names, boxcar_descriptions: boxcar_descriptions, next_actions: next_actions }.merge super
+      { boxcar_names:, boxcar_descriptions:, next_actions: }.merge super
     end
 
     # Extract the boxcar and input from the engine output.
@@ -72,7 +72,7 @@ module Boxcars
       #   with "Action Input:" should be separated by a newline.
       if engine_output.include?(FINAL_ANSWER_ACTION)
         answer = engine_output.split(FINAL_ANSWER_ACTION).last.strip
-        Result.new(status: :ok, answer: answer, explanation: engine_output)
+        Result.new(status: :ok, answer:, explanation: engine_output)
       else
         # the thought should be the frist line here if it doesn't start with "Action:"
         thought = engine_output.split(/\n+/).reject(&:empty?).first

data/lib/boxcars/train.rb

@@ -24,7 +24,7 @@ module Boxcars
       init_prefixes
       kwargs[:stop] = ["\n#{observation_prefix}"] unless kwargs.key?(:stop)
 
-      super(prompt: prompt, engine: engine, **kwargs)
+      super(prompt:, engine:, **kwargs)
     end
 
     def init_prefixes

data/lib/boxcars/vector_search.rb

@@ -42,7 +42,7 @@ module Boxcars
     def call(query:, count: 1)
       validate_query(query)
       query_vector = convert_query_to_vector(query)
-      @vector_search_instance.call(query_vector: query_vector, count: count)
+      @vector_search_instance.call(query_vector:, count:)
     end
 
     private
@@ -53,15 +53,15 @@ module Boxcars
       case vector_documents[:type]
       when :hnswlib
         Boxcars::VectorStore::Hnswlib::Search.new(
-          vector_documents: vector_documents
+          vector_documents:
         )
       when :in_memory
         Boxcars::VectorStore::InMemory::Search.new(
-          vector_documents: vector_documents
+          vector_documents:
         )
       when :pgvector
         Boxcars::VectorStore::Pgvector::Search.new(
-          vector_documents: vector_documents
+          vector_documents:
         )
       else
         raise_argument_error('Unsupported vector store provided')
@@ -69,7 +69,7 @@ module Boxcars
     end
 
     def default_connection(openai_access_token: nil)
-      Openai.open_ai_client(openai_access_token: openai_access_token)
+      Openai.open_ai_client(openai_access_token:)
     end
 
     def validate_query(query)

data/lib/boxcars/vector_store/pgvector/build_from_array.rb

@@ -1,106 +1,134 @@
 # frozen_string_literal: true
 
-module Boxcars
-  module VectorStore
-    # install pgvector: https://github.com/pgvector/pgvector#installation-notes
-    module Pgvector
-      class BuildFromArray
-        include VectorStore
-
-        # initialize the vector store with the following parameters:
-        #
-        # @param params [Hash] A Hash containing the initial configuration.
-        #
-        # @option params [Symbol] :embedding_tool The embedding tool to use. Must be provided.
-        # @option params [Array] :input_array The array of inputs to use for the embedding tool. Must be provided.
-        # each hash item should have content and metadata
-        # [
-        #   { content: "hello", metadata: { a: 1 } },
-        #   { content: "hi", metadata: { a: 1 } },
-        #   { content: "bye", metadata: { a: 1 } },
-        #   { content: "what's this", metadata: { a: 1 } }
-        # ]
-        # @option params [String] :database_url The URL of the database where embeddings are stored. Must be provided.
-        # @option params [String] :table_name The name of the database table where embeddings are stored. Must be provided.
-        # @option params [String] :embedding_column_name The name of the database column where embeddings are stored. required.
-        # @option params [String] :content_column_name The name of the database column where content is stored. Must be provided.
-        # @option params [String] :metadata_column_name The name of the database column where metadata is stored. required.
-        def initialize(params)
-          @embedding_tool = params[:embedding_tool] || :openai
-
-          validate_params(embedding_tool, params[:input_array])
-
-          @database_url = params[:database_url]
-          @table_name = params[:table_name]
-          @embedding_column_name = params[:embedding_column_name]
-          @content_column_name = params[:content_column_name]
-          @metadata_column_name = params[:metadata_column_name]
-
-          @input_array = params[:input_array]
-          @pg_vectors = []
-        end
+if Gem.loaded_specs.key?('pgvector') && Gem.loaded_specs.key?('pg')
+  module Boxcars
+    module VectorStore
+      # install pgvector: https://github.com/pgvector/pgvector#installation-notes
+      module Pgvector
+        class BuildFromArray
+          include VectorStore
+
+          # initialize the vector store with the following parameters:
+          #
+          # @param params [Hash] A Hash containing the initial configuration.
+          #
+          # @option params [Symbol] :embedding_tool The embedding tool to use. Must be provided.
+          # @option params [Array] :input_array The array of inputs to use for the embedding tool. Must be provided.
+          # each hash item should have content and metadata
+          # [
+          #   { content: "hello", metadata: { a: 1 } },
+          #   { content: "hi", metadata: { a: 1 } },
+          #   { content: "bye", metadata: { a: 1 } },
+          #   { content: "what's this", metadata: { a: 1 } }
+          # ]
+          # @option params [String] :database_url The URL of the database where embeddings are stored. Must be provided.
+          # @option params [String] :table_name The name of the database table where embeddings are stored. Must be provided.
+          # @option params [String] :embedding_column_name The name of the database column where embeddings are stored. required.
+          # @option params [String] :content_column_name The name of the db column where content is stored. Must be provided.
+          # @option params [String] :metadata_column_name The name of the database column where metadata is stored. required.
+          def initialize(params)
+            @embedding_tool = params[:embedding_tool] || :openai
+
+            validate_params(embedding_tool, params[:input_array])
+
+            @database_url = params[:database_url]
+            @table_name = params[:table_name]
+            @embedding_column_name = params[:embedding_column_name]
+            @content_column_name = params[:content_column_name]
+            @metadata_column_name = params[:metadata_column_name]
+
+            @input_array = params[:input_array]
+            @pg_vectors = []
+          end
 
-        # @return [Hash] vector_store: array of hashes with :content, :metadata, and :embedding keys
-        def call
-          texts = input_array.map { |doc| doc[:content] }
-          vectors = generate_vectors(texts)
-          add_vectors(vectors, input_array)
-          documents = save_vector_store
-
-          {
-            type: :pgvector,
-            vector_store: documents
-          }
-        end
+          # @return [Hash] vector_store: array of hashes with :content, :metadata, and :embedding keys
+          def call
+            texts = input_array.map { |doc| doc[:content] }
+            vectors = generate_vectors(texts)
+            add_vectors(vectors, input_array)
+            documents = save_vector_store
+
+            {
+              type: :pgvector,
+              vector_store: documents
+            }
+          end
 
-        private
+          private
 
-        attr_reader :input_array, :embedding_tool, :pg_vectors, :database_url,
-                    :table_name, :embedding_column_name, :content_column_name,
-                    :metadata_column_name
+          attr_reader :input_array, :embedding_tool, :pg_vectors, :database_url,
+                      :table_name, :embedding_column_name, :content_column_name,
+                      :metadata_column_name
 
-        def validate_params(embedding_tool, input_array)
-          raise_argument_error('input_array is nil') unless input_array
-          raise_argument_error('input_array must be an array') unless input_array.is_a?(Array)
-          raise_argument_error('items in input_array needs to have content and metadata') unless proper_input_array?(input_array)
-          return if %i[openai tensorflow].include?(embedding_tool)
+          def validate_params(embedding_tool, input_array)
+            raise_argument_error('input_array is nil') unless input_array
+            raise_argument_error('input_array must be an array') unless input_array.is_a?(Array)
+            unless proper_input_array?(input_array)
+              raise_argument_error('items in input_array needs to have content and metadata')
+            end
+            return if %i[openai tensorflow].include?(embedding_tool)
 
-          raise_argument_error('embedding_tool is invalid') unless %i[openai tensorflow].include?(embedding_tool)
-        end
+            raise_argument_error('embedding_tool is invalid') unless %i[openai tensorflow].include?(embedding_tool)
+          end
 
-        def proper_input_array?(input_array)
-          return false unless
-            input_array.all? { |hash| hash.key?(:content) && hash.key?(:metadata) }
+          def proper_input_array?(input_array)
+            return false unless
+              input_array.all? { |hash| hash.key?(:content) && hash.key?(:metadata) }
 
-          true
-        end
+            true
+          end
 
-        def add_vectors(vectors, texts)
-          raise_argument_error("vectors are nil") unless vectors
-          raise_argument_error("vectors and texts are not the same size") unless vectors.size == texts.size
+          def add_vectors(vectors, texts)
+            raise_argument_error("vectors are nil") unless vectors
+            raise_argument_error("vectors and texts are not the same size") unless vectors.size == texts.size
+
+            vectors.zip(texts) do |vector, doc|
+              pg_vector = Document.new(
+                content: doc[:content],
+                embedding: vector[:embedding],
+                metadata: doc[:metadata]
+              )
+              @pg_vectors << pg_vector
+            end
+          end
 
-          vectors.zip(texts) do |vector, doc|
-            pg_vector = Document.new(
-              content: doc[:content],
-              embedding: vector[:embedding],
-              metadata: doc[:metadata]
+          def save_vector_store
+            result = Boxcars::VectorStore::Pgvector::SaveToDatabase.call(
+              pg_vectors: pg_vectors,
+              database_url: database_url,
+              table_name: table_name,
+              embedding_column_name: embedding_column_name,
+              content_column_name: content_column_name,
+              metadata_column_name: metadata_column_name
             )
-            @pg_vectors << pg_vector
+            raise_argument_error('Error saving vector store to database.') unless result
+
+            result
           end
         end
+      end
+    end
+  end
+else
+  # Define placeholder modules/classes that raise an error if pgvector is not available
+  module Boxcars
+    module VectorStore
+      module Pgvector
+        class PgvectorNotAvailableError < StandardError
+          DEFAULT_MESSAGE = "The 'pgvector' and 'pg' gems are required. Please add them to your Gemfile."
+          def initialize(message = DEFAULT_MESSAGE)
+            super
+          end
+        end
+
+        class BuildFromArray
+          def initialize(*_args)
+            raise PgvectorNotAvailableError
+          end
 
-        def save_vector_store
-          result = Boxcars::VectorStore::Pgvector::SaveToDatabase.call(
-            pg_vectors: pg_vectors,
-            database_url: database_url,
-            table_name: table_name,
-            embedding_column_name: embedding_column_name,
-            content_column_name: content_column_name,
-            metadata_column_name: metadata_column_name
-          )
-          raise_argument_error('Error saving vector store to database.') unless result
-
-          result
+          def call(*_args)
+            raise PgvectorNotAvailableError
+          end
         end
       end
     end