DSPy | Respan Docs

DSPy is a framework from Stanford NLP for programming — not prompting — language models. It provides composable modules and automatic prompt optimization, replacing hand-crafted prompts with learnable programs. Respan gives you full observability over every module forward pass, chain-of-thought step, optimizer iteration, and LLM call — and gateway routing through the OpenAI-compatible Respan endpoint.

Set up Respan

Create an account at platform.respan.ai and grab an API key. For gateway, also add credits or a provider key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Python examples

Tracing

Gateway

Setup

Install packages

$ pip install respan-ai openinference-instrumentation-dspy dspy

Set environment variables

$ export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

OPENAI_API_KEY is used for LLM requests. RESPAN_API_KEY is used to export traces to Respan.

Initialize and run

1 import dspy
2 from respan import Respan
3 from openinference.instrumentation.dspy import DSPyInstrumentor
4 
5 respan = Respan(instrumentations=[DSPyInstrumentor()])
6 
7 lm = dspy.LM("openai/gpt-4.1-nano")
8 dspy.configure(lm=lm)
9 
10 class QA(dspy.Signature):
11     """Answer the question with a short, factual response."""
12     question: str = dspy.InputField()
13     answer: str = dspy.OutputField()
14 
15 predict = dspy.ChainOfThought(QA)
16 result = predict(question="What is the capital of France?")
17 print(result.answer)
18 respan.flush()

View your trace

Open the Traces page to see your DSPy program with module forward passes, chain-of-thought steps, and LLM calls.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate (e.g. `DSPyInstrumentor()`).
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag (e.g. `"production"`).

Attributes

In Respan()

Set defaults at initialization — these apply to all spans.

1 from respan import Respan
2 from openinference.instrumentation.dspy import DSPyInstrumentor
3 
4 respan = Respan(
5     instrumentations=[DSPyInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "dspy-api", "version": "1.0.0"},
8 )

With propagate_attributes

Override per-request using a context scope.

1 import dspy
2 from respan import Respan, propagate_attributes
3 from openinference.instrumentation.dspy import DSPyInstrumentor
4 
5 respan = Respan(instrumentations=[DSPyInstrumentor()])
6 dspy.configure(lm=dspy.LM("openai/gpt-4.1-nano"))
7 
8 def handle_request(user_id: str, question: str):
9     with propagate_attributes(
10         customer_identifier=user_id,
11         thread_identifier="conv_abc_123",
12         metadata={"plan": "pro"},
13     ):
14         result = dspy.ChainOfThought(QA)(question=question)
15         print(result.answer)

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.

Decorators (optional)

Decorators are not required. All DSPy module forward passes and LLM calls are auto-traced by the instrumentor. Use @workflow and @task to add structure when you want to group related runs into a named workflow with nested tasks.

1 import dspy
2 from respan import Respan, workflow, task
3 from openinference.instrumentation.dspy import DSPyInstrumentor
4 
5 respan = Respan(instrumentations=[DSPyInstrumentor()])
6 dspy.configure(lm=dspy.LM("openai/gpt-4.1-nano"))
7 
8 @task(name="answer")
9 def answer(question: str) -> str:
10     return dspy.ChainOfThought(QA)(question=question).answer
11 
12 @workflow(name="qa_pipeline")
13 def qa_pipeline(question: str):
14     print(answer(question))
15 
16 qa_pipeline("What is the capital of France?")
17 respan.flush()