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

> Understand the difference between Source Chat and Regular Chat in LangGraph. Explore Source Chat for document context and traceability. Learn about Regular Chat for general dialogue.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: architecture
- Published: 2026-07-02

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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:

```python
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:

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/chat.py) maintains only message history in `ThreadState`, Source Chat in [`open_notebook/graphs/source_chat.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.