boxcars 0.7.6 → 0.8.0

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

@@ -1,160 +1,186 @@
 # frozen_string_literal: true
 
-require 'pg'
-require 'json'
-
-module Boxcars
-  module VectorStore
-    module Pgvector
-      class Search
-        include VectorStore
-
-        # initialize the vector store with the following parameters:
-        # @param params [Hash] A Hash containing the initial configuration.
-        # @option params [Hash] :vector_documents The vector documents to search.
-        # example:
-        # {
-        #   type: :pgvector,
-        #   vector_store: {
-        #     table_name: "vector_store",
-        #     embedding_column_name: "embedding",
-        #     content_column_name: "content",
-        #     database_url: ENV['DATABASE_URL']
-        #   }
-        # }
-        #
-        # @option params [Hash] :vector_store The vector store to search.
-        def initialize(params)
-          vector_store = validate_params(params)
-          db_url = validate_vector_store(vector_store)
-          @db_connection = test_db(db_url)
-
-          @vector_documents = params[:vector_documents]
-        end
+if Gem.loaded_specs.key?('pgvector') && Gem.loaded_specs.key?('pg')
+  require 'pg'
+  require 'json'
+
+  module Boxcars
+    module VectorStore
+      module Pgvector
+        class Search
+          include VectorStore
+
+          # initialize the vector store with the following parameters:
+          # @param params [Hash] A Hash containing the initial configuration.
+          # @option params [Hash] :vector_documents The vector documents to search.
+          # example:
+          # {
+          #   type: :pgvector,
+          #   vector_store: {
+          #     table_name: "vector_store",
+          #     embedding_column_name: "embedding",
+          #     content_column_name: "content",
+          #     database_url: ENV['DATABASE_URL']
+          #   }
+          # }
+          #
+          # @option params [Hash] :vector_store The vector store to search.
+          def initialize(params)
+            vector_store = validate_params(params)
+            db_url = validate_vector_store(vector_store)
+            @db_connection = test_db(db_url)
+
+            @vector_documents = params[:vector_documents]
+          end
 
-        # @param query_vector [Array] The query vector to search for.
-        # @param count [Integer] The number of results to return.
-        # @return [Array] array of hashes with :document and :distance keys
-        # @example
-        #   [
-        #     {
-        #       document: Boxcars::VectorStore::Document.new(
-        #         content: "hello",
-        #         embedding: [0.1, 0.2, 0.3],
-        #         metadata: { a: 1 }
-        #       ),
-        #       distance: 0.1
-        #     }
-        #   ]
-        def call(query_vector:, count: 1)
-          raise ::Boxcars::ArgumentError, 'query_vector is empty' if query_vector.empty?
-
-          search(query_vector, count)
-        end
+          # @param query_vector [Array] The query vector to search for.
+          # @param count [Integer] The number of results to return.
+          # @return [Array] array of hashes with :document and :distance keys
+          # @example
+          #   [
+          #     {
+          #       document: Boxcars::VectorStore::Document.new(
+          #         content: "hello",
+          #         embedding: [0.1, 0.2, 0.3],
+          #         metadata: { a: 1 }
+          #       ),
+          #       distance: 0.1
+          #     }
+          #   ]
+          def call(query_vector:, count: 1)
+            raise ::Boxcars::ArgumentError, 'query_vector is empty' if query_vector.empty?
+
+            search(query_vector, count)
+          end
 
-        private
+          private
 
-        attr_reader :vector_documents, :vector_store, :db_connection,
-                    :table_name, :embedding_column_name, :content_column_name
+          attr_reader :vector_documents, :vector_store, :db_connection,
+                      :table_name, :embedding_column_name, :content_column_name
 
-        def validate_params(params)
-          @vector_documents = params[:vector_documents]
+          def validate_params(params)
+            @vector_documents = params[:vector_documents]
 
-          raise_argument_error('vector_documents is nil') unless vector_documents
-          raise_arugment_error('vector_documents must be a hash') unless vector_documents.is_a?(Hash)
-          raise_arugment_error('type must be pgvector') unless vector_documents[:type] == :pgvector
+            raise_argument_error('vector_documents is nil') unless vector_documents
+            raise_arugment_error('vector_documents must be a hash') unless vector_documents.is_a?(Hash)
+            raise_arugment_error('type must be pgvector') unless vector_documents[:type] == :pgvector
 
-          @vector_store = vector_documents[:vector_store]
-          @vector_store
-        end
+            @vector_store = vector_documents[:vector_store]
+            @vector_store
+          end
 
-        def validate_vector_store(vector_store)
-          raise_arugment_error('vector_store is nil') unless vector_store
-          raise_arugment_error('vector_store must be a hash') unless vector_store.is_a?(Hash)
-          raise_arugment_error('vector_store must have a table_name') unless vector_store[:table_name]
-          raise_arugment_error('vector_store must have a embedding_column_name') unless vector_store[:embedding_column_name]
-          raise_arugment_error('vector_store must have a content_column_name') unless vector_store[:content_column_name]
-          raise_argument_error('missing DATABASE_URL') unless vector_store[:database_url]
+          def validate_vector_store(vector_store)
+            raise_arugment_error('vector_store is nil') unless vector_store
+            raise_arugment_error('vector_store must be a hash') unless vector_store.is_a?(Hash)
+            raise_arugment_error('vector_store must have a table_name') unless vector_store[:table_name]
+            raise_arugment_error('vector_store must have a embedding_column_name') unless vector_store[:embedding_column_name]
+            raise_arugment_error('vector_store must have a content_column_name') unless vector_store[:content_column_name]
+            raise_argument_error('missing DATABASE_URL') unless vector_store[:database_url]
 
-          vector_store[:database_url]
-        end
+            vector_store[:database_url]
+          end
 
-        def test_db(db_url)
-          conn = ::PG::Connection.new(db_url)
+          def test_db(db_url)
+            conn = ::PG::Connection.new(db_url)
 
-          check_db_connection(conn)
-          check_vector_extension(conn)
-          check_table_exists(conn, vector_store[:table_name])
-          check_column_exists(conn)
+            check_db_connection(conn)
+            check_vector_extension(conn)
+            check_table_exists(conn, vector_store[:table_name])
+            check_column_exists(conn)
 
-          @table_name = vector_store[:table_name]
-          @embedding_column_name = vector_store[:embedding_column_name]
-          @content_column_name = vector_store[:content_column_name]
+            @table_name = vector_store[:table_name]
+            @embedding_column_name = vector_store[:embedding_column_name]
+            @content_column_name = vector_store[:content_column_name]
 
-          conn
-        rescue PG::Error, PG::UndefinedTable, NameError => e
-          raise_argument_error(e.message)
-        end
+            conn
+          rescue PG::Error, PG::UndefinedTable, NameError => e
+            raise_argument_error(e.message)
+          end
 
-        def check_db_connection(conn)
-          return if conn.status == PG::CONNECTION_OK
+          def check_db_connection(conn)
+            return if conn.status == PG::CONNECTION_OK
 
-          raise_argument_error("PostgreSQL connection is not ok")
-        end
+            raise_argument_error("PostgreSQL connection is not ok")
+          end
 
-        def check_vector_extension(conn)
-          return if conn.exec("SELECT 1 FROM pg_extension WHERE extname = 'vector'").any?
+          def check_vector_extension(conn)
+            return if conn.exec("SELECT 1 FROM pg_extension WHERE extname = 'vector'").any?
 
-          raise_argument_error("PostgreSQL 'vector' extension is not installed")
-        end
+            raise_argument_error("PostgreSQL 'vector' extension is not installed")
+          end
 
-        def check_table_exists(conn, table_name)
-          table_exists = conn.exec_params(
-            "SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = $1)", [table_name]
-          ).getvalue(0, 0) == "t"
-          return if table_exists
+          def check_table_exists(conn, table_name)
+            table_exists = conn.exec_params(
+              "SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = $1)", [table_name]
+            ).getvalue(0, 0) == "t"
+            return if table_exists
 
-          raise_argument_error("Table '#{table_name}' does not exist")
-        end
+            raise_argument_error("Table '#{table_name}' does not exist")
+          end
 
-        def check_column_exists(conn)
-          column_names = %i[embedding_column_name content_column_name]
-          table_name = vector_store[:table_name]
+          def check_column_exists(conn)
+            column_names = %i[embedding_column_name content_column_name]
+            table_name = vector_store[:table_name]
 
-          column_names.each do |target|
-            column_name = vector_store[target]
-            column_exists = conn.exec_params(
-              "SELECT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name = $1 AND column_name = $2)",
-              [table_name, column_name]
-            ).getvalue(0, 0) == "t"
-            next if column_exists
+            column_names.each do |target|
+              column_name = vector_store[target]
+              column_exists = conn.exec_params(
+                "SELECT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name = $1 AND column_name = $2)",
+                [table_name, column_name]
+              ).getvalue(0, 0) == "t"
+              next if column_exists
 
-            raise_argument_error("Column '#{column_name}' does not exist in table '#{table_name}'")
+              raise_argument_error("Column '#{column_name}' does not exist in table '#{table_name}'")
+            end
+          end
+
+          def search(query_vector, num_neighbors)
+            sql = <<-SQL
+              SELECT *, #{embedding_column_name} <-> $1 AS distance FROM #{table_name}
+              ORDER BY #{embedding_column_name} <-> $1
+              LIMIT #{num_neighbors}
+            SQL
+            result = db_connection.exec_params(sql, [query_vector.to_s]).to_a
+            return [] if result.empty?
+
+            result.map { |hash| hash.transform_keys(&:to_sym) }
+                  .map do |item|
+                    {
+                      document: Boxcars::VectorStore::Document.new(
+                        content: item[:content],
+                        embedding: JSON.parse(item[:embedding]),
+                        metadata: JSON.parse(item[:metadata], symbolize_names: true)
+                      ),
+                      distance: item[:distance].to_f
+                    }
+                  end
+          rescue StandardError => e
+            raise_argument_error("Error searching for #{query_vector}: #{e.message}")
+          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
 
-        def search(query_vector, num_neighbors)
-          sql = <<-SQL
-            SELECT *, #{embedding_column_name} <-> $1 AS distance FROM #{table_name}
-            ORDER BY #{embedding_column_name} <-> $1
-            LIMIT #{num_neighbors}
-          SQL
-          result = db_connection.exec_params(sql, [query_vector.to_s]).to_a
-          return [] if result.empty?
-
-          result.map { |hash| hash.transform_keys(&:to_sym) }
-                .map do |item|
-                  {
-                    document: Boxcars::VectorStore::Document.new(
-                      content: item[:content],
-                      embedding: JSON.parse(item[:embedding]),
-                      metadata: JSON.parse(item[:metadata], symbolize_names: true)
-                    ),
-                    distance: item[:distance].to_f
-                  }
-                end
-        rescue StandardError => e
-          raise_argument_error("Error searching for #{query_vector}: #{e.message}")
+        class Search
+          def initialize(*_args)
+            raise PgvectorNotAvailableError
+          end
+
+          def call(*_args)
+            raise PgvectorNotAvailableError
+          end
         end
       end
     end

data/lib/boxcars/vector_store.rb

@@ -6,8 +6,8 @@ module Boxcars
     module ClassMethods
       VectorStoreError = Class.new(StandardError)
 
-      def call(*args, **kw_args)
-        new(*args, **kw_args).call
+      def call(*, **kw_args)
+        new(*, **kw_args).call
       end
     end
 
@@ -24,7 +24,7 @@ module Boxcars
 
       embeddings_method[:klass]
         .call(
-          texts: texts, client: embeddings_method[:client]
+          texts:, client: embeddings_method[:client]
         )
         .map { |item| item.transform_keys(&:to_sym) }
     end
@@ -42,7 +42,7 @@ module Boxcars
     # @param openai_access_token [String] the OpenAI access token
     # @return [OpenAI::Client]
     def openai_client(openai_access_token: nil)
-      @openai_client ||= Openai.open_ai_client(openai_access_token: openai_access_token)
+      @openai_client ||= Openai.open_ai_client(openai_access_token:)
     end
 
     def raise_argument_error(message)

data/lib/boxcars/version.rb

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

data/lib/boxcars.rb

@@ -27,8 +27,9 @@ module Boxcars
 
   # Configuration contains gem settings
   class Configuration
-    attr_writer :openai_access_token, :serpapi_api_key, :groq_api_key, :cerebras_api_key
-    attr_accessor :organization_id, :logger, :log_prompts, :log_generated, :default_train, :default_engine
+    attr_writer :openai_access_token, :serpapi_api_key, :groq_api_key, :cerebras_api_key, :perplexity_api_key
+    attr_accessor :organization_id, :logger, :log_prompts, :log_generated, :default_train, :default_engine, :default_model,
+                  :observability_backend
 
     def initialize
       @organization_id = nil
@@ -77,6 +78,11 @@ module Boxcars
       key_lookup(:together_api_key, kwargs)
     end
 
+    # @return [String] The Perplexity API key either from arg or env.
+    def perplexity_api_key(**kwargs)
+      key_lookup(:perplexity_api_key, kwargs)
+    end
+
     private
 
     def check_key(key, val)
@@ -155,8 +161,8 @@ module Boxcars
 
   # Logging system
   # debug log
-  def self.debug(msg, color = nil, **options)
-    msg = colorize(msg.to_s, color, **options) if color
+  def self.debug(msg, color = nil, **)
+    msg = colorize(msg.to_s, color, **) if color
     log << msg
     if logger
       logger.debug(msg)
@@ -166,8 +172,8 @@ module Boxcars
   end
 
   # info log
-  def self.info(msg, color = nil, **options)
-    msg = colorize(msg.to_s, color, **options) if color
+  def self.info(msg, color = nil, **)
+    msg = colorize(msg.to_s, color, **) if color
     log << msg
     if logger
       logger.info(msg)
@@ -177,8 +183,8 @@ module Boxcars
   end
 
   # warn log
-  def self.warn(msg, color = nil, **options)
-    msg = colorize(msg.to_s, color, **options) if color
+  def self.warn(msg, color = nil, **)
+    msg = colorize(msg.to_s, color, **) if color
     log << msg
     if logger
       logger.warn(msg)
@@ -188,8 +194,8 @@ module Boxcars
   end
 
   # error log
-  def self.error(msg, color = nil, **options)
-    msg = colorize(msg.to_s, color, **options) if color
+  def self.error(msg, color = nil, **)
+    msg = colorize(msg.to_s, color, **) if color
     log << msg
     if logger
       logger.error(msg)
@@ -211,13 +217,18 @@ module Boxcars
   end
 end
 
-require "boxcars/version"
-require "boxcars/x_node"
-require "boxcars/prompt"
-require "boxcars/conversation_prompt"
-require "boxcars/conversation"
-require "boxcars/generation"
-require "boxcars/ruby_repl"
-require "boxcars/engine"
-require "boxcars/boxcar"
-require "boxcars/train"
+require_relative "boxcars/version"
+require_relative "boxcars/observability_backend"
+require_relative "boxcars/observability"
+# If users want it, they can require 'boxcars/observability_backends/multi_backend'
+require_relative "boxcars/x_node"
+require_relative "boxcars/prompt"
+require_relative "boxcars/conversation_prompt"
+require_relative "boxcars/conversation"
+require_relative "boxcars/generation"
+require_relative "boxcars/ruby_repl"
+require_relative "boxcars/result"
+require_relative "boxcars/engine"
+require_relative "boxcars/boxcar"
+require_relative "boxcars/train"
+require_relative "boxcars/engines"

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: boxcars
 version: !ruby/object:Gem::Version
-  version: 0.7.6
+  version: 0.8.0
 platform: ruby
 authors:
 - Francis Sullivan
 - Tabrez Syed
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google_search_results
@@ -81,20 +80,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.18'
-- !ruby/object:Gem::Dependency
-  name: pgvector
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: ruby-anthropic
   requirement: !ruby/object:Gem::Requirement
@@ -140,6 +125,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
+- POSTHOG_TEST_README.md
 - README.md
 - Rakefile
 - bin/console
@@ -177,7 +163,13 @@ files:
 - lib/boxcars/engine/openai.rb
 - lib/boxcars/engine/perplexityai.rb
 - lib/boxcars/engine/together.rb
+- lib/boxcars/engine/unified_observability.rb
+- lib/boxcars/engines.rb
 - lib/boxcars/generation.rb
+- lib/boxcars/observability.rb
+- lib/boxcars/observability_backend.rb
+- lib/boxcars/observability_backends/multi_backend.rb
+- lib/boxcars/observability_backends/posthog_backend.rb
 - lib/boxcars/observation.rb
 - lib/boxcars/prompt.rb
 - lib/boxcars/result.rb
@@ -216,7 +208,6 @@ metadata:
   source_code_uri: https://github.com/BoxcarsAI/boxcars
   changelog_uri: https://github.com/BoxcarsAI/boxcars/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -224,15 +215,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Boxcars is a gem that enables you to create new systems with AI composability.
   Inspired by python langchain.