Skip to content

armgit / dspy

Public Imported from GitHub
0

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__.py
index b61d9d2b6..9cc6c90c9 100644
--- a/dspy/__init__.py
+++ b/dspy/__init__.py
@@ -8,7 +8,7 @@ import dspy.retrievers
from dspy.evaluate import Evaluate # isort: skip
from 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: skip
from dspy.utils.logging_utils import configure_dspy_loggers, disable_logging, enable_logging
from dspy.utils.asyncify import asyncify
from dspy.utils.saving import load
diff --git a/dspy/adapters/__init__.py b/dspy/adapters/__init__.py
index 9bb499f38..6d342df33 100644
--- a/dspy/adapters/__init__.py
+++ b/dspy/adapters/__init__.py
@@ -3,6 +3,7 @@ from dspy.adapters.chat_adapter import ChatAdapter
from dspy.adapters.json_adapter import JSONAdapter
from dspy.adapters.two_step_adapter import TwoStepAdapter
from 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.py
index 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 the
diff --git a/dspy/adapters/xml_adapter.py b/dspy/adapters/xml_adapter.py
new file mode 100644
index 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.py
new file mode 100644
index 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"]