Tavily Core

#Overview

The TavilyDeepResearch class is a dynamic wrapper over the TavilyClient of the tavily library. Instead of defining its own signature for each operation, each method receives a single configuration dictionary (params) and forwards it, as named arguments, to the corresponding method of the Tavily client.

In practice, this gives maximum flexibility: any parameter accepted by Tavily can be sent without changing the class. It is the Tavily access layer used by the Context Builder, which turns a web search into context ready for language models.

#Execution Flow

1. Instantiation: the class receives an optional API key. If it is not provided, it is read from the TAVILY_API_KEY environment variable.
2. Key validation: if no key is found, a RuntimeError is raised.
3. Client creation: a TavilyClient is created with the key and stored in self.client.
4. Method call: the user calls a method (for example, start_search) passing a dictionary with the operation's parameters.
5. Parameter forwarding: the dictionary is unpacked with **params and sent to the same-named method of the Tavily client, whose return value is returned unchanged.

#Class Methods Table

#Environment Variables

• TAVILY_API_KEY: Tavily API key. Used when api_key is not passed to the constructor. The module calls load_dotenv() when imported, so the variable can also come from a .env file.

#Important Architecture Points and Insights

• Thin, dynamic wrapper: the class neither validates nor transforms the parameters; it only forwards them. The accepted names and values are those of the tavily library.
• Return without processing: the methods return exactly what the Tavily client returns. Processing, filtering and formatting are left to the caller, such as the Context Builder.
• Errors: besides the key check in the constructor, the class does not catch exceptions. Any Tavily error propagates to the caller.
• Autonomous research topic: in start_research, the topic is sent in the input key, which is the name used by the original library's research method.

#Class and Methods Description

#TavilyDeepResearch Class

#Description

Dynamic wrapper for Tavily AI. Receives configuration dictionaries for maximum flexibility.

#Constructor Arguments

#Methods

#1. __init__

#Description

Resolves the API key (argument or environment variable) and creates the TavilyClient.

#Arguments

• api_key (str | None): Tavily API key.

#Returns

• Does not return a value.

#Raises

• RuntimeError: if the key is not provided and TAVILY_API_KEY is not defined.

#Examples

# Usando a chave definida em TAVILY_API_KEY
researcher = TavilyDeepResearch()

# Informando a chave diretamente
researcher = TavilyDeepResearch(api_key="tvly-...")

#2. start_search

#Description

General search. Expects keys such as query, search_depth, max_results, among others accepted by Tavily.

#Arguments

• params (Dict[str, Any]): search parameters, forwarded to client.search.

#Returns

• dict: search response.

#Examples

result = researcher.start_search({
    "query": "Quais as principais tendências de IA em 2026?",
    "search_depth": "advanced",
    "max_results": 5,
})

#3. get_context

#Description

Returns context for LLMs. Expects query, max_tokens, among others.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.get_search_context.

#Returns

• str: context for use in language models.

#Examples

context = researcher.get_context({"query": "tendências de IA em 2026", "max_tokens": 1500})

#4. qna

#Description

Direct question and answer. Usually requires only {'query': 'sua pergunta'}.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.qna_search.

#Returns

• str: answer to the question.

#Examples

answer = researcher.qna({"query": "Quem criou a linguagem Python?"})

#5. extract_content

#Description

Content extraction. Expects urls (list or string) and format.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.extract.

#Returns

• dict: extracted content.

#Examples

content = researcher.extract_content({"urls": ["https://example.com"], "format": "markdown"})

#6. map_site

#Description

Maps the URL structure of a site. Expects url and, optionally, limit.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.map.

#Returns

• dict: map of the site's URLs.

#Examples

site_map = researcher.map_site({"url": "https://example.com", "limit": 50})

#7. crawl_site

#Description

Explores a site recursively. Expects url, limit and max_depth.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.crawl.

#Returns

• dict: result of the exploration.

#Examples

crawl = researcher.crawl_site({"url": "https://example.com", "limit": 20, "max_depth": 2})

#8. get_company

#Description

Firmographic data of a company. Expects query.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.get_company_info.

#Returns

• List[dict]: company data.

#Examples

company = researcher.get_company({"query": "Tavily"})

#9. start_research

#Description

Starts the autonomous research agent. Expects input (the topic) and model.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.research. The original library uses input for the topic.

#Returns

• dict: response to the research request.

#Examples

research = researcher.start_research({"input": "Mercado de energia solar no Brasil", "model": "gpt-4o-mini"})

#10. get_research_status

#Description

Checks the status of a research started with start_research. Expects request_id.

#Arguments

• params (Dict[str, Any]): parameters forwarded to client.get_research.

#Returns

• dict: research status.

#Examples

status = researcher.get_research_status({"request_id": "..."})