exa-ai-ruby 1.0.0

data/lib/exa/internal/transport/stream.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Exa
+  module Internal
+    module Transport
+      class Stream
+        include Enumerable
+
+        def initialize(headers:, stream:)
+          @headers = headers
+          @stream = stream
+        end
+
+        def each(&blk)
+          return enum_for(__method__) unless block_given?
+          @stream.each(&blk)
+        end
+
+        def each_line(&blk)
+          return enum_for(__method__) unless block_given?
+          enumerator = Exa::Internal::Util.decode_lines(@stream)
+          begin
+            enumerator.each do |line|
+              yield line.chomp
+            end
+          ensure
+            close
+          end
+        end
+
+        def each_json_line(symbolize: true, &blk)
+          return enum_for(__method__, symbolize: symbolize) unless block_given?
+          each_line do |line|
+            next if line.strip.empty?
+            yield JSON.parse(line, symbolize_names: symbolize)
+          end
+        end
+
+        def each_event(&blk)
+          return enum_for(__method__) unless block_given?
+          sse = Exa::Internal::Util.decode_sse(@stream)
+          begin
+            sse.each do |event|
+              payload = event[:data]
+              payload = payload.chomp if payload
+              yield(event.merge(data: payload))
+            end
+          ensure
+            close
+          end
+        end
+
+        def each_event_json(symbolize: true, &blk)
+          return enum_for(__method__, symbolize: symbolize) unless block_given?
+          each_event do |event|
+            data = event[:data]
+            next if data.nil? || data.empty?
+            yield event.merge(data: JSON.parse(data, symbolize_names: symbolize))
+          end
+        end
+
+        def close
+          Exa::Internal::Util.close_fused!(@stream)
+        end
+
+        def content_type
+          @headers["content-type"]
+        end
+      end
+    end
+  end
+end

data/lib/exa/internal/util.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+require "set"
+
+module Exa
+  module Internal
+    module Util
+      JSON_CONTENT = %r{application/(json|problem\+json)}i.freeze
+      JSONL_CONTENT = %r{application/x-ndjson}i.freeze
+
+      module_function
+
+      def normalized_headers(headers)
+        headers.each_with_object({}) do |(key, value), acc|
+          next if value.nil?
+          acc[key.to_s.downcase] = value.to_s
+        end
+      end
+
+      def deep_merge_hash(base, extra)
+        return base unless extra
+        base.merge(extra) do |_k, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge_hash(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+
+      def build_query(query)
+        return nil if query.nil? || query.empty?
+        URI.encode_www_form(query)
+      end
+
+      def decode_content(headers, stream:)
+        case headers["content-type"]
+        when JSON_CONTENT
+          json = stream.to_a.join
+          JSON.parse(json, symbolize_names: true)
+        when JSONL_CONTENT
+          stream.map { JSON.parse(_1, symbolize_names: true) }
+        when /^text\/event-stream/
+          decode_sse(stream)
+        else
+          StringIO.new(stream.to_a.join)
+        end
+      end
+
+      def force_charset!(content_type, text:)
+        return text unless content_type
+        return text if text.encoding == Encoding::UTF_8
+        if (match = /charset=([^;]+)/i.match(content_type))
+          encoding = Encoding.find(match[1])
+          text.force_encoding(encoding)
+        end
+        text
+      rescue ArgumentError
+        text
+      end
+
+      def decode_lines(enum)
+        Enumerator.new do |y|
+          buffer = String.new
+          enum.each do |chunk|
+            buffer << chunk
+            while (idx = buffer.index(/\r?\n/))
+              y << buffer.slice!(0..idx)
+            end
+          end
+          y << buffer unless buffer.empty?
+        end
+      end
+
+      def decode_sse(enum)
+        lines = decode_lines(enum)
+        Enumerator.new do |y|
+          event = {event: nil, data: String.new, id: nil, retry: nil}
+          lines.each do |line|
+            stripped = line.strip
+            if stripped.empty?
+              y << event.dup if event[:data]&.length&.positive?
+              event = {event: nil, data: String.new, id: nil, retry: nil}
+              next
+            end
+
+            case stripped
+            when /^event:(.*)$/
+              event[:event] = Regexp.last_match(1).strip
+            when /^data:(.*)$/
+              event[:data] << Regexp.last_match(1).lstrip << "\n"
+            when /^id:(.*)$/
+              event[:id] = Regexp.last_match(1).strip
+            when /^retry:(\d+)$/
+              event[:retry] = Regexp.last_match(1).to_i
+            end
+          end
+        end
+      end
+
+      def fused_enum(enum, &on_close)
+        closed = false
+        wrapper = Enumerator.new do |y|
+          begin
+            enum.each { y << _1 }
+          ensure
+            unless closed
+              closed = true
+              on_close&.call
+            end
+          end
+        end
+
+        wrapper.define_singleton_method(:close) do
+          unless closed
+            closed = true
+            on_close&.call
+          end
+        end
+
+        wrapper
+      end
+
+      def close_fused!(enum)
+        if enum.respond_to?(:close)
+          enum.close
+        end
+      end
+    end
+  end
+end

data/lib/exa/resources/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client:)
+        @client = client
+      end
+
+      private
+
+      def serialize(struct_class, params)
+        case params
+        when struct_class
+          params.to_payload
+        when Hash
+          struct_class.new(**params).to_payload
+        else
+          raise ArgumentError, "Expected #{struct_class} or Hash, got #{params.class}"
+        end
+      end
+    end
+  end
+end

data/lib/exa/resources/events.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Exa
+  module Resources
+    class Events < Base
+      def list(params = nil)
+        client.request(
+          method: :get,
+          path: events_path,
+          query: params,
+          response_model: Exa::Responses::EventListResponse
+        )
+      end
+
+      def retrieve(event_id)
+        client.request(
+          method: :get,
+          path: events_path(event_id),
+          response_model: Exa::Responses::Event
+        )
+      end
+
+      private
+
+      def events_path(*parts)
+        ["v0", "events", *parts]
+      end
+    end
+  end
+end

data/lib/exa/resources/imports.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Exa
+  module Resources
+    class Imports < Base
+      def create(params)
+        client.request(
+          method: :post,
+          path: imports_path,
+          body: params,
+          response_model: Exa::Responses::ImportCreationResponse
+        )
+      end
+
+      def list(params = nil)
+        client.request(
+          method: :get,
+          path: imports_path,
+          query: params,
+          response_model: Exa::Responses::ImportListResponse
+        )
+      end
+
+      def retrieve(id)
+        client.request(
+          method: :get,
+          path: imports_path(id),
+          response_model: Exa::Responses::Import
+        )
+      end
+
+      def update(id, params)
+        client.request(
+          method: :patch,
+          path: imports_path(id),
+          body: params,
+          response_model: Exa::Responses::Import
+        )
+      end
+
+      def delete(id)
+        client.request(
+          method: :delete,
+          path: imports_path(id),
+          response_model: Exa::Responses::Import
+        )
+      end
+
+      private
+
+      def imports_path(*parts)
+        ["v0", "imports", *parts]
+      end
+    end
+  end
+end

data/lib/exa/resources/research.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Exa
+  module Resources
+    class Research < Base
+      def create(params)
+        payload = serialize(Exa::Types::ResearchCreateRequest, params)
+        client.request(
+          method: :post,
+          path: "research",
+          body: payload,
+          response_model: Exa::Responses::Research
+        )
+      end
+
+      def list(params = nil)
+        client.request(
+          method: :get,
+          path: "research",
+          query: params,
+          response_model: Exa::Responses::ResearchListResponse
+        )
+      end
+
+      def get(research_id, stream: false, events: nil)
+        query = {}
+        query[:events] = events unless events.nil?
+        query[:stream] = stream ? "true" : nil
+        response_model = stream ? nil : Exa::Responses::Research
+        client.request(
+          method: :get,
+          path: ["research", research_id],
+          query: query.compact,
+          stream: stream,
+          response_model: response_model
+        )
+      end
+
+      def cancel(research_id)
+        client.request(
+          method: :post,
+          path: ["research", research_id, "cancel"],
+          response_model: Exa::Responses::Research
+        )
+      end
+    end
+  end
+end

data/lib/exa/resources/search.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Exa
+  module Resources
+    class Search < Base
+      def search(params)
+        payload = serialize(Exa::Types::SearchRequest, params)
+        client.request(method: :post, path: "search", body: payload, response_model: Exa::Responses::SearchResponse)
+      end
+
+      def contents(params)
+        payload = serialize(Exa::Types::ContentsRequest, params)
+        client.request(method: :post, path: "contents", body: payload, response_model: Exa::Responses::ContentsResponse)
+      end
+
+      def find_similar(params)
+        payload = serialize(Exa::Types::FindSimilarRequest, params)
+        client.request(method: :post, path: "findSimilar", body: payload, response_model: Exa::Responses::FindSimilarResponse)
+      end
+
+      def answer(params)
+        normalized = normalize_nested_struct(params, :search_options, Exa::Types::AnswerSearchOptions)
+        payload = serialize(Exa::Types::AnswerRequest, normalized)
+        client.request(method: :post, path: "answer", body: payload)
+      end
+
+      private
+
+      def normalize_nested_struct(params, key, struct_class)
+        return params unless params.is_a?(Hash)
+
+        value = params[key] || params[key.to_s]
+        return params if value.nil? || value.is_a?(struct_class)
+
+        merged = params.dup
+        merged[key] = struct_class.new(**value)
+        merged.delete(key.to_s)
+        merged
+      end
+    end
+  end
+end

data/lib/exa/resources/webhooks.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Exa
+  module Resources
+    class Webhooks < Base
+      def create(params)
+        client.request(
+          method: :post,
+          path: webhooks_path,
+          body: params,
+          response_model: Exa::Responses::Webhook
+        )
+      end
+
+      def list(params = nil)
+        client.request(
+          method: :get,
+          path: webhooks_path,
+          query: params,
+          response_model: Exa::Responses::WebhookListResponse
+        )
+      end
+
+      def retrieve(id)
+        client.request(
+          method: :get,
+          path: webhooks_path(id),
+          response_model: Exa::Responses::Webhook
+        )
+      end
+
+      def update(id, params)
+        client.request(
+          method: :patch,
+          path: webhooks_path(id),
+          body: params,
+          response_model: Exa::Responses::Webhook
+        )
+      end
+
+      def delete(id)
+        client.request(
+          method: :delete,
+          path: webhooks_path(id),
+          response_model: Exa::Responses::Webhook
+        )
+      end
+
+      def attempts(id, params = nil)
+        client.request(
+          method: :get,
+          path: ["v0", "webhooks", id, "attempts"],
+          query: params,
+          response_model: Exa::Responses::WebhookAttemptListResponse
+        )
+      end
+
+      private
+
+      def webhooks_path(*parts)
+        ["v0", "webhooks", *parts]
+      end
+    end
+  end
+end

data/lib/exa/resources/websets/enrichments.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    class Websets
+      class Enrichments < Base
+        def create(webset_id, params)
+          client.request(
+            method: :post,
+            path: enrichments_path(webset_id),
+            body: params,
+            response_model: Exa::Responses::WebsetEnrichment
+          )
+        end
+
+        def retrieve(webset_id, enrichment_id)
+          client.request(
+            method: :get,
+            path: enrichments_path(webset_id, enrichment_id),
+            response_model: Exa::Responses::WebsetEnrichment
+          )
+        end
+
+        def update(webset_id, enrichment_id, params)
+          client.request(
+            method: :patch,
+            path: enrichments_path(webset_id, enrichment_id),
+            body: params,
+            response_model: Exa::Responses::WebsetEnrichment
+          )
+        end
+
+        def delete(webset_id, enrichment_id)
+          client.request(
+            method: :delete,
+            path: enrichments_path(webset_id, enrichment_id),
+            response_model: Exa::Responses::WebsetEnrichment
+          )
+        end
+
+        def cancel(webset_id, enrichment_id)
+          client.request(
+            method: :post,
+            path: enrichments_path(webset_id, enrichment_id, "cancel"),
+            response_model: Exa::Responses::WebsetEnrichment
+          )
+        end
+
+        private
+
+        def enrichments_path(webset_id, *parts)
+          ["v0", "websets", webset_id, "enrichments", *parts]
+        end
+      end
+    end
+  end
+end

data/lib/exa/resources/websets/items.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    class Websets
+      class Items < Base
+        def list(webset_id, params = nil)
+          client.request(
+            method: :get,
+            path: items_path(webset_id),
+            query: params,
+            response_model: Exa::Responses::WebsetItemListResponse
+          )
+        end
+
+        def retrieve(webset_id, item_id)
+          client.request(
+            method: :get,
+            path: items_path(webset_id, item_id),
+            response_model: Exa::Responses::WebsetItem
+          )
+        end
+
+        def delete(webset_id, item_id)
+          client.request(
+            method: :delete,
+            path: items_path(webset_id, item_id),
+            response_model: Exa::Responses::WebsetItem
+          )
+        end
+
+        private
+
+        def items_path(webset_id, *parts)
+          ["v0", "websets", webset_id, "items", *parts]
+        end
+      end
+    end
+  end
+end

data/lib/exa/resources/websets/monitors.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    class Websets
+      class Monitors < Base
+        def create(params)
+          client.request(
+            method: :post,
+            path: monitor_path,
+            body: params,
+            response_model: Exa::Responses::Monitor
+          )
+        end
+
+        def list(params = nil)
+          client.request(
+            method: :get,
+            path: monitor_path,
+            query: params,
+            response_model: Exa::Responses::MonitorListResponse
+          )
+        end
+
+        def retrieve(id)
+          client.request(
+            method: :get,
+            path: monitor_path(id),
+            response_model: Exa::Responses::Monitor
+          )
+        end
+
+        def update(id, params)
+          client.request(
+            method: :patch,
+            path: monitor_path(id),
+            body: params,
+            response_model: Exa::Responses::Monitor
+          )
+        end
+
+        def delete(id)
+          client.request(
+            method: :delete,
+            path: monitor_path(id),
+            response_model: Exa::Responses::Monitor
+          )
+        end
+
+        def runs_list(monitor_id, params = nil)
+          client.request(
+            method: :get,
+            path: monitor_path(monitor_id, "runs"),
+            query: params,
+            response_model: Exa::Responses::MonitorRunListResponse
+          )
+        end
+
+        def runs_get(monitor_id, run_id)
+          client.request(
+            method: :get,
+            path: monitor_path(monitor_id, "runs", run_id),
+            response_model: Exa::Responses::MonitorRun
+          )
+        end
+
+        private
+
+        def monitor_path(*parts)
+          ["v0", "monitors", *parts]
+        end
+      end
+    end
+  end
+end