### Start Frontend Development Server

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md

Navigate to the frontend directory, install its dependencies using npm, and start the development server.

```bash
# Terminal 4
cd frontend && npm install && npm run dev
```

--------------------------------

### Clone and Setup Open Notebook

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md

Clone the Open Notebook repository, navigate into the directory, synchronize Python dependencies using uv, and install frontend Node.js dependencies.

```bash
cd %USERPROFILE%\Projects  # or your preferred location
git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
uv sync
cd frontend && npm install && cd ..
```

--------------------------------

### Minimal Setup Environment Variables

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/environment-reference.md

Configure essential variables for a new installation of Open Notebook. This includes encryption keys and SurrealDB connection details.

```shell
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=password
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=open_notebook
```

--------------------------------

### Copy Ollama example docker-compose.yml

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/docker-compose.md

Alternatively, copy the Ollama example configuration file from the repository's examples directory to your project.

```bash
cp examples/docker-compose-ollama.yml docker-compose.yml
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/quick-start.md

Install Node.js if not already installed, then install frontend dependencies using npm.

```bash
# Install Node.js from https://nodejs.org/
# Then install frontend dependencies
cd frontend && npm install
```

--------------------------------

### Start Development with Docker Compose

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Initiates the development environment using Docker Compose, with options for a development profile or a full stack setup.

```bash
make dev
make full
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md

Navigate to the frontend directory and run this command to start the development server.

```bash
cd frontend && npm run dev
```

--------------------------------

### Start Frontend Service

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Starts only the frontend application.

```bash
make frontend
```

--------------------------------

### Start the Frontend

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md

Navigate to the frontend directory and start the Next.js development server. This is optional and runs on port 3000.

```bash
# Terminal 3: Start Next.js frontend (port 3000)
cd frontend
npm install  # First time only
npm run dev
```

--------------------------------

### Start All Services

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md

Convenience command to start the Database, API, Worker, and Frontend services simultaneously.

```bash
# Start everything
make start-all
```

--------------------------------

### Start All Services for Development

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Starts all necessary services including database, API, worker, and frontend for a full local development environment.

```bash
make start-all
```

--------------------------------

### Install MCP Server (No Manual Installation)

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/mcp-integration.md

No manual installation is required for the MCP server. Claude Desktop uses uvx to run it automatically.

```bash
# No manual installation needed! Claude Desktop will use uvx to run it automatically
```

--------------------------------

### Clone and Setup Open Notebook

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Initial steps to clone the repository and set up the environment for local development.

```bash
git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
cp .env.example .env
cp .env.example docker.env
uv sync
```

--------------------------------

### Start API Server

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md

Start the API server for Open Notebook. This can be done using the Makefile target or by running uvicorn directly with uv.

```bash
# Terminal 2
make api
# or: uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md

Install project dependencies using uv (recommended) or pip. Ensure you have Python 3.11+ installed.

```bash
# Using uv (recommended)
uv sync

# Or using pip
pip install -e .
```

--------------------------------

### Start Open Notebook Services

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/advanced.md

Use docker compose to start all defined services in detached mode.

```bash
# Start services
docker compose up -d
```

--------------------------------

### Usage Example

Source: https://github.com/lfnovo/open-notebook/blob/main/frontend/src/lib/hooks/CLAUDE.md

A practical example demonstrating how to use various credential hooks in a React component.

```APIDOC
## Usage Example

```typescript
import {
  useCredentialStatus,
  useCredentials,
  useCreateCredential,
  useTestCredential,
  useMigrateFromEnv
} from '@/lib/hooks/use-credentials'

function CredentialSettings() {
  const { data: status, isLoading } = useCredentialStatus()
  const { data: credentials } = useCredentials()
  const createCredential = useCreateCredential()
  const { testCredential, testResults, isPending } = useTestCredential()
  const migrateFromEnv = useMigrateFromEnv()

  const handleCreate = () => {
    createCredential.mutate({
      name: 'My OpenAI Key',
      provider: 'openai',
      modalities: ['language', 'embedding'],
      api_key: 'sk-...'
    })
  }

  const handleTest = (credentialId: string) => {
    testCredential(credentialId)
  }

  const handleMigrate = () => {
    migrateFromEnv.mutate()
  }

  return (
    <div>
      {credentials?.map(cred => (
        <div key={cred.id}>
          <span>{cred.name} ({cred.provider})</span>
          <button onClick={() => handleTest(cred.id)} disabled={isPending}>Test</button>
          {testResults[cred.id]?.success && <span>Connected!</span>}
        </div>
      ))}
      <button onClick={handleCreate}>Add Credential</button>
      <button onClick={handleMigrate}>Migrate from .env</button>
    </div>
  )
}
```
```

--------------------------------

### vLLM: Start Server

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/openai-compatible.md

Command to start the vLLM server with OpenAI API compatibility enabled.

```bash
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --port 8000
```

--------------------------------

### Start API Service

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Starts only the backend API service.

```bash
make api
```

--------------------------------

### Start Open Notebook Services

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/quick-start.md

Start the SurrealDB, API, and Frontend services in separate terminals. Docker is optional for SurrealDB.

```bash
# Terminal 1: Start SurrealDB (database)
make database
# or: docker run -d --name surrealdb -p 8000:8000 surrealdb/surrealdb:v2 start --user root --pass password --bind 0.0.0.0:8000 memory

# Terminal 2: Start API (backend on port 5055)
make api
# or: uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055

# Terminal 3: Start Frontend (UI on port 3000)
cd frontend && npm run dev
```

--------------------------------

### Quick Start: Applying a Transformation

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/3-USER-GUIDE/transformations.md

Follow these steps to apply a built-in transformation template to your sources.

```text
1. Go to your notebook
2. Click "Transformations" in navigation
3. Select a built-in template (e.g., "Summary")
4. Select sources to transform
5. Click "Apply"
6. Wait for processing
7. New notes appear automatically
```

--------------------------------

### Install Python Dependencies with uv

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/quick-start.md

Install Python dependencies using the uv package manager. Verify uv installation.

```bash
# Install Python dependencies
uv sync

# Verify uv is working
uv --version
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Installs Node.js dependencies for the frontend application.

```bash
cd frontend && npm install package-name
```

--------------------------------

### Text Generation WebUI: Start with API Enabled

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/openai-compatible.md

Command to start the Text Generation WebUI server with the API enabled and listening.

```bash
python server.py --api --listen
```

--------------------------------

### Start SurrealDB using Docker Compose

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md

If using Docker Compose, start the SurrealDB service with this command.

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

--------------------------------

### Start Database Service

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Starts only the database service, useful for specific development needs.

```bash
make database
```

--------------------------------

### Start SurrealDB

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md

Start the SurrealDB database. This can be done using the provided Makefile target or directly with Docker Compose.

```bash
# Terminal 1
make database
# or: docker compose up surrealdb
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md

Install git hooks to automatically check code quality before each commit. This is optional but recommended.

```bash
uv run pre-commit install
```

--------------------------------

### Start API Service

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/6-TROUBLESHOOTING/connection-issues.md

If the API is not running, start it using `docker compose up`. Ensure to wait a few seconds and verify its status.

```bash
# Start API
docker compose up api -d

# Wait 5 seconds
sleep 5

# Verify it's running
docker compose logs api | tail -20
```

--------------------------------

### Development Password Setup

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/security.md

Configure the password for development environments using a `.env` file. This is a simpler setup for local testing and development.

```bash
# .env
OPEN_NOTEBOOK_PASSWORD=your_secure_password
```

--------------------------------

### curl Examples for API Interaction

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/security.md

Provides `curl` command examples for common API operations including listing notebooks, creating a notebook, and uploading a file. Ensure you replace `your_password` with your actual password.

```bash
# List notebooks
curl -H "Authorization: Bearer your_password" \
  http://localhost:5055/api/notebooks

# Create notebook
curl -X POST \
  -H "Authorization: Bearer your_password" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Notebook", "description": "Research notes"}' \
  http://localhost:5055/api/notebooks

# Upload file
curl -X POST \
  -H "Authorization: Bearer your_password" \
  -F "file=@document.pdf" \
  http://localhost:5055/api/sources/upload
```

--------------------------------

### Start Open Notebook Services

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/0-START-HERE/quick-start-cloud.md

Execute this command in your terminal within the 'open-notebook' directory to start the Docker services defined in your docker-compose.yml file.

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

--------------------------------

### Notebook Example: Customer Research

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/2-CORE-CONCEPTS/notebooks-sources-notes.md

An example illustrating a notebook's scope, description, and how its context applies to sources, notes, and AI interactions.

```text
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
```

--------------------------------

### Docker Compose Example with SSL Configuration

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/ollama.md

Example of configuring Open Notebook in Docker Compose, including environment variables for encryption keys and SSL settings like custom CA bundles or disabling verification.

```yaml
# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
services:
  open-notebook:
    image: lfnovo/open_notebook:v1-latest
    pull_policy: always
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
      # Option 1: Custom CA bundle (if Ollama uses self-signed SSL)
      - ESPERANTO_SSL_CA_BUNDLE=/certs/ca-bundle.pem
      # Option 2: Disable verification (dev only)
      # - ESPERANTO_SSL_VERIFY=false
    volumes:
      - /path/to/your/ca-bundle.pem:/certs/ca-bundle.pem:ro
```

--------------------------------

### Authenticate and Access Notebooks (Development)

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/api-reference.md

Example of authenticating with a bearer token and accessing the notebooks endpoint. This is for development purposes only.

```bash
curl -H "Authorization: Bearer your_password" http://localhost:5055/api/notebooks
```

--------------------------------

### Ollama Command Line Examples

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/ai-providers.md

Basic command-line operations for managing Ollama, including serving and downloading models.

```bash
ollama serve
```

```bash
ollama pull mistral
```

```bash
ollama list
```

--------------------------------

### Create and Configure .env File

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md

Copy the example environment file and edit it with your specific configuration for the database, encryption key, and application settings.

```bash
# Copy from example
cp .env.example .env
```

```bash
# Database
SURREAL_URL=ws://localhost:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=password
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=development

# Credential encryption (required for storing API keys)
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-dev-secret-key

# Application
APP_PASSWORD=  # Optional password protection
DEBUG=true
LOG_LEVEL=DEBUG
```

--------------------------------

### Start Speaches and Download Model

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/local-tts.md

Commands to start the Speaches Docker container in detached mode and then download a specific voice model using the Speaches CLI. Ensure the container is running before executing the download command.

```bash
# Start Speaches
docker compose up -d

# Wait for startup
sleep 10

# Download voice model (~500MB)
docker compose exec speaches uv tool run speaches-cli model download speaches-ai/Kokoro-82M-v1.0-ONNX
```

--------------------------------

### Docker Compose for Local Testing

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/single-container.md

Use this Docker Compose configuration for local testing of the Open Notebook single-container setup. Ensure Docker is installed and running.

```yaml
services:
  open_notebook:
    image: lfnovo/open_notebook:v1-latest-single
    pull_policy: always
    ports:
      - "8502:8502"  # Web UI (React frontend)
      - "5055:5055"  # API
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
      - SURREAL_URL=ws://localhost:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=root
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
    volumes:
      - ./data:/app/data
    restart: always
```

--------------------------------

### Verify Ollama Model Names

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/6-TROUBLESHOOTING/ai-chat-issues.md

Use `ollama list` to get the exact names of your installed Ollama models. Ensure these names precisely match the configuration in Open Notebook to avoid errors.

```bash
# Get exact model names
ollama list
```

```bash
# Example output:
# NAME                   SIZE      MODIFIED
# gemma3:12b            8.1 GB    2 months ago

# The model name in Open Notebook must be EXACTLY "gemma3:12b"
# NOT "gemma3" or "gemma3-12b"
```

--------------------------------

### Get Default AI Model by Type (Python)

Source: https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/CLAUDE.md

Fetches a default AI model based on the specified type, with smart fallback logic. For example, 'transformation' type might fall back to the 'chat' model if not explicitly configured.

```python
def get_default_model(self, model_type: str) -> BaseAIModel:
    """Smart lookup (e.g., "chat" → default_chat_model, "transformation" → default_transformation_model with fallback to chat)."""
    defaults = self.get_defaults()
    model_name = getattr(defaults, f"default_{model_type}_model")

    if not model_name:
        if model_type == "transformation":
            model_name = defaults.default_chat_model
        else:
            raise ValueError(f"Default model for type '{model_type}' not configured")

    return self.get_model(model_name)

```

--------------------------------

### Quick-Start: Using Chat

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/3-USER-GUIDE/chat-effectively.md

Follow these steps to initiate your first chat session. Context management is key for effective dialogue.

```text
1. Go to your notebook
2. Click "Chat"
3. Select which sources to include (context)
4. Type your question
5. Click "Send"
6. Read the response
7. Ask a follow-up (context stays same)
8. Repeat until satisfied
```

--------------------------------

### Setting Context: Step-by-Step Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/3-USER-GUIDE/chat-effectively.md

This outlines the process for setting context levels for each source in your notebook. Ensure your selections are checked before saving.

```text
1. Click "Select Sources"
   (Shows list of all sources in notebook)

2. For each source:
   □ Checkbox: Include or exclude

   Level dropdown:
   ├─ Full Content
   ├─ Summary Only
   └─ Excluded

3. Check your selections
   Example:
   ✓ Paper A (Full Content) - "Main focus"
   ✓ Paper B (Summary Only) - "Background"
   ✓ Paper C (Excluded) - "Keep private"
   □ Paper D (Not included) - "Not relevant"

4. Click "Save Context"

5. Now chat uses these settings
```

--------------------------------

### Install Python Dependencies with uv

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md

Install all required Python dependencies using the uv package manager. Also installs the python-magic library.

```bash
uv sync
uv pip install python-magic
```

--------------------------------

### Reset to Default Configuration

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/6-TROUBLESHOOTING/quick-fixes.md

Restore the default configuration by copying the example .env file. Remember to back up your current .env file first and re-enter your API keys.

```bash
# Backup your .env first!
cp .env .env.backup

# Reset to example
cp .env.example .env

# Edit with your API keys
# Restart
docker compose up
```

--------------------------------

### Start Worker Service

Source: https://github.com/lfnovo/open-notebook/blob/main/README.dev.md

Starts only the background worker service.

```bash
make worker
```

--------------------------------

### Deploy to Production - Review Configuration

Source: https://github.com/lfnovo/open-notebook/blob/main/open_notebook/CLAUDE.md

Review the `CONFIGURATION.md` file for essential security settings before deploying to production. Ensure all configurations are appropriate for a production environment.

```markdown
[CONFIGURATION.md](CONFIGURATION.md)
```

--------------------------------

### Product Research Workflow Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/2-CORE-CONCEPTS/chat-vs-transformations.md

This workflow shows how to use ASK to identify key themes from interview transcripts, followed by CHAT for conversational analysis and optional TRANSFORMATIONS for structured data extraction.

```text
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
```

--------------------------------

### Start Speaches and Download Model

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/local-stt.md

Commands to start the Speaches container in detached mode and download a Whisper model. A 10-second sleep is included to allow the service to start before executing the model download command.

```bash
# Start Speaches
docker compose up -d

# Wait for startup
sleep 10

# Download Whisper model (~500MB for small)
docker compose exec speaches uv tool run speaches-cli model download Systran/faster-whisper-small
```

--------------------------------

### Download Ollama example docker-compose.yml

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/docker-compose.md

Download a pre-configured docker-compose.yml file that includes Ollama for local AI model support.

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/main/examples/docker-compose-ollama.yml
```

--------------------------------

### Install Ollama on Linux/macOS

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/ollama.md

Use this command to download and install Ollama on Linux and macOS systems.

```bash
curl -fsSL https://ollama.ai/install.sh | sh
```

--------------------------------

### Install and Run Ollama Locally

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/6-TROUBLESHOOTING/ai-chat-issues.md

Set up Ollama for local model execution, including serving the API and downloading a model. This provides a free alternative to cloud providers.

```bash
# Install Ollama
# Run: ollama serve
# Download: ollama pull mistral
# Set: OLLAMA_API_BASE=http://localhost:11434
# Cost: Free!
```

--------------------------------

### Troubleshoot Service Startup

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/local-stt.md

Commands to check logs, verify port availability, and restart the service using Docker Compose.

```bash
# Check logs
docker compose logs speaches

# Verify port available
lsof -i :8969

# Restart
docker compose down && docker compose up -d
```

--------------------------------

### Policy Analysis Workflow Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/2-CORE-CONCEPTS/chat-vs-transformations.md

This workflow illustrates using ASK to compare policy documents, followed by CHAT for in-depth discussion and optional note export for reporting.

```text
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
```

--------------------------------

### Troubleshoot Speaches Service Startup

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/local-tts.md

Commands to check logs, verify port availability, and restart the Speaches Docker service. Use these when the service fails to start.

```bash
# Check logs
docker compose logs speaches
```

```bash
# Verify port available
lsof -i :8969
```

```bash
# Restart
docker compose down && docker compose up -d
```

--------------------------------

### Test Create Notebook with Sources (Integration)

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md

Tests creating a notebook and adding sources to it, then retrieving the notebook with its sources. Requires helper functions like create_notebook, add_source, and get_notebook_with_sources.

```python
@pytest.mark.asyncio
async def test_create_notebook_with_sources():
    """Test creating a notebook and adding sources."""
    notebook = await create_notebook(name="Research", description="")
    source = await add_source(notebook_id=notebook.id, url="https://example.com")

    retrieved = await get_notebook_with_sources(notebook.id)
    assert len(retrieved.sources) == 1
    assert retrieved.sources[0].id == source.id
```

--------------------------------

### Basic Async Test Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md

A simple pytest example for testing an asynchronous function. Requires `pytest.mark.asyncio` and an `some_async_function`.

```python
@pytest.mark.asyncio
async def test_async_operation():
    """Test async function."""
    result = await some_async_function()
    assert result is not None
```

--------------------------------

### Authenticate and List Notebooks (Development)

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/api-reference.md

Use this command for basic authentication in development environments. Replace 'your_password' with your actual password. For production, use OAuth/JWT.

```bash
curl http://localhost:5055/api/notebooks \
  -H "Authorization: Bearer your_password"
```

--------------------------------

### Get Specific Credential

Source: https://github.com/lfnovo/open-notebook/blob/main/api/CLAUDE.md

Retrieve details for a specific credential by its ID using the GET /credentials/{credential_id} endpoint.

```python
GET /credentials/{credential_id}
```

--------------------------------

### Python Function Docstring with Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/code-standards.md

Document functions comprehensively, including parameters, return values, exceptions, and a usage example.

```python
async def create_notebook(
    name: str,
    description: str = "",
    user_id: Optional[str] = None
) -> Notebook:
    """Create a new notebook with validation.

    Args:
        name: The notebook name (required, non-empty)
        description: Optional notebook description
        user_id: Optional user ID for multi-user deployments

    Returns:
        The created notebook instance

    Raises:
        InvalidInputError: If name is empty or invalid
        DatabaseOperationError: If creation fails

    Example:
        ```python
        notebook = await create_notebook(
            name="AI Research",
            description="Research on AI applications"
        )
        ```
    """
```

--------------------------------

### Start the API Server

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md

Run the API server using uv and uvicorn. Ensure the .env file is present in the project root. The API will run on port 5055.

```bash
# Terminal 2: Start API (port 5055)
uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055

# Or using the shortcut
make api
```

--------------------------------

### Source Example: OpenAI Charter PDF

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/2-CORE-CONCEPTS/notebooks-sources-notes.md

An example of a PDF source, detailing the processing steps and searchability after being added to a notebook.

```text
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"
```

--------------------------------

### Podcast Dialogue Generation Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/2-CORE-CONCEPTS/podcasts-explained.md

An example of generated dialogue between two speakers, Alex and Sam, discussing AI alignment approaches.

```text
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..."
```

--------------------------------

### Discover and Register Models

Source: https://github.com/lfnovo/open-notebook/blob/main/frontend/src/lib/api/CLAUDE.md

This example shows how to discover available models for a credential and then register them. It requires the `credentialsApi` to be imported and uses the credential ID. The discovered models are mapped to the required format for registration.

```typescript
// Discover and register models
const discovered = await credentialsApi.discover(cred.id)
await credentialsApi.registerModels(cred.id, {
  models: discovered.models.map(m => ({ model_id: m.model_id, name: m.name, type: 'language' }))
})
```

--------------------------------

### Migrate Open Notebook Between Servers

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/advanced.md

Perform a migration by stopping services on the source server, creating a tar archive of data, transferring it to the new server, extracting it, and starting services.

```bash
# On source server
docker compose down
tar -czf open-notebook-migration.tar.gz notebook_data/ surreal_data/

# Transfer to new server
scp open-notebook-migration.tar.gz user@newserver:/path/

# On new server
tar -xzf open-notebook-migration.tar.gz
docker compose up -d
```

--------------------------------

### Start Docker Services

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/0-START-HERE/quick-start-openai.md

Run this command in your terminal within the 'open-notebook' directory to start the defined Docker services in detached mode.

```bash
docker compose up -d

```

--------------------------------

### Quantized Model Performance Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/openai-compatible.md

Illustrates the RAM and speed differences between quantized and full-precision models. Quantized models like Q4_K_M offer significant RAM savings and faster inference.

```text
llama-3-8b-q4_k_m.gguf  → ~4GB RAM, fast
llama-3-8b-f16.gguf     → ~16GB RAM, slower
```

--------------------------------

### Set Environment Variables

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md

Copy the example environment file and edit it to set necessary environment variables, such as the encryption key.

```bash
cp .env.example .env
# Edit .env and set:
# OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
```

--------------------------------

### Start Ollama Server

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/0-START-HERE/quick-start-external-ollama.md

Start the Ollama server on the default host and port (http://localhost:11434). Keep this terminal open while Ollama is in use.

```bash
ollama serve
```

--------------------------------

### Provision All Keys

Source: https://github.com/lfnovo/open-notebook/blob/main/api/CLAUDE.md

Load all provider keys stored in the database into environment variables using the `provision_all_keys()` function. This ensures all configured credentials are available system-wide.

```python
provision_all_keys()
```

--------------------------------

### Install Certbot and Obtain Nginx Certificate

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/reverse-proxy.md

Steps to install Certbot for Nginx and obtain an SSL certificate for your domain. Auto-renewal is typically configured by Certbot.

```bash
# Install certbot
sudo apt install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d notebook.example.com

# Auto-renewal (usually configured automatically)
sudo certbot renew --dry-run
```

--------------------------------

### SurrealDB Configuration: Local Machine Setup

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/database.md

These environment variables are for when both Open Notebook and SurrealDB are running on the same local machine, including the deprecated single-container setup.

```env
SURREAL_URL="ws://localhost:8000/rpc"
SURREAL_USER="root"
SURREAL_PASSWORD="root"
SURREAL_NAMESPACE="open_notebook"
SURREAL_DATABASE="open_notebook"
```

--------------------------------

### Example Note Structure with Markdown

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/3-USER-GUIDE/working-with-notes.md

An example of a well-structured note using markdown for headings, lists, and emphasis, covering key findings, methodology, and personal thoughts.

```markdown
# Key Findings from "AI Safety Paper 2025"

## Main Argument
The paper argues that X approach is better than Y because...

## Methodology
The authors use [methodology] to test this hypothesis.

## Key Results
- Result 1: [specific finding with citation]
- Result 2: [specific finding with citation]
- Result 3: [specific finding with citation]

## Gaps & Limitations
1. The paper assumes X, which might not hold in Y scenario
2. Limited to Z population/domain
3. Future work needed on A, B, C

## My Thoughts
- This connects to previous research on...
- Potential application in...

## Next Steps
- [ ] Read the referenced paper on X
- [ ] Find similar studies on Y
- [ ] Discuss implications with team
```

--------------------------------

### Start Ollama on Custom Port

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/ollama.md

Use this command to start the Ollama server on a specific port, such as 8080. This is useful if the default port 11434 is already in use.

```bash
OLLAMA_HOST=0.0.0.0:8080 ollama serve
```

--------------------------------

### View API Documentation

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md

Open the interactive API documentation in your browser.

```bash
# View API docs
open http://localhost:5055/docs
```

--------------------------------

### Meeting Notes Template Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/3-USER-GUIDE/transformations.md

An example prompt template for extracting key information from meeting transcripts, including attendees, decisions, action items, and open questions.

```text
Name: Meeting Summary

Prompt:
"From this meeting transcript, extract:

**Attendees**: Who was present
**Date/Time**: When it occurred
**Key Decisions**: What was decided (numbered)
**Action Items**:
- [ ] Task (Owner, Due Date)
**Open Questions**: Unresolved issues
**Next Steps**: What happens next

Format as clear, scannable notes."
```

--------------------------------

### Good Question Example

Source: https://github.com/lfnovo/open-notebook/blob/main/docs/3-USER-GUIDE/chat-effectively.md

Formulate specific questions that clearly define the scope and request citations. This example asks about limitations in the methodology section and requires page references.

```text
"Based on the paper's methodology section,
what are the three main limitations the authors acknowledge?
Please cite which pages mention each one."

Strengths:
- Specific about what you want
- Clear scope (methodology section)
- Asks for citations
- Requires deep reading

Result: Precise, verifiable, useful answer
```