@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/models/Environment.d.ts

@@ -0,0 +1,86 @@
+import { IContent } from './Content';
+import { IItem } from './Item';
+export type IEnvironment = IItem & {
+    type: 'environment';
+};
+export interface IResources {
+    cpu: string;
+    memory: string;
+    'nvidia.com/gpu'?: string;
+}
+/**
+ * Code snippet
+ */
+export interface ISnippet {
+    /**
+     * Snippet summary
+     */
+    title: string;
+    /**
+     * Snippet long description
+     */
+    description?: string;
+    /**
+     * Code snippet
+     */
+    code: string;
+}
+/**
+ * Datalayer environment
+ */
+export interface IDatalayerEnvironment {
+    /**
+     * Name
+     */
+    name: string;
+    /**
+     * Title
+     */
+    title: string;
+    /**
+     * Description
+     */
+    description: string;
+    /**
+     * Icon key (e.g. ai-agent -> AiAgentIcon)
+     */
+    icon?: string;
+    /**
+     * Execution language
+     */
+    language: string;
+    /**
+     * Docker image
+     */
+    dockerImage: string;
+    /**
+     * Example notebook URL
+     */
+    example?: string;
+    /**
+     * Example code snippets
+     */
+    snippets?: ISnippet[];
+    /**
+     * Associate kernel attributes
+     */
+    runtime?: {
+        /**
+         * Proposed display name
+         */
+        givenNameTemplate?: string;
+    };
+    /**
+     * Environment credits burning rate
+     */
+    burning_rate: number;
+    /**
+     * Environment server resources
+     */
+    resources?: IResources;
+    /**
+     * Environment contents.
+     */
+    contents?: IContent[];
+}
+export default IEnvironment;

package/lib/models/Environment.js

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

package/lib/models/EnvironmentDTO.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Environment domain model for the Datalayer Client.
+ *
+ * @module models/EnvironmentDTO
+ */
+import type { AgentRuntimesClient as DatalayerClient } from '../client/AgentRuntimesClient';
+/**
+ * Represents a computing environment available in the Datalayer platform.
+ * @interface EnvironmentData
+ */
+export interface EnvironmentData {
+    /** Human-readable title for the environment */
+    title: string;
+    /** Detailed description of the environment */
+    description: string;
+    /** Docker image used for this environment */
+    dockerImage: string;
+    /** Example usage or description */
+    example?: string;
+    /** Code snippets for this environment */
+    snippets?: any[];
+    /** Content mounts for this environment */
+    contents?: any[];
+    /** Kernel configuration */
+    runtime?: {
+        /** Template for kernel naming */
+        givenNameTemplate?: string;
+    };
+    /** Programming language (e.g., "python", "r") */
+    language: string;
+    /** Resource ranges configuration */
+    resourcesRanges?: any;
+    /** Credits consumed per hour when running */
+    burning_rate: number;
+    /** Simple resource specification */
+    resources?: any;
+    /** Name identifier for the environment */
+    name: string;
+    /** Docker registry for the image */
+    dockerRegistry?: string;
+    /** Icon or avatar URL for the environment */
+    icon?: string;
+    /** Whether the environment is enabled */
+    enabled?: boolean;
+    /** Tags associated with the environment */
+    tags?: string[];
+}
+/**
+ * Stable public interface for Environment data.
+ * This is the contract that Client consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface EnvironmentJSON {
+    /** Human-readable title for the environment */
+    title: string;
+    /** Unique name identifier for the environment */
+    name: string;
+    /** Credits consumed per hour for this environment */
+    burningRate: number;
+    /** Description of the environment (contains HTML markup) */
+    description: string;
+    /** Rich description of the environment (contains HTML markup) */
+    richDescription: string;
+}
+/**
+ * Response from listing available environments
+ * @interface ListEnvironmentsResponse
+ */
+export interface ListEnvironmentsResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response message from the server */
+    message: string;
+    /** Array of available environments */
+    environments: EnvironmentData[];
+}
+/**
+ * Environment domain model that wraps API responses with convenient methods.
+ * Provides information about available computational environments.
+ *
+ * @example
+ * ```typescript
+ * const environments = await client.listEnvironments();
+ * const aiEnv = environments.find(env => env.name === 'ai-env');
+ * console.log(aiEnv.title); // "AI Environment"
+ * ```
+ */
+export declare class EnvironmentDTO {
+    /** @internal */
+    _data: EnvironmentData;
+    /**
+     * Create an Environment instance.
+     *
+     * @param data - Environment data from API
+     * @param _client - Client instance (not currently used but kept for consistency)
+     */
+    constructor(data: EnvironmentData, _client: DatalayerClient);
+    /** Human-readable title for the environment (e.g., 'AI Environment', 'Python CPU Environment'). */
+    get title(): string;
+    /** Unique name identifier for the environment (e.g., 'ai-env', 'ai-agents-env'). */
+    get name(): string;
+    /** Credits consumed per hour for this environment. */
+    get burningRate(): number;
+    /** Rich description of the environment (contains HTML markup). */
+    get richDescription(): string;
+    /** Clean description without HTML tags. */
+    get description(): string;
+    /**
+     * Get environment data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core environment data with camelCase properties
+     */
+    toJSON(): EnvironmentJSON;
+    /**
+     * Get the raw environment data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw environment data from API
+     */
+    rawData(): EnvironmentData;
+    /** String representation of the environment. */
+    toString(): string;
+}

package/lib/models/EnvironmentDTO.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { validateJSON } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Environment domain model that wraps API responses with convenient methods.
+ * Provides information about available computational environments.
+ *
+ * @example
+ * ```typescript
+ * const environments = await client.listEnvironments();
+ * const aiEnv = environments.find(env => env.name === 'ai-env');
+ * console.log(aiEnv.title); // "AI Environment"
+ * ```
+ */
+export class EnvironmentDTO {
+    /** @internal */
+    _data;
+    /**
+     * Create an Environment instance.
+     *
+     * @param data - Environment data from API
+     * @param _client - Client instance (not currently used but kept for consistency)
+     */
+    constructor(data, _client) {
+        this._data = data;
+        // Client instance not currently used but kept for future extensibility
+    }
+    // ========================================================================
+    // Properties
+    // ========================================================================
+    /** Human-readable title for the environment (e.g., 'AI Environment', 'Python CPU Environment'). */
+    get title() {
+        return this._data.title;
+    }
+    /** Unique name identifier for the environment (e.g., 'ai-env', 'ai-agents-env'). */
+    get name() {
+        return this._data.name;
+    }
+    /** Credits consumed per hour for this environment. */
+    get burningRate() {
+        return this._data.burning_rate;
+    }
+    /** Rich description of the environment (contains HTML markup). */
+    get richDescription() {
+        return this._data.description;
+    }
+    /** Clean description without HTML tags. */
+    get description() {
+        // Simple HTML tag removal
+        return this._data.description.replace(/<[^>]*>/g, '').trim();
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get environment data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core environment data with camelCase properties
+     */
+    toJSON() {
+        const obj = {
+            title: this.title,
+            name: this.name,
+            burningRate: this.burningRate,
+            description: this.description,
+            richDescription: this.richDescription,
+        };
+        validateJSON(obj, 'Environment');
+        return obj;
+    }
+    /**
+     * Get the raw environment data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw environment data from API
+     */
+    rawData() {
+        return this._data;
+    }
+    /** String representation of the environment. */
+    toString() {
+        return `Environment(${this.name}, ${this.title})`;
+    }
+}

package/lib/models/Exercise.d.ts

@@ -0,0 +1,16 @@
+import { IDataset } from './Dataset';
+import { IItem } from './Item';
+export type ICode = string;
+export type IHelp = string;
+export type IExercise = IItem & {
+    type: 'exercise';
+    help: IHelp;
+    codePre: ICode;
+    codeSolution: ICode;
+    codeQuestion: ICode;
+    codeTest: ICode;
+    datasets: Array<IDataset>;
+    lastUpdateDate?: Date;
+    lastPublicationDate?: Date;
+};
+export default IExercise;

package/lib/models/Exercise.js

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

package/lib/models/Item.d.ts

@@ -0,0 +1,20 @@
+import { ISpaceItem } from './SpaceItem';
+import { IUser } from '@datalayer/core/lib/models/User';
+import { IAnyOrganization } from '@datalayer/core/lib/models/Organization';
+import { IAnySpace } from './Space';
+import { IItemType } from './ItemType';
+export type IAnyItem = ISpaceItem;
+export type IItem = {
+    id: string;
+    type: IItemType;
+    name: string;
+    description: string;
+    public: boolean;
+    creationDate: Date;
+    lastUpdateDate?: Date;
+    lastPublicationDate?: Date;
+    owner: IUser;
+    space: Partial<IAnySpace>;
+    organization: Partial<IAnyOrganization>;
+};
+export default IItem;

package/lib/models/Item.js

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

package/lib/models/ItemDTO.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Abstract base class for all Datalayer content items.
+ *
+ * @module models/ItemDTO
+ */
+import type { AgentRuntimesClient as DatalayerClient } from '../client/AgentRuntimesClient';
+/**
+ * Abstract base class for all Datalayer content items.
+ * Provides common functionality for content management including lifecycle tracking.
+ *
+ * @template TData - Raw data type from API
+ * @template TUpdateRequest - Update request type for API
+ */
+export declare abstract class ItemDTO<TData> {
+    protected _data: TData;
+    private _client;
+    private _deleted;
+    /**
+     * Create an Item instance.
+     * @param data - Item data from API
+     * @param client - Client instance
+     */
+    constructor(data: TData, client: DatalayerClient);
+    /** Check if this item has been deleted. */
+    get isDeleted(): boolean;
+    /**
+     * Check if this item has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    protected _checkDeleted(): void;
+    /** Item ID. */
+    get id(): string;
+    /** Unique identifier for the item. */
+    get uid(): string;
+    /** Parent space ID. */
+    get spaceId(): string;
+    /** Owner user ID. */
+    get ownerId(): string;
+    /** When the item was created. */
+    get createdAt(): Date;
+    /** The cached update time. */
+    get updatedAt(): Date;
+    /** Get the item type identifier. */
+    abstract get type(): string;
+    /** The cached name. */
+    abstract get name(): string;
+    /** Get the current name from API. */
+    abstract getName(): Promise<string>;
+    /** The cached content. */
+    abstract get content(): any;
+    /** Get when the item was last updated from API. */
+    abstract getUpdatedAt(): Promise<Date>;
+    /** Update the item. */
+    abstract update(...args: any[]): Promise<this>;
+    /**
+     * Delete this item permanently.
+     * After deletion, all subsequent method calls will throw errors.
+     */
+    delete(): Promise<void>;
+    /** Get the document content from API. */
+    getContent(): Promise<any>;
+    /** Get raw item data object. */
+    rawData(): TData;
+    /** Convert to JSON representation - must be implemented by subclasses. */
+    abstract toJSON(): any;
+    /** String representation of the item. */
+    toString(): string;
+    /** Get Client token for API calls. */
+    protected _getToken(): string;
+    /** Get spacer API URL for API calls. */
+    protected _getSpacerUrl(): string;
+    /** Update internal data after API call. */
+    protected _updateData(newData: TData): void;
+}

package/lib/models/ItemDTO.js

@@ -0,0 +1,186 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import * as items from '../api/spacer/items';
+/**
+ * Abstract base class for all Datalayer content items.
+ * Provides common functionality for content management including lifecycle tracking.
+ *
+ * @template TData - Raw data type from API
+ * @template TUpdateRequest - Update request type for API
+ */
+export class ItemDTO {
+    _data;
+    _client;
+    _deleted = false;
+    /**
+     * Create an Item instance.
+     * @param data - Item data from API
+     * @param client - Client instance
+     */
+    constructor(data, client) {
+        this._data = data;
+        this._client = client;
+    }
+    // ========================================================================
+    // Deletion State Management
+    // ========================================================================
+    /** Check if this item has been deleted. */
+    get isDeleted() {
+        return this._deleted;
+    }
+    /**
+     * Check if this item has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`${this.constructor.name} ${this._data.id} has been deleted and no longer exists`);
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Item ID. */
+    get id() {
+        this._checkDeleted();
+        return this._data.id;
+    }
+    /** Unique identifier for the item. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** Parent space ID. */
+    get spaceId() {
+        this._checkDeleted();
+        // Try the direct field first (if API provides it)
+        if (this._data.space_id) {
+            return this._data.space_id;
+        }
+        // Extract from s3_path_s if available: "datalayer.ai/SPACE_ID/..."
+        const s3Path = this._data.s3_path_s;
+        if (s3Path && typeof s3Path === 'string') {
+            const match = s3Path.match(/^datalayer\.app\/([^/]+)\//);
+            if (match) {
+                return match[1];
+            }
+        }
+        // Fallback to empty string if no space ID can be determined
+        return '';
+    }
+    /** Owner user ID. */
+    get ownerId() {
+        this._checkDeleted();
+        return (this._data.owner_id || this._data.creator_uid || '');
+    }
+    /** When the item was created. */
+    get createdAt() {
+        this._checkDeleted();
+        const dateStr = this._data.creation_ts_dt || this._data.created_at;
+        if (!dateStr) {
+            throw new Error(`No creation timestamp available for ${this.constructor.name.toLowerCase()}`);
+        }
+        return new Date(dateStr);
+    }
+    /** The cached update time. */
+    get updatedAt() {
+        this._checkDeleted();
+        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 update timestamp available for ${this.constructor.name.toLowerCase()}`);
+        }
+        return new Date(dateStr);
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Delete this item permanently.
+     * After deletion, all subsequent method calls will throw errors.
+     */
+    async delete() {
+        this._checkDeleted();
+        const token = this._client.getToken();
+        const spacerUrl = this._client.getSpacerUrl();
+        await items.deleteItem(token, this.uid, spacerUrl);
+        this._deleted = true;
+    }
+    /** Get the document content from API. */
+    async getContent() {
+        this._checkDeleted();
+        // First try: CDN URL (fastest)
+        const cdnUrl = this._data.cdn_url_s;
+        if (cdnUrl) {
+            try {
+                const response = await fetch(cdnUrl);
+                if (!response.ok) {
+                    throw new Error('Failed to fetch content from CDN');
+                }
+                const data = await response.json();
+                if (data.content !== undefined && data.content !== null) {
+                    return data.content;
+                }
+            }
+            catch (error) {
+                console.error('Error fetching content from CDN:', error);
+            }
+        }
+        // Second try: Check if content is already loaded
+        const cachedContent = this.content;
+        if (cachedContent !== undefined && cachedContent !== null) {
+            return cachedContent;
+        }
+        // Third try: Fetch full item details from API
+        try {
+            const token = this._client.getToken();
+            const spacerUrl = this._client.getSpacerUrl();
+            const response = await items.getItem(token, this.uid, spacerUrl);
+            // Update internal data with full item details
+            if (response.success && response.item) {
+                this._data = response.item;
+                const freshContent = this.content;
+                if (freshContent !== undefined && freshContent !== null) {
+                    return freshContent;
+                }
+            }
+        }
+        catch (error) {
+            console.error('Error fetching full item details:', error);
+        }
+        throw new Error(`Content is not available for item ${this.uid}. The item may not have been fully loaded or the content is not yet available.`);
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /** Get raw item data object. */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the item. */
+    toString() {
+        this._checkDeleted();
+        const name = this.name || 'Unnamed';
+        return `${this.constructor.name}(${this.id}, ${name})`;
+    }
+    // ========================================================================
+    // Protected Helper Methods
+    // ========================================================================
+    /** Get Client token for API calls. */
+    _getToken() {
+        return this._client.getToken();
+    }
+    /** Get spacer API URL for API calls. */
+    _getSpacerUrl() {
+        return this._client.getSpacerUrl();
+    }
+    /** Update internal data after API call. */
+    _updateData(newData) {
+        this._data = newData;
+    }
+}

package/lib/models/ItemType.d.ts

@@ -0,0 +1,2 @@
+export type IItemType = 'assignment' | 'authoring' | 'cell' | 'content' | 'credits' | 'dataset' | 'datasource' | 'document' | 'documentation' | 'environment' | 'exercise' | 'growth' | 'home' | 'invite' | 'lesson' | 'library' | 'mail' | 'management' | 'notebook' | 'onboarding' | 'organization' | 'page' | 'runtime' | 'runtime-snapshot' | 'settings' | 'share' | 'space' | 'storage' | 'success' | 'support' | 'tag' | 'team' | 'usage' | 'user' | 'undefined';
+export default IItemType;

package/lib/models/ItemType.js

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

package/lib/models/Lesson.d.ts

@@ -0,0 +1,5 @@
+import { IBaseNotebook } from './Notebook';
+export type ILesson = IBaseNotebook & {
+    type: 'lesson';
+};
+export default ILesson;

package/lib/models/Lesson.js

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