Citation

Type

Where a retrieved passage came from: document, page, heading path, and a stable on-domain link.

Where a retrieved chunk came from, and enough to show the user the source. Always render it, since retrieval is approximate: a clickable citation turns an answer into something the reader can check. url is a stable on-domain link you can drop straight into an <a href>, and (documentId, chunkIndex) is the stable identity of a chunk, so key an eval set or regression check on that rather than on the chunk text, which moves when a corpus is re-chunked.

Citation.ts

interface Citation {
  documentId: string
  filename: string | null
  pageNumber: number | null
  chunkIndex: number | null
  headingPath: string[]
  boundingBox?: { topLeftX, topLeftY, bottomRightX, bottomRightY }
  url: string
}

Fields

documentId

string

The source document. With chunkIndex, the stable identity of a chunk.

filename

string | null

Original filename, when known.

pageNumber

number | null

1-based page. Null for formats with no pagination, like plain text and html.

chunkIndex

number | null

0-based position in the document. Key eval sets on (documentId, chunkIndex), not on text.

headingPath

string[]

Enclosing headings, outermost first.

boundingBox?

{ ...corners }

Region of the page, when the format had a layout to measure, like a PDF. Precise enough to highlight.

url

string

Stable, on-domain link to the source. A same-origin logged-in request authorizes automatically.

Link to the source

<a href={hit.citation.url}>
  {hit.citation.filename} · p.{hit.citation.pageNumber}
</a>