# stanfordnlp/dspy architecture

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

- Interactive diagram: https://gitdiagram.com/stanfordnlp/dspy
- Repository: https://github.com/stanfordnlp/dspy
- Video tour (about a minute): https://gitdiagram.com/stanfordnlp/dspy/video

## Overview

DSPy is a Python framework for composing language-model programs and optimizing their instructions, demonstrations, or weights. A typical workflow defines typed signatures, runs predictors through adapters and an LM client, optionally retrieves evidence, evaluates outputs, and uses teleprompt optimizers to improve a program. The graph also preserves streaming, interpreter-backed reasoning, datasets, and the bundled lm15 provider/authentication runtime. Relationships are limited to README statements and references visible in the supplied source index or excerpts; unsampled subsystems are shown without speculative call edges.

Main entry points: [`dspy/_vendor/lm15/router.py`](https://github.com/stanfordnlp/dspy/blob/main/dspy/_vendor/lm15/router.py) (Provider router), [`dspy/teleprompt`](https://github.com/stanfordnlp/dspy/tree/main/dspy/teleprompt) (Teleprompt optimizers), [`dspy/predict`](https://github.com/stanfordnlp/dspy/tree/main/dspy/predict) (Predictors), [`dspy/adapters/base.py`](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/base.py) (Adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_programming["Program Construction"]
  node_signature["Signatures<br/>[signature.py]"]
  node_predict["Predictors"]
  node_prediction["Predictions<br/>[prediction.py]"]
end

subgraph group_runtime["Model Runtime"]
  node_adapters["Adapters<br/>[base.py]"]
  node_requests["LM requests<br/>[requests.py]"]
  node_lmclient["LM client<br/>[lm.py]"]
  node_engines["LM engines"]
  node_lm15api["lm15 API<br/>[lm15.py]"]
  node_router["Provider router<br/>[router.py]"]
  node_registry["Provider registry<br/>[registry.py]"]
  node_provider["Provider adapters"]
  node_auth["Managed login<br/>[manager.py]"]
  node_streaming["Streaming"]
end

subgraph group_learning["Optimization and Evaluation"]
  node_evaluate["Evaluation<br/>[evaluate.py]"]
  node_optimizers["Teleprompt optimizers"]
  node_proposer["Grounded proposer"]
end

subgraph group_support["Data and Extensions"]
  node_retrieval["Retrieval<br/>[retrieve.py]"]
  node_datasets[("Datasets<br/>[dataset.py]")]
  node_interpreter["Code interpreter"]
end

node_user(("DSPy user"))

node_user -->|"defines program"| node_signature
node_signature -->|"formats fields"| node_adapters
node_adapters -->|"builds request"| node_requests
node_requests -->|"uses interface"| node_lm15api
node_lm15api -->|"exposes routing"| node_router
node_router -->|"resolves providers"| node_registry
node_registry -->|"registers adapters"| node_provider
node_engines -->|"routes native calls"| node_router
node_engines -->|"uses interface"| node_lm15api
node_auth -->|"consults provider config"| node_router
node_predict -.->|"produces outputs"| node_prediction
node_retrieval -->|"returns results"| node_prediction
node_evaluate -->|"evaluates outputs"| node_prediction
node_optimizers -->|"scores programs"| node_evaluate
node_optimizers -.->|"optimizes programs"| node_predict
node_proposer -->|"summarizes data"| node_datasets
node_proposer -->|"uses optimizer utilities"| node_optimizers
node_streaming -->|"assembles streams"| node_adapters
node_interpreter -.->|"supports reasoning"| node_predict

click node_signature "https://github.com/stanfordnlp/dspy/blob/main/dspy/signatures/signature.py"
click node_predict "https://github.com/stanfordnlp/dspy/tree/main/dspy/predict"
click node_prediction "https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/prediction.py"
click node_adapters "https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/base.py"
click node_requests "https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/requests.py"
click node_lmclient "https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/lm.py"
click node_engines "https://github.com/stanfordnlp/dspy/tree/main/dspy/clients/engines"
click node_lm15api "https://github.com/stanfordnlp/dspy/blob/main/dspy/lm15.py"
click node_router "https://github.com/stanfordnlp/dspy/blob/main/dspy/_vendor/lm15/router.py"
click node_registry "https://github.com/stanfordnlp/dspy/blob/main/dspy/_vendor/lm15/registry.py"
click node_provider "https://github.com/stanfordnlp/dspy/tree/main/dspy/_vendor/lm15/providers"
click node_auth "https://github.com/stanfordnlp/dspy/blob/main/dspy/_vendor/lm15/login/manager.py"
click node_streaming "https://github.com/stanfordnlp/dspy/blob/main/dspy/streaming/streaming_listener.py"
click node_retrieval "https://github.com/stanfordnlp/dspy/blob/main/dspy/retrievers/retrieve.py"
click node_datasets "https://github.com/stanfordnlp/dspy/blob/main/dspy/datasets/dataset.py"
click node_interpreter "https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/code_interpreter.py"
click node_evaluate "https://github.com/stanfordnlp/dspy/blob/main/dspy/evaluate/evaluate.py"
click node_optimizers "https://github.com/stanfordnlp/dspy/tree/main/dspy/teleprompt"
click node_proposer "https://github.com/stanfordnlp/dspy/blob/main/dspy/propose/grounded_proposer.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_signature,node_predict,node_prediction,node_user toneBlue
class node_adapters,node_requests,node_lmclient,node_engines,node_lm15api,node_router,node_registry,node_provider,node_auth,node_streaming toneAmber
class node_evaluate,node_optimizers,node_proposer toneMint
class node_retrieval,node_datasets,node_interpreter toneRose
```

## Components

### Program Construction

- [Signatures](https://github.com/stanfordnlp/dspy/blob/main/dspy/signatures/signature.py): `dspy/signatures/signature.py`
- [Predictors](https://github.com/stanfordnlp/dspy/tree/main/dspy/predict): `dspy/predict`
- [Predictions](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/prediction.py): `dspy/primitives/prediction.py`

### Model Runtime

- [Adapters](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/base.py): `dspy/adapters/base.py`
- [LM requests](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/requests.py): `dspy/clients/requests.py`
- [LM client](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/lm.py): `dspy/clients/lm.py`
- [LM engines](https://github.com/stanfordnlp/dspy/tree/main/dspy/clients/engines): `dspy/clients/engines`
- [lm15 API](https://github.com/stanfordnlp/dspy/blob/main/dspy/lm15.py): `dspy/lm15.py`
- [Provider router](https://github.com/stanfordnlp/dspy/blob/main/dspy/_vendor/lm15/router.py): `dspy/_vendor/lm15/router.py`
- [Provider registry](https://github.com/stanfordnlp/dspy/blob/main/dspy/_vendor/lm15/registry.py): `dspy/_vendor/lm15/registry.py`
- [Provider adapters](https://github.com/stanfordnlp/dspy/tree/main/dspy/_vendor/lm15/providers): `dspy/_vendor/lm15/providers`
- [Managed login](https://github.com/stanfordnlp/dspy/blob/main/dspy/_vendor/lm15/login/manager.py): `dspy/_vendor/lm15/login/manager.py`
- [Streaming](https://github.com/stanfordnlp/dspy/blob/main/dspy/streaming/streaming_listener.py): `dspy/streaming/streaming_listener.py`

### Optimization and Evaluation

- [Evaluation](https://github.com/stanfordnlp/dspy/blob/main/dspy/evaluate/evaluate.py): `dspy/evaluate/evaluate.py`
- [Teleprompt optimizers](https://github.com/stanfordnlp/dspy/tree/main/dspy/teleprompt): `dspy/teleprompt`
- [Grounded proposer](https://github.com/stanfordnlp/dspy/blob/main/dspy/propose/grounded_proposer.py): `dspy/propose/grounded_proposer.py`

### Data and Extensions

- [Retrieval](https://github.com/stanfordnlp/dspy/blob/main/dspy/retrievers/retrieve.py): `dspy/retrievers/retrieve.py`
- [Datasets](https://github.com/stanfordnlp/dspy/blob/main/dspy/datasets/dataset.py): `dspy/datasets/dataset.py`
- [Code interpreter](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/code_interpreter.py): `dspy/primitives/code_interpreter.py`

### Other components

- **DSPy user**

## Connections

- DSPy user → Signatures: defines program
- Signatures → Adapters: formats fields (evidence: `dspy/adapters/base.py`)
- Adapters → LM requests: builds request (evidence: `dspy/adapters/base.py`)
- LM requests → lm15 API: uses interface (evidence: `dspy/clients/requests.py`)
- lm15 API → Provider router: exposes routing (evidence: `dspy/lm15.py`)
- Provider router → Provider registry: resolves providers (evidence: `dspy/_vendor/lm15/router.py`)
- Provider registry → Provider adapters: registers adapters (evidence: `dspy/_vendor/lm15/registry.py`)
- LM engines → Provider router: routes native calls (evidence: `dspy/clients/engines/lm15_engine.py`)
- LM engines → lm15 API: uses interface (evidence: `dspy/clients/engines/base.py`)
- Managed login → Provider router: consults provider config (evidence: `dspy/_vendor/lm15/login/manager.py`)
- Predictors → Predictions: produces outputs (evidence: `dspy/predict/rlm.py`)
- Retrieval → Predictions: returns results (evidence: `dspy/retrievers/retrieve.py`)
- Evaluation → Predictions: evaluates outputs (evidence: `dspy/evaluate/evaluate.py`)
- Teleprompt optimizers → Evaluation: scores programs (evidence: `dspy/teleprompt/random_search.py`)
- Teleprompt optimizers → Predictors: optimizes programs
- Grounded proposer → Datasets: summarizes data (evidence: `dspy/propose/grounded_proposer.py`)
- Grounded proposer → Teleprompt optimizers: uses optimizer utilities (evidence: `dspy/propose/grounded_proposer.py`)
- Streaming → Adapters: assembles streams (evidence: `dspy/streaming/streaming_listener.py`)
- Code interpreter → Predictors: supports reasoning (evidence: `dspy/predict/rlm.py`)
