chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,450 @@
|
||||
# AI Context & RAG - How Open Notebook Uses Your Research
|
||||
|
||||
Open Notebook uses different approaches to make AI models aware of your research depending on the feature. This section explains **RAG** (used in Ask) and **full-content context** (used in Chat).
|
||||
|
||||
---
|
||||
|
||||
## The Problem: Making AI Aware of Your Data
|
||||
|
||||
### Traditional Approaches (and their problems)
|
||||
|
||||
**Option 1: Fine-Tuning**
|
||||
- Train the model on your data
|
||||
- Pro: Model becomes specialized
|
||||
- Con: Expensive, slow, permanent (can't unlearn)
|
||||
|
||||
**Option 2: Send Everything to Cloud**
|
||||
- Upload all your data to ChatGPT/Claude API
|
||||
- Pro: Works well, fast
|
||||
- Con: Privacy nightmare, data leaves your control, expensive
|
||||
|
||||
**Option 3: Ignore Your Data**
|
||||
- Just use the base model without your research
|
||||
- Pro: Private, free
|
||||
- Con: AI doesn't know anything about your specific topic
|
||||
|
||||
### Open Notebook's Dual Approach
|
||||
|
||||
**For Chat**: Sends the entire selected content to the LLM
|
||||
- Simple and transparent: You select sources, they're sent in full
|
||||
- Maximum context: AI sees everything you choose
|
||||
- You control which sources are included
|
||||
|
||||
**For Ask (RAG)**: Retrieval-Augmented Generation
|
||||
- RAG = Retrieval-Augmented Generation
|
||||
- The insight: *Search your content, find relevant pieces, send only those*
|
||||
- Automatic: AI decides what's relevant based on your question
|
||||
|
||||
---
|
||||
|
||||
## How RAG Works: Three Stages
|
||||
|
||||
### Stage 1: Content Preparation
|
||||
|
||||
When you upload a source, Open Notebook prepares it for retrieval:
|
||||
|
||||
```
|
||||
1. EXTRACT TEXT
|
||||
PDF → text
|
||||
URL → webpage text
|
||||
Audio → transcribed text
|
||||
Video → subtitles + transcription
|
||||
|
||||
2. CHUNK INTO PIECES
|
||||
Long documents → break into ~500-word chunks
|
||||
Why? AI context has limits; smaller pieces are more precise
|
||||
|
||||
3. CREATE EMBEDDINGS
|
||||
Each chunk → semantic vector (numbers representing meaning)
|
||||
Why? Allows finding chunks by similarity, not just keywords
|
||||
|
||||
4. STORE IN DATABASE
|
||||
Chunks + embeddings + metadata → searchable storage
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Source: "AI Safety Research 2026" (50-page PDF)
|
||||
↓
|
||||
Extracted: 50 pages of text
|
||||
↓
|
||||
Chunked: 150 chunks (~500 words each)
|
||||
↓
|
||||
Embedded: Each chunk gets a vector (1536 numbers for OpenAI)
|
||||
↓
|
||||
Stored: Ready for search
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Query Time (What You Search For)
|
||||
|
||||
When you ask a question, the system finds relevant content:
|
||||
|
||||
```
|
||||
1. YOU ASK A QUESTION
|
||||
"What does the paper say about alignment?"
|
||||
|
||||
2. SYSTEM CONVERTS QUESTION TO EMBEDDING
|
||||
Your question → vector (same way chunks are vectorized)
|
||||
|
||||
3. SIMILARITY SEARCH
|
||||
Find chunks most similar to your question
|
||||
(using vector math, not keyword matching)
|
||||
|
||||
4. RETURN TOP RESULTS
|
||||
Usually top 5-10 most similar chunks
|
||||
|
||||
5. YOU GET BACK
|
||||
✓ The relevant chunks
|
||||
✓ Where they came from (sources + page numbers)
|
||||
✓ Relevance scores
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Q: "What does the paper say about alignment?"
|
||||
↓
|
||||
Q vector: [0.23, -0.51, 0.88, ..., 0.12]
|
||||
↓
|
||||
Search: Compare to all chunk vectors
|
||||
↓
|
||||
Results:
|
||||
- Chunk 47 (alignment section): similarity 0.94
|
||||
- Chunk 63 (safety approaches): similarity 0.88
|
||||
- Chunk 12 (related work): similarity 0.71
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Augmentation (How AI Uses It)
|
||||
|
||||
Now you have the relevant pieces. The AI uses them:
|
||||
|
||||
```
|
||||
SYSTEM BUILDS A PROMPT:
|
||||
"You are an AI research assistant.
|
||||
|
||||
The user has the following research materials:
|
||||
[CHUNK 47 CONTENT]
|
||||
[CHUNK 63 CONTENT]
|
||||
|
||||
User question: 'What does the paper say about alignment?'
|
||||
|
||||
Answer based on the above materials."
|
||||
|
||||
AI RESPONDS:
|
||||
"Based on the research materials, the paper approaches
|
||||
alignment through [pulls from chunks] and emphasizes
|
||||
[pulls from chunks]..."
|
||||
|
||||
SYSTEM ADDS CITATIONS:
|
||||
"- See research materials page 15 for approach details
|
||||
- See research materials page 23 for emphasis on X"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Two Search Modes: Exact vs. Semantic
|
||||
|
||||
Open Notebook provides two different search strategies for different goals.
|
||||
|
||||
### 1. Text Search (Keyword Matching)
|
||||
|
||||
**How it works:**
|
||||
- Uses BM25 ranking (the same algorithm Google uses)
|
||||
- Finds chunks containing your keywords
|
||||
- Ranks by relevance (how often keywords appear, position, etc.)
|
||||
|
||||
**When to use:**
|
||||
- "I remember the exact phrase 'X' and want to find it"
|
||||
- "I'm looking for a specific name or number"
|
||||
- "I need the exact quote"
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Search: "transformer architecture"
|
||||
Results:
|
||||
1. Chunk with "transformer architecture" 3 times
|
||||
2. Chunk with "transformer" and "architecture" separately
|
||||
3. Chunk with "transformer-based models"
|
||||
```
|
||||
|
||||
### 2. Vector Search (Semantic Similarity)
|
||||
|
||||
**How it works:**
|
||||
- Converts your question to a vector (number embedding)
|
||||
- Finds chunks with similar vectors
|
||||
- No keywords needed—finds conceptually similar content
|
||||
|
||||
**When to use:**
|
||||
- "Find content about X (without saying exact words)"
|
||||
- "I'm exploring a concept"
|
||||
- "Find similar ideas even if worded differently"
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Search: "what's the mechanism for model understanding?"
|
||||
Results (no "understanding" in any chunk):
|
||||
1. Chunk about interpretability and mechanistic analysis
|
||||
2. Chunk about feature analysis
|
||||
3. Chunk about attention mechanisms
|
||||
|
||||
Why? The vectors are semantically similar to your concept.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Management: Your Control Panel
|
||||
|
||||
Here's where Open Notebook is different: **You decide what the AI sees.**
|
||||
|
||||
### The Three Levels
|
||||
|
||||
| Level | What's Shared | Example Cost | Privacy | Use Case |
|
||||
|-------|---------------|--------------|---------|----------|
|
||||
| **Full Content** | Complete source text | 10,000 tokens | Low | Detailed analysis, close reading |
|
||||
| **Summary Only** | AI-generated summary | 2,000 tokens | High | Background material, references |
|
||||
| **Not in Context** | Nothing | 0 tokens | Max | Confidential, irrelevant, or archived |
|
||||
|
||||
### How It Works
|
||||
|
||||
**Full Content:**
|
||||
```
|
||||
You: "What's the methodology in paper A?"
|
||||
System:
|
||||
- Searches paper A
|
||||
- Retrieves full paper content (or large chunks)
|
||||
- Sends to AI: "Here's paper A. Answer about methodology."
|
||||
- AI analyzes complete content
|
||||
- Result: Detailed, precise answer
|
||||
```
|
||||
|
||||
**Summary Only:**
|
||||
```
|
||||
You: "I want to chat using paper A and B"
|
||||
System:
|
||||
- For Paper A: Sends AI-generated summary (not full text)
|
||||
- For Paper B: Sends full content (detailed analysis)
|
||||
- AI sees 2 sources but in different detail levels
|
||||
- Result: Uses summaries for context, details for focused content
|
||||
```
|
||||
|
||||
**Not in Context:**
|
||||
```
|
||||
You: "I have 10 sources but only want 5 in context"
|
||||
System:
|
||||
- Paper A-E: In context (sent to AI)
|
||||
- Paper F-J: Not in context (AI can't see them, doesn't search them)
|
||||
- AI never knows these 5 sources exist
|
||||
- Result: Tight, focused context
|
||||
```
|
||||
|
||||
### Why This Matters
|
||||
|
||||
**Privacy**: You control what leaves your system
|
||||
```
|
||||
Scenario: Confidential company docs + public research
|
||||
Control: Public research in context → Confidential docs excluded
|
||||
Result: AI never sees confidential content
|
||||
```
|
||||
|
||||
**Cost**: You control token usage
|
||||
```
|
||||
Scenario: 100 sources for background + 5 for detailed analysis
|
||||
Control: Full content for 5 detailed, summaries for 95 background
|
||||
Result: 80% lower token cost than sending everything
|
||||
```
|
||||
|
||||
**Quality**: You control what the AI focuses on
|
||||
```
|
||||
Scenario: 20 sources, question requires deep analysis
|
||||
Control: Full content for relevant source, exclude others
|
||||
Result: AI doesn't get distracted; gives better answer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Difference: Chat vs. Ask
|
||||
|
||||
**IMPORTANT**: These use completely different approaches!
|
||||
|
||||
### Chat: Full-Content Context (NO RAG)
|
||||
|
||||
**How it works:**
|
||||
```
|
||||
YOU:
|
||||
1. Select which sources to include in context
|
||||
2. Set context level (full/summary/excluded)
|
||||
3. Ask question
|
||||
|
||||
SYSTEM:
|
||||
- Takes ALL selected sources (respecting context levels)
|
||||
- Sends the ENTIRE content to the LLM at once
|
||||
- NO search, NO retrieval, NO chunking
|
||||
- AI sees everything you selected
|
||||
|
||||
AI:
|
||||
- Responds based on the full content you provided
|
||||
- Can reference any part of selected sources
|
||||
- Conversational: context stays for follow-ups
|
||||
```
|
||||
|
||||
**Use this when**:
|
||||
- You know which sources are relevant
|
||||
- You want conversational back-and-forth
|
||||
- You want AI to see the complete context
|
||||
- You're doing close reading or analysis
|
||||
|
||||
**Advantages:**
|
||||
- Simple and transparent
|
||||
- AI sees everything (no missed content)
|
||||
- Conversational flow
|
||||
|
||||
**Limitations:**
|
||||
- Limited by LLM context window
|
||||
- You must manually select relevant sources
|
||||
- Sends more tokens (higher cost with many sources)
|
||||
|
||||
---
|
||||
|
||||
### Ask: RAG - Automatic Retrieval
|
||||
|
||||
**How it works:**
|
||||
```
|
||||
YOU:
|
||||
Ask one complex question
|
||||
|
||||
SYSTEM:
|
||||
1. Analyzes your question
|
||||
2. Searches across ALL your sources automatically
|
||||
3. Finds relevant chunks using vector similarity
|
||||
4. Retrieves only the most relevant pieces
|
||||
5. Sends ONLY those chunks to the LLM
|
||||
6. Synthesizes into comprehensive answer
|
||||
|
||||
AI:
|
||||
- Sees ONLY the retrieved chunks (not full sources)
|
||||
- Answers based on what was found to be relevant
|
||||
- One-shot answer (not conversational)
|
||||
```
|
||||
|
||||
**Use this when**:
|
||||
- You have many sources and don't know which are relevant
|
||||
- You want the AI to search automatically
|
||||
- You need a comprehensive answer to a complex question
|
||||
- You want to minimize tokens sent to LLM
|
||||
|
||||
**Advantages:**
|
||||
- Automatic search (you don't pick sources)
|
||||
- Works across many sources at once
|
||||
- Cost-effective (sends only relevant chunks)
|
||||
|
||||
**Limitations:**
|
||||
- Not conversational (single question/answer)
|
||||
- AI only sees retrieved chunks (might miss context)
|
||||
- Search quality depends on how well question matches content
|
||||
|
||||
---
|
||||
|
||||
## What This Means: Privacy by Design
|
||||
|
||||
Open Notebook's RAG approach gives you something you don't get with ChatGPT or Claude directly:
|
||||
|
||||
**You control the boundary between:**
|
||||
- What stays private (on your system)
|
||||
- What goes to AI (explicitly chosen)
|
||||
- What the AI can see (context levels)
|
||||
|
||||
### The Audit Trail
|
||||
|
||||
Because everything is retrieved explicitly, you can ask:
|
||||
- "Which sources did the AI use for this answer?" → See citations
|
||||
- "What exactly did the AI see?" → See chunks in context level
|
||||
- "Is the AI's claim actually in my sources?" → Verify citation
|
||||
|
||||
This prevents hallucinations or misrepresentation better than most systems.
|
||||
|
||||
---
|
||||
|
||||
## How Embeddings Work (Simplified)
|
||||
|
||||
The magic of semantic search comes from embeddings. Here's the intuition:
|
||||
|
||||
### The Idea
|
||||
Instead of storing text, store it as a list of numbers (vectors) that represent "meaning."
|
||||
|
||||
```
|
||||
Chunk: "The transformer uses attention mechanisms"
|
||||
Vector: [0.23, -0.51, 0.88, 0.12, ..., 0.34]
|
||||
(1536 numbers for OpenAI)
|
||||
|
||||
Another chunk: "Attention allows models to focus on relevant parts"
|
||||
Vector: [0.24, -0.48, 0.87, 0.15, ..., 0.35]
|
||||
(similar numbers = similar meaning!)
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
Words that are semantically similar produce similar vectors. So:
|
||||
- "alignment" and "interpretability" have similar vectors
|
||||
- "transformer" and "attention" have related vectors
|
||||
- "cat" and "dog" are more similar than "cat" and "radiator"
|
||||
|
||||
### How Search Works
|
||||
```
|
||||
Your question: "How do models understand their decisions?"
|
||||
Question vector: [0.25, -0.50, 0.86, 0.14, ..., 0.33]
|
||||
|
||||
Compare to all stored vectors. Find the most similar:
|
||||
- Chunk about interpretability: similarity 0.94
|
||||
- Chunk about explainability: similarity 0.91
|
||||
- Chunk about feature attribution: similarity 0.88
|
||||
|
||||
Return the top matches.
|
||||
```
|
||||
|
||||
This is why semantic search finds conceptually similar content even when words are different.
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### 1. Search, Don't Train
|
||||
**Why?** Fine-tuning is slow and permanent. Search is flexible and reversible.
|
||||
|
||||
### 2. Explicit Retrieval, Not Implicit Knowledge
|
||||
**Why?** You can verify what the AI saw. You have audit trails. You control what leaves your system.
|
||||
|
||||
### 3. Multiple Search Types
|
||||
**Why?** Different questions need different search (keyword vs. semantic). Giving you both is more powerful.
|
||||
|
||||
### 4. Context as a Permission System
|
||||
**Why?** Not everything you save needs to reach AI. You control granularly.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Open Notebook gives you **two ways** to work with AI:
|
||||
|
||||
### Chat (Full-Content)
|
||||
- Sends entire selected sources to LLM
|
||||
- Manual control: you pick sources
|
||||
- Conversational: back-and-forth dialog
|
||||
- Transparent: you know exactly what AI sees
|
||||
- Best for: focused analysis, close reading
|
||||
|
||||
### Ask (RAG)
|
||||
- Searches and retrieves relevant chunks automatically
|
||||
- Automatic: AI finds what's relevant
|
||||
- One-shot: single comprehensive answer
|
||||
- Efficient: sends only relevant pieces
|
||||
- Best for: broad questions across many sources
|
||||
|
||||
**Both approaches:**
|
||||
1. Keep your data private (doesn't leave your system by default)
|
||||
2. Give you control (you choose which features to use)
|
||||
3. Create audit trails (citations show what was used)
|
||||
4. Support multiple AI providers
|
||||
|
||||
**Coming Soon**: The community is working on adding RAG capabilities to Chat as well, giving you the best of both worlds.
|
||||
@@ -0,0 +1,353 @@
|
||||
# Chat vs. Ask vs. Transformations - Which Tool for Which Job?
|
||||
|
||||
Open Notebook offers different ways to work with your research. Understanding when to use each is key to using the system effectively.
|
||||
|
||||
---
|
||||
|
||||
## The Three Interaction Modes
|
||||
|
||||
### 1. CHAT - Conversational Exploration with Manual Context
|
||||
|
||||
**What it is:** Have a conversation with AI about selected sources.
|
||||
|
||||
**The flow:**
|
||||
```
|
||||
1. You select which sources to include ("in context")
|
||||
2. You ask a question
|
||||
3. AI responds using ONLY those sources
|
||||
4. You ask follow-up questions (context stays same)
|
||||
5. You change sources or context level, then continue
|
||||
```
|
||||
|
||||
**Context management:** You explicitly choose which sources the AI can see.
|
||||
|
||||
**Conversational:** Multiple questions with shared history.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: [Select sources: "paper1.pdf", "research_notes.txt"]
|
||||
[Set context: Full content for paper1, Summary for notes]
|
||||
|
||||
You: "What's the main argument in these sources?"
|
||||
AI: "Paper 1 argues X [citation]. Your notes emphasize Y [citation]."
|
||||
|
||||
You: "How do they differ?"
|
||||
AI: "Paper 1 focuses on X [citation], while your notes highlight Y [citation]..."
|
||||
|
||||
You: [Now select different sources]
|
||||
|
||||
You: "Compare to this other perspective"
|
||||
AI: "This new source takes a different approach..."
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Exploring a focused topic with specific sources
|
||||
- Having a dialogue (multiple back-and-forth questions)
|
||||
- When you know which sources matter
|
||||
- When you want tight control over what goes to AI
|
||||
|
||||
---
|
||||
|
||||
### 2. ASK - Automated Comprehensive Search
|
||||
|
||||
**What it is:** Ask one complex question, system automatically finds relevant content.
|
||||
|
||||
**The flow:**
|
||||
```
|
||||
1. You ask a comprehensive question
|
||||
2. System analyzes the question
|
||||
3. System automatically searches your sources
|
||||
4. System retrieves relevant chunks
|
||||
5. System synthesizes answer from all results
|
||||
6. You get one detailed answer (not conversational)
|
||||
```
|
||||
|
||||
**Context management:** Automatic. System figures out what's relevant.
|
||||
|
||||
**Non-conversational:** One question → one answer. No follow-ups.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: "How do these papers compare their approaches to alignment?
|
||||
What does each one recommend?"
|
||||
|
||||
System:
|
||||
- Breaks down the question into search strategies
|
||||
- Searches all sources for alignment approaches
|
||||
- Searches all sources for recommendations
|
||||
- Retrieves top 10 relevant chunks
|
||||
- Synthesizes: "Paper A recommends X [citation].
|
||||
Paper B recommends Y [citation].
|
||||
They differ in Z."
|
||||
|
||||
You: [Get back one comprehensive answer]
|
||||
[If you want to follow up, use Chat instead]
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Comprehensive, one-time questions
|
||||
- Comparing multiple sources at once
|
||||
- When you want the system to decide what's relevant
|
||||
- Complex questions that need multiple search angles
|
||||
- When you don't need a back-and-forth conversation
|
||||
|
||||
---
|
||||
|
||||
### 3. TRANSFORMATIONS - Template-Based Processing
|
||||
|
||||
**What it is:** Apply a reusable template to a source and get structured output.
|
||||
|
||||
**The flow:**
|
||||
```
|
||||
1. You define a transformation (or choose a preset)
|
||||
"Extract: main argument, methodology, limitations"
|
||||
|
||||
2. You apply it to ONE source at a time
|
||||
(You can repeat for other sources)
|
||||
|
||||
3. For the source:
|
||||
- Source content + transformation prompt → AI
|
||||
- Result stored as new insight/note
|
||||
|
||||
4. You get back
|
||||
- Structured output (main argument, methodology, limitations)
|
||||
- Saved as a note in your notebook
|
||||
```
|
||||
|
||||
**Context management:** Works on one source at a time.
|
||||
|
||||
**Reusable:** Apply the same template to different sources (one by one).
|
||||
|
||||
**Note**: Currently processes one source at a time. Batch processing (multiple sources at once) is planned for a future release.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: Define transformation
|
||||
"For each academic paper, extract:
|
||||
- Main research question
|
||||
- Methodology used
|
||||
- Key findings
|
||||
- Limitations and gaps
|
||||
- Recommended next research"
|
||||
|
||||
You: Apply to paper 1
|
||||
|
||||
System:
|
||||
- Runs the transformation on paper 1
|
||||
- Result stored as new note
|
||||
|
||||
You: Apply same transformation to paper 2, 3, etc.
|
||||
|
||||
After 10 papers:
|
||||
- You have 10 structured notes with consistent format
|
||||
- Perfect for writing a literature review or comparison
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Extracting the same information from each source (run repeatedly)
|
||||
- Creating structured summaries with consistent format
|
||||
- Building a knowledge base of categorized insights
|
||||
- When you want reusable templates you can apply to each source
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree: Which Tool to Use?
|
||||
|
||||
```
|
||||
What are you trying to do?
|
||||
|
||||
│
|
||||
├─→ "I want to have a conversation about this topic"
|
||||
│ └─→ Is the conversation exploratory or fixed?
|
||||
│ ├─→ Exploratory (I'll ask follow-ups)
|
||||
│ │ └─→ USE: CHAT
|
||||
│ │
|
||||
│ └─→ Fixed (One question → done)
|
||||
│ └─→ Go to next question
|
||||
│
|
||||
├─→ "I need to compare these sources or get a comprehensive answer"
|
||||
│ └─→ USE: ASK
|
||||
│
|
||||
├─→ "I want to extract the same info from each source (one at a time)"
|
||||
│ └─→ USE: TRANSFORMATIONS (apply to each source)
|
||||
│
|
||||
└─→ "I just want to read and search"
|
||||
└─→ USE: Search (text or vector)
|
||||
OR read your notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Side-by-Side Comparison
|
||||
|
||||
| Aspect | CHAT | ASK | TRANSFORMATIONS |
|
||||
|--------|------|-----|-----------------|
|
||||
| **What's it for?** | Conversational exploration | Comprehensive Q&A | Template-based extraction |
|
||||
| **# of questions** | Multiple (conversational) | One | One template per source |
|
||||
| **Context control** | Manual (you choose) | Automatic (system searches) | One source at a time |
|
||||
| **Conversational?** | Yes (follow-ups work) | No (one question only) | No (single operation) |
|
||||
| **Output** | Natural conversation | Natural answer | Structured note |
|
||||
| **Time** | Quick (back-and-forth) | Longer (comprehensive) | Per source |
|
||||
| **Best when** | Exploring & uncertain | Need full picture | Want consistent format |
|
||||
| **Model speed** | Any | Fast preferred | Any |
|
||||
|
||||
---
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Example 1: Academic Research
|
||||
|
||||
```
|
||||
Goal: Write literature review from 15 papers
|
||||
|
||||
Step 1: TRANSFORMATIONS
|
||||
- Define: "Extract abstract, methodology, findings, relevance"
|
||||
- Apply to paper 1 → get structured note
|
||||
- Apply to paper 2 → get structured note
|
||||
- ... repeat for all 15 papers
|
||||
- Result: 15 structured notes with consistent format
|
||||
|
||||
Step 2: Read the notes
|
||||
- Now you have consistent summaries
|
||||
|
||||
Step 3: CHAT or ASK
|
||||
- Chat: "Help me organize these by theme"
|
||||
- Ask: "What are the common methodologies across these papers?"
|
||||
|
||||
Step 4: Write your review
|
||||
- Use the transformations as foundation
|
||||
- Use chat/ask insights for structure
|
||||
```
|
||||
|
||||
### Example 2: Product Research
|
||||
|
||||
```
|
||||
Goal: Understand customer feedback from interviews
|
||||
|
||||
Step 1: Add sources (interview transcripts)
|
||||
|
||||
Step 2: ASK
|
||||
- "What are the top 10 pain points mentioned?"
|
||||
- Get comprehensive answer with citations
|
||||
|
||||
Step 3: CHAT
|
||||
- "Can you help me group these by severity?"
|
||||
- Continue conversation to prioritize
|
||||
|
||||
Step 4: TRANSFORMATIONS (optional)
|
||||
- Define: "Extract: pain point, frequency, who mentioned it"
|
||||
- Apply to each interview (one by one)
|
||||
- Get structured data for analysis
|
||||
```
|
||||
|
||||
### Example 3: Policy Analysis
|
||||
|
||||
```
|
||||
Goal: Compare policy documents
|
||||
|
||||
Step 1: Add all policy documents as sources
|
||||
|
||||
Step 2: ASK
|
||||
- "How do these policies differ on climate measures?"
|
||||
- System searches all docs, gives comprehensive comparison
|
||||
|
||||
Step 3: CHAT (if needed)
|
||||
- "Which policy is most aligned with X goals?"
|
||||
- Have discussion about trade-offs
|
||||
|
||||
Step 4: Export notes
|
||||
- Save AI responses as notes for reports
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Management: The Control Panel
|
||||
|
||||
All three modes let you control what the AI sees.
|
||||
|
||||
### In CHAT and TRANSFORMATIONS
|
||||
```
|
||||
You choose:
|
||||
- Which sources to include
|
||||
- Context level for each:
|
||||
✓ Full Content (send complete text)
|
||||
✓ Summary Only (send AI summary, not full text)
|
||||
✓ Not in Context (exclude entirely)
|
||||
|
||||
Example:
|
||||
Paper A: Full Content (analyzing closely)
|
||||
Paper B: Summary Only (background)
|
||||
Paper C: Not in Context (confidential)
|
||||
```
|
||||
|
||||
### In ASK
|
||||
```
|
||||
Context is automatic:
|
||||
- System searches ALL your sources
|
||||
- Retrieves most relevant chunks
|
||||
- Sends those to AI
|
||||
|
||||
But you can:
|
||||
- Search in specific notebook
|
||||
- Filter by source type
|
||||
- Use the results to decide context for follow-up Chat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Model Selection
|
||||
|
||||
Each mode works with different models:
|
||||
|
||||
### CHAT
|
||||
- **Any model** works fine
|
||||
- Fast models (GPT-4o mini, Claude Haiku): Quick responses, good for conversation
|
||||
- Powerful models (GPT-4o, Claude Sonnet): Better reasoning, better for complex topics
|
||||
|
||||
### ASK
|
||||
- **Fast models preferred** (because it processes multiple searches)
|
||||
- Can use powerful models if you want deep synthesis
|
||||
- Example: GPT-4 for strategy planning, GPT-4o-mini for quick facts
|
||||
|
||||
### TRANSFORMATIONS
|
||||
- **Any model** works
|
||||
- Fast models (cost-effective for batch processing)
|
||||
- Powerful models (better quality extractions)
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Chaining Modes Together
|
||||
|
||||
You can combine these modes:
|
||||
|
||||
```
|
||||
TRANSFORMATIONS → CHAT
|
||||
1. Use transformations to extract structured data
|
||||
2. Use chat to discuss the results
|
||||
|
||||
ASK → TRANSFORMATIONS
|
||||
1. Use Ask to understand what matters
|
||||
2. Use Transformations to extract it from remaining sources
|
||||
|
||||
CHAT → Save as Note → TRANSFORMATIONS
|
||||
1. Have conversation (Chat)
|
||||
2. Save good responses as notes
|
||||
3. Use those notes as context for transformations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary: When to Use Each
|
||||
|
||||
| Situation | Use | Why |
|
||||
|-----------|-----|-----|
|
||||
| "I want to explore a topic with follow-up questions" | **CHAT** | Conversational, you control context |
|
||||
| "I need a comprehensive answer to one complex question" | **ASK** | Automatic search, synthesized answer |
|
||||
| "I want consistent summaries from each source" | **TRANSFORMATIONS** | Template reuse, apply to each source |
|
||||
| "I'm comparing two specific sources" | **CHAT** | Select just those 2, have discussion |
|
||||
| "I need to categorize each source by X criteria" | **TRANSFORMATIONS** | Extract category from each source |
|
||||
| "I want to understand the big picture across all sources" | **ASK** | Automatic comprehensive search |
|
||||
| "I want to build a knowledge base" | **TRANSFORMATIONS** | Create structured note from each source |
|
||||
| "I want to iterate on understanding" | **CHAT** | Multiple questions, refine thinking |
|
||||
|
||||
The key insight: **Different questions need different tools.** Open Notebook gives you all three because research rarely fits one mode.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Core Concepts - Understand the Mental Model
|
||||
|
||||
Before diving into how to use Open Notebook, it's important to understand **how it thinks**. These core concepts explain the "why" behind the design.
|
||||
|
||||
## The Five Mental Models
|
||||
|
||||
### 1. [Notebooks, Sources, and Notes](notebooks-sources-notes.md)
|
||||
How Open Notebook organizes your research. Understand the three-tier container structure and how information flows from raw materials to finished insights.
|
||||
|
||||
**Key idea**: A notebook is a scoped research container. Sources are inputs (PDFs, URLs, etc.). Notes are outputs (your insights, AI-generated summaries, captured responses).
|
||||
|
||||
---
|
||||
|
||||
### 2. [AI Context & RAG](ai-context-rag.md)
|
||||
How Open Notebook makes AI aware of your research - two different approaches.
|
||||
|
||||
**Key idea**: **Chat** sends entire selected sources to the LLM (full context, conversational). **Ask** uses RAG (retrieval-augmented generation) to automatically search and retrieve only relevant chunks. Different tools for different needs.
|
||||
|
||||
---
|
||||
|
||||
### 3. [Chat vs. Transformations](chat-vs-transformations.md)
|
||||
Why Open Notebook has different interaction modes and when to use each one.
|
||||
|
||||
**Key idea**: Chat is conversational exploration (you control context). Transformations are insight extractions. They reduced content to smaller bits of concentrated/dense information, which is much more suitable for an AI to use.
|
||||
|
||||
---
|
||||
|
||||
### 4. [Context Management](chat-vs-transformations.md#context-management-the-control-panel)
|
||||
Your control panel for privacy and cost. Decide what data actually reaches AI.
|
||||
|
||||
**Key idea**: You choose three levels—not in context (private), summary only (condensed), or full content (complete access). This gives you fine-grained control.
|
||||
|
||||
---
|
||||
|
||||
### 5. [Podcasts Explained](podcasts-explained.md)
|
||||
Why Open Notebook can turn research into audio and why this matters.
|
||||
|
||||
**Key idea**: Podcasts transform your research into a different consumption format. Instead of reading, someone can listen and absorb your insights passively.
|
||||
|
||||
---
|
||||
|
||||
## Read This Section If:
|
||||
|
||||
- **You're new to Open Notebook** — Start here to understand how the system works conceptually before learning the features
|
||||
- **You're confused about Chat vs Ask** — Section 2 explains the difference (full-content vs RAG)
|
||||
- **You're wondering when to use Chat vs Transformations** — Section 3 clarifies the differences
|
||||
- **You want to understand privacy controls** — Section 4 shows you what you can control
|
||||
- **You're curious about podcasts** — Section 5 explains the architecture and why it's different from competitors
|
||||
|
||||
---
|
||||
|
||||
## The Big Picture
|
||||
|
||||
Open Notebook is built on a simple insight: **Your research deserves to stay yours**.
|
||||
|
||||
That means:
|
||||
- **Privacy by default** — Your data doesn't leave your infrastructure unless you explicitly choose
|
||||
- **AI as a tool, not a gatekeeper** — You decide which sources the AI sees, not the AI deciding for you
|
||||
- **Flexible consumption** — Read, listen, search, chat, or transform your research however makes sense
|
||||
|
||||
These core concepts explain how that works.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Just want to use it?** → Go to [User Guide](../3-USER-GUIDE/index.md)
|
||||
2. **Want to understand it first?** → Read the 5 sections above (15 min)
|
||||
3. **Setting up for the first time?** → Go to [Installation](../1-INSTALLATION/index.md)
|
||||
|
||||
@@ -0,0 +1,284 @@
|
||||
# Notebooks, Sources, and Notes - The Container Model
|
||||
|
||||
Open Notebook organizes research in three connected layers. Understanding this hierarchy is key to using the system effectively.
|
||||
|
||||
## The Three-Layer Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ NOTEBOOK (The Container) │
|
||||
│ "My AI Safety Research 2026" │
|
||||
├─────────────────────────────────────┤
|
||||
│ │
|
||||
│ SOURCES (The Raw Materials) │
|
||||
│ ├─ safety_paper.pdf │
|
||||
│ ├─ alignment_video.mp4 │
|
||||
│ └─ prompt_injection_article.html │
|
||||
│ │
|
||||
│ NOTES (The Processed Insights) │
|
||||
│ ├─ AI Summary (auto-generated) │
|
||||
│ ├─ Key Concepts (transformation) │
|
||||
│ ├─ My Research Notes (manual) │
|
||||
│ └─ Chat Insights (from conversation)
|
||||
│ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. NOTEBOOKS - The Research Container
|
||||
|
||||
### What Is a Notebook?
|
||||
|
||||
A **notebook** is a *scoped container* for a research project or topic. It's your research workspace.
|
||||
|
||||
Think of it like a physical notebook: everything inside is about the same topic, shares the same context, and builds toward the same goals.
|
||||
|
||||
### What Goes In?
|
||||
|
||||
- **A description** — "This notebook collects research on X topic"
|
||||
- **Sources** — The raw materials you add
|
||||
- **Notes** — Your insights and outputs
|
||||
- **Conversation history** — Your chats and questions
|
||||
|
||||
### Why This Matters
|
||||
|
||||
**Isolation**: Each notebook is completely separate. Sources in Notebook A never appear in Notebook B. This lets you:
|
||||
- Keep different research topics completely isolated
|
||||
- Reuse source names across notebooks without conflicts
|
||||
- Control which AI context applies to which research
|
||||
|
||||
**Shared Context**: All sources and notes in a notebook inherit the notebook's context. If your notebook is titled "AI Safety 2026" with description "Focusing on alignment and interpretability," that context applies to all AI interactions within that notebook.
|
||||
|
||||
**Parallel Projects**: You can have 10 notebooks running simultaneously. Each one is its own isolated research environment.
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
Notebook: "Customer Research - Product Launch"
|
||||
Description: "User interviews and feedback for Q1 2026 launch"
|
||||
|
||||
→ All sources added to this notebook are about customer feedback
|
||||
→ All notes generated are in that context
|
||||
→ When you chat, the AI knows you're analyzing product launch feedback
|
||||
→ Different from your "Market Analysis - Competitors" notebook
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. SOURCES - The Raw Materials
|
||||
|
||||
### What Is a Source?
|
||||
|
||||
A **source** is a *single piece of input material* — the raw content you bring in. Sources never change; they're just processed and indexed.
|
||||
|
||||
### What Can Be a Source?
|
||||
|
||||
- **PDFs** — Research papers, reports, documents
|
||||
- **Web links** — Articles, blog posts, web pages
|
||||
- **Audio files** — Podcasts, interviews, lectures
|
||||
- **Video files** — Tutorials, presentations, recordings
|
||||
- **Plain text** — Notes, transcripts, passages
|
||||
- **Uploaded text** — Paste content directly
|
||||
|
||||
### What Happens When You Add a Source?
|
||||
|
||||
```
|
||||
1. EXTRACTION
|
||||
File/URL → Extract text and metadata
|
||||
(OCR for PDFs, web scraping for URLs, speech-to-text for audio)
|
||||
|
||||
2. CHUNKING
|
||||
Long text → Break into searchable chunks
|
||||
(Prevents "too much context" in single query)
|
||||
|
||||
3. EMBEDDING
|
||||
Each chunk → Generate semantic vector
|
||||
(Allows AI to find conceptually similar content)
|
||||
|
||||
4. STORAGE
|
||||
Chunks + vectors → Store in database
|
||||
(Ready for search and retrieval)
|
||||
```
|
||||
|
||||
### Key Properties
|
||||
|
||||
**Immutable**: Once added, the source doesn't change. If you need a new version, add it as a new source.
|
||||
|
||||
**Indexed**: Sources are automatically indexed for search (both text and semantic).
|
||||
|
||||
**Scoped**: A source belongs to exactly one notebook.
|
||||
|
||||
**Referenceable**: Other sources and notes can reference this source by citation.
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
Source: "openai_charter.pdf"
|
||||
Type: PDF document
|
||||
|
||||
What happens:
|
||||
→ PDF is uploaded
|
||||
→ Text is extracted (including images)
|
||||
→ Text is split into 50 chunks (paragraphs, sections)
|
||||
→ Each chunk gets an embedding vector
|
||||
→ Now searchable by: "OpenAI's approach to safety"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. NOTES - The Processed Insights
|
||||
|
||||
### What Is a Note?
|
||||
|
||||
A **note** is a *processed output* — something you created or AI created based on your sources. Notes are the "results" of your research work.
|
||||
|
||||
### Types of Notes
|
||||
|
||||
#### Manual Notes
|
||||
You write them yourself. They're your original thinking, capturing:
|
||||
- What you learned from sources
|
||||
- Your analysis and interpretations
|
||||
- Your next steps and questions
|
||||
|
||||
#### AI-Generated Notes
|
||||
Created by applying AI processing to sources:
|
||||
- **Transformations** — Structured extraction (main points, key concepts, methodology)
|
||||
- **Chat Responses** — Answers you saved from conversations
|
||||
- **Ask Results** — Comprehensive answers saved to your notebook
|
||||
|
||||
#### Captured Insights
|
||||
Notes you explicitly saved from interactions:
|
||||
- "Save this response as a note"
|
||||
- "Save this transformation result"
|
||||
- Convert any AI output into a permanent note
|
||||
|
||||
### What Can Notes Contain?
|
||||
|
||||
- **Text** — Your writing or AI-generated content
|
||||
- **Citations** — References to specific sources
|
||||
- **Metadata** — When created, how created (manual/AI), which sources influenced it
|
||||
- **Tags** — Your categorization (optional but useful)
|
||||
|
||||
### Why Notes Matter
|
||||
|
||||
**Knowledge Accumulation**: Notes become your actual knowledge base. They're what you take away from the research.
|
||||
|
||||
**Searchable**: Notes are searchable along with sources. "Find everything about X" includes your notes, not just sources.
|
||||
|
||||
**Citable**: Notes can cite sources, creating an audit trail of where insights came from.
|
||||
|
||||
**Shareable**: Notes are your outputs. You can share them, publish them, or build on them in other projects.
|
||||
|
||||
---
|
||||
|
||||
## How They Connect: The Data Flow
|
||||
|
||||
```
|
||||
YOU
|
||||
│
|
||||
├─→ Create Notebook ("AI Research")
|
||||
│
|
||||
├─→ Add Sources (papers, articles, videos)
|
||||
│ └─→ System: Extract, embed, index
|
||||
│
|
||||
├─→ Search Sources (text or semantic)
|
||||
│ └─→ System: Find relevant chunks
|
||||
│
|
||||
├─→ Apply Transformations (extract insights)
|
||||
│ └─→ Creates Notes
|
||||
│
|
||||
├─→ Chat with Sources (explore with context control)
|
||||
│ ├─→ Can save responses as Notes
|
||||
│ └─→ Notes include citations
|
||||
│
|
||||
├─→ Ask Questions (automated comprehensive search)
|
||||
│ ├─→ Can save results as Notes
|
||||
│ └─→ Notes include citations
|
||||
│
|
||||
└─→ Generate Podcast (transform notebook into audio)
|
||||
└─→ Uses all sources + notes for content
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### 1. One Notebook Per Source
|
||||
|
||||
Each source belongs to exactly one notebook. This creates clear boundaries:
|
||||
- No ambiguity about which research project a source is in
|
||||
- Easy to isolate or export a complete project
|
||||
- Clean permissions model (if someone gets access to notebook, they get access to all its sources)
|
||||
|
||||
### 2. Immutable Sources, Mutable Notes
|
||||
|
||||
Sources never change (once added, always the same). But notes can be edited or deleted. Why?
|
||||
- Sources are evidence → evidence shouldn't be altered
|
||||
- Notes are your thinking → thinking evolves as you learn
|
||||
|
||||
### 3. Explicit Context Control
|
||||
|
||||
Sources don't automatically go to AI. You decide which sources are "in context" for each interaction:
|
||||
- Chat: You manually select which sources to include
|
||||
- Ask: System automatically figures out which sources to search
|
||||
- Transformations: You choose which sources to transform
|
||||
|
||||
This is different from systems that always send everything to AI.
|
||||
|
||||
---
|
||||
|
||||
## Mental Models Explained
|
||||
|
||||
### Notebook as Boundaries
|
||||
Think of a notebook like a Git repository:
|
||||
- Everything in it is about the same topic
|
||||
- You can clone/fork it (copy to new project)
|
||||
- It has clear entry/exit points
|
||||
- You know exactly what's included
|
||||
|
||||
### Sources as Evidence
|
||||
Think of sources like exhibits in a legal case:
|
||||
- Once filed, they don't change
|
||||
- They can be cited and referenced
|
||||
- They're the ground truth for what you're basing claims on
|
||||
- Multiple sources can be cross-referenced
|
||||
|
||||
### Notes as Synthesis
|
||||
Think of notes like your case brief:
|
||||
- You write them based on evidence
|
||||
- They're your interpretation
|
||||
- You can cite which evidence supports each claim
|
||||
- They're what you actually share or act on
|
||||
|
||||
---
|
||||
|
||||
## Common Questions
|
||||
|
||||
### Can I move a source to a different notebook?
|
||||
Not directly. Each source is tied to one notebook. If you want it in multiple notebooks, add it again (uploads are fast if it's already processed).
|
||||
|
||||
### Can a note reference sources from a different notebook?
|
||||
No. Notes stay within their notebook and reference sources within that notebook. This keeps boundaries clean.
|
||||
|
||||
### What if I want to group sources within a notebook?
|
||||
Use tags. You can tag sources ("primary research," "background," "methodology") and filter by tags.
|
||||
|
||||
### Can I merge two notebooks?
|
||||
Not built-in, but you can manually copy sources from one notebook to another by re-uploading them.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Concept | Purpose | Lifecycle | Scope |
|
||||
|---------|---------|-----------|-------|
|
||||
| **Notebook** | Container + context | Create once, configure | All its sources + notes |
|
||||
| **Source** | Raw material | Add → Process → Store | One notebook |
|
||||
| **Note** | Processed output | Create/capture → Edit → Share | One notebook |
|
||||
|
||||
This three-layer model gives you:
|
||||
- **Clear organization** (everything scoped to projects)
|
||||
- **Privacy control** (isolated notebooks)
|
||||
- **Audit trails** (notes cite sources)
|
||||
- **Flexibility** (notes can be manual or AI-generated)
|
||||
@@ -0,0 +1,426 @@
|
||||
# Podcasts Explained - Research as Audio Dialogue
|
||||
|
||||
Podcasts are Open Notebook's highest-level transformation: converting your research into audio dialogue for a different consumption pattern.
|
||||
|
||||
---
|
||||
|
||||
## Why Podcasts Matter
|
||||
|
||||
### The Problem
|
||||
Research naturally accumulates as text: PDFs, articles, web pages, notes. This creates a friction point:
|
||||
|
||||
**To consume research, you must:**
|
||||
- Sit down at a desk
|
||||
- Focus intently
|
||||
- Read actively
|
||||
- Take notes
|
||||
- Set aside dedicated time
|
||||
|
||||
**But much of life is passive time:**
|
||||
- Commuting
|
||||
- Exercising
|
||||
- Doing dishes
|
||||
- Driving
|
||||
- Walking
|
||||
- Idle moments
|
||||
|
||||
### The Solution
|
||||
Convert your research into audio dialogue so you can consume it passively.
|
||||
|
||||
```
|
||||
Before (Text-based):
|
||||
Research pile → Must schedule reading time → Requires focus
|
||||
|
||||
After (Podcast):
|
||||
Research pile → Podcast → Can listen while commuting
|
||||
→ Absorb while exercising
|
||||
→ Understand while walking
|
||||
→ Engage without screen time
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Makes It Special: Open Notebook vs. Competitors
|
||||
|
||||
### Google Notebook LM Podcasts
|
||||
- **Fixed format**: 2 hosts, always conversational
|
||||
- **Limited customization**: You can't choose who the "hosts" are
|
||||
- **One TTS voice per speaker**: Can't customize voices
|
||||
- **Only uses cloud services**: No local options
|
||||
|
||||
### Open Notebook Podcasts
|
||||
- **Customizable format**: 1-4 speakers, you design them
|
||||
- **Rich speaker profiles**: Create personas with backstories and expertise
|
||||
- **Multiple TTS options**:
|
||||
- OpenAI (natural, fast)
|
||||
- Google TTS (high quality)
|
||||
- ElevenLabs (beautiful voices, accents)
|
||||
- Local TTS (privacy-first, no API calls)
|
||||
- **Async generation**: Doesn't block your work
|
||||
- **Full control**: Choose outline structure, tone, depth
|
||||
|
||||
---
|
||||
|
||||
## How Podcast Generation Works
|
||||
|
||||
### Stage 1: Content Selection
|
||||
|
||||
You choose what goes into the podcast:
|
||||
```
|
||||
Notebook content → Which sources? → Which notes?
|
||||
→ Which topics to focus on?
|
||||
→ Depth of coverage?
|
||||
```
|
||||
|
||||
### Stage 2: Episode Profile
|
||||
|
||||
You define how you want the podcast structured:
|
||||
```
|
||||
Episode Profile
|
||||
├─ Topic: "AI Safety Approaches"
|
||||
├─ Length: 20 minutes
|
||||
├─ Tone: Academic but accessible
|
||||
├─ Format: Debate (2 speakers with opposing views)
|
||||
├─ Audience: Researchers new to the field
|
||||
└─ Focus areas: Main approaches, pros/cons, open questions
|
||||
```
|
||||
|
||||
### Stage 3: Speaker Configuration
|
||||
|
||||
You create speaker personas (1-4 speakers):
|
||||
|
||||
```
|
||||
Speaker 1: "Expert Alex"
|
||||
├─ Expertise: "Deep knowledge of alignment research"
|
||||
├─ Personality: "Rigorous, academic, patient with explanation"
|
||||
├─ Accent: (Optional) "British English"
|
||||
└─ Voice Model: Selected from model registry (e.g., OpenAI TTS)
|
||||
└─ Optional per-speaker override of the episode's default voice model
|
||||
|
||||
Speaker 2: "Researcher Sam"
|
||||
├─ Expertise: "Field observer, pragmatic perspective"
|
||||
├─ Personality: "Curious, asks clarifying questions"
|
||||
├─ Accent: "American English"
|
||||
└─ Voice Model: Selected from model registry (e.g., ElevenLabs TTS)
|
||||
```
|
||||
|
||||
### Stage 4: Outline Generation
|
||||
|
||||
System generates episode outline:
|
||||
```
|
||||
EPISODE: "AI Safety Approaches"
|
||||
|
||||
1. Introduction (2 min)
|
||||
Alex: Introduces topic and speakers
|
||||
Sam: What will we cover today?
|
||||
|
||||
2. Main Approaches (8 min)
|
||||
Alex: Explains top 3 approaches
|
||||
Sam: Asks about tradeoffs
|
||||
|
||||
3. Debate: Best approach? (6 min)
|
||||
Alex: Advocates for approach A
|
||||
Sam: Argues for approach B
|
||||
|
||||
4. Open Questions (3 min)
|
||||
Both: What's unsolved?
|
||||
|
||||
5. Conclusion (1 min)
|
||||
Recap and where to learn more
|
||||
```
|
||||
|
||||
### Stage 5: Dialogue Generation
|
||||
|
||||
System generates dialogue based on outline:
|
||||
```
|
||||
Alex: "Today we're exploring three major approaches to AI alignment..."
|
||||
|
||||
Sam: "That's a great start. Can you break down what we mean by alignment?"
|
||||
|
||||
Alex: "Good question. Alignment means ensuring AI systems pursue the goals
|
||||
we actually want them to pursue, not just what we literally asked for.
|
||||
There's a classic example of a paperclip maximizer..."
|
||||
|
||||
Sam: "Interesting. So it's about solving the intention problem?"
|
||||
|
||||
Alex: "Exactly. And that's where the three approaches come in..."
|
||||
```
|
||||
|
||||
### Stage 6: Text-to-Speech
|
||||
|
||||
System converts dialogue to audio using the voice models configured in the model registry. Credentials are automatically resolved from each model's configuration.
|
||||
```
|
||||
Alex's text → Voice model (from registry) → Alex's voice (audio file)
|
||||
Sam's text → Voice model (from registry) → Sam's voice (audio file)
|
||||
Audio files → Mix together → Final podcast MP3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When Things Go Wrong: Failures & Retry
|
||||
|
||||
Podcast generation involves multiple steps (outline, transcript, TTS) and depends on external AI providers. Sometimes things fail.
|
||||
|
||||
### What Happens on Failure
|
||||
|
||||
When podcast generation fails (e.g., wrong model configured, API key expired, provider outage):
|
||||
|
||||
- The episode is marked as **Failed** with a red badge
|
||||
- The **error message** from the AI provider is displayed so you can understand what went wrong
|
||||
- No duplicate episodes are created — automatic retries are disabled to prevent confusion
|
||||
|
||||
### How to Retry a Failed Episode
|
||||
|
||||
1. Go to the podcast's **Episodes** tab
|
||||
2. Find the failed episode — it shows a red "FAILED" badge and an error details box
|
||||
3. Click the **Retry** button
|
||||
4. The failed episode is deleted and a new generation job is submitted
|
||||
5. The new episode appears with "pending" status
|
||||
|
||||
### Common Failure Causes
|
||||
|
||||
| Error | What to Do |
|
||||
|-------|-----------|
|
||||
| Invalid API key | Check Settings -> Credentials for the TTS and language model providers |
|
||||
| Model not found | Verify the model exists in the model registry and has valid credentials configured |
|
||||
| Rate limit exceeded | Wait a few minutes and retry |
|
||||
| Provider unavailable | Check provider status page; retry later |
|
||||
|
||||
---
|
||||
|
||||
## Key Architecture Decisions
|
||||
|
||||
### 1. Asynchronous Processing
|
||||
Podcasts are generated in the background. You upload → system processes → you download when ready.
|
||||
|
||||
**Why?** Podcast generation takes time (10+ minutes for a 30-minute episode). Blocking would lock up your interface.
|
||||
|
||||
### 2. Multi-Speaker Support
|
||||
Unlike Google Notebook LM (always 2 hosts), you choose 1-4 speakers.
|
||||
|
||||
**Why?** Different discussions work better with different formats:
|
||||
- Expert monologue (1 speaker)
|
||||
- Interview (2 speakers: host + expert)
|
||||
- Debate (2 speakers: opposing views)
|
||||
- Panel discussion (3-4 speakers: different expertise)
|
||||
|
||||
### 3. Speaker Customization
|
||||
You create rich speaker profiles, not just "Host A" and "Host B".
|
||||
|
||||
**Why?** Makes podcasts more engaging and authentic. Different speakers bring different perspectives.
|
||||
|
||||
### 4. Multiple TTS Providers
|
||||
You're not locked into one voice provider.
|
||||
|
||||
**Why?**
|
||||
- Cost optimization (some providers cheaper)
|
||||
- Quality preferences (some voices more natural)
|
||||
- Privacy options (local TTS for sensitive content)
|
||||
- Accessibility (different accents, genders, styles)
|
||||
|
||||
### 5. Local TTS Option
|
||||
Can generate podcasts entirely offline with local text-to-speech.
|
||||
|
||||
**Why?** For sensitive research, never send audio to external APIs.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases Show Why This Matters
|
||||
|
||||
### Academic Publishing
|
||||
```
|
||||
Traditional: Academic paper → PDF
|
||||
Problem: Hard to consume, linear reading required
|
||||
|
||||
Open Notebook:
|
||||
Research materials → Podcast (expert explaining methodology)
|
||||
→ Podcast (debate format: different interpretations)
|
||||
→ Different consumption for different audiences
|
||||
```
|
||||
|
||||
### Content Creation
|
||||
```
|
||||
Blog creator: Has research pile on a topic
|
||||
Problem: Doesn't have time to write the article
|
||||
|
||||
Solution:
|
||||
Add research → Create podcast → Transcribe → Becomes article
|
||||
OR: Podcast BECOMES the content (upload to podcast platforms)
|
||||
```
|
||||
|
||||
### Educational Content
|
||||
```
|
||||
Educator: Has reading materials for a course
|
||||
Problem: Students don't read the papers
|
||||
|
||||
Solution:
|
||||
Create podcast with expert explaining papers
|
||||
Students listen → Better engagement → Discussions can reference podcast
|
||||
```
|
||||
|
||||
### Market Research
|
||||
```
|
||||
Product manager: Has interviews with customers
|
||||
Problem: Too many hours of audio to review
|
||||
|
||||
Solution:
|
||||
Create podcast with debate format (customer perspective vs. team perspective)
|
||||
Much more engaging than raw transcripts
|
||||
```
|
||||
|
||||
### Knowledge Transfer
|
||||
```
|
||||
Domain expert: Leaving the organization
|
||||
Problem: How to preserve expertise?
|
||||
|
||||
Solution:
|
||||
Create expert-mode podcast explaining frameworks, decision-making, context
|
||||
New team member listens, gets context faster than reading 100 documents
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Difference: Active vs. Passive Learning
|
||||
|
||||
### Text-Based Research (Active)
|
||||
- **Effort**: High (must focus, read, synthesize)
|
||||
- **When**: Dedicated study time
|
||||
- **Cost**: Time is expensive (can't multitask)
|
||||
- **Best for**: Deep dives, precise information
|
||||
- **Format**: Whatever you write (notes, articles, books)
|
||||
|
||||
### Audio Podcast (Passive)
|
||||
- **Effort**: Low (just listen)
|
||||
- **When**: Anywhere, anytime
|
||||
- **Cost**: Low (can multitask)
|
||||
- **Best for**: Overview, context, exploration
|
||||
- **Format**: Dialogue (more engaging than narration)
|
||||
|
||||
**They complement each other:**
|
||||
1. **First encounter**: Listen to podcast (passive, get context)
|
||||
2. **Deep dive**: Read source materials (active, precise)
|
||||
3. **Mastery**: Both together (understand big picture + details)
|
||||
|
||||
---
|
||||
|
||||
## How Podcasts Fit Into Your Workflow
|
||||
|
||||
```
|
||||
1. Build notebook (add sources)
|
||||
↓
|
||||
2. Apply transformations (extract insights)
|
||||
↓
|
||||
3. Chat/Ask (explore content)
|
||||
↓
|
||||
4. Decide on podcast
|
||||
├─→ Create speaker profiles
|
||||
├─→ Define episode profile
|
||||
├─→ Configure voice models (from model registry)
|
||||
└─→ Generate podcast
|
||||
↓
|
||||
5. Listen while commuting/exercising
|
||||
↓
|
||||
6. Reference sources for deep dive
|
||||
↓
|
||||
7. Repeat for different formats/speakers/focus
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Multiple Podcasts from Same Research
|
||||
|
||||
You can create different podcasts from the same sources:
|
||||
|
||||
### Example: AI Safety Research
|
||||
```
|
||||
Podcast 1: "Expert Monologue"
|
||||
Speaker: Researcher explaining field
|
||||
Format: Educational, comprehensive
|
||||
Audience: Students new to field
|
||||
|
||||
Podcast 2: "Debate Format"
|
||||
Speakers: Optimist vs. skeptic
|
||||
Format: Discussion of tradeoffs
|
||||
Audience: Advanced researchers
|
||||
|
||||
Podcast 3: "Interview Format"
|
||||
Speakers: Journalist + expert
|
||||
Format: Q&A about practical applications
|
||||
Audience: Industry practitioners
|
||||
```
|
||||
|
||||
Each tells the same story from different angles.
|
||||
|
||||
---
|
||||
|
||||
## Privacy & Data Considerations
|
||||
|
||||
### Where Your Data Goes
|
||||
|
||||
**Option 1: Cloud TTS (Faster, Higher Quality)**
|
||||
```
|
||||
Your outline → API call to TTS provider
|
||||
→ Audio returned
|
||||
→ Stored in your notebook
|
||||
|
||||
Provider sees: Your outlined script (not raw sources)
|
||||
Privacy level: Medium (outline is shared, sources aren't)
|
||||
```
|
||||
|
||||
**Option 2: Local TTS (Slower, Maximum Privacy)**
|
||||
```
|
||||
Your outline → Local TTS engine (runs on your machine)
|
||||
→ Audio generated locally
|
||||
→ Stored in your notebook
|
||||
|
||||
Provider sees: Nothing
|
||||
Privacy level: Maximum (everything local)
|
||||
```
|
||||
|
||||
### Recommendation
|
||||
- **Sensitive research**: Use local TTS, no API calls
|
||||
- **Less sensitive**: Use ElevenLabs or Google (both handle audio data professionally)
|
||||
- **Mixed**: Use local TTS for speakers reading sensitive content
|
||||
|
||||
---
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
### Cloud TTS Costs
|
||||
| Provider | Cost | Quality | Speed |
|
||||
|----------|------|---------|-------|
|
||||
| OpenAI | ~$0.015 per minute | Good | Fast |
|
||||
| Google | ~$0.004 per minute | Excellent | Fast |
|
||||
| ElevenLabs | ~$0.10 per minute | Exceptional | Medium |
|
||||
| Local TTS | Free | Basic | Slow |
|
||||
|
||||
A 30-minute podcast costs:
|
||||
- OpenAI: ~$0.45
|
||||
- Google: ~$0.12
|
||||
- ElevenLabs: ~$3.00
|
||||
- Local: Free (but slow)
|
||||
|
||||
---
|
||||
|
||||
## Summary: Why Podcasts Are Special
|
||||
|
||||
**Podcasts transform your research consumption:**
|
||||
|
||||
| Aspect | Text | Podcast |
|
||||
|--------|------|---------|
|
||||
| **How consumed?** | Active reading | Passive listening |
|
||||
| **Where consumed?** | Desk | Anywhere |
|
||||
| **Multitasking** | Hard | Easy |
|
||||
| **Time commitment** | Scheduled | Flexible |
|
||||
| **Format** | Whatever | Natural dialogue |
|
||||
| **Engagement** | Academic | Conversational |
|
||||
| **Accessibility** | Text-based | Audio-based |
|
||||
|
||||
**In Open Notebook specifically:**
|
||||
- **Full customization** — you create speakers and format
|
||||
- **Privacy options** — local TTS for sensitive content
|
||||
- **Cost control** — choose TTS provider based on budget
|
||||
- **Non-blocking** — generates in background
|
||||
- **Multiple versions** — create different podcasts from same research
|
||||
|
||||
This is why podcasts matter: they change *when* and *how* you can consume your research.
|
||||
Reference in New Issue
Block a user