Dspy Citations

Add Structured Citations to DSPy Outputs

Guide the user through adding structured citations to DSPy outputs so AI answers can be traced back to specific source passages.

What are DSPy Citations

dspy.experimental.Citations provides structured source attribution for LM outputs. Instead of inline quotes, you get machine-readable citation objects that identify exactly which passage from which document supports each claim. Works natively with Anthropic's Citations API and falls back to prompt-based extraction for other providers.

When to use Citations

Step 1: Set up Documents

Create Document objects from your source material:

import dspy
from dspy.experimental import Citations, Document

lm = dspy.LM("openai/gpt-4o-mini")  # or "anthropic/claude-sonnet-4-5-20250929", etc.
dspy.configure(lm=lm)

# Create documents from your sources
documents = [
    Document(
        text="DSPy is a framework for programming language models. It replaces prompting with composable modules that can be optimized.",
        title="DSPy Overview",
        source_id="doc-001",
    ),
    Document(
        text="MIPROv2 is the most powerful DSPy optimizer. It jointly optimizes instructions and few-shot demonstrations.",
        title="Optimizers Guide",
        source_id="doc-002",
    ),
]

Step 2: Build a signature with Citations output

class CitedQA(dspy.Signature):
    """Answer the question using the provided context. Cite your sources."""
    context: list[str] = dspy.InputField(desc="source documents")
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()
    citations: Citations = dspy.OutputField(desc="structured citations for claims in the answer")

Step 3: Use with a standard module

qa = dspy.ChainOfThought(CitedQA)

# Format documents as context strings
context = [f"[{doc.source_id}] {doc.title}: {doc.text}" for doc in documents]

result = qa(
    context=context,
    question="What is the most powerful DSPy optimizer?",
)

print(result.answer)
# "MIPROv2 is the most powerful DSPy optimizer..."

for citation in result.citations:
    print(f"  Cited: '{citation.cited_text}' from document {citation.document_index}")

Step 4: Anthropic native Citations API

For Anthropic models, enable native citation support for higher accuracy:

lm = dspy.LM("anthropic/claude-sonnet-4-5-20250929")
dspy.configure(lm=lm)

# Enable native citations via adapter feature
dspy.configure(
    lm=lm,
    adapter=dspy.ChatAdapter(
        adapt_to_native_lm_feature=["citations"],
    ),
)

# Now Citations output uses Anthropic's built-in citation extraction
# instead of prompt-based parsing -- higher accuracy, structured response
result = qa(
    context=context,
    question="How does DSPy replace prompting?",
)

Native mode advantages:

• Citations are extracted by the model during generation (not post-hoc)
• cited_text exactly matches source text (character-level accuracy)
• document_index reliably maps to the input document list

Step 5: Parse and validate citations

# Each citation has these fields
for citation in result.citations:
    print(f"Cited text: {citation.cited_text}")
    print(f"Document index: {citation.document_index}")
    print(f"Start char: {citation.start}")
    print(f"End char: {citation.end}")

# Validate that cited text exists in the source document
for citation in result.citations:
    source_doc = documents[citation.document_index]
    if citation.cited_text in source_doc.text:
        print(f"VALID: Citation found in {source_doc.title}")
    else:
        print(f"INVALID: Citation not found in source")

Step 6: Citations with streaming

Stream answers while accumulating citations:

from dspy.streaming import streamify, StreamListener

qa = dspy.ChainOfThought(CitedQA)

answer_listener = StreamListener(signature_field_name="answer")
streaming_qa = streamify(qa, stream_listeners=[answer_listener])

async for chunk in streaming_qa(context=context, question="..."):
    if hasattr(chunk, "answer"):
        print(chunk.answer, end="", flush=True)
    elif isinstance(chunk, dspy.Prediction):
        # Citations are available in the final prediction
        for citation in chunk.citations:
            print(f"\n[{citation.document_index}] {citation.cited_text}")

Step 7: Non-Anthropic fallback patterns

For providers without native citation support, use prompt engineering:

class CitedAnswer(dspy.Signature):
    """Answer using ONLY information from the provided documents.
    For each claim, include [doc_N] inline where N is the document number."""
    context: list[str] = dspy.InputField(desc="numbered source documents")
    question: str = dspy.InputField()
    answer: str = dspy.OutputField(desc="answer with [doc_N] inline citations")

# Number your documents explicitly
numbered_context = [
    f"[doc_{i}] {doc.title}: {doc.text}"
    for i, doc in enumerate(documents)
]

qa = dspy.ChainOfThought(CitedAnswer)
result = qa(context=numbered_context, question="...")
# Parse [doc_N] references from the answer text

Gotchas

1. Claude omits the `Citations` type import. You must import from dspy.experimental -- it is not in the main dspy namespace. Use from dspy.experimental import Citations, Document. 2. Native citations only work with Anthropic models. If you configure adapt_to_native_lm_feature=["citations"] with OpenAI, it silently falls back to prompt-based parsing which may be less accurate. 3. Claude hardcodes document indices. The document_index in citations maps to the position in the context list. If you reorder documents, indices change. Always use the index to look up the source, do not hardcode. 4. Citations are experimental. The API is in dspy.experimental and may change between versions. Pin your DSPy version in production. 5. Claude generates citations without source material. Citations only make sense when you provide context documents. Without context, the model fabricates citation metadata. Always pair Citations with a retrieval step.

Additional resources

• dspy.ai/api/experimental/Citations
• For API details, see reference.md
• For worked examples, see examples.md

Cross-references

Install any skill: npx skills add lebsral/DSPy-Programming-not-prompting-LMs-skills --skill <name>

• Stopping hallucinations with grounding -- see /ai-stopping-hallucinations
• Searching docs for RAG pipelines -- see /ai-searching-docs
• Retrieval modules for getting context -- see /dspy-retrieval
• Streaming citations progressively -- see /dspy-streaming
• Install `/ai-do` if you do not have it -- it routes any AI problem to the right skill and is the fastest way to work: npx skills add lebsral/DSPy-Programming-not-prompting-LMs-skills --skill ai-do

Citations Examples

Example 1: RAG with verifiable citations

A retrieval-augmented QA system that returns cited answers:

import dspy
from dspy.experimental import Citations, Document

lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)


class CitedRAG(dspy.Module):
    def __init__(self, retriever):
        self.retriever = retriever
        self.qa = dspy.ChainOfThought(CitedQA)

    def forward(self, question):
        # Retrieve relevant documents
        passages = self.retriever(question).passages

        # Format as context with source IDs
        context = [f"[{i}] {p}" for i, p in enumerate(passages)]

        # Generate answer with citations
        result = self.qa(context=context, question=question)
        return result


class CitedQA(dspy.Signature):
    """Answer using only the provided context. Cite each claim."""
    context: list[str] = dspy.InputField()
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()
    citations: Citations = dspy.OutputField()


# Usage
retriever = dspy.ColBERTv2(url="http://localhost:8893/api/search")
rag = CitedRAG(retriever=retriever)
result = rag(question="What optimizers does DSPy support?")

print(result.answer)
for c in result.citations:
    print(f"  Source [{c.document_index}]: {c.cited_text[:60]}...")

Example 2: Legal document citation

Extracting claims with precise source attribution for compliance:

import dspy
from dspy.experimental import Citations, Document

lm = dspy.LM("anthropic/claude-sonnet-4-5-20250929")
dspy.configure(
    lm=lm,
    adapter=dspy.ChatAdapter(adapt_to_native_lm_feature=["citations"]),
)


class LegalCitedAnswer(dspy.Signature):
    """Answer the legal question citing specific clauses from the contract.
    Every factual claim must have a citation."""
    contract_sections: list[str] = dspy.InputField(desc="numbered contract sections")
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()
    citations: Citations = dspy.OutputField()


qa = dspy.ChainOfThought(LegalCitedAnswer)

contract_sections = [
    "Section 1.1: The term of this agreement is 24 months from the effective date.",
    "Section 2.3: Either party may terminate with 90 days written notice.",
    "Section 4.1: The monthly fee is $5,000, payable within 30 days of invoice.",
]

result = qa(
    contract_sections=contract_sections,
    question="What is the termination notice period?",
)

print(f"Answer: {result.answer}")
print(f"\nCitations:")
for c in result.citations:
    print(f"  Section [{c.document_index}]: \"{c.cited_text}\"")
    # Verify citation accuracy
    assert c.cited_text in contract_sections[c.document_index]

Example 3: Multi-source research with citation validation

Research across multiple documents with validation:

import dspy
from dspy.experimental import Citations, Document

lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)


class ResearchAnswer(dspy.Signature):
    """Synthesize information from multiple sources. Cite each claim."""
    sources: list[str] = dspy.InputField(desc="labeled source documents")
    question: str = dspy.InputField()
    answer: str = dspy.OutputField(desc="synthesis with citations")
    citations: Citations = dspy.OutputField()


def validate_citations(result, sources):
    """Check that all citations reference real text in the sources."""
    valid = 0
    invalid = 0
    for c in result.citations:
        if c.document_index < len(sources):
            if c.cited_text in sources[c.document_index]:
                valid += 1
            else:
                invalid += 1
                print(f"  INVALID: '{c.cited_text[:40]}...' not in source {c.document_index}")
        else:
            invalid += 1
            print(f"  INVALID: document_index {c.document_index} out of range")
    print(f"Citations: {valid} valid, {invalid} invalid")
    return invalid == 0


qa = dspy.ChainOfThought(ResearchAnswer)

sources = [
    "[Wikipedia] Python was created by Guido van Rossum and first released in 1991.",
    "[Official docs] Python 3.12 introduced per-interpreter GIL and improved error messages.",
    "[Blog] Python is the most popular language for machine learning and data science.",
]

result = qa(sources=sources, question="When was Python created and what is it used for?")
print(f"Answer: {result.answer}\n")
validate_citations(result, sources)

Citations API Reference

Condensed from dspy.ai/api/experimental/Citations. Verify against upstream for latest.

Citations type

from dspy.experimental import Citations

A list-like container of citation objects. Used as an output field type in DSPy signatures.

Usage in signatures:

class MySignature(dspy.Signature):
    context: list[str] = dspy.InputField()
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()
    citations: Citations = dspy.OutputField()

Iteration:

for citation in result.citations:
    print(citation.cited_text, citation.document_index)

Citation object fields

Document type

from dspy.experimental import Document

doc = Document(
    text="...",         # str -- required, document content
    title="...",        # str -- optional, document title
    source_id="...",    # str -- optional, unique identifier
)

Native Anthropic Citations

Enable via adapter configuration:

dspy.configure(
    lm=dspy.LM("anthropic/claude-sonnet-4-5-20250929"),
    adapter=dspy.ChatAdapter(
        adapt_to_native_lm_feature=["citations"],
    ),
)

When enabled:

• Anthropic's Citations API extracts citations during generation
• cited_text exactly matches source text (character-level)
• start and end offsets are populated
• Higher accuracy than prompt-based extraction

Only works with Anthropic models. Other providers fall back to prompt-based citation extraction.

Class methods

Provider compatibility