Understanding Attribution

Attribution answers the question: which words of the prompt did this generated word actually draw on? The Engine computes attribution scores at the token level while it generates; the SDK aggregates them to words and attaches them to every streamed chunk.

Anatomy of one attribution entry

Each entry in a chunk's input_attributions or output_attributions links one generated word to one source word:

Field	Meaning
source_type	Where the source word lives: message, tool, boilerplate, or output.
source_id	Index of the source container — the message index for message, the tool-definition index for tool.
word_id	Position of the source word within its container.
word_string	The source word itself, so you can render evidence without re-tokenizing.
score	Attribution strength. Higher means the generated word drew more on this source word.

The four source types:

• message — a word in one of your request messages. source_id is the index into request.messages, so you can resolve the role and full text.
• tool — a word in one of your tool definitions (request.tools).
• boilerplate — chat-template scaffolding around your content (role markers, special tokens). Usually noise for applications; the evidence layer ignores it.
• output — used in output_attributions: the generated word drew on earlier generated words rather than on the prompt.

Input versus output attributions

The split matters for interpretation. A response segment whose mass sits in input_attributions is anchored in your context; a segment whose mass sits in output_attributions is primarily elaborating on the model's own earlier output. The evidence layer turns exactly this ratio into its source-share signal.

Controlling attribution volume

top_k_attributions / topKAttributions bounds how many attribution entries the Engine reports per generated token (default 5). A higher value gives the evidence layer more complete source coverage at the cost of larger stream payloads; 12 is a reasonable value for evidence-heavy applications.

From tokens to words

The Engine reports attributions between tokens; the SDK maps token spans to word spans on both the prompt side and the output side. When several token scores land on the same word pair, the word-level score is their maximum, not their sum. This keeps tokenizer fragmentation from inflating values for phone numbers, identifiers, and other words that happen to use many tokens. Words are what applications should reason about — token boundaries are a tokenizer implementation detail and differ between model releases.