tavily 0.1.0

data/lib/tavily/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Tavily
+  # Holds configuration for a {Tavily::Client}. A global instance is available
+  # via {Tavily.configuration} / {Tavily.configure}; individual clients may
+  # override any value through keyword arguments to {Tavily::Client#initialize}.
+  class Configuration
+    # Default Tavily REST API base URL.
+    DEFAULT_BASE_URL = "https://api.tavily.com"
+    # Default read timeout, in seconds.
+    DEFAULT_TIMEOUT = 60
+    # Default connection-open timeout, in seconds.
+    DEFAULT_OPEN_TIMEOUT = 10
+    # Default number of automatic retries for transient failures.
+    DEFAULT_MAX_RETRIES = 2
+    # Base delay (seconds) for exponential backoff between retries.
+    DEFAULT_RETRY_BASE_DELAY = 0.5
+
+    # @return [String, nil] Tavily API key (e.g. "tvly-...").
+    attr_accessor :api_key
+    # @return [String] API base URL.
+    attr_accessor :base_url
+    # @return [Numeric] read timeout in seconds.
+    attr_accessor :timeout
+    # @return [Numeric] open timeout in seconds.
+    attr_accessor :open_timeout
+    # @return [Integer] maximum number of retries for transient errors.
+    attr_accessor :max_retries
+    # @return [Numeric] base delay for exponential backoff, in seconds.
+    attr_accessor :retry_base_delay
+    # @return [String, nil] proxy URL (e.g. "http://user:pass@host:port").
+    attr_accessor :proxy
+    # @return [String, nil] path to a PEM CA-certificate bundle. Defaults to
+    #   ENV["SSL_CERT_FILE"]. Handy on Windows, where some Ruby builds ship
+    #   without a usable default certificate store.
+    attr_accessor :ca_file
+    # @return [Logger, nil] optional logger for request/response diagnostics.
+    attr_accessor :logger
+    # @return [String] User-Agent header sent with every request.
+    attr_accessor :user_agent
+
+    def initialize
+      @api_key          = ENV.fetch("TAVILY_API_KEY", nil)
+      @base_url         = ENV.fetch("TAVILY_BASE_URL", DEFAULT_BASE_URL)
+      @timeout          = Float(ENV.fetch("TAVILY_TIMEOUT", DEFAULT_TIMEOUT))
+      @open_timeout     = DEFAULT_OPEN_TIMEOUT
+      @max_retries      = Integer(ENV.fetch("TAVILY_MAX_RETRIES", DEFAULT_MAX_RETRIES))
+      @retry_base_delay = DEFAULT_RETRY_BASE_DELAY
+      @proxy            = ENV.fetch("TAVILY_PROXY", nil)
+      @ca_file          = ENV.fetch("SSL_CERT_FILE", nil)
+      @logger           = nil
+      @user_agent       = "tavily-ruby/#{Tavily::VERSION}"
+    end
+
+    # @return [Hash] a shallow copy of the configuration as a hash.
+    def to_h
+      {
+        base_url: base_url,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        max_retries: max_retries,
+        retry_base_delay: retry_base_delay,
+        proxy: proxy,
+        ca_file: ca_file,
+        user_agent: user_agent
+      }
+    end
+  end
+end

data/lib/tavily/connection.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "openssl"
+
+module Tavily
+  # Thin HTTP layer over Ruby's standard library {Net::HTTP}. Handles JSON
+  # encoding/decoding, authentication, timeouts, automatic retries with
+  # exponential backoff, and translation of HTTP errors into {APIError}s.
+  #
+  # @api private
+  class Connection
+    # HTTP statuses that are safe to retry (transient).
+    RETRIABLE_STATUSES = [408, 409, 425, 429, 500, 502, 503, 504].freeze
+
+    # Network-level exceptions that warrant a retry.
+    RETRIABLE_TIMEOUTS = [
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      defined?(Net::WriteTimeout) ? Net::WriteTimeout : nil
+    ].compact.freeze
+
+    RETRIABLE_NETWORK = [
+      SocketError,
+      SystemCallError,
+      IOError,
+      OpenSSL::SSL::SSLError,
+      EOFError
+    ].freeze
+
+    # @param config [Configuration]
+    def initialize(config)
+      @config = config
+    end
+
+    # Issue a POST request with a JSON body.
+    # @param path [String] request path (e.g. "/search")
+    # @param body [Hash] request body; nil values are removed before sending
+    # @return [Hash, Array, String] parsed response body
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    # Issue a GET request with query parameters.
+    # @param path [String]
+    # @param params [Hash]
+    # @return [Hash, Array, String] parsed response body
+    def get(path, params = {})
+      request(:get, path, query: params)
+    end
+
+    # Issue a POST request and yield Server-Sent Events as they arrive.
+    # Streaming responses are not retried.
+    #
+    # @param path [String]
+    # @param body [Hash]
+    # @yieldparam event [ResearchEvent]
+    # @return [nil]
+    def stream(path, body = {})
+      ensure_api_key!
+      uri = build_uri(path, nil)
+      http = build_http(uri)
+      req = build_request(:post, uri, body)
+      req["Accept"] = "text/event-stream"
+
+      buffer = +""
+      begin
+        http.start do |conn|
+          conn.request(req) do |response|
+            status = response.code.to_i
+            raise stream_error(response) unless status.between?(200, 299)
+
+            response.read_body do |chunk|
+              buffer << chunk.gsub("\r\n", "\n")
+              while (idx = buffer.index("\n\n"))
+                raw_event = buffer.slice!(0..(idx + 1))
+                event = parse_sse_event(raw_event)
+                yield event if event
+              end
+            end
+          end
+        end
+      rescue *RETRIABLE_TIMEOUTS => e
+        raise TimeoutError, "Tavily stream timed out: #{e.message}"
+      rescue *RETRIABLE_NETWORK => e
+        raise ConnectionError, "Tavily stream connection failed: #{e.message}"
+      end
+
+      event = parse_sse_event(buffer)
+      yield event if event
+      nil
+    end
+
+    private
+
+    def request(method, path, body: nil, query: nil)
+      ensure_api_key!
+      uri = build_uri(path, query)
+      attempt = 0
+
+      loop do
+        attempt += 1
+        response =
+          begin
+            perform(method, uri, body)
+          rescue *RETRIABLE_TIMEOUTS => e
+            if attempt > @config.max_retries
+              raise TimeoutError,
+                    "Tavily request timed out after #{@config.timeout}s: #{e.message}"
+            end
+
+            log { "timeout (attempt #{attempt}), retrying: #{e.message}" }
+            sleep(backoff(attempt))
+            next
+          rescue *RETRIABLE_NETWORK => e
+            raise ConnectionError, "Tavily connection failed: #{e.message}" if attempt > @config.max_retries
+
+            log { "network error (attempt #{attempt}), retrying: #{e.message}" }
+            sleep(backoff(attempt))
+            next
+          end
+
+        status = response.code.to_i
+        if RETRIABLE_STATUSES.include?(status) && attempt <= @config.max_retries
+          log { "HTTP #{status} (attempt #{attempt}), retrying" }
+          sleep(backoff(attempt, response))
+          next
+        end
+
+        return handle(response, status)
+      end
+    end
+
+    def perform(method, uri, body)
+      http = build_http(uri)
+      req = build_request(method, uri, body)
+      started = monotonic_now
+      response = http.request(req)
+      log { "#{method.to_s.upcase} #{uri.path} -> #{response.code} in #{format("%.3f", monotonic_now - started)}s" }
+      response
+    end
+
+    def build_http(uri)
+      http =
+        if @config.proxy && !@config.proxy.empty?
+          proxy = URI.parse(@config.proxy)
+          Net::HTTP.new(uri.host, uri.port, proxy.host, proxy.port, proxy.user, proxy.password)
+        else
+          Net::HTTP.new(uri.host, uri.port)
+        end
+
+      http.use_ssl = uri.scheme == "https"
+      http.ca_file = @config.ca_file if http.use_ssl? && @config.ca_file && File.exist?(@config.ca_file)
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+      http.write_timeout = @config.timeout if http.respond_to?(:write_timeout=)
+      http
+    end
+
+    def build_request(method, uri, body)
+      klass = method == :post ? Net::HTTP::Post : Net::HTTP::Get
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{@config.api_key}"
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = @config.user_agent
+
+      payload = compact(body)
+      req.body = JSON.generate(payload) if payload && !payload.empty?
+      req
+    end
+
+    def build_uri(path, query)
+      uri = URI.join("#{@config.base_url.chomp("/")}/", path.to_s.sub(%r{\A/}, ""))
+      uri.query = URI.encode_www_form(compact(query)) if query && !query.empty?
+      uri
+    end
+
+    def handle(response, status)
+      parsed = parse_body(response.body)
+      return parsed if status.between?(200, 299)
+
+      raise build_error(status, parsed)
+    end
+
+    def parse_body(raw)
+      return {} if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      raw
+    end
+
+    def build_error(status, parsed)
+      request_id = parsed.is_a?(Hash) ? parsed["request_id"] : nil
+      message = extract_error_message(parsed)
+      Errors.class_for(status).new(message, status: status, body: parsed, request_id: request_id)
+    end
+
+    # Tavily returns errors in a few shapes:
+    #   {"detail": {"error": "..."}}                       (auth / bad request)
+    #   {"detail": [{"loc": [...], "msg": "...", ...}]}     (FastAPI validation)
+    #   {"error": "..."} / {"message": "..."}              (fallbacks)
+    def extract_error_message(parsed)
+      return parsed.to_s unless parsed.is_a?(Hash)
+
+      detail = parsed["detail"] || parsed["error"] || parsed["message"]
+      case detail
+      when String then detail
+      when Hash   then detail["error"] || detail["message"] || detail.to_s
+      when Array  then detail.map { |d| format_detail(d) }.join("; ")
+      else parsed.to_s
+      end
+    end
+
+    def format_detail(entry)
+      return entry.to_s unless entry.is_a?(Hash)
+
+      loc = Array(entry["loc"]).reject { |part| part == "body" }.join(".")
+      msg = entry["msg"] || entry["error"] || entry.to_s
+      loc.empty? ? msg : "#{loc}: #{msg}"
+    end
+
+    # Remove nil values so callers can pass optional params freely without
+    # accidentally sending nulls the API would reject.
+    def compact(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), acc|
+        acc[key] = value unless value.nil?
+      end
+    end
+
+    def backoff(attempt, response = nil)
+      if response && (retry_after = response["retry-after"])
+        seconds = retry_after.to_f
+        return seconds if seconds.positive?
+      end
+
+      base = @config.retry_base_delay * (2**(attempt - 1))
+      jitter = base * 0.25 * rand
+      base + jitter
+    end
+
+    def stream_error(response)
+      body = +""
+      response.read_body { |chunk| body << chunk }
+      build_error(response.code.to_i, parse_body(body))
+    end
+
+    def parse_sse_event(raw)
+      event_name = nil
+      data_lines = []
+      raw.each_line(chomp: true) do |line|
+        next if line.empty? || line.start_with?(":")
+
+        field, _separator, value = line.partition(":")
+        value = value.sub(/\A /, "")
+        case field
+        when "event" then event_name = value
+        when "data"  then data_lines << value
+        end
+      end
+      return nil if event_name.nil? && data_lines.empty?
+
+      ResearchEvent.new(event: event_name, data: parse_sse_data(data_lines.join("\n")))
+    end
+
+    def parse_sse_data(raw)
+      return nil if raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      raw
+    end
+
+    def ensure_api_key!
+      return unless @config.api_key.nil? || @config.api_key.to_s.empty?
+
+      raise ConfigurationError,
+            "Missing Tavily API key. Set ENV['TAVILY_API_KEY'], call " \
+            "Tavily.configure { |c| c.api_key = ... }, or pass api_key: to Tavily::Client.new."
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def log
+      logger = @config.logger
+      return unless logger
+
+      logger.debug("[tavily] #{yield}")
+    end
+  end
+end

data/lib/tavily/errors.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Tavily
+  # Base class for every error raised by this library. Rescue this to catch
+  # anything the gem might raise.
+  class Error < StandardError; end
+
+  # Raised when the client is misconfigured (e.g. a missing API key).
+  class ConfigurationError < Error; end
+
+  # Raised when a request exceeds the configured timeout.
+  class TimeoutError < Error; end
+
+  # Raised when the connection to the API fails at the network/TLS layer.
+  class ConnectionError < Error; end
+
+  # Base class for errors returned by the Tavily API (non-2xx responses).
+  # Carries the HTTP status, parsed body, and request id when available.
+  class APIError < Error
+    # @return [Integer, nil] HTTP status code.
+    attr_reader :status
+    # @return [Object, nil] parsed response body (Hash, Array, or String).
+    attr_reader :body
+    # @return [String, nil] Tavily request id, useful for support tickets.
+    attr_reader :request_id
+
+    # @param message [String, nil] human-readable error message
+    # @param status [Integer, nil] HTTP status code
+    # @param body [Object, nil] parsed response body
+    # @param request_id [String, nil] Tavily request id
+    def initialize(message = nil, status: nil, body: nil, request_id: nil)
+      @status = status
+      @body = body
+      @request_id = request_id
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      parts = []
+      parts << "[#{status}]" if status
+      parts << (message || "Tavily API error")
+      parts << "(request_id: #{request_id})" if request_id
+      parts.join(" ")
+    end
+  end
+
+  # 400 — the request was malformed or a parameter value was invalid.
+  class BadRequestError < APIError; end
+  # 401 — missing or invalid API key.
+  class AuthenticationError < APIError; end
+  # 403 — the key is valid but not permitted (plan/usage limit reached).
+  class ForbiddenError < APIError; end
+  # 404 — the requested resource does not exist.
+  class NotFoundError < APIError; end
+  # 422 — request body failed validation.
+  class UnprocessableEntityError < APIError; end
+  # 429 — rate limit exceeded.
+  class RateLimitError < APIError; end
+
+  # Base class for Tavily's non-standard usage/quota limit errors (432, 433).
+  class UsageLimitError < APIError; end
+  # 432 — plan/key credit quota exceeded (non-standard Tavily status code).
+  class PlanLimitError < UsageLimitError; end
+  # 433 — pay-as-you-go spending limit exceeded (non-standard Tavily status code).
+  class PayAsYouGoLimitError < UsageLimitError; end
+
+  # 5xx — Tavily server-side error.
+  class ServerError < APIError; end
+
+  # Maps HTTP status codes to {APIError} subclasses.
+  module Errors
+    # @api private
+    STATUS_MAP = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError,
+      432 => PlanLimitError,
+      433 => PayAsYouGoLimitError
+    }.freeze
+
+    # @param status [Integer] HTTP status code
+    # @return [Class] the most specific {APIError} subclass for +status+
+    def self.class_for(status)
+      return STATUS_MAP[status] if STATUS_MAP.key?(status)
+      return ServerError if status >= 500
+
+      APIError
+    end
+  end
+end

data/lib/tavily/object.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Tavily
+  # Base class for every response object returned by the client. Wraps the
+  # parsed JSON hash, exposing typed accessors (declared with {.attribute})
+  # while remaining forward-compatible: any field the API adds is still
+  # reachable via {#[]}, {#dig}, and {#to_h}.
+  class Object
+    # @return [Hash] the raw, parsed response body with string keys.
+    attr_reader :attributes
+
+    # Declare a typed accessor for a response field.
+    #
+    # @param name [Symbol] method name to define
+    # @param key [String] the key in the raw hash (defaults to +name+)
+    # @param wrap [Class, String, nil] wrap the value in this {Tavily::Object}
+    #   subclass (may be given as a String to allow forward references)
+    # @param collection [Boolean] when true, treat the value as an array and
+    #   wrap each element
+    # @return [void]
+    def self.attribute(name, key: name.to_s, wrap: nil, collection: false)
+      define_method(name) do
+        raw = @attributes[key]
+        return raw if wrap.nil?
+
+        klass = wrap.is_a?(Class) ? wrap : Tavily.const_get(wrap)
+        if collection
+          Array(raw).map { |item| item.is_a?(Hash) ? klass.new(item) : item }
+        elsif raw.is_a?(Hash)
+          klass.new(raw)
+        else
+          raw
+        end
+      end
+    end
+
+    # @param attributes [Hash] parsed response body
+    def initialize(attributes = {})
+      @attributes = attributes.is_a?(Hash) ? attributes : {}
+    end
+
+    # Fetch a raw field by name (String or Symbol).
+    # @param key [String, Symbol]
+    # @return [Object, nil]
+    def [](key)
+      @attributes[key.to_s]
+    end
+
+    # @see Hash#dig
+    # @return [Object, nil]
+    def dig(*keys)
+      @attributes.dig(*keys.map(&:to_s))
+    end
+
+    # @param key [String, Symbol]
+    # @return [Boolean] whether the raw field is present
+    def key?(key)
+      @attributes.key?(key.to_s)
+    end
+
+    # @return [Hash] the raw response body
+    def to_h
+      @attributes
+    end
+    alias to_hash to_h
+
+    def ==(other)
+      other.is_a?(self.class) && other.attributes == attributes
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, @attributes].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@attributes.inspect}>"
+    end
+  end
+end