@pie-project/server 0.5.1 → 0.6.0

package/README.md

@@ -1,39 +1,37 @@
 # @pie-project/server
 
 What `pie serve` boots (controller, gateway, worker, the built-in
-inferlets), inside your Node.js process on the native GPU engines. Clients
-connect as they would to a `pie serve`: over WebSocket with
-`@pie-project/client`, or over the OpenAI / Anthropic / Gemini HTTP routes.
+inferlets), inside your process. Under Node.js it runs on the native GPU
+engines; under a bundler, the same import is pie compiled for the browser,
+on WebGPU. Clients connect as they would to a `pie serve`: with
+`@pie-project/client` over the server's socket, or (Node) over the OpenAI /
+Anthropic / Gemini HTTP routes.
 
 ```js
 import { Server } from '@pie-project/server';
+import '@pie-project/language-python';           // Python inferlets run; one line per language
 
 const server = await Server.start({
-  server: { port: 0 },                         // 0: a free port; see server.url
-  model: { model: 'Qwen/Qwen3.5-0.8B' },       // what `pie model import` fetched
+  model: 'Qwen/Qwen3.5-0.8B',                    // Node: what `pie model import` fetched
+  // model: '/models/qwen3.5-0.8b.wgpu.zt',      // browser: the artifact's URL, served with Range support
+  config: { server: { listen: '127.0.0.1:0' } }, // the rest of `pie serve`'s config
 });
 
-const client = await server.connect();          // a PieClient over ws
+await server.install('./beam_search.wasm');           // an inferlet of your own: a path or URL, or bytes with a file name
+const client = await server.connect();               // a PieClient
 const process = await client.launchProcess('text-completion', { prompt: 'Hello' });
 console.log(await process.result());
-
-const reply = await fetch(server.httpUrl + '/v1/chat/completions', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ messages: [{ role: 'user', content: 'Hi' }] }),
-});
-console.log((await reply.json()).choices[0].message.content);
-
 await server.shutdown();
 ```
 
-`Server.start` takes the config `pie serve --config` reads (what `pie config
-init` writes), as an object or as TOML text, and resolves once the model is
-loaded and the listener is bound. A handle garbage-collected without
-`shutdown()` still stops the engine, on a background thread.
+`Server.start` resolves once the model is loaded and the server is
+listening, with every registered language component installed; `config` is
+the file `pie serve --config` reads, minus the model, as an object. A bare
+`Server.start(config)` with `model.source` inside, as an object or TOML text,
+is accepted too. Under Node, `server.httpUrl` is where the HTTP routes live.
+A handle garbage-collected without `shutdown()` still stops the engine.
 
-The Python twin is the `pie-server` wheel (`python/server`); the browser
-build of pie is `javascript/browser`.
+The Python twin is the `pie-server` wheel (`packages/python/server`).
 
 ## Installing
 
@@ -41,16 +39,24 @@ build of pie is `javascript/browser`.
 npm install @pie-project/server
 ```
 
-The addon comes as an optional dependency per platform
-(`@pie-project/server-linux-x64`, `-linux-arm64`, `-darwin-arm64`,
+Under Node the engine is a native addon, one optional dependency per
+platform (`@pie-project/server-linux-x64`, `-linux-arm64`, `-darwin-arm64`,
 `-win32-x64`), each carrying every engine that platform supports (Linux:
-CUDA, Vulkan, wgpu; macOS: Metal, wgpu; Windows: CUDA, Vulkan); the config's
-`engine.type` picks one at boot.
+CUDA, Vulkan, wgpu; macOS: Metal, wgpu; Windows: CUDA, Vulkan); the
+config's `engine.type` picks one at boot. Under a bundler (Vite, webpack 5)
+the `browser` export condition resolves to `@pie-project/server-web`: the
+runtime and the WebGPU engine as wasm, run in a Web Worker. The page must be
+cross-origin isolated and the browser needs WebGPU and JSPI (Chrome 137+);
+`packages/javascript/server-web/README.md` has the details.
+
+Language components (`@pie-project/language-python`,
+`@pie-project/language-javascript`) register themselves on import; a
+registration after `start()` lands on the running server too.
 
 ## Building
 
-From source, the addon is built from this directory with the engine features
-for your GPU (`cuda` by default, `metal` on macOS):
+From source, the Node addon is built from this directory with the engine
+features for your GPU (`cuda` by default, `metal` on macOS):
 
 ```bash
 npm run build                      # release, default features
@@ -59,4 +65,5 @@ bash build.sh dev --no-default-features   # no engine: loads, refuses to serve
 ```
 
 It lands beside `index.mjs` as `pie-server.<platform>-<arch>.node`, which
-the loader prefers over the platform package.
+the loader prefers over the platform package. The browser bundle is
+`packages/javascript/server-web/build.sh`.

package/index.d.ts

@@ -3,19 +3,36 @@ import type { PieClient } from '@pie-project/client';
 /** The native addon file this platform loads, or null when none is built. */
 export function addonPath(): string | null;
 
-/** A running pie engine in this process. */
+/** `pie serve`'s config: the file's shape, as an object or TOML text. */
+export type Config = string | Record<string, unknown>;
+
+export interface StartOptions {
+  /** What to serve: a Hugging Face repo, a path, an imported artifact's name. In the browser: the artifact's URL. */
+  model: string;
+  /** The rest of the config (server, engine, sandbox, …), as an object; TOML text is accepted for a bare `start(config)`. */
+  config?: Record<string, unknown> | string;
+  /** Node: where the runtime keeps its files (installed inferlets, languages, caches, models); `$PIE_HOME`, else `~/.pie`. */
+  home?: string;
+  /** Browser only: download progress of a lazy boot. */
+  onProgress?: (served: number, total: number, from: 'network' | 'cache') => void;
+}
+
+/** A running pie engine in this process. The same class serves in Node (native engines) and in the browser (WebGPU). */
 export class Server {
   /**
-   * Boot the engine from the TOML text `pie serve --config` reads, or an
-   * object of the same shape. Resolves once the engine is serving.
+   * Boot the engine; resolves once it is serving, with every registered
+   * language component (`import "@pie-project/language-python"`) installed.
    */
-  static start(config: string | Record<string, unknown>): Promise<Server>;
-  /** `ws://host:port` the engine listens on. */
+  static start(options: StartOptions | Config): Promise<Server>;
+  /** `ws://host:port` the engine listens on; `pie://local` in the browser. */
   readonly url: string;
-  /** `http://host:port`, where the OpenAI / Anthropic / Gemini routes live. */
-  readonly httpUrl: string;
+  /** Node: `http://host:port`, where the OpenAI / Anthropic / Gemini routes live. */
+  readonly httpUrl?: string;
   /** True until `shutdown()` resolves. */
   readonly running: boolean;
+  /** A language component (`python`, `javascript`) from bytes or a URL. */
+  installLanguage(language: 'python' | 'javascript' | string, source: Uint8Array | ArrayBuffer | URL | string): Promise<string>;
+  install(source: Uint8Array | ArrayBuffer | URL | string, file?: string | null, version?: string | null): Promise<string>;
   /** A `PieClient` connected to this engine; closed by `shutdown()`. */
   connect(options?: { identity?: string }): Promise<PieClient>;
   /** Stop the engine and release it. Idempotent. */

package/index.mjs

@@ -1,7 +1,7 @@
 // `@pie-project/server`: what `pie serve` boots, inside a Node process.
 //
 //   import { Server } from '@pie-project/server';
-//   const server = await Server.start({ server: { port: 0 }, model: { model: 'Qwen/Qwen3.5-0.8B' } });
+//   const server = await Server.start({ server: { listen: '127.0.0.1:0' }, model: { source: 'Qwen/Qwen3.5-0.8B' } });
 //   const client = await server.connect();
 //   ...
 //   await server.shutdown();
@@ -12,11 +12,14 @@
 // dependency; this wrapper loads it and adds `connect()`.
 
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import WebSocket from 'ws';
-import { PieClient } from '@pie-project/client';
+import { PieClient, programFile } from '@pie-project/client';
+import { attachLanguages } from '@pie-project/server-web/languages';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -48,25 +51,74 @@ function load() {
   return native;
 }
 
+function isBytes(source) {
+  return source instanceof Uint8Array || source instanceof ArrayBuffer;
+}
+
+function urlOf(source) {
+  if (source instanceof URL) return source;
+  try {
+    return new URL(String(source));
+  } catch {
+    return pathToFileURL(String(source));
+  }
+}
+
+/** Bytes from what `install*` accept: bytes, or a file/http URL to read. */
+async function bytesOf(source) {
+  if (source instanceof Uint8Array) return source;
+  if (source instanceof ArrayBuffer) return new Uint8Array(source);
+  const url = urlOf(source);
+  if (url.protocol === 'file:') return new Uint8Array(await readFile(fileURLToPath(url)));
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`${url}: ${response.status} ${response.statusText}`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+/** Under Node a language package that is installed need not be imported by hand: importing it here registers it. */
+async function importInstalledLanguages() {
+  for (const language of ['python', 'javascript']) {
+    try {
+      await import(`@pie-project/language-${language}`);
+    } catch (error) {
+      if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+    }
+  }
+}
+
 /** A running pie engine in this process. */
 export class Server {
   #handle;
   #clients = [];
+  #detach = null;
 
   constructor(handle) {
     this.#handle = handle;
   }
 
   /**
-   * Boot the engine from the TOML text `pie serve --config` reads, or an
-   * object of the same shape (`{server: {port: 0}, model: {…}}`).
-   * `server.port = 0` asks the OS for a free port; `url` says which.
-   * Resolves once the engine is serving — minutes for a large model.
+   * Boot the engine. `{ model, config }` names the model (`Qwen/Qwen3.5-0.8B`,
+   * a path, an artifact) and gives the rest of `pie serve`'s config as an
+   * object; a bare config — TOML text, or an object of the file's shape with
+   * `model.source` inside — is accepted as well. `server.listen` at port 0 asks the OS
+   * for a free port; `url` says which. Resolves once the engine is serving,
+   * with every registered language component installed.
    */
-  static async start(config) {
+  static async start(options) {
+    let config = options;
+    let home = process.env.PIE_HOME?.trim() || join(homedir(), '.pie');
+    if (options && typeof options === 'object' && typeof options.model === 'string') {
+      const { model, config: rest = {} } = options;
+      if (typeof rest !== 'object') throw new Error('Server.start: with `model`, `config` is an object');
+      config = { ...rest, model: { name: 'default', ...(rest.model ?? {}), source: model } };
+      home = options.home ?? home;
+    }
     const api = load();
-    const handle = typeof config === 'string' ? await api.startToml(config) : await api.start(config);
-    return new Server(handle);
+    const handle = typeof config === 'string' ? await api.startToml(config, home) : await api.start(config, home);
+    const server = new Server(handle);
+    await importInstalledLanguages();
+    server.#detach = await attachLanguages(server);
+    return server;
   }
 
   /** `ws://host:port` the engine listens on. */
@@ -84,10 +136,24 @@ export class Server {
     return this.#handle.running;
   }
 
+  /** A language component (`python`, `javascript`) from bytes or a URL; a script inferlet in that language runs once this resolves. */
+  async installLanguage(language, source) {
+    const handle = this.#alive();
+    return handle.installLanguage(language, Buffer.from(await bytesOf(source)));
+  }
+
+  async install(source, file = null, version = null) {
+    const handle = this.#alive();
+    if (!file) {
+      if (isBytes(source)) throw new Error('Server.install: bytes need `file`, the program\'s file name (`x.wasm`, `x.py`, `x.js`)');
+      file = programFile(urlOf(source));
+    }
+    return handle.install(Buffer.from(await bytesOf(source)), file, version ?? undefined);
+  }
+
   /** A `PieClient` connected to this engine (over Node's `ws`, which can send the identity header). Closed by `shutdown()`. */
   async connect({ identity = 'default/node' } = {}) {
-    if (!this.running) throw new Error('the server is shut down');
-    const client = new PieClient(this.url, { WebSocket, identity });
+    const client = new PieClient(this.#alive().url, { WebSocket, identity });
     await client.connect();
     this.#clients.push(client);
     return client;
@@ -95,6 +161,8 @@ export class Server {
 
   /** Close the clients from `connect()`, then stop the engine. Idempotent. */
   async shutdown() {
+    this.#detach?.();
+    this.#detach = null;
     for (const client of this.#clients.splice(0)) {
       try {
         await client.close();
@@ -104,4 +172,9 @@ export class Server {
     }
     await this.#handle.shutdown();
   }
+
+  #alive() {
+    if (!this.running) throw new Error('the server is shut down');
+    return this.#handle;
+  }
 }

package/languages.d.ts

@@ -0,0 +1 @@
+export * from '@pie-project/server-web/languages';

package/languages.mjs

@@ -0,0 +1,3 @@
+// `import { registerLanguage } from "@pie-project/server/languages"`: what a
+// language package calls on import.
+export * from '@pie-project/server-web/languages';

package/package.json

@@ -1,19 +1,28 @@
 {
   "name": "@pie-project/server",
-  "version": "0.5.1",
-  "description": "What `pie serve` boots, inside a Node.js process, on the native GPU engines.",
+  "version": "0.6.0",
+  "description": "What `pie serve` boots, inside your process: on the native GPU engines under Node.js, on WebGPU under a bundler for the browser.",
   "type": "module",
   "main": "index.mjs",
   "types": "index.d.ts",
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.mjs"
+      "browser": "./web.mjs",
+      "node": "./index.mjs",
+      "default": "./index.mjs"
+    },
+    "./languages": {
+      "types": "./languages.d.ts",
+      "default": "./languages.mjs"
     }
   },
   "files": [
     "index.mjs",
     "index.d.ts",
+    "web.mjs",
+    "languages.mjs",
+    "languages.d.ts",
     "README.md"
   ],
   "scripts": {
@@ -30,19 +39,20 @@
     "win32"
   ],
   "dependencies": {
-    "@pie-project/client": "^0.5.0",
-    "ws": "^8.18.0"
-  },
-  "optionalDependencies": {
-    "@pie-project/server-linux-x64": "0.5.1",
-    "@pie-project/server-linux-arm64": "0.5.1",
-    "@pie-project/server-darwin-arm64": "0.5.1",
-    "@pie-project/server-win32-x64": "0.5.1"
+    "@pie-project/client": "^0.6.0",
+    "@pie-project/server-web": "0.6.0",
+    "ws": "^8.22.0"
   },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pie-project/pie",
-    "directory": "javascript/server"
+    "directory": "packages/javascript/server"
+  },
+  "optionalDependencies": {
+    "@pie-project/server-darwin-arm64": "0.6.0",
+    "@pie-project/server-linux-arm64": "0.6.0",
+    "@pie-project/server-linux-x64": "0.6.0",
+    "@pie-project/server-win32-x64": "0.6.0"
   }
 }

package/web.mjs

@@ -0,0 +1,3 @@
+// The browser half: what a bundler resolves `@pie-project/server` to under
+// its `browser` condition.
+export * from '@pie-project/server-web';