# vespa-engine/pyvespa architecture

> Architecture diagram of the GitHub repository vespa-engine/pyvespa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vespa-engine/pyvespa
- Repository: https://github.com/vespa-engine/pyvespa

## Overview

pyvespa is a Python API for creating and modifying Vespa applications, deploying them, interacting with running instances, and evaluating retrieval behavior. The principal workflow is to define an application package, deploy it, then query or feed documents through the application API; evaluation and MTEB benchmarking are additional branches. The repository also includes a Python wrapper for the Vespa CLI. Relationships are limited to those shown in the README or source index; unsampled implementation details are not inferred.

Main entry points: [`vespa/application.py`](https://github.com/vespa-engine/pyvespa/blob/master/vespa/application.py) (Application API), [`vespa/package.py`](https://github.com/vespa-engine/pyvespa/blob/master/vespa/package.py) (Application package), [`vespa/evaluation/_mteb.py`](https://github.com/vespa-engine/pyvespa/blob/master/vespa/evaluation/_mteb.py) (MTEB benchmarking), [`vespa/deployment.py`](https://github.com/vespa-engine/pyvespa/blob/master/vespa/deployment.py) (Deployment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Application authoring"]
  node_package["Application package<br/>[package.py]"]
  node_xml["XML configuration<br/>[vt.py]"]
  node_services["Services config<br/>[services.py]"]
  node_deploy_config["Deployment config<br/>[deployment.py]"]
  node_query_profiles["Query profiles<br/>[query_profiles.py]"]
  node_query_builder["Query builder<br/>[builder.py]"]
  node_grouping["Grouping expressions<br/>[grouping.py]"]
end

subgraph group_runtime["Serving interactions"]
  node_application["Application API<br/>[application.py]"]
  node_responses["API responses<br/>[io.py]"]
  node_retry["Retry policies<br/>[retries.py]"]
  node_throttling["Request throttling<br/>[throttling.py]"]
end

subgraph group_operations["Deployment and operations"]
  node_deployment["Deployment API<br/>[deployment.py]"]
  node_cli_wrapper["Vespa CLI wrapper<br/>[__init__.py]"]
  node_cli_binaries["CLI binaries"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Retrieval evaluation<br/>[_base.py]"]
  node_mteb["MTEB benchmarking<br/>[_mteb.py]"]
  node_models["Model utilities<br/>[models.py]"]
end

node_user(("Developer"))
node_vespa_service{{"Vespa service"}}

node_user -->|"defines app"| node_package
node_user -->|"deploys app"| node_deployment
node_user -->|"interacts with"| node_application
node_package -->|"uses config"| node_xml
node_package -->|"uses config"| node_services
node_package -->|"uses config"| node_deploy_config
node_package -->|"uses profiles"| node_query_profiles
node_services -->|"builds tags"| node_xml
node_deploy_config -->|"builds tags"| node_xml
node_query_profiles -->|"builds tags"| node_xml
node_user -->|"builds queries"| node_query_builder
node_user -->|"builds expressions"| node_grouping
node_application -->|"sends requests"| node_vespa_service
node_application -->|"creates responses"| node_responses
node_application -->|"uses retries"| node_retry
node_application -->|"uses throttling"| node_throttling
node_deployment -->|"deploys package"| node_package
node_deployment -->|"deploys to"| node_vespa_service
node_user -->|"uses wrapper"| node_cli_wrapper
node_cli_wrapper -->|"downloads binaries"| node_cli_binaries
node_user -->|"evaluates retrieval"| node_evaluation
node_evaluation -->|"queries app"| node_application
node_user -->|"runs benchmarks"| node_mteb
node_mteb -->|"uses app"| node_application
node_mteb -->|"deploys benchmark app"| node_deployment
node_mteb -->|"uses models"| node_models

click node_package "https://github.com/vespa-engine/pyvespa/blob/master/vespa/package.py"
click node_xml "https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/vt.py"
click node_services "https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/services.py"
click node_deploy_config "https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/deployment.py"
click node_query_profiles "https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/query_profiles.py"
click node_query_builder "https://github.com/vespa-engine/pyvespa/blob/master/vespa/querybuilder/builder/builder.py"
click node_grouping "https://github.com/vespa-engine/pyvespa/blob/master/vespa/querybuilder/grouping/grouping.py"
click node_application "https://github.com/vespa-engine/pyvespa/blob/master/vespa/application.py"
click node_responses "https://github.com/vespa-engine/pyvespa/blob/master/vespa/io.py"
click node_deployment "https://github.com/vespa-engine/pyvespa/blob/master/vespa/deployment.py"
click node_cli_wrapper "https://github.com/vespa-engine/pyvespa/blob/master/vespacli/vespacli/__init__.py"
click node_cli_binaries "https://github.com/vespa-engine/pyvespa/blob/master/vespacli/utils/download_binaries.py"
click node_retry "https://github.com/vespa-engine/pyvespa/blob/master/vespa/retries.py"
click node_throttling "https://github.com/vespa-engine/pyvespa/blob/master/vespa/throttling.py"
click node_evaluation "https://github.com/vespa-engine/pyvespa/blob/master/vespa/evaluation/_base.py"
click node_mteb "https://github.com/vespa-engine/pyvespa/blob/master/vespa/evaluation/_mteb.py"
click node_models "https://github.com/vespa-engine/pyvespa/blob/master/vespa/models.py"

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_package,node_xml,node_services,node_deploy_config,node_query_profiles,node_query_builder,node_grouping toneBlue
class node_application,node_responses,node_retry,node_throttling toneAmber
class node_deployment,node_cli_wrapper,node_cli_binaries toneMint
class node_evaluation,node_mteb,node_models toneRose
class node_user,node_vespa_service toneIndigo
```

## Components

### Application authoring

- [Application package](https://github.com/vespa-engine/pyvespa/blob/master/vespa/package.py): `vespa/package.py`
- [XML configuration](https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/vt.py): `vespa/configuration/vt.py`
- [Services config](https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/services.py): `vespa/configuration/services.py`
- [Deployment config](https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/deployment.py): `vespa/configuration/deployment.py`
- [Query profiles](https://github.com/vespa-engine/pyvespa/blob/master/vespa/configuration/query_profiles.py): `vespa/configuration/query_profiles.py`
- [Query builder](https://github.com/vespa-engine/pyvespa/blob/master/vespa/querybuilder/builder/builder.py): `vespa/querybuilder/builder/builder.py`
- [Grouping expressions](https://github.com/vespa-engine/pyvespa/blob/master/vespa/querybuilder/grouping/grouping.py): `vespa/querybuilder/grouping/grouping.py`

### Serving interactions

- [Application API](https://github.com/vespa-engine/pyvespa/blob/master/vespa/application.py): `vespa/application.py`
- [API responses](https://github.com/vespa-engine/pyvespa/blob/master/vespa/io.py): `vespa/io.py`
- [Retry policies](https://github.com/vespa-engine/pyvespa/blob/master/vespa/retries.py): `vespa/retries.py`
- [Request throttling](https://github.com/vespa-engine/pyvespa/blob/master/vespa/throttling.py): `vespa/throttling.py`

### Deployment and operations

- [Deployment API](https://github.com/vespa-engine/pyvespa/blob/master/vespa/deployment.py): `vespa/deployment.py`
- [Vespa CLI wrapper](https://github.com/vespa-engine/pyvespa/blob/master/vespacli/vespacli/__init__.py): `vespacli/vespacli/__init__.py`
- [CLI binaries](https://github.com/vespa-engine/pyvespa/blob/master/vespacli/utils/download_binaries.py): `vespacli/utils/download_binaries.py`

### Evaluation

- [Retrieval evaluation](https://github.com/vespa-engine/pyvespa/blob/master/vespa/evaluation/_base.py): `vespa/evaluation/_base.py`
- [MTEB benchmarking](https://github.com/vespa-engine/pyvespa/blob/master/vespa/evaluation/_mteb.py): `vespa/evaluation/_mteb.py`
- [Model utilities](https://github.com/vespa-engine/pyvespa/blob/master/vespa/models.py): `vespa/models.py`

### Other components

- **Developer**
- **Vespa service**

## Connections

- Developer → Application package: defines app (evidence: `README.md`)
- Developer → Deployment API: deploys app (evidence: `README.md`)
- Developer → Application API: interacts with (evidence: `README.md`)
- Application package → XML configuration: uses config (evidence: `vespa/package.py`)
- Application package → Services config: uses config (evidence: `vespa/package.py`)
- Application package → Deployment config: uses config (evidence: `vespa/package.py`)
- Application package → Query profiles: uses profiles (evidence: `vespa/package.py`)
- Services config → XML configuration: builds tags (evidence: `vespa/configuration/services.py`)
- Deployment config → XML configuration: builds tags (evidence: `vespa/configuration/deployment.py`)
- Query profiles → XML configuration: builds tags (evidence: `vespa/configuration/query_profiles.py`)
- Developer → Query builder: builds queries (evidence: `README.md`)
- Developer → Grouping expressions: builds expressions (evidence: `README.md`)
- Application API → Vespa service: sends requests (evidence: `vespa/application.py`)
- Application API → API responses: creates responses (evidence: `vespa/application.py`)
- Application API → Retry policies: uses retries (evidence: `vespa/application.py`)
- Application API → Request throttling: uses throttling (evidence: `vespa/application.py`)
- Deployment API → Application package: deploys package (evidence: `vespa/deployment.py`)
- Deployment API → Vespa service: deploys to (evidence: `vespa/deployment.py`)
- Developer → Vespa CLI wrapper: uses wrapper (evidence: `README.md`)
- Vespa CLI wrapper → CLI binaries: downloads binaries
- Developer → Retrieval evaluation: evaluates retrieval (evidence: `README.md`)
- Retrieval evaluation → Application API: queries app (evidence: `vespa/evaluation/_base.py`)
- Developer → MTEB benchmarking: runs benchmarks (evidence: `README.md`)
- MTEB benchmarking → Application API: uses app (evidence: `vespa/evaluation/_mteb.py`)
- MTEB benchmarking → Deployment API: deploys benchmark app (evidence: `vespa/evaluation/_mteb.py`)
- MTEB benchmarking → Model utilities: uses models (evidence: `vespa/evaluation/_mteb.py`)
