@blaxel/core 0.2.6 → 0.2.7-preview.7

package/README.md

@@ -0,0 +1,116 @@
+# Blaxel Typescript SDK
+
+<p align="center">
+  <img src="https://blaxel.ai/logo.png" alt="Blaxel"/>
+</p>
+
+**Blaxel is a computing platform for AI agent builders, with all the services and infrastructure to build and deploy agents efficiently.** This repository contains the TypeScript SDK to create and manage resources on Blaxel.
+
+## Table of Contents
+
+- [Installation](#installation)
+  - [Optional libraries](#optional-libraries)
+  - [Authentication](#authentication)
+- [Features](#features)
+- [Quickstart](#quickstart)
+- [Contributing](#contributing)
+- [License](#license)
+
+
+
+## Installation
+
+Install Blaxel core SDK, which lets you manage Blaxel resources.
+
+```bash
+## npm
+npm install @blaxel/core
+
+## pnpm
+pnpm i @blaxel/core
+
+## yarn
+yarn add @blaxel/core
+```
+
+
+### Optional libraries
+Blaxel SDK is split between multiple packages. *core* is the minimal package to connect to Blaxel. You can find other packages to help you integrate with your favorite AI framework, or set up telemetry.
+
+- [@blaxel/telemetry](@blaxel/telemetry/README.md)
+- [@blaxel/vercel](@blaxel/vercel/README.md)
+- [@blaxel/llamaindex](@blaxel/llamaindex/README.md)
+- [@blaxel/langgraph](@blaxel/langgraph/README.md)
+- [@blaxel/mastra](@blaxel/mastra/README.md)
+
+Instrumentation happens automatically when workloads run on Blaxel. To enable telemetry, simply require the SDK in your project's entry point.
+```ts
+import "@blaxel/telemetry";
+```
+
+
+### Authentication
+
+The Blaxel SDK authenticates with your workspace using credentials from these sources, in priority order:
+1. When running on Blaxel, authentication is handled automatically
+2. Variables in your .env file (`BL_WORKSPACE` and `BL_API_KEY`, or see [this page](https://docs.blaxel.ai/Agents/Variables-and-secrets) for other authentication options).
+3. Environment variables from your machine
+4. Configuration file created locally when you log in through Blaxel CLI (or deploy on Blaxel)
+
+When developing locally, the recommended method is to just log in to your workspace with Blaxel CLI. This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, this connection persists automatically.
+
+When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recommend using environment variables as described in the third option above.
+
+
+
+## Features
+- Agents & MCP servers
+  - [Create MCP servers](https://docs.blaxel.ai/Functions/Create-MCP-server)
+  - [Connect to MCP servers and model APIs hosted on Blaxel](https://docs.blaxel.ai/Agents/Develop-an-agent-ts)
+  - [Call agents from another agent](https://docs.blaxel.ai/Agents/Develop-an-agent-ts#connect-to-another-agent-multi-agent-chaining)
+  - [Deploy on Blaxel](https://docs.blaxel.ai/Agents/Deploy-an-agent)
+- Sandboxes
+  - [Create and update sandboxes and sandbox previews](https://docs.blaxel.ai/Sandboxes/Overview)
+  - [Run filesystem operations and processes on a sandbox](https://docs.blaxel.ai/Sandboxes/Processes)
+- [Use environment variables or secrets](https://docs.blaxel.ai/Agents/Variables-and-secrets)
+
+
+
+## Quickstart
+
+Blaxel CLI gives you a quick way to create new applications: agents, MCP servers, jobs, etc - and deploy them to Blaxel.
+
+**Prerequisites**:
+- **Node.js:** v18 or later.
+- **Blaxel CLI:** Make sure you have Blaxel CLI installed. If not, [install it](https://docs.blaxel.ai/cli-reference/introduction):
+  ```bash
+  curl -fsSL \
+  https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
+  | BINDIR=/usr/local/bin sudo -E sh
+  ```
+- **Blaxel login:** Login to Blaxel:
+  ```bash
+    bl login YOUR-WORKSPACE
+  ```
+
+```bash
+bl create-agent-app myfolder
+cd myfolder
+bl deploy
+```
+
+Also available:
+-  `bl create-mcp-server`
+-  `bl create-job`
+
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/dist/authentication/clientcredentials.d.ts

@@ -9,6 +9,8 @@ export declare class ClientCredentials extends Credentials {
     get workspace(): string;
     needRefresh(): boolean;
     authenticate(): Promise<void>;
+    private sleep;
+    processWithRetry(retry?: number): Promise<void>;
     process(): Promise<void>;
     get authorization(): string;
     get token(): string;

package/dist/authentication/clientcredentials.js

@@ -42,9 +42,24 @@ class ClientCredentials extends credentials_js_1.Credentials {
         if (!this.needRefresh()) {
             return this.currentPromise || Promise.resolve();
         }
-        this.currentPromise = this.process();
+        this.currentPromise = this.processWithRetry();
         return this.currentPromise;
     }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async processWithRetry(retry = 3) {
+        try {
+            return await this.process();
+        }
+        catch (error) {
+            if (retry > 0) {
+                await this.sleep(1000);
+                return this.processWithRetry(retry - 1);
+            }
+            throw error;
+        }
+    }
     async process() {
         const response = await (0, authentication_js_1.oauthToken)({
             headers: {

package/dist/jobs/index.d.ts

@@ -1 +1,3 @@
 export * from "./jobs.js";
+export * from "./start.js";
+export * from "./types.js";

package/dist/jobs/index.js

@@ -15,3 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./jobs.js"), exports);
+__exportStar(require("./start.js"), exports);
+__exportStar(require("./types.js"), exports);

package/dist/jobs/jobs.d.ts

@@ -1,11 +1,13 @@
 declare class BlJob {
-    getArguments(): Promise<{
-        [key: number]: any;
-    }>;
-    private parseCommandLineArgs;
-    get indexKey(): string;
-    get index(): number;
-    start(func: (args: any) => Promise<void>): Promise<void>;
+    jobName: string;
+    constructor(jobName: string);
+    get fallbackUrl(): import("url").URL | null;
+    get externalUrl(): import("url").URL;
+    get internalUrl(): import("url").URL;
+    get forcedUrl(): import("url").URL | null;
+    get url(): import("url").URL;
+    call(url: URL, tasks: Record<string, unknown>[]): Promise<Response>;
+    run(tasks: Record<string, unknown>[]): Promise<string>;
 }
-export declare const blJob: BlJob;
+export declare const blJob: (jobName: string) => BlJob;
 export {};

package/dist/jobs/jobs.js

@@ -2,54 +2,94 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.blJob = void 0;
 const env_js_1 = require("../common/env.js");
+const internal_js_1 = require("../common/internal.js");
+const logger_js_1 = require("../common/logger.js");
+const settings_js_1 = require("../common/settings.js");
+const telemetry_js_1 = require("../telemetry/telemetry.js");
 class BlJob {
-    async getArguments() {
-        if (!env_js_1.env.BL_EXECUTION_DATA_URL) {
-            const args = this.parseCommandLineArgs();
-            return args;
+    jobName;
+    constructor(jobName) {
+        this.jobName = jobName;
+    }
+    get fallbackUrl() {
+        if (this.externalUrl != this.url) {
+            return this.externalUrl;
         }
-        const response = await fetch(env_js_1.env.BL_EXECUTION_DATA_URL);
-        const data = await response.json();
-        return data.tasks[this.index] ?? {};
-    }
-    parseCommandLineArgs() {
-        const args = process.argv.slice(2);
-        const result = {};
-        for (let i = 0; i < args.length; i++) {
-            const arg = args[i];
-            if (arg.startsWith('--')) {
-                const key = arg.slice(2);
-                const value = args[i + 1];
-                if (value && !value.startsWith('--')) {
-                    result[key] = value;
-                    i++;
-                }
-                else {
-                    result[key] = 'true';
-                }
-            }
+        return null;
+    }
+    get externalUrl() {
+        return new URL(`${settings_js_1.settings.runUrl}/${settings_js_1.settings.workspace}/jobs/${this.jobName}`);
+    }
+    get internalUrl() {
+        const hash = (0, internal_js_1.getGlobalUniqueHash)(settings_js_1.settings.workspace, "job", this.jobName);
+        return new URL(`${settings_js_1.settings.runInternalProtocol}://bl-${settings_js_1.settings.env}-${hash}.${settings_js_1.settings.runInternalHostname}`);
+    }
+    get forcedUrl() {
+        const envVar = this.jobName.replace(/-/g, "_").toUpperCase();
+        if (env_js_1.env[`BL_JOB_${envVar}_URL`]) {
+            return new URL(env_js_1.env[`BL_JOB_${envVar}_URL`]);
         }
-        return result;
+        return null;
     }
-    get indexKey() {
-        return env_js_1.env.BL_TASK_KEY ?? "TASK_INDEX";
+    get url() {
+        if (this.forcedUrl)
+            return this.forcedUrl;
+        if (settings_js_1.settings.runInternalHostname)
+            return this.internalUrl;
+        return this.externalUrl;
     }
-    get index() {
-        return env_js_1.env[this.indexKey] ? Number(env_js_1.env[this.indexKey]) ?? 0 : 0;
+    async call(url, tasks) {
+        let body = {
+            tasks: tasks
+        };
+        const response = await fetch(url + "/executions", {
+            method: "POST",
+            headers: {
+                ...settings_js_1.settings.headers,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        return response;
     }
-    /*
-      Run a job defined in a function, it's run in the current process
-    */
-    async start(func) {
+    async run(tasks) {
+        logger_js_1.logger.debug(`Job Calling: ${this.jobName}`);
+        const span = (0, telemetry_js_1.startSpan)(this.jobName, {
+            attributes: {
+                "job.name": this.jobName,
+                "span.type": "job.run",
+            },
+            isRoot: false,
+        });
         try {
-            const parsedArgs = await this.getArguments();
-            await func(parsedArgs);
-            process.exit(0);
+            const response = await this.call(this.url, tasks);
+            return await response.text();
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                if (!this.fallbackUrl) {
+                    span.setAttribute("job.run.error", err.stack);
+                    throw err;
+                }
+                try {
+                    const response = await this.call(this.fallbackUrl, tasks);
+                    return await response.text();
+                }
+                catch (err) {
+                    if (err instanceof Error) {
+                        span.setAttribute("job.run.error", err.stack);
+                    }
+                    throw err;
+                }
+            }
+            throw err;
         }
-        catch (error) {
-            console.error('Job execution failed:', error);
-            process.exit(1);
+        finally {
+            span.end();
         }
     }
 }
-exports.blJob = new BlJob();
+const blJob = (jobName) => {
+    return new BlJob(jobName);
+};
+exports.blJob = blJob;

package/dist/jobs/start.d.ts

@@ -0,0 +1 @@
+export declare const blStartJob: (func: (args: any) => Promise<void>) => void;

package/dist/jobs/start.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blStartJob = void 0;
+const autoload_js_1 = require("../common/autoload.js");
+const env_js_1 = require("../common/env.js");
+const telemetry_js_1 = require("../telemetry/telemetry.js");
+class BlJobWrapper {
+    async getArguments() {
+        if (!env_js_1.env.BL_EXECUTION_DATA_URL) {
+            const args = this.parseCommandLineArgs();
+            return args;
+        }
+        const response = await fetch(env_js_1.env.BL_EXECUTION_DATA_URL);
+        const data = await response.json();
+        return data.tasks[this.index] ?? {};
+    }
+    parseCommandLineArgs() {
+        const args = process.argv.slice(2);
+        const result = {};
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (arg.startsWith('--')) {
+                const key = arg.slice(2);
+                const value = args[i + 1];
+                if (value && !value.startsWith('--')) {
+                    result[key] = value;
+                    i++;
+                }
+                else {
+                    result[key] = 'true';
+                }
+            }
+        }
+        return result;
+    }
+    get indexKey() {
+        return env_js_1.env.BL_TASK_KEY ?? "TASK_INDEX";
+    }
+    get index() {
+        return env_js_1.env[this.indexKey] ? Number(env_js_1.env[this.indexKey]) ?? 0 : 0;
+    }
+    /*
+      Run a job defined in a function, it's run in the current process
+    */
+    async start(func) {
+        await (0, autoload_js_1.authenticate)();
+        let span = (0, telemetry_js_1.startSpan)(`blStartJob-${func.name}`, {
+            attributes: {
+                'job.name': func.name,
+                'job.index': this.index,
+                'job.args': JSON.stringify(this.getArguments()),
+            },
+            isRoot: true,
+        });
+        try {
+            const parsedArgs = await this.getArguments();
+            await func(parsedArgs);
+            span.setStatus('ok');
+            span.end();
+        }
+        catch (error) {
+            span.recordException(error);
+            span.setStatus('error', 'Job execution failed');
+            span.end();
+            throw error;
+        }
+    }
+}
+const blStartJob = (func) => {
+    const job = new BlJobWrapper();
+    job.start(func).then(async () => {
+        try {
+            await (0, telemetry_js_1.flush)();
+        }
+        catch (error) {
+            console.error('Error flushing telemetry:', error);
+        }
+    }).catch((error) => {
+        console.error('Job execution failed:', error);
+        process.exit(1);
+    });
+};
+exports.blStartJob = blStartJob;

package/dist/jobs/types.d.ts

@@ -0,0 +1,3 @@
+export type ExecutionArgs = {
+    [key: number]: any;
+}[];

package/dist/jobs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/telemetry/telemetry.d.ts

@@ -32,6 +32,8 @@ export interface BlaxelSpan {
 export interface BlaxelTelemetryProvider {
     /** Create a new span */
     startSpan(name: string, options?: BlaxelSpanOptions): BlaxelSpan;
+    /** Flush the telemetry provider */
+    flush(): Promise<void>;
 }
 /**
  * Registry for managing the global telemetry provider
@@ -55,5 +57,6 @@ export declare const telemetryRegistry: TelemetryRegistry;
  * Create a span with the registered provider
  */
 export declare function startSpan(name: string, options?: BlaxelSpanOptions): BlaxelSpan;
-export declare function withSpan<T>(name: string, fn: () => T, options?: BlaxelSpanOptions): T;
+export declare function withSpan<T>(name: string, fn: () => Promise<T>, options?: BlaxelSpanOptions): Promise<T>;
+export declare function flush(): Promise<void>;
 export {};

package/dist/telemetry/telemetry.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.telemetryRegistry = void 0;
 exports.startSpan = startSpan;
 exports.withSpan = withSpan;
+exports.flush = flush;
 /**
  * No-operation implementation of Span
  */
@@ -22,6 +23,9 @@ class NoopTelemetryProvider {
     startSpan() {
         return new NoopSpan();
     }
+    flush() {
+        return Promise.resolve();
+    }
 }
 /**
  * Registry for managing the global telemetry provider
@@ -58,10 +62,10 @@ exports.telemetryRegistry = TelemetryRegistry.getInstance();
 function startSpan(name, options) {
     return exports.telemetryRegistry.getProvider().startSpan(name, options);
 }
-function withSpan(name, fn, options) {
+async function withSpan(name, fn, options) {
     const span = startSpan(name, options);
     try {
-        const result = fn();
+        const result = await fn();
         span.end();
         return result;
     }
@@ -71,3 +75,6 @@ function withSpan(name, fn, options) {
         throw error;
     }
 }
+async function flush() {
+    await exports.telemetryRegistry.getProvider().flush();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blaxel/core",
-  "version": "0.2.6",
+  "version": "0.2.7-preview.7",
   "description": "Blaxel Core SDK for TypeScript",
   "license": "MIT",
   "author": "Blaxel, INC (https://blaxel.ai)",