Jupyter Integration

Overview

Thesis provides a complete implementation of the Jupyter REST and WebSocket APIs, allowing seamless integration with any Jupyter server. The implementation is in apps/frontend/lib/jupyter/.

Key components:

• kernels.ts - Kernel lifecycle management
• sessions.ts - Session management
• contents.ts - File operations
• ws.ts - WebSocket communication
• notebook.ts - Notebook file utilities

Kernels API

Manage computational kernels:

// List all running kernels
KernelsAPI.list()

// Start a new kernel
KernelsAPI.start({ name: 'python3' })

// Get kernel information
KernelsAPI.get(kernelId)

// Interrupt execution
KernelsAPI.interrupt(kernelId)

// Restart kernel (clear state)
KernelsAPI.restart(kernelId)

// Shutdown kernel
KernelsAPI.shutdown(kernelId)

Kernel states: starting, idle, busy, restarting, dead

Sessions API

Associate notebooks with kernels:

// Create a session
SessionsAPI.create({
  path: 'notebook.ipynb',
  kernel: { name: 'python3' }
})

// List active sessions
SessionsAPI.list()

// Update session (change kernel)
SessionsAPI.update(sessionId, { kernel: { id: newKernelId } })

// Delete session
SessionsAPI.delete(sessionId)

Contents API

File and directory operations:

// Get file/directory contents
ContentsAPI.get(path, { content: true })

// Create new notebook
ContentsAPI.create(path, { type: 'notebook' })

// Save file
ContentsAPI.save(path, { content: notebookJson })

// Delete file
ContentsAPI.delete(path)

// Rename file
ContentsAPI.rename(oldPath, newPath)

// Checkpoints (version control)
ContentsAPI.createCheckpoint(path)
ContentsAPI.listCheckpoints(path)
ContentsAPI.restoreCheckpoint(path, checkpointId)

WebSocket Communication

Real-time bidirectional communication with kernels using the Jupyter messaging protocol (v5.3):

// Create connection
const connection = new KernelConnection(kernelId, sessionId)
await connection.connect()

// Execute code
const msgId = connection.execute(code)

// Handle messages
connection.on('execute_result', (msg) => { ... })
connection.on('stream', (msg) => { ... })
connection.on('error', (msg) => { ... })

// Request completion
connection.complete(code, cursorPos)

// Request documentation
connection.inspect(code, cursorPos, detailLevel)

Connection features:

• Exponential backoff reconnection (up to 5 attempts)
• Message queuing when disconnected
• 10-second connection timeout
• Automatic channel routing (shell, iopub, stdin)

Notebook Format

Thesis uses Jupyter notebook format v4.5 (.ipynb files):

{
  "cells": [...],        // Array of cell objects
  "metadata": {...},     // Notebook metadata
  "nbformat": 4,
  "nbformat_minor": 5
}

Utility functions in notebook.ts:

• createNotebook() - Create empty notebook
• createCell(type, source) - Create cell
• insertCell(), deleteCell(), updateCell()
• moveCell() - Reorder cells
• clearAllOutputs() - Clear execution outputs