Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

fix(dspy): parse XMLAdapter outputs as typed tags with literal leaves (#10402)

Isaac Millera42c98b0cb27
diff --git a/docs/docs/diving-deeper/adapters.md b/docs/docs/diving-deeper/adapters.md
index f7a61a8b5..c1b31854e 100644
--- a/docs/docs/diving-deeper/adapters.md
+++ b/docs/docs/diving-deeper/adapters.md
@@ -18,11 +18,11 @@ Text-only, model-agnostic, uses `[[ ## field ## ]]` markers. It needs no special
### 3. Every adapter follows a fixed lifecycle
-preprocess → format → LM call → postprocess → parse. You can debug any adapter by walking these five steps. Preprocess adapts the signature for native LM features (function calling, reasoning). Format builds the messages. The LM call returns raw outputs. Postprocess pulls out tool calls and native-typed responses (Reasoning, Citations). Parse runs `parse_value` on each declared output field.
+preprocess → format → LM call → postprocess → parse. You can debug any adapter by walking these five steps. Preprocess adapts the signature for native LM features (function calling, reasoning). Format builds the messages. The LM call returns raw outputs. Postprocess pulls out tool calls and native-typed responses (Reasoning, Citations). Parse converts declared output fields to typed values.
### 4. Type coercion is centralized
-`dspy/adapters/utils.py::parse_value` is the single function every adapter delegates to. Adapters differ in how they *find* a field’s value in the LM’s output (regex marker, JSON key, XML tag), but once they have the raw string they all call the same `parse_value(value, annotation)`. That keeps coercion rules consistent across adapter swaps and gives you one place to look when a typed field misbehaves.
+Adapters use `dspy/adapters/utils.py::parse_value` for text. XML containers use Pydantic validation by field name with `strict=False`, since their scalar values arrive as text.
### 5. Custom types own their own serialization
@@ -65,7 +65,9 @@ The default. Builds a chat-style prompt with field markers, parses the response
Outputs structured JSON. Internally extends ChatAdapter — formatting is similar, but the output instruction asks for JSON and parsing uses `json_repair`. The constructor’s `use_native_function_calling=True` default flips when tool calling is wired in.
**`dspy.XMLAdapter(callbacks=None)`**
-`<field_name>value</field_name>` tags. Lists use repeated `<item>` tags.
+Uses `<field_name>...</field_name>` tags, with nested fields for objects and `<item>` for lists. Supports streaming and leading reasoning blocks. Use `<field/>` for null, `<field></field>` for an empty string. Untyped (`Any`) values still require user validation.
+
+Container-closing tag sequences are reserved inside strings. Undeclared object fields are rejected unless the schema allows extras.
**`dspy.TwoStepAdapter(extraction_model: BaseLM, **kwargs)`**
Two LM calls per inference. Use it when the main LM is a reasoning model that’s bad at formatting — the extractor is usually a cheap general-purpose LM with ChatAdapter. Doesn’t support finetuning yet.
diff --git a/dspy/adapters/xml_adapter.py b/dspy/adapters/xml_adapter.py
index 8d6c42e67..c91144332 100644
--- a/dspy/adapters/xml_adapter.py
+++ b/dspy/adapters/xml_adapter.py
@@ -1,10 +1,13 @@
+import re
import types
import xml.etree.ElementTree as ET
from collections import defaultdict
+from functools import lru_cache
from typing import Any, Union, get_args, get_origin
from xml.sax.saxutils import quoteattr
import pydantic
+import regex
from pydantic import TypeAdapter
from typing_extensions import is_typeddict
@@ -19,41 +22,54 @@ from dspy.adapters.utils import (
from dspy.signatures.signature import Signature
from dspy.utils.exceptions import AdapterParseError
+# Avoid regex's compile/flag dispatch for every leaf and streaming chunk.
+_compile_xml_pattern = lru_cache(maxsize=128)(regex.compile)
+_xml_whitespace = re.compile(r"\s*")
+_xml_newline = re.compile(r"[ \t]*\r?\n")
+
class XMLAdapter(ChatAdapter):
+ """Formats and parses typed outputs using XML tags as field delimiters.
+
+ Text inside fields need not be valid XML, so models can return code, HTML,
+ and prose without escaping them.
+ """
+
def format_field_with_value(self, fields_with_values: dict[FieldInfoWithName, Any]) -> str:
output = []
for field, value in fields_with_values.items():
serialized = serialize_for_json(value)
is_output = (field.info.json_schema_extra or {}).get("__dspy_field_type") == "output"
- if is_output and self._uses_nested_xml(field.info.annotation) and isinstance(serialized, (dict, list)):
+ nested = isinstance(serialized, (dict, list)) and self._uses_nested_xml(field.info.annotation)
+ if is_output and (serialized is None or nested):
output.append(self._value_to_xml(serialized, field.name))
continue
formatted = format_field_value(field_info=field.info, value=value)
- if is_output and field.info.annotation is str:
- formatted = formatted.replace("&", "&amp;").replace("<", "&lt;")
output.append(f"<{field.name}>\n{formatted}\n</{field.name}>")
return "\n\n".join(output).strip()
def format_field_structure(self, signature: type[Signature]) -> str:
+ if not signature.output_fields:
+ return ""
+
def format_field(name, field):
- if (field.json_schema_extra or {}).get("__dspy_field_type") == "output" and self._uses_nested_xml(
- field.annotation
- ):
+ if self._uses_nested_xml(field.annotation):
return self._xml_schema(name, field.annotation)
- return self.format_field_with_value(
- {FieldInfoWithName(name=name, info=field): translate_field_type(name, field)}
+ annotations = (
+ get_args(field.annotation)
+ if get_origin(field.annotation) in (Union, types.UnionType)
+ else (field.annotation,)
)
-
- fields = (
- "\n\n".join(format_field(name, field) for name, field in group.items())
- for group in (signature.input_fields, signature.output_fields)
- )
- return "\n\n".join(
- (
- "All interactions will be structured in the following way, with the appropriate values filled in.",
- *fields,
+ # Primitive types are already described above; JSON hints conflict with XML nulls.
+ placeholder = (
+ "{" + name + "}"
+ if all(annotation in (str, int, float, bool, type(None)) for annotation in annotations)
+ else translate_field_type(name, field)
)
+ return self.format_field_with_value({FieldInfoWithName(name=name, info=field): placeholder})
+
+ return "Output format (replace placeholders):\n" + "\n\n".join(
+ format_field(name, field) for name, field in signature.output_fields.items()
)
def format_user_message_content(
@@ -82,51 +98,84 @@ class XMLAdapter(ChatAdapter):
return self.format_field_with_value(fields)
def user_message_output_requirements(self, signature: type[Signature]) -> str:
- fields = ", then ".join(f"`<{name}>`" for name in signature.output_fields)
- schemas = [
- self._xml_schema(name, field.annotation)
- for name, field in signature.output_fields.items()
- if self._uses_nested_xml(field.annotation)
- ]
- return f"Respond with the corresponding output fields wrapped in XML tags {fields}." + (
- f" Use this nested XML structure: {' '.join(schemas)}" if schemas else ""
+ if not signature.output_fields:
+ return ""
+ text = (
+ "Use this format for text outputs. Put field tags on separate lines."
+ " Write string values literally, without XML or JSON escaping."
)
+ nodes = []
+ for field in signature.output_fields.values():
+ schema = TypeAdapter(field.annotation).json_schema()
+ if self._uses_nested_xml(field.annotation):
+ nodes.append(schema)
+ else:
+ # DSPy types retain their own JSON conventions inside literal leaves.
+ nodes.extend(s for s in [schema, *schema.get("anyOf", [])] if s.get("type") == "null")
+ nullable = mapping = False
+ while nodes:
+ node = nodes.pop()
+ if isinstance(node, dict):
+ nullable |= node.get("type") == "null"
+ mapping |= isinstance(node.get("additionalProperties"), dict) or node.get("additionalProperties") is True
+ nodes.extend(node.values())
+ elif isinstance(node, list):
+ nodes.extend(node)
+ if nullable:
+ text += " Use <field/> for null and <field></field> for an empty string."
+ if mapping:
+ text += ' Dictionary keys: <entry key="...">; escape key attributes only.'
+ return self.format_field_structure(signature) + "\n\n" + text
def parse(self, signature: type[Signature], completion: str) -> dict[str, Any]:
+ fields = {}
+ context = "Failed to parse XML"
+ schemas = {
+ name: TypeAdapter(field.annotation).json_schema(by_alias=False)
+ for name, field in signature.output_fields.items()
+ }
try:
- root = ET.fromstring(f"<dspy_root>{completion}</dspy_root>")
- except ET.ParseError as e:
+ root = ET.Element("dspy_root")
+ prefix = _XMLPrefixParser(signature.output_fields)
+ text = prefix.feed(completion.strip(), final=True)
+ if text is None:
+ raise ET.ParseError("Incomplete leading thought block")
+ if prefix.fenced:
+ fence = re.fullmatch(r"(.*)\r?\n```[^<]*", text, re.DOTALL)
+ if not fence:
+ raise ET.ParseError("Missing closing XML fence")
+ text = fence[1].strip()
+ # Like ChatAdapter, ignore introductory prose before the first field.
+ text = re.sub(r"\A[^<]+(?=<)", "", text)
+ parser = _XMLParser(root, {"properties": schemas}, {})
+ parser.feed(text, final=True)
+ elements = self._group_children(root)
+ if "<" in parser.buffer or {child.tag for child in root} - signature.output_fields.keys():
+ raise ET.ParseError("Unexpected output field or closing tag")
+ for name, field in signature.output_fields.items():
+ if name not in elements:
+ continue
+ context = f"Failed to parse field {name}"
+ field_schema = schemas[name]
+ for candidate in [field_schema, *field_schema.get("anyOf", [])]:
+ try:
+ value = self._elements_to_value(elements[name], candidate, field_schema.get("$defs", {}))
+ if isinstance(value, (dict, list)):
+ fields[name] = TypeAdapter(field.annotation).validate_python(value, by_name=True, strict=False)
+ else:
+ fields[name] = parse_value(value, field.annotation)
+ break
+ except ValueError as e:
+ error = e
+ else:
+ raise error
+ except (ET.ParseError, ValueError) as e:
raise AdapterParseError(
adapter_name="XMLAdapter",
signature=signature,
lm_response=completion,
- message=f"Failed to parse XML: {e}",
+ message=f"{context}: {e}",
) from e
- elements = self._group_children(root)
- fields = {}
- for name, field in signature.output_fields.items():
- if name not in elements:
- continue
- adapter = TypeAdapter(field.annotation)
- schema = adapter.json_schema(by_alias=False)
- value = None
- for candidate in [schema, *schema.get("anyOf", [])]:
- try:
- value = self._elements_to_value(elements[name], candidate, schema.get("$defs", {}))
- try:
- fields[name] = parse_value(value, field.annotation)
- except pydantic.ValidationError:
- fields[name] = adapter.validate_python(value, by_name=True)
- break
- except ValueError as e:
- error = e
- else:
- raise AdapterParseError(
- adapter_name="XMLAdapter",
- signature=signature,
- lm_response=completion,
- message=f"Failed to parse field {field} with value {value}: {error}",
- ) from error
fields = apply_output_field_defaults(signature, fields)
if fields.keys() != signature.output_fields.keys():
raise AdapterParseError(
@@ -134,13 +183,57 @@ class XMLAdapter(ChatAdapter):
)
return fields
+ @classmethod
+ def _scalar_boundary(cls, schema: dict, definitions: dict, enclosing: str) -> str:
+ """Recognize sibling headers or the enclosing close chain, without consuming them."""
+ names = set()
+ choices = cls._schemas(schema, definitions)
+ siblings = []
+ for choice in choices:
+ if choice.get("type") == "array":
+ names.add("item")
+ siblings.extend(cls._schemas(choice.get("items", {}), definitions))
+ else:
+ siblings.append(choice)
+ for sibling in siblings:
+ names.update(sibling.get("properties", {}))
+ if any(not (name[:1] + name[1:].replace("-", "_").replace(".", "_")).isidentifier() for name in names):
+ names.add("entry")
+ arbitrary = any(
+ not s or (s.get("type") == "object" and s.get("additionalProperties", "properties" not in s) is not False)
+ for s in siblings
+ )
+ tags = r"[\w.-]+" if arbitrary else "|".join(re.escape(name) for name in sorted(names))
+ if not tags:
+ return enclosing
+ opening = rf"""<(?:{tags})(?:\s+key=(?:"[^"]*"|'[^']*'))?\s*/?>"""
+ return rf"(?:{opening}|{enclosing})"
+
+ @classmethod
+ def _schemas(cls, schema: dict, definitions: dict, child: str | None = None) -> list[dict]:
+ schema = definitions.get(schema.get("$ref", "").rsplit("/", 1)[-1], schema)
+ if choices := schema.get("anyOf", schema.get("oneOf")):
+ return [s for branch in choices for s in cls._schemas(branch, definitions, child)]
+ if child is None:
+ return [schema]
+ if schema.get("type") == "array":
+ item = schema.get("items", {})
+ return [item] if child == "item" else cls._schemas(item, definitions, child)
+ if schema.get("type") not in ("object", None):
+ return []
+ properties = schema.get("properties", {})
+ additional = schema.get("additionalProperties", "properties" not in schema)
+ if child not in properties and additional is False:
+ return []
+ value = properties.get(child, additional)
+ return [value if isinstance(value, dict) else {}]
+
@classmethod
def _value_to_xml(cls, value: Any, tag: str, key: str | None = None) -> str:
attrs = f" key={quoteattr(key)}" if key is not None else ""
if isinstance(value, list):
- children = "".join(cls._value_to_xml(item, "item") for item in value)
- return f"<{tag}{attrs}>{children}</{tag}>" if children else f"<{tag}{attrs} />"
- if isinstance(value, dict):
+ body = "\n".join(cls._value_to_xml(item, "item") for item in value)
+ elif isinstance(value, dict):
children = []
for name, child in value.items():
name = str(name)
@@ -148,49 +241,52 @@ class XMLAdapter(ChatAdapter):
children.append(
cls._value_to_xml(child, name) if valid_name else cls._value_to_xml(child, "entry", name)
)
- return f"<{tag}{attrs}>{''.join(children)}</{tag}>"
- return (
- f"<{tag}{attrs}>{str(value).replace('&', '&amp;').replace('<', '&lt;')}</{tag}>"
- if value is not None
- else f"<{tag}{attrs} />"
- )
+ body = "\n".join(children)
+ elif value is None:
+ return f"<{tag}{attrs} />"
+ else:
+ body = str(value)
+ return f"<{tag}{attrs}>\n{body}\n</{tag}>"
@classmethod
def _xml_schema(cls, tag: str, annotation: Any) -> str:
schema = TypeAdapter(annotation).json_schema(by_alias=False)
- return cls._schema_to_xml(tag, schema, schema.get("$defs", {}), frozenset())
- @classmethod
- def _schema_to_xml(cls, tag: str, schema: dict, definitions: dict, seen: frozenset[str]) -> str:
- if ref := schema.get("$ref"):
- name = ref.rsplit("/", 1)[-1]
- return (
- f"<{tag}>...</{tag}>"
- if name in seen
- else cls._schema_to_xml(tag, definitions[name], definitions, seen | {name})
- )
- if choices := schema.get("anyOf"):
- return cls._schema_to_xml(
- tag, next((s for s in choices if s.get("type") != "null"), choices[0]), definitions, seen
- )
- if schema.get("type") == "array":
- item = cls._schema_to_xml("item", schema.get("items", {}), definitions, seen)
- return f"<{tag}>{item}</{tag}>"
- children = "".join(
- cls._schema_to_xml(name, child, definitions, seen) for name, child in schema.get("properties", {}).items()
- )
- return f"<{tag}>{children}</{tag}>" if children else f"<{tag}>...</{tag}>"
+ def example(node, seen=frozenset()):
+ if ref := node.get("$ref"):
+ name = ref.rsplit("/", 1)[-1]
+ return "..." if name in seen else example(schema["$defs"][name], seen | {name})
+ if choices := node.get("anyOf", node.get("oneOf")):
+ return example(next(s for s in choices if s.get("type") != "null"), seen)
+ if node.get("type") == "array":
+ return [example(node.get("items", {}), seen)]
+ if not node.get("properties") and isinstance(node.get("additionalProperties"), dict):
+ return {"example key": example(node["additionalProperties"], seen)}
+ return {name: example(child, seen) for name, child in node.get("properties", {}).items()} or "..."
+
+ return cls._value_to_xml(example(schema), tag)
@classmethod
def _elements_to_value(cls, elements: list[ET.Element], schema: dict, definitions: dict) -> Any:
schema = definitions.get(schema.get("$ref", "").rsplit("/", 1)[-1], schema)
- if choices := schema.get("anyOf"):
- if {"type": "null"} in choices and not list(elements[0]) and not (elements[0].text or "").strip():
- return None
+ if (
+ len(elements) == 1
+ and (schema.get("type") == "null" or {"type": "null"} in schema.get("anyOf", []))
+ and not list(elements[0])
+ and elements[0].text is None
+ ):
+ return None
+ if choices := schema.get("anyOf", schema.get("oneOf")):
+ discriminator = schema.get("discriminator", {})
+ tags = cls._group_children(elements[0]).get(discriminator.get("propertyName"), [])
+ if len(tags) == 1 and (ref := discriminator.get("mapping", {}).get((tags[0].text or "").strip())):
+ return cls._elements_to_value(elements, {"$ref": ref}, definitions)
choices = [choice for choice in choices if choice.get("type") != "null"]
schema = choices[0]
if list(elements[0]):
schema = next((choice for choice in choices if choice.get("type") != "string"), schema)
+ if len(elements) > 1 and schema.get("type") not in ("array", None):
+ raise ValueError("Repeated elements require a list field")
if schema.get("type") == "array":
if len(elements) == 1 and not list(elements[0]):
text = (elements[0].text or "").strip()
@@ -200,13 +296,13 @@ class XMLAdapter(ChatAdapter):
elements = items
return [cls._elements_to_value([element], schema.get("items", {}), definitions) for element in elements]
element = elements[0]
- if schema.get("type") == "string" and list(element):
- return (element.text or "") + "".join(ET.tostring(child, encoding="unicode") for child in element)
+ if schema.get("type") not in ("object", None) and list(element):
+ raise ValueError("Scalar values cannot contain child fields")
children = cls._group_children(element)
if not children:
if schema.get("type") == "object" and not (element.text or "").strip():
return {}
- values = [(element.text or "").strip() for element in elements]
+ values = [element.text or "" for element in elements]
return values[0] if len(values) == 1 else values
properties = schema.get("properties", {})
child_schema = schema.get("additionalProperties", {})
@@ -238,3 +334,268 @@ class XMLAdapter(ChatAdapter):
or is_typeddict(annotation)
or (isinstance(annotation, type) and issubclass(annotation, pydantic.BaseModel))
)
+
+
+class _XMLParser:
+ """Schema-directed traversal that can pause for a chunk without reparsing completed children."""
+
+ def __init__(self, parent, schema, definitions, boundary=r"(?P<end>[^<]*\Z)", single=False):
+ self.parent = parent
+ self.schema = schema
+ self.definitions = definitions
+ self.boundary = boundary
+ self.single = single
+ self.text = ""
+ self.pos = 0
+ self.final = False
+ self.done = False
+ self.reader = None
+ self.waiting_for_tag = False
+ self.pending = []
+
+ @property
+ def buffer(self):
+ return self.text[self.pos:]
+
+ def feed(self, text, final=False):
+ if self.waiting_for_tag and not final and "<" not in text:
+ self.pending.append(text)
+ return ""
+ if self.pending:
+ text = "".join([*self.pending, text])
+ self.pending.clear()
+ self.waiting_for_tag = False
+ self.text = self.buffer + text
+ self.pos = 0
+ self.final = final
+ if self.reader is None:
+ self.reader = self._children(self.parent, self.schema, self.definitions, self.boundary, self.single)
+ try:
+ next(self.reader)
+ except StopIteration:
+ self.done = True
+ return ""
+
+ def _match(self, pattern):
+ while True:
+ match = _compile_xml_pattern(pattern).match(self.text, self.pos, partial=not self.final)
+ if not match:
+ raise ET.ParseError("Expected a field tag")
+ if not match.partial:
+ return match
+ yield
+
+ def _children(self, parent, schema, definitions, boundary, single=False):
+ enclosing = boundary if boundary.startswith("</") else None
+ boundary = XMLAdapter._scalar_boundary(schema, definitions, boundary)
+ while True:
+ self.pos = _xml_whitespace.match(self.text, self.pos).end()
+ if not self.final and (
+ self.pos == len(self.text) or (self.pos == len(self.text) - 1 and self.text[self.pos] == "<")
+ ):
+ yield
+ continue
+ if self.pos == len(self.text) or self.text.startswith("</", self.pos):
+ return
+ # Only top-level trailing prose is ignorable; nested containers still require tags.
+ if enclosing is None and not self.text.startswith("<", self.pos):
+ return
+ opening = yield from self._match(r"""<([\w.-]+)(?:\s+key=(?:"[^"]*"|'[^']*'))?\s*(/?)>""")
+ name = opening[1]
+ element = ET.fromstring(opening[0] if opening[2] else opening[0] + f"</{name}>")
+ key = element.get("key", name) if name == "entry" else name
+ children = XMLAdapter._schemas(schema, definitions, key)
+ if not children:
+ raise ET.ParseError(f"Unexpected field {key}")
+ parent.append(element)
+ self.pos = opening.end()
+ if not opening[2]:
+ child_schema = children[0] if len(children) == 1 else {"anyOf": children}
+ child_definitions = {**definitions, **child_schema.get("$defs", {})}
+ choices = XMLAdapter._schemas(child_schema, child_definitions)
+ structured = any(s.get("type") in ("object", "array") or not s for s in choices)
+ nested = False
+ while structured:
+ newline = _xml_newline.match(self.text, self.pos)
+ nested_start = _xml_whitespace.match(self.text, self.pos).end()
+ ambiguous = newline and any(s.get("type") == "string" for s in choices)
+ tag_line = _compile_xml_pattern(r"<[^>\n]+>[ \t]*(?:\r?\n|$)").match(
+ self.text, nested_start, partial=not self.final
+ ) if ambiguous else None
+ if not self.final and (
+ nested_start == len(self.text)
+ or (tag_line and (tag_line.partial or tag_line.end() == len(self.text)))
+ ):
+ yield
+ continue
+ nested = bool(tag_line) if ambiguous else self.text.startswith("<", nested_start)
+ break
+ element.text = ""
+ if nested:
+ self.pos = nested_start
+ yield from self._children(
+ element, child_schema, child_definitions, rf"</{re.escape(name)}\s*>\s*{boundary}"
+ )
+ closing = yield from self._match(rf"</{re.escape(name)}\s*>")
+ self.pos = closing.end()
+ else:
+ parser = _XMLScalarParser(name, boundary, enclosing)
+ values = []
+ while True:
+ value, self.pos = parser.read(self.text, self.pos, final=self.final)
+ values.append(value)
+ if parser.done:
+ element.text = "".join(values)
+ break
+ if self.final:
+ raise ET.ParseError(f"Missing closing tag for {name}")
+ self.waiting_for_tag = parser.waiting_for_tag
+ yield
+ if single:
+ return
+
+
+class _XMLPrefixParser:
+ """Discard leading thought blocks and one XML fence, without retaining thought bodies."""
+
+ def __init__(self, output_fields):
+ self.output_fields = output_fields
+ self.buffer = ""
+ self.thought = None
+ self.fenced = False
+ self.done = False
+
+ def feed(self, text: str, final: bool = False) -> str | None:
+ if self.done:
+ return text
+ self.buffer += text
+ while True:
+ if self.thought:
+ closing = f"</{self.thought}>"
+ end = self.buffer.find(closing)
+ if end < 0:
+ # Only a split closing tag can matter in the next chunk.
+ self.buffer = self.buffer[-(len(closing) - 1):]
+ return None
+ self.buffer = self.buffer[end + len(closing):]
+ self.thought = None
+ self.buffer = self.buffer.lstrip()
+ opening = _compile_xml_pattern(r"<(think|thinking)>|```(?:xml)?[ \t]*\r?\n").match(
+ self.buffer, partial=not final
+ )
+ if opening:
+ if opening.partial:
+ return None
+ if opening[1] and opening[1] not in self.output_fields:
+ self.thought = opening[1]
+ self.buffer = self.buffer[opening.end():]
+ continue
+ if not opening[1] and not self.fenced:
+ self.fenced = True
+ self.buffer = self.buffer[opening.end():]
+ continue
+ self.done = True
+ text, self.buffer = self.buffer, ""
+ return text
+
+
+class _XMLScalarParser:
+ """Read a literal leaf after its opening tag, in full or incrementally."""
+
+ def __init__(self, name: str, boundary: str, enclosing: str | None = None):
+ self.name = re.escape(name)
+ self.boundary = boundary
+ self.enclosing = enclosing
+ self.buffer = ""
+ self.multiline = None
+ self.at_line_start = True
+ self.value_started = False
+ self.done = False
+ self.waiting_for_tag = False
+ self.pending = []
+
+ def feed(self, text: str, final: bool = False) -> str:
+ # Plain text cannot resolve an ambiguous terminal close. Accumulate chunks
+ # without copying/rescanning the growing suffix on every token.
+ if self.waiting_for_tag and not final and "<" not in text:
+ self.pending.append(text)
+ return ""
+ if self.pending:
+ text = "".join([*self.pending, text])
+ self.pending.clear()
+ self.buffer += text
+ value, pos = self.read(self.buffer, 0, final=final)
+ self.buffer = self.buffer[pos:]
+ return value
+
+ def read(self, text: str, pos: int, final: bool) -> tuple[str, int]:
+ """Scan a shared response without copying its unconsumed suffix."""
+ self.waiting_for_tag = False
+ if self.multiline is None:
+ newline = _xml_newline.match(text, pos)
+ if not newline and not final and re.compile(r"[ \t]*\r?").fullmatch(text, pos):
+ return "", pos
+ self.multiline = newline is not None
+ if newline:
+ pos = newline.end()
+
+ if self.multiline:
+ # A tag at a chunk boundary may still be followed by literal text on the same line.
+ ending = r"(?:\n|$)" if final else r"\n"
+ # Accept an end-of-line closing tag attached to text (e.g. a Markdown code fence).
+ pattern = rf"</{self.name}[ \t]*>[ \t]*\r?{ending}"
+ else:
+ pattern = rf"</{self.name}\s*>"
+ if self.enclosing:
+ # A missing leaf close must not consume the next object or list item.
+ pattern = rf"{pattern}|(?P<scope>{self.enclosing})"
+ closing_pattern = _compile_xml_pattern(pattern)
+ continuation_pattern = _compile_xml_pattern(rf"\s*{self.boundary}")
+ end = len(text)
+ for candidate in closing_pattern.finditer(text, pos, partial=not final):
+ if candidate.partial:
+ end = candidate.start()
+ break
+ # Match in place rather than copying the response suffix for each candidate.
+ continuation = continuation_pattern.match(text, candidate.end(), partial=not final)
+ if self.enclosing and (candidate.group("scope") is not None or continuation is None):
+ scope = _compile_xml_pattern(self.enclosing).match(text, candidate.start(), partial=not final)
+ if scope:
+ if not final and (scope.partial or scope.group("end") is not None):
+ end = candidate.start()
+ self.waiting_for_tag = not scope.partial
+ break
+ raise ET.ParseError(f"Missing closing tag for {self.name} before container end")
+ if continuation is None:
+ # An inner closing tag followed by literal text is part of the value.
+ continue
+ end = candidate.start()
+ # A plain suffix may be sign-off prose or literal text before a later close.
+ # Keep it behind the candidate until another tag or EOF resolves the boundary.
+ self.done = not continuation.partial and (final or continuation.group("end") is None)
+ self.waiting_for_tag = not self.done and not continuation.partial
+ break
+
+ if self.multiline:
+ line_start = text.rfind("\n", pos, end) + 1
+ if line_start > pos or self.at_line_start:
+ line_start = max(pos, line_start)
+ if not text[line_start:end].strip(" \t"):
+ end = line_start
+ value = text[pos:end]
+ if self.done:
+ consumed = candidate.end()
+ value = value.removesuffix("\n").removesuffix("\r") if self.multiline else value.rstrip()
+ else:
+ # Retain the possible framing newline (or compact trailing whitespace) until the delimiter is known.
+ if self.multiline:
+ value = value.removesuffix("\n").removesuffix("\r")
+ else:
+ value = value.rstrip()
+ consumed = pos + len(value)
+ if value:
+ self.at_line_start = value.endswith("\n")
+ if not self.multiline and not self.value_started:
+ value = value.lstrip()
+ self.value_started |= bool(value)
+ return value, consumed
diff --git a/dspy/streaming/streamify.py b/dspy/streaming/streamify.py
index 044204156..e1b94d5aa 100644
--- a/dspy/streaming/streamify.py
+++ b/dspy/streaming/streamify.py
@@ -221,6 +221,11 @@ def streamify(
async for value in receive_stream:
if isinstance(value, _StreamSignature):
for listener in predict_id_to_listener.get(value.predict_id, []):
+ # A new predictor call also ends the previous one when the provider omitted its stop chunk.
+ if listener.allow_reuse:
+ if final_chunk := listener.finalize():
+ yield final_chunk
+ listener._reset()
listener._set_signature(value.signature)
elif _is_litellm_model_response_stream(value):
if len(predict_id_to_listener) == 0:
diff --git a/dspy/streaming/streaming_listener.py b/dspy/streaming/streaming_listener.py
index 9f171f99b..a90197eb6 100644
--- a/dspy/streaming/streaming_listener.py
+++ b/dspy/streaming/streaming_listener.py
@@ -2,15 +2,18 @@ from __future__ import annotations
import inspect
import re
+import xml.etree.ElementTree as ET
from collections import defaultdict
from queue import Queue
from typing import TYPE_CHECKING, Any
+from pydantic import TypeAdapter
+
from dspy.adapters.chat_adapter import ChatAdapter
from dspy.adapters.json_adapter import JSONAdapter
from dspy.adapters.types import Type
from dspy.adapters.types.reasoning import Reasoning
-from dspy.adapters.xml_adapter import XMLAdapter
+from dspy.adapters.xml_adapter import XMLAdapter, _XMLParser, _XMLPrefixParser, _XMLScalarParser
from dspy.dsp.utils.settings import settings
from dspy.streaming.messages import StreamResponse
from dspy.utils.lazy_import import require
@@ -47,20 +50,12 @@ class StreamListener:
"""
self.signature_field_name = signature_field_name
self._wire_field_name = signature_field_name
+ self._wire_signature = None
self._use_native_reasoning = True
self.predict = predict
self.predict_name = predict_name
-
- self.field_start_queue = []
- self.field_end_queue = Queue()
- self.stream_start = False
- self.stream_end = False
- self.cache_hit = False
self.allow_reuse = allow_reuse
-
- self.json_adapter_state = {"field_accumulated_messages": ""}
- self.value_started = False
- self.held_whitespace = ""
+ self._reset()
self.adapter_identifiers = {
"ChatAdapter": {
@@ -86,6 +81,20 @@ class StreamListener:
},
}
+ def _reset(self):
+ """Clear response state independently of whether the target field was present."""
+ self.field_start_queue = []
+ self.field_end_queue = Queue()
+ self.stream_start = False
+ self.stream_end = False
+ self.cache_hit = False
+ self.json_adapter_state = {"field_accumulated_messages": ""}
+ self.value_started = False
+ self.held_whitespace = ""
+ self.xml_parser = None
+ self.xml_prefix = None
+ self.xml_response_complete = False
+
def _buffered_message_end_with_start_identifier(self, concat_message: str, start_identifier: str) -> str:
for i in range(len(concat_message)):
if start_identifier.startswith(concat_message[len(concat_message) - i - 1 :]):
@@ -123,6 +132,8 @@ class StreamListener:
def _set_signature(self, signature):
# Use the adapter's decision, after per-call overrides and native adaptation.
+ self._wire_signature = signature
+ self._wire_field_name = self.signature_field_name
self._use_native_reasoning = True
for name, field in signature.output_fields.items():
if field.json_schema_extra.get("__dspy_reasoning_field", name) == self.signature_field_name:
@@ -147,15 +158,12 @@ class StreamListener:
if self.stream_end:
if self.allow_reuse:
+ if isinstance(settings.adapter, XMLAdapter) and not self.xml_response_complete:
+ # A field can end before its response's trailing XML/Markdown framing.
+ self.xml_response_complete = chunk.choices[0].finish_reason is not None
+ return
# Clear up the state for the next stream.
- self.stream_end = False
- self.cache_hit = False
- self.field_start_queue = []
- self.field_end_queue = Queue()
- self.json_adapter_state["field_accumulated_messages"] = ""
- self.stream_start = False
- self.value_started = False
- self.held_whitespace = ""
+ self._reset()
else:
return
@@ -178,11 +186,17 @@ class StreamListener:
# For non-custom streamable types, the streaming chunks come from the content field of the ModelResponseStream.
try:
chunk_message = chunk.choices[0].delta.content
- if chunk_message is None:
- return
except Exception:
return
+ if isinstance(settings.adapter, XMLAdapter) and not settings.adapter._uses_nested_xml(self._output_type):
+ self.xml_response_complete = chunk.choices[0].finish_reason is not None
+ return self._xml_adapter_handle_stream_chunk(
+ chunk_message or "", final=self.xml_response_complete
+ )
+ if chunk_message is None:
+ return
+
if chunk_message and start_identifier in chunk_message and not isinstance(settings.adapter, JSONAdapter):
# If the cache is hit, the chunk_message could be the full response. When it happens we can
# directly end the stream listening. In some models like gemini, each stream chunk can be multiple
@@ -260,6 +274,58 @@ class StreamListener:
# Other adapters rely on the end_identifier to detect the end of the field we are listening to.
return self._default_handle_stream_chunk(token, end_identifier)
+ def _xml_adapter_handle_stream_chunk(self, text: str, final: bool = False) -> StreamResponse | None:
+ signature = self._wire_signature or (self.predict.signature if self.predict else None)
+ fields = signature.output_fields if signature else {self._wire_field_name: None}
+ if self.xml_prefix is None:
+ self.xml_prefix = _XMLPrefixParser(fields)
+ text = self.xml_prefix.feed(text, final=final)
+ if text is None:
+ return None
+ while True:
+ if self.xml_parser is None:
+ self.field_start_queue.append(text)
+ buffered = "".join(self.field_start_queue)
+ names = "|".join(re.escape(name) for name in fields)
+ opening = re.search(rf"<({names})\s*(/?)>", buffered)
+ if not opening:
+ # Retain only a potentially split field header.
+ self.field_start_queue = [buffered[buffered.rfind("<") :]] if "<" in buffered else []
+ return None
+ self.field_start_queue = []
+ self.stream_start = opening[1] == self._wire_field_name
+ text = buffered[opening.end() :]
+ if opening[2]:
+ if self.stream_start:
+ self.stream_end = True
+ return StreamResponse(self.predict_name, self.signature_field_name, "", is_last_chunk=True)
+ continue
+ boundary = XMLAdapter._scalar_boundary({"properties": fields}, {}, r"(?P<end>[^<]*\Z)")
+ if self.stream_start:
+ self.xml_parser = _XMLScalarParser(opening[1], boundary)
+ else:
+ schema = TypeAdapter(fields[opening[1]].annotation).json_schema(by_alias=False)
+ self.xml_parser = _XMLParser(
+ ET.Element("root"), {"properties": {opening[1]: schema}}, {}, boundary, single=True
+ )
+ text = buffered[opening.start():]
+ try:
+ token = self.xml_parser.feed(text, final=final)
+ except ET.ParseError:
+ # Final adapter postprocessing owns errors, including tolerated text alongside native tool calls.
+ self.stream_end = True
+ return None
+ if self.stream_start:
+ self.stream_end = self.xml_parser.done
+ if token or self.stream_end:
+ return StreamResponse(self.predict_name, self.signature_field_name, token, is_last_chunk=self.stream_end)
+ return None
+ # Skip preceding fields as complete values, not as arbitrary text containing our field's tag.
+ if not self.xml_parser.done:
+ return None
+ text = self.xml_parser.buffer
+ self.xml_parser = None
+
def _json_adapter_handle_stream_chunk(self, token: str, chunk_message: str) -> StreamResponse | None:
self.json_adapter_state["field_accumulated_messages"] += chunk_message
if self.json_adapter_state["field_accumulated_messages"].rstrip().endswith("}"):
@@ -382,8 +448,13 @@ class StreamListener:
A StreamResponse with the remaining buffered tokens and is_last_chunk=True,
or None if there are no buffered tokens or the stream hasn't started.
"""
- if self.stream_end or not self.stream_start:
- # Stream already ended or never started, nothing to finalize
+ self.xml_response_complete = True
+ if self.stream_end:
+ return None
+
+ if self.xml_parser is not None:
+ return self._xml_adapter_handle_stream_chunk("", final=True)
+ if not self.stream_start:
return None
self.stream_end = True
diff --git a/tests/adapters/test_xml_adapter.py b/tests/adapters/test_xml_adapter.py
index fcbd25c01..2dec5e220 100644
--- a/tests/adapters/test_xml_adapter.py
+++ b/tests/adapters/test_xml_adapter.py
@@ -1,3 +1,4 @@
+from typing import Literal
from unittest import mock
import pydantic
@@ -73,6 +74,357 @@ def test_xml_adapter_parse_casts_types():
assert parsed == {"number": 42, "flag": True}
[email protected]("fenced", [False, True])
[email protected]("closing_newline", ["\n", ""])
[email protected]("prefix", ["", "<think>Consider <code>wrong</code>.</think>\n", "Here is the code:\n\n"])
+def test_xml_adapter_predict_accepts_literal_code_without_fallback(fenced, closing_newline, prefix):
+ class Generate(dspy.Signature):
+ question: str = dspy.InputField()
+ reasoning: str = dspy.OutputField()
+ code: str = dspy.OutputField()
+
+ code = "```python\nif len(page) < 20:\n print('R&B', '</code>')\n```"
+ completion = f"{prefix}<reasoning>\nKeep R&B tracks\n</reasoning>\n<code>\n{code}{closing_newline}</code>"
+ if fenced:
+ completion = f"```xml\n{completion}\n```"
+ with mock.patch("litellm.completion") as completion_mock:
+ completion_mock.return_value = ModelResponse(
+ choices=[Choices(message=Message(content=completion))], model="openai/gpt-4o-mini"
+ )
+ with dspy.context(
+ lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False),
+ adapter=XMLAdapter(use_json_adapter_fallback=False),
+ ):
+ result = dspy.Predict(Generate)(question="Write a pagination check")
+ assert result.code == code
+ assert result.reasoning == "Keep R&B tracks"
+ assert completion_mock.call_count == 1
+
+
+ "body, annotation, expected",
+ [
+ ("<answer>Paris</answer>", str, "Paris"),
+ ("<answer> \r\n Paris \r\n </answer> ", str, " Paris "),
+ ("<answer>\n\n</answer>", str, ""),
+ ("<answer/>", str | None, None),
+ ("<answer><item>Paris</item><item>Lyon</item></answer>", list[str], ["Paris", "Lyon"]),
+ ("<answer>\nx = '''\n</answer>\nR&B\n'''\n</answer>", str, "x = '''\n</answer>\nR&B\n'''"),
+ ("```xml\n<answer>\nParis\n</answer>\n```", str, "Paris"),
+ ],
+)
+def test_xml_adapter_predict_ignores_trailing_prose(body, annotation, expected):
+ signature = dspy.Signature("question -> answer").with_updated_fields("answer", type_=annotation)
+ response = body + "\n\nLet me know if you need anything else."
+ with mock.patch("litellm.completion", return_value=ModelResponse(
+ choices=[Choices(message=Message(content=response))], model="openai/gpt-4o-mini"
+ )):
+ with dspy.context(
+ lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False),
+ adapter=XMLAdapter(use_json_adapter_fallback=False),
+ ):
+ assert dspy.Predict(signature)(question="Name French cities").answer == expected
+
+
[email protected]("name", ["think", "thinking"])
+def test_xml_adapter_preserves_declared_thinking_field(name):
+ signature = dspy.Signature(f"question -> {name}, answer")
+ result = XMLAdapter().parse(signature, f"<{name}>Literal thought</{name}><answer>42</answer>")
+ assert result == {name: "Literal thought", "answer": "42"}
+
+
[email protected]("prefix", ["<think>unfinished", "<thinking>unfinished", "<unknown>extra</unknown>"])
+def test_xml_adapter_does_not_ignore_incomplete_reasoning_or_unknown_fields(prefix):
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ XMLAdapter().parse(dspy.Signature("question -> answer"), prefix + "<answer>42</answer>")
+
+
+def test_xml_adapter_xml_syntax_is_literal_text():
+ class Result(dspy.Signature):
+ text: str = dspy.OutputField()
+
+ value = "<![CDATA[<raw> &amp; &#65;]]>"
+ adapter = XMLAdapter()
+ formatted = adapter.format_assistant_message_content(Result, {"text": value})
+ assert formatted == f"<text>\n{value}\n</text>"
+ assert adapter.parse(Result, formatted) == {"text": value}
+ assert adapter.parse(Result, f"<text>{value}</text>") == {"text": value}
+
+
+ "value",
+ [
+ "if x<y: print('</code>', '</item>', 'R&B')",
+ "payload\n</code>\n</item>\n</source>\nmore &amp; text",
+ ],
+)
+def test_xml_adapter_literal_leaves_round_trip_at_every_depth(value):
+ class Program(pydantic.BaseModel):
+ code: str
+ alternatives: list[str]
+ metadata: dict[str, str]
+
+ Labels = TypedDict("Labels", {"first": str, "postal code": str})
+
+ class Result(dspy.Signature):
+ code: str = dspy.OutputField()
+ programs: list[Program] = dspy.OutputField()
+ labels: Labels = dspy.OutputField()
+
+ expected = {
+ "code": value,
+ "programs": [
+ Program(code=value, alternatives=[value, "second"], metadata={"source": value, "other": "tail"}),
+ Program(code="last", alternatives=[], metadata={}),
+ ],
+ "labels": {"first": "before", "postal code": "after"},
+ }
+ adapter = XMLAdapter()
+ formatted = adapter.format_assistant_message_content(Result, expected)
+ assert adapter.parse(Result, formatted) == expected
+
+
[email protected]("case", ["nested_html", "unicode_key", "html_with_extra"])
+def test_xml_predict_round_trips_nested_html_and_unicode_keys(case):
+ class Page(pydantic.BaseModel):
+ model_config = pydantic.ConfigDict(strict=True)
+ html: str
+ name: str
+ count: int = pydantic.Field(alias="count-alias")
+
+ annotation, expected = (
+ (Page, Page(html="<html>Body</html>\n<footer>Copyright</footer>", name="literal <name> opening", **{"count-alias": 2}))
+ if case != "unicode_key"
+ else (dict[str, str], {"cafe\u0301": "decomposed", "café": "precomposed"})
+ )
+ signature = dspy.Signature({"result": (annotation, dspy.OutputField())})
+ adapter = XMLAdapter(use_json_adapter_fallback=False)
+ response = adapter.format_assistant_message_content(signature, {"result": expected})
+ if case == "html_with_extra":
+ response = response.replace("</name>", "</name>\n<extra>ignored</extra>")
+ with mock.patch("litellm.completion", return_value=ModelResponse(
+ choices=[Choices(message=Message(content=response))], model="openai/gpt-4o-mini"
+ )):
+ with dspy.context(lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False), adapter=adapter):
+ if case == "html_with_extra":
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ dspy.Predict(signature)()
+ return
+ assert dspy.Predict(signature)().result == expected
+
+
[email protected]("kind", ["cat", "dog"])
+def test_xml_adapter_nested_discriminated_union_round_trip(kind):
+ class Cat(pydantic.BaseModel):
+ kind: Literal["cat"]
+ name: str
+
+ class Dog(pydantic.BaseModel):
+ kind: Literal["dog"]
+ tricks: list[str]
+ nickname: str | None
+
+ class Owner(pydantic.BaseModel):
+ pet: Cat | Dog = pydantic.Field(discriminator="kind")
+
+ class Result(dspy.Signature):
+ owner: Owner = dspy.OutputField()
+
+ pet = Cat(kind="cat", name="Milo") if kind == "cat" else Dog(kind="dog", tricks=["sit", "fetch"], nickname=None)
+ expected = {"owner": Owner(pet=pet)}
+ adapter = XMLAdapter()
+ formatted = adapter.format_assistant_message_content(Result, expected)
+ assert adapter.parse(Result, formatted) == expected
+ assert adapter.parse(Result, formatted.replace("\n", "")) == expected
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ adapter.parse(Result, formatted.replace(f"\n{kind}\n", "\nunknown\n"))
+
+
[email protected]("newline", ["\n", "\r\n"])
+def test_xml_adapter_html_round_trip_with_same_named_ancestors(newline):
+ class Page(pydantic.BaseModel):
+ html: str
+
+ class Result(dspy.Signature):
+ html: Page = dspy.OutputField()
+ pages: list[Page] = dspy.OutputField()
+ count: int = dspy.OutputField()
+
+ page = newline.join(["<!DOCTYPE html>", "<html><body>R&B &amp; 雪</body>", "</html>"])
+ expected = {"html": Page(html=page), "pages": [Page(html=page), Page(html="second")], "count": 2}
+ adapter = XMLAdapter()
+ formatted = adapter.format_assistant_message_content(Result, expected)
+ assert adapter.parse(Result, formatted) == expected
+
+
+ "completion, expected",
+ [
+ ("<code>x</code></code>", "x</code>"),
+ ("<code>\nx\n</code>\nsurplus\n</code>", "x\n</code>\nsurplus"),
+ ("<code>print('</code>')</code>", "print('</code>')"),
+ ],
+)
+def test_xml_adapter_recovers_literal_closing_tags(completion, expected):
+ assert XMLAdapter().parse(dspy.Signature("-> code"), completion) == {"code": expected}
+
+
[email protected]("newline", ["\n", "\r\n"])
+def test_xml_adapter_nested_tag_lines_preserve_literal_payload(newline):
+ class Program(pydantic.BaseModel):
+ code: str
+ checks: list[str]
+
+ class Result(dspy.Signature):
+ program: Program = dspy.OutputField()
+
+ code = f" if n < 20:{newline} print('</code> &amp;') "
+ completion = newline.join(
+ [
+ "<program>",
+ " <code>",
+ code,
+ " </code>",
+ " <checks>",
+ " <item>",
+ "print('</item>')",
+ " </item>",
+ " <item>",
+ "R&B",
+ " </item>",
+ " </checks>",
+ "</program>",
+ ]
+ )
+ assert XMLAdapter().parse(Result, completion) == {"program": Program(code=code, checks=["print('</item>')", "R&B"])}
+
+
+ "completion",
+ [
+ "<code>unterminated",
+ "<code>x</wrong>",
+ "<code>x</code><code>y</code>",
+ "<code>x</code><unknown>y</unknown>",
+ '<entry key="code">x</entry>',
+ "<code>x</code><counts><item>2</counts>",
+ "<code>x</code><counts>bad</counts></code>",
+ "<code>x</code>Thanks! <unknown>extra</unknown>",
+ "<code>x</code><counts><item>2</counts>Thanks!",
+ ],
+)
+def test_xml_adapter_validates_outer_fields_and_structured_nesting(completion):
+ class Result(dspy.Signature):
+ code: str = dspy.OutputField()
+ counts: list[int] = dspy.OutputField(default=[])
+
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ XMLAdapter().parse(Result, completion)
+
+
+def test_xml_adapter_nullable_scalar_cannot_repeat():
+ class Result(dspy.Signature):
+ text: str | None = dspy.OutputField()
+
+ assert XMLAdapter().parse(Result, "<text />") == {"text": None}
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ XMLAdapter().parse(Result, "<text /><text />")
+
+
[email protected]("value", [None, ""])
+def test_xml_adapter_nullable_text_round_trip_distinguishes_empty_from_null(value):
+ class Result(dspy.Signature):
+ text: str | None = dspy.OutputField()
+
+ adapter = XMLAdapter()
+ formatted = adapter.format_assistant_message_content(Result, {"text": value})
+ assert adapter.parse(Result, formatted) == {"text": value}
+ assert adapter.parse(Result, "<text>\n\n</text>") == {"text": ""}
+ messages = adapter.format(Result, [], {})
+ assert messages[0]["content"].split("Output format (replace placeholders):\n")[1].startswith(
+ "<text>\n{text}\n</text>\n"
+ )
+ assert messages[-1]["content"] == (
+ "Output format (replace placeholders):\n<text>\n{text}\n</text>\n\n"
+ "Use this format for text outputs. Put field tags on separate lines. "
+ "Write string values literally, without XML or JSON escaping."
+ " Use <field/> for null and <field></field> for an empty string."
+ )
+ assert "JSON" not in messages[0]["content"]
+
+
[email protected]("values", [None, [], ["", None, "R&B"]])
+def test_xml_adapter_nullable_containers_round_trip(values):
+ class Result(dspy.Signature):
+ values: list[str | None] | None = dspy.OutputField()
+ mapping: dict[str, str | None] | None = dspy.OutputField()
+ missing: None = dspy.OutputField()
+
+ expected = {
+ "values": values,
+ "mapping": None if values is None else {str(i): value for i, value in enumerate(values)},
+ "missing": None,
+ }
+ adapter = XMLAdapter()
+ formatted = adapter.format_assistant_message_content(Result, expected)
+ assert adapter.parse(Result, formatted) == expected
+
+
+def test_xml_adapter_concise_prompt_preserves_type_guidance_and_dictionary_keys():
+ from enum import Enum
+ from typing import Any
+
+ class Choice(Enum):
+ YES = "yes"
+ NO = "no"
+
+ class Result(dspy.Signature):
+ question: str = dspy.InputField()
+ scalar: int | str = dspy.OutputField()
+ choice: Choice = dspy.OutputField()
+ pair: tuple[str, int] = dspy.OutputField()
+ metadata: dict[str, Any] = dspy.OutputField()
+
+ messages = XMLAdapter().format(Result, [], {"question": "Choose"})
+ structure = messages[0]["content"].split("Output format (replace placeholders):\n")[1]
+ assert "<question>" not in structure
+ assert "<scalar>\n{scalar}\n</scalar>" in structure
+ assert "{choice} # note: the value you produce must be one of: yes; no" in structure
+ assert "{pair} # note: the value you produce must adhere to the JSON schema:" in structure
+ assert "<metadata>\n...\n</metadata>" in structure
+ assert "Output format (replace placeholders):\n" in messages[-1]["content"]
+ assert "<metadata>\n...\n</metadata>" in messages[-1]["content"]
+ assert messages[-1]["content"].endswith(
+ "Use this format for text outputs. Put field tags on separate lines. "
+ "Write string values literally, without XML or JSON escaping."
+ ' Dictionary keys: <entry key="...">; escape key attributes only.'
+ )
+
+
+def test_xml_adapter_structured_union_uses_structural_tag_lines():
+ class Person(pydantic.BaseModel):
+ name: str
+ age: int
+
+ class Result(dspy.Signature):
+ person: str | Person = dspy.OutputField()
+
+ adapter = XMLAdapter()
+ body = "<name>Ada</name><age>not an integer</age>"
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ adapter.parse(Result, f"<person>{body}</person>")
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ adapter.parse(Result, "<person>\n<name>\nAda\n</name>\n<age>\nbad\n</age>\n</person>")
+ assert adapter.parse(Result, f"<person>\n{body}\n</person>") == {"person": body}
+ assert adapter.parse(Result, adapter.format_assistant_message_content(Result, {"person": body})) == {"person": body}
+ assert adapter.parse(Result, "<person><name>Ada</name><age>36</age></person>") == {
+ "person": Person(name="Ada", age=36)
+ }
+ assert adapter.parse(Result, "<person>\n<name>\n<unfinished>\n</name>\n<age>\n36\n</age>\n</person>") == {
+ "person": Person(name="<unfinished>", age=36)
+ }
+
+
def test_xml_adapter_parse_raises_on_type_error():
class TestSignature(dspy.Signature):
number: int = dspy.OutputField()
@@ -89,23 +441,33 @@ def test_xml_adapter_repeated_dict_elements_and_empty_lists():
counts: dict[str, list[int]] = dspy.OutputField()
adapter = XMLAdapter()
+ assert '<entry key="example key">\n<item>\n...\n</item>\n</entry>' in (
+ adapter.format_field_structure(TestSignature)
+ )
completion = "<counts><first>3</first><first>4</first><second>5</second></counts>"
assert adapter.parse(TestSignature, completion) == {
"counts": {"first": [3, 4], "second": [5]},
}
+ assert adapter.parse(TestSignature, "<counts>\n<first><item>3</item><item>4</item></first>\n</counts>") == {
+ "counts": {"first": [3, 4]},
+ }
counts = {"postal code": [3, 4], 'quoted "key" & more': [5], "line\nbreak": [6], "-status": [7], ".status": [8]}
field = FieldInfoWithName(name="counts", info=TestSignature.output_fields["counts"])
formatted = adapter.format_field_with_value({field: counts})
- assert '<entry key="postal code"><item>3</item><item>4</item></entry>' in formatted
+ assert '<entry key="postal code">\n<item>\n3\n</item>\n<item>\n4\n</item>\n</entry>' in formatted
assert adapter.parse(TestSignature, formatted) == {"counts": counts}
assert adapter.parse(TestSignature, "<counts />") == {"counts": {}}
class EmptySignature(dspy.Signature):
items: list[str] = dspy.OutputField()
+ assert adapter.parse(EmptySignature, "<items>\n<item>Q7-194</item>\n<item>M2-863</item>\n</items>") == {
+ "items": ["Q7-194", "M2-863"],
+ }
+
field = FieldInfoWithName(name="items", info=EmptySignature.output_fields["items"])
- assert adapter.format_field_with_value({field: []}) == "<items />"
+ assert adapter.format_field_with_value({field: []}) == "<items>\n\n</items>"
assert adapter.parse(EmptySignature, "<items />") == {"items": []}
@@ -121,8 +483,8 @@ def test_xml_adapter_uses_pydantic_field_names_as_xml_tags():
address = Address(**{"postal code": "94305", "country-code": "US"})
xml = adapter.format_assistant_message_content(TestSignature, {"address": address})
- assert xml == "<address><postal_code>94305</postal_code><country_code>US</country_code></address>"
- assert "<address><postal_code>...</postal_code><country_code>...</country_code></address>" in (
+ assert xml == "<address>\n<postal_code>\n94305\n</postal_code>\n<country_code>\nUS\n</country_code>\n</address>"
+ assert "<address>\n<postal_code>\n...\n</postal_code>\n<country_code>\n...\n</country_code>\n</address>" in (
adapter.format_field_structure(TestSignature)
)
assert adapter.parse(TestSignature, xml) == {"address": address}
@@ -143,17 +505,20 @@ def test_xml_adapter_typed_dict_schema_and_parsing():
adapter = XMLAdapter()
order_schema = (
- "<order><order_id>...</order_id><address><city>...</city></address>"
- "<labels><item>...</item></labels></order>"
+ "<order>\n<order_id>\n...\n</order_id>\n<address>\n<city>\n...\n</city>\n</address>\n"
+ "<labels>\n<item>\n...\n</item>\n</labels>\n</order>"
)
orders_schema = (
- "<orders><item><order_id>...</order_id><address><city>...</city></address>"
- "<labels><item>...</item></labels></item></orders>"
+ "<orders>\n<item>\n<order_id>\n...\n</order_id>\n<address>\n<city>\n...\n</city>\n</address>\n"
+ "<labels>\n<item>\n...\n</item>\n</labels>\n</item>\n</orders>"
)
system_instructions = adapter.format_field_structure(TestSignature)
assert f"{order_schema}\n\n{orders_schema}" in system_instructions
- assert f"Use this nested XML structure: {order_schema} {orders_schema}" in (
- adapter.user_message_output_requirements(TestSignature)
+ assert adapter.user_message_output_requirements(TestSignature) == (
+ f"Output format (replace placeholders):\n{order_schema}\n\n{orders_schema}\n\n"
+ "Use this format for text outputs. Put field tags on separate lines. "
+ "Write string values literally, without XML or JSON escaping."
+ " Use <field/> for null and <field></field> for an empty string."
)
completion = (
@@ -242,7 +607,7 @@ def test_xml_adapter_recursive_model_schema_terminates():
root: Node = dspy.OutputField()
adapter = XMLAdapter()
- assert "<root><value>...</value><children><item>...</item></children></root>" in (
+ assert "<root>\n<value>\n...\n</value>\n<children>\n<item>\n...\n</item>\n</children>\n</root>" in (
adapter.format_field_structure(TestSignature)
)
completion = "<root><value>parent</value><children><value>child</value><children /></children></root>"
@@ -251,20 +616,6 @@ def test_xml_adapter_recursive_model_schema_terminates():
}
-def test_xml_adapter_escapes_closing_tags_and_rejects_malformed_xml():
- class TestSignature(dspy.Signature):
- code: str = dspy.OutputField()
-
- adapter = XMLAdapter()
- value = "print('</code> & done')"
- formatted = adapter.format_assistant_message_content(TestSignature, {"code": value})
- assert "&lt;/code> &amp; done" in formatted
- assert adapter.parse(TestSignature, formatted) == {"code": value}
-
- with pytest.raises(dspy.utils.exceptions.AdapterParseError, match="Failed to parse XML"):
- adapter.parse(TestSignature, "<code>print('</code>')</code>")
-
-
def test_xml_adapter_format_and_parse_nested_model():
class Address(pydantic.BaseModel):
city: str
@@ -283,7 +634,7 @@ def test_xml_adapter_format_and_parse_nested_model():
result = InnerModel(value=5, label="foo", address=Address(city="London"))
fields_with_values = {FieldInfoWithName(name="result", info=TestSignature.output_fields["result"]): result}
xml = adapter.format_field_with_value(fields_with_values)
- assert xml == "<result><value>5</value><label>foo</label><address><city>London</city></address></result>"
+ assert xml == "<result>\n<value>\n5\n</value>\n<label>\nfoo\n</label>\n<address>\n<city>\nLondon\n</city>\n</address>\n</result>"
assert adapter.parse(TestSignature, xml) == {"result": result}
# Legacy JSON values inside the outer XML field remain supported.
@@ -305,10 +656,15 @@ def test_xml_adapter_format_and_parse_list_of_models():
fields_with_values = {FieldInfoWithName(name="items", info=TestSignature.output_fields["items"]): items}
xml = adapter.format_field_with_value(fields_with_values)
assert xml == (
- "<items><item><name>a</name><score>1.1</score></item>"
- "<item><name>b</name><score>2.2</score></item></items>"
+ "<items>\n<item>\n<name>\na\n</name>\n<score>\n1.1\n</score>\n</item>\n"
+ "<item>\n<name>\nb\n</name>\n<score>\n2.2\n</score>\n</item>\n</items>"
)
assert adapter.parse(TestSignature, xml) == {"items": items}
+ # XML structure follows the declared fields, not Pydantic's extra-ignore policy.
+ for count in (1, 2):
+ with_extra = xml.replace("</name>", "</name>\n<extra>ignored</extra>", count)
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ adapter.parse(TestSignature, with_extra)
# Legacy JSON lists inside the outer XML field remain supported.
import json
@@ -342,8 +698,8 @@ def test_xml_adapter_with_tool_like_output():
}
xml = adapter.format_field_with_value(fields_with_values)
assert xml.strip().startswith("<tool_calls>")
- assert "<name>get_weather</name>" in xml
- assert "<result>125M</result>" in xml
+ assert "<name>\nget_weather\n</name>" in xml
+ assert "<result>\n125M\n</result>" in xml
assert xml.strip().endswith("</answer>")
import json
@@ -461,9 +817,7 @@ def test_xml_adapter_full_prompt():
f"2. `context` ({union_type_repr}):\n"
"Your output fields are:\n"
"1. `answer` (str):\n"
- "All interactions will be structured in the following way, with the appropriate values filled in.\n\n"
- "<query>\n{query}\n</query>\n\n"
- "<context>\n{context}\n</context>\n\n"
+ "Output format (replace placeholders):\n"
"<answer>\n{answer}\n</answer>\n"
"In adhering to this structure, your objective is: \n"
" Given the fields `query`, `context`, produce the fields `answer`."
@@ -471,13 +825,47 @@ def test_xml_adapter_full_prompt():
expected_user = (
"<query>\nwhen was Marie Curie born\n</query>\n\n"
- "Respond with the corresponding output fields wrapped in XML tags `<answer>`."
+ "Output format (replace placeholders):\n<answer>\n{answer}\n</answer>\n\n"
+ "Use this format for text outputs. Put field tags on separate lines. "
+ "Write string values literally, without XML or JSON escaping."
)
assert messages[0]["content"] == expected_system
assert messages[1]["content"] == expected_user
+def test_xml_adapter_native_only_outputs_do_not_request_text_fields():
+ class NativeLM(dspy.utils.DummyLM):
+ @property
+ def supports_function_calling(self):
+ return True
+
+ @property
+ def supports_reasoning(self):
+ return True
+
+ def search(query: str) -> str:
+ return query
+
+ class Agent(dspy.Signature):
+ question: str = dspy.InputField()
+ tools: list[dspy.Tool] = dspy.InputField()
+ thought: dspy.Reasoning = dspy.OutputField()
+ tool_calls: dspy.ToolCalls = dspy.OutputField()
+
+ messages, lm_kwargs = format_messages_and_lm_kwargs(
+ XMLAdapter(use_native_function_calling=True),
+ Agent,
+ [],
+ {"question": "Find cats", "tools": [dspy.Tool(search)]},
+ lm=NativeLM([{}]),
+ )
+ assert messages[-1]["content"] == "<question>\nFind cats\n</question>"
+ assert "Output format" not in messages[0]["content"]
+ assert lm_kwargs["tools"][0]["function"]["name"] == "search"
+ assert lm_kwargs["reasoning_effort"] == "low"
+
+
def test_xml_adapter_format_exact_messages_for_simple_signature():
class StringSignature(dspy.Signature):
question: str = dspy.InputField()
@@ -499,12 +887,7 @@ def test_xml_adapter_format_exact_messages_for_simple_signature():
1. `question` (str):
Your output fields are:
1. `answer` (str):
-All interactions will be structured in the following way, with the appropriate values filled in.
-
-<question>
-{question}
-</question>
-
+Output format (replace placeholders):
<answer>
{answer}
</answer>
@@ -517,7 +900,12 @@ In adhering to this structure, your objective is:\x20
why did a chicken cross the kitchen?
</question>
-Respond with the corresponding output fields wrapped in XML tags `<answer>`.""",
+Output format (replace placeholders):
+<answer>
+{answer}
+</answer>
+
+Use this format for text outputs. Put field tags on separate lines. Write string values literally, without XML or JSON escaping.""",
},
]
@@ -569,7 +957,15 @@ def test_xml_adapter_format_exact_non_native_tool_result_history_field():
'["search. It takes arguments {\'query\': {\'type\': \'string\'}}."]\n'
"</tools>\n"
"\n"
- "Respond with the corresponding output fields wrapped in XML tags `<next_thought>`, then `<tool_calls>`."
+ "Output format (replace placeholders):\n<next_thought>\n{next_thought}\n</next_thought>\n\n"
+ "<tool_calls>\n{tool_calls} # note: the value you produce must adhere to the JSON schema: "
+ '{"type": "object", "$defs": {"ToolCall": {"type": "object", "properties": {"args": '
+ '{"type": "object", "additionalProperties": true, "title": "Args"}, "name": {"type": "string", '
+ '"title": "Name"}}, "required": ["name", "args"], "title": "ToolCall"}}, "properties": '
+ '{"tool_calls": {"type": "array", "items": {"$ref": "#/$defs/ToolCall"}, "title": "Tool Calls"}}, '
+ '"required": ["tool_calls"], "title": "ToolCalls"}\n</tool_calls>\n\n'
+ "Use this format for text outputs. Put field tags on separate lines. "
+ "Write string values literally, without XML or JSON escaping."
)
@@ -596,16 +992,7 @@ def test_xml_adapter_format_exact_messages_for_two_input_signature():
2. `answer` (str):
Your output fields are:
1. `judgement` (str):
-All interactions will be structured in the following way, with the appropriate values filled in.
-
-<question>
-{question}
-</question>
-
-<answer>
-{answer}
-</answer>
-
+Output format (replace placeholders):
<judgement>
{judgement}
</judgement>
@@ -622,7 +1009,12 @@ why did a chicken cross the kitchen?
To get to the other side!
</answer>
-Respond with the corresponding output fields wrapped in XML tags `<judgement>`.""",
+Output format (replace placeholders):
+<judgement>
+{judgement}
+</judgement>
+
+Use this format for text outputs. Put field tags on separate lines. Write string values literally, without XML or JSON escaping.""",
},
]
@@ -650,18 +1042,13 @@ def test_xml_adapter_format_exact_messages_with_demo_and_typed_output():
Your output fields are:
1. `answer` (str):\x20
2. `score` (float):
-All interactions will be structured in the following way, with the appropriate values filled in.
-
-<question>
-{question}
-</question>
-
+Output format (replace placeholders):
<answer>
{answer}
</answer>
<score>
-{score} # note: the value you produce must be a single float value
+{score}
</score>
In adhering to this structure, your objective is:\x20
Given the fields `question`, produce the fields `answer`, `score`.""",
@@ -685,11 +1072,52 @@ A1
Q2
</question>
-Respond with the corresponding output fields wrapped in XML tags `<answer>`, then `<score>`.""",
+Output format (replace placeholders):
+<answer>
+{answer}
+</answer>
+
+<score>
+{score}
+</score>
+
+Use this format for text outputs. Put field tags on separate lines. Write string values literally, without XML or JSON escaping.""",
},
]
+def test_xml_adapter_long_history_preserves_turns_and_literals():
+ class Conversation(dspy.Signature):
+ history: dspy.History = dspy.InputField()
+ question: str = dspy.InputField()
+ answer: str = dspy.OutputField()
+ counts: dict[str, int] = dspy.OutputField()
+
+ turns = [
+ {
+ "question": f'Turn {i}: preserve <div data-id="{i}">R&B</div>.',
+ "answer": f"<section><p>雪 {i}</p><script>const x = {{n: {i}}};</script></section>",
+ "counts": {"turn": i, "balance": 17 - i},
+ }
+ for i in range(80)
+ ]
+ history = dspy.History(messages=turns)
+ original = history.model_dump()
+ adapter = XMLAdapter(use_json_adapter_fallback=False)
+ messages, _ = format_messages_and_lm_kwargs(
+ adapter, Conversation, demos=[turns[0]], inputs={"history": history, "question": "Current question"}
+ )
+ assert [m["role"] for m in messages] == ["system"] + ["user", "assistant"] * 81 + ["user"]
+ assert "Current question" in messages[-1]["content"]
+ for turn, user, assistant in zip(turns, messages[3:-1:2], messages[4:-1:2], strict=False):
+ assert user["content"].startswith(f'<question>\n{turn["question"]}\n</question>')
+ assert "<history>" not in user["content"]
+ assert adapter.parse(Conversation, assistant["content"]) == {
+ "answer": turn["answer"], "counts": turn["counts"]
+ }
+ assert history.model_dump() == original
+
+
def test_xml_adapter_format_exact_messages_with_history_demo_pydantic_tools_and_image():
def search(query: str, k: int = 3) -> str:
"""Search for documents."""
@@ -767,30 +1195,8 @@ def test_xml_adapter_format_exact_messages_with_history_demo_pydantic_tools_and_
"5. `question` (str):\n"
"Your output fields are:\n"
"1. `answer` (AnswerCard):\n"
- "All interactions will be structured in the following way, with the appropriate "
- "values filled in.\n"
- "\n"
- "<history>\n"
- "{history}\n"
- "</history>\n"
- "\n"
- "<image>\n"
- "{image}\n"
- "</image>\n"
- "\n"
- "<tools>\n"
- "{tools}\n"
- "</tools>\n"
- "\n"
- "<profile>\n"
- "{profile}\n"
- "</profile>\n"
- "\n"
- "<question>\n"
- "{question}\n"
- "</question>\n"
- "\n"
- "<answer><answer>...</answer><sources><item>...</item></sources></answer>\n"
+ "Output format (replace placeholders):\n"
+ "<answer>\n<answer>\n...\n</answer>\n<sources>\n<item>\n...\n</item>\n</sources>\n</answer>\n"
"In adhering to this structure, your objective is: \n"
" Answer using all supplied context."},
{"role": "user",
@@ -819,7 +1225,7 @@ def test_xml_adapter_format_exact_messages_with_history_demo_pydantic_tools_and_
'What should we mention?\n'
'</question>'}]},
{"role": "assistant",
- "content": "<answer><answer>Mention analytical engines.</answer><sources><item>demo</item></sources></answer>"},
+ "content": "<answer>\n<answer>\nMention analytical engines.\n</answer>\n<sources>\n<item>\ndemo\n</item>\n</sources>\n</answer>"},
{"role": "user",
"content": '<profile>\n'
'{"name": "Ada", "location": {"city": "London", "country": "UK"}, "interests": '
@@ -829,11 +1235,12 @@ def test_xml_adapter_format_exact_messages_with_history_demo_pydantic_tools_and_
'<question>\n'
'Who is Ada?\n'
'</question>\n\n'
- 'Respond with the corresponding output fields wrapped in XML tags `<answer>`. '
- 'Use this nested XML structure: '
- '<answer><answer>...</answer><sources><item>...</item></sources></answer>'},
+ 'Output format (replace placeholders):\n'
+ '<answer>\n<answer>\n...\n</answer>\n<sources>\n<item>\n...\n</item>\n</sources>\n</answer>\n\n'
+ 'Use this format for text outputs. Put field tags on separate lines. '
+ 'Write string values literally, without XML or JSON escaping.'},
{"role": "assistant",
- "content": "<answer><answer>Ada is a mathematician.</answer><sources><item>memory</item></sources></answer>"},
+ "content": "<answer>\n<answer>\nAda is a mathematician.\n</answer>\n<sources>\n<item>\nmemory\n</item>\n</sources>\n</answer>"},
{"role": "user",
"content": [{"type": "text", "text": "<image>\n"},
{"type": "image_url", "image_url": {"url": "https://example.com/current.png"}},
@@ -856,9 +1263,10 @@ def test_xml_adapter_format_exact_messages_with_history_demo_pydantic_tools_and_
'What should the answer include?\n'
'</question>\n'
'\n'
- 'Respond with the corresponding output fields wrapped in XML tags '
- '`<answer>`. Use this nested XML structure: '
- '<answer><answer>...</answer><sources><item>...</item></sources></answer>'}]}]
+ 'Output format (replace placeholders):\n'
+ '<answer>\n<answer>\n...\n</answer>\n<sources>\n<item>\n...\n</item>\n</sources>\n</answer>\n\n'
+ 'Use this format for text outputs. Put field tags on separate lines. '
+ 'Write string values literally, without XML or JSON escaping.'}]}]
assert messages == expected_messages
expected_lm_kwargs = {}
assert lm_kwargs == expected_lm_kwargs
@@ -883,15 +1291,9 @@ def test_xml_adapter_format_exact_messages_with_nested_pydantic_output():
"1. `question` (str):\n"
"Your output fields are:\n"
"1. `summary` (XmlSummary):\n"
- "All interactions will be structured in the following way, with the appropriate "
- "values filled in.\n"
- "\n"
- "<question>\n"
- "{question}\n"
- "</question>\n"
- "\n"
- "<summary><title>...</title><address><city>...</city><country>...</country>"
- "</address></summary>\n"
+ "Output format (replace placeholders):\n"
+ "<summary>\n<title>\n...\n</title>\n<address>\n<city>\n...\n</city>\n<country>\n...\n</country>\n"
+ "</address>\n</summary>\n"
"In adhering to this structure, your objective is: \n"
" Given the fields `question`, produce the fields `summary`."},
{"role": "user",
@@ -899,10 +1301,11 @@ def test_xml_adapter_format_exact_messages_with_nested_pydantic_output():
"Summarize\n"
"</question>\n"
"\n"
- "Respond with the corresponding output fields wrapped in XML tags `<summary>`. "
- "Use this nested XML structure: "
- "<summary><title>...</title><address><city>...</city><country>...</country>"
- "</address></summary>"}]
+ "Output format (replace placeholders):\n"
+ "<summary>\n<title>\n...\n</title>\n<address>\n<city>\n...\n</city>\n<country>\n...\n</country>\n"
+ "</address>\n</summary>\n\n"
+ "Use this format for text outputs. Put field tags on separate lines. "
+ "Write string values literally, without XML or JSON escaping."}]
assert messages == expected_messages
expected_lm_kwargs = {}
assert lm_kwargs == expected_lm_kwargs
@@ -928,23 +1331,13 @@ def test_xml_adapter_format_exact_messages_with_incomplete_demo():
"Your output fields are:\n"
"1. `answer` (str): \n"
"2. `score` (float):\n"
- "All interactions will be structured in the following way, with the appropriate "
- "values filled in.\n"
- "\n"
- "<question>\n"
- "{question}\n"
- "</question>\n"
- "\n"
- "<context>\n"
- "{context}\n"
- "</context>\n"
- "\n"
+ "Output format (replace placeholders):\n"
"<answer>\n"
"{answer}\n"
"</answer>\n"
"\n"
"<score>\n"
- "{score} # note: the value you produce must be a single float value\n"
+ "{score}\n"
"</score>\n"
"In adhering to this structure, your objective is: \n"
" Given the fields `question`, `context`, produce the fields `answer`, "
@@ -973,8 +1366,10 @@ def test_xml_adapter_format_exact_messages_with_incomplete_demo():
"C2\n"
"</context>\n"
"\n"
- "Respond with the corresponding output fields wrapped in XML tags `<answer>`, then "
- "`<score>`."}]
+ "Output format (replace placeholders):\n<answer>\n{answer}\n</answer>\n\n"
+ "<score>\n{score}\n</score>\n\n"
+ "Use this format for text outputs. Put field tags on separate lines. "
+ "Write string values literally, without XML or JSON escaping."}]
assert messages == expected_messages
expected_lm_kwargs = {}
assert lm_kwargs == expected_lm_kwargs
@@ -996,15 +1391,18 @@ def test_format_system_message():
Your output fields are:
1. `answers` (list[str]):\x20
2. `scores` (list[float]):
-All interactions will be structured in the following way, with the appropriate values filled in.
-
-<question>
-{question}
-</question>
-
-<answers><item>...</item></answers>
-
-<scores><item>...</item></scores>
+Output format (replace placeholders):
+<answers>
+<item>
+...
+</item>
+</answers>
+
+<scores>
+<item>
+...
+</item>
+</scores>
In adhering to this structure, your objective is:\x20
Answer the question with multiple answers and scores"""
assert system_message == expected_system_message
diff --git a/tests/streaming/test_streaming.py b/tests/streaming/test_streaming.py
index 210f1b33e..505dff4ab 100644
--- a/tests/streaming/test_streaming.py
+++ b/tests/streaming/test_streaming.py
@@ -947,7 +947,8 @@ async def test_status_message_non_blocking_async_program():
@pytest.mark.anyio
-async def test_stream_listener_allow_reuse():
[email protected]("adapter", [dspy.ChatAdapter(), dspy.XMLAdapter(use_json_adapter_fallback=False)])
+async def test_stream_listener_allow_reuse(adapter):
class MyProgram(dspy.Module):
def __init__(self):
super().__init__()
@@ -965,6 +966,13 @@ async def test_stream_listener_allow_reuse():
)
async def gpt_4o_mini_stream(*args, **kwargs):
+ if isinstance(adapter, dspy.XMLAdapter):
+ response = "```xml\n<answer>\nTo get to the other side!\n</answer>\n```"
+ for start in range(0, len(response), 7):
+ yield ModelResponseStream(
+ model="gpt-4o-mini", choices=[StreamingChoices(delta=Delta(content=response[start:start + 7]))]
+ )
+ return
# Recorded streaming from openai/gpt-4o-mini
yield ModelResponseStream(model="gpt-4o-mini", choices=[StreamingChoices(delta=Delta(content="[["))])
yield ModelResponseStream(model="gpt-4o-mini", choices=[StreamingChoices(delta=Delta(content=" ##"))])
@@ -988,7 +996,7 @@ async def test_stream_listener_allow_reuse():
return stream_generators.pop(0)() # return new async generator instance
with mock.patch("litellm.acompletion", side_effect=completion_side_effect):
- with dspy.context(lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False)):
+ with dspy.context(lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False), adapter=adapter):
output = program(question="why did a chicken cross the kitchen?")
all_chunks = []
async for value in output:
@@ -1074,6 +1082,295 @@ async def test_stream_listener_returns_correct_chunk_xml_adapter():
assert "".join([chunk.chunk for chunk in judgement_chunks]) == "The answer is humorous."
[email protected]("chunk_size", [1, 7, 1000])
[email protected]("terminal_content", [False, True])
+ "response, expected",
+ [
+ (
+ '<answer>\n if a < b:\n print("</answer>", "&amp;") \n\n</answer>',
+ ' if a < b:\n print("</answer>", "&amp;") \n',
+ ),
+ (
+ "<answer>\r\n\r\n </answer> is literal & text\r\n end \r\n</answer>\r\n",
+ "\r\n </answer> is literal & text\r\n end ",
+ ),
+ ("<answer> compact < &amp; text </answer>", "compact < &amp; text"),
+ ("<answer>print('</answer>')</answer>", "print('</answer>')"),
+ (
+ "<answer>\nx = '''\n</answer>\nR&B\n'''\n</answer>",
+ "x = '''\n</answer>\nR&B\n'''",
+ ),
+ ("<answer>\n\n</answer>", ""),
+ ("<answer>\n```python\nSUBMIT(1353, 5)\n```</answer>", "```python\nSUBMIT(1353, 5)\n```"),
+ ("<answer>\r\nR&B &amp; 雪</answer>\r\n", "R&B &amp; 雪"),
+ (
+ "<think>Ignore <answer>wrong</answer>.</think>\n<thinking>Check again.</thinking>\n"
+ "<answer>\nKeep <think>literal</think> text</answer>",
+ "Keep <think>literal</think> text",
+ ),
+ (
+ "```xml\n<think>Ignore <answer>wrong</answer>.</think>\n<answer>\nright\n</answer>\n```",
+ "right",
+ ),
+ (
+ "<think>Ignore <answer>wrong</answer>.</think>\n```xml\n<answer>\nright\n</answer>\n```",
+ "right",
+ ),
+ (
+ "<think>outer</think>\n```xml\n<think><answer>wrong</answer></think>\n"
+ "<answer>\nright\n</answer>\n```",
+ "right",
+ ),
+ ("Here is the result:\n\n<answer>\nR&B &amp; 雪\n</answer>", "R&B &amp; 雪"),
+ ("<answer>Paris</answer>\n\nLet me know if you need anything else.", "Paris"),
+ ("<answer> \r\n Paris \r\n </answer> \r\nThanks!", " Paris "),
+ ("<answer>\n\n</answer>\nThanks!", ""),
+ (
+ "<answer>\nx = '''\n</answer>\nR&B\n'''\n</answer>\nLet me know if you need anything else.",
+ "x = '''\n</answer>\nR&B\n'''",
+ ),
+ (
+ "<think>Check.</think>\n```xml\n<answer>\nParis\n</answer>\n```\nThanks!",
+ "Paris",
+ ),
+ (
+ '<answer>\n<html><style>.a { color: red; }</style>\n'
+ '<body><div><div>R&B &amp; 雪</div></div><script>const x = {tag: "</answer>"};</script></body>\n'
+ '</html></answer>',
+ '<html><style>.a { color: red; }</style>\n'
+ '<body><div><div>R&B &amp; 雪</div></div><script>const x = {tag: "</answer>"};</script></body>\n'
+ '</html>',
+ ),
+ ],
+)
+async def test_xml_stream_preserves_literal_text(response, expected, chunk_size, terminal_content):
+ program = dspy.streamify(
+ dspy.Predict("question->answer"),
+ stream_listeners=[dspy.streaming.StreamListener(signature_field_name="answer", allow_reuse=True)],
+ )
+
+ async def stream(*args, **kwargs):
+ for start in range(0, len(response), chunk_size):
+ yield ModelResponseStream(
+ model="gpt-4o-mini",
+ choices=[StreamingChoices(
+ delta=Delta(content=response[start : start + chunk_size]),
+ finish_reason="stop" if terminal_content and start + chunk_size >= len(response) else None,
+ )],
+ )
+
+ with mock.patch("litellm.acompletion", side_effect=stream):
+ with dspy.context(
+ lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False),
+ adapter=dspy.XMLAdapter(use_json_adapter_fallback=False),
+ ):
+ for _ in range(2):
+ values = [value async for value in program(question="Copy the text verbatim.")]
+ chunks = [value for value in values if isinstance(value, dspy.streaming.StreamResponse)]
+ assert values[-1].answer == expected
+ assert "".join(chunk.chunk for chunk in chunks) == expected
+ assert sum(chunk.is_last_chunk for chunk in chunks) == 1
+ if expected and chunk_size == 1:
+ assert len(chunks) > 2 # Emit text incrementally, not just once at the closing tag.
+
+
[email protected]("chunk_size", [1, 7, 1000])
[email protected]("finish_reason", [None, "stop"])
+async def test_xml_stream_recovers_html_without_consuming_following_field(chunk_size, finish_reason):
+ class Page(dspy.Signature):
+ html: str = dspy.OutputField()
+ count: int = dspy.OutputField()
+ note: str = dspy.OutputField()
+
+ html = "<!DOCTYPE html>\n<html><body>R&B &amp; 雪 <count/> <count>wrong</count></body>\n</html>"
+ note = "A later field can also mention\n</html>"
+ response = f"<html>\n{html}\n</html>\n<count>2</count>\n<note>\n{note}\n</note>\nHope this helps!"
+
+ async def stream(*args, **kwargs):
+ for start in range(0, len(response), chunk_size):
+ yield ModelResponseStream(
+ model="gpt-4o-mini",
+ choices=[StreamingChoices(delta=Delta(content=response[start : start + chunk_size]))],
+ )
+ if finish_reason:
+ yield ModelResponseStream(
+ model="gpt-4o-mini",
+ choices=[StreamingChoices(delta=Delta(), finish_reason=finish_reason)],
+ )
+
+ program = dspy.streamify(
+ dspy.Predict(Page),
+ stream_listeners=[
+ dspy.streaming.StreamListener(signature_field_name=name) for name in ("html", "count", "note")
+ ],
+ )
+ with mock.patch("litellm.acompletion", side_effect=stream):
+ with dspy.context(
+ lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False),
+ adapter=dspy.XMLAdapter(use_json_adapter_fallback=False),
+ ):
+ values = [value async for value in program()]
+ assert values[-1].html == html
+ assert values[-1].count == 2
+ assert values[-1].note == note
+ for name, expected in [("html", html), ("count", "2"), ("note", note)]:
+ chunks = [v for v in values if isinstance(v, dspy.streaming.StreamResponse) and v.signature_field_name == name]
+ assert "".join(c.chunk for c in chunks) == expected
+ assert sum(c.is_last_chunk for c in chunks) == 1
+
+
[email protected]("chunk_size", [1, 7, 1000])
[email protected]("variant", ["model", "union", "joined_close", "unknown_field", "literal_close"])
+async def test_xml_stream_skips_nested_fields_with_top_level_names(chunk_size, variant):
+ class Meta(pydantic.BaseModel):
+ meta: str
+ answer: str
+
+ class Result(dspy.Signature):
+ meta: Meta = dspy.OutputField()
+ answer: str = dspy.OutputField()
+
+ expected = {"meta": Meta(meta="inner", answer="wrong"), "answer": "right"}
+ if variant == "literal_close":
+ expected["meta"].meta = "inner\n</meta>\nmore"
+ adapter = dspy.XMLAdapter(use_json_adapter_fallback=False)
+ response = adapter.format_assistant_message_content(Result, expected)
+ signature = Result
+ if variant == "union":
+ signature = Result.with_updated_fields("meta", type_=Meta | str)
+ elif variant == "joined_close":
+ response = response.replace("</meta>\n\n<answer>", "</meta><answer>")
+ elif variant == "unknown_field":
+ response = response.replace("inner\n</meta>", "inner\n</meta>\n<extra>ignored</extra>")
+
+ async def stream(*args, **kwargs):
+ for start in range(0, len(response), chunk_size):
+ yield ModelResponseStream(choices=[StreamingChoices(delta=Delta(content=response[start:start + chunk_size]))])
+
+ program = dspy.streamify(dspy.Predict(signature), stream_listeners=[dspy.streaming.StreamListener("answer")])
+ with mock.patch("litellm.acompletion", side_effect=stream):
+ with dspy.context(lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False), adapter=adapter):
+ if variant == "unknown_field":
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ _ = [value async for value in program()]
+ return
+ values = [value async for value in program()]
+ assert values[-1].meta == expected["meta"]
+ assert values[-1].answer == "right"
+ assert "".join(v.chunk for v in values if isinstance(v, StreamResponse)) == "right"
+
+
[email protected]("chunk_size", [1, 7, 1000])
[email protected]("compact", [False, True])
[email protected]("variant", ["valid", "missing_close", "extra_first"])
+async def test_xml_stream_preserves_list_item_boundaries(chunk_size, compact, variant):
+ class Item(pydantic.BaseModel):
+ name: str
+ score: float
+
+ class Result(dspy.Signature):
+ rows: list[Item] = dspy.OutputField()
+ answer: str = dspy.OutputField()
+
+ rows = [Item(name="a", score=1.1), Item(name="b", score=2.2)]
+ adapter = dspy.XMLAdapter(use_json_adapter_fallback=False)
+ response = adapter.format_assistant_message_content(Result, {"rows": rows, "answer": "right"})
+ if variant == "missing_close":
+ response = response.replace("</name>", "", 1)
+ elif variant == "extra_first":
+ response = response.replace("</name>", "</name>\n<extra>ignored</extra>", 1)
+ if compact:
+ response = response.replace("\n", "")
+ response += "\nLet me know if you need anything else."
+
+ async def stream(*args, **kwargs):
+ for start in range(0, len(response), chunk_size):
+ yield ModelResponseStream(choices=[StreamingChoices(delta=Delta(content=response[start:start + chunk_size]))])
+
+ program = dspy.streamify(dspy.Predict(Result), stream_listeners=[dspy.streaming.StreamListener("answer")])
+ with mock.patch("litellm.acompletion", side_effect=stream):
+ with dspy.context(lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False), adapter=adapter):
+ if variant != "valid":
+ with pytest.raises(dspy.utils.exceptions.AdapterParseError):
+ _ = [value async for value in program()]
+ return
+ values = [value async for value in program()]
+ assert values[-1].rows == rows
+ assert values[-1].answer == "right"
+ assert "".join(v.chunk for v in values if isinstance(v, StreamResponse)) == "right"
+
+
+async def test_xml_stream_reuse_after_native_reasoning():
+ class Twice(dspy.Module):
+ def __init__(self):
+ super().__init__()
+ self.predict = dspy.ChainOfThought("->answer")
+
+ def forward(self):
+ self.predict()
+ return self.predict(config={"reasoning_effort": None})
+
+ turns = iter([
+ [Delta(reasoning_content="native thought"), Delta(content="<answer>one</answer>")],
+ [Delta(content="<plan>fallback thought</plan><answer>two</answer>")],
+ ])
+
+ async def stream(*args, **kwargs):
+ for delta in next(turns):
+ yield ModelResponseStream(choices=[StreamingChoices(delta=delta)])
+
+ program = dspy.streamify(Twice(), stream_listeners=[dspy.streaming.StreamListener("reasoning", allow_reuse=True)])
+ with (
+ mock.patch("litellm.acompletion", side_effect=stream),
+ mock.patch("litellm.supports_reasoning", return_value=True),
+ dspy.context(
+ lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False),
+ adapter=dspy.XMLAdapter(use_json_adapter_fallback=False),
+ ),
+ ):
+ values = [value async for value in program()]
+ assert values[-1].reasoning == "fallback thought"
+ assert values[-1].answer == "two"
+ assert "".join(v.chunk for v in values if isinstance(v, StreamResponse)) == "native thoughtfallback thought"
+
+
+async def test_xml_stream_native_tools_ignore_incomplete_accompanying_thought():
+ class Result(dspy.Signature):
+ tools: list[dspy.Tool] = dspy.InputField()
+ answer: str = dspy.OutputField()
+ calls: dspy.ToolCalls = dspy.OutputField()
+
+ def search(query: str) -> str:
+ return query
+
+ call = {"index": 0, "id": "c1", "type": "function", "function": {"name": "search", "arguments": '{"query":"test"}'}}
+
+ async def stream(*args, **kwargs):
+ yield ModelResponseStream(choices=[StreamingChoices(delta=Delta(content="<think>Need to search"))])
+ yield ModelResponseStream(choices=[StreamingChoices(delta=Delta(tool_calls=[call]), finish_reason="tool_calls")])
+
+ program = dspy.streamify(dspy.Predict(Result), stream_listeners=[dspy.streaming.StreamListener("answer")])
+ with (
+ mock.patch("litellm.acompletion", side_effect=stream),
+ mock.patch("litellm.supports_function_calling", return_value=True),
+ dspy.context(
+ lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False),
+ adapter=dspy.XMLAdapter(use_json_adapter_fallback=False, use_native_function_calling=True),
+ ),
+ ):
+ values = [value async for value in program(tools=[dspy.Tool(search)])]
+ assert not any(isinstance(value, StreamResponse) for value in values)
+ assert values[-1].calls.tool_calls[0].name == "search"
+ assert values[-1].calls.tool_calls[0].args == {"query": "test"}
+
+
@pytest.mark.anyio
async def test_streaming_allows_custom_chunk_types():
@dataclass
@@ -2203,6 +2500,33 @@ async def test_default_cot_fallback_streams_reasoning(adapter_type, mode):
assert values[-1].answer == "17"
+async def test_xml_streaming_recognizes_a_renamed_reasoning_sibling():
+ # Output order may differ from the prompt; `plan` is the adapter's wire name.
+ text = "<answer>17</answer><plan>Count the signed items.</plan>"
+
+ async def stream(*args, **kwargs):
+ for offset in range(0, len(text), 4):
+ yield ModelResponseStream(choices=[StreamingChoices(delta=Delta(content=text[offset : offset + 4]))])
+
+ program = dspy.streamify(
+ dspy.ChainOfThought("question -> answer"),
+ stream_listeners=[dspy.streaming.StreamListener(name) for name in ("answer", "reasoning")],
+ )
+ with (
+ mock.patch("litellm.supports_reasoning", return_value=False),
+ mock.patch("litellm.acompletion", side_effect=stream),
+ dspy.context(lm=dspy.LM("openai/gpt-4o-mini", engine="litellm", cache=False), adapter=dspy.XMLAdapter()),
+ ):
+ values = [value async for value in program(question="Count items")]
+ for name, expected in {"answer": "17", "reasoning": "Count the signed items."}.items():
+ chunks = [
+ value.chunk for value in values if isinstance(value, StreamResponse) and value.signature_field_name == name
+ ]
+ assert "".join(chunks) == expected
+ assert getattr(values[-1], name) == expected
+
+
def test_streamify_keeps_a_group_of_several_failures():
import builtins