exa-ai 0.3.0 → 0.4.0

data/lib/exa/resources/webset_enrichment.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a webset enrichment from the Exa API
+    #
+    # An enrichment extracts specific data from web entities in a webset.
+    class WebsetEnrichment < Struct.new(
+      :id,
+      :object,
+      :status,
+      :webset_id,
+      :title,
+      :description,
+      :format,
+      :options,
+      :instructions,
+      :metadata,
+      :created_at,
+      :updated_at,
+      keyword_init: true
+    )
+      def initialize(
+        id:,
+        object:,
+        status:,
+        webset_id: nil,
+        title: nil,
+        description: nil,
+        format: nil,
+        options: nil,
+        instructions: nil,
+        metadata: nil,
+        created_at: nil,
+        updated_at: nil
+      )
+        super
+        freeze
+      end
+
+      def pending?
+        status == "pending"
+      end
+
+      def running?
+        status == "running"
+      end
+
+      def completed?
+        status == "completed"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          status: status,
+          webset_id: webset_id,
+          title: title,
+          description: description,
+          format: format,
+          options: options,
+          instructions: instructions,
+          metadata: metadata,
+          created_at: created_at,
+          updated_at: updated_at
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/resources/webset_enrichment_collection.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a list of enrichments for a webset from the Exa API
+    #
+    # This class wraps the JSON response from the GET /websets/v0/websets/{id}/enrichments endpoint
+    class WebsetEnrichmentCollection < Struct.new(
+      :data,
+      keyword_init: true
+    )
+      def initialize(data:)
+        super
+        freeze
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def to_h
+        {
+          data: data
+        }
+      end
+    end
+  end
+end

data/lib/exa/resources/webset_search.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a search operation within a webset
+    #
+    # A search finds entities matching specific criteria and can either
+    # override existing webset items or append to them.
+    class WebsetSearch < Struct.new(
+      :id,
+      :object,
+      :status,
+      :webset_id,
+      :query,
+      :entity,
+      :criteria,
+      :count,
+      :behavior,
+      :exclude,
+      :scope,
+      :progress,
+      :recall,
+      :metadata,
+      :canceled_at,
+      :canceled_reason,
+      :created_at,
+      :updated_at,
+      keyword_init: true
+    )
+      def initialize(
+        id:,
+        object:,
+        status:,
+        webset_id: nil,
+        query: nil,
+        entity: nil,
+        criteria: nil,
+        count: nil,
+        behavior: nil,
+        exclude: nil,
+        scope: nil,
+        progress: nil,
+        recall: nil,
+        metadata: nil,
+        canceled_at: nil,
+        canceled_reason: nil,
+        created_at: nil,
+        updated_at: nil
+      )
+        super
+        freeze
+      end
+
+      # Status helper methods
+      def created?
+        status == "created"
+      end
+
+      def running?
+        status == "running"
+      end
+
+      def completed?
+        status == "completed"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      def canceled?
+        status == "canceled"
+      end
+
+      def in_progress?
+        created? || running?
+      end
+
+      # Behavior helper methods
+      def override?
+        behavior == "override"
+      end
+
+      def append?
+        behavior == "append"
+      end
+
+      def to_h
+        {
+          id: id,
+          object: object,
+          status: status,
+          webset_id: webset_id,
+          query: query,
+          entity: entity,
+          criteria: criteria,
+          count: count,
+          behavior: behavior,
+          exclude: exclude,
+          scope: scope,
+          progress: progress,
+          recall: recall,
+          metadata: metadata,
+          canceled_at: canceled_at,
+          canceled_reason: canceled_reason,
+          created_at: created_at,
+          updated_at: updated_at
+        }.compact
+      end
+    end
+  end
+end

data/lib/exa/services/parameter_converter.rb

@@ -35,6 +35,7 @@ module Exa
         when :end_crawl_date then :endCrawlDate
         when :include_text then :includeText
         when :exclude_text then :excludeText
+        when :external_id then :externalId
         else
           key
         end

data/lib/exa/services/websets/cancel.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class Cancel
+        def initialize(connection, id:)
+          @connection = connection
+          @id = id
+        end
+
+        def call
+          response = @connection.post("/websets/v0/websets/#{@id}/cancel", {})
+          body = response.body
+
+          Resources::Webset.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            external_id: body["externalId"],
+            title: body["title"],
+            searches: body["searches"],
+            imports: body["imports"],
+            enrichments: body["enrichments"],
+            monitors: body["monitors"],
+            excludes: body["excludes"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            items: body["items"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/cancel_enrichment.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class CancelEnrichment
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.post("/websets/v0/websets/#{@webset_id}/enrichments/#{@id}/cancel", {})
+          body = response.body
+
+          Resources::WebsetEnrichment.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            title: body["title"],
+            description: body["description"],
+            format: body["format"],
+            options: body["options"],
+            instructions: body["instructions"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/cancel_search.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class CancelSearch
+        def initialize(connection, webset_id:, id:)
+          @connection = connection
+          @webset_id = webset_id
+          @id = id
+        end
+
+        def call
+          response = @connection.post(
+            "/websets/v0/websets/#{@webset_id}/searches/#{@id}/cancel",
+            {}
+          )
+          body = response.body
+
+          Resources::WebsetSearch.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            query: body["query"],
+            entity: body["entity"],
+            criteria: body["criteria"],
+            count: body["count"],
+            behavior: body["behavior"],
+            exclude: body["exclude"],
+            scope: body["scope"],
+            progress: body["progress"],
+            recall: body["recall"],
+            metadata: body["metadata"],
+            canceled_at: body["canceledAt"],
+            canceled_reason: body["canceledReason"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/create.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "create_validator"
+require_relative "../websets_parameter_converter"
+
+module Exa
+  module Services
+    module Websets
+      class Create
+        def initialize(connection, **params)
+          @connection = connection
+          @params = params
+        end
+
+        def call
+          # Validate parameters before making the API call
+          CreateValidator.validate!(@params)
+
+          # Convert Ruby snake_case params to API camelCase
+          converted_params = WebsetsParameterConverter.convert(@params)
+
+          response = @connection.post("/websets/v0/websets", converted_params)
+          body = response.body
+
+          Resources::Webset.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            external_id: body["externalId"],
+            title: body["title"],
+            searches: body["searches"],
+            imports: body["imports"],
+            enrichments: body["enrichments"],
+            monitors: body["monitors"],
+            excludes: body["excludes"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"],
+            items: body["items"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/create_enrichment.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      class CreateEnrichment
+        def initialize(connection, webset_id:, **params)
+          @connection = connection
+          @webset_id = webset_id
+          @params = params
+        end
+
+        def call
+          response = @connection.post("/websets/v0/websets/#{@webset_id}/enrichments", @params)
+          body = response.body
+
+          Resources::WebsetEnrichment.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            title: body["title"],
+            description: body["description"],
+            format: body["format"],
+            options: body["options"],
+            instructions: body["instructions"],
+            metadata: body["metadata"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/create_search.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "create_search_validator"
+
+module Exa
+  module Services
+    module Websets
+      class CreateSearch
+        def initialize(connection, webset_id:, **params)
+          @connection = connection
+          @webset_id = webset_id
+          @params = params
+        end
+
+        def call
+          CreateSearchValidator.validate!(@params)
+
+          response = @connection.post(
+            "/websets/v0/websets/#{@webset_id}/searches",
+            @params
+          )
+          body = response.body
+
+          Resources::WebsetSearch.new(
+            id: body["id"],
+            object: body["object"],
+            status: body["status"],
+            webset_id: body["websetId"],
+            query: body["query"],
+            entity: body["entity"],
+            criteria: body["criteria"],
+            count: body["count"],
+            behavior: body["behavior"],
+            exclude: body["exclude"],
+            scope: body["scope"],
+            progress: body["progress"],
+            recall: body["recall"],
+            metadata: body["metadata"],
+            canceled_at: body["canceledAt"],
+            canceled_reason: body["canceledReason"],
+            created_at: body["createdAt"],
+            updated_at: body["updatedAt"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exa/services/websets/create_search_validator.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    module Websets
+      # Validates parameters for webset search creation
+      class CreateSearchValidator
+        VALID_ENTITY_TYPES = %w[company person article research_paper custom].freeze
+        VALID_BEHAVIORS = %w[override append].freeze
+        VALID_SOURCE_TYPES = %w[import webset].freeze
+
+        class << self
+          def validate!(params)
+            validate_query!(params[:query]) if params[:query]
+            validate_count!(params[:count]) if params[:count]
+            validate_entity!(params[:entity]) if params[:entity]
+            validate_criteria!(params[:criteria]) if params[:criteria]
+            validate_scope!(params[:scope]) if params[:scope]
+            validate_exclude!(params[:exclude]) if params[:exclude]
+            validate_behavior!(params[:behavior]) if params[:behavior]
+            validate_metadata!(params[:metadata]) if params[:metadata]
+          end
+
+          private
+
+          def validate_query!(query)
+            raise ArgumentError, "query must be a String" unless query.is_a?(String)
+            raise ArgumentError, "query cannot be empty" if query.strip.empty?
+            raise ArgumentError, "query cannot exceed 5000 characters" if query.length > 5000
+          end
+
+          def validate_count!(count)
+            raise ArgumentError, "count must be a positive Integer" unless count.is_a?(Integer) && count > 0
+          end
+
+          def validate_entity!(entity)
+            raise ArgumentError, "entity must be a Hash" unless entity.is_a?(Hash)
+            raise ArgumentError, "entity[:type] is required" unless entity[:type]
+
+            type = entity[:type]
+            unless VALID_ENTITY_TYPES.include?(type)
+              raise ArgumentError, "entity[:type] must be one of: #{VALID_ENTITY_TYPES.join(', ')}"
+            end
+
+            if type == "custom"
+              raise ArgumentError, "entity[:description] is required for custom entity type" unless entity[:description]
+              validate_string_length!(entity[:description], "entity[:description]", min: 2, max: 200)
+            end
+          end
+
+          def validate_criteria!(criteria)
+            raise ArgumentError, "criteria must be an Array" unless criteria.is_a?(Array)
+            raise ArgumentError, "criteria must have at least 1 item" if criteria.empty?
+            raise ArgumentError, "criteria cannot have more than 5 items" if criteria.length > 5
+
+            criteria.each_with_index do |criterion, index|
+              raise ArgumentError, "criteria[#{index}] must be a Hash" unless criterion.is_a?(Hash)
+              raise ArgumentError, "criteria[#{index}][:description] is required" unless criterion[:description]
+              validate_string_length!(criterion[:description], "criteria[#{index}][:description]", min: 1, max: 1000)
+            end
+          end
+
+          def validate_scope!(scope)
+            raise ArgumentError, "scope must be an Array" unless scope.is_a?(Array)
+
+            scope.each_with_index do |item, index|
+              validate_source_reference!(item, "scope[#{index}]")
+
+              next unless item[:relationship]
+
+              rel = item[:relationship]
+              raise ArgumentError, "scope[#{index}][:relationship] must be a Hash" unless rel.is_a?(Hash)
+              raise ArgumentError, "scope[#{index}][:relationship][:definition] is required" unless rel[:definition]
+              raise ArgumentError, "scope[#{index}][:relationship][:limit] is required" unless rel[:limit]
+
+              limit = rel[:limit]
+              unless limit.is_a?(Integer) && limit >= 1 && limit <= 10
+                raise ArgumentError, "scope[#{index}][:relationship][:limit] must be an Integer between 1 and 10"
+              end
+            end
+          end
+
+          def validate_exclude!(exclude)
+            raise ArgumentError, "exclude must be an Array" unless exclude.is_a?(Array)
+
+            exclude.each_with_index do |item, index|
+              validate_source_reference!(item, "exclude[#{index}]")
+            end
+          end
+
+          def validate_behavior!(behavior)
+            unless VALID_BEHAVIORS.include?(behavior)
+              raise ArgumentError, "behavior must be one of: #{VALID_BEHAVIORS.join(', ')}"
+            end
+          end
+
+          def validate_metadata!(metadata)
+            raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
+            metadata.each do |key, value|
+              raise ArgumentError, "metadata values must be Strings" unless value.is_a?(String)
+              raise ArgumentError, "metadata value for '#{key}' cannot exceed 1000 characters" if value.length > 1000
+            end
+          end
+
+          def validate_source_reference!(item, context)
+            raise ArgumentError, "#{context} must be a Hash" unless item.is_a?(Hash)
+            raise ArgumentError, "#{context}[:source] is required" unless item[:source]
+            raise ArgumentError, "#{context}[:id] is required" unless item[:id]
+
+            source = item[:source]
+            unless VALID_SOURCE_TYPES.include?(source)
+              raise ArgumentError, "#{context}[:source] must be one of: #{VALID_SOURCE_TYPES.join(', ')}"
+            end
+
+            raise ArgumentError, "#{context}[:id] must be a non-empty String" unless item[:id].is_a?(String) && !item[:id].empty?
+          end
+
+          def validate_string_length!(value, name, min: nil, max: nil)
+            raise ArgumentError, "#{name} must be a String" unless value.is_a?(String)
+            raise ArgumentError, "#{name} must be at least #{min} characters" if min && value.length < min
+            raise ArgumentError, "#{name} cannot exceed #{max} characters" if max && value.length > max
+          end
+        end
+      end
+    end
+  end
+end