@datalayer/agent-runtimes 1.0.10 → 1.0.18

package/lib/models/LexicalDTO.d.ts

@@ -0,0 +1,155 @@
+import type { AgentRuntimesClient as DatalayerClient } from '../client/AgentRuntimesClient';
+import { ItemDTO } from './ItemDTO';
+/**
+ * Represents a Lexical document (rich text editor)
+ * @interface Lexical
+ */
+export interface LexicalData {
+    id: string;
+    uid: string;
+    name?: string;
+    name_t?: string;
+    content?: any;
+    space_id?: string;
+    owner_id?: string;
+    creator_uid?: string;
+    creator_handle_s?: string;
+    created_at?: string;
+    creation_ts_dt?: string;
+    updated_at?: string;
+    last_update_ts_dt?: string;
+    cdn_url_s: string;
+    type_s?: string;
+    public_b?: boolean;
+    description_t?: string;
+    document_name_s?: string;
+    document_extension_s: string;
+    document_format_s?: string;
+    content_length_i?: number;
+    content_type_s?: string;
+    mime_type_s?: string;
+    s3_path_s?: string;
+    s3_url_s?: string;
+    model_s?: string;
+}
+/**
+ * Request payload for creating a Lexical document
+ * @interface CreateLexicalRequest
+ */
+export interface CreateLexicalRequest {
+    spaceId: string;
+    documentType: string;
+    name: string;
+    description: string;
+    file?: File | Blob;
+}
+/**
+ * Response from creating a Lexical document
+ * @interface CreateLexicalResponse
+ */
+export interface CreateLexicalResponse {
+    success: boolean;
+    message: string;
+    document?: LexicalData;
+}
+/**
+ * Response from getting a Lexical document
+ * @interface GetLexicalResponse
+ */
+export interface GetLexicalResponse {
+    success: boolean;
+    message: string;
+    document?: LexicalData;
+}
+/**
+ * Request payload for updating a Lexical document
+ * @interface UpdateLexicalRequest
+ */
+export interface UpdateLexicalRequest {
+    name?: string;
+    description?: string;
+}
+/**
+ * Response from updating a Lexical document
+ * @interface UpdateLexicalResponse
+ */
+export interface UpdateLexicalResponse {
+    success: boolean;
+    message: string;
+    document: LexicalData;
+}
+/**
+ * Stable public interface for Lexical data.
+ * This is the contract that Client consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface LexicalJSON {
+    /** Unique identifier for the lexical document */
+    uid: string;
+    /** Unique identifier for the lexical document */
+    id: string;
+    /** Name of the lexical document */
+    name: string;
+    /** Description of the lexical document */
+    description: string;
+    /** Type of lexical document */
+    type: string;
+    /** File extension of the lexical document */
+    extension: string;
+    /** ISO 8601 timestamp when the document was created */
+    createdAt: string;
+    /** ISO 8601 timestamp when the document was last updated */
+    updatedAt: string;
+    /** CDN URL for accessing the document */
+    cdnUrl: string;
+}
+/**
+ * Lexical domain model that extends the base Item class.
+ * Provides lexical document functionality for managing rich text documents.
+ *
+ * @example
+ * ```typescript
+ * const lexical = await client.createLexical(formData);
+ * await lexical.update({ name: 'Updated Documentation' });
+ * ```
+ */
+export declare class LexicalDTO extends ItemDTO<LexicalData> {
+    /**
+     * Create a Lexical instance.
+     *
+     * @param data - Lexical data from API
+     * @param client - Client instance
+     */
+    constructor(data: LexicalData, client: DatalayerClient);
+    /** Document type identifier. */
+    get type(): string;
+    /** The cached name of the document. */
+    get name(): string;
+    /** Get the current name of the document from API. */
+    getName(): Promise<string>;
+    /** The cached content. */
+    get content(): any;
+    /** Description of the lexical document. */
+    get description(): string;
+    /** Get the document extension. */
+    get extension(): string;
+    /** Get when the document was last updated from API. */
+    getUpdatedAt(): Promise<Date>;
+    /** Update the document. */
+    update(name?: string, description?: string): Promise<this>;
+    /**
+     * Get lexical document data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core lexical data with camelCase properties
+     */
+    toJSON(): LexicalJSON;
+    /**
+     * Get the raw lexical data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw lexical data from API
+     */
+    rawData(): LexicalData;
+}

package/lib/models/LexicalDTO.js

@@ -0,0 +1,157 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Lexical domain model for the Datalayer Client.
+ *
+ * @module models/LexicalDTO
+ */
+import * as lexicals from '../api/spacer/lexicals';
+import { ItemTypes } from '@datalayer/core/lib/client';
+import { ItemDTO } from './ItemDTO';
+import { validateJSON } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Lexical domain model that extends the base Item class.
+ * Provides lexical document functionality for managing rich text documents.
+ *
+ * @example
+ * ```typescript
+ * const lexical = await client.createLexical(formData);
+ * await lexical.update({ name: 'Updated Documentation' });
+ * ```
+ */
+export class LexicalDTO extends ItemDTO {
+    /**
+     * Create a Lexical instance.
+     *
+     * @param data - Lexical data from API
+     * @param client - Client instance
+     */
+    constructor(data, client) {
+        super(data, client);
+    }
+    // ========================================================================
+    // Abstract Method Implementations
+    // ========================================================================
+    /** Document type identifier. */
+    get type() {
+        this._checkDeleted();
+        return ItemTypes.LEXICAL;
+    }
+    /** The cached name of the document. */
+    get name() {
+        this._checkDeleted();
+        return this._data.name_t || this._data.name || '';
+    }
+    /** Get the current name of the document from API. */
+    async getName() {
+        this._checkDeleted();
+        const token = this._getToken();
+        const spacerUrl = this._getSpacerUrl();
+        const response = await lexicals.getLexical(token, this.uid, spacerUrl);
+        if (response.document) {
+            this._updateData(response.document);
+            return response.document.name_t || response.document.name || '';
+        }
+        return this.name;
+    }
+    /** The cached content. */
+    get content() {
+        this._checkDeleted();
+        if (!this._data.content && this._data.model_s) {
+            try {
+                return JSON.parse(this._data.model_s);
+            }
+            catch {
+                return this._data.model_s;
+            }
+        }
+        return this._data.content;
+    }
+    /** Description of the lexical document. */
+    get description() {
+        this._checkDeleted();
+        return this._data.description_t || '';
+    }
+    /** Get the document extension. */
+    get extension() {
+        this._checkDeleted();
+        const ext = this._data.document_extension_s;
+        return ext ? (ext.startsWith('.') ? ext : `.${ext}`) : '.lexical';
+    }
+    /** Get when the document was last updated from API. */
+    async getUpdatedAt() {
+        this._checkDeleted();
+        const token = this._getToken();
+        const spacerUrl = this._getSpacerUrl();
+        const response = await lexicals.getLexical(token, this.uid, spacerUrl);
+        if (response.document) {
+            this._updateData(response.document);
+            const dateStr = response.document.last_update_ts_dt ||
+                response.document.updated_at ||
+                response.document.creation_ts_dt ||
+                response.document.created_at;
+            if (!dateStr) {
+                throw new Error('No timestamp available for lexical document');
+            }
+            return new Date(dateStr);
+        }
+        const dateStr = this._data.last_update_ts_dt ||
+            this._data.updated_at ||
+            this._data.creation_ts_dt ||
+            this._data.created_at;
+        if (!dateStr) {
+            throw new Error('No timestamp available for lexical document');
+        }
+        return new Date(dateStr);
+    }
+    /** Update the document. */
+    async update(name, description) {
+        // FIXME: check if both are needed, and use the existing values if only one provided
+        this._checkDeleted();
+        const token = this._getToken();
+        const spacerUrl = this._getSpacerUrl();
+        const updateData = {};
+        if (name !== undefined)
+            updateData.name = name;
+        if (description !== undefined)
+            updateData.description = description;
+        const response = await lexicals.updateLexical(token, this.uid, updateData, spacerUrl);
+        this._updateData(response.document);
+        return this;
+    }
+    /**
+     * Get lexical document data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core lexical data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        const obj = {
+            uid: this.uid,
+            id: this.id,
+            name: this.name,
+            description: this.description,
+            type: this.type,
+            extension: this.extension,
+            createdAt: this.createdAt.toDateString(),
+            updatedAt: this.updatedAt.toDateString(),
+            cdnUrl: this._data.cdn_url_s,
+        };
+        validateJSON(obj, 'Lexical');
+        return obj;
+    }
+    /**
+     * Get the raw lexical data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw lexical data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+}

package/lib/models/Library.d.ts

@@ -0,0 +1,10 @@
+import { IExercise } from './Exercise';
+import { IDataset } from './Dataset';
+export type LibraryType = 'public' | 'private';
+export type Library = {
+    id: string;
+    type: LibraryType;
+    exercises: Array<IExercise>;
+    datasets: Array<IDataset>;
+};
+export default Library;

package/lib/models/Library.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/models/Notebook.d.ts

@@ -0,0 +1,11 @@
+import { INotebookContent } from '@jupyterlab/nbformat';
+import { IItem } from './Item';
+import { IDataset } from './Dataset';
+export type IBaseNotebook = IItem & {
+    nbformat?: INotebookContent;
+    datasets: Array<IDataset>;
+};
+export type INotebook = IBaseNotebook & {
+    type: 'notebook';
+};
+export default INotebook;

package/lib/models/Notebook.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/models/NotebookDTO.d.ts

@@ -0,0 +1,96 @@
+import type { AgentRuntimesClient as DatalayerClient } from '../client/AgentRuntimesClient';
+import { ItemDTO } from './ItemDTO';
+/**
+ * Represents a Jupyter notebook document
+ * @interface NotebookData
+ */
+export interface NotebookData {
+    id: string;
+    uid: string;
+    name_t: string;
+    description_t: string;
+    type_s: string;
+    notebook_extension_s: string;
+    s3_path_s: string;
+    s3_url_s: string;
+    cdn_url_s: string;
+}
+/**
+ * Stable public interface for Notebook data.
+ * This is the contract that Client consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface NotebookJSON {
+    /** uuid of the notebook */
+    id: string;
+    /** ulid for of the notebook */
+    uid: string;
+    /** Name of the notebook */
+    name: string;
+    /** Description of the notebook */
+    description: string;
+    /** Type of notebook */
+    type: string;
+    /** File extension of the notebook */
+    extension: string;
+    /** CDN URL for accessing the notebook */
+    cdnUrl: string;
+}
+/**
+ * Notebook domain model that extends the base Item class.
+ * Provides notebook-specific functionality for managing Jupyter notebooks.
+ *
+ * @example
+ * ```typescript
+ * const notebook = await client.createNotebook(formData);
+ * const kernelSpec = await notebook.getKernelSpec();
+ * ```
+ */
+export declare class NotebookDTO extends ItemDTO<NotebookData> {
+    /**
+     * Create a Notebook instance.
+     *
+     * @param data - Notebook data from API
+     * @param client - Client instance
+     */
+    constructor(data: NotebookData, client: DatalayerClient);
+    /** Document type identifier. */
+    get type(): string;
+    /** The cached name of the notebook. */
+    get name(): string;
+    /** The cached content. */
+    get content(): any;
+    /** Get the current name from API. */
+    getName(): Promise<string>;
+    /** Get when the notebook was last updated from API. */
+    getUpdatedAt(): Promise<Date>;
+    /** Update the notebook. */
+    update(name?: string, description?: string): Promise<this>;
+    /** File path within the space. */
+    get path(): string;
+    /** Version number. */
+    get version(): number;
+    /** Notebook metadata. */
+    get metadata(): Record<string, any>;
+    /** Kernel specification (cached). */
+    get kernelSpec(): any;
+    /** Description of the notebook. */
+    get description(): string;
+    /** Get the notebook extension. */
+    get extension(): string;
+    /**
+     * Get notebook data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core notebook data with camelCase properties
+     */
+    toJSON(): NotebookJSON;
+    /**
+     * Get the raw notebook data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw notebook data from API
+     */
+    rawData(): NotebookData;
+}

package/lib/models/NotebookDTO.js

@@ -0,0 +1,153 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import * as notebooks from '../api/spacer/notebooks';
+import { ItemDTO } from './ItemDTO';
+import { ItemTypes } from '@datalayer/core/lib/client/constants';
+import { validateJSON } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Notebook domain model that extends the base Item class.
+ * Provides notebook-specific functionality for managing Jupyter notebooks.
+ *
+ * @example
+ * ```typescript
+ * const notebook = await client.createNotebook(formData);
+ * const kernelSpec = await notebook.getKernelSpec();
+ * ```
+ */
+export class NotebookDTO extends ItemDTO {
+    /**
+     * Create a Notebook instance.
+     *
+     * @param data - Notebook data from API
+     * @param client - Client instance
+     */
+    constructor(data, client) {
+        super(data, client);
+    }
+    // ========================================================================
+    // Abstract Method Implementations
+    // ========================================================================
+    /** Document type identifier. */
+    get type() {
+        this._checkDeleted();
+        return ItemTypes.NOTEBOOK;
+    }
+    /** The cached name of the notebook. */
+    get name() {
+        this._checkDeleted();
+        return (this._data.name_t ||
+            this._data.notebook_name_s ||
+            this._data.name ||
+            '');
+    }
+    /** The cached content. */
+    get content() {
+        this._checkDeleted();
+        if (!this._data.content && this._data.model_s) {
+            try {
+                return JSON.parse(this._data.model_s);
+            }
+            catch {
+                return this._data.model_s;
+            }
+        }
+        return this._data.content;
+    }
+    /** Get the current name from API. */
+    async getName() {
+        this._checkDeleted();
+        // For now, return cached value - implement API call if needed
+        return this.name;
+    }
+    /** Get when the notebook was last updated from API. */
+    async getUpdatedAt() {
+        this._checkDeleted();
+        const dateStr = this._data.updated_at || this._data.update_ts_dt;
+        if (!dateStr) {
+            throw new Error('No update timestamp available for notebook');
+        }
+        return new Date(dateStr);
+    }
+    /** Update the notebook. */
+    async update(name, description) {
+        // FIXME: check if both are needed, and use the existing values if only one provided
+        this._checkDeleted();
+        const token = this._client.getToken();
+        const spacerUrl = this._client.getSpacerUrl();
+        const updateData = {};
+        if (name !== undefined)
+            updateData.name = name;
+        if (description !== undefined)
+            updateData.description = description;
+        await notebooks.updateNotebook(token, this.uid, updateData, spacerUrl);
+        // FIXME: handle partial updates
+        return this;
+    }
+    // ========================================================================
+    // Notebook-specific Properties
+    // ========================================================================
+    /** File path within the space. */
+    get path() {
+        this._checkDeleted();
+        return this._data.path || '';
+    }
+    /** Version number. */
+    get version() {
+        this._checkDeleted();
+        return this._data.version || 0;
+    }
+    /** Notebook metadata. */
+    get metadata() {
+        this._checkDeleted();
+        return this._data.metadata || {};
+    }
+    /** Kernel specification (cached). */
+    get kernelSpec() {
+        this._checkDeleted();
+        return this._data.kernel_spec;
+    }
+    /** Description of the notebook. */
+    get description() {
+        this._checkDeleted();
+        return this._data.description_t || '';
+    }
+    /** Get the notebook extension. */
+    get extension() {
+        this._checkDeleted();
+        const ext = this._data.notebook_extension_s;
+        return ext ? (ext.startsWith('.') ? ext : `.${ext}`) : '.ipynb';
+    }
+    /**
+     * Get notebook data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core notebook data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        const obj = {
+            id: this.id,
+            uid: this.uid,
+            name: this.name,
+            description: this.description,
+            type: this.type,
+            extension: this.extension,
+            cdnUrl: this._data.cdn_url_s,
+        };
+        validateJSON(obj, 'Notebook');
+        return obj;
+    }
+    /**
+     * Get the raw notebook data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw notebook data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+}

package/lib/models/Page.d.ts

@@ -0,0 +1,41 @@
+import { INotebookContent } from '@jupyterlab/nbformat';
+import { IUser } from '@datalayer/core/lib/models/User';
+import { PageTagName } from './PageTag';
+import { ICodeSandboxSnapshot } from './CodeSandboxSnapshot';
+export type PageTheme = 'default';
+export type PageVariant = 'document' | 'cell' | 'notebook';
+/**
+ * Page attributes.
+ *
+ * - Notebook
+ * - Screen Capture
+ * - Theme
+ * - Tags
+ * - Video Explainer
+ * - Kernel Launcher Button
+ * - Kernel Snapshot
+ * - Share Button
+ * - Stars Counter - 1 ⭐ -> 1 Credit
+ */
+export type IPage = {
+    id: string;
+    variant: PageVariant;
+    type: 'page';
+    name: string;
+    description: string;
+    theme: PageTheme;
+    tags: Array<PageTagName>;
+    nbformat: INotebookContent;
+    screenCapture?: string;
+    creator?: IUser;
+    creatorId?: string;
+    selectedPrincipalUid?: string;
+    selectedPrincipalKind?: 'personal' | 'organization' | 'team';
+    selectedOrganizationUid?: string;
+    kernelSnapshot?: ICodeSandboxSnapshot;
+    kernelSnapshotId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+};
+export declare const asPage: (s: any) => IPage;
+export default IPage;

package/lib/models/Page.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { asUser } from '@datalayer/core/lib/models/User';
+import { asCodeSandboxSnapshot, } from './CodeSandboxSnapshot';
+export const asPage = (s) => {
+    return {
+        id: s.uid,
+        type: 'page',
+        variant: s.variant_s,
+        name: s.name_t,
+        description: s.description_t,
+        theme: s.theme_s,
+        nbformat: s.nbformat_s ? JSON.parse(s.nbformat_s) : undefined,
+        screenCapture: s.screen_capture_cdn_url_s || s.screen_capture_s,
+        tags: s.tags_ss ?? [],
+        creator: s.creator ? asUser(s.creator) : undefined,
+        creatorId: s.creator_uid,
+        kernelSnapshot: s.kernel_snapshot
+            ? asCodeSandboxSnapshot(s.kernel_snapshot)
+            : undefined,
+        kernelSnapshotId: s.kernel_snapshot_uid,
+    };
+};

package/lib/models/PageTag.d.ts

@@ -0,0 +1,19 @@
+import { CardIconColors } from '@primer/react-brand';
+import { Icon } from '@primer/octicons-react';
+type CardIconColorsType = (typeof CardIconColors)[number];
+export type PageTagMetadata = {
+    fillColor: React.CSSProperties['backgroundColor'];
+};
+export type PageTagName = 'agent' | 'ai' | 'ai-agent' | 'deep-learning' | 'example' | 'llm' | 'notebook' | 'python' | 'pytorch' | 'spatial' | 'tutorial';
+export type PageTag = {
+    id: string;
+    text?: PageTagName;
+    color: CardIconColorsType;
+    Icon: Icon;
+    metadata?: PageTagMetadata;
+};
+export declare const PAGE_TAGE_NONE: PageTag;
+export declare const PAGE_TAGS: PageTag[];
+export declare const PAGE_TAGS_BY_NAME_MAP: Map<PageTagName | undefined, PageTag>;
+export declare const PAGE_TAGS_BY_COLOR_MAP: Map<"default" | "blue" | "coral" | "gray" | "green" | "indigo" | "lime" | "orange" | "pink" | "purple" | "red" | "teal" | "yellow" | "lemon", PageTag>;
+export {};