domains / research / open-notebook-automation / open-notebook

open-notebook

Skill card

combined

The two skills cover the same tool (Open Notebook) but diverge significantly in implementation details and API contracts. The K-Dense skill is more rigorous, pinning a specific version (v1.14.0), providing bundled Python helpers, and explicitly correcting common API misconceptions (e.g., model types are 'language' not 'llm'). The FreedomIntelligence skill is a broader overview that includes raw REST API examples for features like podcast generation and search, but it uses a potentially unstable 'main' branch reference and contains API calls that appear inconsistent with the more detailed K-Dense documentation (e.g., using 'model_ids' for registration vs 'models[]' with explicit types). Because the K-Dense skill contains critical safety/versioning constraints and helper usage that the other lacks, while the FreedomIntelligence skill provides raw endpoint examples for features (podcasts, search) that are truncated or less detailed in the K-Dense copy, neither is a complete superset. Combining them allows an agent to use the safe, versioned deployment and helper approach from K-Dense while referencing the raw API patterns from FreedomIntelligence for features not fully detailed in the K-Dense snippet.

Repositories

Other copies

Combined skill

---
name: open-notebook
description: Automate Open Notebook (self-hosted NotebookLM alternative) for research ingestion, chat, and podcast generation. Use for REST API automation, provider configuration, and bundled helper scripts.
license: MIT
metadata:
  version: "1.5"
  skill-author: K-Dense Inc.
---

# Open Notebook

## Overview
Open Notebook is a self-hosted, open-source alternative to Google NotebookLM. It supports source ingestion (PDFs, web, audio, video), cited chat, vector search, and multi-speaker podcasts. This skill targets v1.14.0.

## Quick Start

### Installation
Use Docker Compose. **Do not use `main` branch**; pin to a specific release tag for reproducibility.

```bash
curl --fail --location --output docker-compose.yml \
  https://raw.githubusercontent.com/lfnovo/open-notebook/v1.14.0/docker-compose.yml
```

**Critical Configuration:**
1. Edit `docker-compose.yml` to replace the literal `OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me...` with `${OPEN_NOTEBOOK_ENCRYPTION_KEY:?Set OPEN_NOTEBOOK_ENCRYPTION_KEY}`.
2. Export the variable in your shell: `export OPEN_NOTEBOOK_ENCRYPTION_KEY="your-secret"`.
3. Optionally set `OPEN_NOTEBOOK_PASSWORD` for Bearer token auth.

```bash
docker compose up -d
```

- UI: `http://localhost:8502`
- API: `http://localhost:5055/api`

### Configure AI Providers
1. Go to **Manage → Models** in the UI.
2. Add credentials and test the connection.
3. Discover models. Note: Discovery returns `name` and `provider` but often lacks `model_type`.
4. Register models explicitly. You must specify `model_type` as one of: `language`, `embedding`, `speech_to_text`, `text_to_speech`. **Do not use** `llm`, `stt`, or `tts`.

## Core Features

### Using Bundled Helpers (Recommended)
The K-Dense skill provides Python helpers in `scripts/`. Use these for reliable interaction.

```python
from notebook_management import create_notebook
from source_ingestion import add_text_source, wait_for_processing
from chat_interaction import build_context, create_chat_session, send_chat_message

# Create notebook
notebook = create_notebook("Research", "Description")

# Add source
source = add_text_source(notebook["id"], "Title", "Content", process_async=True)
wait_for_processing(source["id"])

# Chat
built = build_context(notebook["id"], source_ids=[source["id"]])
session = create_chat_session(notebook["id"], "Session")
answer = send_chat_message(session["id"], "Question", built["context"])
```

### Raw REST API Examples
If not using helpers, use the following patterns:

**Create Notebook:**
```python
import requests
BASE_URL = "http://localhost:5055/api"
resp = requests.post(f"{BASE_URL}/notebooks", json={"name": "Test", "description": "Desc"})
```

**Add Source (Web URL):**
```python
resp = requests.post(f"{BASE_URL}/sources", data={"url": "https://example.com", "notebook_id": notebook_id, "process_async": "true"})
```

**Search:**
```python
# Vector search
results = requests.post(f"{BASE_URL}/search", json={"query": "term", "search_type": "vector"}).json()
```

**Podcast Generation:**
```python
# Requires episode and speaker profile IDs
job = requests.post(f"{BASE_URL}/podcasts/generate", json={"notebook_id": notebook_id, "episode_profile_id": ep_id, "speaker_profile_ids": [sp_id]})
```

## Conflicts & Notes
- **Versioning:** Always pin the Docker image/compose file to a specific tag (e.g., v1.14.0). The `main` branch may contain breaking changes.
- **Model Types:** The API is strict about `model_type` values. Use `language`, not `llm`.
- **Encryption:** The encryption key encrypts provider credentials, not source documents. It must be stable across restarts.