@datalayer/jupyter-react 1.2.2 → 2.0.0

package/lib/components/notebook/NotebookAdapter.d.ts

@@ -1,72 +1,269 @@
-import { CompletionHandler } from '@jupyterlab/completer';
-import { Context } from '@jupyterlab/docregistry';
-import { CellType, INotebookContent } from '@jupyterlab/nbformat';
-import { INotebookModel, NotebookPanel } from '@jupyterlab/notebook';
-import { Kernel as JupyterKernel, ServiceManager } from '@jupyterlab/services';
 import { CommandRegistry } from '@lumino/commands';
-import { BoxPanel } from '@lumino/widgets';
-import { Kernel, Lite } from '../../jupyter';
-import { INotebookProps } from './Notebook';
+import { NotebookPanel, type Notebook } from '@jupyterlab/notebook';
+import { Context } from '@jupyterlab/docregistry';
+import { NotebookModel } from '@jupyterlab/notebook';
+import * as nbformat from '@jupyterlab/nbformat';
 export declare class NotebookAdapter {
-    private _boxPanel;
     private _commands;
-    private _contentFactory;
-    private _context?;
-    private _documentRegistry?;
-    private _iPyWidgetsManager?;
-    private _id;
-    private _kernel?;
-    private _kernelConnection;
-    private _kernelClients?;
-    private _kernelTransfer?;
-    private _lite?;
-    private _mimeTypeService;
-    private _nbformat?;
-    private _notebookModelFactory?;
-    private _notebookPanel?;
-    private _onSessionConnection?;
-    private _panelProvider;
-    private _path?;
-    private _readonly;
-    private _renderers;
-    private _rendermime?;
-    private _serverless;
-    private _serviceManager;
-    private _tracker?;
-    private _url?;
-    private _useVSCodeTheme;
-    constructor(props: INotebookProps);
-    loadFromUrl(url: string): Promise<any>;
-    notebookKeydownListener: (event: KeyboardEvent) => void;
-    setupCompleter(notebookPanel: NotebookPanel): CompletionHandler;
-    initializeContext(): void;
-    private setupAdapter;
-    get id(): string;
-    get readonly(): boolean;
-    get serverless(): boolean;
-    get lite(): Lite | undefined;
-    get path(): string | undefined;
-    get url(): string | undefined;
-    get nbformat(): INotebookContent | undefined;
-    get kernel(): Kernel | undefined;
-    get kernelConnection(): JupyterKernel.IKernelConnection | null | undefined;
-    get notebookPanel(): NotebookPanel | undefined;
-    get context(): Context<INotebookModel> | undefined;
-    set notebookPanel(notebookPanel: NotebookPanel | undefined);
-    get panel(): BoxPanel;
+    private _panel;
+    private _notebook;
+    private _context;
+    private _defaultCellType;
+    constructor(commands: CommandRegistry, panel: NotebookPanel, context: Context<NotebookModel>);
+    /**
+     * Get the command registry.
+     */
     get commands(): CommandRegistry;
-    get serviceManager(): ServiceManager.IManager;
-    setNbformat(nbformat?: INotebookContent): void;
-    setServiceManager(serviceManager: ServiceManager.IManager, lite?: Lite): void;
-    setKernel(kernel?: Kernel): void;
-    setReadonly(readonly: boolean): void;
-    setServerless(serverless: boolean): void;
-    setPath(path: string): void;
-    assignKernel(kernel: Kernel): void;
-    setDefaultCellType: (cellType: CellType) => void;
-    changeCellType: (cellType: CellType) => void;
-    insertAbove: (source?: string) => void;
-    insertBelow: (source?: string) => void;
-    dispose: () => void;
+    /**
+     * Get the notebook panel.
+     */
+    get panel(): NotebookPanel;
+    /**
+     * Get the notebook widget.
+     */
+    get notebook(): Notebook;
+    /**
+     * Get the notebook context.
+     */
+    get context(): Context<NotebookModel>;
+    /**
+     * Set the default cell type for new cells.
+     */
+    setDefaultCellType(cellType: nbformat.CellType): void;
+    /**
+     * Get the default cell type for new cells.
+     */
+    get defaultCellType(): nbformat.CellType;
+    /**
+     * Insert a new cell above the active cell.
+     */
+    insertAbove(source?: string): void;
+    /**
+     * Insert a new cell below the active cell.
+     */
+    insertBelow(source?: string): void;
+    /**
+     * Change the type of the active cell.
+     */
+    changeCellType(cellType: nbformat.CellType): void;
+    /**
+     * Delete the currently selected cells.
+     */
+    deleteCells(): void;
+    /**
+     * Get the notebook model.
+     */
+    get model(): NotebookModel | null;
+    /**
+     * Undo the last change in the notebook.
+     *
+     * @remarks
+     * If there is no history to undo (e.g., at the beginning of the undo stack),
+     * this operation will have no effect. The notebook must be available and
+     * properly initialized for this operation to succeed.
+     */
+    undo(): void;
+    /**
+     * Redo the last undone change in the notebook.
+     *
+     * @remarks
+     * If there is no history to redo (e.g., no prior undo operations or at the
+     * end of the redo stack), this operation will have no effect. The notebook
+     * must be available and properly initialized for this operation to succeed.
+     */
+    redo(): void;
+    /**
+     * Set the active cell by index.
+     *
+     * @param index - The index of the cell to activate (0-based)
+     *
+     * @remarks
+     * This method programmatically selects a cell at the specified index.
+     * If the index is out of bounds, the operation has no effect.
+     */
+    setActiveCell(index: number): void;
+    /**
+     * Get all cells from the notebook.
+     *
+     * @returns Array of cell data including type, source, and outputs
+     *
+     * @remarks
+     * This method extracts cell information from the notebook model.
+     * For code cells, outputs are included. Returns an empty array if
+     * the notebook model is not available.
+     */
+    getCells(): Array<{
+        index: number;
+        type: nbformat.CellType;
+        source: string;
+        outputs?: unknown[];
+    }>;
+    /**
+     * Read all cells from the notebook (alias for getCells).
+     *
+     * @param format - Response format: 'brief' returns preview only, 'detailed' returns full content
+     * @returns Array of cell data - brief or detailed based on format
+     *
+     * @remarks
+     * This method is an alias for getCells() to match the readAllCells tool operation.
+     * Provides a consistent naming convention for read operations.
+     * Supports brief format (index, type, 40-char preview) and detailed format (full content).
+     */
+    readAllCells(format?: 'brief' | 'detailed'): Array<{
+        index: number;
+        type: string;
+        preview?: string;
+        source?: string;
+        execution_count?: number | null;
+        outputs?: unknown[];
+    }>;
+    /**
+     * Get the total number of cells in the notebook.
+     *
+     * @returns The number of cells, or 0 if the notebook model is not available
+     */
+    getCellCount(): number;
+    /**
+     * Insert a new cell at a specific index.
+     *
+     * @param cellIndex - The index where the cell should be inserted (0-based)
+     * @param source - Optional source code/text for the new cell
+     *
+     * @remarks
+     * This method inserts a cell at the specified position by:
+     * 1. Setting the active cell to cellIndex
+     * 2. Calling insertAbove to insert before that cell
+     *
+     * Note: The cell type is determined by _defaultCellType, which should be set
+     * before calling this method (typically done by the store layer).
+     */
+    insertAt(cellIndex: number, source?: string): void;
+    /**
+     * NEW ALIGNED TOOL METHODS
+     * These methods align 1:1 with tool operation names for seamless integration
+     */
+    /**
+     * Insert a cell at a specific index (aligned with insertCell tool).
+     *
+     * @param cellType - Type of cell to insert (code, markdown, or raw)
+     * @param cellIndex - Index where to insert (0-based). If undefined, inserts at end.
+     * @param source - Optional source code/text for the cell
+     */
+    insertCell(cellType: nbformat.CellType, cellIndex?: number, source?: string): void;
+    /**
+     * Insert multiple cells at a specific index (aligned with insertCells tool).
+     *
+     * More efficient than calling insertCell multiple times.
+     * Cells are inserted sequentially starting at the given index.
+     *
+     * @param cells - Array of cells to insert (each with type and source)
+     * @param cellIndex - Index where to insert first cell (0-based). Use large number for end.
+     */
+    insertCells(cells: Array<{
+        type: nbformat.CellType;
+        source: string;
+    }>, cellIndex: number): void;
+    /**
+     * Delete cell(s) at the specified index/indices (aligned with deleteCell tool and Jupyter MCP Server).
+     *
+     * @param index - Single cell index, array of indices, or undefined.
+     *   - Single number: Deletes that cell
+     *   - Array: Deletes all cells at those indices (in reverse order to prevent shifting)
+     *   - Undefined: Deletes the active cell if one exists
+     *
+     * @remarks
+     * This method matches the Jupyter MCP Server behavior:
+     * - Validates ALL indices are in range before deleting any
+     * - Deletes in reverse order (highest to lowest) to prevent index shifting
+     * - Throws error with MCP-compatible message format if any index is out of range
+     *
+     * @throws {Error} If any index is out of range
+     */
+    deleteCell(index?: number | number[]): void;
+    /**
+     * Updates cell source at the specified index and returns a diff.
+     * Matches MCP server's overwrite_cell_source behavior.
+     *
+     * @param index - Cell index (0-based)
+     * @param source - New cell source content
+     * @returns Diff string showing changes made
+     * @throws Error if cell index is out of range or cell not found
+     */
+    updateCell(index: number, source: string): string;
+    /**
+     * Get a cell's content by index or active cell (aligned with getCell tool and MCP Server).
+     *
+     * @param index - Optional cell index (0-based). If not provided, returns active cell.
+     * @param includeOutputs - Whether to include cell outputs (default: true)
+     * @returns Cell data or undefined if not found
+     */
+    getCell(index?: number, includeOutputs?: boolean): {
+        type: nbformat.CellType;
+        source: string;
+        execution_count?: number | null;
+        outputs?: unknown[];
+    } | undefined;
+    /**
+     * Run a cell and optionally capture outputs (aligned with runCell tool).
+     *
+     * @param params - Parameters for cell execution
+     * @param params.index - Cell index to run (optional, defaults to active cell)
+     * @param params.timeoutSeconds - Timeout in seconds (optional, for future use)
+     * @param params.stream - Enable streaming progress (optional, for future use)
+     * @param params.progressInterval - Progress update interval (optional, for future use)
+     * @returns Promise resolving to execution result with outputs
+     */
+    runCell(params?: {
+        index?: number;
+        timeoutSeconds?: number;
+        stream?: boolean;
+        progressInterval?: number;
+    }): Promise<{
+        execution_count?: number | null;
+        outputs?: Array<string>;
+    }>;
+    /**
+     * Run all cells in the notebook (aligned with runAllCells tool).
+     */
+    runAllCells(): void;
+    /**
+     * Clear all outputs from all cells in the notebook.
+     *
+     * @remarks
+     * Removes all execution outputs from all cells. This operation:
+     * - Clears outputs but preserves cell source code
+     * - Resets execution counts
+     * - Cannot be undone
+     */
+    clearAllOutputs(): void;
+    /**
+     * Execute code directly in the kernel without creating a cell.
+     *
+     * This method sends code execution requests directly to the kernel,
+     * bypassing the notebook cell model. Useful for:
+     * - Variable inspection
+     * - Environment setup
+     * - Background tasks
+     * - Tool introspection
+     *
+     * @param code - Code to execute
+     * @param options - Execution options
+     * @returns Promise with execution result including outputs
+     */
+    executeCode(code: string, options?: {
+        timeout?: number;
+    }): Promise<{
+        success: boolean;
+        outputs?: Array<{
+            type: 'stream' | 'execute_result' | 'display_data' | 'error';
+            content: unknown;
+        }>;
+        executionCount?: number;
+        error?: string;
+    }>;
+    /**
+     * Dispose of the adapter.
+     */
+    dispose(): void;
 }
 export default NotebookAdapter;