Skip to main content

Citations

Every answer lists its sources in citations. A source is a document, such as a filing, transcript, or broker report, or data, such as a figure or a data view. The answer text has no source links. Instead, each citation's text_ranges say where the text cites it.

Citations come in two places:

  • On each assistant message from GET /sessions/{session_id}/messages.
  • As citation.added events on a stream, with the answer text.

The citation object​

{
"type": "document",
"id": "…",
"title": "Nvidia's data center sales jump",
"source": "Financial Times",
"url": "https://research.alpha-sense.com/…",
"document_id": "…",
"page": 3,
"statement_ids": ["…"],
"broker_code": null,
"broker_name": null,
"text_ranges": [{"start": 412, "end": 412}]
}
  • type is document or data. More types may be added, so skip any you don't recognize.
  • url opens the citation in AlphaSense: a document at the cited passage, or the data. The reader must be signed in to AlphaSense. url can be null.
  • For a document, document_id, page, and statement_ids identify the cited passage. title, source, and the broker fields can be null if the document's details can't be found. The citation is still listed.
  • For data, title is the cited value or the data view's name. source, document_id, page, and the broker fields are null, and statement_ids is empty.
  • broker_code and broker_name are set for broker research.

Every field is listed in the API Reference.

Place citations in the text​

text_ranges lists every place the text cites the citation, in order. Each range is a start and an exclusive end, counted from the start of the answer text:

  • In the transcript, the text is content[0].text.
  • On a stream, the text is the turn's message.delta deltas, joined in order.

A document's range is a point (start equals end) just after the claim it supports. Put a marker there. A data citation's range covers the cited value, which stays in the text. Link that span.

Offsets count UTF-16 code units, the way JavaScript and Java index strings. Python counts characters differently for emoji and other rare characters, so slice the UTF-16 encoding, as the sample does.

These samples add a numbered marker at each cited place and list the sources. answer is an assistant message, as in the Quick Start.

def add_footnotes(message):
"""Return the answer text with [n] at each cited place, and the numbered sources."""
text = message["content"][0]["text"].encode("utf-16-le") # offsets count UTF-16 units
sources = [c for c in message["citations"] if c["type"] in ("document", "data")]
places = sorted(
(place["end"], number)
for number, citation in enumerate(sources, start=1)
for place in citation["text_ranges"]
)
parts, last = [], 0
for end, number in places:
parts.append(text[2 * last : 2 * end].decode("utf-16-le") + f"[{number}]")
last = end
parts.append(text[2 * last :].decode("utf-16-le"))
return "".join(parts), sources


text, sources = add_footnotes(answer)
print(text)
for number, citation in enumerate(sources, start=1):
print(f"[{number}] {citation['title']} ({citation['source'] or citation['type']}) {citation['url']}")

Match streamed and saved citations​

A citation's id is unique within its message, but it changes each time you read the transcript, except for a datapoint. Don't use id to match a streamed citation to the transcript. For the same answer, text_ranges match, and so do a document's document_id and statement_ids.