How exa-labs/exa-py works
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