tavily 0.1.0

data/lib/tavily/responses.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "object"
+
+module Tavily
+  # Credit usage information, present when +include_usage: true+ is requested.
+  class Usage < Object
+    # @return [Integer, nil] number of API credits consumed by the request.
+    attribute :credits
+  end
+
+  # An image associated with a search result. Tavily returns images either as
+  # bare URL strings or as objects with a description; this normalizes both.
+  class Image < Object
+    # @return [String, nil] image URL.
+    attribute :url
+    # @return [String, nil] generated description (when image descriptions requested).
+    attribute :description
+  end
+
+  # A single web result from {Client#search}.
+  class SearchResult < Object
+    # @return [String, nil] page title.
+    attribute :title
+    # @return [String, nil] result URL.
+    attribute :url
+    # @return [String, nil] short relevant snippet.
+    attribute :content
+    # @return [Float, nil] relevance score (0.0–1.0).
+    attribute :score
+    # @return [String, nil] full cleaned page content (when raw content requested).
+    attribute :raw_content
+    # @return [String, nil] favicon URL (when +include_favicon: true+).
+    attribute :favicon
+    # @return [String, nil] publication date (present for +topic: "news"+).
+    attribute :published_date
+  end
+
+  # Mixin adding +usage+/+credits+/+request_id+/+response_time+ accessors shared
+  # by every top-level response.
+  module Envelope
+    def self.included(base)
+      base.attribute :response_time
+      base.attribute :request_id
+    end
+
+    # @return [Usage, nil] credit usage details (when +include_usage: true+).
+    def usage
+      raw = self["usage"]
+      raw.is_a?(Hash) ? Usage.new(raw) : nil
+    end
+
+    # @return [Integer, nil] convenience accessor for +usage.credits+.
+    def credits
+      usage&.credits
+    end
+  end
+
+  # Response from {Client#search}.
+  class SearchResponse < Object
+    include Envelope
+
+    # @return [String] the executed query.
+    attribute :query
+    # @return [String, nil] LLM-generated answer (when +include_answer+ requested).
+    attribute :answer
+    # @return [Array, nil] suggested follow-up questions, if any.
+    attribute :follow_up_questions
+    # @return [Hash, nil] parameters auto-selected by Tavily (when +auto_parameters: true+).
+    attribute :auto_parameters
+    # @return [Array<SearchResult>] ranked results.
+    attribute :results, wrap: SearchResult, collection: true
+
+    # @return [Array<Image>] related images (normalizes string and object forms).
+    def images
+      Array(self["images"]).map do |img|
+        img.is_a?(Hash) ? Image.new(img) : Image.new("url" => img)
+      end
+    end
+
+    # @return [Array<String>] convenience list of result URLs.
+    def urls
+      results.map(&:url)
+    end
+  end
+
+  # A single successfully extracted page from {Client#extract}.
+  class ExtractResult < Object
+    # @return [String, nil] the extracted URL.
+    attribute :url
+    # @return [String, nil] extracted content (markdown or text).
+    attribute :raw_content
+    # @return [Array<String>] image URLs (when +include_images: true+).
+    attribute :images
+    # @return [String, nil] favicon URL (when +include_favicon: true+).
+    attribute :favicon
+  end
+
+  # A URL that failed extraction.
+  class FailedResult < Object
+    # @return [String, nil] the URL that failed.
+    attribute :url
+    # @return [String, nil] reason for the failure.
+    attribute :error
+  end
+
+  # Response from {Client#extract}.
+  class ExtractResponse < Object
+    include Envelope
+
+    # @return [Array<ExtractResult>] successfully extracted pages.
+    attribute :results, wrap: ExtractResult, collection: true
+    # @return [Array<FailedResult>] URLs that could not be extracted.
+    attribute :failed_results, wrap: FailedResult, collection: true
+  end
+
+  # A single page discovered by {Client#crawl}.
+  class CrawlResult < Object
+    # @return [String, nil] page URL.
+    attribute :url
+    # @return [String, nil] extracted content (markdown or text).
+    attribute :raw_content
+    # @return [String, nil] favicon URL (when +include_favicon: true+).
+    attribute :favicon
+  end
+
+  # Response from {Client#crawl}.
+  class CrawlResponse < Object
+    include Envelope
+
+    # @return [String, nil] the root URL that was crawled.
+    attribute :base_url
+    # @return [Array<CrawlResult>] crawled pages.
+    attribute :results, wrap: CrawlResult, collection: true
+  end
+
+  # Response from {Client#map}.
+  class MapResponse < Object
+    include Envelope
+
+    # @return [String, nil] the root URL that was mapped.
+    attribute :base_url
+    # @return [Array<String>] discovered URLs.
+    attribute :results
+  end
+
+  # A source cited by a research task.
+  class ResearchSource < Object
+    # @return [String, nil] source title.
+    attribute :title
+    # @return [String, nil] source URL.
+    attribute :url
+    # @return [String, nil] favicon URL.
+    attribute :favicon
+  end
+
+  # A research task, returned by {Client#research} (status +pending+) and by
+  # {Client#research_task} / {Client#wait_for_research} (with the final result).
+  class ResearchTask < Object
+    include Envelope
+
+    # @return [String, nil] research task id (use to poll for results).
+    attribute :request_id
+    # @return [String, nil] creation timestamp (ISO 8601).
+    attribute :created_at
+    # @return [String, nil] one of "pending", "in_progress", "completed", "failed".
+    attribute :status
+    # @return [String, nil] echo of the research input.
+    attribute :input
+    # @return [String, nil] the model used ("mini", "pro", or resolved from "auto").
+    attribute :model
+    # @return [String, Hash, nil] the final report (String, or Hash when +output_schema+ used).
+    attribute :content
+    # @return [Array<ResearchSource>] sources used in the research.
+    attribute :sources, wrap: ResearchSource, collection: true
+
+    # @return [Boolean] whether the task finished successfully.
+    def completed?
+      status == "completed"
+    end
+
+    # @return [Boolean] whether the task failed.
+    def failed?
+      status == "failed"
+    end
+
+    # @return [Boolean] whether the task is still running or queued.
+    def pending?
+      %w[pending in_progress].include?(status)
+    end
+  end
+
+  # A single Server-Sent Event emitted by streaming research
+  # ({Client#research} with a block). +data+ is the parsed JSON payload when
+  # possible, otherwise the raw string.
+  ResearchEvent = Struct.new(:event, :data, keyword_init: true)
+end

data/lib/tavily/version.rb

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

data/lib/tavily.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "tavily/version"
+require_relative "tavily/errors"
+require_relative "tavily/configuration"
+require_relative "tavily/object"
+require_relative "tavily/responses"
+require_relative "tavily/connection"
+require_relative "tavily/client"
+
+# Ruby client for the {https://docs.tavily.com Tavily} web search, extract,
+# crawl, map, and research API.
+#
+# @example One-off call using the global configuration
+#   Tavily.configure { |c| c.api_key = ENV["TAVILY_API_KEY"] }
+#   Tavily.search("latest ruby release").results.first.url
+#
+# @example Dedicated client
+#   client = Tavily::Client.new(api_key: "tvly-...")
+#   client.extract("https://example.com")
+module Tavily
+  class << self
+    # The global configuration shared by {Tavily.search} and friends, and used
+    # as the default for new {Client} instances.
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the library.
+    # @yieldparam config [Configuration]
+    # @return [Configuration]
+    def configure
+      yield(configuration) if block_given?
+      reset_default_client!
+      configuration
+    end
+
+    # Reset the global configuration to defaults (re-reads ENV). Mainly useful
+    # in tests.
+    # @return [Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+      reset_default_client!
+      @configuration
+    end
+
+    # A process-wide {Client} built from the global {.configuration}.
+    # @return [Client]
+    def default_client
+      @default_client ||= Client.new
+    end
+
+    # @api private
+    def reset_default_client!
+      @default_client = nil
+    end
+
+    # @see Client#search
+    def search(...) = default_client.search(...)
+    # @see Client#qna_search
+    def qna_search(...) = default_client.qna_search(...)
+    # @see Client#search_context
+    def search_context(...) = default_client.search_context(...)
+    # @see Client#extract
+    def extract(...) = default_client.extract(...)
+    # @see Client#crawl
+    def crawl(...) = default_client.crawl(...)
+    # @see Client#map
+    def map(...) = default_client.map(...)
+    # @see Client#research
+    def research(...) = default_client.research(...)
+    # @see Client#research_task
+    def research_task(...) = default_client.research_task(...)
+    # @see Client#wait_for_research
+    def wait_for_research(...) = default_client.wait_for_research(...)
+  end
+end

data/sig/tavily/client.rbs

@@ -0,0 +1,107 @@
+module Tavily
+  class Client
+    DEFAULT_POLL_INTERVAL: Float
+    DEFAULT_POLL_TIMEOUT: Integer
+
+    attr_reader config: Configuration
+
+    def initialize: (?api_key: String?, **untyped) -> void
+
+    def search: (
+      String query,
+      ?search_depth: String?,
+      ?topic: String?,
+      ?max_results: Integer?,
+      ?chunks_per_source: Integer?,
+      ?time_range: String?,
+      ?days: Integer?,
+      ?start_date: String?,
+      ?end_date: String?,
+      ?include_answer: (bool | String)?,
+      ?include_raw_content: (bool | String)?,
+      ?include_images: bool?,
+      ?include_image_descriptions: bool?,
+      ?include_favicon: bool?,
+      ?include_domains: Array[String]?,
+      ?exclude_domains: Array[String]?,
+      ?country: String?,
+      ?auto_parameters: bool?,
+      ?include_usage: bool?,
+      **untyped extra
+    ) -> SearchResponse
+
+    def qna_search: (String query, **untyped options) -> String?
+
+    def search_context: (String query, ?max_tokens: Integer, **untyped options) -> String
+
+    def extract: (
+      String | Array[String] urls,
+      ?query: String?,
+      ?chunks_per_source: Integer?,
+      ?extract_depth: String?,
+      ?include_images: bool?,
+      ?include_favicon: bool?,
+      ?format: String?,
+      ?timeout: Numeric?,
+      ?include_usage: bool?,
+      **untyped extra
+    ) -> ExtractResponse
+
+    def crawl: (
+      String url,
+      ?instructions: String?,
+      ?chunks_per_source: Integer?,
+      ?max_depth: Integer?,
+      ?max_breadth: Integer?,
+      ?limit: Integer?,
+      ?select_paths: Array[String]?,
+      ?select_domains: Array[String]?,
+      ?exclude_paths: Array[String]?,
+      ?exclude_domains: Array[String]?,
+      ?allow_external: bool?,
+      ?include_images: bool?,
+      ?extract_depth: String?,
+      ?format: String?,
+      ?include_favicon: bool?,
+      ?timeout: Numeric?,
+      ?include_usage: bool?,
+      **untyped extra
+    ) -> CrawlResponse
+
+    def map: (
+      String url,
+      ?instructions: String?,
+      ?max_depth: Integer?,
+      ?max_breadth: Integer?,
+      ?limit: Integer?,
+      ?select_paths: Array[String]?,
+      ?select_domains: Array[String]?,
+      ?exclude_paths: Array[String]?,
+      ?exclude_domains: Array[String]?,
+      ?allow_external: bool?,
+      ?timeout: Numeric?,
+      ?include_usage: bool?,
+      **untyped extra
+    ) -> MapResponse
+
+    def research: (
+      String input,
+      ?model: String?,
+      ?output_schema: Hash[untyped, untyped]?,
+      ?citation_format: String?,
+      ?include_domains: Array[String]?,
+      ?exclude_domains: Array[String]?,
+      ?output_length: String?,
+      ?files: Array[Hash[untyped, untyped]]?,
+      **untyped extra
+    ) ?{ (ResearchEvent) -> void } -> ResearchTask?
+
+    def research_task: (String request_id) -> ResearchTask
+
+    def wait_for_research: (
+      String request_id,
+      ?poll_interval: Numeric,
+      ?timeout: Numeric
+    ) ?{ (ResearchTask) -> void } -> ResearchTask
+  end
+end

data/sig/tavily/configuration.rbs

@@ -0,0 +1,23 @@
+module Tavily
+  class Configuration
+    DEFAULT_BASE_URL: String
+    DEFAULT_TIMEOUT: Integer
+    DEFAULT_OPEN_TIMEOUT: Integer
+    DEFAULT_MAX_RETRIES: Integer
+    DEFAULT_RETRY_BASE_DELAY: Float
+
+    attr_accessor api_key: String?
+    attr_accessor base_url: String
+    attr_accessor timeout: Numeric
+    attr_accessor open_timeout: Numeric
+    attr_accessor max_retries: Integer
+    attr_accessor retry_base_delay: Numeric
+    attr_accessor proxy: String?
+    attr_accessor ca_file: String?
+    attr_accessor logger: untyped
+    attr_accessor user_agent: String
+
+    def initialize: () -> void
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/tavily/connection.rbs

@@ -0,0 +1,12 @@
+module Tavily
+  class Connection
+    RETRIABLE_STATUSES: Array[Integer]
+    RETRIABLE_TIMEOUTS: Array[Class]
+    RETRIABLE_NETWORK: Array[Class]
+
+    def initialize: (Configuration config) -> void
+    def post: (String path, ?Hash[untyped, untyped] body) -> untyped
+    def get: (String path, ?Hash[untyped, untyped] params) -> untyped
+    def stream: (String path, ?Hash[untyped, untyped] body) { (ResearchEvent) -> void } -> nil
+  end
+end

data/sig/tavily/errors.rbs

@@ -0,0 +1,57 @@
+module Tavily
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class ConnectionError < Error
+  end
+
+  class APIError < Error
+    attr_reader status: Integer?
+    attr_reader body: untyped
+    attr_reader request_id: String?
+
+    def initialize: (?String? message, ?status: Integer?, ?body: untyped, ?request_id: String?) -> void
+  end
+
+  class BadRequestError < APIError
+  end
+
+  class AuthenticationError < APIError
+  end
+
+  class ForbiddenError < APIError
+  end
+
+  class NotFoundError < APIError
+  end
+
+  class UnprocessableEntityError < APIError
+  end
+
+  class RateLimitError < APIError
+  end
+
+  class UsageLimitError < APIError
+  end
+
+  class PlanLimitError < UsageLimitError
+  end
+
+  class PayAsYouGoLimitError < UsageLimitError
+  end
+
+  class ServerError < APIError
+  end
+
+  module Errors
+    STATUS_MAP: Hash[Integer, Class]
+
+    def self.class_for: (Integer status) -> Class
+  end
+end

data/sig/tavily/object.rbs

@@ -0,0 +1,18 @@
+module Tavily
+  class Object
+    attr_reader attributes: Hash[String, untyped]
+
+    def self.attribute: (Symbol name, ?key: String, ?wrap: (Class | String)?, ?collection: bool) -> void
+
+    def initialize: (?untyped attributes) -> void
+    def []: (String | Symbol key) -> untyped
+    def dig: (*(String | Symbol) keys) -> untyped
+    def key?: (String | Symbol key) -> bool
+    def to_h: () -> Hash[String, untyped]
+    def to_hash: () -> Hash[String, untyped]
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+    def inspect: () -> String
+  end
+end

data/sig/tavily/responses.rbs

@@ -0,0 +1,108 @@
+module Tavily
+  class Usage < Object
+    def credits: () -> Integer?
+  end
+
+  class Image < Object
+    def url: () -> String?
+    def description: () -> String?
+  end
+
+  class SearchResult < Object
+    def title: () -> String?
+    def url: () -> String?
+    def content: () -> String?
+    def score: () -> Float?
+    def raw_content: () -> String?
+    def favicon: () -> String?
+    def published_date: () -> String?
+  end
+
+  module Envelope
+    def self.included: (untyped base) -> void
+
+    def response_time: () -> Numeric?
+    def request_id: () -> String?
+    def usage: () -> Usage?
+    def credits: () -> Integer?
+  end
+
+  class SearchResponse < Object
+    include Envelope
+
+    def query: () -> String?
+    def answer: () -> String?
+    def follow_up_questions: () -> Array[untyped]?
+    def auto_parameters: () -> Hash[String, untyped]?
+    def results: () -> Array[SearchResult]
+    def images: () -> Array[Image]
+    def urls: () -> Array[String?]
+  end
+
+  class ExtractResult < Object
+    def url: () -> String?
+    def raw_content: () -> String?
+    def images: () -> Array[String]?
+    def favicon: () -> String?
+  end
+
+  class FailedResult < Object
+    def url: () -> String?
+    def error: () -> String?
+  end
+
+  class ExtractResponse < Object
+    include Envelope
+
+    def results: () -> Array[ExtractResult]
+    def failed_results: () -> Array[FailedResult]
+  end
+
+  class CrawlResult < Object
+    def url: () -> String?
+    def raw_content: () -> String?
+    def favicon: () -> String?
+  end
+
+  class CrawlResponse < Object
+    include Envelope
+
+    def base_url: () -> String?
+    def results: () -> Array[CrawlResult]
+  end
+
+  class MapResponse < Object
+    include Envelope
+
+    def base_url: () -> String?
+    def results: () -> Array[String]?
+  end
+
+  class ResearchSource < Object
+    def title: () -> String?
+    def url: () -> String?
+    def favicon: () -> String?
+  end
+
+  class ResearchTask < Object
+    include Envelope
+
+    def request_id: () -> String?
+    def created_at: () -> String?
+    def status: () -> String?
+    def input: () -> String?
+    def model: () -> String?
+    def content: () -> (String | Hash[String, untyped])?
+    def sources: () -> Array[ResearchSource]
+    def completed?: () -> bool
+    def failed?: () -> bool
+    def pending?: () -> bool
+  end
+
+  class ResearchEvent
+    attr_accessor event: String?
+    attr_accessor data: untyped
+
+    def self.new: (?event: String?, ?data: untyped) -> instance
+  end
+end

data/sig/tavily.rbs

@@ -0,0 +1,19 @@
+module Tavily
+  VERSION: String
+
+  def self.configuration: () -> Configuration
+  def self.configure: () ?{ (Configuration) -> void } -> Configuration
+  def self.reset_configuration!: () -> Configuration
+  def self.default_client: () -> Client
+  def self.reset_default_client!: () -> void
+
+  def self.search: (*untyped, **untyped) -> SearchResponse
+  def self.qna_search: (*untyped, **untyped) -> String?
+  def self.search_context: (*untyped, **untyped) -> String
+  def self.extract: (*untyped, **untyped) -> ExtractResponse
+  def self.crawl: (*untyped, **untyped) -> CrawlResponse
+  def self.map: (*untyped, **untyped) -> MapResponse
+  def self.research: (*untyped, **untyped) ?{ (ResearchEvent) -> void } -> ResearchTask?
+  def self.research_task: (*untyped, **untyped) -> ResearchTask
+  def self.wait_for_research: (*untyped, **untyped) ?{ (ResearchTask) -> void } -> ResearchTask
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: tavily
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  A lightweight, dependency-free Ruby client for the Tavily API. The web access
+  layer built for LLMs and AI agents. Wraps the search, extract, crawl, map, and
+  research endpoints with typed response objects, automatic retries with backoff,
+  streaming research, and granular error handling.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/tavily.rb
+- lib/tavily/client.rb
+- lib/tavily/configuration.rb
+- lib/tavily/connection.rb
+- lib/tavily/errors.rb
+- lib/tavily/object.rb
+- lib/tavily/responses.rb
+- lib/tavily/version.rb
+- sig/tavily.rbs
+- sig/tavily/client.rbs
+- sig/tavily/configuration.rbs
+- sig/tavily/connection.rbs
+- sig/tavily/errors.rbs
+- sig/tavily/object.rbs
+- sig/tavily/responses.rbs
+homepage: https://github.com/main-path/tavily
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/main-path/tavily
+  changelog_uri: https://github.com/main-path/tavily/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.tavily.com/
+  bug_tracker_uri: https://github.com/main-path/tavily/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Tavily search, extract, crawl, map, and research API.
+test_files: []