WordPress / WordPress/php-ai-client

MessagePart cannot represent source attribution, so every provider drops citations

Open
#277 5 comments 0 reactions 0 assignees View on GitHub

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 annotationstype: "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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.