@datalayer/core 0.0.1 → 0.0.2

package/README.md

@@ -1,19 +1,188 @@
+**Datalayer Core**
+
+---
+
 [![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)
 
 [![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
 
 # Ξ Datalayer Core
 
-Datalayer Core is the base foundation package used by many other Datalayer packages.
+<p align="center">
+  <img src="https://assets.datalayer.tech/datalayer-25.svg" alt="Datalayer Logo" width="200"></img>
+</p>
+
+<p align="center">
+  <strong>The foundational Python SDK for the Datalayer AI Platform</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/datalayer-core/"><img src="https://img.shields.io/pypi/v/datalayer-core.svg" alt="PyPI version"></img></a>
+  <a href="https://pypi.org/project/datalayer-core/"><img src="https://img.shields.io/pypi/pyversions/datalayer-core.svg" alt="Python versions"></img></a>
+  <a href="https://github.com/datalayer/core/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-BSD%203--Clause-blue.svg" alt="License"></img></a>
+  <a href="https://docs.datalayer.app/"><img src="https://img.shields.io/badge/docs-datalayer.app-blue" alt="Documentation"></img></a>
+  <a href="https://github.com/datalayer/core/actions/workflows/tests.yml"><img src="https://github.com/datalayer/core/actions/workflows/tests.yml/badge.svg" alt="Units Tests"></img></a>
+</p>
+
+## Overview
+
+Datalayer Core is the foundational package that powers the [Datalayer AI Platform](https://datalayer.app/). It provides both a Python SDK and Command Line Interface (CLI) for AI engineers, data scientists, and researchers to seamlessly integrate scalable compute runtimes into their workflows.
+
+This package serves as the base foundation used by many other Datalayer packages, containing core application classes, configuration, and unified APIs for authentication, runtime management, and code execution in cloud-based environments.
+
+## Key Features
+
+- **🔐 Simple Authentication**: Easy token-based authentication with environment variable support
+- **⚡ Runtime Management**: Create and manage scalable compute runtimes (CPU/GPU) for code execution
+- **📸 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
+- **💻 Command Line Interface**: CLI tools for managing runtimes, snapshots, and platform resources
+- **🔧 Base Classes**: Core application classes and configuration inherited by other Datalayer projects
+
+## Installation
+
+Install Datalayer Core using pip:
+
+```bash
+pip install datalayer-core
+```
+
+For development installation:
+
+```bash
+git clone https://github.com/datalayer/core.git
+cd core
+pip install -e .[test]
+```
+
+## Quick Start
+
+### 1. Authentication
+
+Set your Datalayer token as an environment variable:
+
+```bash
+export DATALAYER_TOKEN="your-token-here"
+```
+
+Or pass it directly to the SDK:
+
+```python
+from datalayer_core import DatalayerClient
+
+# Using environment variable
+client = DatalayerClient()
+
+# Or pass token directly
+client = DatalayerClient(token="your-token-here")
+
+if client.authenticate():
+    print("Successfully authenticated!")
+```
+
+### 2. Execute Code in a Runtime
+
+Use context managers to create runtimes and ensure proper resource cleanup:
 
-It contains base application classes and configuration inherited by other projects.
+```python
+from datalayer_core import DatalayerClient
 
-## Develop
+client = DatalayerClient()
+
+# Execute code in a managed runtime
+with client.create_runtime() as runtime:
+    response = runtime.execute("print('Hello from Datalayer!')")
+    print(response.stdout)
+```
+
+### 3. Using the CLI
+
+The CLI provides command-line access to Datalayer platform features:
+
+```bash
+# List available runtimes
+datalayer runtime list
+
+# Create a new runtime
+datalayer runtime create ai-env --given-name my-runtime-123
+
+# Execute a script in a runtime
+datalayer runtime exec my-script.py --runtime <runtime-id>
+
+# Create a snapshot from a runtime but do not terminate the runtime
+datalayer snapshots create <pod-name> my-snapshot 'AI work!' False
+```
+
+## 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.
+
+Key platform features accessible through this SDK and CLI:
+
+- **Remote Runtimes**: Execute code on powerful remote machines with CPU, RAM, and GPU resources
+- **Multiple Interfaces**: Access and consume runtimes through Python SDK, CLI, or other integrated tools
+- **Scalable Compute**: Dynamically scale your computational resources based on workload requirements
+
+## Documentation
+
+- **Command Line Interface (CLI)**: [https://docs.datalayer.app/cli/](https://docs.datalayer.app/cli/)
+- **Core Python SDK**: [core.datalayer.tech/python/](https://core.datalayer.tech/python/)
+- **Platform Documentation**: [docs.datalayer.app](https://docs.datalayer.app/)
+- **API Reference**: [API documentation](https://docs.datalayer.app/api/)
+
+## Development
+
+### Running Tests
 
 ```bash
 pip install -e .[test]
-# jupyter server extension enable datalayer
-jupyter server extension list
-# open http://localhost:8888/api/jupyter?token=60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6
-make start
+pytest datalayer_core/tests/
 ```
+
+### Contributing
+
+This SDK is designed to be simple and extensible. We welcome contributions! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
+
+For issues and enhancement requests, please use the [GitHub issue tracker](https://github.com/datalayer/core/issues).
+
+## Architecture
+
+Datalayer Core serves as the foundation for the entire Datalayer ecosystem:
+
+- **Base Classes**: Core application classes inherited by other Datalayer packages
+- **Configuration Management**: Centralized configuration system for all Datalayer components
+- **Authentication Layer**: Unified authentication across all Datalayer services
+- **Runtime Abstraction**: Common interface for different types of compute runtimes
+- **Resource Management**: Automatic cleanup and lifecycle management
+
+## Use Cases
+
+- **AI/ML Development**: Scale your machine learning workflows with cloud compute using SDK or CLI
+- **Data Analysis**: Process large datasets with powerful remote runtimes
+- **Research**: Collaborate on computational research with reproducible environments
+- **Automation**: Integrate Datalayer into CI/CD pipelines and automated workflows using CLI tools
+- **Prototyping**: Quickly test ideas without local hardware limitations
+
+## License
+
+This project is licensed under the [BSD 3-Clause License](https://github.com/datalayer/core/blob/main/LICENSE).
+
+## Support
+
+- **Documentation**: [Datalayer Platform Documentation](https://docs.datalayer.app/)
+- **Issues**: [GitHub Issues](https://github.com/datalayer/core/issues)
+- **Community**: [Datalayer Platform](https://datalayer.app/)
+
+---
+
+<p align="center">
+  <strong>🚀 AI Platform for Data Analysis</strong><br></br>
+  <a href="https://datalayer.app/">Get started with Datalayer today!</a>
+</p>

package/lib/App.d.ts

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

package/lib/App.js

@@ -1,4 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * 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';

package/lib/__tests__/App.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/App.test.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { describe, it, expect } from 'vitest';
+import { App } from '../App';
+describe('App Component', () => {
+    it('should be a function component', () => {
+        expect(typeof App).toBe('function');
+    });
+    it('should be defined', () => {
+        expect(App).toBeDefined();
+    });
+    it('component name should be App', () => {
+        expect(App.name).toBe('App');
+    });
+});

package/lib/__tests__/hooks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/hooks.test.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { describe, it, expect } from 'vitest';
+import { useCache } from '../hooks';
+describe('hooks', () => {
+    it('should export qfds constant', () => {
+        expect(useCache).toBeDefined();
+    });
+    /*
+    it('useCache should have correct value', () => {
+      expect(useCache).toBe('');
+    });
+    it('useCache should be a string', () => {
+      expect(typeof useCache).toBe('string');
+    });
+    */
+});

package/lib/__tests__/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/index.test.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { describe, it, expect } from 'vitest';
+import * as coreIndex from '../index';
+describe('@datalayer/core - index', () => {
+    it('should export App', () => {
+        expect(coreIndex.App).toBeDefined();
+        expect(typeof coreIndex.App).toBe('function');
+    });
+    it('should export BackdropContext from hooks', () => {
+        expect(coreIndex.BackdropContext).toBeDefined();
+        expect(coreIndex.BackdropContext).toBe('lkj');
+    });
+    it('should export utils functions', () => {
+        expect(coreIndex.convertToLargestUnit).toBeDefined();
+        expect(coreIndex.asArray).toBeDefined();
+    });
+    it('should have all expected exports', () => {
+        const exports = Object.keys(coreIndex);
+        expect(exports).toContain('App');
+        expect(exports).toContain('convertToLargestUnit');
+        expect(exports).toContain('asArray');
+    });
+});

package/lib/__tests__/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/integration.test.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { describe, it, expect } from 'vitest';
+describe('@datalayer/core - Integration Tests', () => {
+    it('should have proper TypeScript compilation', () => {
+        // This test ensures TypeScript compilation is working
+        const testNumber = 42;
+        const testString = 'hello';
+        const testBoolean = true;
+        expect(typeof testNumber).toBe('number');
+        expect(typeof testString).toBe('string');
+        expect(typeof testBoolean).toBe('boolean');
+    });
+    it('should support modern JavaScript features', () => {
+        // Test arrow functions
+        const add = (a, b) => a + b;
+        expect(add(2, 3)).toBe(5);
+        // Test template literals
+        const name = 'Datalayer';
+        const greeting = `Hello, ${name}!`;
+        expect(greeting).toBe('Hello, Datalayer!');
+        // Test destructuring
+        const obj = { x: 1, y: 2 };
+        const { x, y } = obj;
+        expect(x).toBe(1);
+        expect(y).toBe(2);
+        // Test spread operator
+        const arr1 = [1, 2, 3];
+        const arr2 = [...arr1, 4, 5];
+        expect(arr2).toEqual([1, 2, 3, 4, 5]);
+    });
+    it('should support async/await', async () => {
+        const asyncFunction = async () => {
+            return new Promise(resolve => {
+                setTimeout(() => resolve('async result'), 10);
+            });
+        };
+        const result = await asyncFunction();
+        expect(result).toBe('async result');
+    });
+    it('should support generics', () => {
+        function identity(arg) {
+            return arg;
+        }
+        expect(identity('test')).toBe('test');
+        expect(identity(123)).toBe(123);
+        expect(identity(true)).toBe(true);
+    });
+    it('should handle error cases', () => {
+        const throwError = () => {
+            throw new Error('Test error');
+        };
+        expect(throwError).toThrow('Test error');
+    });
+});

package/lib/__tests__/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/utils.test.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { describe, it, expect } from 'vitest';
+import { formatString, addNumbers, isDefined, delay } from '../utils';
+describe('utils', () => {
+    describe('formatString', () => {
+        it('should trim and lowercase strings', () => {
+            expect(formatString('  HELLO WORLD  ')).toBe('hello world');
+        });
+        it('should handle empty strings', () => {
+            expect(formatString('')).toBe('');
+        });
+        it('should handle already formatted strings', () => {
+            expect(formatString('hello')).toBe('hello');
+        });
+    });
+    describe('addNumbers', () => {
+        it('should add positive numbers', () => {
+            expect(addNumbers(2, 3)).toBe(5);
+        });
+        it('should add negative numbers', () => {
+            expect(addNumbers(-2, -3)).toBe(-5);
+        });
+        it('should add zero', () => {
+            expect(addNumbers(5, 0)).toBe(5);
+        });
+        it('should handle decimals', () => {
+            expect(addNumbers(1.5, 2.5)).toBe(4);
+        });
+    });
+    describe('isDefined', () => {
+        it('should return true for defined values', () => {
+            expect(isDefined('hello')).toBe(true);
+            expect(isDefined(0)).toBe(true);
+            expect(isDefined(false)).toBe(true);
+            expect(isDefined([])).toBe(true);
+        });
+        it('should return false for undefined', () => {
+            expect(isDefined(undefined)).toBe(false);
+        });
+        it('should return false for null', () => {
+            expect(isDefined(null)).toBe(false);
+        });
+    });
+    describe('delay', () => {
+        it('should resolve after specified time', async () => {
+            const start = Date.now();
+            await delay(100);
+            const end = Date.now();
+            expect(end - start).toBeGreaterThanOrEqual(90); // Allow some tolerance
+        });
+        it('should return a Promise', () => {
+            const result = delay(1);
+            expect(result).toBeInstanceOf(Promise);
+        });
+    });
+});

package/lib/api/RunApi.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A wrapped error for a fetch response.
+ */
+export declare class RunResponseError extends Error {
+    /**
+     * Create a RunResponseError from a response, handling the traceback and message
+     * as appropriate.
+     *
+     * @param response The response object.
+     *
+     * @returns A promise that resolves with a `RunResponseError` object.
+     */
+    static create(response: Response): Promise<RunResponseError>;
+    /**
+     * Create a new response error.
+     */
+    constructor(response: Response, message?: string, warnings?: undefined, errors?: undefined, exceptionMessage?: undefined, traceback?: string);
+    /**
+     * Warnings listed in the response.
+     */
+    readonly warnings: string[];
+    /**
+     * Errors listed in the response.
+     */
+    readonly errors: string[];
+    /**
+     * The response associated with the error.
+     */
+    readonly response: Response;
+    /**
+     * The exception associated with the error.
+     */
+    readonly exceptionMessage?: string;
+    /**
+     * The traceback associated with the error.
+     */
+    readonly traceback: string;
+    private static _defaultMessage;
+}
+/**
+ * A wrapped error for a network error.
+ */
+export declare class NetworkError extends TypeError {
+    /**
+     * Create a new network error.
+     */
+    constructor(original: TypeError);
+}
+export interface IRequestRunAPIOptions {
+    /**
+     * URL to request
+     */
+    url: string;
+    /**
+     * HTTP method
+     */
+    method?: string;
+    /**
+     * JSON-serializable object
+     */
+    body?: any;
+    /**
+     * Headers
+     */
+    headers?: Record<string, string>;
+    /**
+     * Authorization bearer token
+     */
+    token?: string;
+    /**
+     * Request abort signal.
+     */
+    signal?: AbortSignal;
+}
+export declare function requestRunAPI<T = any>({ url, method, body, token, signal, headers }: IRequestRunAPIOptions): Promise<T>;

package/lib/api/RunApi.js

@@ -0,0 +1,150 @@
+/*
+ * 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';
+/**
+ * A wrapped error for a fetch response.
+ */
+export class RunResponseError extends Error {
+    /**
+     * Create a RunResponseError from a response, handling the traceback and message
+     * as appropriate.
+     *
+     * @param response The response object.
+     *
+     * @returns A promise that resolves with a `RunResponseError` object.
+     */
+    static async create(response) {
+        try {
+            const data = await response.json();
+            const { message, errors, warnings, traceback, exception } = data;
+            if (traceback) {
+                console.error(traceback);
+            }
+            const responseError = new RunResponseError(response, message ?? RunResponseError._defaultMessage(response), warnings, errors, exception, traceback ?? '');
+            return responseError;
+        }
+        catch (e) {
+            console.debug(e);
+            return new RunResponseError(response);
+        }
+    }
+    /**
+     * Create a new response error.
+     */
+    constructor(response, message = RunResponseError._defaultMessage(response), warnings = undefined, errors = undefined, exceptionMessage = undefined, traceback = '') {
+        super(message);
+        this.name = 'RunResponseError';
+        this.warnings = warnings ?? [];
+        this.errors = errors ?? [];
+        this.response = response;
+        this.exceptionMessage = exceptionMessage;
+        this.traceback = traceback;
+    }
+    /**
+     * Warnings listed in the response.
+     */
+    warnings;
+    /**
+     * Errors listed in the response.
+     */
+    errors;
+    /**
+     * The response associated with the error.
+     */
+    response;
+    /**
+     * The exception associated with the error.
+     */
+    exceptionMessage;
+    /**
+     * The traceback associated with the error.
+     */
+    traceback;
+    static _defaultMessage(response) {
+        return `Invalid response: ${response.status} ${response.statusText}`;
+    }
+}
+/**
+ * A wrapped error for a network error.
+ */
+export class NetworkError extends TypeError {
+    /**
+     * Create a new network error.
+     */
+    constructor(original) {
+        super(original.message);
+        this.name = 'NetworkError';
+        this.stack = original.stack;
+    }
+}
+export async function requestRunAPI({ url, method, body, token, signal, headers = {} }) {
+    const headers_ = new Headers(headers);
+    if (!headers_.has('Accept')) {
+        headers_.set('Accept', 'application/json');
+    }
+    if (!headers_.has('Content-Type')) {
+        headers_.set('Content-Type', 'application/json');
+    }
+    if (token) {
+        headers_.set('Authorization', `Bearer ${token}`);
+    }
+    //  headers_.set('Origin', currentUri());
+    let response;
+    try {
+        response = await fetch(url, {
+            method: method ?? 'GET',
+            headers: headers_,
+            body: body ? JSON.stringify(body) : undefined,
+            //      credentials: token ? 'include' : 'omit',
+            credentials: 'include',
+            mode: 'cors',
+            cache: 'no-store',
+            signal
+        });
+    }
+    catch (error) {
+        throw new NetworkError(error);
+    }
+    if (response.ok) {
+        response = await wait_for_redirection(response, url, headers_);
+        const content = await response.text();
+        return (content ? JSON.parse(content) : null);
+    }
+    else {
+        throw await RunResponseError.create(response);
+    }
+}
+async function wait_for_redirection(response, url, headers_) {
+    let redirect = response.headers.get('Location');
+    if (redirect) {
+        const parsedURL = URLExt.parse(url);
+        const baseUrl = parsedURL.protocol + '//' + parsedURL.hostname;
+        if (!redirect.startsWith(baseUrl)) {
+            redirect = URLExt.join(baseUrl, redirect);
+        }
+    }
+    let sleepTimeout = 1000;
+    while (response.status === 202 && redirect) {
+        await sleep(sleepTimeout);
+        sleepTimeout *= 2;
+        response = await fetch(redirect, {
+            method: 'GET',
+            headers: headers_,
+            credentials: 'include',
+            mode: 'cors',
+            cache: 'no-store'
+        });
+        if (!response.ok) {
+            throw await RunResponseError.create(response);
+        }
+    }
+    return response;
+}

package/lib/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./runtimes";
+export * from "./RunApi";

package/lib/api/index.js

@@ -0,0 +1,11 @@
+/*
+ * 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 "./runtimes";
+export * from "./RunApi";

package/lib/api/runtimes/exec/Python.d.ts

@@ -0,0 +1,5 @@
+export declare function listVariables(): string;
+export declare function saveVariables(variables: string[]): string;
+export declare function loadVariables(variables: string): string;
+export declare function changeCurrentWorkingDirectory(path: string): string;
+export declare function getOutputCandidates(code: string): string[];