Raw heatmap cookbook

Most products should use POST /v1/attributions. Reach for the raw heatmap when you want to see the attention itself, write your own aggregation, or debug why a phrase resolved the way it did.

1. Fetch the heatmap

import os
import httpx

document = "Revenue improved in Q4 after stronger enterprise demand drove renewals."
question = "Why did revenue improve?"
answer = "Revenue improved because enterprise demand increased."

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions/heatmap",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    json={
        "document": document,
        "question": question,
        "answer": answer,
        "threshold": 0.001,
        "offset_encoding": "utf-32",  # Slice with Python indices below.
    },
    timeout=90.0,
)
response.raise_for_status()
heatmap = response.json()

2. Map cells back to text

row, col, and data are parallel arrays. Each index i is one cell: answer token row[i] pays data[i] of its attention to document token col[i].

cells = []
for row, col, score in zip(heatmap["row"], heatmap["col"], heatmap["data"]):
    a_start, a_end = heatmap["answer_offsets"][row]
    d_start, d_end = heatmap["document_offsets"][col]
    cells.append((score, answer[a_start:a_end], document[d_start:d_end]))

for score, answer_token, document_token in sorted(cells, reverse=True)[:10]:
    print(f"{score:.3f}  {answer_token!r} -> {document_token!r}")

3. Build a dense matrix

import numpy as np

matrix = np.zeros(heatmap["shape"], dtype=np.float32)
matrix[heatmap["row"], heatmap["col"]] = heatmap["data"]

Rows are answer tokens and columns are document tokens. Cells below threshold stay 0.

4. Plot it

import matplotlib.pyplot as plt

answer_labels = [answer[s:e] for s, e in heatmap["answer_offsets"]]
document_labels = [document[s:e] for s, e in heatmap["document_offsets"]]

fig, ax = plt.subplots(figsize=(12, 4))
ax.imshow(matrix, aspect="auto", cmap="Purples")
ax.set_yticks(range(len(answer_labels)), answer_labels)
ax.set_xticks(range(len(document_labels)), document_labels, rotation=90)
ax.set_ylabel("answer token")
ax.set_xlabel("document token")
plt.tight_layout()
plt.show()

5. Aggregate a phrase yourself

To see where one answer phrase points, add up its tokens’ rows. This is the first step /v1/attributions takes before it picks a contiguous source range:

phrase = "enterprise demand"
start = answer.index(phrase)
end = start + len(phrase)

token_rows = [
    t for t, (s, e) in enumerate(heatmap["answer_offsets"])
    if s < end and e > start
]
mass = matrix[token_rows].sum(axis=0)

for col in mass.argsort()[::-1][:5]:
    s, e = heatmap["document_offsets"][col]
    print(f"{mass[col]:.3f}  {document[s:e]!r}")

When to use which endpoint

Use the raw heatmap for	Use `/v1/attributions` for
Token-by-token visualizations	Citations and click-to-source UI
Research and debugging	Ranked, annotated source links
Custom aggregation logic	Documents over 400,000 characters
Comparing thresholds	Almost every product integration

Get started

Core concepts

Advanced

Use cases

Cookbooks

Resources

Raw heatmap cookbook

1. Fetch the heatmap

2. Map cells back to text

3. Build a dense matrix

4. Plot it

5. Aggregate a phrase yourself

When to use which endpoint

​1. Fetch the heatmap

​2. Map cells back to text

​3. Build a dense matrix

​4. Plot it

​5. Aggregate a phrase yourself

​When to use which endpoint

1. Fetch the heatmap

2. Map cells back to text

3. Build a dense matrix

4. Plot it

5. Aggregate a phrase yourself

When to use which endpoint