dspy.Adapter¶
dspy.Adapter(callbacks: list[BaseCallback] | None = None, use_native_function_calling: bool = False, native_response_types: list[type[Type]] | None = None)
¶
Base Adapter class.
The Adapter serves as the interface layer between DSPy module/signature and Language Models (LMs). It handles the complete transformation pipeline from DSPy inputs to LM calls and back to structured outputs.
Key responsibilities
- Transform user inputs and signatures into properly formatted LM prompts, which also instructs the LM to format the response in a specific format.
- Parse LM outputs into dictionaries matching the signature's output fields.
- Enable/disable native LM features (function calling, citations, etc.) based on configuration.
- Handle conversation history, few-shot examples, and custom type processing.
The adapter pattern allows DSPy to work with different LM interfaces while maintaining a consistent programming model for users.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
callbacks
|
list[BaseCallback] | None
|
List of callback functions to execute during |
None
|
use_native_function_calling
|
bool
|
Whether to enable native function calling capabilities when the LM supports it.
If True, the adapter will automatically configure function calling when input fields contain |
False
|
native_response_types
|
list[type[Type]] | None
|
List of output field types that should be handled by native LM features rather than
adapter parsing. For example, |
None
|
Source code in dspy/adapters/base.py
Functions¶
__call__(lm: LM, lm_kwargs: dict[str, Any], signature: type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]
¶
Execute the adapter pipeline: format inputs, call LM, and parse outputs.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
lm
|
LM
|
The Language Model instance to use for generation. Must be an instance of |
required |
lm_kwargs
|
dict[str, Any]
|
Additional keyword arguments to pass to the LM call (e.g., temperature, max_tokens). These are passed directly to the LM. |
required |
signature
|
type[Signature]
|
The DSPy signature associated with this LM call. |
required |
demos
|
list[dict[str, Any]]
|
List of few-shot examples to include in the prompt. Each dictionary should contain keys matching the signature's input and output field names. Examples are formatted as user/assistant message pairs. |
required |
inputs
|
dict[str, Any]
|
The current input values for this call. Keys must match the signature's input field names. |
required |
Returns:
Type | Description |
---|---|
list[dict[str, Any]]
|
List of dictionaries representing parsed LM responses. Each dictionary contains keys matching the |
list[dict[str, Any]]
|
signature's output field names. For multiple generations (n > 1), returns multiple dictionaries. |
Source code in dspy/adapters/base.py
acall(lm: LM, lm_kwargs: dict[str, Any], signature: type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]
async
¶
Source code in dspy/adapters/base.py
format(signature: type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]
¶
Format the input messages for the LM call.
This method converts the DSPy structured input along with few-shot examples and conversation history into multiturn messages as expected by the LM. For custom adapters, this method can be overridden to customize the formatting of the input messages.
In general we recommend the messages to have the following structure:
[
{"role": "system", "content": system_message},
# Begin few-shot examples
{"role": "user", "content": few_shot_example_1_input},
{"role": "assistant", "content": few_shot_example_1_output},
{"role": "user", "content": few_shot_example_2_input},
{"role": "assistant", "content": few_shot_example_2_output},
...
# End few-shot examples
# Begin conversation history
{"role": "user", "content": conversation_history_1_input},
{"role": "assistant", "content": conversation_history_1_output},
{"role": "user", "content": conversation_history_2_input},
{"role": "assistant", "content": conversation_history_2_output},
...
# End conversation history
{"role": "user", "content": current_input},
]
And system message should contain the field description, field structure, and task description.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to format the input messages. |
required |
demos
|
list[dict[str, Any]]
|
A list of few-shot examples. |
required |
inputs
|
dict[str, Any]
|
The input arguments to the DSPy module. |
required |
Returns:
Type | Description |
---|---|
list[dict[str, Any]]
|
A list of multiturn messages as expected by the LM. |
Source code in dspy/adapters/base.py
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 |
|
format_assistant_message_content(signature: type[Signature], outputs: dict[str, Any], missing_field_message: str | None = None) -> str
¶
Format the assistant message content.
This method formats the assistant message content, which can be used in formatting few-shot examples, conversation history.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to format the assistant message content. |
required |
outputs
|
dict[str, Any]
|
The output fields to be formatted. |
required |
missing_field_message
|
str | None
|
A message to be used when a field is missing. |
None
|
Returns:
Type | Description |
---|---|
str
|
A string that contains the assistant message content. |
Source code in dspy/adapters/base.py
format_conversation_history(signature: type[Signature], history_field_name: str, inputs: dict[str, Any]) -> list[dict[str, Any]]
¶
Format the conversation history.
This method formats the conversation history and the current input as multiturn messages.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to format the conversation history. |
required |
history_field_name
|
str
|
The name of the history field in the signature. |
required |
inputs
|
dict[str, Any]
|
The input arguments to the DSPy module. |
required |
Returns:
Type | Description |
---|---|
list[dict[str, Any]]
|
A list of multiturn messages. |
Source code in dspy/adapters/base.py
format_demos(signature: type[Signature], demos: list[dict[str, Any]]) -> list[dict[str, Any]]
¶
Format the few-shot examples.
This method formats the few-shot examples as multiturn messages.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to format the few-shot examples. |
required |
demos
|
list[dict[str, Any]]
|
A list of few-shot examples, each element is a dictionary with keys of the input and output fields of the signature. |
required |
Returns:
Type | Description |
---|---|
list[dict[str, Any]]
|
A list of multiturn messages. |
Source code in dspy/adapters/base.py
format_field_description(signature: type[Signature]) -> str
¶
Format the field description for the system message.
This method formats the field description for the system message. It should return a string that contains the field description for the input fields and the output fields.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to format the field description. |
required |
Returns:
Type | Description |
---|---|
str
|
A string that contains the field description for the input fields and the output fields. |
Source code in dspy/adapters/base.py
format_field_structure(signature: type[Signature]) -> str
¶
Format the field structure for the system message.
This method formats the field structure for the system message. It should return a string that dictates the format the input fields should be provided to the LM, and the format the output fields will be in the response. Refer to the ChatAdapter and JsonAdapter for an example.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to format the field structure. |
required |
Source code in dspy/adapters/base.py
format_task_description(signature: type[Signature]) -> str
¶
Format the task description for the system message.
This method formats the task description for the system message. In most cases this is just a thin wrapper
over signature.instructions
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature of the DSpy module. |
required |
Returns:
Type | Description |
---|---|
str
|
A string that describes the task. |
Source code in dspy/adapters/base.py
format_user_message_content(signature: type[Signature], inputs: dict[str, Any], prefix: str = '', suffix: str = '', main_request: bool = False) -> str
¶
Format the user message content.
This method formats the user message content, which can be used in formatting few-shot examples, conversation history, and the current input.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to format the user message content. |
required |
inputs
|
dict[str, Any]
|
The input arguments to the DSPy module. |
required |
prefix
|
str
|
A prefix to the user message content. |
''
|
suffix
|
str
|
A suffix to the user message content. |
''
|
Returns:
Type | Description |
---|---|
str
|
A string that contains the user message content. |
Source code in dspy/adapters/base.py
parse(signature: type[Signature], completion: str) -> dict[str, Any]
¶
Parse the LM output into a dictionary of the output fields.
This method parses the LM output into a dictionary of the output fields.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
signature
|
type[Signature]
|
The DSPy signature for which to parse the LM output. |
required |
completion
|
str
|
The LM output to be parsed. |
required |
Returns:
Type | Description |
---|---|
dict[str, Any]
|
A dictionary of the output fields. |
Source code in dspy/adapters/base.py
:::