GitHub - pavelblank/ResearchNotebookLLM: 🔬 Private AI research assistant like Google NotebookLM but 100% local. Upload PDFs, URLs & YouTube. Ask questions grounded in your sources. 12-provider AI fallback. Works offline.

Your Private AI Research Assistant

Better than Google NotebookLM. Runs 100% on your own machine.

📄
Upload PDFs
_{URLs & YouTube too}

💬
Ask Questions
_{AI answers from your docs}

🔒
100% Private
_{Zero data leaves your PC}

🔗
12 AI Engines
_{Never goes offline}

No Docker. No cloud account. No subscription. No data upload. Everything runs on your machine, even the AI.

🚀 Quick Start · ✨ Features · 📋 Prerequisites · ⚙️ Settings · 🔒 Security · 📁 Structure

📸 Screenshots

_{🏠 Home: projects, stats, sidebar clock}

_{💬 Research Chat: grounded AI answers}

_{⚙️ Settings: AI engines, timezone, clock}

💡 Why ResearchNotebookLM?

"I was doing serious research: 30+ papers, 3 projects. Google NotebookLM was uploading everything to Google's servers. I wanted the same power, but private, free, and mine."

Pavel Blank, creator

The problem with cloud research tools:

📤 Your documents leave your machine the moment you upload them
🔒 You're locked to one AI. Google only offers Gemini, nothing else
💸 Free tiers run out when you actually need them
📶 Requires constant internet. No wifi, no research
🏢 Their servers, their rules. What happens to your data?

ResearchNotebookLM is the answer:

✅ PDFs, notes, and chat history never leave your disk
✅ 12 AI engines: OpenRouter, NVIDIA, DeepSeek, Gemma, or run 100% offline with Ollama
✅ No subscription, no limits, no account required
✅ Works on a plane, in a hospital, in a lab with no internet required
✅ Open source, so you can audit every line and change anything

🆚 ResearchNLM vs Google NotebookLM

Feature	ResearchNotebookLM	Google NotebookLM
🔒 Your data stays on your machine	✅ Always	❌ Uploaded to Google
🤖 Choose your AI model	✅ 12 providers + local Ollama	❌ Gemini only
💰 Free to use	✅ Free (use your own keys)	⚠️ Limited free tier
📁 Unlimited projects	✅ No limits	⚠️ Capped
🌐 Works offline	✅ Ollama local fallback	❌ Needs internet
🔧 Self-hostable	✅ Your server	❌ Google's cloud
📝 Notes system	✅ Built-in, expandable cards	✅ Built-in
🎥 YouTube ingestion	✅ Auto captions via yt-dlp	✅ Yes
🕐 Sidebar clock & timezone	✅ Configurable	❌ No
🔍 Cross-project file search	✅ Search files across all projects	❌ Per-notebook only
🛡️ API key security	✅ Masked in browser, never exposed	N/A

✨ Features in Detail

🤖 AI-Grounded Chat

Answers come only from your uploaded documents
AI is explicitly forbidden from using training data or outside knowledge
Says "Not found in provided sources" if the answer is not there
Cites the source title for every fact

🔗 12-Engine Fallback Chain

Providers are tried in order; if one fails, the next takes over automatically
Handles rate limits, outages, timeouts, and bad responses
Final fallback: local Ollama (works with no internet)
The system never stops mid-session

✨ Do More — AI Actions in Chat

Select one or more sources, then click any action — results appear instantly in Research Chat. Works from the right panel or the mobile bottom sheet:

Action	Output
📋 Briefing	Executive summary + key findings
🏷️ Key Themes	5+ themes with evidence per source
❓ FAQ	8 grounded questions & answers
📅 Timeline	Chronological events with dates
🗺 Mind Map	Hierarchical text knowledge tree
❓ Quiz	10-question multiple-choice test
🃏 Flashcards	12 study cards — Term / Definition
📊 Knowledge Stats	Concept scores, gaps, source overview

Type a keyword in chat (quiz, briefing, flashcard, timeline…) and it auto-expands to the full action — with your selected source scope applied.

📄 Multi-Source Ingestion

Type	Engine
PDF	Docling (OCR + tables) with pypdf fallback
Web URL	Trafilatura (full article text)
YouTube	yt-dlp (auto captions)
Text / Markdown	Direct paste or file upload

📖 Source Viewer

PDF button to read the original extracted text
MD button to view AI-converted Markdown (tables, headings preserved)
Opens in the left panel; the chat area stays full width

📝 Notes System

Save any AI answer as a note in one click
Write your own manual notes
Click a note card to expand the full content
Notes persist between sessions, stored per project

🔍 Smart Search

Searches project names and files inside projects
Results show file name and parent project
Click to navigate directly
Real-time as you type

🕐 Sidebar Clock & Timezone

Live time and date displayed in the sidebar
Fully configurable timezone (25+ regions)
Gear icon links directly to Clock settings
Stored in your browser, per-user, no server needed

🗑️ Trash & Restore

Deleting a project moves it to Trash (not permanent)
Restore from Settings > Trash at any time
Permanently delete when you are sure
Project data fully preserved until permanent delete

📊 Workspace Stats

Home page shows total Projects, Sources, and Notes at a glance
Per-project source count shown in sidebar (not chunk count)
"How it works" guide shown for new users

📋 Prerequisites

Nothing complex. You only need Python installed. Everything else is optional.

Requirement	Version	Required?	Notes
Python	3.10+	✅ Yes	python.org/downloads
Ollama	Any	⭐ Recommended	Local AI fallback. Get it at ollama.ai
OpenRouter key	n/a	💡 Optional	Free tier available, with much better AI quality
NVIDIA NIM key	n/a	💡 Optional	Free GPU inference. See build.nvidia.com
RAM	4 GB min	✅ Yes	8 GB recommended for large PDFs
Disk	~3 GB	✅ Yes	~2 GB for local AI model + your documents

🚀 Quick Start

⚡ Windows: One Click

Step 1 │ Download this repo
       │ Click green "Code" button > Download ZIP
       │ Extract to any folder

Step 2 │ Double-click  install.bat
       │ Installs Python packages + Ollama
       │ (takes ~5 min on first run)

Step 3 │ Double-click  start.bat
       │ Browser opens automatically

Step 4 │ Open  http://localhost:8080
       │ You're ready to research 🎉

That's it.

No Docker.
No cloud account.
No terminal needed.

Just double-click and go.

📖 Full Setup Guide → SETUP.md
_{Step-by-step for non-technical users}

🛠️ Manual Install (All Platforms)

🪟 Windows: Step by Step

# 1. Clone the repo
git clone https://github.com/pavelblank/ResearchNotebookLM.git
cd ResearchNotebookLM

# 2. Install Python packages
pip install -r requirements.txt

# 3. Install Ollama (local AI)
winget install Ollama.Ollama

# 4. Pull a local model (~2 GB)
ollama pull qwen2.5:3b

# 5. Copy config files
copy .env.example .env
copy data\providers.example.json data\providers.json

# 6. Run
python webapp\app.py

Then open: http://localhost:8080

🍎 macOS: Step by Step

# 1. Clone the repo
git clone https://github.com/pavelblank/ResearchNotebookLM.git
cd ResearchNotebookLM

# 2. Install Python packages
pip3 install -r requirements.txt

# 3. Install Ollama
brew install ollama

# 4. Pull a local model (~2 GB)
ollama pull qwen2.5:3b

# 5. Copy config files
cp .env.example .env
cp data/providers.example.json data/providers.json

# 6. Run
ollama serve &
python3 webapp/app.py

Then open: http://localhost:8080

🐧 Linux: Step by Step

# 1. Clone the repo
git clone https://github.com/pavelblank/ResearchNotebookLM.git
cd ResearchNotebookLM

# 2. Install Python packages
pip3 install -r requirements.txt

# 3. Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 4. Pull a local model (~2 GB)
ollama pull qwen2.5:3b

# 5. Copy config files
cp .env.example .env
cp data/providers.example.json data/providers.json

# 6. Run
ollama serve &
python3 webapp/app.py

Then open: http://localhost:8080

⚠️ First install note: Docling (PDF engine) downloads OCR models (~15 MB) on first PDF upload. This is a one-time download. All future uploads are fast.

🔑 Getting Free API Keys

The app works with Ollama only, no keys needed. But free cloud keys give significantly better AI quality.

OpenRouter

50+ free models (Gemini, Llama, Qwen, etc.)

Go to openrouter.ai and sign up
Dashboard > Keys > Create Key
Copy the key (sk-or-...)
App > Settings > AI Engines > paste key

Free tier includes Gemini 2.5 Flash, Llama 3, Qwen and more

NVIDIA NIM

Free GPU inference, no credit card needed

Go to build.nvidia.com and sign up
Click Get API Key
Copy the key (nvapi-...)
App > Settings > AI Engines > paste key

Free tier includes DeepSeek, Gemma, GLM, MiniMax and more

🏗️ How It Works

  ┌─────────────────────────────────────────────────────────────────┐
  │                    YOUR DOCUMENT COMES IN                        │
  │                                                                  │
  │   PDF  ──▶  Docling (OCR + tables + headings)  ──▶  Markdown    │
  │   URL  ──▶  Trafilatura (full article text)     ──▶  Plain text  │
  │   YouTube ▶  yt-dlp (auto captions)             ──▶  Transcript  │
  └─────────────────────────────┬───────────────────────────────────┘
                                │  text chunks
                                ▼
  ┌─────────────────────────────────────────────────────────────────┐
  │                   ChromaDB  (local vector DB)                    │
  │   Text is split into chunks and stored as embeddings on disk     │
  └─────────────────────────────┬───────────────────────────────────┘
                                │
                    You ask a question
                                │
                                ▼
  ┌─────────────────────────────────────────────────────────────────┐
  │              Semantic Search (cosine similarity)                 │
  │         Top 8 most relevant chunks retrieved                     │
  └─────────────────────────────┬───────────────────────────────────┘
                                │  source excerpts
                                ▼
  ┌─────────────────────────────────────────────────────────────────┐
  │                    AI Fallback Chain                             │
  │                                                                  │
  │  1. OpenRouter  ──fail──▶  2. NVIDIA NIM  ──fail──▶  3. ...    │
  │                                               ──fail──▶  Ollama │
  │                                                                  │
  │  Each failure is handled silently; next provider takes over      │
  └─────────────────────────────┬───────────────────────────────────┘
                                │
                                ▼
         Answer grounded strictly in YOUR source excerpts
         AI cannot use internet, training data, or memory

⚙️ Settings & Configuration

In-App Settings

Open the app and click ⚙️ Settings in the sidebar.

Section	What You Can Do
AI Engines	Add, remove, enable/disable, reorder providers
Clock & Timezone	Choose your local timezone for the sidebar clock
Deleted Projects	Restore or permanently delete from Trash

Configuring AI Providers (`data/providers.json`)

Click to see full providers.json format

{
  "providers": [
    {
      "id": "p1",
      "name": "OR Gemini 2.5 Flash",
      "description": "Often free on OpenRouter",
      "url": "https://openrouter.ai/api/v1",
      "model": "google/gemini-2.5-flash",
      "api_key": "sk-or-YOUR_KEY_HERE",
      "enabled": true
    },
    {
      "id": "p2",
      "name": "NV DeepSeek V4",
      "description": "Free NVIDIA inference",
      "url": "https://integrate.api.nvidia.com/v1",
      "model": "deepseek-ai/deepseek-v4-flash",
      "api_key": "nvapi-YOUR_KEY_HERE",
      "enabled": true
    },
    {
      "id": "p3",
      "name": "Ollama Local",
      "description": "No key needed, works offline",
      "url": "http://localhost:11434",
      "model": "qwen2.5:3b",
      "api_key": "ollama",
      "enabled": true,
      "is_ollama": true
    }
  ]
}

Field reference:

Field	Required	Description
`id`	✅	Any unique string
`name`	✅	Display name in UI
`url`	✅	Base API URL (any OpenAI-compatible endpoint)
`model`	✅	Model ID for this provider
`api_key`	✅	Your key, or `"ollama"` for local
`enabled`	✅	`true` to use, `false` to skip
`is_ollama`	optional	`true` only for local Ollama entries

Any OpenAI-compatible API works: Groq, Together AI, Mistral, self-hosted vLLM, etc.

📍 Where to Update for New Versions

What changed	File to update	Action needed
New Python package added	`requirements.txt`	`pip install -r requirements.txt`
New AI provider available	`data/providers.json`	Add via Settings > AI Engines
UI / template change	`webapp/templates/*.html`	Browser refresh (auto-reloads)
Backend logic change	`webapp/app.py` or `engine/*.py`	Restart: `stop.bat` then `start.bat`
New version released	Auto-updated	`git pull origin main` then restart

# To update to latest version
git pull origin main
pip install -r requirements.txt
# Then restart start.bat

📁 Project Structure

ResearchNotebookLM/
│
├── 📄 README.md                   ← You are here
├── 📄 requirements.txt            ← All Python dependencies
├── 📄 .env.example                ← Environment config template
├── 📄 LICENSE                     ← Apache 2.0
├── 📄 LICENSE-MIT                 ← MIT License
├── 📖 SETUP.md                    ← Full non-technical setup guide
│
├── 🪟 install.bat                 ← Windows one-click installer
├── 📜 install.ps1                 ← Windows PowerShell installer script
├── ▶️  start.bat                   ← Windows: start the app
├── ⏹️  stop.bat                    ← Windows: stop the app
│
├── 📁 docs/
│   └── 📁 screenshots/            ← App screenshots (used in README)
│
├── 📁 webapp/                     ← Flask web application
│   ├── 📄 app.py                  ← Main server (all routes + API endpoints)
│   └── 📁 templates/              ← HTML templates (Jinja2)
│       ├── 📄 base.html           ← Shared layout: sidebar, topbar, search, JS
│       ├── 📄 index.html          ← Home page with project list + stats
│       ├── 📄 notebook.html       ← Workspace: sources, chat, notes
│       └── 📄 settings.html       ← AI engines, clock/timezone, trash
│
├── 📁 engine/                     ← AI and data processing core
│   ├── 📄 rag.py                  ← Fallback chain + RAG query engine
│   ├── 📄 ingest.py               ← PDF / URL / YouTube to ChromaDB
│   └── 📄 db.py                   ← ChromaDB vector store manager
│
└── 📁 data/                       ← Auto-created on first run
    ├── 📄 providers.example.json  ← Copy to providers.json, then add your keys
    ├── 📁 chroma/                 ← Vector DB (your indexed documents)
    ├── 📁 projects/               ← Projects, uploads, notes, chat history
    └── 📁 trash/                  ← Soft-deleted projects (restorable)

🔒 Security

Protections Built In

Threat	How It's Handled
📁 Path traversal on upload	`secure_filename()` strips `../` from all filenames
🦠 Malicious file types	Whitelist: only `.pdf` `.txt` `.md` accepted
💾 Oversized uploads	Hard 100 MB limit
🔑 API key theft	Keys masked in browser (`sk-ab***cdef`); the raw key is never sent to the frontend
💉 Meta injection	Project metadata endpoint whitelists allowed keys only
🗂️ Trash path traversal	Path validated against trash directory before any operation
🤖 AI hallucination	System prompt explicitly forbids outside knowledge and training data
💥 All providers fail	Caught and returns a clean `503` error instead of crashing Flask

Data Privacy

✅  Projects stored on your disk
✅  Vector DB runs locally (ChromaDB)
✅  API keys never committed to git
✅  data/providers.json in .gitignore
✅  Masked keys in Settings UI
✅  No telemetry, no analytics
✅  No accounts required

Running Publicly (e.g. behind Cloudflare Tunnel)

If you expose the app online, add authentication at the edge. The app has no built-in login system:

Recommended: Cloudflare Access (Zero Trust) - free, easy, blocks all
             unauthenticated access before it reaches your app

⚠️ Without edge auth, anyone who knows your URL can use the app and access Settings.

🗺️ Roadmap

✅ Shipped

🔜 Coming Next

Suggested Questions: auto-generates 5 research questions when a project opens
Mac/Linux one-click install script (install.sh)
Export session as PDF or Markdown
Source deduplication on upload
Dark/light theme toggle

📅 Changelog

v3.0 (June 2026)

Do More panel: 8 one-click action buttons (Briefing, Themes, FAQ, Timeline, Mind Map, Quiz, Flashcards, Knowledge Stats) — all trigger rich AI responses in the Research Chat
Research Chat as primary screen: all AI outputs — including structured quiz, flashcards, mind map, and knowledge analysis — appear inline in chat
Quiz format: properly structured 10-question multiple-choice with answers and explanations
Flashcards format: 12-card Term/Definition deck with source attribution
Mind Map format: hierarchical text concept map with branches and subtopics
Knowledge Stats: concept importance scores, overview, and knowledge gaps
12-hour clock (AM/PM) in sidebar and Settings
Do More panel: default visible, hide/show button in panel header plus floating right-edge tab
Responsive layout: mobile, tablet, and large screen CSS improvements; no overlapping elements
Confirmation on chat clear: prevents accidental deletion
MIT licence added alongside Apache 2.0

v2.2 (June 2026)

Mind Map tab: vis.js force-directed knowledge graph extracted from your sources
Quiz tab: AI-generated multiple-choice questions with scoring and explanations
Flashcards tab: flip-card study deck with keyboard navigation (arrow keys + space to flip)
Backend caching: graph, quiz, and flashcard results cached per project

v2.1 (June 2026)

Security hardening: path traversal protection, file type whitelist, 100 MB upload limit, API key masking, trash path validation
AI grounding strengthened: system prompt now explicitly forbids outside knowledge and training data
Sidebar clock & timezone: live clock with configurable timezone (25+ regions)
Home page stats strip: total projects, sources, and notes at a glance
Smart Search: searches project names and files within projects in real time
Source count fix: sidebar now shows real source file count, not ChromaDB chunk count
Note cards: click to expand full content (was truncated to 300 chars)
Model indicator: single status dot in topbar (green = active, red = unavailable)
Settings: new Clock & Timezone tab added

v2.0 (May 2026) - Initial public release

Flask web app with full project management
12-provider AI fallback chain with Ollama local fallback
PDF / URL / YouTube ingestion pipeline
ChromaDB vector search
Do More AI actions (Briefing, Themes, FAQ, Timeline, Mind Map, Quiz, Flashcards, Knowledge Stats)
Notes system, Trash & Restore
Windows one-click installer

🛠️ Troubleshooting

App won't start

# Check Python version (needs 3.10+)
python --version

# Reinstall packages
pip install -r requirements.txt

# Check if port is in use
netstat -ano | findstr :8080      # Windows
lsof -i :8080                     # Mac/Linux

"All AI engines unavailable" error

Go to Settings > AI Engines. At least one provider must have enabled: true
If using Ollama only: make sure it is running with ollama serve
If using API keys: verify the keys are valid and the service is up

First PDF upload is slow (1-2 min)

This is normal. Docling downloads OCR models (~15 MB) once on first use. All future uploads are fast.

Sources disappeared after restart

Your data lives in the data/ folder. Never delete this folder. If you moved the project folder, the ChromaDB path may be broken. Run the app from the original install location.

Port 8080 already in use

# Windows
stop.bat
# or:
netstat -ano | findstr :8080
taskkill /PID <pid> /F

# Mac/Linux
kill $(lsof -t -i:8080)

Ollama model not found

ollama list              # see what's installed
ollama pull qwen2.5:3b   # install the default model

🤝 Contributing

Contributions are welcome!

# 1. Fork this repo
# 2. Create your branch
git checkout -b feature/your-idea

# 3. Make changes & commit
git commit -m "add: your feature description"

# 4. Push and open a Pull Request
git push origin feature/your-idea

Found a bug? Open an Issue with steps to reproduce.

📜 License (MIT) & Apache 2.0

MIT License — free to use, copy, modify, distribute, no conditions
Apache 2.0 License — includes patent grant and attribution requirements

🧰 Built With

Built by Pavel Blank

If this project helps your research, give it a star. It helps other researchers find it.

Name		Name	Last commit message	Last commit date
data		data
docs/screenshots		docs/screenshots
engine		engine
webapp		webapp
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
SETUP.md		SETUP.md
USER_GUIDE.md		USER_GUIDE.md
install.bat		install.bat
install.ps1		install.ps1
requirements.txt		requirements.txt
start.bat		start.bat
stop.bat		stop.bat

Latest commit

History

Folders and files

Repository files navigation

Your Private AI Research Assistant

📸 Screenshots

💡 Why ResearchNotebookLM?

🆚 ResearchNLM vs Google NotebookLM

✨ Features in Detail

🤖 AI-Grounded Chat

🔗 12-Engine Fallback Chain

✨ Do More — AI Actions in Chat

📄 Multi-Source Ingestion

📖 Source Viewer

📝 Notes System

🔍 Smart Search

🕐 Sidebar Clock & Timezone

🗑️ Trash & Restore

📊 Workspace Stats

📋 Prerequisites

🚀 Quick Start

⚡ Windows: One Click

🛠️ Manual Install (All Platforms)

🔑 Getting Free API Keys

OpenRouter

NVIDIA NIM

🏗️ How It Works

⚙️ Settings & Configuration

In-App Settings

Configuring AI Providers (data/providers.json)

📍 Where to Update for New Versions

📁 Project Structure

🔒 Security

Protections Built In

Data Privacy

Running Publicly (e.g. behind Cloudflare Tunnel)

🗺️ Roadmap

✅ Shipped

🔜 Coming Next

📅 Changelog

v3.0 (June 2026)

v2.2 (June 2026)

v2.1 (June 2026)

v2.0 (May 2026) - Initial public release

🛠️ Troubleshooting

🤝 Contributing

📜 License (MIT) & Apache 2.0

🧰 Built With

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Configuring AI Providers (`data/providers.json`)