Citation Configuration and Behavior in Brainfish Search Responses

Overview

This article describes how citation functionality works in Brainfish search responses, including the three supported citation modes, how each behaves, and key implications for accuracy and user experience.

Citation Modes

Brainfish currently supports three distinct citation configurations:

1. Citations enabled via settings
2. Citations disabled via settings (top sources only)
3. Inline citations via custom instructions

Each mode affects how sources are selected, displayed, and interpreted.

---

1. Citations Enabled via Settings

When citations are turned on in the settings:

• The response includes proper citations that indicate exactly which documents were actually used to generate the answer.
• Citations are reliable for tracing the origin of information in the response.

Behavior

• The model generates an answer based on retrieved documents.
• The system then attaches citations specifically for the documents that directly contributed to the final answer.
• Users can trust that a cited document was used in the reasoning process, not just retrieved.

When to Use

Enable this mode when:

• You need auditable, trustworthy answers.
• You want users to be able to quickly confirm information in the original source documents.
• Compliance, governance, or quality review requires traceable sources.

---

2. Citations Disabled via Settings (Top 4 Search Sources)

When citations are turned off in the settings:

• The system does not show true answer-level citations.
• Instead, it returns the top 4 search sources based purely on embedding similarity to the user’s query.
• These sources may or may not have been used to generate the final answer.

Behavior

• The model still uses retrieved documents to form an answer.
• However, the list of sources shown is simply the top 4 documents most similar to the user query embedding.
• The relevance score displayed reflects query-to-document similarity, not the document’s actual role in producing the answer.

Important Caveats

• Not guaranteed used in the answer: A displayed source might not have influenced the answer at all.
• Score is not fully accurate for answer relevance: The score only measures how close the user query embedding is to the document embedding.
• Do not treat these sources as authoritative citations; they are search hints, not a provenance trail.

When to Use

Use this mode when:

• You want a simpler, less opinionated UI that just shows “related documents.”
• You do not need strict source traceability.
• You are comfortable with users seeing likely-relevant but not guaranteed-used documents.

---

3. Inline Citations via Custom Instructions

Inline citations are implemented by adding specific instructions in the custom instructions for the assistant.

When configured, the system automatically:

• Adds citation numbers (for example, [1], [2]) within the response.
• Makes these citation numbers clickable links that lead to the underlying documents.
• Places citations within step headings and key points to highlight where information comes from.

Behavior

• The inline citation style is enforced at the prompt/instructions level.
• The underlying citation logic can still be controlled via settings, meaning:
  • You can pair inline styling with true answer-based citations, or
  • You can adapt it alongside other citation configuration options.

Implementation Notes

• Inline citations are supported directly in the codebase via a pull request that:
  • Adds inline citation formatting behavior to the assistant.
  • Allows this behavior to be optionally controlled via settings.
• Custom instructions determine:
  • When and how citation numbers appear.
  • Where links are embedded (e.g., headings, bullet points, or specific claims).

When to Use

Use inline citations when you want:

• A documentation-like experience with numbered references.
• Users to quickly jump from a statement to the supporting document via clickable links.
• Citations to appear in structured parts of the answer, such as:
  • Step titles in a how-to guide
  • Key recommendations
  • Major conclusions and definitions

---

Choosing the Right Citation Mode

Consider the following when selecting a configuration:

• Need for traceability
  • High: Enable citations via settings; optionally add inline format via custom instructions.
  • Medium/Low: Disable citations and rely on top 4 search sources as suggestions.
• User experience expectations
  • Documentation-style, formal: Use inline citations with clickable numbered references.
  • Simple, search-like: Show top related sources only.
• Accuracy requirements
  • If users must know exactly which sources were used, do not rely solely on the “top 4 search sources” mode.

---

Key Takeaways

• There are three distinct citation behaviors: full citations, top-4 search sources, and inline citations via custom instructions.
• With citations enabled, each citation reflects a document that truly influenced the answer.
• With citations disabled, the displayed sources are similar to the query but may not be used in the answer; their scores reflect embedding similarity only.
• Inline citations provide a structured, clickable way to show sources within headings and key points and can be controlled through both custom instructions and settings.