DSPy: The framework for programming—not prompting—language models
Python
Add xml adapter (#8358)
Chen Qian716e82cf8457
diff --git a/dspy/__init__.py b/dspy/__init__.pyindex b61d9d2b6..9cc6c90c9 100644--- a/dspy/__init__.py+++ b/dspy/__init__.py@@ -8,7 +8,7 @@ import dspy.retrieversfrom dspy.evaluate import Evaluate # isort: skipfrom dspy.clients import * # isort: skip-from dspy.adapters import Adapter, ChatAdapter, JSONAdapter, TwoStepAdapter, Image, Audio, History, BaseType, Tool, ToolCalls # isort: skip+from dspy.adapters import Adapter, ChatAdapter, JSONAdapter, XMLAdapter, TwoStepAdapter, Image, Audio, History, BaseType, Tool, ToolCalls # isort: skipfrom dspy.utils.logging_utils import configure_dspy_loggers, disable_logging, enable_loggingfrom dspy.utils.asyncify import asyncifyfrom dspy.utils.saving import loaddiff --git a/dspy/adapters/__init__.py b/dspy/adapters/__init__.pyindex 9bb499f38..6d342df33 100644--- a/dspy/adapters/__init__.py+++ b/dspy/adapters/__init__.py@@ -3,6 +3,7 @@ from dspy.adapters.chat_adapter import ChatAdapterfrom dspy.adapters.json_adapter import JSONAdapterfrom dspy.adapters.two_step_adapter import TwoStepAdapterfrom dspy.adapters.types import Audio, BaseType, History, Image, Tool, ToolCalls+from dspy.adapters.xml_adapter import XMLAdapter__all__ = ["Adapter",@@ -12,6 +13,7 @@ __all__ = ["Image","Audio","JSONAdapter",+ "XMLAdapter","TwoStepAdapter","Tool","ToolCalls",diff --git a/dspy/adapters/utils.py b/dspy/adapters/utils.pyindex 2c27fec94..138ba7729 100644--- a/dspy/adapters/utils.py+++ b/dspy/adapters/utils.py@@ -90,7 +90,8 @@ def translate_field_type(field_name, field_info):elif field_type in (int, float):desc = f"must be a single {field_type.__name__} value"elif inspect.isclass(field_type) and issubclass(field_type, enum.Enum):- desc = f"must be one of: {'; '.join(field_type.__members__)}"+ enum_vals = '; '.join(str(member.value) for member in field_type)+ desc = f"must be one of: {enum_vals}"elif hasattr(field_type, "__origin__") and field_type.__origin__ is Literal:desc = (# Strongly encourage the LM to avoid choosing values that don't appear in thediff --git a/dspy/adapters/xml_adapter.py b/dspy/adapters/xml_adapter.pynew file mode 100644index 000000000..8ed0da27f--- /dev/null+++ b/dspy/adapters/xml_adapter.py@@ -0,0 +1,62 @@+import re+from typing import Any, Dict, Optional, Type++from dspy.adapters.chat_adapter import ChatAdapter, FieldInfoWithName+from dspy.adapters.utils import format_field_value+from dspy.signatures.signature import Signature+from dspy.utils.callback import BaseCallback+++class XMLAdapter(ChatAdapter):+ def __init__(self, callbacks: Optional[list[BaseCallback]] = None):+ super().__init__(callbacks)+ self.field_pattern = re.compile(r"<(?P<name>\w+)>((?P<content>.*?))</\1>", re.DOTALL)++ def format_field_with_value(self, fields_with_values: Dict[FieldInfoWithName, Any]) -> str:+ output = []+ for field, field_value in fields_with_values.items():+ formatted = format_field_value(field_info=field.info, value=field_value)+ output.append(f"<{field.name}>\n{formatted}\n</{field.name}>")+ return "\n\n".join(output).strip()++ def user_message_output_requirements(self, signature: Type[Signature]) -> str:+ message = "Respond with the corresponding output fields wrapped in XML tags"+ message += ", then ".join(f"`<{f}>`" for f in signature.output_fields)+ message += ", and then end with the `<completed>` tag."+ return message++ def parse(self, signature: Type[Signature], completion: str) -> dict[str, Any]:+ fields = {}+ for match in self.field_pattern.finditer(completion):+ name = match.group("name")+ content = match.group("content").strip()+ if name in signature.output_fields and name not in fields:+ fields[name] = content+ # Cast values using base class parse_value helper+ for k, v in fields.items():+ fields[k] = self._parse_field_value(signature.output_fields[k], v, completion, signature)+ if fields.keys() != signature.output_fields.keys():+ from dspy.utils.exceptions import AdapterParseError++ raise AdapterParseError(+ adapter_name="XMLAdapter",+ signature=signature,+ lm_response=completion,+ parsed_result=fields,+ )+ return fields++ def _parse_field_value(self, field_info, raw, completion, signature):+ from dspy.adapters.utils import parse_value++ try:+ return parse_value(raw, field_info.annotation)+ except Exception as e:+ from dspy.utils.exceptions import AdapterParseError++ raise AdapterParseError(+ adapter_name="XMLAdapter",+ signature=signature,+ lm_response=completion,+ message=f"Failed to parse field {field_info} with value {raw}: {e}",+ )diff --git a/tests/adapters/test_xml_adapter.py b/tests/adapters/test_xml_adapter.pynew file mode 100644index 000000000..f47884d3f--- /dev/null+++ b/tests/adapters/test_xml_adapter.py@@ -0,0 +1,218 @@+import pydantic+import pytest++import dspy+from dspy.adapters.chat_adapter import FieldInfoWithName+from dspy.adapters.xml_adapter import XMLAdapter+++def test_xml_adapter_format_and_parse_basic():+ class TestSignature(dspy.Signature):+ question: str = dspy.InputField()+ answer: str = dspy.OutputField()++ adapter = XMLAdapter()+ # Format output fields as XML+ fields_with_values = {FieldInfoWithName(name="answer", info=TestSignature.output_fields["answer"]): "Paris"}+ xml = adapter.format_field_with_value(fields_with_values)+ assert xml.strip() == "<answer>\nParis\n</answer>"++ # Parse XML output+ completion = "<answer>Paris</answer>"+ parsed = adapter.parse(TestSignature, completion)+ assert parsed == {"answer": "Paris"}+++def test_xml_adapter_parse_multiple_fields():+ class TestSignature(dspy.Signature):+ question: str = dspy.InputField()+ answer: str = dspy.OutputField()+ explanation: str = dspy.OutputField()++ adapter = XMLAdapter()+ completion = """+<answer>Paris</answer>+<explanation>The capital of France is Paris.</explanation>+"""+ parsed = adapter.parse(TestSignature, completion)+ assert parsed == {"answer": "Paris", "explanation": "The capital of France is Paris."}+++def test_xml_adapter_parse_raises_on_missing_field():+ class TestSignature(dspy.Signature):+ question: str = dspy.InputField()+ answer: str = dspy.OutputField()+ explanation: str = dspy.OutputField()++ adapter = XMLAdapter()+ completion = "<answer>Paris</answer>"+ with pytest.raises(dspy.utils.exceptions.AdapterParseError) as e:+ adapter.parse(TestSignature, completion)+ assert e.value.adapter_name == "XMLAdapter"+ assert e.value.signature == TestSignature+ assert e.value.lm_response == "<answer>Paris</answer>"+ assert "explanation" in str(e.value)+++def test_xml_adapter_parse_casts_types():+ class TestSignature(dspy.Signature):+ number: int = dspy.OutputField()+ flag: bool = dspy.OutputField()++ adapter = XMLAdapter()+ completion = """+<number>42</number>+<flag>true</flag>+"""+ parsed = adapter.parse(TestSignature, completion)+ assert parsed == {"number": 42, "flag": True}+++def test_xml_adapter_parse_raises_on_type_error():+ class TestSignature(dspy.Signature):+ number: int = dspy.OutputField()++ adapter = XMLAdapter()+ completion = "<number>not_a_number</number>"+ with pytest.raises(dspy.utils.exceptions.AdapterParseError) as e:+ adapter.parse(TestSignature, completion)+ assert "Failed to parse field" in str(e.value)+++def test_xml_adapter_format_and_parse_nested_model():+ class InnerModel(pydantic.BaseModel):+ value: int+ label: str++ class TestSignature(dspy.Signature):+ question: str = dspy.InputField()+ result: InnerModel = dspy.OutputField()++ adapter = XMLAdapter()+ # Format output fields as XML+ fields_with_values = {+ FieldInfoWithName(name="result", info=TestSignature.output_fields["result"]): InnerModel(value=5, label="foo")+ }+ xml = adapter.format_field_with_value(fields_with_values)+ # The output will be a JSON string inside the XML tag+ assert xml.strip().startswith("<result>")+ assert '"value": 5' in xml+ assert '"label": "foo"' in xml+ assert xml.strip().endswith("</result>")++ # Parse XML output (should parse as string, not as model)+ completion = '<result>{"value": 5, "label": "foo"}</result>'+ parsed = adapter.parse(TestSignature, completion)+ # The parse_value helper will try to cast to InnerModel+ assert isinstance(parsed["result"], InnerModel)+ assert parsed["result"].value == 5+ assert parsed["result"].label == "foo"+++def test_xml_adapter_format_and_parse_list_of_models():+ class Item(pydantic.BaseModel):+ name: str+ score: float++ class TestSignature(dspy.Signature):+ items: list[Item] = dspy.OutputField()++ adapter = XMLAdapter()+ items = [Item(name="a", score=1.1), Item(name="b", score=2.2)]+ fields_with_values = {FieldInfoWithName(name="items", info=TestSignature.output_fields["items"]): items}+ xml = adapter.format_field_with_value(fields_with_values)+ assert xml.strip().startswith("<items>")+ assert '"name": "a"' in xml+ assert '"score": 2.2' in xml+ assert xml.strip().endswith("</items>")++ # Parse XML output+ import json++ completion = f"<items>{json.dumps([i.model_dump() for i in items])}</items>"+ parsed = adapter.parse(TestSignature, completion)+ assert isinstance(parsed["items"], list)+ assert all(isinstance(i, Item) for i in parsed["items"])+ assert parsed["items"][0].name == "a"+ assert parsed["items"][1].score == 2.2+++def test_xml_adapter_with_tool_like_output():+ # XMLAdapter does not natively support tool calls, but we can test structured output+ class ToolCall(pydantic.BaseModel):+ name: str+ args: dict+ result: str++ class TestSignature(dspy.Signature):+ question: str = dspy.InputField()+ tool_calls: list[ToolCall] = dspy.OutputField()+ answer: str = dspy.OutputField()++ adapter = XMLAdapter()+ tool_calls = [+ ToolCall(name="get_weather", args={"city": "Tokyo"}, result="Sunny"),+ ToolCall(name="get_population", args={"country": "Japan", "year": 2023}, result="125M"),+ ]+ fields_with_values = {+ FieldInfoWithName(name="tool_calls", info=TestSignature.output_fields["tool_calls"]): tool_calls,+ FieldInfoWithName(+ name="answer", info=TestSignature.output_fields["answer"]+ ): "The weather is Sunny. Population is 125M.",+ }+ xml = adapter.format_field_with_value(fields_with_values)+ assert xml.strip().startswith("<tool_calls>")+ assert '"name": "get_weather"' in xml+ assert '"result": "125M"' in xml+ assert xml.strip().endswith("</answer>")++ import json++ completion = (+ f"<tool_calls>{json.dumps([tc.model_dump() for tc in tool_calls])}</tool_calls>"+ f"\n<answer>The weather is Sunny. Population is 125M.</answer>"+ )+ parsed = adapter.parse(TestSignature, completion)+ assert isinstance(parsed["tool_calls"], list)+ assert parsed["tool_calls"][0].name == "get_weather"+ assert parsed["tool_calls"][1].result == "125M"+ assert parsed["answer"] == "The weather is Sunny. Population is 125M."+++def test_xml_adapter_formats_nested_images():+ class ImageWrapper(pydantic.BaseModel):+ images: list[dspy.Image]+ tag: list[str]++ class MySignature(dspy.Signature):+ image: ImageWrapper = dspy.InputField()+ text: str = dspy.OutputField()++ image1 = dspy.Image(url="https://example.com/image1.jpg")+ image2 = dspy.Image(url="https://example.com/image2.jpg")+ image3 = dspy.Image(url="https://example.com/image3.jpg")++ image_wrapper = ImageWrapper(images=[image1, image2, image3], tag=["test", "example"])+ demos = [+ dspy.Example(+ image=image_wrapper,+ text="This is a test image",+ ),+ ]++ image_wrapper_2 = ImageWrapper(images=[dspy.Image(url="https://example.com/image4.jpg")], tag=["test", "example"])+ adapter = dspy.XMLAdapter()+ messages = adapter.format(MySignature, demos, {"image": image_wrapper_2})++ assert len(messages) == 4++ # Image information in the few-shot example's user message+ expected_image1_content = {"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}}+ expected_image2_content = {"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}}+ expected_image3_content = {"type": "image_url", "image_url": {"url": "https://example.com/image3.jpg"}}+ assert expected_image1_content in messages[1]["content"]+ assert expected_image2_content in messages[1]["content"]+ assert expected_image3_content in messages[1]["content"]++ # The query image is formatted in the last user message+ assert {"type": "image_url", "image_url": {"url": "https://example.com/image4.jpg"}} in messages[-1]["content"]