exa-ai 0.6.0 → 0.7.1

data/lib/exa/cli/formatters/webset_item_formatter.rb

@@ -9,7 +9,7 @@ module Exa
           when "json"
             JSON.generate(item)
           when "pretty"
-            JSON.pretty_generate(item)
+            format_as_pretty(item)
           when "text"
             format_as_text(item)
           when "toon"
@@ -19,21 +19,42 @@ module Exa
           end
         end
 
-        def self.format_collection(items, output_format)
+        def self.format_collection(collection, output_format)
           case output_format
           when "json"
-            JSON.generate(items)
+            JSON.generate(collection.to_h)
           when "pretty"
-            JSON.pretty_generate(items)
+            format_collection_as_pretty(collection)
           when "text"
-            format_collection_as_text(items)
+            format_collection_as_text(collection)
           when "toon"
-            Exa::CLI::Base.encode_as_toon(items)
+            Exa::CLI::Base.encode_as_toon(collection.to_h)
           else
             raise ArgumentError, "Unknown output format: #{output_format}"
           end
         end
 
+        def self.format_as_pretty(item)
+          lines = []
+          lines << "Item ID:       #{item['id']}"
+          lines << "URL:           #{item['url']}" if item['url']
+          lines << "Title:         #{item['title']}" if item['title']
+          lines << "Status:        #{item['status']}" if item['status']
+          lines << "Created:       #{item['createdAt']}" if item['createdAt']
+          lines << "Updated:       #{item['updatedAt']}" if item['updatedAt']
+
+          if item['entity']
+            lines << ""
+            lines << "Entity:"
+            lines << "  Type:        #{item['entity']['type']}" if item['entity']['type']
+            lines << "  Name:        #{item['entity']['name']}" if item['entity']['name']
+            lines << "  Description: #{item['entity']['description']}" if item['entity']['description']
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_pretty
+
         def self.format_as_text(item)
           lines = []
           lines << "Item: #{item['id']}"
@@ -53,9 +74,41 @@ module Exa
         end
         private_class_method :format_as_text
 
-        def self.format_collection_as_text(items)
-          lines = ["Items (#{items.length} total):"]
-          items.each_with_index do |item, idx|
+        def self.format_collection_as_pretty(collection)
+          lines = []
+          lines << "Webset Items (#{collection.data.length} items)"
+
+          if collection.has_more
+            lines << "Next Cursor:   #{collection.next_cursor}"
+          end
+
+          lines << ""
+
+          collection.data.each_with_index do |item, idx|
+            lines << "" if idx > 0  # Blank line between items
+
+            lines << "Item ID:       #{item['id']}"
+            lines << "URL:           #{item['url']}" if item['url']
+            lines << "Title:         #{item['title']}" if item['title']
+            lines << "Status:        #{item['status']}" if item['status']
+            lines << "Created:       #{item['createdAt']}" if item['createdAt']
+            lines << "Updated:       #{item['updatedAt']}" if item['updatedAt']
+
+            if item['entity']
+              entity_name = item['entity']['name']
+              entity_type = item['entity']['type']
+              lines << "Entity:        #{entity_name}" if entity_name
+              lines << "Entity Type:   #{entity_type}" if entity_type && !entity_name
+            end
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_pretty
+
+        def self.format_collection_as_text(collection)
+          lines = ["Webset Items (#{collection.data.length} items):"]
+          collection.data.each_with_index do |item, idx|
             lines << "\n#{idx + 1}. #{item['id']}"
             lines << "   URL: #{item['url']}" if item['url']
             lines << "   Title: #{item['title']}" if item['title']
@@ -64,6 +117,11 @@ module Exa
               lines << "   Entity: #{item['entity']['name']}"
             end
           end
+
+          if collection.has_more
+            lines << "\nMore available (cursor: #{collection.next_cursor})"
+          end
+
           lines.join("\n")
         end
         private_class_method :format_collection_as_text

data/lib/exa/cli/formatters/webset_search_formatter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class WebsetSearchFormatter
+        def self.format(search, format)
+          case format
+          when "json"
+            JSON.pretty_generate(search.to_h)
+          when "pretty"
+            format_pretty(search)
+          when "text"
+            format_text(search)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(search.to_h)
+          else
+            JSON.pretty_generate(search.to_h)
+          end
+        end
+
+        private
+
+        def self.format_pretty(search)
+          output = []
+          output << "Search ID:       #{search.id}"
+          output << "Status:          #{search.status}"
+          output << "Query:           #{search.query}"
+          output << "Entity Type:     #{search.entity&.[]('type') || 'N/A'}" if search.entity
+          output << "Count:           #{search.count}" if search.count
+          output << "Behavior:        #{search.behavior}"
+          output << "Recall:          #{search.recall}" if search.recall
+          output << "Created:         #{search.created_at}"
+          output << "Updated:         #{search.updated_at}"
+          output << "Progress:        #{search.progress}" if search.progress
+          output << ""
+
+          if search.canceled?
+            output << "Canceled:        #{search.canceled_at}"
+            output << "Cancel Reason:   #{search.canceled_reason}" if search.canceled_reason
+          end
+
+          output.join("\n")
+        end
+
+        def self.format_text(search)
+          [
+            "ID: #{search.id}",
+            "Status: #{search.status}",
+            "Query: #{search.query}",
+            "Behavior: #{search.behavior}"
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/exa/cli/search_parser.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    class SearchParser
+      VALID_SEARCH_TYPES = ["fast", "deep", "keyword", "auto"].freeze
+      VALID_CATEGORIES = [
+        "company", "research paper", "news", "pdf", "github",
+        "tweet", "personal site", "financial report", "people"
+      ].freeze
+
+      def self.parse(argv)
+        new(argv).parse
+      end
+
+      def initialize(argv)
+        @argv = argv
+        @args = {
+          output_format: "json",
+          api_key: nil
+        }
+      end
+
+      def parse
+        parse_arguments
+        validate_query
+        @args
+      end
+
+      private
+
+      def parse_arguments
+        query_parts = []
+        i = 0
+
+        while i < @argv.length
+          arg = @argv[i]
+          case arg
+          when "--num-results"
+            @args[:num_results] = @argv[i + 1].to_i
+            i += 2
+          when "--type"
+            search_type = @argv[i + 1]
+            validate_search_type(search_type)
+            @args[:type] = search_type
+            i += 2
+          when "--category"
+            category = @argv[i + 1]
+            validate_category(category)
+            @args[:category] = category
+            i += 2
+          when "--include-domains"
+            @args[:include_domains] = @argv[i + 1].split(",").map(&:strip)
+            i += 2
+          when "--exclude-domains"
+            @args[:exclude_domains] = @argv[i + 1].split(",").map(&:strip)
+            i += 2
+          when "--api-key"
+            @args[:api_key] = @argv[i + 1]
+            i += 2
+          when "--output-format"
+            @args[:output_format] = @argv[i + 1]
+            i += 2
+          when "--start-published-date"
+            @args[:start_published_date] = @argv[i + 1]
+            i += 2
+          when "--end-published-date"
+            @args[:end_published_date] = @argv[i + 1]
+            i += 2
+          when "--start-crawl-date"
+            @args[:start_crawl_date] = @argv[i + 1]
+            i += 2
+          when "--end-crawl-date"
+            @args[:end_crawl_date] = @argv[i + 1]
+            i += 2
+          when "--include-text"
+            @args[:include_text] ||= []
+            @args[:include_text] << @argv[i + 1]
+            i += 2
+          when "--exclude-text"
+            @args[:exclude_text] ||= []
+            @args[:exclude_text] << @argv[i + 1]
+            i += 2
+          when "--text"
+            @args[:text] = true
+            i += 1
+          when "--text-max-characters"
+            @args[:text_max_characters] = @argv[i + 1].to_i
+            i += 2
+          when "--include-html-tags"
+            @args[:include_html_tags] = true
+            i += 1
+          when "--summary"
+            @args[:summary] = true
+            i += 1
+          when "--summary-query"
+            @args[:summary_query] = @argv[i + 1]
+            i += 2
+          when "--summary-schema"
+            schema_arg = @argv[i + 1]
+            @args[:summary_schema] = if schema_arg.start_with?("@")
+                                      JSON.parse(File.read(schema_arg[1..]))
+                                    else
+                                      JSON.parse(schema_arg)
+                                    end
+            i += 2
+          when "--context"
+            @args[:context] = true
+            i += 1
+          when "--context-max-characters"
+            @args[:context_max_characters] = @argv[i + 1].to_i
+            i += 2
+          when "--subpages"
+            @args[:subpages] = @argv[i + 1].to_i
+            i += 2
+          when "--subpage-target"
+            @args[:subpage_target] ||= []
+            @args[:subpage_target] << @argv[i + 1]
+            i += 2
+          when "--links"
+            @args[:links] = @argv[i + 1].to_i
+            i += 2
+          when "--image-links"
+            @args[:image_links] = @argv[i + 1].to_i
+            i += 2
+          else
+            query_parts << arg
+            i += 1
+          end
+        end
+
+        @args[:query] = query_parts.join(" ")
+      end
+
+      def validate_query
+        raise ArgumentError, "Query is required" if @args[:query].nil? || @args[:query].empty?
+      end
+
+      def validate_search_type(search_type)
+        return if VALID_SEARCH_TYPES.include?(search_type)
+
+        raise ArgumentError, "Search type must be one of: #{VALID_SEARCH_TYPES.join(', ')}"
+      end
+
+      def validate_category(category)
+        return if VALID_CATEGORIES.include?(category)
+
+        raise ArgumentError, "Category must be one of: #{VALID_CATEGORIES.map { |c| "\"#{c}\"" }.join(', ')}"
+      end
+    end
+  end
+end

data/lib/exa/client.rb

@@ -122,32 +122,6 @@ module Exa
       Services::Context.new(connection, query: query, **params).call
     end
 
-    # Search for LinkedIn company pages
-    #
-    # Convenience method that restricts search to LinkedIn company profiles
-    # using keyword search for precise name matching.
-    #
-    # @param query [String] Company name to search
-    # @param params [Hash] Additional search parameters
-    # @option params [Integer] :numResults Number of results to return
-    # @return [Resources::SearchResult] LinkedIn company results
-    def linkedin_company(query, **params)
-      search(query, type: "keyword", includeDomains: ["linkedin.com/company"], **params)
-    end
-
-    # Search for LinkedIn profiles
-    #
-    # Convenience method that restricts search to LinkedIn individual profiles
-    # using keyword search for precise name matching.
-    #
-    # @param query [String] Person name to search
-    # @param params [Hash] Additional search parameters
-    # @option params [Integer] :numResults Number of results to return
-    # @return [Resources::SearchResult] LinkedIn profile results
-    def linkedin_person(query, **params)
-      search(query, type: "keyword", includeDomains: ["linkedin.com/in"], **params)
-    end
-
     # List all websets
     #
     # @param params [Hash] Pagination parameters
@@ -314,9 +288,12 @@ module Exa
     # List all items in a webset
     #
     # @param webset_id [String] Webset ID
-    # @return [Array<Hash>] Array of items
-    def list_items(webset_id:)
-      Services::Websets::ListItems.new(connection, webset_id: webset_id).call
+    # @param params [Hash] Pagination parameters
+    # @option params [String] :cursor Cursor for pagination
+    # @option params [Integer] :limit Maximum number of items to return (default: 20)
+    # @return [Resources::WebsetItemCollection] Paginated list of items
+    def list_items(webset_id:, **params)
+      Services::Websets::ListItems.new(connection, webset_id: webset_id, **params).call
     end
 
     # List all imports

data/lib/exa/constants/websets.rb

@@ -7,7 +7,7 @@ module Exa
       ENTITY_TYPES = %w[company person article research_paper custom].freeze
 
       # Valid enrichment formats
-      ENRICHMENT_FORMATS = %w[text date number options url].freeze
+      ENRICHMENT_FORMATS = %w[text date number options email phone url].freeze
 
       # Valid source types for imports and exclusions
       SOURCE_TYPES = %w[import webset].freeze

data/lib/exa/resources/webset_item_collection.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a paginated list of webset items from the Exa API
+    #
+    # This class wraps the JSON response from the GET /websets/v0/websets/{id}/items endpoint
+    # and provides pagination support.
+    class WebsetItemCollection < Struct.new(
+      :data,
+      :has_more,
+      :next_cursor,
+      keyword_init: true
+    )
+      def initialize(data:, has_more: false, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def to_h
+        {
+          data: data,
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

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

@@ -20,6 +20,7 @@ module Exa
             validate_exclude!(params[:exclude]) if params[:exclude]
             validate_external_id!(params[:externalId]) if params[:externalId]
             validate_metadata!(params[:metadata]) if params[:metadata]
+            validate_no_duplicate_ids_in_import_and_scope!(params)
           end
 
           private
@@ -184,6 +185,20 @@ module Exa
             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
+
+          def validate_no_duplicate_ids_in_import_and_scope!(params)
+            return unless params[:import] && params[:search] && params[:search][:scope]
+
+            import_ids = params[:import].map { |item| item[:id] }
+            scope_ids = params[:search][:scope].map { |item| item[:id] }
+
+            duplicates = import_ids & scope_ids
+
+            return if duplicates.empty?
+
+            raise ArgumentError,
+                  "Cannot use the same import/webset ID in both :import and search[:scope]: #{duplicates.join(', ')}"
+          end
         end
       end
     end

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

@@ -4,15 +4,21 @@ module Exa
   module Services
     module Websets
       class ListItems
-        def initialize(connection, webset_id:)
+        def initialize(connection, webset_id:, **params)
           @connection = connection
           @webset_id = webset_id
+          @params = params
         end
 
         def call
-          response = @connection.get("/websets/v0/websets/#{@webset_id}/items")
+          response = @connection.get("/websets/v0/websets/#{@webset_id}/items", @params)
           body = response.body
-          body["data"] || []
+
+          Resources::WebsetItemCollection.new(
+            data: body["data"] || [],
+            has_more: body["hasMore"] || false,
+            next_cursor: body["nextCursor"]
+          )
         end
       end
     end

data/lib/exa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exa
-  VERSION = "0.6.0"
+  VERSION = "0.7.1"
 end

data/lib/exa.rb

@@ -17,6 +17,7 @@ require_relative "exa/resources/webset"
 require_relative "exa/resources/webset_search"
 require_relative "exa/resources/webset_enrichment"
 require_relative "exa/resources/webset_enrichment_collection"
+require_relative "exa/resources/webset_item_collection"
 require_relative "exa/resources/import"
 require_relative "exa/resources/import_collection"
 require_relative "exa/resources/monitor"
@@ -67,6 +68,7 @@ require_relative "exa/cli/base"
 require_relative "exa/cli/polling"
 require_relative "exa/cli/error_handler"
 require_relative "exa/cli/formatters/search_formatter"
+require_relative "exa/cli/formatters/webset_search_formatter"
 require_relative "exa/cli/formatters/context_formatter"
 require_relative "exa/cli/formatters/contents_formatter"
 require_relative "exa/cli/formatters/research_formatter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Benjamin Jackson
@@ -135,6 +135,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: A Ruby gem for interacting with the Exa.ai search and discovery API
 email:
 - ben@hearmeout.co
@@ -206,7 +220,9 @@ files:
 - lib/exa/cli/formatters/search_formatter.rb
 - lib/exa/cli/formatters/webset_formatter.rb
 - lib/exa/cli/formatters/webset_item_formatter.rb
+- lib/exa/cli/formatters/webset_search_formatter.rb
 - lib/exa/cli/polling.rb
+- lib/exa/cli/search_parser.rb
 - lib/exa/client.rb
 - lib/exa/connection.rb
 - lib/exa/constants/websets.rb
@@ -229,6 +245,7 @@ files:
 - lib/exa/resources/webset_collection.rb
 - lib/exa/resources/webset_enrichment.rb
 - lib/exa/resources/webset_enrichment_collection.rb
+- lib/exa/resources/webset_item_collection.rb
 - lib/exa/resources/webset_search.rb
 - lib/exa/services/answer.rb
 - lib/exa/services/answer_stream.rb