> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# DSPy

> Trace DSPy pipelines in Braintrust to debug modules, evaluate prompts, and monitor LLM calls

[DSPy](https://dspy.ai) is a framework for programming language model pipelines. Braintrust traces the full DSPy execution tree, so a single trace shows how each module decomposed into its underlying steps.

**Python**

## Setup

Install the Braintrust and DSPy packages, then set your API keys. Requires `dspy` v2.6.0 or later.

**1. Install packages**

```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv add braintrust dspy
```

```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust dspy
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>
OPENAI_API_KEY=<your-openai-api-key>
```

## Auto-instrumentation

To trace DSPy runs without modifying your application code, call `braintrust.auto_instrument()` before you configure DSPy. It patches `dspy.configure()` so Braintrust's DSPy callback is attached automatically.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

import braintrust

braintrust.auto_instrument()
braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="dspy-example",  # Replace with your project name
)

import dspy

lm = dspy.LM("openai/gpt-5-mini")
dspy.configure(lm=lm)

cot = dspy.ChainOfThought("question -> answer")
result = cot(question="What is the capital of France?")
print(result.answer)
```

To patch only DSPy instead of enabling all supported Python integrations, use `patch_dspy()`.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

from braintrust import init_logger
from braintrust.integrations.dspy import patch_dspy

init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="dspy-example",  # Replace with your project name
)
patch_dspy()

import dspy

lm = dspy.LM("openai/gpt-5-mini")
dspy.configure(lm=lm)

predict = dspy.Predict("question -> answer")
result = predict(question="What is 2 + 2?")
print(result.answer)
```

## Manual instrumentation

To trace DSPy runs manually, attach `BraintrustDSpyCallback()` yourself when you configure DSPy. For detailed LiteLLM token and cost spans, patch LiteLLM before importing DSPy.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

from braintrust import init_logger
from braintrust.integrations.dspy import BraintrustDSpyCallback
from braintrust.integrations.litellm import patch_litellm

patch_litellm()

import dspy

init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="dspy-example",  # Replace with your project name
)

# Disable DSPy's disk cache if you want every LiteLLM call to be traced.
dspy.configure_cache(enable_disk_cache=False, enable_memory_cache=True)

lm = dspy.LM("openai/gpt-5-mini")
dspy.configure(lm=lm, callbacks=[BraintrustDSpyCallback()])

cot = dspy.ChainOfThought("question -> answer")
result = cot(question="What is the capital of France?")
print(result.answer)
```

## What Braintrust traces

A DSPy execution appears as a parent module span with child spans for adapter work and model calls:

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
trace-dspy-auto
└── dspy.module.ChainOfThought
    ├── dspy.adapter.format
    ├── dspy.lm
    └── dspy.adapter.parse
```

Braintrust captures:

* Module spans (`dspy.module.Predict`, `dspy.module.ChainOfThought`, and other module classes), with module inputs, the module class, and outputs.
* Adapter formatting and parsing spans (`dspy.adapter.format` and `dspy.adapter.parse`), with inputs, the adapter class, and outputs.
* LLM call spans (`dspy.lm`), with inputs, the model and provider, request parameters (`temperature`, `max_tokens`, `top_p`, `top_k`, `stop`), outputs, token usage (prompt, completion, and total), and latency.
* Tool spans (named after the invoked tool), with tool inputs and outputs.
* Evaluation spans (`dspy.evaluate`), with evaluation inputs, the metric name, thread count, outputs, and score metrics (`accuracy`, `score`, `total`, `correct`).
* Additional LiteLLM completion spans (`Completion`), with token usage and latency metrics, when you patch LiteLLM.
* Base64 data URL images in span inputs and outputs, including `dspy.Image` values, captured as attachments.

## Resources

* [LiteLLM integration](https://docs.braintrust.dev/integrations/sdk-integrations/litellm.md)
* [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md)
* [Advanced tracing](https://docs.braintrust.dev/instrument/advanced-tracing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.