ARCANA References#

Parse GWDG ARCANA reference blocks from chat-completion content.

When a request is routed through GWDG SAIA’s ARCANA (RAG) gateway, the gateway appends a verbose References: block to the assistant’s reply — one [RREFn] <filename>.md (<distance>) line per retrieved chunk, followed by that chunk’s body. This module turns that GWDG-specific wire shape into structured data, leaving rendering and filename interpretation to the caller: a filename’s meaning depends on your own corpus, and presentation depends on your own UI, so neither belongs here.

The module is pure and dependency-free (no HTTP, no I/O), so it is safe to import into any environment — including an async server — without pulling in a transport layer.

Example:

from saia_python import parse_arcana_references

parsed = parse_arcana_references(message_content)
if parsed.matched:
    print(parsed.prose)            # the answer, References block removed
    for ref in parsed.references:  # structured citations
        print(ref.n, ref.filename, ref.distance)
class saia_python.arcana_references.ArcanaReference(n: int, filename: str, distance: float | None = None)[source]#

A single parsed ARCANA citation.

Variables:

  • n (int) – The RREFn reference number emitted by the gateway.

  • filename (str) – The retrieved chunk’s source filename (e.g. "onkopedia_....md"). Deriving a label or URL from it is the caller’s responsibility — it depends on your corpus.

  • distance (float | None) – The retrieval distance score the gateway reports in parentheses, or None if it could not be parsed as a float.

n: int#
filename: str#
distance: float | None = None#
class saia_python.arcana_references.ParsedReferences(matched: bool, prose: str, references: list[ArcanaReference] = <factory>, references_block: str = '')[source]#

The result of splitting assistant content around the References block.

Variables:

  • matched (bool) – Whether a References: block was found.

  • prose (str) – The assistant content with the References block removed (the substring before the marker). Equal to the full input when matched is False. Note this still includes any trailing horizontal-rule line the gateway inserts before References: — stripping that is a rendering concern left to the caller.

  • references (list[saia_python.arcana_references.ArcanaReference]) – Parsed, de-duplicated citations, ordered by n.

  • references_block (str) – The raw References block (marker to end of input), or "" when matched is False.

matched: bool#
prose: str#
references: list[ArcanaReference]#
references_block: str = ''#
saia_python.arcana_references.parse_arcana_references(content: str) → ParsedReferences[source]#

Split assistant content into prose and structured references.

Locates the GWDG References: marker; everything before it is prose, everything from it onward is parsed into ArcanaReference entries. Conservative: if no marker is present, returns the content unchanged as prose with matched=False and no references.

Parameters:

content – The assistant message content from an ARCANA-routed reply.

Returns:

A ParsedReferences.

saia_python.arcana_references.parse_reference_entries(block: str, *, dedupe: bool = True) → list[ArcanaReference][source]#

Parse [RREFn] <filename>.md (<distance>) entries from block.

Parameters:

  • block – Text containing one or more reference entry lines (typically the References block, but any text works — non-matching lines are ignored).

  • dedupe – When True (default), collapse repeated filenames to a single entry keeping the lowest n (the gateway lists a filename once per retrieved chunk, so one document can appear several times); the result is ordered by n. When False, every matching entry is returned in document order.

Returns:

A list of ArcanaReference.

saia_python.arcana_references.is_arcana_event(tool_call: dict) → bool[source]#

Return True if tool_call is a GWDG arcana.event beacon.

GWDG ARCANA streams retrieval-lifecycle markers (accessing / done) as tool_calls whose function name starts with arcana.event. These are status signals, not real citations (the actual references are baked into the message content as [RREFn] markers), so consumers typically filter them out before rendering.