Difference Between Source Chat and Regular Chat in LangGraph: Open Notebook Architecture Explained

Source Chat enriches LangGraph conversations with document-specific context and traceability metadata, while Regular Chat provides a lightweight, context-free messaging interface suitable for general dialogue.

Open Notebook leverages LangGraph to implement two distinct conversational workflows within the same repository. Understanding the difference between source_chat and regular chat is essential for developers building grounded AI applications that require exact citations versus general-purpose assistance systems.

State Schema and Architectural Purpose

The fundamental architectural split begins with the state definitions governing each graph’s execution.

Regular Chat ThreadState

In open_notebook/graphs/chat.py, the ThreadState schema maintains a minimal footprint:

• messages: The conversation history
• notebook: Optional notebook association
• context and context_config: Generic context configuration flags
• model_override: Optional LLM specification for the session

This lean state supports free-form brainstorming and assistance without external document dependencies.

Source Chat SourceChatState

In open_notebook/graphs/source_chat.py, SourceChatState extends the base state with fields for document grounding:

• source_id: Unique identifier for the referenced document
• source: The complete source object containing full text and metadata
• insights: Extracted knowledge items associated with the source
• context_indicators: A mapping structure tracking which source, insight, and note IDs contributed to each response
• context: The pre-built formatted string injected into prompts

These additions enable persistent document grounding and answer traceability across conversation turns.

Context Construction Methodology

Regular Chat Context Handling

Regular Chat provides no explicit context-building mechanism. The graph passes only the system prompt—defined in the chat/system Jinja2 template—and the message list to provision_langchain_model. The model receives no external document text unless manually pasted into user messages.

Source Chat Context Building

Source Chat implements a retrieval-augmented generation (RAG) pipeline. Before each inference cycle, it invokes ContextBuilder from open_notebook/utils/context_builder.py to:

1. Retrieve the source’s full text from the database
2. Collect associated insights and metadata
3. Format the assembled context using the source_chat/system template

This template injects the source, insights, and context variables directly into the prompt, ensuring the language model receives complete document grounding with precise citation markers.

Response Payloads and Traceability

The return structures differ significantly in analytical utility for downstream applications.

Regular Chat, implemented in open_notebook/graphs/chat.py, returns a minimal payload: {"messages": [...]} containing only the cleaned AI message content. This suits simple chat interfaces requiring no attribution or source verification.

Source Chat returns a comprehensive payload including:

• The AI message content
• The complete source object for downstream reference
• The list of insights extracted during context building
• The raw formatted context string actually sent to the model
• context_indicators: A structured map exposing exactly which sources, insights, and notes contributed to the generated answer

This traceability makes Source Chat ideal for academic research, legal analysis, and professional workflows requiring citation-ready responses.

API Endpoints and Session Management

Regular Chat Routing

Regular Chat exposes REST endpoints under /chat via api/routers/chat.py. Sessions persist using a single graph checkpoint keyed by a thread ID (chat session ID), storing only message history and configuration parameters. This creates a lightweight, ephemeral conversation state.

Source Chat Routing

Source Chat exposes endpoints under /sources/{source_id}/chat/... via api/routers/source_chat.py. It maintains a separate source_chat_graph checkpoint that persists the enriched SourceChatState, including document bindings and insight references, alongside the standard thread ID. This ensures conversation continuity remains anchored to the specific source document.

Implementation Examples

Source-Grounded Chat Session

The following Python client demonstrates the Source Chat API using explicit document binding:

import httpx

BASE = "http://localhost:5055"

# 1️⃣ Create a session for source "source:1234"

resp = httpx.post(
    f"{BASE}/sources/1234/chat/sessions",
    json={"title": "Paper QA", "model_override": "gpt-4o"},
)
session = resp.json()
session_id = session["id"]

# 2️⃣ Send a message and stream the response

msg = {"message": "What is the main hypothesis of this paper?"}
stream = httpx.post(
    f"{BASE}/sources/1234/chat/sessions/{session_id}/messages",
    json=msg,
    stream=True,
)
for line in stream.iter_lines():
    print(line)          # SSE events: user_message, ai_message, context_indicators, complete

Standard Chat Session

Compare this with the Regular Chat implementation for context-free dialogue:

resp = httpx.post(
    "http://localhost:5055/chat/sessions",
    json={"title": "Free chat"},
)
session_id = resp.json()["id"]

msg = {"message": "Tell me a joke."}
chat = httpx.post(
    f"http://localhost:5055/chat/sessions/{session_id}/messages",
    json=msg,
).json()
print(chat["messages"].content)   # Only the AI reply

Summary

• Source Chat binds conversations to specific documents using SourceChatState, providing citation-ready responses through ContextBuilder and traceable context_indicators showing exactly which content contributed to answers.

• Regular Chat uses lightweight ThreadState defined in open_notebook/graphs/chat.py for context-free dialogue, returning only message content without document references or attribution maps.

• Both architectures share the same provision_langchain_model utility but differ in template selection (source_chat/system versus chat/system) and checkpoint persistence mechanisms (source_chat_graph versus graph).

• API routes reflect this architectural separation: /sources/{source_id}/chat/... for grounded, attributable conversations versus /chat for general assistance.

Frequently Asked Questions

What is the primary architectural difference between source_chat and regular chat in LangGraph?

Source Chat extends the base graph with document-specific state management and retrieval-augmented generation capabilities. While Regular Chat in open_notebook/graphs/chat.py maintains only message history in ThreadState, Source Chat in open_notebook/graphs/source_chat.py utilizes SourceChatState to persist source_id, insights, and context_indicators, enabling persistent document grounding across conversation turns.

How does Source Chat build context differently than Regular Chat?

Source Chat explicitly invokes ContextBuilder from open_notebook/utils/context_builder.py to pull full document text, metadata, and associated insights before each language model call, formatting them via the source_chat/system template. Regular Chat skips this retrieval step entirely, passing only the conversation history and generic system prompt to provision_langchain_model without external document context.

When should I use Source Chat versus Regular Chat in Open Notebook?

Use Source Chat when building applications requiring answer faithfulness, citation capabilities, or grounded Q&A against specific documents like PDFs, web pages, or YouTube transcripts. Use Regular Chat for brainstorming sessions, creative writing assistance, or general dialogue where document references are unnecessary and minimal latency is preferred.

Can Regular Chat access source documents if I manually include them in messages?

No. While you can paste document text into user messages manually, Regular Chat lacks the ContextBuilder integration and context_indicators tracking found in open_notebook/graphs/source_chat.py. Without these components, the system cannot maintain persistent source bindings, generate traceability metadata, or utilize the source_chat/system template for structured grounding, making citations impossible.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}