@pie-project/server 0.5.2 → 0.6.0

package/README.md

@@ -14,10 +14,10 @@ import '@pie-project/language-python';           // Python inferlets run; one li
 const server = await Server.start({
   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: { port: 0 } },               // the rest of `pie serve`'s config
+  config: { server: { listen: '127.0.0.1:0' } }, // the rest of `pie serve`'s config
 });
 
-await server.install(inferletBytes, manifestToml);   // an inferlet of your own, from bytes or a URL
+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());
@@ -27,11 +27,11 @@ await server.shutdown();
 `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.model` inside, as an object or TOML text,
+`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 Python twin is the `pie-server` wheel (`packages/python/server`).
 
 ## Installing
 
@@ -47,7 +47,7 @@ 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+);
-`javascript/server-web/README.md` has the details.
+`packages/javascript/server-web/README.md` has the details.
 
 Language components (`@pie-project/language-python`,
 `@pie-project/language-javascript`) register themselves on import; a
@@ -66,4 +66,4 @@ 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 browser bundle is
-`javascript/server-web/build.sh`.
+`packages/javascript/server-web/build.sh`.

package/index.d.ts

@@ -11,6 +11,8 @@ export interface StartOptions {
   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;
 }
@@ -30,8 +32,7 @@ export class Server {
   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>;
-  /** An inferlet from its component bytes (or URL) and manifest text, replacing an installed version; resolves to `name@version`. */
-  install(source: Uint8Array | ArrayBuffer | URL | string, manifest: 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,12 +12,13 @@
 // 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));
@@ -50,11 +51,24 @@ 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 = source instanceof URL ? source : new URL(String(source), 'file://');
+  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}`);
@@ -86,19 +100,21 @@ export class Server {
    * 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.model` inside — is accepted as well. `server.port = 0` asks the OS
+   * `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(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 ?? {}), model } };
+      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);
+    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);
@@ -126,10 +142,13 @@ export class Server {
     return handle.installLanguage(language, Buffer.from(await bytesOf(source)));
   }
 
-  /** An inferlet from its component bytes (or URL) and manifest text, replacing an installed version. Resolves to `name@version`. */
-  async install(source, manifest) {
+  async install(source, file = null, version = null) {
     const handle = this.#alive();
-    return handle.install(Buffer.from(await bytesOf(source)), manifest);
+    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()`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pie-project/server",
-  "version": "0.5.2",
+  "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",
@@ -39,20 +39,20 @@
     "win32"
   ],
   "dependencies": {
-    "@pie-project/client": "^0.5.0",
-    "@pie-project/server-web": "0.5.2",
-    "ws": "^8.18.0"
-  },
-  "optionalDependencies": {
-    "@pie-project/server-linux-x64": "0.5.2",
-    "@pie-project/server-linux-arm64": "0.5.2",
-    "@pie-project/server-darwin-arm64": "0.5.2",
-    "@pie-project/server-win32-x64": "0.5.2"
+    "@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"
   }
 }