Skip to content

Stop Your AI from Lying: How to Build Trustworthy RAG Systems with Verifiable Citations

Generative AI is transforming how we access information, offering a tantalizing promise: instant, articulate answers to complex questions. Imagine an AI assistant that can summarize your company's entire knowledge base in seconds or provide legal precedents from thousands of case files. Powerful, right? But there's a dark side to this magic: AI Hallucination.

Without a clear path to verify its claims, your powerful AI becomes a confident storyteller, not a trusted expert. It might sound incredibly convincing, but how do you know if what it's telling you is actually true? This "trust deficit" is the biggest hurdle for enterprise AI adoption, and it's where citations become your most critical tool.

The AI's Dirty Little Secret: Why You Can't Trust Your RAG System (Yet)

When you build a Retrieval-Augmented Generation (RAG) system, you're essentially giving a Large Language Model (LLM) access to a private, specialized library of information. You ask it a question, it sifts through relevant documents (the "retrieval" part), and then it crafts an answer (the "generation" part).

The problem? The LLM is a black box. It doesn't inherently know which specific sentences in its retrieved context led to its answer. It synthesizes, it summarizes, and sometimes, it invents. This invention is what we call hallucination – a confident, plausible-sounding answer that has no basis in the source material.

Think of it this way:

  • Researcher A (RAG without Citations): You ask for complex financial data. They return a beautifully written summary: "In Q3 2019, revenue increased 15% due to a successful product launch." When you ask for proof, they shrug, "I read it in the archives." You're left to re-read everything yourself, defeating the purpose of hiring them.

  • Researcher B (RAG with Citations): They provide the same summary but with footnotes: "In Q3 2019, revenue increased 15% [1] due to a successful product launch [2]." At the bottom, they list: [1] 2019 Annual Report, page 47, paragraph 2. and [2] Product Launch Post-Mortem Memo, October 2019, Executive Summary. Now, you have instant trust and verifiability.

Citations are the digital "receipts" that prove your AI's answer isn't a creative invention but a grounded synthesis of verifiable source material. They transform your RAG system from a "magic box" into a transparent, trustworthy research assistant.

Citations: Your AI's Digital Receipts for Truth

At its core, a RAG system relies on vector embeddings. These are numerical representations of text chunks that capture their semantic meaning. Imagine your entire document corpus (PDFs, web pages, internal reports) as a massive, unstructured database. Vector embeddings turn this into a highly structured, searchable index – a global hash map where the "key" is the semantic meaning (the vector) and the "value" is a rich object containing:

  1. The actual text content of the chunk.
  2. Crucial Metadata: Information about where this chunk came from (source file, page number, URL).
  3. A Unique Identifier: A primary key for this specific chunk.
// A conceptual representation of what's stored in our vector database for each chunk.
type VectorStoreRecord = {
  // The vector embedding (the "hash key") for semantic search.
  embedding: number[]; 

  // The actual text content (the "hash value").
  content: string; 

  // The metadata, which is the foundation of our citation system.
  metadata: {
    source: string; // e.g., "2023-Annual-Report.pdf"
    chunkId: string; // e.g., "2023-Annual-Report.pdf_chunk_42"
    page: number; // e.g., 42
    title: string; // e.g., "Annual Report 2023"
    url?: string; // If the source is a web page
    lastModified: Date;
  };
};

When a user asks a question, your system performs a semantic search using the query's embedding to find the most relevant VectorStoreRecord objects. The retrieved metadata is the raw ingredient for your citations, with the chunkId being the unique pointer back to the source of truth.

How to Build a Trustworthy AI: The Technical Blueprint

The challenge lies in bridging the gap between the retrieved source chunks and the LLM's generated answer. The LLM doesn't inherently understand your chunkIds; it just sees a block of context. You need a system to ensure the LLM's output is "annotated" with source information.

There are two primary strategies:

  1. Post-Processing (Backend Approach): The LLM generates a clean, unadorned text response. After generation, your application code analyzes the generated text, matches it back to the original retrieved chunks, and programmatically inserts citations.
  2. In-Generation (Frontend Approach): You prompt the LLM to generate the answer and the citations simultaneously, often by asking it to output a special format (like Markdown [citation] or JSON) that includes the source identifiers directly.

The linchpin of both approaches is the Unique Chunk Identifier. Without it, the system falls apart. This chunkId is the foreign key that connects the generated answer back to the source of truth, enabling full traceability and verifiability.

Code in Action: A TypeScript Example for Verifiable AI

To achieve robust citations, we force the LLM to output a structured response (JSON) containing both the answer text and an array of source references.

First, define your data structures:

/**
 * Represents a single segment of text retrieved from a vector database.
 */
type SourceChunk = {
  id: string;          // Unique identifier (e.g., UUID or Vector ID)
  content: string;     // The actual text content
  metadata: {
    source: string;    // e.g., "report_2023.pdf" or "https://example.com"
    page?: number;     // Optional page number
  };
};

// The structured output we expect from the LLM to ensure citations are handled.
// We instruct the LLM to output JSON matching this interface.
interface LLMStructuredResponse {
  answer: string; // The natural language response
  citations: string[]; // Array of IDs referencing the SourceChunk.id
}

Now, let's look at the core logic for fetching, generating, and reconciling citations:

// Mock Vector Database Retrieval
function mockVectorSearch(query: string): SourceChunk[] {
  // In a real app, this queries Pinecone, Weaviate, or Qdrant.
  return [
    {
      id: "chunk_001",
      content: "The sky is blue because of Rayleigh scattering.",
      metadata: { source: "science_manual.pdf", page: 1 },
    },
    {
      id: "chunk_002",
      content: "Photosynthesis requires sunlight, water, and carbon dioxide.",
      metadata: { source: "biology_101.pdf", page: 42 },
    },
  ];
}

// Mock LLM Inference with Citation Generation
async function mockLLMInference(
  query: string,
  context: SourceChunk[]
): Promise<LLMStructuredResponse> {
  await new Promise((r) => setTimeout(r, 100)); // Simulate delay

  // CRITICAL: Prompt engineering here instructs the LLM to output JSON
  // and include relevant chunk IDs.
  return {
    answer: "The sky appears blue due to a phenomenon called Rayleigh scattering.",
    citations: ["chunk_001"], // LLM identifies 'chunk_001' as the source
  };
}

/**
 * Fetches data, generates an answer, and hydrates the response with source links.
 * This mimics a Next.js Server Action or API Route handler.
 */
async function generateCitedAnswer(userQuery: string) {
  // Step 1: Retrieve relevant chunks from Vector DB
  const retrievedChunks = mockVectorSearch(userQuery);

  // Step 2: Send query + context to LLM to get structured answer + citation IDs
  const llmResponse = await mockLLMInference(userQuery, retrievedChunks);

  // Step 3: Reconciliation (The Citation Step)
  // Map LLM's citation IDs back to full metadata from retrieved chunks.
  const sources = llmResponse.citations.map((id) => {
    const foundChunk = retrievedChunks.find((c) => c.id === id);

    if (!foundChunk) {
      console.warn(`Hallucinated citation ID: ${id}`); // LLM returned an ID not in context
      return null;
    }

    return {
      id: foundChunk.id,
      sourceName: foundChunk.metadata.source,
      page: foundChunk.metadata.page,
    };
  }).filter(Boolean); // Remove any nulls (hallucinated IDs)

  // Step 4: Return the fully hydrated object to the frontend
  return {
    answer: llmResponse.answer,
    sources: sources,
  };
}

// Simulating a React Component rendering the result
function renderUI(result: Awaited<ReturnType<typeof generateCitedAnswer>>) {
  console.log("\n--- RENDERED UI ---");
  console.log(`Answer: ${result.answer}`);

  if (result.sources.length > 0) {
    console.log("Sources:");
    result.sources.forEach((src) => {
      // In a real React app, this would be: <a href={`/view/${src.id}`}>Source</a>
      console.log(`- [${src.sourceName}, Page ${src.page}] (ID: ${src.id})`);
    });
  }
  console.log("-------------------\n");
}

(async () => {
  const userQuery = "Why is the sky blue?";
  const finalData = await generateCitedAnswer(userQuery);
  renderUI(finalData);
})();

This flow ensures that when the frontend renders the AI's answer, it also has a verified list of sources, ready to be displayed as clickable links or tooltips.

Avoiding the AI Citation Traps: Common Pitfalls

Implementing citations isn't without its challenges. Watch out for these common pitfalls:

  1. Hallucinated JSON / IDs: LLMs can sometimes fail to output valid JSON or invent chunkIds that weren't in the provided context. Fix: Use robust validation (like Zod) on the LLM's output and filter out any invalid or unverified IDs.
  2. Vercel/AWS Timeouts (Streaming): If you perform the citation reconciliation after an LLM stream finishes, you might hit serverless function timeout limits for long responses. Fix: Perform vector search before streaming. For real-time citation mapping during a stream, embed IDs directly into the stream tokens and parse them client-side, or hydrate citations in a background job.
  3. Async/Await Loops in Rendering: Trying to fetch citation metadata directly within a React component's .map() function creates a waterfall of requests and can break React Server Component rules. Fix: Always resolve all citation metadata on the server before sending the data to the client. The client should receive a fully hydrated array of sources.

Beyond the Basics: Advanced RAG with LangGraph and Streaming

For production-grade enterprise RAG applications, especially those requiring complex workflows, state management, and real-time user experiences, you'll need more advanced tools. Let's look at an example using LangGraph for stateful orchestration and Vercel AI SDK for streaming in a Next.js environment.

Imagine a "Smart Support Agent" in a SaaS dashboard. This agent needs to answer user queries using internal documentation, cite its sources, and potentially allow for iterative refinement.

The architecture involves: * LangGraph: To define and manage the multi-step RAG workflow as a graph of nodes. It also supports checkpointing for resumability and debugging. * HNSWLib: A lightweight, in-memory vector store for semantic search (easily replaceable with Pinecone, Weaviate, etc., in production). * OpenAI Embeddings & ChatOpenAI: For generating vectors and LLM inference. * Vercel AI SDK: For efficient streaming of LLM responses to the client.

The core idea is to embed unique chunkIds and sourceLinks into the retrieved documents' metadata. The LLM is then prompted to reference these IDs directly in its streamed output (e.g., [1], [2]). The frontend parses these markers to render interactive citations.

The Advanced Smart Agent: Code Walkthrough

This comprehensive example demonstrates a Next.js API route (app/api/chat/route.ts) acting as the backend for a smart support agent.

// app/api/chat/route.ts
// Target: Next.js App Router (Server Component / API Route)
// Dependencies: @langchain/langgraph, @langchain/community, langchain, ai, zod

import { NextRequest } from 'next/server';
import { StreamingTextResponse } from 'ai';
import { z } from 'zod';
import { StateGraph, END, MessageSend } from '@langchain/langgraph';
import { HNSWLib } from '@langchain/community/vectorstores/hnswlib';
import { OpenAIEmbeddings, ChatOpenAI } from '@langchain/openai';
import { ChatPromptTemplate } from '@langchain/core/prompts';
import { Document } from '@langchain/core/documents';

// ============================================================================
// 1. INITIALIZATION & STATE DEFINITION
// ============================================================================

/**
 * Defines the state schema for our LangGraph.
 * In a production app, this state is hydrated from the Checkpointer.
 * We include `retrievedDocs` to store metadata (chunkId, source) alongside text.
 */
const StateSchema = z.object({
  input: z.string(),
  retrievedDocs: z.array(z.object({
    pageContent: z.string(),
    metadata: z.object({
      chunkId: z.string(), // Unique identifier for citation
      sourceLink: z.string(), // URL to the specific document section
      sourceName: z.string() // Human-readable name
    })
  })),
  // The final answer with citations injected
  answer: z.string().optional()
});

type AgentState = z.infer<typeof StateSchema>;

/**
 * Mock Data Initialization
 * In production, this would be a connection to a persistent Vector DB (Pinecone, Weaviate).
 * We use HNSWLib here for a self-contained, file-system-based demo.
 */
let vectorStore: HNSWLib | null = null;
const embeddings = new OpenAIEmbeddings();

async function initializeVectorStore(): Promise<HNSWLib> {
  if (vectorStore) return vectorStore;

  const docs = [
    {
      pageContent: "To reset your password, go to Settings > Security and click 'Reset Password'. You will receive an email verification link.",
      metadata: { chunkId: "doc_101_chunk_1", sourceLink: "/docs/security#reset", sourceName: "Security Guide" }
    },
    {
      pageContent: "A subscription plan can be upgraded at any time from your 'Billing' page. Downgrades take effect at the end of your current billing cycle.",
      metadata: { chunkId: "doc_102_chunk_1", sourceLink: "/docs/billing#plans", sourceName: "Billing FAQ" }
    },
    {
      pageContent: "Our API supports OAuth2 for authentication. Detailed documentation is available at developer.example.com/api/auth.",
      metadata: { chunkId: "doc_103_chunk_1", sourceLink: "/docs/api#auth", sourceName: "Developer Docs" }
    },
    {
        pageContent: "For advanced troubleshooting, please contact our support team via the 'Help' widget on the bottom right of your dashboard.",
        metadata: { chunkId: "doc_104_chunk_1", sourceLink: "/support", sourceName: "Support Contact" }
    }
  ];

  vectorStore = await HNSWLib.fromDocuments(docs, embeddings);
  return vectorStore;
}

// Initialize the LLM
const chatModel = new ChatOpenAI({
  modelName: "gpt-4o", // Or gpt-3.5-turbo, etc.
  temperature: 0.1,
  streaming: true,
});

// ============================================================================
// 2. LANGGRAPH NODES
// ============================================================================

/**
 * Retrieval Node: Fetches relevant documents from the vector store.
 */
async function retrievalNode(state: AgentState): Promise<Partial<AgentState>> {
  console.log("---RETRIEVAL NODE---");
  const { input } = state;
  const db = await initializeVectorStore();
  const retrievedDocs = await db.similaritySearch(input, 4); // Retrieve top 4 relevant chunks

  // Ensure metadata is correctly typed for the state schema
  const formattedDocs = retrievedDocs.map(doc => ({
    pageContent: doc.pageContent,
    metadata: {
      chunkId: doc.metadata.chunkId as string,
      sourceLink: doc.metadata.sourceLink as string,
      sourceName: doc.metadata.sourceName as string
    }
  }));

  return { retrievedDocs: formattedDocs };
}

/**
 * Generation Node: Generates the answer using the LLM and retrieved context.
 * This node is responsible for instructing the LLM to include citation markers.
 */
async function generationNode(state: AgentState): Promise<Partial<AgentState>> {
  console.log("---GENERATION NODE---");
  const { input, retrievedDocs } = state;

  const context = retrievedDocs.map((doc, i) =>
    `Source ${i + 1} (ID: ${doc.metadata.chunkId}, Name: ${doc.metadata.sourceName}):\n${doc.pageContent}`
  ).join("\n\n");

  const prompt = ChatPromptTemplate.fromMessages([
    ["system", `You are a helpful support agent. Answer the user's question ONLY based on the provided context.
    Cite your sources by including the SOURCE ID in brackets, e.g., [doc_101_chunk_1], immediately after the relevant sentence or phrase.
    If you cannot find an answer in the context, politely state that you don't have enough information.

    Context:
    {context}`],
    ["user", "{question}"],
  ]);

  const chain = prompt.pipe(chatModel);
  const stream = await chain.stream({ context, question: input });

  // The actual streaming of the answer will happen outside this node
  // This node just prepares the chain. The actual answer will be accumulated
  // and streamed by the `streamResponse` function.
  // For LangGraph, we'll return an empty partial state here.
  // The full answer will be assembled during the streaming process.
  return {}; // We handle the stream externally for Vercel AI SDK compatibility
}

// ============================================================================
// 3. GRAPH COMPILATION & CHECKPOINTING
// ============================================================================

const workflow = new StateGraph<AgentState>({
  channels: StateSchema,
})
  .addNode("retrieve", retrievalNode)
  .addNode("generate", generationNode);

workflow.setEntryPoint("retrieve");
workflow.addEdge("retrieve", "generate");
workflow.addConditionalEdges("generate", (state) => {
    // In a more complex graph, you might have conditions here.
    // For this simple RAG, we always end after generation.
    return END;
});

// Compile the graph
const graph = workflow.compile();

// For a real application, use a persistent checkpointer (e.g., Redis, Postgres)
// For this demo, we'll manage state in memory within the request context.
// LangGraph's checkpointer allows resuming workflows.
// const checkpointer = new MemorySaver(); // Example, not used directly in this streaming API route

// ============================================================================
// 4. STREAMING RESPONSE (Next.js API Route)
// ============================================================================

export async function POST(req: NextRequest) {
  try {
    const { messages } = await req.json();
    const lastMessage = messages[messages.length - 1].content;

    // Initialize state for this request
    const initialState: AgentState = {
      input: lastMessage,
      retrievedDocs: [],
      answer: undefined,
    };

    let fullAnswer = "";
    const sourceMap = new Map<string, { sourceName: string; sourceLink: string }>();

    // Execute the graph
    const stream = await graph.stream(initialState, {
      // Configure checkpointing if needed, but for a stateless API, we process full stream
    });

    // Create a TransformStream to process and format the output for the client
    const transformStream = new TransformStream({
      async transform(chunk, controller) {
        // LangGraph chunks contain node outputs. We care about the 'generate' node's output.
        if (chunk.output && chunk.output.retrievedDocs) {
          // Store retrieved docs metadata for client-side citation mapping
          chunk.output.retrievedDocs.forEach((doc: any) => {
            sourceMap.set(doc.metadata.chunkId, {
              sourceName: doc.metadata.sourceName,
              sourceLink: doc.metadata.sourceLink,
            });
          });
          // Send the source map to the client first, as a special JSON message
          controller.enqueue(JSON.stringify({ type: "sources", data: Object.fromEntries(sourceMap) }) + "\n");
        }

        // The LLM stream tokens come from the `generate` node
        if (chunk.output && chunk.output.answer) {
            // This path would be taken if the LLM output was fully generated by the node.
            // For streaming LLM, we need to access the `stream` property of the last node's output.
        }

        // Accessing the streamed tokens directly from the LLM via the graph's generator
        if (chunk.values?.generate && chunk.values.generate.stream) {
            for await (const token of chunk.values.generate.stream) {
                if (token.content) {
                    fullAnswer += token.content;
                    controller.enqueue(token.content); // Send token to client
                }
            }
        }
      },
      flush(controller) {
          // After the stream ends, ensure any final messages are sent
          console.log("Stream finished. Full answer generated.");
      }
    });

    // Pipe the LangGraph stream through our transform stream
    const readableStream = new ReadableStream({
        async start(controller) {
            for await (const chunk of stream) {
                await transformStream.writable.getWriter().write(chunk);
            }
            await transformStream.writable.getWriter().close();
            controller.close();
        },
    });

    return new StreamingTextResponse(readableStream);

  } catch (error) {
    console.error("Error in chat API:", error);
    return new Response(JSON.stringify({ error: (error as Error).message }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}

// ============================================================================
// 5. FRONTEND RENDERING (React Component Simulation)
// ============================================================================

// This would be a React client component, e.g., `components/ChatComponent.tsx`
/*
"use client";

import { useChat } from 'ai/react';
import React, { useState, useEffect } from 'react';

type SourceMetadata = {
  sourceName: string;
  sourceLink: string;
};

type SourceMap = { [chunkId: string]: SourceMetadata };

export function ChatComponent() {
  const [sourceMap, setSourceMap] = useState<SourceMap>({});
  const { messages, input, handleInputChange, handleSubmit, append } = useChat({
    api: '/api/chat',
    onStreamData: (data) => {
      // Check for special JSON messages containing source map
      try {
        const parsed = JSON.parse(data);
        if (parsed.type === "sources" && parsed.data) {
          setSourceMap(parsed.data);
        }
      } catch (e) {
        // Not a JSON message, just regular text token
      }
    }
  });

  const parseAndRenderMessage = (content: string) => {
    // Regex to find citation markers like [doc_101_chunk_1]
    const citationRegex = /\[(doc_\d+_\w+)\]/g;
    let lastIndex = 0;
    const parts: React.ReactNode[] = [];

    content.replace(citationRegex, (match, chunkId, offset) => {
      // Add text before the citation
      parts.push(content.substring(lastIndex, offset));
      lastIndex = offset + match.length;

      const source = sourceMap[chunkId];
      if (source) {
        parts.push(
          <a
            key={offset}
            href={source.sourceLink}
            target="_blank"
            rel="noopener noreferrer"
            className="text-blue-500 hover:underline"
            title={`Source: ${source.sourceName}`}
          >
            [{source.sourceName.substring(0, 3)}...]
          </a>
        );
      } else {
        parts.push(<span key={offset} className="text-gray-500">[Source Unknown]</span>);
      }
      return match;
    });

    parts.push(content.substring(lastIndex)); // Add any remaining text
    return parts;
  };

  return (
    <div className="flex flex-col h-screen p-4">
      <div className="flex-1 overflow-y-auto mb-4">
        {messages.map((m) => (
          <div key={m.id} className="mb-2">
            <strong className="font-semibold">{m.role === 'user' ? 'You: ' : 'AI: '}</strong>
            {parseAndRenderMessage(m.content)}
          </div>
        ))}
      </div>
      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          className="flex-1 p-2 border rounded shadow"
          value={input}
          placeholder="Ask about your dashboard..."
          onChange={handleInputChange}
        />
        <button type="submit" className="p-2 bg-blue-500 text-white rounded shadow">
          Send
        </button>
      </form>
    </div>
  );
}
*/

This advanced setup ensures that as the AI streams its answer, the client simultaneously receives the necessary source metadata. The frontend then dynamically parses the streamed text, identifying citation markers (like [doc_101_chunk_1]) and rendering them as interactive links using the received sourceMap.

The Future of Enterprise AI is Trustworthy

Citations are not just a technical detail; they are a fundamental requirement for building trust, enabling verifiability, and ensuring traceability in any serious enterprise RAG application. By grounding AI answers in transparent, auditable sources, you combat hallucination, empower users to verify information, and provide a critical audit trail for business decisions.

The journey to truly intelligent AI isn't just about bigger models; it's about building smarter, more reliable systems. Start integrating robust citation mechanisms into your RAG applications today, and unlock the true potential of AI as a trusted partner in discovery and decision-making.

The concepts and code demonstrated here are drawn directly from the comprehensive roadmap laid out in the book Master Your Data. Production RAG, Vector Databases, and Enterprise Search with JavaScript Amazon Link of the AI with JavaScript & TypeScript Series. The ebook is also on Leanpub.com: https://leanpub.com/RAGVectorDatabasesJSTypescript.

Code License: All code examples are released under the MIT License. Github repo.

Content Copyright: Copyright © 2026 Edgar Milvus | Privacy & Cookie Policy. All rights reserved.

All textual explanations, original diagrams, and illustrations are the intellectual property of the author. To support the maintenance of this site via AdSense, please read this content exclusively online. Copying, redistribution, or reproduction is strictly prohibited.