tavily 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7b9e2b04dccf49bff52ed85008cc143ec009b95f289efed38cd230c165ee2fa
+  data.tar.gz: '089bd278c94dcf7ae30976a4e596dd36b7e462efda363369030592df105b0844'
+SHA512:
+  metadata.gz: 1943c54bdfa88cbc213565714c523523bf389ba3319d18ba3f8a9b4a38cb34a07151d6a5691c8f7bbb935171817265a9744b30b9a9cd6a9c1e92c9b76538bbd8
+  data.tar.gz: 0a5c3869a3493867a68ddfe5c0c7c7c463492cbfa2391e61c77a2f457e793349d1e3539001946ada94b618ad76a103f951db15088e80a3d31b0bb79cc9e1dd14

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-02
+
+### Added
+- Initial release.
+- `Tavily::Client` covering the Tavily REST API:
+  - `#search` (plus `#qna_search` and `#search_context` helpers)
+  - `#extract`
+  - `#crawl`
+  - `#map`
+  - `#research`, `#research_task`, `#wait_for_research`, and streaming research
+    via a block.
+- Typed response objects (`SearchResponse`, `ExtractResponse`, `CrawlResponse`,
+  `MapResponse`, `ResearchTask`, and friends) with raw-hash access preserved.
+- Global configuration (`Tavily.configure`) and per-client overrides.
+- Automatic retries with exponential backoff for transient failures, honoring
+  the `Retry-After` header on `429` responses.
+- Granular error hierarchy, including Tavily's non-standard `432` (plan limit)
+  and `433` (pay-as-you-go limit) status codes.
+- Built entirely on the Ruby standard library, no runtime dependencies.
+
+[Unreleased]: https://github.com/main-path/tavily/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/main-path/tavily/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ned
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,319 @@
+# Tavily
+
+[![CI](https://github.com/main-path/tavily/actions/workflows/ci.yml/badge.svg)](https://github.com/main-path/tavily/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/tavily.svg)](https://rubygems.org/gems/tavily)
+
+A lightweight, dependency-free Ruby client for the [Tavily](https://docs.tavily.com/welcome) API — the web-access layer built for LLMs and AI agents.
+
+It wraps every Tavily endpoint with typed response objects, automatic retries, streaming research, and a granular error hierarchy:
+
+- **Search** — `search`, plus the `qna_search` and `search_context` helpers
+- **Extract** — clean content from one or many URLs
+- **Crawl** — follow links from a root URL
+- **Map** — discover a site's URL structure
+- **Research** — start, poll, or live-stream an asynchronous research task
+
+Built entirely on the Ruby standard library (`net/http`) — **no runtime dependencies**.
+
+## Installation
+
+Add it to your Gemfile:
+
+```ruby
+gem "tavily"
+```
+
+Then run `bundle install`. Or install it directly:
+
+```sh
+gem install tavily
+```
+
+Requires Ruby 3.1+.
+
+## Quick start
+
+```ruby
+require "tavily"
+
+client = Tavily::Client.new(api_key: "tvly-YOUR_API_KEY")
+
+response = client.search("who won the 2022 FIFA World Cup?", include_answer: true)
+
+response.answer            # => "Argentina won the 2022 FIFA World Cup..."
+response.results.first.url # => "https://en.wikipedia.org/wiki/..."
+response.results.first.title
+response.credits           # credit usage, when include_usage: true
+```
+
+Get your API key from the [Tavily dashboard](https://app.tavily.com).
+
+## Configuration
+
+You can configure a global default (used by `Tavily.search` and friends, and as the default for every new client):
+
+```ruby
+Tavily.configure do |config|
+  config.api_key          = ENV["TAVILY_API_KEY"] # default: ENV["TAVILY_API_KEY"]
+  config.base_url         = "https://api.tavily.com"
+  config.timeout          = 60   # read timeout (seconds)
+  config.open_timeout     = 10   # connection-open timeout (seconds)
+  config.max_retries      = 2    # automatic retries for transient failures
+  config.retry_base_delay = 0.5  # base seconds for exponential backoff
+  config.proxy            = nil  # "http://user:pass@host:port"
+  config.ca_file          = nil  # path to a PEM CA bundle (see "Windows / TLS")
+  config.logger           = Logger.new($stdout) # optional request logging
+end
+
+Tavily.search("latest ruby release")
+```
+
+Every option can also be overridden per client:
+
+```ruby
+client = Tavily::Client.new(api_key: "tvly-...", timeout: 120, max_retries: 5)
+```
+
+The following environment variables are read automatically: `TAVILY_API_KEY`, `TAVILY_BASE_URL`, `TAVILY_TIMEOUT`, `TAVILY_MAX_RETRIES`, `TAVILY_PROXY`, and `SSL_CERT_FILE`.
+
+## Endpoints
+
+### Search
+
+```ruby
+response = client.search(
+  "embedded systems news",
+  topic: "news",            # "general" (default), "news", or "finance"
+  search_depth: "advanced", # "basic" (default), "advanced", "fast", "ultra-fast"
+  max_results: 10,          # 0–20 (default 5)
+  time_range: "week",       # "day" | "week" | "month" | "year"
+  include_answer: "advanced",   # true/false, "basic", or "advanced"
+  include_raw_content: "markdown",
+  include_images: true,
+  include_domains: ["arxiv.org"],
+  exclude_domains: ["example.com"],
+  include_usage: true
+)
+
+response.query
+response.answer
+response.results        # => [Tavily::SearchResult, ...]
+response.results.first.title
+response.results.first.content
+response.results.first.score
+response.urls           # => convenience array of result URLs
+response.images         # => [Tavily::Image, ...] (url + optional description)
+response.credits        # => Integer (when include_usage: true)
+response.request_id
+```
+
+#### `qna_search` — just the answer
+
+```ruby
+client.qna_search("what is the capital of France?")
+# => "Paris is the capital of France."
+```
+
+#### `search_context` — a RAG-ready context string
+
+Returns a JSON string of `[{ "url" =>, "content" => }, ...]`, trimmed to roughly `max_tokens` tokens.
+
+```ruby
+context = client.search_context("ruby concurrency", max_tokens: 4000)
+```
+
+### Extract
+
+```ruby
+response = client.extract(
+  ["https://docs.tavily.com/welcome", "https://example.com"],
+  extract_depth: "advanced", # "basic" (default) or "advanced"
+  format: "markdown",        # "markdown" (default) or "text"
+  include_images: true,
+  include_usage: true
+)
+
+response.results        # => [Tavily::ExtractResult, ...]
+response.results.first.raw_content
+response.failed_results # => [Tavily::FailedResult, ...] (url + error)
+```
+
+A single URL string works too: `client.extract("https://example.com")`. Up to 20 URLs per request.
+
+### Crawl
+
+```ruby
+response = client.crawl(
+  "https://docs.tavily.com",
+  instructions: "Find all pages about pricing", # natural-language guidance
+  max_depth: 2,        # 1–5
+  max_breadth: 50,     # links per level (1–500)
+  limit: 100,          # total links to process
+  select_paths: ["/documentation/.*"], # regex allowlist
+  exclude_paths: ["/blog/.*"],         # regex blocklist
+  extract_depth: "basic"
+)
+
+response.base_url
+response.results # => [Tavily::CrawlResult, ...] (url, raw_content, favicon)
+```
+
+### Map
+
+```ruby
+response = client.map("https://docs.tavily.com", max_depth: 2, limit: 100)
+
+response.base_url
+response.results # => ["https://docs.tavily.com/...", ...] (array of URLs)
+```
+
+### Research (asynchronous)
+
+Research is an asynchronous endpoint. Start a task, then either poll for the result or stream it live.
+
+**Create + poll:**
+
+```ruby
+task = client.research(
+  "Compare the leading Ruby HTTP clients in 2025",
+  model: "mini",            # "mini", "pro", or "auto" (default)
+  output_length: "standard" # "short", "standard", or "long"
+)
+
+task.request_id
+task.status        # => "pending"
+
+# Block until it finishes (raises on failure / timeout):
+result = client.wait_for_research(task.request_id, poll_interval: 3, timeout: 600)
+result.content     # => the final report (String, or Hash if output_schema given)
+result.sources     # => [Tavily::ResearchSource, ...] (title, url, favicon)
+
+# Or check once, yourself:
+client.research_task(task.request_id).completed?
+```
+
+**Stream live** (pass a block to receive Server-Sent Events). Each `event` is a `Tavily::ResearchEvent` with an `.event` name and parsed `.data`. The stream is OpenAI-compatible: events are `chat.completion.chunk`s whose `choices/0/delta` carries either report text (`content`) or a research `tool_calls` step, ending with a `done` event (or an `error` event on failure):
+
+```ruby
+client.research("Latest developments in fusion energy", model: "mini") do |event|
+  case event.event
+  when "chat.completion.chunk"
+    delta = event.data.dig("choices", 0, "delta")
+    print delta["content"] if delta && delta["content"]
+  when "error"
+    warn event.data["error"]
+  when "done"
+    puts "\n[done]"
+  end
+end
+```
+
+The gem yields every event exactly as the API sends it, so it keeps working even if Tavily changes the event schema.
+
+You can also request structured output with a JSON Schema:
+
+```ruby
+client.research(
+  "Top 3 EVs by range in 2025",
+  output_schema: {
+    "type" => "object",
+    "properties" => { "cars" => { "type" => "array", "items" => { "type" => "string" } } },
+    "required" => ["cars"]
+  }
+)
+```
+
+## Response objects
+
+Every endpoint returns a typed object that wraps the raw JSON. Declared fields are exposed as methods, and the full payload is always reachable:
+
+```ruby
+response = client.search("ruby")
+
+response.results.first.title  # typed accessor
+response["request_id"]        # raw access by key (String or Symbol)
+response.dig("usage", "credits")
+response.to_h                 # the complete parsed Hash
+```
+
+Because access falls through to the raw hash, any new field Tavily adds is reachable immediately — and any new request parameter can be passed through as a keyword argument without waiting for a gem update:
+
+```ruby
+client.search("ruby", some_new_param: true) # forwarded straight to the API
+```
+
+## Error handling
+
+Non-2xx responses raise a subclass of `Tavily::APIError`, which carries the HTTP status, parsed body, and request id:
+
+```ruby
+begin
+  client.search("ruby")
+rescue Tavily::RateLimitError => e
+  retry_later
+rescue Tavily::APIError => e
+  e.status      # => 401
+  e.message     # => "[401] Unauthorized: missing or invalid API key."
+  e.request_id  # => "..." (quote this in support tickets)
+  e.body        # => parsed response body
+end
+```
+
+| Exception | Status | Meaning |
+|---|---|---|
+| `Tavily::BadRequestError` | 400 | Invalid request or parameter value |
+| `Tavily::AuthenticationError` | 401 | Missing or invalid API key |
+| `Tavily::ForbiddenError` | 403 | Not permitted (e.g. unsupported URL) |
+| `Tavily::NotFoundError` | 404 | Resource not found |
+| `Tavily::UnprocessableEntityError` | 422 | Request body failed validation |
+| `Tavily::RateLimitError` | 429 | Rate limit exceeded (honors `Retry-After`) |
+| `Tavily::PlanLimitError` | 432 | Plan/key credit quota exceeded |
+| `Tavily::PayAsYouGoLimitError` | 433 | Pay-as-you-go limit exceeded |
+| `Tavily::ServerError` | 5xx | Tavily server-side error |
+
+`Tavily::PlanLimitError` and `Tavily::PayAsYouGoLimitError` share the ancestor `Tavily::UsageLimitError`. Network problems raise `Tavily::TimeoutError` or `Tavily::ConnectionError`, and a missing key raises `Tavily::ConfigurationError`. Everything ultimately descends from `Tavily::Error`.
+
+## Retries
+
+Transient failures (HTTP 408/409/425/429/5xx and network timeouts) are retried automatically up to `max_retries` times with exponential backoff and jitter. On a `429`, the `Retry-After` header is respected. Streaming research requests are not retried.
+
+## Windows / TLS certificates
+
+Some Windows Ruby builds (including MSVC builds) ship without a usable default OpenSSL certificate store, which causes `certificate verify failed (unable to get local issuer certificate)`. Point the client at a CA bundle:
+
+```ruby
+Tavily.configure { |c| c.ca_file = 'C:\path\to\cacert.pem' }
+```
+
+Or set it for the whole process before requiring the gem:
+
+```sh
+# A bundle ships with Git for Windows, for example:
+set SSL_CERT_FILE=C:\Program Files\Git\mingw64\etc\ssl\certs\ca-bundle.crt
+```
+
+You can also download an up-to-date bundle from <https://curl.se/ca/cacert.pem>.
+
+## Development
+
+```sh
+bin/setup            # bundle install + create .env
+bundle exec rake     # run the specs and RuboCop
+bin/console          # an IRB session with the gem loaded
+```
+
+The default `rake` task runs RSpec and RuboCop. The offline suite uses [WebMock](https://github.com/bblimke/webmock) and makes no network calls.
+
+To run the live integration suite (consumes credits):
+
+```sh
+TAVILY_LIVE=1 TAVILY_API_KEY=tvly-... bundle exec rspec spec/live_spec.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/main-path/tavily>.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/tavily/client.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "connection"
+require_relative "responses"
+
+module Tavily
+  # The main entry point for talking to the Tavily API.
+  #
+  # @example
+  #   client = Tavily::Client.new(api_key: "tvly-...")
+  #   response = client.search("who won the 2022 world cup?", include_answer: true)
+  #   response.answer # => "Argentina ..."
+  #
+  # Every endpoint method accepts the documented parameters as keyword
+  # arguments and forwards any additional keywords (`**extra`) straight into the
+  # request body, so newly released API parameters work without a gem upgrade.
+  class Client
+    # Default polling interval (seconds) for {#wait_for_research}.
+    DEFAULT_POLL_INTERVAL = 3.0
+    # Default overall timeout (seconds) for {#wait_for_research}.
+    DEFAULT_POLL_TIMEOUT = 600
+
+    # @return [Configuration] the resolved configuration for this client.
+    attr_reader :config
+
+    # @param api_key [String, nil] overrides {Configuration#api_key}
+    # @param options [Hash] any other {Configuration} attribute to override
+    #   (e.g. +base_url:+, +timeout:+, +max_retries:+, +logger:+)
+    def initialize(api_key: nil, **options)
+      @config = build_config(api_key, options)
+      @connection = Connection.new(@config)
+    end
+
+    # Execute a web search.
+    #
+    # @param query [String] the search query (required)
+    # @param search_depth [String, nil] "basic", "advanced", "fast", or "ultra-fast"
+    # @param topic [String, nil] "general", "news", or "finance"
+    # @param max_results [Integer, nil] number of results (0–20, default 5)
+    # @param chunks_per_source [Integer, nil] 1–3, advanced depth only
+    # @param time_range [String, nil] "day"/"week"/"month"/"year" (or d/w/m/y)
+    # @param days [Integer, nil] limit to the last N days (news topic)
+    # @param start_date [String, nil] "YYYY-MM-DD"
+    # @param end_date [String, nil] "YYYY-MM-DD"
+    # @param include_answer [Boolean, String, nil] true/false, "basic", or "advanced"
+    # @param include_raw_content [Boolean, String, nil] true/false, "markdown", or "text"
+    # @param include_images [Boolean, nil]
+    # @param include_image_descriptions [Boolean, nil] requires +include_images: true+
+    # @param include_favicon [Boolean, nil]
+    # @param include_domains [Array<String>, nil] up to 300 domains
+    # @param exclude_domains [Array<String>, nil] up to 150 domains
+    # @param country [String, nil] boost results from a country (general topic)
+    # @param auto_parameters [Boolean, nil] let Tavily choose parameters
+    # @param include_usage [Boolean, nil] include credit usage in the response
+    # @param extra [Hash] any additional request-body parameters
+    # @return [SearchResponse]
+    def search(query, search_depth: nil, topic: nil, max_results: nil, chunks_per_source: nil,
+               time_range: nil, days: nil, start_date: nil, end_date: nil, include_answer: nil,
+               include_raw_content: nil, include_images: nil, include_image_descriptions: nil,
+               include_favicon: nil, include_domains: nil, exclude_domains: nil, country: nil,
+               auto_parameters: nil, include_usage: nil, **extra)
+      body = {
+        query: query, search_depth: search_depth, topic: topic, max_results: max_results,
+        chunks_per_source: chunks_per_source, time_range: time_range, days: days,
+        start_date: start_date, end_date: end_date, include_answer: include_answer,
+        include_raw_content: include_raw_content, include_images: include_images,
+        include_image_descriptions: include_image_descriptions, include_favicon: include_favicon,
+        include_domains: include_domains, exclude_domains: exclude_domains, country: country,
+        auto_parameters: auto_parameters, include_usage: include_usage
+      }.merge(extra)
+      SearchResponse.new(@connection.post("/search", body))
+    end
+
+    # Convenience: run a search and return only the generated answer string.
+    # @param query [String]
+    # @param options [Hash] forwarded to {#search}
+    # @return [String, nil] the answer, or nil if none was produced
+    def qna_search(query, **options)
+      options[:include_answer] = true unless options.key?(:include_answer)
+      search(query, **options).answer
+    end
+
+    # Convenience: run a search and return a compact context string suitable for
+    # RAG prompts: a JSON array of {url, content} objects trimmed to roughly
+    # +max_tokens+ tokens (estimated at ~4 characters per token). The top result
+    # is always included, even if it alone exceeds the budget.
+    # @param query [String]
+    # @param max_tokens [Integer] approximate token budget for the context
+    # @param options [Hash] forwarded to {#search}
+    # @return [String] JSON string of [{ "url" =>, "content" => }, ...]
+    def search_context(query, max_tokens: 4000, **options)
+      budget = max_tokens * 4
+      used = 0
+      sources = []
+      search(query, **options).results.each do |result|
+        entry = { "url" => result.url, "content" => result.content }
+        sources << entry
+        used += JSON.generate(entry).length
+        break if used >= budget
+      end
+      JSON.generate(sources)
+    end
+
+    # Extract clean content from one or more URLs.
+    #
+    # @param urls [String, Array<String>] one URL or an array (max 20)
+    # @param query [String, nil] rerank extracted chunks by this intent
+    # @param chunks_per_source [Integer, nil] 1–5, only with +query+
+    # @param extract_depth [String, nil] "basic" or "advanced"
+    # @param include_images [Boolean, nil]
+    # @param include_favicon [Boolean, nil]
+    # @param format [String, nil] "markdown" or "text"
+    # @param timeout [Numeric, nil] per-request extraction timeout (1.0–60.0s)
+    # @param include_usage [Boolean, nil]
+    # @param extra [Hash] any additional request-body parameters
+    # @return [ExtractResponse]
+    def extract(urls, query: nil, chunks_per_source: nil, extract_depth: nil, include_images: nil,
+                include_favicon: nil, format: nil, timeout: nil, include_usage: nil, **extra)
+      body = {
+        urls: urls, query: query, chunks_per_source: chunks_per_source, extract_depth: extract_depth,
+        include_images: include_images, include_favicon: include_favicon, format: format,
+        timeout: timeout, include_usage: include_usage
+      }.merge(extra)
+      ExtractResponse.new(@connection.post("/extract", body))
+    end
+
+    # Crawl a site starting from a root URL, following links.
+    #
+    # @param url [String] root URL (required)
+    # @param instructions [String, nil] natural-language crawl guidance
+    # @param chunks_per_source [Integer, nil] 1–5, only with +instructions+
+    # @param max_depth [Integer, nil] 1–5
+    # @param max_breadth [Integer, nil] 1–500 links per level
+    # @param limit [Integer, nil] total links to process
+    # @param select_paths [Array<String>, nil] regex path allowlist
+    # @param select_domains [Array<String>, nil] regex domain allowlist
+    # @param exclude_paths [Array<String>, nil] regex path blocklist
+    # @param exclude_domains [Array<String>, nil] regex domain blocklist
+    # @param allow_external [Boolean, nil] follow external domains (default true)
+    # @param include_images [Boolean, nil]
+    # @param extract_depth [String, nil] "basic" or "advanced"
+    # @param format [String, nil] "markdown" or "text"
+    # @param include_favicon [Boolean, nil]
+    # @param timeout [Numeric, nil] 10–150s
+    # @param include_usage [Boolean, nil]
+    # @param extra [Hash] any additional request-body parameters
+    # @return [CrawlResponse]
+    def crawl(url, instructions: nil, chunks_per_source: nil, max_depth: nil, max_breadth: nil,
+              limit: nil, select_paths: nil, select_domains: nil, exclude_paths: nil,
+              exclude_domains: nil, allow_external: nil, include_images: nil, extract_depth: nil,
+              format: nil, include_favicon: nil, timeout: nil, include_usage: nil, **extra)
+      body = {
+        url: url, instructions: instructions, chunks_per_source: chunks_per_source,
+        max_depth: max_depth, max_breadth: max_breadth, limit: limit, select_paths: select_paths,
+        select_domains: select_domains, exclude_paths: exclude_paths, exclude_domains: exclude_domains,
+        allow_external: allow_external, include_images: include_images, extract_depth: extract_depth,
+        format: format, include_favicon: include_favicon, timeout: timeout, include_usage: include_usage
+      }.merge(extra)
+      CrawlResponse.new(@connection.post("/crawl", body))
+    end
+
+    # Map the structure of a site, returning discovered URLs.
+    #
+    # @param url [String] root URL (required)
+    # @param instructions [String, nil] natural-language mapping guidance
+    # @param max_depth [Integer, nil] 1–5
+    # @param max_breadth [Integer, nil] 1–500
+    # @param limit [Integer, nil] 1–500
+    # @param select_paths [Array<String>, nil] regex path allowlist
+    # @param select_domains [Array<String>, nil] regex domain allowlist
+    # @param exclude_paths [Array<String>, nil] regex path blocklist
+    # @param exclude_domains [Array<String>, nil] regex domain blocklist
+    # @param allow_external [Boolean, nil] follow external domains (default true)
+    # @param timeout [Numeric, nil] 10–150s
+    # @param include_usage [Boolean, nil]
+    # @param extra [Hash] any additional request-body parameters
+    # @return [MapResponse]
+    def map(url, instructions: nil, max_depth: nil, max_breadth: nil, limit: nil, select_paths: nil,
+            select_domains: nil, exclude_paths: nil, exclude_domains: nil, allow_external: nil,
+            timeout: nil, include_usage: nil, **extra)
+      body = {
+        url: url, instructions: instructions, max_depth: max_depth, max_breadth: max_breadth,
+        limit: limit, select_paths: select_paths, select_domains: select_domains,
+        exclude_paths: exclude_paths, exclude_domains: exclude_domains, allow_external: allow_external,
+        timeout: timeout, include_usage: include_usage
+      }.merge(extra)
+      MapResponse.new(@connection.post("/map", body))
+    end
+
+    # Start an asynchronous research task, or stream it live.
+    #
+    # Without a block this creates the task and returns immediately with a
+    # {ResearchTask} whose +status+ is "pending"; poll it with
+    # {#research_task} or {#wait_for_research}. With a block, the task is
+    # streamed and each Server-Sent Event is yielded as a {ResearchEvent}.
+    #
+    # @param input [String] the research question (required)
+    # @param model [String, nil] "mini", "pro", or "auto"
+    # @param output_schema [Hash, nil] JSON Schema for structured output
+    # @param citation_format [String, nil] "numbered", "mla", "apa", or "chicago"
+    # @param include_domains [Array<String>, nil] up to 20 preferred domains
+    # @param exclude_domains [Array<String>, nil] up to 20 blocked domains
+    # @param output_length [String, nil] "short", "standard", or "long"
+    # @param files [Array<Hash>, nil] up to 5 base64 file objects
+    # @param extra [Hash] any additional request-body parameters
+    # @yieldparam event [ResearchEvent] (streaming mode only)
+    # @return [ResearchTask, nil] the queued task, or nil when streaming
+    def research(input, model: nil, output_schema: nil, citation_format: nil, include_domains: nil,
+                 exclude_domains: nil, output_length: nil, files: nil, **extra, &block)
+      body = {
+        input: input, model: model, output_schema: output_schema, citation_format: citation_format,
+        include_domains: include_domains, exclude_domains: exclude_domains,
+        output_length: output_length, files: files
+      }.merge(extra)
+
+      if block
+        @connection.stream("/research", body.merge(stream: true), &block)
+        nil
+      else
+        ResearchTask.new(@connection.post("/research", body))
+      end
+    end
+
+    # Fetch the current status and (when finished) result of a research task.
+    # @param request_id [String]
+    # @return [ResearchTask]
+    def research_task(request_id)
+      ResearchTask.new(@connection.get("/research/#{request_id}"))
+    end
+
+    # Poll a research task until it completes or fails.
+    #
+    # @param request_id [String]
+    # @param poll_interval [Numeric] seconds between polls
+    # @param timeout [Numeric] overall timeout in seconds
+    # @yieldparam task [ResearchTask] optional progress callback on each poll
+    # @raise [Tavily::Error] if the task fails or the timeout is exceeded
+    # @return [ResearchTask] the completed task
+    def wait_for_research(request_id, poll_interval: DEFAULT_POLL_INTERVAL,
+                          timeout: DEFAULT_POLL_TIMEOUT)
+      deadline = monotonic_now + timeout
+      loop do
+        task = research_task(request_id)
+        yield task if block_given?
+        return task if task.completed?
+        raise Error, "Research task #{request_id} failed" if task.failed?
+
+        if monotonic_now >= deadline
+          raise TimeoutError,
+                "Research task #{request_id} did not complete within #{timeout}s"
+        end
+
+        sleep(poll_interval)
+      end
+    end
+
+    private
+
+    def build_config(api_key, options)
+      cfg = Tavily.configuration.dup
+      cfg.api_key = api_key unless api_key.nil?
+      options.each do |key, value|
+        setter = "#{key}="
+        raise ConfigurationError, "Unknown configuration option: #{key.inspect}" unless cfg.respond_to?(setter)
+
+        cfg.public_send(setter, value)
+      end
+      cfg
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end