rag.core.citations
==================

.. py:module:: rag.core.citations

.. autoapi-nested-parse::

   Citation helpers for retrieved LlamaIndex nodes.



Attributes
----------

.. autoapisummary::

   rag.core.citations.UNKNOWN_FILE_NAME
   rag.core.citations.DEFAULT_SNIPPET_CHARS


Classes
-------

.. autoapisummary::

   rag.core.citations.FileMetadataKey
   rag.core.citations.PageMetadataKey
   rag.core.citations.Citation


Functions
---------

.. autoapisummary::

   rag.core.citations.citations_from_nodes
   rag.core.citations.format_citations


Module Contents
---------------

.. py:class:: FileMetadataKey

   Bases: :py:obj:`enum.StrEnum`


   LlamaIndex / loader metadata keys that may hold a file path or name.


   .. py:attribute:: FILE_NAME
      :value: 'file_name'



   .. py:attribute:: FILENAME
      :value: 'filename'



   .. py:attribute:: FILE_PATH
      :value: 'file_path'



   .. py:attribute:: SOURCE
      :value: 'source'



.. py:class:: PageMetadataKey

   Bases: :py:obj:`enum.StrEnum`


   LlamaIndex / pypdf metadata keys that may hold a page number.


   .. py:attribute:: PAGE_LABEL
      :value: 'page_label'



   .. py:attribute:: PAGE
      :value: 'page'



   .. py:attribute:: PAGE_NUMBER
      :value: 'page_number'



.. py:data:: UNKNOWN_FILE_NAME
   :type:  Final
   :value: 'unknown'


.. py:data:: DEFAULT_SNIPPET_CHARS
   :type:  Final
   :value: 280


.. py:class:: Citation

   A single retrieved source used to ground an answer.

   :ivar file_name: PDF file name (or path basename).
   :vartype file_name: str
   :ivar page: 1-based page number when available.
   :vartype page: int or None
   :ivar score: Retriever score when available.
   :vartype score: float or None
   :ivar snippet: Short text excerpt from the chunk.

   :vartype snippet: str


   .. py:attribute:: file_name
      :type:  str


   .. py:attribute:: page
      :type:  int | None


   .. py:attribute:: score
      :type:  float | None


   .. py:attribute:: snippet
      :type:  str


.. py:function:: citations_from_nodes(*, nodes: collections.abc.Sequence[Any], max_snippet_chars: int = DEFAULT_SNIPPET_CHARS) -> list[Citation]

   Convert LlamaIndex ``NodeWithScore`` objects into citations.

   :param nodes: Retrieved nodes (typically ``NodeWithScore``).
   :type nodes: Sequence
   :param max_snippet_chars: Max characters for each snippet.
   :type max_snippet_chars: int

   :returns: Ordered citations matching retrieval order.
   :rtype: list of Citation


.. py:function:: format_citations(*, citations: collections.abc.Sequence[Citation]) -> str

   Render citations as a markdown bullet list.

   :param citations: Citations to format.
   :type citations: Sequence of Citation

   :returns: Markdown string (empty when there are no citations).
   :rtype: str