Context attribution

​

Attribute a response from an agent run

import os
from seekrai import SeekrFlow

client = SeekrFlow(api_key=os.environ["SEEKR_API_KEY"])

attribution = client.explainability.get_context_attribution_from_run(
    thread_id="<your-thread-id>",
)
print(attribution)

attribution = client.explainability.get_context_attribution_from_run(
    thread_id="<your-thread-id>",
    run_id="<your-run-id>",
    granularity="sentence",
    top_k=5,
)

​

Parameters

​

Attribute raw context

attribution = client.explainability.get_context_attribution(
    context="France is a country in Western Europe with Paris as its capital. "
            "The Eiffel Tower is a wrought-iron lattice tower in Paris...",
    query="What is the capital of France and what is it known for?",
    response="Paris is the capital of France. It is known for the Eiffel Tower.",
    granularity="sentence",
    top_k=5,
)
print(attribution)

​

Parameters

​

Response structure

{
  "response_text": "Paris is the capital of France. It is known for the Eiffel Tower.",
  "segments": [
    {
      "segment_index": 0,
      "segment_text": "Paris is the capital of France.",
      "char_offset": 0,
      "sources": [
        {
          "source_type": "tool_response",
          "id": 0,
          "text": "France is a country in Western Europe with Paris as its capital.",
          "attribution": 0.87,
          "offset": 0,
          "tool_name": "file_search",
          "tool_call_id": "call_abc123",
          "tool": {
            "type": "file_search",
            "file_path": "europe_facts.txt",
            "file_id": "file-xyz789",
            "query": "capital of France"
          }
        }
      ]
    },
    {
      "segment_index": 1,
      "segment_text": "It is known for the Eiffel Tower.",
      "char_offset": 31,
      "sources": [
        {
          "source_type": "tool_response",
          "id": 2,
          "text": "The Eiffel Tower is a wrought-iron lattice tower on the Champ de Mars in Paris.",
          "attribution": 0.91,
          "offset": 312,
          "tool_name": "web_search",
          "tool_call_id": "call_def456",
          "tool": {
            "type": "web_search",
            "url": "https://en.wikipedia.org/wiki/Eiffel_Tower",
            "title": "Eiffel Tower - Wikipedia",
            "search_query": "Eiffel Tower Paris landmark"
          }
        }
      ]
    }
  ],
  "highlight": null
}

​

Fields

• response_text (string): The full response text that was attributed.
• segments (list): Per-segment attribution results. Populated when highlight is not provided. Each item contains:
  • segment_index (int): 0-based position of the segment in the response.
  • segment_text (string): The text of this segment.
  • char_offset (int): Character offset of this segment within response_text.
  • sources (list): Sources attributed to this segment, each with:
    • source_type (string): Either "raw" (plain context text) or "tool_response" (output from a tool call).
    • id (int): Index of this source in the partitioned context.
    • text (string): The source text content.
    • attribution (float): Attribution score. See Attribution scores.
    • offset (int): Character offset of this source in the original context.
    • tool_name, tool_call_id, tool (tool_response only): The tool name, call ID, and tool-specific metadata. The tool object varies by type: file_search includes file_path, file_id, and query; web_search includes url, title, and search_query; code_interpreter includes code; custom includes tool_name.
• sources (list): Only populated when highlight is provided. Contains sources for the highlighted text instead of per-segment results.
• highlight (string): The highlighted text echoed back, if provided in the request.

​

Attribution scores

​

Attribute a specific portion of the response

attribution = client.explainability.get_context_attribution_from_run(
    thread_id="<your-thread-id>",
    highlight="It is known for the Eiffel Tower.",
)

for source in attribution.sources:
    print(source.attribution, source.text)

​

Common errors

• 400 Bad request – A required parameter is missing or invalid.
• 404 Not found – The thread or run ID does not exist.
• 422 Unprocessable entity – The thread has no assistant response. This occurs if response generation is still in progress or the agent run failed.
• 503 Service unavailable – The request timed out. Retry, or reduce context size.
• 500 Internal server error – Unexpected server error. Retry the request.

​

Best practices

• Granularity: Sentence-level gives the most interpretable results. When context is large and speed matters more than precision, use "chunk" with get_context_attribution_from_run or "paragraph" with get_context_attribution.
• top_k: Values of 3–5 work well for most use cases. Increase toward 10 when debugging multi-hop answers where many sources contribute.
• num_ablations: Leave unset in production. Override only when benchmarking or reproducing a specific result.
• Segments with no strong sources: This indicates the model generated that content from prior knowledge rather than retrieved context. It is expected behavior, not an error.