From fbfe15e5eb60b454b28458079a61d7af1001977e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Oct 2025 14:42:17 +0000 Subject: [PATCH] docs: Add XMLAdapter documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive documentation for XMLAdapter to both the main adapters guide and API reference. Changes: - Add XMLAdapter section to docs/docs/learn/programming/adapters.md - Format structure with example usage - When to use and when not to use guidance - Complete example with expected output - Create docs/docs/api/adapters/XMLAdapter.md for API reference - Update adapter types overview with XMLAdapter mention XMLAdapter has been in the codebase since August 2025 but was missing from documentation. This fills that gap. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/docs/api/adapters/XMLAdapter.md | 31 +++++++ docs/docs/learn/programming/adapters.md | 115 ++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 docs/docs/api/adapters/XMLAdapter.md diff --git a/docs/docs/api/adapters/XMLAdapter.md b/docs/docs/api/adapters/XMLAdapter.md new file mode 100644 index 0000000000..118a20024b --- /dev/null +++ b/docs/docs/api/adapters/XMLAdapter.md @@ -0,0 +1,31 @@ +# dspy.XMLAdapter + + +::: dspy.XMLAdapter + handler: python + options: + members: + - __call__ + - acall + - format + - format_assistant_message_content + - format_conversation_history + - format_demos + - format_field_description + - format_field_structure + - format_field_with_value + - format_finetune_data + - format_task_description + - format_user_message_content + - parse + - user_message_output_requirements + show_source: true + show_root_heading: true + heading_level: 2 + docstring_style: google + show_root_full_path: true + show_object_full_path: false + separate_signature: false + inherited_members: true +::: + diff --git a/docs/docs/learn/programming/adapters.md b/docs/docs/learn/programming/adapters.md index e096863d61..6d381d5d20 100644 --- a/docs/docs/learn/programming/adapters.md +++ b/docs/docs/learn/programming/adapters.md @@ -78,6 +78,10 @@ The output should resemble: DSPy offers several adapter types, each tailored for specific use cases: +- **ChatAdapter**: Uses `[[ ## field ## ]]` markers (default, universal compatibility) +- **JSONAdapter**: Uses JSON format (optimal for structured output models) +- **XMLAdapter**: Uses `` XML tags (ideal for XML-native systems) + ### ChatAdapter **ChatAdapter** is the default adapter and works with all language models. It uses a field-based format with special markers. @@ -301,6 +305,117 @@ Avoid using `JSONAdapter` if you are: - Using a model that does not natively support structured output, such as a small open-source model hosted on Ollama. +### XMLAdapter + +**XMLAdapter** formats inputs and outputs using XML tags, providing a clean structured format that some models and systems prefer. It wraps each field in opening and closing XML tags (e.g., `value`). + +#### Format Structure + +XMLAdapter uses XML tags to delineate fields. Like other adapters, it includes JSON schema information for complex types. Below is an example using the same signature: + +```python +import dspy +import pydantic + +dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"), adapter=dspy.XMLAdapter()) + + +class ScienceNews(pydantic.BaseModel): + text: str + scientists_involved: list[str] + + +class NewsQA(dspy.Signature): + """Get news about the given science field""" + + science_field: str = dspy.InputField() + year: int = dspy.InputField() + num_of_outputs: int = dspy.InputField() + news: list[ScienceNews] = dspy.OutputField(desc="science news") + + +predict = dspy.Predict(NewsQA) +predict(science_field="Computer Theory", year=2022, num_of_outputs=1) +dspy.inspect_history() +``` + +The output looks like: + +``` +System message: + +Your input fields are: +1. `science_field` (str): +2. `year` (int): +3. `num_of_outputs` (int): +Your output fields are: +1. `news` (list[ScienceNews]): science news +All interactions will be structured in the following way, with the appropriate values filled in. + + +{science_field} + + + +{year} + + + +{num_of_outputs} + + + +{news} # note: the value you produce must adhere to the JSON schema: {"type": "array", "$defs": {"ScienceNews": {"type": "object", "properties": {"scientists_involved": {"type": "array", "items": {"type": "string"}, "title": "Scientists Involved"}, "text": {"type": "string", "title": "Text"}}, "required": ["text", "scientists_involved"], "title": "ScienceNews"}}, "items": {"$ref": "#/$defs/ScienceNews"}} + + + +User message: + + +Computer Theory + + + +2022 + + + +1 + + +Respond with the corresponding output fields wrapped in XML tags ``. + + +Response: + + +[ + { + "text": "In 2022, researchers made significant advancements in quantum computing algorithms, demonstrating that quantum systems can outperform classical computers in specific tasks.", + "scientists_involved": [ + "Dr. Alice Smith", + "Dr. Bob Johnson" + ] + } +] + +``` + +#### When to Use XMLAdapter + +`XMLAdapter` is ideal when: + +- **XML-native systems**: Your application or downstream systems expect XML format. +- **Model preference**: Some models are trained with XML-structured prompts and may perform better with XML formatting. +- **Clean structure**: You want a format that's human-readable with clear opening/closing tags. + +#### When Not to Use XMLAdapter + +Avoid using `XMLAdapter` if you are: + +- **Latency sensitive**: Like `ChatAdapter`, `XMLAdapter` includes boilerplate in the output. If minimizing tokens is critical, consider `JSONAdapter`. +- **Working with JSON-native models**: Models optimized for JSON structured output will work better with `JSONAdapter`. + ## Summary Adapters are a crucial component of DSPy that bridge the gap between structured DSPy signatures and language model APIs.