Skip to content

dspy.Adapter

dspy.Adapter(callbacks: list[BaseCallback] | None = None, use_native_function_calling: bool = False, native_response_types: list[type[Type]] | None = None, parallel_tool_calls: bool | 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 format() and parse() methods. Callbacks can be used for logging, monitoring, or custom processing. Defaults to None (empty list).

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 dspy.Tool or list[dspy.Tool] types. Defaults to False.

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, dspy.Citations can be populated directly by citation APIs (e.g., Anthropic’s citation feature). Defaults to [Citations].

None
parallel_tool_calls bool | None

Whether to request provider-side parallel tool-call generation when native function calling is active. If None, the adapter does not set the provider option. Defaults to None.

None
Source code in dspy/adapters/base.py
def __init__(
    self,
    callbacks: list[BaseCallback] | None = None,
    use_native_function_calling: bool = False,
    native_response_types: list[type[Type]] | None = None,
    parallel_tool_calls: bool | None = None,
):
    """
    Args:
        callbacks: List of callback functions to execute during `format()` and `parse()` methods. Callbacks can be
            used for logging, monitoring, or custom processing. Defaults to None (empty list).
        use_native_function_calling: 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 `dspy.Tool`
            or `list[dspy.Tool]` types. Defaults to False.
        native_response_types: List of output field types that should be handled by native LM features rather than
            adapter parsing. For example, `dspy.Citations` can be populated directly by citation APIs
            (e.g., Anthropic's citation feature). Defaults to `[Citations]`.
        parallel_tool_calls: Whether to request provider-side parallel tool-call generation when native function
            calling is active. If None, the adapter does not set the provider option. Defaults to None.
    """
    self.callbacks = callbacks or []
    self.use_native_function_calling = use_native_function_calling
    self.parallel_tool_calls = parallel_tool_calls
    self.native_response_types = native_response_types or _DEFAULT_NATIVE_RESPONSE_TYPES

Methods:

__call__(lm: BaseLM, 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 BaseLM

The Language Model instance to use for generation. Must be an instance of dspy.BaseLM.

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
@with_capability_planning
def __call__(
    self,
    lm: BaseLM,
    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.

    Args:
        lm: The Language Model instance to use for generation. Must be an instance of `dspy.BaseLM`.
        lm_kwargs: Additional keyword arguments to pass to the LM call (e.g., temperature, max_tokens). These are
            passed directly to the LM.
        signature: The DSPy signature associated with this LM call.
        demos: 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.
        inputs: The current input values for this call. Keys must match the signature's input field names.

    Returns:
        List of dictionaries representing parsed LM responses. Each dictionary contains keys matching the
        signature's output field names. For multiple generations (n > 1), returns multiple dictionaries.
    """
    processed_signature = self._call_preprocess(lm, lm_kwargs, signature, inputs)
    prompt = self.format(processed_signature, demos, inputs)
    request = _place_tool_result_media(build_request(lm, prompt, lm_kwargs), lm, lm_kwargs)
    if settings.send_stream and settings.stream_listeners:
        from dspy.streaming.messages import _StreamSignature, sync_send_to_stream

        sync_send_to_stream(settings.send_stream, _StreamSignature(id(settings.caller_predict), processed_signature))
    responses = [lm(candidate, **options) for candidate, options in _candidate_calls(lm, lm_kwargs, request)]
    return self._call_postprocess(processed_signature, signature, responses)

acall(lm: BaseLM, 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
@with_capability_planning
async def acall(
    self,
    lm: BaseLM,
    lm_kwargs: dict[str, Any],
    signature: type[Signature],
    demos: list[dict[str, Any]],
    inputs: dict[str, Any],
) -> list[dict[str, Any]]:
    processed_signature = self._call_preprocess(lm, lm_kwargs, signature, inputs)
    prompt = self.format(processed_signature, demos, inputs)
    request = _place_tool_result_media(build_request(lm, prompt, lm_kwargs), lm, lm_kwargs)
    if settings.send_stream and settings.stream_listeners:
        from dspy.streaming.messages import _StreamSignature

        await settings.send_stream.send(_StreamSignature(id(settings.caller_predict), processed_signature))
    responses = [await lm.acall(candidate, **options) for candidate, options in _candidate_calls(lm, lm_kwargs, request)]
    return self._call_postprocess(processed_signature, signature, responses)

format(signature: type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> Prompt

Render the prompt for the LM call.

This method converts the DSPy structured input along with few-shot examples and conversation history into a system instruction plus multiturn lm15 messages. For custom adapters, this method can be overridden to customize the rendering.

The recommended structure is:

Prompt(
    system=system_message,  # field descriptions, field structure and task description
    messages=(
        # Begin few-shot examples
        Message.user(few_shot_example_1_input),
        Message.assistant(few_shot_example_1_output),
        ...
        # End few-shot examples
        # Begin conversation history
        Message.user(conversation_history_1_input),
        Message.assistant(conversation_history_1_output),
        ...
        # End conversation history
        Message.user(current_input),
    ),
)

Parameters:

Name Type Description Default
signature type[Signature]

The DSPy signature for which to format the prompt.

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
Prompt

The rendered Prompt.

Source code in dspy/adapters/base.py
def format(
    self,
    signature: type[Signature],
    demos: list[dict[str, Any]],
    inputs: dict[str, Any],
) -> Prompt:
    """Render the prompt for the LM call.

    This method converts the DSPy structured input along with few-shot examples and conversation history into
    a system instruction plus multiturn lm15 messages. For custom adapters, this method can be overridden to
    customize the rendering.

    The recommended structure is:
    ```
    Prompt(
        system=system_message,  # field descriptions, field structure and task description
        messages=(
            # Begin few-shot examples
            Message.user(few_shot_example_1_input),
            Message.assistant(few_shot_example_1_output),
            ...
            # End few-shot examples
            # Begin conversation history
            Message.user(conversation_history_1_input),
            Message.assistant(conversation_history_1_output),
            ...
            # End conversation history
            Message.user(current_input),
        ),
    )
    ```

    Args:
        signature: The DSPy signature for which to format the prompt.
        demos: A list of few-shot examples.
        inputs: The input arguments to the DSPy module.

    Returns:
        The rendered `Prompt`.
    """
    inputs_copy = dict(inputs)
    fallback_names = {
        field.json_schema_extra["__dspy_reasoning_field"]: name
        for name, field in signature.output_fields.items()
        if "__dspy_reasoning_field" in field.json_schema_extra
    }
    if fallback_names:
        def remap(values):
            return {fallback_names.get(key, key): value for key, value in values.items()}

        demos = [remap(demo) for demo in demos]
        for name, field in signature.input_fields.items():
            if field.annotation is History and name in inputs_copy:
                inputs_copy[name] = inputs_copy[name]._remap_fields(fallback_names)

    # If the signature and inputs have conversation history, we need to format the conversation history and
    # remove the history field from the signature.
    history_field_name = self._get_history_field_name(signature)
    if history_field_name:
        # In order to format the conversation history, we need to remove the history field from the signature.
        signature_without_history = signature.delete(history_field_name)
        conversation_history = self.format_conversation_history(
            signature_without_history,
            history_field_name,
            inputs_copy,
        )

    messages = []
    system_message = self.format_system_message(signature)
    messages.extend(self.format_demos(signature, demos))
    content = self.format_user_message_content(
        signature_without_history if history_field_name else signature, inputs_copy, main_request=True
    )
    if history_field_name:
        messages.extend(conversation_history)
    if content:
        messages.append(user_message(content))

    return Prompt(system=system_message or None, messages=tuple(messages))

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
def format_assistant_message_content(
    self,
    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.

    Args:
        signature: The DSPy signature for which to format the assistant message content.
        outputs: The output fields to be formatted.
        missing_field_message: A message to be used when a field is missing.

    Returns:
        A string that contains the assistant message content.
    """
    raise NotImplementedError

format_conversation_history(signature: type[Signature], history_field_name: str, inputs: dict[str, Any]) -> list[Message]

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[Message]

A list of multiturn lm15 messages.

Source code in dspy/adapters/base.py
def format_conversation_history(
    self,
    signature: type[Signature],
    history_field_name: str,
    inputs: dict[str, Any],
) -> list[Message]:
    """Format the conversation history.

    This method formats the conversation history and the current input as multiturn messages.

    Args:
        signature: The DSPy signature for which to format the conversation history.
        history_field_name: The name of the history field in the signature.
        inputs: The input arguments to the DSPy module.

    Returns:
        A list of multiturn lm15 messages.
    """
    if history_field_name not in inputs:
        return []

    messages = inputs[history_field_name].format(self, signature)
    del inputs[history_field_name]
    return messages

format_demos(signature: type[Signature], demos: list[dict[str, Any]]) -> list[Message]

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[Message]

A list of multiturn lm15 messages.

Source code in dspy/adapters/base.py
def format_demos(self, signature: type[Signature], demos: list[dict[str, Any]]) -> list[Message]:
    """Format the few-shot examples.

    This method formats the few-shot examples as multiturn messages.

    Args:
        signature: The DSPy signature for which to format the few-shot examples.
        demos: A list of few-shot examples, each element is a dictionary with keys of the input and output fields of
            the signature.

    Returns:
        A list of multiturn lm15 messages.
    """
    complete_demos = []
    incomplete_demos = []

    for demo in demos:
        # Check if all fields are present and not None
        is_complete = all(k in demo and demo[k] is not None for k in signature.fields)

        # Check if demo has at least one input and one output field
        has_input = any(k in demo for k in signature.input_fields)
        has_output = any(k in demo for k in signature.output_fields)

        if is_complete:
            complete_demos.append(demo)
        elif has_input and has_output:
            # We only keep incomplete demos that have at least one input and one output field
            incomplete_demos.append(demo)

    messages = []

    incomplete_demo_prefix = "This is an example of the task, though some input or output fields are not supplied."
    for demo in incomplete_demos:
        messages.append(user_message(self.format_user_message_content(signature, demo, prefix=incomplete_demo_prefix)))
        messages.append(Message.assistant(self.format_assistant_message_content(
            signature, demo, missing_field_message="Not supplied for this particular example. "
        )))

    for demo in complete_demos:
        messages.append(user_message(self.format_user_message_content(signature, demo)))
        messages.append(Message.assistant(self.format_assistant_message_content(
            signature, demo, missing_field_message="Not supplied for this conversation history message. "
        )))

    return messages

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
def format_field_description(self, 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.

    Args:
        signature: The DSPy signature for which to format the field description.

    Returns:
        A string that contains the field description for the input fields and the output fields.
    """
    raise NotImplementedError

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
def format_field_structure(self, 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.

    Args:
        signature: The DSPy signature for which to format the field structure.
    """
    raise NotImplementedError

format_system_message(signature: type[Signature]) -> str

Format the system message for the LM call.

Parameters:

Name Type Description Default
signature type[Signature]

The DSPy signature for which to format the system message.

required
Source code in dspy/adapters/base.py
def format_system_message(self, signature: type[Signature]) -> str:
    """Format the system message for the LM call.


    Args:
        signature: The DSPy signature for which to format the system message.
    """
    return (
        f"{self.format_field_description(signature)}\n"
        f"{self.format_field_structure(signature)}\n"
        f"{self.format_task_description(signature)}"
    )

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
def format_task_description(self, 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`.

    Args:
        signature: The DSPy signature of the DSpy module.

    Returns:
        A string that describes the task.
    """
    raise NotImplementedError

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
def format_user_message_content(
    self,
    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.

    Args:
        signature: The DSPy signature for which to format the user message content.
        inputs: The input arguments to the DSPy module.
        prefix: A prefix to the user message content.
        suffix: A suffix to the user message content.

    Returns:
        A string that contains the user message content.
    """
    raise NotImplementedError

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
def parse(self, 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.

    Args:
        signature: The DSPy signature for which to parse the LM output.
        completion: The LM output to be parsed.

    Returns:
        A dictionary of the output fields.
    """
    raise NotImplementedError