@datalayer/core 0.0.2 → 0.0.3

package/README.md

@@ -37,6 +37,7 @@ This package serves as the base foundation used by many other Datalayer packages
 - **📸 Snapshot Management**: Create and manage compute snapshots of your runtimes for reproducible environments
 - **🔒 Secrets Management**: Securely handle sensitive data and credentials in your workflows
 - **🐍 Python SDK**: Programmatic access to Datalayer platform with context managers and clean resource management
+- **🌐 TypeScript SDK**: Programmatic access to Datalayer platform with context managers and clean resource management
 - **💻 Command Line Interface**: CLI tools for managing runtimes, snapshots, and platform resources
 - **🔧 Base Classes**: Core application classes and configuration inherited by other Datalayer projects
 
@@ -56,7 +57,7 @@ cd core
 pip install -e .[test]
 ```
 
-## Quick Start
+## Quick Start with Python
 
 ### 1. Authentication
 
@@ -114,6 +115,16 @@ datalayer runtime exec my-script.py --runtime <runtime-id>
 datalayer snapshots create <pod-name> my-snapshot 'AI work!' False
 ```
 
+## Examples
+
+For comprehensive usage examples, see the [`examples/`](https://github.com/datalayer/core/tree/main/examples) directory which includes:
+
+- **FastAPI + scikit-learn**: Web application with ML models
+- **Streamlit + scikit-learn**: Interactive data science apps
+- **PyTorch GPU workloads**: High-performance computing examples
+- **Decorator patterns**: Remote function execution with `@datalayer`
+- **And more**: Complete examples with documentation and setup instructions
+
 ## Platform Integration
 
 Datalayer adds AI capabilities and scalable compute runtimes to your development workflows. The platform is designed to seamlessly integrate into your existing processes and supercharge your computations with the processing power you need.

package/lib/App.css

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+/*  text-align: center; */
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

package/lib/App.d.ts

@@ -1,3 +1,3 @@
-import './App.css';
+import "./App.css";
 export declare function App(): import("react/jsx-runtime").JSX.Element;
 export default App;

package/lib/App.js

@@ -3,12 +3,24 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { useState } from 'react';
-import reactLogo from './assets/react.svg';
-import viteLogo from '/vite.svg';
-import './App.css';
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+import { useState } from "react";
+import reactLogo from "./assets/react.svg";
+import { useJupyter, JupyterReactTheme } from '@datalayer/jupyter-react';
+import { CellExample } from "./examples/CellExample";
+import { NotebookExample } from "./examples/NotebookExample";
+import "./App.css";
 export function App() {
+    const { defaultKernel, serviceManager } = useJupyter({
+        jupyterServerUrl: "https://oss.datalayer.run/api/jupyter-server",
+        jupyterServerToken: "60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6",
+        startDefaultKernel: true,
+    });
     const [count, setCount] = useState(0);
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { children: [_jsx("a", { href: "https://vite.dev", target: "_blank", children: _jsx("img", { src: viteLogo, className: "logo", alt: "Vite logo" }) }), _jsx("a", { href: "https://react.dev", target: "_blank", children: _jsx("img", { src: reactLogo, className: "logo react", alt: "React logo" }) })] }), _jsx("h1", { children: "Vite + React" }), _jsxs("div", { className: "card", children: [_jsxs("button", { onClick: () => setCount((count) => count + 1), children: ["count is ", count] }), _jsxs("p", { children: ["Edit ", _jsx("code", { children: "src/App.tsx" }), " and save to test HMR"] })] }), _jsx("p", { className: "read-the-docs", children: "Click on the Vite and React logos to learn more" })] }));
+    return (_jsxs("div", { className: "App", children: [_jsx(_Fragment, { children: _jsxs(JupyterReactTheme, { children: [defaultKernel && _jsx(CellExample, { kernel: defaultKernel }), defaultKernel && serviceManager && _jsx(NotebookExample, { kernel: defaultKernel, serviceManager: serviceManager })] }) }), _jsxs("div", { children: [_jsx("a", { href: "https://reactjs.org", target: "_blank", children: _jsx("img", { src: reactLogo, className: "logo react", alt: "React logo" }) }), _jsx("a", { href: "https://vitejs.dev", target: "_blank", children: _jsx("img", { src: "/vite.svg", className: "logo", alt: "Vite logo" }) })] }), _jsx("h1", { children: "React + Vite" }), _jsx("h2", { children: "On CodeSandbox!" }), _jsxs("div", { className: "card", children: [_jsxs("button", { onClick: () => setCount((count) => count + 1), children: ["count is ", count] }), _jsxs("p", { children: ["Edit ", _jsx("code", { children: "src/App.tsx" }), " and save to test HMR."] }), _jsx("p", { children: "Tip: you can use the inspector button next to address bar to click on components in the preview and open the code in the editor!" })] }), _jsx("p", { className: "read-the-docs", children: "Click on the Vite and React logos to learn more" })] }));
 }
 export default App;

package/lib/__tests__/index.test.js

@@ -11,7 +11,8 @@ describe('@datalayer/core - index', () => {
     });
     it('should export BackdropContext from hooks', () => {
         expect(coreIndex.BackdropContext).toBeDefined();
-        expect(coreIndex.BackdropContext).toBe('lkj');
+        expect(coreIndex.BackdropContext).toHaveProperty('$$typeof');
+        expect(typeof coreIndex.BackdropContext).toBe('object');
     });
     it('should export utils functions', () => {
         expect(coreIndex.convertToLargestUnit).toBeDefined();

package/lib/api/{RunApi.d.ts → DatalayerApi.d.ts}

@@ -3,8 +3,8 @@
  */
 export declare class RunResponseError extends Error {
     /**
-     * Create a RunResponseError from a response, handling the traceback and message
-     * as appropriate.
+     * Create a RunResponseError from a response,
+     * handling the traceback and message as appropriate.
      *
      * @param response The response object.
      *
@@ -46,7 +46,7 @@ export declare class NetworkError extends TypeError {
      */
     constructor(original: TypeError);
 }
-export interface IRequestRunAPIOptions {
+export interface IRequestDatalayerAPIOptions {
     /**
      * URL to request
      */
@@ -72,4 +72,4 @@ export interface IRequestRunAPIOptions {
      */
     signal?: AbortSignal;
 }
-export declare function requestRunAPI<T = any>({ url, method, body, token, signal, headers }: IRequestRunAPIOptions): Promise<T>;
+export declare function requestDatalayerAPI<T = any>({ url, method, body, token, signal, headers }: IRequestDatalayerAPIOptions): Promise<T>;

package/lib/api/{RunApi.js → DatalayerApi.js}

@@ -2,11 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 import { URLExt } from '@jupyterlab/coreutils';
 import { sleep } from '../utils';
 /**
@@ -14,8 +9,8 @@ import { sleep } from '../utils';
  */
 export class RunResponseError extends Error {
     /**
-     * Create a RunResponseError from a response, handling the traceback and message
-     * as appropriate.
+     * Create a RunResponseError from a response,
+     * handling the traceback and message as appropriate.
      *
      * @param response The response object.
      *
@@ -85,7 +80,7 @@ export class NetworkError extends TypeError {
         this.stack = original.stack;
     }
 }
-export async function requestRunAPI({ url, method, body, token, signal, headers = {} }) {
+export async function requestDatalayerAPI({ url, method, body, token, signal, headers = {} }) {
     const headers_ = new Headers(headers);
     if (!headers_.has('Accept')) {
         headers_.set('Accept', 'application/json');
@@ -103,7 +98,7 @@ export async function requestRunAPI({ url, method, body, token, signal, headers
             method: method ?? 'GET',
             headers: headers_,
             body: body ? JSON.stringify(body) : undefined,
-            //      credentials: token ? 'include' : 'omit',
+            // credentials: token ? 'include' : 'omit',
             credentials: 'include',
             mode: 'cors',
             cache: 'no-store',

package/lib/api/index.d.ts

@@ -1,2 +1,3 @@
+export * from "./jupyter";
 export * from "./runtimes";
-export * from "./RunApi";
+export * from "./DatalayerApi";

package/lib/api/index.js

@@ -2,10 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
+export * from "./jupyter";
 export * from "./runtimes";
-export * from "./RunApi";
+export * from "./DatalayerApi";

package/lib/api/{runtimes → jupyter}/exec/Python.js

@@ -2,11 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 export function listVariables() {
     return `
 def _list_variables():

package/lib/api/{runtimes → jupyter}/exec/Snippets.js

@@ -2,11 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 import * as Python from './Python';
 /**
  * Facade to interact with kernels by requesting code execution.

package/lib/api/{runtimes → jupyter}/exec/index.js

@@ -2,10 +2,5 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 export * from './Python';
 export * from './Snippets';

package/lib/api/jupyter/index.d.ts

@@ -0,0 +1,2 @@
+export * from './exec';
+export * from './kernelsHandler';

package/lib/api/jupyter/index.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './exec';
+export * from './kernelsHandler';

package/lib/api/{runtimes → jupyter}/kernelsHandler.d.ts

@@ -1,5 +1,5 @@
 /**
- * Call the Runtimes extension
+ * Call the jupyter_kernels extension
  *
  * @param endPoint API REST end point for the extension
  * @param init Initial values for the request

package/lib/api/{runtimes → jupyter}/kernelsHandler.js

@@ -2,15 +2,10 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
 /**
- * Call the Runtimes extension
+ * Call the jupyter_kernels extension
  *
  * @param endPoint API REST end point for the extension
  * @param init Initial values for the request

package/lib/api/runtimes/actions.d.ts

@@ -0,0 +1,102 @@
+import { IRuntimeOptions } from '..';
+import type { IRuntimeSnapshot, IDatalayerEnvironment, IRuntimePod } from '../../models';
+/**
+ * Get available Environments.
+ */
+export declare function getEnvironments(): Promise<IDatalayerEnvironment[]>;
+/**
+ * Create a Runtime.
+ */
+export declare function createRuntime(options: IRuntimeOptions): Promise<IRuntimePod>;
+/**
+ * Get the Runtimes.
+ */
+export declare function getRuntimes(): Promise<IRuntimePod[]>;
+/**
+ * Delete a Runtime
+ */
+export declare function deleteRuntime(options: {
+    /**
+     * Runtime ID
+     */
+    id: string;
+    /**
+     * Deletion reason
+     */
+    reason?: string;
+}): Promise<void>;
+/**
+ * Snapshot a Runtime.
+ */
+export declare function snapshotRuntime(options: {
+    /**
+     * Runtime ID.
+     */
+    id: string;
+    /**
+     * Snapshot name.
+     */
+    name?: string;
+    /**
+     * Snapshot description.
+     */
+    description?: string;
+    /**
+     * Whether to stop the kernel after the snapshot completion or not.
+     */
+    stop?: boolean;
+}): Promise<IRuntimeSnapshot>;
+/**
+ * Get Runtime Snapshots.
+ */
+export declare function getRuntimeSnapshots(): Promise<IRuntimeSnapshot[]>;
+/**
+ * Load a Runtime Snapshot within a kernel.
+ */
+export declare function loadRuntimeSnapshot(options: {
+    /**
+     * Runtime ID
+     */
+    id: string;
+    /**
+     * Snapshot UID
+     */
+    from: string;
+}): Promise<void>;
+/**
+ * Returns the Runtime Snapshot download URL.
+ *
+ * @param id Snapshot UID to download
+ * @returns The download URL
+ */
+export declare function createRuntimeSnapshotDownloadURL(id: string): string;
+/**
+ * Export a Runtime Snapshot.
+ *
+ * @param id Runtime snapshot UID to download
+ */
+export declare function exportRuntimeSnapshot(id: string): void;
+/**
+ * Delete a Runtime Snapshot.
+ */
+export declare function deleteRuntimeSnapshot(id: string): Promise<void>;
+/**
+ * Update Runtime Snapshot metadata.
+ */
+export declare function updateRuntimeSnapshot(id: string, metadata: {
+    name?: string;
+    description?: string;
+}): Promise<void>;
+/**
+ * Upload a Runtime Snapshot.
+ *
+ * Note: The promise will be rejected if the runtime state is empty.
+ */
+export declare function uploadRuntimeSnapshot(options: {
+    file: File | Blob;
+    metadata: {
+        filename: string;
+        [key: string]: string;
+    };
+    onProgress?: (bytesUploaded: number, bytesTotal: number) => void;
+}): Promise<void>;

package/lib/api/runtimes/{runtimesApi.js → actions.js}

@@ -2,26 +2,21 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 /**
- * Datalayer Jupyter API interface.
+ * Runtimes APIs.
  */
 import { URLExt } from '@jupyterlab/coreutils';
 import { PromiseDelegate } from '@lumino/coreutils';
 import { Upload } from 'tus-js-client';
-import { requestRunAPI } from '..';
+import { requestDatalayerAPI } from '..';
 import { asRuntimeSnapshot } from '../../models';
 import { iamStore, runtimesStore } from '../../state';
 import { sleep } from '../../utils';
 /**
- * Get available environments.
+ * Get available Environments.
  */
 export async function getEnvironments() {
-    const data = await requestRunAPI({
+    const data = await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, 'api/runtimes/v1/environments'),
         token: iamStore.getState().token
     });
@@ -32,7 +27,7 @@ export async function getEnvironments() {
     return data.environments ?? [];
 }
 /**
- * Create a Kernel.
+ * Create a Runtime.
  */
 export async function createRuntime(options) {
     const { externalToken, token } = iamStore.getState();
@@ -48,7 +43,7 @@ export async function createRuntime(options) {
     if (options.snapshot) {
         body['from'] = options.snapshot;
     }
-    const data = await requestRunAPI({
+    const data = await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, `api/runtimes/v1/runtimes`),
         method: 'POST',
         body,
@@ -68,10 +63,10 @@ export async function createRuntime(options) {
     return data.runtime;
 }
 /**
- * List Runtimes
+ * Get the Runtimes.
  */
 export async function getRuntimes() {
-    const data = await requestRunAPI({
+    const data = await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, 'api/runtimes/v1/runtimes'),
         token: iamStore.getState().token
     });
@@ -83,11 +78,11 @@ export async function getRuntimes() {
     return data.runtimes ?? [];
 }
 /**
- * Remove a Kernel
+ * Delete a Runtime
  */
 export async function deleteRuntime(options) {
     const externalToken = iamStore.getState().externalToken;
-    await requestRunAPI({
+    await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, `api/runtimes/v1/runtimes/${options.id}`) +
             URLExt.objectToQueryString(options.reason ? { reason: options.reason } : {}),
         method: 'DELETE',
@@ -102,10 +97,10 @@ export async function deleteRuntime(options) {
     });
 }
 /**
- * Snapshot a Kernel.
+ * Snapshot a Runtime.
  */
 export async function snapshotRuntime(options) {
-    const data = await requestRunAPI({
+    const data = await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, 'api/runtimes/v1/runtime-snapshots'),
         method: 'POST',
         body: {
@@ -122,10 +117,10 @@ export async function snapshotRuntime(options) {
     return asRuntimeSnapshot(data.snapshot);
 }
 /**
- * Get Kernel Snapshots.
+ * Get Runtime Snapshots.
  */
 export async function getRuntimeSnapshots() {
-    const data = await requestRunAPI({
+    const data = await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, 'api/runtimes/v1/runtime-snapshots'),
         token: iamStore.getState().token
     });
@@ -136,10 +131,10 @@ export async function getRuntimeSnapshots() {
     return (data.snapshots ?? []).map(asRuntimeSnapshot);
 }
 /**
- * Load a kernel snapshot within a kernel.
+ * Load a Runtime Snapshot within a kernel.
  */
 export async function loadRuntimeSnapshot(options) {
-    const data = await requestRunAPI({
+    const data = await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, 'api/runtimes/v1/runtimes', options.id),
         method: 'PUT',
         body: {
@@ -152,7 +147,7 @@ export async function loadRuntimeSnapshot(options) {
     }
 }
 /**
- * Returns the runtime snapshot download URL.
+ * Returns the Runtime Snapshot download URL.
  *
  * @param id Snapshot UID to download
  * @returns The download URL
@@ -165,7 +160,7 @@ export function createRuntimeSnapshotDownloadURL(id) {
         }));
 }
 /**
- * Export runtime snapshot.
+ * Export a Runtime Snapshot.
  *
  * @param id Runtime snapshot UID to download
  */
@@ -179,21 +174,21 @@ export function exportRuntimeSnapshot(id) {
     document.body.removeChild(element);
 }
 /**
- * Delete runtime snapshot.
+ * Delete a Runtime Snapshot.
  */
 export async function deleteRuntimeSnapshot(id) {
-    await requestRunAPI({
+    await requestDatalayerAPI({
         url: URLExt.join(runtimesStore.getState().runtimesRunUrl, `api/runtimes/v1/runtime-snapshots/${id}`),
         method: 'DELETE',
         token: iamStore.getState().token
     });
-    // Poll runtime snapshot state upto its deletion
+    // Poll Runtime Snapshot state up-to its deletion
     try {
         let sleepTimeout = 1000;
         while (true) {
             await sleep(sleepTimeout);
             sleepTimeout *= 2;
-            const response = await requestRunAPI({
+            const response = await requestDatalayerAPI({
                 url: URLExt.join(runtimesStore.getState().runtimesRunUrl, `api/runtimes/v1/runtime-snapshots/${id}`),
                 token: iamStore.getState().token
             });
@@ -213,11 +208,11 @@ export async function deleteRuntimeSnapshot(id) {
     }
 }
 /**
- * Update runtime snapshot metadata.
+ * Update Runtime Snapshot metadata.
  */
 export async function updateRuntimeSnapshot(id, metadata) {
     if (metadata.name || metadata.description) {
-        await requestRunAPI({
+        await requestDatalayerAPI({
             url: URLExt.join(runtimesStore.getState().runtimesRunUrl, `api/runtimes/v1/runtime-snapshots/${id}`),
             method: 'PATCH',
             body: { ...metadata },
@@ -226,13 +221,13 @@ export async function updateRuntimeSnapshot(id, metadata) {
     }
 }
 /**
- * Upload a runtime snapshot.
+ * Upload a Runtime Snapshot.
  *
  * Note: The promise will be rejected if the runtime state is empty.
  */
 export async function uploadRuntimeSnapshot(options) {
     if (options.file.size === 0) {
-        return Promise.reject('Empty runtime snapshot');
+        return Promise.reject('Empty Runtime Snapshot.');
     }
     const tracker = new PromiseDelegate();
     // Create a new tus upload.