Skip to content

armgit / dspy

Public Imported from GitHub
0

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

Python

Add Anthropic Citation API support (#8721)

TomuHiratab4b9babcb31f
diff --git a/dspy/adapters/base.py b/dspy/adapters/base.py
index eaea79563..f714b338b 100644
--- a/dspy/adapters/base.py
+++ b/dspy/adapters/base.py
@@ -7,6 +7,7 @@ import litellm
from dspy.adapters.types import History
from dspy.adapters.types.base_type import split_message_content_for_custom_types
from dspy.adapters.types.tool import Tool, ToolCalls
+from dspy.experimental import Citations
from dspy.signatures.signature import Signature
from dspy.utils.callback import BaseCallback, with_callbacks
@@ -63,6 +64,10 @@ class Adapter:
return signature_for_native_function_calling
+ citation_output_field_name = self._get_citation_output_field_name(signature)
+ if citation_output_field_name:
+ signature = signature.delete(citation_output_field_name)
+
return signature
def _call_postprocess(
@@ -74,16 +79,19 @@ class Adapter:
values = []
tool_call_output_field_name = self._get_tool_call_output_field_name(original_signature)
+ citation_output_field_name = self._get_citation_output_field_name(original_signature)
for output in outputs:
output_logprobs = None
tool_calls = None
+ citations = None
text = output
if isinstance(output, dict):
text = output["text"]
output_logprobs = output.get("logprobs")
tool_calls = output.get("tool_calls")
+ citations = output.get("citations")
if text:
value = self.parse(processed_signature, text)
@@ -106,6 +114,10 @@ class Adapter:
]
value[tool_call_output_field_name] = ToolCalls.from_dict_list(tool_calls)
+ if citations and citation_output_field_name:
+ citations_obj = Citations.from_dict_list(citations)
+ value[citation_output_field_name] = citations_obj
+
if output_logprobs:
value["logprobs"] = output_logprobs
@@ -390,6 +402,13 @@ class Adapter:
return name
return None
+ def _get_citation_output_field_name(self, signature: type[Signature]) -> str | None:
+ """Find the Citations output field in the signature."""
+ for name, field in signature.output_fields.items():
+ if field.annotation == Citations:
+ return name
+ return None
+
def format_conversation_history(
self,
signature: type[Signature],
diff --git a/dspy/adapters/types/citation.py b/dspy/adapters/types/citation.py
new file mode 100644
index 000000000..b3c613c07
--- /dev/null
+++ b/dspy/adapters/types/citation.py
@@ -0,0 +1,168 @@
+from typing import Any
+
+import pydantic
+
+from dspy.adapters.types.base_type import Type
+from dspy.utils.annotation import experimental
+
+
+@experimental(version="3.0.4")
+class Citations(Type):
+ """Citations extracted from an LM response with source references.
+
+ This type represents citations returned by language models that support
+ citation extraction, particularly Anthropic's Citations API through LiteLLM.
+ Citations include the quoted text and source information.
+
+ Example:
+ ```python
+ import dspy
+ from dspy.signatures import Signature
+ from dspy.experimental import Citations, Document
+
+ class AnswerWithSources(Signature):
+ '''Answer questions using provided documents with citations.'''
+ documents: list[Document] = dspy.InputField()
+ question: str = dspy.InputField()
+ answer: str = dspy.OutputField()
+ citations: Citations = dspy.OutputField()
+
+ # Create documents to provide as sources
+ docs = [
+ Document(
+ data="The Earth orbits the Sun in an elliptical path.",
+ title="Basic Astronomy Facts"
+ ),
+ Document(
+ data="Water boils at 100°C at standard atmospheric pressure.",
+ title="Physics Fundamentals",
+ metadata={"author": "Dr. Smith", "year": 2023}
+ )
+ ]
+
+ # Use with a model that supports citations like Claude
+ lm = dspy.LM("anthropic/claude-opus-4-1-20250805")
+ predictor = dspy.Predict(AnswerWithSources, lm=lm)
+ result = predictor(documents=docs, question="What temperature does water boil?")
+
+ for citation in result.citations.citations:
+ print(citation.format())
+ ```
+ """
+
+ class Citation(Type):
+ """Individual citation with character location information."""
+ type: str = "char_location"
+ cited_text: str
+ document_index: int
+ document_title: str | None = None
+ start_char_index: int
+ end_char_index: int
+ supported_text: str | None = None
+
+ def format(self) -> dict[str, Any]:
+ """Format citation as dictionary for LM consumption.
+
+ Returns:
+ A dictionary in the format expected by citation APIs.
+ """
+ citation_dict = {
+ "type": self.type,
+ "cited_text": self.cited_text,
+ "document_index": self.document_index,
+ "start_char_index": self.start_char_index,
+ "end_char_index": self.end_char_index
+ }
+
+ if self.document_title:
+ citation_dict["document_title"] = self.document_title
+
+ if self.supported_text:
+ citation_dict["supported_text"] = self.supported_text
+
+ return citation_dict
+
+ citations: list[Citation]
+
+ @classmethod
+ def from_dict_list(cls, citations_dicts: list[dict[str, Any]]) -> "Citations":
+ """Convert a list of dictionaries to a Citations instance.
+
+ Args:
+ citations_dicts: A list of dictionaries, where each dictionary should have 'cited_text' key
+ and 'document_index', 'start_char_index', 'end_char_index' keys.
+
+ Returns:
+ A Citations instance.
+
+ Example:
+ ```python
+ citations_dict = [
+ {
+ "cited_text": "The sky is blue",
+ "document_index": 0,
+ "document_title": "Weather Guide",
+ "start_char_index": 0,
+ "end_char_index": 15,
+ "supported_text": "The sky was blue yesterday."
+ }
+ ]
+ citations = Citations.from_dict_list(citations_dict)
+ ```
+ """
+ citations = [cls.Citation(**item) for item in citations_dicts]
+ return cls(citations=citations)
+
+ @classmethod
+ def description(cls) -> str:
+ """Description of the citations type for use in prompts."""
+ return (
+ "Citations with quoted text and source references. "
+ "Include the exact text being cited and information about its source."
+ )
+
+ def format(self) -> list[dict[str, Any]]:
+ """Format citations as a list of dictionaries."""
+ return [citation.format() for citation in self.citations]
+
+ @pydantic.model_validator(mode="before")
+ @classmethod
+ def validate_input(cls, data: Any):
+ if isinstance(data, cls):
+ return data
+
+ # Handle case where data is a list of dicts with citation info
+ if isinstance(data, list) and all(
+ isinstance(item, dict) and "cited_text" in item for item in data
+ ):
+ return {"citations": [cls.Citation(**item) for item in data]}
+
+ # Handle case where data is a dict
+ elif isinstance(data, dict):
+ if "citations" in data:
+ # Handle case where data is a dict with "citations" key
+ citations_data = data["citations"]
+ if isinstance(citations_data, list):
+ return {
+ "citations": [
+ cls.Citation(**item) if isinstance(item, dict) else item
+ for item in citations_data
+ ]
+ }
+ elif "cited_text" in data:
+ # Handle case where data is a single citation dict
+ return {"citations": [cls.Citation(**data)]}
+
+ raise ValueError(f"Received invalid value for `Citations`: {data}")
+
+ def __iter__(self):
+ """Allow iteration over citations."""
+ return iter(self.citations)
+
+ def __len__(self):
+ """Return the number of citations."""
+ return len(self.citations)
+
+ def __getitem__(self, index):
+ """Allow indexing into citations."""
+ return self.citations[index]
diff --git a/dspy/adapters/types/document.py b/dspy/adapters/types/document.py
new file mode 100644
index 000000000..cd492a6ff
--- /dev/null
+++ b/dspy/adapters/types/document.py
@@ -0,0 +1,114 @@
+from typing import Any, Literal
+
+import pydantic
+
+from dspy.adapters.types.base_type import Type
+from dspy.utils.annotation import experimental
+
+
+@experimental(version="3.0.4")
+class Document(Type):
+ """A document type for providing content that can be cited by language models.
+
+ This type represents documents that can be passed to language models for citation-enabled
+ responses, particularly useful with Anthropic's Citations API. Documents include the content
+ and metadata that helps the LM understand and reference the source material.
+
+ Attributes:
+ data: The text content of the document
+ title: Optional title for the document (used in citations)
+ media_type: MIME type of the document content (defaults to "text/plain")
+ context: Optional context information about the document
+
+ Example:
+ ```python
+ import dspy
+ from dspy.signatures import Signature
+ from dspy.experimental import Document, Citations
+
+ class AnswerWithSources(Signature):
+ '''Answer questions using provided documents with citations.'''
+ documents: list[Document] = dspy.InputField()
+ question: str = dspy.InputField()
+ answer: str = dspy.OutputField()
+ citations: Citations = dspy.OutputField()
+
+ # Create documents
+ docs = [
+ Document(
+ data="The Earth orbits the Sun in an elliptical path.",
+ title="Basic Astronomy Facts"
+ ),
+ Document(
+ data="Water boils at 100°C at standard atmospheric pressure.",
+ title="Physics Fundamentals",
+ )
+ ]
+
+ # Use with a citation-supporting model
+ lm = dspy.LM("anthropic/claude-opus-4-1-20250805")
+ predictor = dspy.Predict(AnswerWithSources)
+ result = predictor(documents=docs, question="What temperature does water boil?", lm=lm)
+ print(result.citations)
+ ```
+ """
+
+ data: str
+ title: str | None = None
+ media_type: Literal["text/plain", "application/pdf"] = "text/plain"
+ context: str | None = None
+
+ def format(self) -> list[dict[str, Any]]:
+ """Format document for LM consumption.
+
+ Returns:
+ A list containing the document block in the format expected by citation-enabled language models.
+ """
+ document_block = {
+ "type": "document",
+ "source": {
+ "type": "text",
+ "media_type": self.media_type,
+ "data": self.data
+ },
+ "citations": {"enabled": True}
+ }
+
+ if self.title:
+ document_block["title"] = self.title
+
+ if self.context:
+ document_block["context"] = self.context
+
+ return [document_block]
+
+
+
+ @classmethod
+ def description(cls) -> str:
+ """Description of the document type for use in prompts."""
+ return (
+ "A document containing text content that can be referenced and cited. "
+ "Include the full text content and optionally a title for proper referencing."
+ )
+
+ @pydantic.model_validator(mode="before")
+ @classmethod
+ def validate_input(cls, data: Any):
+ if isinstance(data, cls):
+ return data
+
+ # Handle case where data is just a string (data only)
+ if isinstance(data, str):
+ return {"data": data}
+
+ # Handle case where data is a dict
+ elif isinstance(data, dict):
+ return data
+
+ raise ValueError(f"Received invalid value for `Document`: {data}")
+
+ def __str__(self) -> str:
+ """String representation showing title and content length."""
+ title_part = f"'{self.title}': " if self.title else ""
+ return f"Document({title_part}{len(self.data)} chars)"
diff --git a/dspy/clients/base_lm.py b/dspy/clients/base_lm.py
index 6f86da563..68fc43cf7 100644
--- a/dspy/clients/base_lm.py
+++ b/dspy/clients/base_lm.py
@@ -183,6 +183,12 @@ class BaseLM:
output["logprobs"] = c.logprobs if hasattr(c, "logprobs") else c["logprobs"]
if hasattr(c, "message") and getattr(c.message, "tool_calls", None):
output["tool_calls"] = c.message.tool_calls
+
+ # Extract citations from LiteLLM response if available
+ citations = self._extract_citations_from_response(c)
+ if citations:
+ output["citations"] = citations
+
outputs.append(output)
if all(len(output) == 1 for output in outputs):
@@ -191,6 +197,24 @@ class BaseLM:
return outputs
+ def _extract_citations_from_response(self, choice):
+ """Extract citations from LiteLLM response if available.
+ Reference: https://docs.litellm.ai/docs/providers/anthropic#beta-citations-api
+
+ Args:
+ choice: The choice object from response.choices
+
+ Returns:
+ A list of citation dictionaries or None if no citations found
+ """
+ try:
+ # Check for citations in LiteLLM provider_specific_fields
+ citations_data = choice.message.provider_specific_fields.get("citations")
+ if isinstance(citations_data, list):
+ return [citation for citations in citations_data for citation in citations]
+ except Exception:
+ return None
+
def _process_response(self, response):
"""Process the response of OpenAI Response API and extract outputs.
diff --git a/dspy/experimental/__init__.py b/dspy/experimental/__init__.py
new file mode 100644
index 000000000..651c7d97f
--- /dev/null
+++ b/dspy/experimental/__init__.py
@@ -0,0 +1,7 @@
+from dspy.adapters.types.citation import Citations
+from dspy.adapters.types.document import Document
+
+__all__ = [
+ "Citations",
+ "Document",
+]
diff --git a/dspy/streaming/streaming_listener.py b/dspy/streaming/streaming_listener.py
index 59168a7b4..e30759351 100644
--- a/dspy/streaming/streaming_listener.py
+++ b/dspy/streaming/streaming_listener.py
@@ -7,6 +7,7 @@ from litellm import ModelResponseStream
from dspy.adapters.chat_adapter import ChatAdapter
from dspy.adapters.json_adapter import JSONAdapter
+from dspy.adapters.types.citation import Citations
from dspy.adapters.xml_adapter import XMLAdapter
from dspy.dsp.utils.settings import settings
from dspy.streaming.messages import StreamResponse
@@ -101,6 +102,19 @@ class StreamListener:
except Exception:
return
+ # Handle anthropic citations. see https://docs.litellm.ai/docs/providers/anthropic#beta-citations-api
+ try:
+ if self._signature_field_is_citation_type():
+ if chunk_citation := chunk.choices[0].delta.provider_specific_fields.get("citation", None):
+ return StreamResponse(
+ self.predict_name,
+ self.signature_field_name,
+ Citations.from_dict_list([chunk_citation]),
+ is_last_chunk=False,
+ )
+ except Exception:
+ pass
+
if chunk_message and start_identifier in chunk_message:
# 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
@@ -203,6 +217,11 @@ class StreamListener:
f"{', '.join([a.__name__ for a in ADAPTER_SUPPORT_STREAMING])}"
)
+ def _signature_field_is_citation_type(self) -> bool:
+ """Check if the signature field is a citations field."""
+ from dspy.predict import Predict
+ return isinstance(self.predict, Predict) and getattr(self.predict.signature.output_fields.get(self.signature_field_name, None), "annotation", None) == Citations
+
def find_predictor_for_stream_listeners(program: "Module", stream_listeners: list[StreamListener]):
"""Find the predictor for each stream listener.
@@ -230,9 +249,9 @@ def find_predictor_for_stream_listeners(program: "Module", stream_listeners: lis
"predictor to use for streaming. Please specify the predictor to listen to."
)
- if field_info.annotation is not str:
+ if field_info.annotation not in [str, Citations]:
raise ValueError(
- f"Stream listener can only be applied to string output field, but your field {field_name} is of "
+ f"Stream listener can only be applied to string or Citations output field, but your field {field_name} is of "
f"type {field_info.annotation}."
)
diff --git a/tests/adapters/test_citation.py b/tests/adapters/test_citation.py
new file mode 100644
index 000000000..8d2881b07
--- /dev/null
+++ b/tests/adapters/test_citation.py
@@ -0,0 +1,192 @@
+import pydantic
+import pytest
+
+import dspy
+from dspy.experimental import Citations
+
+
+def test_citation_validate_input():
+ citation = Citations.Citation(
+ cited_text="The Earth orbits the Sun.",
+ document_index=0,
+ start_char_index=0,
+ end_char_index=23,
+ supported_text="The Earth orbits the Sun."
+ )
+ assert citation.cited_text == "The Earth orbits the Sun."
+ assert citation.document_index == 0
+ assert citation.start_char_index == 0
+ assert citation.end_char_index == 23
+ assert citation.type == "char_location"
+ assert citation.supported_text == "The Earth orbits the Sun."
+
+ with pytest.raises(pydantic.ValidationError):
+ Citations.Citation(cited_text="text")
+
+
+def test_citations_in_nested_type():
+ class Wrapper(pydantic.BaseModel):
+ citations: Citations
+
+ citation = Citations.Citation(
+ cited_text="Hello, world!",
+ document_index=0,
+ start_char_index=0,
+ end_char_index=13,
+ supported_text="Hello, world!"
+ )
+ citations = Citations(citations=[citation])
+ wrapper = Wrapper(citations=citations)
+ assert wrapper.citations.citations[0].cited_text == "Hello, world!"
+
+
+def test_citation_with_all_fields():
+ citation = Citations.Citation(
+ cited_text="Water boils at 100°C.",
+ document_index=1,
+ document_title="Physics Facts",
+ start_char_index=10,
+ end_char_index=31,
+ supported_text="Water boils at 100°C."
+ )
+ assert citation.cited_text == "Water boils at 100°C."
+ assert citation.document_index == 1
+ assert citation.document_title == "Physics Facts"
+ assert citation.start_char_index == 10
+ assert citation.end_char_index == 31
+ assert citation.supported_text == "Water boils at 100°C."
+
+
+def test_citation_format():
+ citation = Citations.Citation(
+ cited_text="The sky is blue.",
+ document_index=0,
+ document_title="Weather Guide",
+ start_char_index=5,
+ end_char_index=21,
+ supported_text="The sky is blue."
+ )
+
+ formatted = citation.format()
+
+ assert formatted["type"] == "char_location"
+ assert formatted["cited_text"] == "The sky is blue."
+ assert formatted["document_index"] == 0
+ assert formatted["document_title"] == "Weather Guide"
+ assert formatted["start_char_index"] == 5
+ assert formatted["end_char_index"] == 21
+ assert formatted["supported_text"] == "The sky is blue."
+
+
+def test_citations_format():
+ citations = Citations(citations=[
+ Citations.Citation(
+ cited_text="First citation",
+ document_index=0,
+ start_char_index=0,
+ end_char_index=14,
+ supported_text="First citation"
+ ),
+ Citations.Citation(
+ cited_text="Second citation",
+ document_index=1,
+ document_title="Source",
+ start_char_index=20,
+ end_char_index=35,
+ supported_text="Second citation"
+ )
+ ])
+
+ formatted = citations.format()
+
+ assert isinstance(formatted, list)
+ assert len(formatted) == 2
+ assert formatted[0]["cited_text"] == "First citation"
+ assert formatted[1]["cited_text"] == "Second citation"
+ assert formatted[1]["document_title"] == "Source"
+
+
+def test_citations_from_dict_list():
+ citations_data = [
+ {
+ "cited_text": "The sky is blue",
+ "document_index": 0,
+ "document_title": "Weather Guide",
+ "start_char_index": 0,
+ "end_char_index": 15,
+ "supported_text": "The sky was blue yesterday."
+ }
+ ]
+
+ citations = Citations.from_dict_list(citations_data)
+
+ assert len(citations.citations) == 1
+ assert citations.citations[0].cited_text == "The sky is blue"
+ assert citations.citations[0].document_title == "Weather Guide"
+
+
+def test_citations_postprocessing():
+ from dspy.adapters.chat_adapter import ChatAdapter
+ from dspy.signatures.signature import Signature
+
+ class CitationSignature(Signature):
+ """Test signature with citations."""
+ question: str = dspy.InputField()
+ answer: str = dspy.OutputField()
+ citations: Citations = dspy.OutputField()
+
+ adapter = ChatAdapter()
+
+ outputs = [{
+ "text": "[[ ## answer ## ]]\nThe answer is blue.\n\n[[ ## citations ## ]]\n[]",
+ "citations": [
+ {
+ "cited_text": "The sky is blue",
+ "document_index": 0,
+ "document_title": "Weather Guide",
+ "start_char_index": 10,
+ "end_char_index": 25,
+ "supported_text": "The sky is blue"
+ }
+ ]
+ }]
+
+ result = adapter._call_postprocess(
+ CitationSignature.delete("citations"),
+ CitationSignature,
+ outputs
+ )
+
+ assert len(result) == 1
+ assert "citations" in result[0]
+ assert isinstance(result[0]["citations"], Citations)
+ assert len(result[0]["citations"]) == 1
+ assert result[0]["citations"][0].cited_text == "The sky is blue"
+
+
+def test_citation_extraction_from_lm_response():
+ from unittest.mock import MagicMock
+
+ mock_choice = MagicMock(message=MagicMock(provider_specific_fields={"citations": [[
+ {
+ "type": "char_location",
+ "cited_text": "The sky is blue",
+ "document_index": 0,
+ "document_title": "Weather Guide",
+ "start_char_index": 10,
+ "end_char_index": 25,
+ "supported_text": "The sky is blue"
+ }
+ ]]}))
+
+ lm = dspy.LM(model="test")
+ citations = lm._extract_citations_from_response(mock_choice)
+
+ assert citations is not None
+ assert len(citations) == 1
+ assert citations[0]["cited_text"] == "The sky is blue"
+ assert citations[0]["document_index"] == 0
+ assert citations[0]["document_title"] == "Weather Guide"
+ assert citations[0]["start_char_index"] == 10
+ assert citations[0]["end_char_index"] == 25
+ assert citations[0]["supported_text"] == "The sky is blue"
diff --git a/tests/adapters/test_document.py b/tests/adapters/test_document.py
new file mode 100644
index 000000000..98c714440
--- /dev/null
+++ b/tests/adapters/test_document.py
@@ -0,0 +1,57 @@
+import pydantic
+import pytest
+
+from dspy.experimental import Document
+
+
+def test_document_validate_input():
+ # Create a `Document` instance with valid data.
+ doc = Document(data="The Earth orbits the Sun.")
+ assert doc.data == "The Earth orbits the Sun."
+
+ with pytest.raises(pydantic.ValidationError):
+ # Try to create a `Document` instance with invalid type.
+ Document(data=123)
+
+
+def test_document_in_nested_type():
+ class Wrapper(pydantic.BaseModel):
+ document: Document
+
+ doc = Document(data="Hello, world!")
+ wrapper = Wrapper(document=doc)
+ assert wrapper.document.data == "Hello, world!"
+
+
+def test_document_with_all_fields():
+ doc = Document(
+ data="Water boils at 100°C at standard pressure.",
+ title="Physics Facts",
+ media_type="application/pdf",
+ context="Laboratory conditions"
+ )
+ assert doc.data == "Water boils at 100°C at standard pressure."
+ assert doc.title == "Physics Facts"
+ assert doc.media_type == "application/pdf"
+ assert doc.context == "Laboratory conditions"
+
+
+def test_document_format():
+ doc = Document(
+ data="The sky is blue.",
+ title="Color Facts",
+ media_type="text/plain"
+ )
+
+ formatted = doc.format()
+
+ assert isinstance(formatted, list)
+ assert len(formatted) == 1
+
+ doc_block = formatted[0]
+ assert doc_block["type"] == "document"
+ assert doc_block["source"]["type"] == "text"
+ assert doc_block["source"]["media_type"] == "text/plain"
+ assert doc_block["source"]["data"] == "The sky is blue."
+ assert doc_block["title"] == "Color Facts"
+ assert doc_block["citations"]["enabled"] is True
diff --git a/tests/streaming/test_streaming.py b/tests/streaming/test_streaming.py
index 2fbd7abd6..134320d61 100644
--- a/tests/streaming/test_streaming.py
+++ b/tests/streaming/test_streaming.py
@@ -9,6 +9,7 @@ from asyncer import syncify
from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices
import dspy
+from dspy.experimental import Citations, Document
from dspy.streaming import StatusMessage, StatusMessageProvider, streaming_response
@@ -874,3 +875,86 @@ async def test_streaming_allows_custom_chunk_types():
assert isinstance(all_chunks[0], CustomChunk)
assert isinstance(all_chunks[1], dspy.Prediction)
+
+
+async def test_streaming_with_citations():
+ class AnswerWithSources(dspy.Signature):
+ """Answer questions using provided documents with citations."""
+ documents: list[Document] = dspy.InputField()
+ question: str = dspy.InputField()
+ answer: str = dspy.OutputField()
+ citations: Citations = dspy.OutputField()
+
+ class MyProgram(dspy.Module):
+ def __init__(self):
+ super().__init__()
+ self.predict = dspy.Predict(AnswerWithSources)
+
+ def forward(self, documents, question, **kwargs):
+ return self.predict(documents=documents, question=question, **kwargs)
+
+ async def citation_stream(*args, **kwargs):
+ # Stream chunks with citation data in provider_specific_fields
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content="[[ ##"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content=" answer"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content=" ## ]]\n\n"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content="Water"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content=" boils"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content=" at"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content=" 100°C"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content="."))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content="\n\n"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content='[{"type": "char_location", "cited_text": "Water boils at 100°C", "document_index": 0, "document_title": "Physics Facts", "start_char_index": 0, "end_char_index": 19}]'))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(
+ content="",
+ provider_specific_fields={
+ "citation": {
+ "type": "char_location",
+ "cited_text": "Water boils at 100°C",
+ "document_index": 0,
+ "document_title": "Physics Facts",
+ "start_char_index": 0,
+ "end_char_index": 19
+ }
+ }
+ ))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content="\n\n"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content="[[ ##"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content=" completed"))])
+ yield ModelResponseStream(model="claude", choices=[StreamingChoices(delta=Delta(content=" ## ]]"))])
+
+ # Mock the final response choice to include provider_specific_fields with citations
+ with mock.patch("litellm.acompletion", return_value=citation_stream()):
+ program = dspy.streamify(
+ MyProgram(),
+ stream_listeners=[
+ dspy.streaming.StreamListener(signature_field_name="citations"),
+ ],
+ )
+
+ # Create test documents
+ docs = [Document(data="Water boils at 100°C at standard pressure.", title="Physics Facts")]
+
+ with dspy.context(lm=dspy.LM("anthropic/claude-3-5-sonnet-20241022", cache=False)):
+ output = program(documents=docs, question="What temperature does water boil?")
+ citation_chunks = []
+ final_prediction = None
+ async for value in output:
+ if isinstance(value, dspy.streaming.StreamResponse) and value.signature_field_name == "citations":
+ citation_chunks.append(value)
+ elif isinstance(value, dspy.Prediction):
+ final_prediction = value
+
+ # Test that we received citation chunks from streaming
+ assert len(citation_chunks) > 0
+ citation_chunk = citation_chunks[0]
+ assert isinstance(citation_chunk.chunk, Citations)
+ assert len(citation_chunk.chunk) == 1
+ assert citation_chunk.chunk[0].cited_text == "Water boils at 100°C"
+ assert citation_chunk.chunk[0].document_title == "Physics Facts"
+
+ # Test that prediction contains the expected fields
+ assert final_prediction is not None
+ assert hasattr(final_prediction, "answer")
+ assert hasattr(final_prediction, "citations")