Inline citations cookbook

This cookbook takes an answer from any model and renders it with numbered citations. Each number points to the exact source text behind it. Running this cookbook against the API prints:

Northwind reported revenue of $312.0 million [1], up 18% year over [2] year. It also ended the quarter with 9,420 customers [3].

[1] "$312.0 million"
[2] "18% year over"
[3] "9,420 customers"

1. Generate an answer

Use whatever model you already use. Keep the exact answer string you show to the user.

document = """
NORTHWIND ANALYTICS Q3 FY2026 RESULTS
Total revenue was $312.0 million, up 18% year over year.
Northwind ended the quarter with 9,420 customers.
""".strip()

question = "Summarize the quarter."

# Replace this with your LLM call.
answer = (
    "Northwind reported revenue of $312.0 million, up 18% year over year. "
    "It also ended the quarter with 9,420 customers."
)

2. Attribute the answer

import os
import httpx

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    json={
        "document": document,
        "question": question,
        "answer": answer,
        # Python indexes strings by code point.
        "offset_encoding": "utf-32",
    },
    timeout=90.0,
)
response.raise_for_status()
links = [item for item in response.json()["spans"] if item["source"] is not None]

Results come back in answer order. If links is empty, render the answer without citations.

3. Split the answer into segments

Walk the answer once. Text between links stays plain, and each link becomes a numbered citation:

def citation_segments(answer: str, links: list[dict]) -> list[dict]:
    segments, cursor, number = [], 0, 0

    for item in links:
        start, end = item["answer"]["start"], item["answer"]["end"]
        if start < cursor:  # Skip a link that overlaps the previous one.
            continue
        if cursor < start:
            segments.append({"text": answer[cursor:start]})
        number += 1
        segments.append({
            "text": answer[start:end],
            "citation": number,
            "source": item["source"],
        })
        cursor = end

    if cursor < len(answer):
        segments.append({"text": answer[cursor:]})
    return segments

segments = citation_segments(answer, links)

4. Render

Put each marker after its phrase, and list the sources underneath:

body = "".join(
    f"{s['text']} [{s['citation']}]" if "citation" in s else s["text"]
    for s in segments
)
sources = [
    f"[{s['citation']}] \"{s['source']['text']}\""
    for s in segments if "citation" in s
]
print(body + "\n\n" + "\n".join(sources))

In a web UI, render each cited phrase as a button. On click, use source.start and source.end to highlight the evidence in the document pane. Here is the same idea in JavaScript. It relies on the default utf-16 encoding, which matches String.prototype.slice:

function renderWithCitations(answer, spans) {
  let html = "";
  let cursor = 0;
  let n = 0;

  for (const { answer: claim, source } of spans) {
    if (!source || claim.start < cursor) continue;
    html += escapeHtml(answer.slice(cursor, claim.start));
    n += 1;
    html +=
      `<mark data-source-start="${source.start}" data-source-end="${source.end}">` +
      `${escapeHtml(answer.slice(claim.start, claim.end))}</mark><sup>${n}</sup>`;
    cursor = claim.end;
  }
  return html + escapeHtml(answer.slice(cursor));
}

function escapeHtml(text) {
  return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
}

5. Rank or style by confidence

source.confidence is the strength of each link, from 0 to 1. Use it to order a source list or to style strong and weak links differently:

ranked = sorted(links, key=lambda item: item["source"]["confidence"], reverse=True)

confidence describes how strongly the phrase is tied to the source text. It does not grade whether the answer is correct.

Multiple documents

To cite across several retrieved documents, join them into one document and record where each one starts. Map each source.start back to its document:

import bisect

docs = [("Q3 report", text_a), ("Press release", text_b)]
separator = "\n\n"

starts, parts, offset = [], [], 0
for _, text in docs:
    starts.append(offset)
    parts.append(text)
    offset += len(text) + len(separator)
document = separator.join(parts)

def title_for(source: dict) -> str:
    return docs[bisect.bisect_right(starts, source["start"]) - 1][0]

Use the same joined document for generation and attribution, so the model and TokenPath see identical text.

Get started

Core concepts

Advanced

Use cases

Cookbooks

Resources

Inline citations cookbook

1. Generate an answer

2. Attribute the answer

3. Split the answer into segments

4. Render

5. Rank or style by confidence

Multiple documents

​1. Generate an answer

​2. Attribute the answer

​3. Split the answer into segments

​4. Render

​5. Rank or style by confidence

​Multiple documents

1. Generate an answer

2. Attribute the answer

3. Split the answer into segments

4. Render

5. Rank or style by confidence

Multiple documents