sema-tavily

Search the web and extract page content through the Tavily API with typed errors.

Install

sema pkg add sema-tavily

Quick start

(import "sema-tavily")

(define client (tavily/client))          ; reads TAVILY_API_KEY from the env

(define r (tavily/search client "who won the 2022 world cup"
                         {:max_results 3 :include_answer #t}))

(println (get r :answer))
;; => "Argentina won the 2022 FIFA World Cup..."

(for-each (fn (hit) (println (get hit :url)))
          (get r :results))
;; => https://...
;;    https://...
;;    https://...

API

(tavily/client opts?)

Builds a client map. opts is an optional map: :api-key (default: TAVILY_API_KEY env var), :base-url (default "https://api.tavily.com"), :timeout in ms (default 60000). Errors if no key is found.

(tavily/client)                          ; key from TAVILY_API_KEY
(tavily/client {:api-key "tvly-..."})    ; explicit key

(tavily/search client query opts?)

Runs a web search for query. Returns a map with :answer (when requested), :results (a list of {:title :url :content :score}), and :query. opts is an optional map merged into the request body.

Common options: :search_depth ("basic" default, or "advanced"), :max_results (default 5), :topic ("general", "news", "finance"), :include_answer (#f), :include_raw_content (#f), :include_domains, :exclude_domains, :time_range.

(tavily/search client "latest rust release"
               {:topic "news" :max_results 5 :include_answer "advanced"})

(tavily/extract client urls opts?)

Extracts cleaned content from one or more page URLs. urls is a URL string or a list of URL strings. Returns a map with :results (a list of {:url :raw_content}) and :failed_results. opts is an optional map merged into the request body: :extract_depth ("basic" default, or "advanced"), :format ("markdown" default, or "text"), :include_images (#f).

(tavily/extract client (list "https://example.com" "https://sema-lisp.org")
                {:extract_depth "advanced"})

(tavily/request client method path body)

Low-level request used by all wrappers. method is "GET"/"POST"/..., path an API path ("/search"), body a map (JSON-encoded) or nil. Returns the decoded JSON body; raises on non-2xx with method, path, status, and the API's error message.

(tavily/request client "POST" "/search" {:query "sema lisp" :max_results 1})

Authentication

Get an API key from tavily.com (keys are prefixed tvly-). Provide it either way:

• Set the TAVILY_API_KEY environment variable, then call (tavily/client).
• Pass it explicitly: (tavily/client {:api-key "tvly-..."}).

The key is sent as Authorization: Bearer <key> and is never logged.

Testing

sema tests.sema

The offline suite (client construction, argument validation, error mapping) always runs. Live tests hit api.tavily.com and run only when TAVILY_API_KEY is set.

License

MIT