# exa-labs/exa-py architecture

> Architecture diagram of the GitHub repository exa-labs/exa-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exa-labs/exa-py
- Repository: https://github.com/exa-labs/exa-py

## Overview

##### Project Type and Purpose
- This is a Python SDK (software development kit) for interacting with the Exa (formerly Metaphor) API.
- It exposes a high-level client (`Exa`) and sub-clients for specialized features (search, research tasks, websets, webhooks, etc.), wrapping Exa’s HTTP/REST API.

##### File Structure Analysis
- Top-level:
- `exa_py/` – the core package exposing modules and entry point (`api.py`).
- `examples/` – sample scripts showing how to use the SDK.
- `docs/` – Sphinx documentation.
- `tests/` – unit tests for websets.
- Inside `exa_py/`:
- `api.py` – defines the main `Exa` class and HTTP logic.
- `utils.py` – helper functions (e.g., request building, response parsing).
- `research/` – research-task submodule (create tasks with JSON schemas).
- `websets/` – “Websets” submodule, with further subpackages:
– `_generator/` for Jinja2-based Pydantic model codegen
– `core`, `client.py`, `items`, `searches`, `webhooks`, `enrichments`
- Config and CI:
- `pyproject.toml` / `setup.py` – package metadata and dependencies
- `.github/workflows/` – CI for running examples
- `publish.sh` – release script

##### Key Architectural Insights from README
- Single HTTP client (`Exa`) initialized with an API key.
- Core operations: `search`, `answer`, `find_similar`, `get_contents`, plus streaming answer.
- Extended features behind `exa.research` and `exa.websets`.

##### Main Components
a. Client Library (Python SDK)
- Core Client (`Exa` in `api.py`)
- Utilities (`utils.py`)
- Sub-clients / Modules:
· `research` – handles structured research tasks with JSON schema
· `websets` – grouped functionality (generation of Pydantic models, client classes for items/searches/webhooks/enrichments)
b. Developer Application
- Your Python code (in `examples/` or real app) imports `exa_py` and calls methods
c. Exa REST API (External Service)
- The remote server that receives HTTP requests from the SDK and returns JSON
d. Build & Continuous Integration
- Sphinx docs builder (docs/)
- GitHub Actions workflow running examples and tests

##### Relationships and Data Flows
- Developer App → (import) → SDK Core Client
- Core Client → (HTTP/JSON) → Exa REST API
- API → (JSON) → Core Client → (Pydantic models or raw dicts) → Developer App
- Codegen: `_generator` uses Jinja2 templates → generates Pydantic `BaseModel` classes used by sub-clients
- Tests → exercise `websets` submodule; Examples → demonstrate all major SDK calls

##### Architectural Patterns & Design Principles
- Facade Pattern: `Exa` class hides HTTP details behind simple methods
- Modularization: separate subpackages for distinct feature sets (search vs. research vs. websets)
- Code Generation: Jinja2 templates + Pydantic for strong typing of API responses
- Asynchronous Support: examples under `examples/async/` illustrate non-blocking versions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Application
    DevApp["Developer Application<br/>(examples/*.py)"]:::dev
    DevAppAsync["Developer Application<br/>(examples/async/*.py)"]:::dev
    DevAppWeb["Developer Application<br/>(examples/websets/*.py)"]:::dev

    %% SDK Core
    subgraph "exa_py SDK"
        direction TB
        SDK_API["Core Client<br/>(api.py)"]:::sdk
        SDK_Utils["Utilities<br/>(utils.py)"]:::sdk

        subgraph "research" 
            direction TB
            SDK_Research_Client["Research Client<br/>(client.py)"]:::sdk
            SDK_Research_Models["Research Models<br/>(models.py)"]:::sdk
        end

        subgraph "websets"
            direction TB
            WS_Client["Websets Client<br/>(client.py)"]:::sdk
            WS_Types["Shared Types<br/>(types.py)"]:::sdk
            WS_Core["Core Abstractions<br/>(core/base.py)"]:::sdk

            subgraph "Code Generation"
                direction TB
                WS_Generator["Pydantic Templates<br/>(_generator/pydantic/BaseModel.jinja2)"]:::gen
                GenModels["Generated Pydantic Models"]:::gen
            end

            WS_Items["Items Client<br/>(items/client.py)"]:::sdk
            WS_Searches["Searches Client<br/>(searches/client.py)"]:::sdk
            WS_Webhooks["Webhooks Client<br/>(webhooks/client.py)"]:::sdk
            WS_Enrichments["Enrichments Client<br/>(enrichments/client.py)"]:::sdk
        end
    end

    %% External API
    ExaAPI["Exa REST API<br/>(HTTP/JSON)"]:::external

    %% CI/CD & Docs
    subgraph "CI/CD & Documentation"
        direction TB
        Docs["Sphinx Docs<br/>(docs/)"]:::docs
        CI["GitHub Actions<br/>(.github/workflows/)"]:::ci
        Packaging["Packaging & Build<br/>(pyproject.toml, setup.py, publish.sh)"]:::ci
    end

    %% Relationships
    DevApp -->|import & method call| SDK_API
    DevAppAsync -->|import & async call| SDK_API
    DevAppWeb -->|import & websets use| WS_Client

    SDK_API -->|uses| SDK_Utils
    SDK_API -->|HTTP GET/POST| ExaAPI
    ExaAPI -->|JSON response| SDK_API

    SDK_API -->|delegates| SDK_Research_Client
    SDK_API -->|delegates| WS_Client

    SDK_Research_Client -->|uses| SDK_Research_Models
    SDK_Research_Client -->|HTTP JSON| ExaAPI

    WS_Client -->|uses| WS_Types
    WS_Client -->|uses| WS_Core
    WS_Client -->|calls codegen| WS_Generator
    WS_Generator -->|generates| GenModels
    WS_Client -->|imports| GenModels

    WS_Client -->|handles| WS_Items
    WS_Client -->|handles| WS_Searches
    WS_Client -->|handles| WS_Webhooks
    WS_Client -->|handles| WS_Enrichments

    WS_Items -->|HTTP JSON| ExaAPI
    WS_Searches -->|HTTP JSON| ExaAPI
    WS_Webhooks -->|HTTP JSON| ExaAPI
    WS_Enrichments -->|HTTP JSON| ExaAPI

    CI -->|runs tests & examples| DevApp
    CI -->|builds docs| Docs

    Docs -->|document modules| SDK_API
    Docs -->|document modules| SDK_Research_Client
    Docs -->|document modules| WS_Client

    Packaging -->|defines metadata| SDK_API

    %% Click Events
    click SDK_API "https://github.com/exa-labs/exa-py/blob/master/exa_py/api.py"
    click SDK_Utils "https://github.com/exa-labs/exa-py/blob/master/exa_py/utils.py"
    click SDK_Research_Client "https://github.com/exa-labs/exa-py/blob/master/exa_py/research/client.py"
    click SDK_Research_Models "https://github.com/exa-labs/exa-py/blob/master/exa_py/research/models.py"
    click WS_Client "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/client.py"
    click WS_Types "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/types.py"
    click WS_Core "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/core/base.py"
    click WS_Generator "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/_generator/pydantic/BaseModel.jinja2"
    click WS_Items "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/items/client.py"
    click WS_Searches "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/searches/client.py"
    click WS_Webhooks "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/webhooks/client.py"
    click WS_Enrichments "https://github.com/exa-labs/exa-py/blob/master/exa_py/websets/enrichments/client.py"
    click DevApp "https://github.com/exa-labs/exa-py/tree/master/examples/"
    click DevAppAsync "https://github.com/exa-labs/exa-py/tree/master/examples/async/"
    click DevAppWeb "https://github.com/exa-labs/exa-py/tree/master/examples/websets/"
    click Docs "https://github.com/exa-labs/exa-py/tree/master/docs/"
    click CI "https://github.com/exa-labs/exa-py/blob/master/.github/workflows/run_examples.yml"
    click Packaging "https://github.com/exa-labs/exa-py/blob/master/pyproject.toml"

    %% Styles
    classDef sdk fill:#D0E8FF,stroke:#0366D6,font-weight:bold
    classDef dev fill:#E6FFDD,stroke:#28A745,font-weight:bold
    classDef external fill:#F0F0F0,stroke:#6A737D,font-weight:bold
    classDef gen fill:#FFE5B4,stroke:#FF8C00,font-weight:bold
    classDef docs fill:#F5E6FF,stroke:#6F42C1,font-weight:bold
    classDef ci fill:#EFEFEF,stroke:#444444,font-weight:bold
```
