Open Notebook

repository·main·Indexed 12 days ago

An open-source, privacy-focused research assistant inspired by Google Notebook LM. It allows users to host their own research environment, manage multi-modal content, and interact with cloud-based or local AI models (such as Ollama and Speaches) while maintaining complete control over their data. Version 1.14.0.

Tokens: 108.6K
Snippets: 203
Records: 489
Agent score: 94%

What's inside Open Notebook

Overview of Open Notebook Core Features
main
Open Notebook provides eight core functional areas for research management:
1. Adding Sources: Import PDFs, web links, audio, video, or text. Uses Content Processing Engines (Docling, Firecrawl, Jina, Crawl4AI) for extraction.
2. Working with Notes: Create manual notes or save AI responses. Organize using tags and naming.
3. Chatting: Converse with AI about specific sources by managing the context window.
4. Creating Podcasts: Convert research into audio dialogue using customizable speakers and TTS providers.
5. Searching: Use Text Search (keyword) or Vector Search (semantic) to find information.
6. Transformations: Batch-process multiple sources using predefined or custom templates to extract specific insights.
7. Citations: Trace AI claims back to specific source material for verification.
8. API Configuration: Manage AI provider API keys (OpenAI, Azure, etc.) directly through the Settings UI.
https://github.com/lfnovo/open-notebook/blob/main/docs/3-USER-GUIDE/index.md
Overview of Open Notebook features
main
Open Notebook is a private, multi-model, 100% local alternative to Google Notebook LM. It is designed for users who want data sovereignty and flexibility in AI model selection.
Core Capabilities:
- Data Control: Self-hosted for privacy.
- Model Flexibility: Supports 18+ providers including OpenAI, Anthropic, Ollama, and LM Studio.
- Multi-modal Support: Process PDFs, videos, audio, and web pages.
- Podcast Generation: Create professional multi-speaker podcasts (1-4 speakers).
- Intelligent Search: Full-text and vector search across all uploaded content.
- Contextual Chat: AI conversations grounded in your specific research data.
- API Access: Full REST API available for automation.
https://github.com/lfnovo/open-notebook/blob/main/README.md
Core Capabilities of Open Notebook
main
Open Notebook is a privacy-first, multi-model alternative to Notebook LM designed for research and content organization.
Key Features:
- Privacy-First: Local-first design with no cloud dependencies required.
- Multi-Notebook Organization: Manage multiple distinct research projects.
- Universal Content Support: Ingest PDFs, videos, audio, web pages, and Office documents.
- Multi-Model AI Support: Access 18+ providers (OpenAI, Anthropic, Ollama, etc.).
- Podcast Generation: Create professional multi-speaker podcasts using Episode Profiles.
- Intelligent Search: Combines full-text and vector search across all sources.
- Context-Aware Chat & Citations: AI conversations that provide proper source citations.
- Content Transformations: Customizable actions to summarize or extract insights from content.
- REST API: Full programmatic access for custom integrations.
https://github.com/lfnovo/open-notebook/blob/main/README.md
Guidelines for AI-assisted and Agent-generated PRs
main
Using coding agents (Claude Code, Cursor, Copilot, etc.) is welcome, but the human operator remains the author and is responsible for the code.
Requirements for AI-generated PRs:
- Ownership: You must be able to explain every line of the diff. "The agent wrote it" is not an acceptable answer during review.
- Process: Agents must still follow the "Discussion $\rightarrow$ Issue $\rightarrow$ Implementation" workflow for non-trivial work.
- Test Evidence: You must provide real test output. An agent's claim that tests pass is not sufficient.
- Context: Use the AGENTS.md files (found in the root, open_notebook/, and frontend/) and change-playbooks.md to provide the agent with correct project context.
- Scope: Prevent agents from performing unrelated refactors; keep changes strictly scoped to the task.
https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/contributing.md
Understand the Open Notebook architecture: API-first design
main
Open Notebook follows an API-first principle, meaning all core capabilities are exposed via a FastAPI REST API. The frontend is a pure client and does not contain business logic; instead, it consumes the same REST API that external integrations use. This architecture ensures that any feature available in the UI is also programmatically accessible via the API.
Frontend Stack:
- Framework: Next.js / React
- State Management: Zustand
- Data Fetching: TanStack Query over axios
- UI Components: Radix / Shadcn
https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/decisions/ADR-003-streamlit-to-nextjs.md

Compare Transformations, Chat, and Ask

main

Understanding which tool to use depends on your goal:

Feature	Transformations	Chat	Ask
Input	Predefined template	Your questions	Your question
Scope	One source at a time	Selected sources	Auto-searched
Output	Structured note	Conversation	Comprehensive answer
Best for	Batch processing	Exploration	One-shot answers
Follow-up	Run again	Ask more	New query

Pattern: Repeated citation emphasis
main
To prevent LLM hallucinations regarding document IDs, response-generating templates (such as ask and chat) must use repeated citation emphasis.
When editing templates, ensure you include the citation rules (e.g., [source:id], [note:id], [insight:id]) and the instruction "do not make up document IDs" multiple times, accompanied by inline examples. Repetition and examples are critical for maintaining citation accuracy.
https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/prompts.md
Test categories and locations
main
Tests in Open Notebook are organized into four main categories based on their scope and location within the tests/ directory:
1. Unit Tests (tests/unit/): Test individual functions and methods in isolation (e.g., validation logic).
2. Integration Tests (tests/integration/): Test component interactions and database operations (e.g., creating a notebook and adding sources).
3. API Tests (tests/api/): Test HTTP endpoints and error responses using httpx.AsyncClient.
4. Database Tests (tests/database/): Test data persistence and query correctness.
https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md
How Model Registry References Work in Podcasts
main
Instead of using raw strings for providers or model names, podcast profiles use references to Model records.
At generation time, the system calls _resolve_model_config(model_id) to:
1. Load the specific Model record.
2. Resolve the linked credentials (or fall back to provision_provider_keys()).
3. Return a tuple of (provider, model_name, config) to the podcast-creator.
Note: Legacy string fields (like tts_provider or outline_provider) have been removed. If a profile is unresolved, the UI will flag it, and you must manually select a model from the registry.
https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/podcasts.md
Understand LangGraph Workflows in Open Notebook
main
Open Notebook uses LangGraph to orchestrate five core multi-step AI workflows. Each workflow manages a specific state dictionary and is triggered by specific API endpoints.
1. Source Processing Workflow (open_notebook/graphs/source.py): Ingests content (PDF, URL, text), extracts/cleans text, generates embeddings via Esperanto, and saves to SurrealDB. Triggered by POST /sources.
2. Chat Workflow (open_notebook/graphs/chat.py): Conducts multi-turn conversations using notebook context. Features message history persistence and token counting. Triggered by POST /chat/execute.
3. Ask Workflow (open_notebook/graphs/ask.py): Answers questions by planning a search strategy (vector + text), scoring results, and synthesizing answers. Supports real-time streaming via astream(). Triggered by POST /ask.
4. Transformation Workflow (open_notebook/graphs/transformation.py): Applies custom rules (e.g., Summary, Key Points, Quotes) to sources using Jinja2 templates. Triggered by POST /sources/{id}/insights.
5. Prompt Workflow (open_notebook/graphs/prompt.py): Executes generic LLM tasks like auto-generating note titles.
```
### Source Processing Workflow State
```python
{
  "content_state": {"file_path" | "url" | "content": str},
  "source_id": str,
  "full_text": str,
  "embeddings": List[Dict],
  "topics": List[str],
  "notebook_ids": List[str],
}
```
Chat Workflow State
```
{
  "session_id": str,
  "messages": List[BaseMessage],
  "context": Dict[str, Any],  # sources, notes, snippets
  "response": str,
  "model_override": Optional[str],
}
```
Ask Workflow State
```
{
  "question": str,
  "strategy": SearchStrategy,
  "answers": List[str],
  "final_answer": str,
  "sources_used": List[Source],
}
```
https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/architecture.md
Compare Text Search and Vector Search modes
main
Open Notebook provides two search strategies to satisfy different research needs:
1. Text Search (Keyword Matching)
Uses the BM25 ranking algorithm to find chunks containing your exact keywords.
- When to use: When searching for specific names, numbers, or exact phrases (e.g., "transformer architecture").
- Behavior: Ranks results based on keyword frequency and position.
2. Vector Search (Semantic Similarity)
Converts your question into a numerical vector (embedding) and finds chunks with similar mathematical meanings.
- When to use: When exploring concepts or looking for ideas that might be worded differently (e.g., searching for "model understanding" might return results about "interpretability").
- Behavior: Finds conceptually similar content even if no exact keywords match.
https://github.com/lfnovo/open-notebook/blob/main/docs/2-CORE-CONCEPTS/ai-context-rag.md
Understand AI Provider Integration via Esperanto
main
Open Notebook uses the Esperanto library to provide a unified interface for interacting with multiple AI providers. This abstraction allows users to swap providers (e.g., from OpenAI to Anthropic or local Ollama) without changing application code.
Supported Capabilities
- LLMs: Unified interface for 17+ providers (OpenAI, Anthropic, Google, Groq, Mistral, DeepSeek, xAI, etc.).
- Embeddings: Multi-provider support (OpenAI, Google, Ollama, Mistral, Voyage).
- Audio: TTS/STT integration (OpenAI, Groq, ElevenLabs, Google).
- Local Execution: Full support for Ollama, enabling a 100% local, private AI setup.
- Smart Selection: Includes fallback logic and cost optimization features.
https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/architecture.md

Open Notebook

What's inside Open Notebook

Chat Workflow State

Ask Workflow State

1. Text Search (Keyword Matching)

2. Vector Search (Semantic Similarity)

Supported Capabilities