WordPress / WordPress/php-ai-client
MessagePart cannot represent source attribution, so every provider drops citations
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 308
- Forks
- 84
- Avg merge
- 7d 21h
- Merged PRs (30d)
- 2
Description
MessagePart (src/Messages/DTO/MessagePart.php) can carry exactly seven things:
channel, type, thoughtSignature, text, file, functionCall,
functionResponse. None of them can hold a citation.
All three first-party providers return source attribution, in three different
shapes (per vendor documentation):
| Provider | Field |
|---|---|
| Anthropic | citations on text blocks — cited_text, document_index, document_title, typed location |
| OpenAI | annotations — type: "url_citation", url, title, start_index, end_index, plus sources |
| Gemini | citationMetadata.citationSources and groundingMetadata; annotations/url_citation on the Search-grounding surface |
And all three provider packages currently drop it. Verified by reading the source:
AnthropicTextGenerationModel::parseResponseContentMessagePart()'s case 'text'
keeps only $partData['text']; GoogleTextGenerationModel and
OpenAiTextGenerationModel contain no citation/grounding/annotation handling at all.
This is a gap rather than a data-loss bug — no provider currently requests
citations, so nothing is being lost in production today. But the parse paths are
not ready, and no provider can be made ready while the DTO has nowhere to put the
result.
Suggested shape: thoughtSignature is the precedent — an opaque,
provider-supplied, round-trippable field already accepted on MessagePart. A
citation carrier could follow it, normalising the three vendor shapes into one
representation (source identifier/URI and optional title).
Related: #268 (provider-agnostic text extraction) — same theme of getting
structured meaning out of documents.
Happy to open a PR once maintainers settle the shape; the API-surface decision is
yours.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with src/Messages/DTO/MessagePart.php, then inspect AnthropicTextGenerationModel::parseResponseContentMessagePart(), GoogleTextGenerationModel, and OpenAiTextGenerationModel. First confirm the provider-specific citation shapes described in the issue; implementation is blocked until maintainers decide the normalized carrier shape. Done means the DTO and all three parse paths can preserve citations, with coverage for each provider shape.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100