# tavily-ai/tavily-python architecture

> Architecture diagram of the GitHub repository tavily-ai/tavily-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tavily-ai/tavily-python
- Repository: https://github.com/tavily-ai/tavily-python

## Overview

1. **What this repo is**
   - This is a **Python SDK wrapper** for the Tavily API, not a standalone application.
   - Its architecture is centered on exposing Tavily’s web/search/research capabilities through a small client library.

2. **Primary runtime boundary**
   - The main boundary is between **user Python code** and the **remote Tavily API**.
   - The SDK prepares request parameters, performs HTTP calls, parses responses, and returns Python-native objects/dicts/streams.

3. **Core client layer**
   - The package exposes at least two client entry points:
     - `TavilyClient` for synchronous usage
     - `AsyncTavilyClient` for async usage
   - These are the main façade objects that application code interacts with.

4. **Endpoint-oriented API surface**
   - The client layer maps directly to Tavily product capabilities:
     - search
     - extract
     - crawl
     - map
     - research
     - search-context / Q&A style helpers
   - This suggests a thin wrapper architecture where each method corresponds closely to a backend endpoint or operation.

5. **Sync vs async transport**
   - The repo separates synchronous and asynchronous HTTP handling into different modules:
     - `tavily/tavily.py`
     - `tavily/async_tavily.py`
   - This is an important architectural split for diagramming: same API surface, two transport implementations.

6. **HTTP session injection boundary**
   - The README explicitly supports injecting a custom `requests.Session` or `httpx.AsyncClient`.
   - This means the SDK can operate in two modes:
     - Tavily-managed auth/session lifecycle
     - externally managed enterprise gateway/session lifecycle
   - The SDK respects external headers/proxies and does not close externally provided clients.

7. **Configuration and defaults**
   - `tavily/config.py` likely centralizes base URL, API key handling, and default request settings.
   - `tavily/utils.py` likely contains request/response helpers, validation, or serialization logic used across endpoints.
   - `tavily/errors.py` defines the SDK’s error boundary, translating API or transport failures into SDK exceptions.

8. **RAG-specific helper subsystem**
   - There is a dedicated subpackage: `tavily/hybrid_rag`.
   - This looks like an integration helper for building retrieval-augmented generation workflows using Tavily search/context outputs.
   - It is separate from the core client, which indicates an application-level helper layer rather than a core transport concern.

9. **Data flow pattern**
   - Typical flow is:
     - caller instantiates client
     - client builds request payload
     - HTTP request goes to Tavily API
     - API response returns
     - SDK formats or forwards the result
   - For research streaming, the flow becomes incremental: the client returns a stream of chunks instead of a single completed response.

10. **Examples as usage boundaries**
   - `examples/` contains usage-focused entry points for:
     - company information
     - hybrid RAG
     - OpenAI assistant integration
   - These show the SDK is intended to be embedded inside larger AI or automation systems rather than run on its own.

11. **Test architecture**
   - Tests are organized by feature: search, map, crawl, research, errors, custom session, session pooling.
   - `tests/request_intercept.py` and `tests/conftest.py` suggest HTTP interception/mocking to verify request construction without calling the live API.
   - `tests/test_session_pooling.py` indicates explicit coverage for connection/session lifecycle behavior.

12. **External dependencies that matter architecturally**
   - The README and tests imply the main transport stack is:
     - `requests` for sync
     - `httpx` for async
   - CI is run via GitHub Actions (`.github/workflows/tests.yml`), reinforcing that this is a packaged library with automated compatibility/testing rather than a service.

13. **How to draw the architecture**
   - A useful diagram would show:
     - application code on the left
     - sync/async Tavily SDK clients in the middle
     - optional custom session/client injection as a side path
     - Tavily API on the right
     - separate helper lane for `hybrid_rag`
     - tests/CI as a validation plane around the library

Main entry points: [`tavily/tavily.py`](https://github.com/tavily-ai/tavily-python/blob/master/tavily/tavily.py) (TavilyClient), [`tavily/async_tavily.py`](https://github.com/tavily-ai/tavily-python/blob/master/tavily/async_tavily.py) (AsyncTavilyClient), [`tavily/hybrid_rag/hybrid_rag.py`](https://github.com/tavily-ai/tavily-python/blob/master/tavily/hybrid_rag/hybrid_rag.py) (Hybrid RAG), [`tavily/errors.py`](https://github.com/tavily-ai/tavily-python/blob/master/tavily/errors.py) (Errors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core SDK"]
  node_sync_client["TavilyClient<br/>sync client<br/>[tavily.py]"]
  node_async_client["AsyncTavilyClient<br/>async client<br/>[async_tavily.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_utils["Utils<br/>helpers<br/>[utils.py]"]
  node_errors["Errors<br/>exceptions<br/>[errors.py]"]
  node_requests_session[("Requests Session<br/>injected transport")]
  node_httpx_client[("HTTPX Client<br/>injected transport")]
  node_search{{"Search<br/>endpoint"}}
  node_extract{{"Extract<br/>endpoint"}}
  node_crawl{{"Crawl<br/>endpoint"}}
  node_map{{"Map<br/>endpoint"}}
  node_research{{"Research<br/>endpoint"}}
  node_search_context{{"Search Context<br/>qa helper"}}
end

subgraph group_helper["RAG Helper"]
  node_hybrid_rag["Hybrid RAG<br/>integration helper<br/>[hybrid_rag.py]"]
end

subgraph group_examples["Examples"]
  node_example_suite["Examples<br/>usage demos"]
end

subgraph group_validation["Validation"]
  node_tests["Test Suite<br/>validation"]
  node_intercept["Request Intercept<br/>test harness"]
  node_session_pooling["Session Pooling<br/>transport test"]
  node_ci["CI Workflow<br/>github actions<br/>[tests.yml]"]
end

node_app(("User Code<br/>caller"))
node_api[("Tavily API<br/>remote api")]

node_app -->|"uses"| node_sync_client
node_app -->|"uses"| node_async_client
node_sync_client -->|"reads"| node_config
node_sync_client -->|"uses"| node_utils
node_sync_client -->|"raises"| node_errors
node_async_client -->|"reads"| node_config
node_async_client -->|"uses"| node_utils
node_async_client -->|"raises"| node_errors
node_sync_client -->|"accepts"| node_requests_session
node_async_client -->|"accepts"| node_httpx_client
node_sync_client -->|"invokes"| node_search
node_sync_client -->|"invokes"| node_extract
node_sync_client -->|"invokes"| node_crawl
node_sync_client -->|"invokes"| node_map
node_sync_client -->|"invokes"| node_research
node_sync_client -->|"invokes"| node_search_context
node_async_client -->|"invokes"| node_search
node_async_client -->|"invokes"| node_extract
node_async_client -->|"invokes"| node_crawl
node_async_client -->|"invokes"| node_map
node_async_client -->|"invokes"| node_research
node_async_client -->|"invokes"| node_search_context
node_search -->|"calls"| node_api
node_extract -->|"calls"| node_api
node_crawl -->|"calls"| node_api
node_map -->|"calls"| node_api
node_research -->|"calls"| node_api
node_search_context -->|"calls"| node_api
node_hybrid_rag -->|"builds on"| node_search
node_hybrid_rag -->|"builds on"| node_search_context
node_hybrid_rag -->|"builds on"| node_research
node_example_suite -->|"demonstrates"| node_sync_client
node_example_suite -->|"demonstrates"| node_async_client
node_example_suite -->|"demonstrates"| node_hybrid_rag
node_tests -->|"verifies"| node_sync_client
node_tests -->|"verifies"| node_async_client
node_tests -->|"uses"| node_intercept
node_tests -->|"covers"| node_session_pooling
node_tests -->|"verifies"| node_errors
node_ci -->|"runs"| node_tests

click node_sync_client "https://github.com/tavily-ai/tavily-python/blob/master/tavily/tavily.py"
click node_async_client "https://github.com/tavily-ai/tavily-python/blob/master/tavily/async_tavily.py"
click node_config "https://github.com/tavily-ai/tavily-python/blob/master/tavily/config.py"
click node_utils "https://github.com/tavily-ai/tavily-python/blob/master/tavily/utils.py"
click node_errors "https://github.com/tavily-ai/tavily-python/blob/master/tavily/errors.py"
click node_hybrid_rag "https://github.com/tavily-ai/tavily-python/blob/master/tavily/hybrid_rag/hybrid_rag.py"
click node_intercept "https://github.com/tavily-ai/tavily-python/blob/master/tests/request_intercept.py"
click node_session_pooling "https://github.com/tavily-ai/tavily-python/blob/master/tests/test_session_pooling.py"
click node_ci "https://github.com/tavily-ai/tavily-python/blob/master/.github/workflows/tests.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sync_client,node_async_client,node_config,node_utils,node_errors,node_requests_session,node_httpx_client,node_search,node_extract,node_crawl,node_map,node_research,node_search_context toneBlue
class node_hybrid_rag toneAmber
class node_example_suite toneMint
class node_tests,node_intercept,node_session_pooling,node_ci toneRose
class node_app,node_api toneNeutral
```

## Components

### Core SDK

Primary synchronous and asynchronous Tavily client surface plus shared support modules.

- [TavilyClient](https://github.com/tavily-ai/tavily-python/blob/master/tavily/tavily.py): sync client · Synchronous façade for Tavily operations. · `tavily/tavily.py`
- [AsyncTavilyClient](https://github.com/tavily-ai/tavily-python/blob/master/tavily/async_tavily.py): async client · Asynchronous façade for Tavily operations. · `tavily/async_tavily.py`
- [Config](https://github.com/tavily-ai/tavily-python/blob/master/tavily/config.py): settings · Centralized defaults such as base URL, API key, and request settings. · `tavily/config.py`
- [Utils](https://github.com/tavily-ai/tavily-python/blob/master/tavily/utils.py): helpers · Shared request, response, and serialization helpers. · `tavily/utils.py`
- [Errors](https://github.com/tavily-ai/tavily-python/blob/master/tavily/errors.py): exceptions · SDK exception boundary for API and transport failures. · `tavily/errors.py`
- **Requests Session**: injected transport · Optional externally managed synchronous HTTP session.
- **HTTPX Client**: injected transport · Optional externally managed asynchronous HTTP client.
- **Search**: endpoint · Core web search operation exposed by the clients.
- **Extract**: endpoint · Content extraction operation exposed by the clients.
- **Crawl**: endpoint · Site crawling operation exposed by the clients.
- **Map**: endpoint · Mapping or discovery operation exposed by the clients.
- **Research**: endpoint · Research workflow, including streaming output behavior.
- **Search Context**: qa helper · Q&A or context-oriented helper built on Tavily search/context outputs.

### RAG Helper

Application-oriented helper layer built on top of Tavily capabilities.

- [Hybrid RAG](https://github.com/tavily-ai/tavily-python/blob/master/tavily/hybrid_rag/hybrid_rag.py): integration helper · Helper subpackage for retrieval-augmented generation workflows. · `tavily/hybrid_rag/hybrid_rag.py`

### Examples

Usage entry points showing how the SDK is embedded in larger systems.

- **Examples**: usage demos · Example scripts for company information, hybrid RAG, and OpenAI assistant integration.

### Validation

Tests and CI that verify request construction, transport behavior, and endpoint coverage.

- **Test Suite**: validation · Feature-oriented tests for endpoints, errors, sessions, and pooling behavior.
- [Request Intercept](https://github.com/tavily-ai/tavily-python/blob/master/tests/request_intercept.py): test harness · HTTP interception and mocking used to verify request construction without live API calls. · `tests/request_intercept.py`
- [Session Pooling](https://github.com/tavily-ai/tavily-python/blob/master/tests/test_session_pooling.py): transport test · Coverage for connection reuse and externally managed session lifecycle. · `tests/test_session_pooling.py`
- [CI Workflow](https://github.com/tavily-ai/tavily-python/blob/master/.github/workflows/tests.yml): github actions · Automated test execution in GitHub Actions. · `.github/workflows/tests.yml`

### Other components

- **User Code**: caller · Application code that consumes the Tavily SDK.
- **Tavily API**: remote api · Remote Tavily backend that receives SDK requests and returns results.

## Connections

- User Code → TavilyClient: uses · Python code instantiates the synchronous client for API calls.
- User Code → AsyncTavilyClient: uses · Python code instantiates the asynchronous client for API calls.
- TavilyClient → Config: reads · Sync client consumes shared defaults and base configuration.
- TavilyClient → Utils: uses · Sync client delegates request and response handling.
- TavilyClient → Errors: raises · Sync client surfaces SDK exceptions on failures.
- AsyncTavilyClient → Config: reads · Async client consumes shared defaults and base configuration.
- AsyncTavilyClient → Utils: uses · Async client delegates request and response handling.
- AsyncTavilyClient → Errors: raises · Async client surfaces SDK exceptions on failures.
- TavilyClient → Requests Session: accepts · Sync transport can use an externally managed requests session.
- AsyncTavilyClient → HTTPX Client: accepts · Async transport can use an externally managed httpx client.
- TavilyClient → Search: invokes · Client method maps to the search endpoint.
- TavilyClient → Extract: invokes · Client method maps to the extract endpoint.
- TavilyClient → Crawl: invokes · Client method maps to the crawl endpoint.
- TavilyClient → Map: invokes · Client method maps to the map endpoint.
- TavilyClient → Research: invokes · Client method maps to the research endpoint.
- TavilyClient → Search Context: invokes · Client exposes context or Q&A oriented helper behavior.
- AsyncTavilyClient → Search: invokes · Async client maps to the search endpoint.
- AsyncTavilyClient → Extract: invokes · Async client maps to the extract endpoint.
- AsyncTavilyClient → Crawl: invokes · Async client maps to the crawl endpoint.
- AsyncTavilyClient → Map: invokes · Async client maps to the map endpoint.
- AsyncTavilyClient → Research: invokes · Async client maps to the research endpoint.
- AsyncTavilyClient → Search Context: invokes · Async client exposes context or Q&A oriented helper behavior.
- Search → Tavily API: calls · Search requests are sent to the Tavily backend.
- Extract → Tavily API: calls · Extract requests are sent to the Tavily backend.
- Crawl → Tavily API: calls · Crawl requests are sent to the Tavily backend.
- Map → Tavily API: calls · Map requests are sent to the Tavily backend.
- Research → Tavily API: calls · Research requests and streaming chunks come from the Tavily backend.
- Search Context → Tavily API: calls · Context helper builds on backend search/context operations.
- Hybrid RAG → Search: builds on · Hybrid RAG uses search outputs as retrieval inputs.
- Hybrid RAG → Search Context: builds on · Hybrid RAG composes context-oriented SDK behavior.
- Hybrid RAG → Research: builds on · Hybrid RAG can incorporate research workflows.
- Examples → TavilyClient: demonstrates · Examples show synchronous SDK usage patterns.
- Examples → AsyncTavilyClient: demonstrates · Examples show asynchronous SDK usage patterns.
- Examples → Hybrid RAG: demonstrates · Examples include the RAG helper integration.
- Test Suite → TavilyClient: verifies · Tests exercise synchronous client behavior.
- Test Suite → AsyncTavilyClient: verifies · Tests exercise asynchronous client behavior.
- Test Suite → Request Intercept: uses · Tests intercept requests to validate payload construction.
- Test Suite → Session Pooling: covers · Tests cover session reuse and lifecycle behavior.
- Test Suite → Errors: verifies · Tests validate SDK error mapping and handling.
- CI Workflow → Test Suite: runs · GitHub Actions executes the test suite.
