exa-ai-ruby 1.0.0

data/lib/exa/responses/webset_response.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Exa
+  module Responses
+    class Webset < T::Struct
+      const :id, String
+      const :object, T.nilable(String)
+      const :status, T.nilable(String)
+      const :external_id, T.nilable(String)
+      const :title, T.nilable(String)
+      const :searches, T::Array[T.untyped]
+      const :imports, T::Array[T.untyped]
+      const :enrichments, T::Array[T.untyped]
+      const :monitors, T::Array[T.untyped]
+      const :streams, T::Array[T.untyped]
+      const :metadata, T.nilable(T::Hash[String, String])
+      const :created_at, T.nilable(String)
+      const :updated_at, T.nilable(String)
+      const :raw, T::Hash[Symbol, T.untyped]
+
+      def self.from_hash(hash)
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          id: sym[:id],
+          object: sym[:object],
+          status: sym[:status],
+          external_id: sym[:externalId],
+          title: sym[:title],
+          searches: Array(sym[:searches]),
+          imports: Array(sym[:imports]),
+          enrichments: Array(sym[:enrichments]),
+          monitors: Array(sym[:monitors]),
+          streams: Array(sym[:streams]),
+          metadata: Helpers.stringify_string_hash(sym[:metadata]),
+          created_at: sym[:createdAt],
+          updated_at: sym[:updatedAt],
+          raw: sym
+        )
+      end
+    end
+
+    class WebsetListResponse < T::Struct
+      const :data, T::Array[Webset]
+      const :has_more, T.nilable(T::Boolean)
+      const :next_cursor, T.nilable(String)
+
+      def self.from_hash(hash)
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          data: Array(sym[:data]).map { Webset.from_hash(_1) },
+          has_more: sym[:hasMore],
+          next_cursor: sym[:nextCursor]
+        )
+      end
+    end
+
+    class WebsetItem < T::Struct
+      const :id, String
+      const :object, T.nilable(String)
+      const :source, T.nilable(String)
+      const :source_id, T.nilable(String)
+      const :webset_id, T.nilable(String)
+      const :properties, T.nilable(T::Hash[Symbol, T.untyped])
+      const :evaluations, T::Array[T.untyped]
+      const :enrichments, T.nilable(T::Array[T.untyped])
+      const :created_at, T.nilable(String)
+      const :updated_at, T.nilable(String)
+      const :raw, T::Hash[Symbol, T.untyped]
+
+      def self.from_hash(hash)
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          id: sym[:id],
+          object: sym[:object],
+          source: sym[:source],
+          source_id: sym[:sourceId],
+          webset_id: sym[:websetId],
+          properties: sym[:properties].is_a?(Hash) ? Helpers.symbolize_keys(sym[:properties]) : sym[:properties],
+          evaluations: Array(sym[:evaluations]),
+          enrichments: sym[:enrichments]&.map { Helpers.symbolize_keys(_1) },
+          created_at: sym[:createdAt],
+          updated_at: sym[:updatedAt],
+          raw: sym
+        )
+      end
+    end
+
+    class WebsetItemListResponse < T::Struct
+      const :data, T::Array[WebsetItem]
+      const :has_more, T.nilable(T::Boolean)
+      const :next_cursor, T.nilable(String)
+
+      def self.from_hash(hash)
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          data: Array(sym[:data]).map { WebsetItem.from_hash(_1) },
+          has_more: sym[:hasMore],
+          next_cursor: sym[:nextCursor]
+        )
+      end
+    end
+
+    class WebsetEnrichment < T::Struct
+      const :id, String
+      const :object, T.nilable(String)
+      const :status, T.nilable(String)
+      const :webset_id, T.nilable(String)
+      const :title, T.nilable(String)
+      const :description, T.nilable(String)
+      const :format, T.nilable(String)
+      const :options, T.nilable(T::Array[T::Hash[Symbol, T.untyped]])
+      const :metadata, T.nilable(T::Hash[String, String])
+      const :created_at, T.nilable(String)
+      const :updated_at, T.nilable(String)
+      const :raw, T::Hash[Symbol, T.untyped]
+
+      def self.from_hash(hash)
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          id: sym[:id],
+          object: sym[:object],
+          status: sym[:status],
+          webset_id: sym[:websetId],
+          title: sym[:title],
+          description: sym[:description],
+          format: sym[:format],
+          options: sym[:options]&.map { Helpers.symbolize_keys(_1) },
+          metadata: Helpers.stringify_string_hash(sym[:metadata]),
+          created_at: sym[:createdAt],
+          updated_at: sym[:updatedAt],
+          raw: sym
+        )
+      end
+    end
+  end
+end

data/lib/exa/responses.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "responses/helpers"
+require_relative "responses/result"
+require_relative "responses/search_response"
+require_relative "responses/contents_response"
+require_relative "responses/monitor_response"
+require_relative "responses/event_response"
+require_relative "responses/webhook_response"
+require_relative "responses/import_response"
+require_relative "responses/webset_response"
+require_relative "responses/research_response"
+require_relative "responses/raw_response"

data/lib/exa/types/answer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Exa
+  module Types
+    class AnswerSearchOptions < T::Struct
+      include StructWrapper
+      include SearchOptionProps
+    end
+
+    class AnswerSummaryOptions < T::Struct
+      include StructWrapper
+      const :schema, T.nilable(T.untyped)
+    end
+
+    class AnswerRequest < T::Struct
+      include StructWrapper
+      const :query, String
+      const :summary, T.nilable(AnswerSummaryOptions)
+      const :search_options, T.nilable(AnswerSearchOptions)
+
+      def to_payload
+        payload = Serializer.to_payload(self)
+        if payload["searchOptions"].is_a?(Hash)
+          payload["searchOptions"] = payload["searchOptions"].merge("query" => query)
+        end
+        payload
+      end
+    end
+  end
+end

data/lib/exa/types/base.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Exa
+  module Types
+    module Serializer
+      module_function
+
+      def to_payload(value)
+        schema_payload = Exa::Types::Schema.maybe_convert(value)
+        return schema_payload unless schema_payload.nil?
+
+        case value
+        when StructWrapper
+          value.__exa_attributes__
+        when ::T::Struct
+          serialize_struct(value)
+        when Hash
+          serialize_hash(value)
+        when Array
+          value.map { to_payload(_1) }
+        when Symbol
+          value.to_s
+        when T::Enum
+          value.serialize.to_s
+        else
+          value
+        end
+      end
+
+      def serialize_struct(struct)
+        struct.serialize.each_with_object({}) do |(key, val), acc|
+          next if val.nil?
+          method_name = key.to_sym
+          raw_value = struct.respond_to?(method_name) ? struct.public_send(method_name) : nil
+          schema_value = Exa::Types::Schema.maybe_convert(raw_value)
+          acc[camelize(method_name)] = schema_value.nil? ? to_payload(val) : schema_value
+        end
+      end
+
+      def serialize_hash(hash)
+        hash.each_with_object({}) do |(key, val), acc|
+          next if val.nil?
+          acc[camelize(key)] = to_payload(val)
+        end
+      end
+
+      def camelize(sym)
+        key = sym.to_s
+        return key if key.include?("$")
+        parts = key.split("_")
+        return key if parts.length == 1
+        parts.first + parts[1..].map(&:capitalize).join
+      end
+    end
+
+    module StructWrapper
+      def to_payload
+        Serializer.to_payload(self)
+      end
+
+      def __exa_attributes__
+        Serializer.serialize_struct(self)
+      end
+    end
+  end
+end

data/lib/exa/types/contents.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Exa
+  module Types
+    class ContentsRequest < T::Struct
+      include StructWrapper
+      const :urls, T::Array[String]
+      const :text, T.nilable(T.any(T::Boolean, TextContentsOptions))
+      const :highlights, T.nilable(T.any(T::Boolean, HighlightsContentsOptions))
+      const :summary, T.nilable(T.any(T::Boolean, SummaryContentsOptions))
+      const :context, T.nilable(T.any(T::Boolean, ContextOptions))
+      const :metadata, T.nilable(T::Boolean)
+      const :livecrawl_timeout, T.nilable(Integer)
+      const :livecrawl, T.nilable(LivecrawlMode)
+      const :filter_empty_results, T.nilable(T::Boolean)
+      const :subpages, T.nilable(Integer)
+      const :subpage_target, T.nilable(T.any(String, T::Array[String]))
+      const :extras, T.nilable(ExtrasOptions)
+
+      def to_payload
+        Serializer.to_payload(self)
+      end
+    end
+  end
+end

data/lib/exa/types/enums.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Exa
+  module Types
+    class SearchType < T::Enum
+      enums do
+        Keyword = new(:keyword)
+        Neural = new(:neural)
+        Hybrid = new(:hybrid)
+        Fast = new(:fast)
+        Deep = new(:deep)
+        Auto = new(:auto)
+      end
+    end
+
+    class Category < T::Enum
+      enums do
+        Company = new(:company)
+        ResearchPaper = new(:research_paper)
+        News = new(:news)
+        Pdf = new(:pdf)
+        Github = new(:github)
+        Tweet = new(:tweet)
+        PersonalSite = new(:personal_site)
+        LinkedinProfile = new(:linkedin_profile)
+        FinancialReport = new(:financial_report)
+      end
+    end
+
+    class LivecrawlMode < T::Enum
+      enums do
+        Never = new(:never)
+        Fallback = new(:fallback)
+        Always = new(:always)
+        Auto = new(:auto)
+        Preferred = new(:preferred)
+      end
+    end
+
+    class ResearchModel < T::Enum
+      enums do
+        Fast = new(:"exa-research-fast")
+        Standard = new(:"exa-research-standard")
+      end
+    end
+  end
+end

data/lib/exa/types/find_similar.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Exa
+  module Types
+    class FindSimilarRequest < T::Struct
+      include StructWrapper
+      const :url, String
+      const :num_results, T.nilable(Integer)
+      const :include_domains, T.nilable(T::Array[String])
+      const :exclude_domains, T.nilable(T::Array[String])
+      const :start_crawl_date, T.nilable(String)
+      const :end_crawl_date, T.nilable(String)
+      const :start_published_date, T.nilable(String)
+      const :end_published_date, T.nilable(String)
+      const :include_text, T.nilable(T::Array[String])
+      const :exclude_text, T.nilable(T::Array[String])
+      const :exclude_source_domain, T.nilable(T::Boolean)
+      const :category, T.nilable(Category)
+      const :flags, T.nilable(T::Array[String])
+
+      def to_payload
+        Serializer.to_payload(self)
+      end
+    end
+  end
+end

data/lib/exa/types/research.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Exa
+  module Types
+    class ResearchCreateRequest < T::Struct
+      include StructWrapper
+      const :instructions, String
+      const :model, T.nilable(ResearchModel)
+      const :output_schema, T.nilable(T.untyped)
+      const :events, T.nilable(T::Boolean)
+      const :stream, T.nilable(T::Boolean)
+
+      def to_payload
+        Serializer.to_payload(self)
+      end
+    end
+  end
+end

data/lib/exa/types/schema.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Exa
+  module Types
+    module Schema
+      module_function
+
+      HAS_DSPY_SCHEMA = begin
+        require "dspy/schema"
+        true
+      rescue LoadError
+        false
+      end
+
+      def to_json_schema(type)
+        ensure_converter!
+        DSPy::TypeSystem::SorbetJsonSchema.type_to_json_schema(type)
+      end
+
+      def maybe_convert(value)
+        return nil if value.nil?
+        return value if value.is_a?(Hash)
+        return nil unless HAS_DSPY_SCHEMA
+
+        if struct_class?(value)
+          to_json_schema(value)
+        elsif type_alias?(value)
+          to_json_schema(value)
+        elsif sorbet_type_object?(value)
+          to_json_schema(value)
+        else
+          nil
+        end
+      end
+
+      def struct_class?(value)
+        value.is_a?(Class) && !value.name.nil? && (value < T::Struct || value < T::Enum)
+      end
+
+      def type_alias?(value)
+        defined?(T::Private::Types::TypeAlias) && value.is_a?(T::Private::Types::TypeAlias)
+      end
+
+      def sorbet_type_object?(value)
+        defined?(T::Types::Base) && value.is_a?(T::Types::Base)
+      end
+
+      def ensure_converter!
+        return if HAS_DSPY_SCHEMA
+
+        raise NotImplementedError,
+              "Sorbet JSON Schema converter not available. Install dspy-schema to enable this feature."
+      end
+    end
+  end
+end

data/lib/exa/types/search.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Exa
+  module Types
+    module SearchOptionProps
+      def self.included(base)
+        base.const :num_results, T.nilable(Integer)
+        base.const :include_domains, T.nilable(T::Array[String])
+        base.const :exclude_domains, T.nilable(T::Array[String])
+        base.const :start_crawl_date, T.nilable(String)
+        base.const :end_crawl_date, T.nilable(String)
+        base.const :start_published_date, T.nilable(String)
+        base.const :end_published_date, T.nilable(String)
+        base.const :include_text, T.nilable(T::Array[String])
+        base.const :exclude_text, T.nilable(T::Array[String])
+        base.const :use_autoprompt, T.nilable(T::Boolean)
+        base.const :type, T.nilable(SearchType)
+        base.const :category, T.nilable(Category)
+        base.const :flags, T.nilable(T::Array[String])
+        base.const :moderation, T.nilable(T::Boolean)
+        base.const :user_location, T.nilable(String)
+        base.const :livecrawl, T.nilable(LivecrawlMode)
+        base.const :livecrawl_timeout, T.nilable(Integer)
+        base.const :subpages, T.nilable(Integer)
+        base.const :subpage_target, T.nilable(T.any(String, T::Array[String]))
+        base.const :extras, T.nilable(ExtrasOptions)
+        base.const :text, T.nilable(T.any(T::Boolean, TextContentsOptions))
+        base.const :highlights, T.nilable(T.any(T::Boolean, HighlightsContentsOptions))
+        base.const :summary, T.nilable(T.any(T::Boolean, SummaryContentsOptions))
+        base.const :context, T.nilable(T.any(T::Boolean, ContextOptions))
+      end
+    end
+
+    class TextContentsOptions < T::Struct
+      include StructWrapper
+      const :max_characters, T.nilable(Integer)
+      const :include_html_tags, T.nilable(T::Boolean)
+    end
+
+    class HighlightsContentsOptions < T::Struct
+      include StructWrapper
+      const :query, T.nilable(String)
+      const :num_sentences, T.nilable(Integer)
+      const :highlights_per_url, T.nilable(Integer)
+    end
+
+    class SummaryContentsOptions < T::Struct
+      include StructWrapper
+      const :query, T.nilable(String)
+      const :schema, T.nilable(T.untyped)
+    end
+
+    class ContextOptions < T::Struct
+      include StructWrapper
+      const :max_characters, T.nilable(Integer)
+    end
+
+    class ExtrasOptions < T::Struct
+      include StructWrapper
+      const :links, T.nilable(Integer)
+      const :image_links, T.nilable(Integer)
+    end
+
+    class SearchRequest < T::Struct
+      include StructWrapper
+      include SearchOptionProps
+      const :query, String
+
+      def to_payload
+        Serializer.to_payload(self)
+      end
+    end
+  end
+end

data/lib/exa/types.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "types/base"
+require_relative "types/enums"
+require_relative "types/search"
+require_relative "types/find_similar"
+require_relative "types/contents"
+require_relative "types/answer"
+require_relative "types/research"
+require_relative "types/schema"

data/lib/exa/version.rb

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

data/lib/exa.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "exa/version"
+require_relative "exa/errors"
+require_relative "exa/internal/util"
+require_relative "exa/internal/transport/pooled_net_requester"
+require_relative "exa/internal/transport/base_client"
+require_relative "exa/internal/transport/stream"
+require_relative "exa/client"
+require_relative "exa/types"
+require_relative "exa/responses"
+require_relative "exa/resources"