@datalayer/jupyter-react 1.1.7 → 1.1.9

package/lib/tools/core/executor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Tool executor interface and implementations.
+ * Provides platform-agnostic execution abstraction.
+ *
+ * @module tools/core/executor
+ */
+import type { Notebook2State } from '../../components/notebook/Notebook2State';
+/**
+ * Tool executor interface - abstracts how operations are executed.
+ * Platforms can implement this interface to provide custom execution logic.
+ */
+export interface ToolExecutor {
+    /**
+     * Execute a tool operation
+     *
+     * @param operationName - Name of the operation (e.g., "insertCell", "runCell")
+     * @param args - Operation arguments
+     * @returns Result from execution
+     */
+    execute(operationName: string, args: unknown): Promise<unknown>;
+}
+/**
+ * Default executor - directly calls Notebook2State store methods.
+ * Calls methods with individual parameters by spreading the payload object.
+ *
+ * @example
+ * ```typescript
+ * const executor = new DefaultExecutor(documentId, notebookStore);
+ * await executor.execute("insertCell", { type: "code", index: 0, source: "print('hi')" });
+ * // Calls: store.insertCell(documentId, "code", 0, "print('hi')")
+ * ```
+ */
+export declare class DefaultExecutor implements ToolExecutor {
+    private documentId;
+    private store;
+    constructor(documentId: string, store: Notebook2State);
+    /**
+     * Execute an operation by calling the corresponding Notebook2State method.
+     * Builds payload with documentId and spreads values as individual parameters.
+     *
+     * @param operationName - Name of the operation (e.g., "insertCell", "deleteCell")
+     * @param args - Operation arguments as an object
+     * @returns Result from store method
+     */
+    execute(operationName: string, args: unknown): Promise<unknown>;
+}

package/lib/tools/core/executor.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Default executor - directly calls Notebook2State store methods.
+ * Calls methods with individual parameters by spreading the payload object.
+ *
+ * @example
+ * ```typescript
+ * const executor = new DefaultExecutor(documentId, notebookStore);
+ * await executor.execute("insertCell", { type: "code", index: 0, source: "print('hi')" });
+ * // Calls: store.insertCell(documentId, "code", 0, "print('hi')")
+ * ```
+ */
+export class DefaultExecutor {
+    documentId;
+    store;
+    constructor(documentId, store) {
+        this.documentId = documentId;
+        this.store = store;
+    }
+    /**
+     * Execute an operation by calling the corresponding Notebook2State method.
+     * Builds payload with documentId and spreads values as individual parameters.
+     *
+     * @param operationName - Name of the operation (e.g., "insertCell", "deleteCell")
+     * @param args - Operation arguments as an object
+     * @returns Result from store method
+     */
+    async execute(operationName, args) {
+        console.log(`[DefaultExecutor] Executing: ${operationName} for document: ${this.documentId}`);
+        console.log(`[DefaultExecutor] Args:`, args);
+        // Get the store method directly (1:1 mapping, no transformation)
+        const method = this.store[operationName];
+        if (typeof method !== 'function') {
+            console.error(`[DefaultExecutor] Method '${operationName}' not found in store!`);
+            console.error(`[DefaultExecutor] Available methods:`, Object.keys(this.store).filter(k => typeof this.store[k] === 'function'));
+            throw new Error(`Store method '${operationName}' not found or not a function`);
+        }
+        // Build payload: { id, ...args } - pass as single object parameter
+        const payload = typeof args === 'object' && args !== null
+            ? { id: this.documentId, ...args }
+            : { id: this.documentId };
+        console.log(`[DefaultExecutor] Calling method with payload:`, payload);
+        // Call method with payload object as first parameter
+        // Methods will check if first param is object and destructure accordingly
+        const methodFn = method;
+        const result = await methodFn.call(this.store, payload);
+        console.log(`[DefaultExecutor] Result:`, result);
+        return result;
+    }
+}
+//# sourceMappingURL=executor.js.map

package/lib/tools/core/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/tools/core/executor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAe;IAEhB;IACA;IAFV,YACU,UAAkB,EAClB,KAAqB;QADrB,eAAU,GAAV,UAAU,CAAQ;QAClB,UAAK,GAAL,KAAK,CAAgB;IAC5B,CAAC;IAEJ;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,aAAqB,EAAE,IAAa;QAChD,OAAO,CAAC,GAAG,CACT,gCAAgC,aAAa,kBAAkB,IAAI,CAAC,UAAU,EAAE,CACjF,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,CAAC;QAE7C,iEAAiE;QACjE,MAAM,MAAM,GAAI,IAAI,CAAC,KAA4C,CAC/D,aAAa,CACd,CAAC;QAEF,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CACX,6BAA6B,aAAa,uBAAuB,CAClE,CAAC;YACF,OAAO,CAAC,KAAK,CACX,sCAAsC,EACtC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAC5B,CAAC,CAAC,EAAE,CAAC,OAAQ,IAAI,CAAC,KAAa,CAAC,CAAC,CAAC,KAAK,UAAU,CAClD,CACF,CAAC;YACF,MAAM,IAAI,KAAK,CACb,iBAAiB,aAAa,+BAA+B,CAC9D,CAAC;QACJ,CAAC;QAED,mEAAmE;QACnE,MAAM,OAAO,GACX,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YACvC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,EAAE;YAClC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;QAE9B,OAAO,CAAC,GAAG,CAAC,gDAAgD,EAAE,OAAO,CAAC,CAAC;QAEvE,qDAAqD;QACrD,0EAA0E;QAC1E,MAAM,QAAQ,GAAG,MAAuC,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAExD,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/lib/tools/core/formatter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Format tool response based on requested format.
+ *
+ * @template T - Type of the data being formatted
+ * @param data - Tool result to format
+ * @param format - Desired output format ("toon" default, or "json")
+ * @returns Formatted response (string for TOON, object for JSON)
+ *
+ * @example
+ * ```typescript
+ * // TOON format (default) - returns human-readable string
+ * const toonResult = formatResponse({ success: true, cells: [...] });
+ * // Returns: "success: true\ncells:\n  - type: code\n    source: print('hello')\n..."
+ *
+ * // JSON format - returns structured object
+ * const jsonResult = formatResponse({ success: true, cells: [...] }, "json");
+ * // Returns: { success: true, cells: [...] }
+ * ```
+ */
+export declare function formatResponse<T>(data: T, format?: 'json' | 'toon'): T | string;

package/lib/tools/core/formatter.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Response formatting utilities for tool operations.
+ * Supports JSON (default, structured) and TOON (human/LLM-readable).
+ *
+ * @module tools/core/formatter
+ */
+import { encode } from '@toon-format/toon';
+/**
+ * Format tool response based on requested format.
+ *
+ * @template T - Type of the data being formatted
+ * @param data - Tool result to format
+ * @param format - Desired output format ("toon" default, or "json")
+ * @returns Formatted response (string for TOON, object for JSON)
+ *
+ * @example
+ * ```typescript
+ * // TOON format (default) - returns human-readable string
+ * const toonResult = formatResponse({ success: true, cells: [...] });
+ * // Returns: "success: true\ncells:\n  - type: code\n    source: print('hello')\n..."
+ *
+ * // JSON format - returns structured object
+ * const jsonResult = formatResponse({ success: true, cells: [...] }, "json");
+ * // Returns: { success: true, cells: [...] }
+ * ```
+ */
+export function formatResponse(data, format) {
+    // Return JSON (structured object) if explicitly requested
+    if (format === 'json') {
+        return data;
+    }
+    // Default to TOON format - encode as human/LLM-readable string
+    // This is the default because most tool operations are called by LLMs
+    return encode(data);
+}
+//# sourceMappingURL=formatter.js.map

package/lib/tools/core/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../../src/tools/core/formatter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAO,EACP,MAAwB;IAExB,0DAA0D;IAC1D,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+DAA+D;IAC/D,sEAAsE;IACtE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC"}

package/lib/tools/core/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Core tool operations, interfaces, and utilities.
+ *
+ * @module tools/core
+ */
+export * from '../operations/insertCell';
+export * from '../operations/deleteCell';
+export * from '../operations/updateCell';
+export * from '../operations/readCell';
+export * from '../operations/readAllCells';
+export * from '../operations/runCell';
+export * from '../operations/executeCode';
+export * from './interfaces';
+export * from './formatter';
+export * from './executor';
+export * from './operationRunner';
+export * from './schema';
+export * from './types';

package/lib/tools/core/index.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Core tool operations, interfaces, and utilities.
+ *
+ * @module tools/core
+ */
+export * from '../operations/insertCell';
+export * from '../operations/deleteCell';
+export * from '../operations/updateCell';
+export * from '../operations/readCell';
+export * from '../operations/readAllCells';
+export * from '../operations/runCell';
+export * from '../operations/executeCode';
+export * from './interfaces';
+export * from './formatter';
+export * from './executor';
+export * from './operationRunner';
+export * from './schema';
+export * from './types';
+//# sourceMappingURL=index.js.map

package/lib/tools/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAE1C,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/lib/tools/core/interfaces.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Core interfaces for platform-agnostic tool operations.
+ *
+ * @module tools/core/interfaces
+ */
+import type { ToolExecutor } from './executor';
+/**
+ * Execution context for tool operations.
+ */
+export interface ToolExecutionContext {
+    /** Tool executor (DefaultExecutor, BridgeExecutor, etc.) */
+    executor: ToolExecutor;
+    /** Document identifier - universal for notebooks, lexicals, etc. (file URI or document UID) */
+    documentId?: string;
+    /** Response format: "json" (default) or "toon" */
+    format?: 'json' | 'toon';
+    /** Platform-specific additional context */
+    extras?: Record<string, unknown>;
+}
+/**
+ * Platform-agnostic tool operation interface.
+ *
+ * @template TParams - Tool parameter type
+ * @template TResult - Tool result type
+ */
+export interface ToolOperation<TParams, TResult> {
+    /** Operation name (matches ToolDefinition.operation field) */
+    name: string;
+    /**
+     * Execute the operation.
+     *
+     * @param params - Tool parameters
+     * @param context - Execution context
+     * @returns Operation result
+     */
+    execute(params: TParams, context: ToolExecutionContext): Promise<TResult>;
+}
+export type { ToolExecutor };

package/lib/tools/core/interfaces.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+export {};
+//# sourceMappingURL=interfaces.js.map

package/lib/tools/core/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../src/tools/core/interfaces.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/lib/tools/core/operationRunner.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Operation runner that executes operations and applies formatting.
+ *
+ * @module tools/core/operationRunner
+ */
+import type { ToolOperation, ToolExecutionContext } from './interfaces';
+/**
+ * Executes tool operations and applies formatting to results.
+ *
+ * Operations return pure typed data. The runner applies formatting
+ * based on context.format:
+ * - 'json' → Returns structured object (TResult)
+ * - 'toon' → Returns TOON-encoded string
+ */
+export declare class OperationRunner {
+    /**
+     * Execute an operation and format its result.
+     *
+     * @template TParams - Operation parameter type
+     * @template TResult - Operation result type
+     * @param operation - Tool operation to execute
+     * @param params - Operation parameters
+     * @param context - Execution context
+     * @returns Formatted result (object or string based on context.format)
+     */
+    execute<TParams, TResult>(operation: ToolOperation<TParams, TResult>, params: TParams, context: ToolExecutionContext): Promise<TResult | string>;
+}

package/lib/tools/core/operationRunner.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+import { formatResponse } from './formatter';
+/**
+ * Executes tool operations and applies formatting to results.
+ *
+ * Operations return pure typed data. The runner applies formatting
+ * based on context.format:
+ * - 'json' → Returns structured object (TResult)
+ * - 'toon' → Returns TOON-encoded string
+ */
+export class OperationRunner {
+    /**
+     * Execute an operation and format its result.
+     *
+     * @template TParams - Operation parameter type
+     * @template TResult - Operation result type
+     * @param operation - Tool operation to execute
+     * @param params - Operation parameters
+     * @param context - Execution context
+     * @returns Formatted result (object or string based on context.format)
+     */
+    async execute(operation, params, context) {
+        // Execute operation (returns pure typed data)
+        const result = await operation.execute(params, context);
+        // Apply formatting based on context.format
+        return formatResponse(result, context.format);
+    }
+}
+//# sourceMappingURL=operationRunner.js.map

package/lib/tools/core/operationRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operationRunner.js","sourceRoot":"","sources":["../../../src/tools/core/operationRunner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,OAAO,eAAe;IAC1B;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,CACX,SAA0C,EAC1C,MAAe,EACf,OAA6B;QAE7B,8CAA8C;QAC9C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAExD,2CAA2C;QAC3C,OAAO,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;CACF"}

package/lib/tools/core/schema.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Platform-agnostic tool configuration and definition schemas.
+ *
+ * @module tools/core/schema
+ */
+/**
+ * Tool configuration interface.
+ */
+export interface ToolConfig<TParams = unknown> {
+    /** Confirmation message from parameters */
+    confirmationMessage?: (params: TParams) => string;
+    /** Invocation message from parameters */
+    invocationMessage?: (params: TParams) => string;
+    /** Require user confirmation */
+    requiresConfirmation?: boolean;
+    /** Can be referenced in prompts */
+    canBeReferencedInPrompt?: boolean;
+    /** Priority for suggestion ranking */
+    priority?: 'low' | 'medium' | 'high';
+    /** Platform-specific config extensions */
+    [key: string]: unknown;
+}
+/**
+ * Tool definition interface.
+ */
+export interface ToolDefinition<TParams = unknown> {
+    /** Vendor-prefixed tool name (e.g., "datalayer_insertCell") */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** User-facing reference name (e.g., "insertCell") */
+    toolReferenceName: string;
+    /** Tool description */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    /** Operation handler name */
+    operation: string;
+    /** Tool configuration */
+    config?: ToolConfig<TParams>;
+    /** Categorization tags */
+    tags?: string[];
+}

package/lib/tools/core/schema.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+export {};
+//# sourceMappingURL=schema.js.map

package/lib/tools/core/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/core/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/lib/tools/core/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for notebook tool operations.
+ *
+ * @module tools/core/types
+ */
+/**
+ * Cell format for controlling response detail level
+ */
+export type CellFormat = 'brief' | 'detailed';
+/**
+ * Brief cell representation for structure queries
+ * Includes index, type, and a 40-char content preview
+ */
+export interface BriefCell {
+    /** Cell index in notebook */
+    index: number;
+    /** Cell type (code, markdown, raw) */
+    type: string;
+    /** 40-character preview of cell source */
+    preview: string;
+}
+/**
+ * Detailed cell representation with full content
+ */
+export interface DetailedCell {
+    /** Cell index in notebook */
+    index: number;
+    /** Cell type (code, markdown, raw) */
+    type: string;
+    /** Full cell source code */
+    source: string;
+    /** Execution count for code cells */
+    execution_count?: number | null;
+    /** Cell outputs (for code cells) */
+    outputs?: string[];
+}

package/lib/tools/core/types.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/tools/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tools/core/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/lib/tools/core/zodUtils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Zod utility functions for tool parameter validation
+ *
+ * @module tools/core/zodUtils
+ */
+import { z } from 'zod';
+import type { ToolDefinition } from './schema';
+/**
+ * Converts a Zod schema to ToolDefinition parameters (JSON Schema format).
+ *
+ * This enables a single source of truth: define the schema once with Zod,
+ * and automatically generate the JSON Schema for LLM tool calling.
+ *
+ * @param schema - Zod schema defining the tool's input parameters
+ * @returns JSON Schema object compatible with ToolDefinition.parameters
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   index: z.number().int().describe('Cell index'),
+ *   source: z.string().describe('Cell content')
+ * });
+ *
+ * const parameters = zodToToolParameters(schema);
+ * // Returns: { type: 'object', properties: {...}, required: [...] }
+ * ```
+ */
+export declare function zodToToolParameters(schema: any): ToolDefinition['parameters'];
+/**
+ * Validates parameters using a Zod schema with user-friendly error messages.
+ *
+ * This replaces manual type guard functions with automatic runtime validation.
+ * On validation failure, throws a descriptive error that helps both developers
+ * and LLMs understand what went wrong.
+ *
+ * @param schema - Zod schema to validate against
+ * @param params - Unknown parameters to validate
+ * @param operationName - Name of the operation (for error messages)
+ * @returns Validated parameters with proper TypeScript type
+ * @throws Error with detailed validation failure information
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ index: z.number().int() });
+ *
+ * // Valid params
+ * const validated = validateWithZod(schema, { index: 5 }, 'readCell');
+ * // Returns: { index: 5 } with type { index: number }
+ *
+ * // Invalid params
+ * validateWithZod(schema, { index: 'invalid' }, 'readCell');
+ * // Throws: Error: Invalid parameters for readCell:
+ * //   - index: Expected number, received string
+ * ```
+ */
+export declare function validateWithZod<T>(schema: z.ZodType<T>, params: unknown, operationName: string): T;