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.addedevents 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}]
}
typeisdocumentordata. More types may be added, so skip any you don't recognize.urlopens the citation in AlphaSense: a document at the cited passage, or the data. The reader must be signed in to AlphaSense.urlcan benull.- For a document,
document_id,page, andstatement_idsidentify the cited passage.title,source, and the broker fields can benullif the document's details can't be found. The citation is still listed. - For data,
titleis the cited value or the data view's name.source,document_id,page, and the broker fields arenull, andstatement_idsis empty. broker_codeandbroker_nameare 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.deltadeltas, 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.
- Python
- JavaScript
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']}")
// Return the answer text with [n] at each cited place, and the numbered sources.
function addFootnotes(message) {
const text = message.content[0].text
const sources = message.citations.filter(c => ['document', 'data'].includes(c.type))
const places = sources
.flatMap((citation, i) => citation.text_ranges.map(({end}) => ({end, number: i + 1})))
.sort((a, b) => a.end - b.end || a.number - b.number)
let result = ''
let last = 0
for (const {end, number} of places) {
result += `${text.slice(last, end)}[${number}]`
last = end
}
return {text: result + text.slice(last), sources}
}
const {text, sources} = addFootnotes(answer)
console.log(text)
sources.forEach((citation, i) => {
console.log(`[${i + 1}] ${citation.title} (${citation.source ?? 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.