feat: support Anthropic document citations

[fangkangmi]

• I have looked for existing issues (including closed) about this

Feature Request

Rig's Anthropic provider supports document content blocks, but it does not currently expose Claude's Messages API citations surface.

Anthropic supports enabling citations on document blocks with:

"citations": { "enabled": true }

When enabled, Claude returns citation metadata on response text blocks, including location types such as char_location, page_location, and content_block_location. Streaming responses can also include citations_delta.

Current Rig behavior in rig-core v0.37.0:

• crates/rig-core/src/providers/anthropic/completion.rs models Content::Document with only source and cache_control.
• message::Document has additional_params, but the Anthropic conversion currently ignores those provider-specific fields when building Content::Document.
• Anthropic response conversion maps text blocks into generic AssistantContent::Text, which has no place to preserve citation metadata.

Related prior work: #1358 added plain text document support for Anthropic, but explicitly did not enable citations.

Motivation

Provider-native citations are useful for document QA, RAG, grading/review workflows, and any application that needs grounded model output with machine-readable links back to source documents.

Without this support, downstream users must bypass Rig and call Anthropic or Anthropic-compatible proxies directly to enable citations and parse the citation-bearing response shape. That loses Rig's normal provider abstraction, response conversion, telemetry, and usage handling.

Proposal

Add Anthropic citation support for document content blocks and responses.

Suggested scope:

1. Add an Anthropic citation config type, e.g. citations: { enabled: true }, on supported Anthropic document content blocks.
2. Ensure generic Document::additional_params is either intentionally forwarded for Anthropic document fields or provide a typed Anthropic-specific builder/API for citations.
3. Preserve returned citation metadata on assistant text blocks instead of dropping it during conversion.
4. Support streaming citations_delta events if possible, or document that only non-streaming citations are supported initially.
5. Add serialization/deserialization tests covering:
   • request document serializes citations.enabled = true
   • response text block with char_location citation is preserved
   • PDF/page citation and custom content block citation shapes are represented or explicitly handled

This should stay scoped to the Anthropic provider and avoid changing other provider APIs to model fields they do not support.

Alternatives

A downstream raw HTTP call works, but bypasses Rig's provider abstraction, response types, telemetry, and usage handling.

Relevant source/docs:

• https://platform.claude.com/docs/en/build-with-claude/citations

I'm happy to work on a PR for this

[linear]

RIG-1310

[temrjan]

Hi @fangkangmi — saw you mentioned wanting to work on a PR for this. Are you still planning to take it on?

If you're tied up, I'd be happy to pick this up — I work with the Claude API daily, including citations in document workflows, and the scope you've outlined (citations config + preserving citation metadata on response blocks + serialization tests) looks well-defined.

Happy to wait a few days for your reply before starting any work.

[gold-silver-copper]

Either one of you, feel free to work on the PR :)

[temrjan]

Thanks @gold-silver-copper — getting started. I'll open a PR in the next few days.