@infernetprotocol/training 0.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,15 @@
1
+ ISC License
2
+
3
+ Copyright (c) 2025 Infernet Protocol
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
12
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
14
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15
+ PERFORMANCE OF THIS SOFTWARE.
package/package.json ADDED
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "@infernetprotocol/training",
3
+ "version": "0.1.22",
4
+ "description": "Training orchestration for Infernet — pluggable backends (DeepSpeed/FSDP for trusted clusters, OpenDiLoCo for cross-provider async, Petals for trustless P2P fine-tunes) over a stable async-iterator API.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./src/index.js",
8
+ "exports": {
9
+ ".": "./src/index.js",
10
+ "./protocol": "./src/protocol.js"
11
+ },
12
+ "files": [
13
+ "src/**/*.js",
14
+ "README.md"
15
+ ],
16
+ "engines": {
17
+ "node": ">=18"
18
+ },
19
+ "dependencies": {
20
+ "@infernetprotocol/engine": "0.1.22"
21
+ },
22
+ "repository": {
23
+ "type": "git",
24
+ "url": "git+https://github.com/profullstack/infernet-protocol.git",
25
+ "directory": "packages/training"
26
+ },
27
+ "homepage": "https://github.com/profullstack/infernet-protocol#readme"
28
+ }
@@ -0,0 +1,67 @@
1
+ /**
2
+ * DeepSpeed backend — trusted-cluster sharded training.
3
+ *
4
+ * Pattern: a single provider with multiple GPUs (or multiple machines on
5
+ * fast LAN) runs the actual training. We spawn `deepspeed` (or
6
+ * `torchrun`) with the operator's hostfile + the job's config, parse its
7
+ * stdout for step/loss/lr signals, and translate into our v1 protocol
8
+ * events.
9
+ *
10
+ * This is the right tool for Class B training jobs (one provider's
11
+ * cluster) — fine-tunes, LoRA, full pretraining when the operator owns
12
+ * enough hardware. Not for Class C cross-provider training; for that
13
+ * see opendiloco.js.
14
+ *
15
+ * Status: placeholder — emits a not_implemented done so the surface
16
+ * exists and downstream callers can wire against the protocol. Real
17
+ * integration: spawn the deepspeed/torchrun launcher under
18
+ * EngineProcess, parse its log lines (loss / lr / step / throughput).
19
+ *
20
+ * https://github.com/deepspeedai/DeepSpeed
21
+ */
22
+
23
+ import { randomUUID } from "node:crypto";
24
+ import { AsyncQueue } from "@infernetprotocol/engine";
25
+ import { TMSG, TRAINING_PROTOCOL_VERSION } from "../protocol.js";
26
+
27
+ export function createDeepspeedBackend({
28
+ hostfile = process.env.DEEPSPEED_HOSTFILE ?? null,
29
+ masterAddr = process.env.MASTER_ADDR ?? "127.0.0.1",
30
+ masterPort = process.env.MASTER_PORT ?? "29500"
31
+ } = {}) {
32
+ return {
33
+ kind: "deepspeed",
34
+ hostfile,
35
+ masterAddr,
36
+ start({ config = {}, id } = {}) {
37
+ const jobId = id ?? randomUUID();
38
+ const stream = new AsyncQueue();
39
+ const ctrl = new AbortController();
40
+
41
+ (async () => {
42
+ stream.push({
43
+ v: TRAINING_PROTOCOL_VERSION,
44
+ type: TMSG.META,
45
+ id: jobId,
46
+ backend: "deepspeed",
47
+ started_at: new Date().toISOString(),
48
+ base_model: config.base_model ?? null,
49
+ kind: config.kind ?? "fine-tune",
50
+ cluster: { hostfile, master_addr: masterAddr, master_port: masterPort }
51
+ });
52
+ stream.push({
53
+ v: TRAINING_PROTOCOL_VERSION,
54
+ type: TMSG.DONE,
55
+ id: jobId,
56
+ reason: "not_implemented",
57
+ finished_at: new Date().toISOString(),
58
+ note: "DeepSpeed launcher integration pending. Will spawn `deepspeed --hostfile=$HOSTFILE` with the job's config and stream stdout into step/eval/checkpoint events."
59
+ });
60
+ stream.end();
61
+ })();
62
+
63
+ return { id: jobId, stream, cancel: () => ctrl.abort() };
64
+ },
65
+ async shutdown() {}
66
+ };
67
+ }
@@ -0,0 +1,64 @@
1
+ /**
2
+ * OpenDiLoCo backend — cross-provider async training.
3
+ *
4
+ * Pattern: workers train independently for N local steps, then exchange
5
+ * model deltas (not per-batch gradients) over the public internet. The
6
+ * key insight is that infrequent, large updates survive WAN latency in a
7
+ * way that synchronous all-reduce gradients cannot. From Google's DiLoCo
8
+ * paper, implemented by Prime Intellect for the INTELLECT-1/2 runs
9
+ * (~10B param training across volunteer GPUs).
10
+ *
11
+ * This is the right tool for Class C training jobs — distributed across
12
+ * providers we don't control, with realistic public-internet links.
13
+ *
14
+ * Status: placeholder. Real integration: spawn a Python worker that
15
+ * connects to the swarm coordinator, parse its training log into v1
16
+ * protocol events. Coordinator address comes from the job config.
17
+ *
18
+ * https://github.com/PrimeIntellect-ai/OpenDiloCo
19
+ */
20
+
21
+ import { randomUUID } from "node:crypto";
22
+ import { AsyncQueue } from "@infernetprotocol/engine";
23
+ import { TMSG, TRAINING_PROTOCOL_VERSION } from "../protocol.js";
24
+
25
+ export function createOpenDiLoCoBackend({
26
+ coordinator = process.env.OPENDILOCO_COORDINATOR ?? null,
27
+ localSteps = Number.parseInt(process.env.OPENDILOCO_LOCAL_STEPS ?? "500", 10) || 500
28
+ } = {}) {
29
+ return {
30
+ kind: "opendiloco",
31
+ coordinator,
32
+ localSteps,
33
+ start({ config = {}, id } = {}) {
34
+ const jobId = id ?? randomUUID();
35
+ const stream = new AsyncQueue();
36
+ const ctrl = new AbortController();
37
+
38
+ (async () => {
39
+ stream.push({
40
+ v: TRAINING_PROTOCOL_VERSION,
41
+ type: TMSG.META,
42
+ id: jobId,
43
+ backend: "opendiloco",
44
+ started_at: new Date().toISOString(),
45
+ base_model: config.base_model ?? null,
46
+ kind: config.kind ?? "pretrain",
47
+ swarm: { coordinator, local_steps: localSteps }
48
+ });
49
+ stream.push({
50
+ v: TRAINING_PROTOCOL_VERSION,
51
+ type: TMSG.DONE,
52
+ id: jobId,
53
+ reason: "not_implemented",
54
+ finished_at: new Date().toISOString(),
55
+ note: "OpenDiLoCo worker integration pending. Will spawn a Python worker that joins the swarm at $COORDINATOR, trains $LOCAL_STEPS steps locally, syncs deltas, repeats."
56
+ });
57
+ stream.end();
58
+ })();
59
+
60
+ return { id: jobId, stream, cancel: () => ctrl.abort() };
61
+ },
62
+ async shutdown() {}
63
+ };
64
+ }
@@ -0,0 +1,71 @@
1
+ /**
2
+ * OpenRLHF backend — RLHF training with vLLM rollouts + DeepSpeed updates.
3
+ *
4
+ * Pattern: classic actor-critic RLHF where vLLM workers do fast generation
5
+ * (rollouts) and DeepSpeed/FSDP workers do the gradient updates. Ray
6
+ * coordinates the pipeline. This is the natural pair to our existing
7
+ * vLLM engine adapter — same operator, same hardware, just driven by an
8
+ * RL training loop instead of a chat request.
9
+ *
10
+ * Lands as Class C-light: trusted-cluster training with vLLM in the loop.
11
+ * The cross-provider variant would compose OpenRLHF's gradient layer with
12
+ * OpenDiLoCo's WAN-tolerant delta exchange — out of scope for v1.
13
+ *
14
+ * Status: placeholder. Real integration: spawn `openrlhf train_xxx.py`
15
+ * with a Ray cluster URL and the job's reward model + dataset config,
16
+ * parse training log into v1 protocol events.
17
+ *
18
+ * https://github.com/OpenRLHF/OpenRLHF
19
+ */
20
+
21
+ import { randomUUID } from "node:crypto";
22
+ import { AsyncQueue } from "@infernetprotocol/engine";
23
+ import { TMSG, TRAINING_PROTOCOL_VERSION } from "../protocol.js";
24
+
25
+ export function createOpenRLHFBackend({
26
+ rayAddress = process.env.RAY_ADDRESS ?? "auto",
27
+ vllmHost = process.env.VLLM_HOST ?? "http://localhost:8000",
28
+ rolloutWorldSize = Number.parseInt(process.env.OPENRLHF_ROLLOUT_WORLD ?? "1", 10) || 1,
29
+ actorWorldSize = Number.parseInt(process.env.OPENRLHF_ACTOR_WORLD ?? "1", 10) || 1
30
+ } = {}) {
31
+ return {
32
+ kind: "openrlhf",
33
+ rayAddress,
34
+ vllmHost,
35
+ start({ config = {}, id } = {}) {
36
+ const jobId = id ?? randomUUID();
37
+ const stream = new AsyncQueue();
38
+ const ctrl = new AbortController();
39
+
40
+ (async () => {
41
+ stream.push({
42
+ v: TRAINING_PROTOCOL_VERSION,
43
+ type: TMSG.META,
44
+ id: jobId,
45
+ backend: "openrlhf",
46
+ started_at: new Date().toISOString(),
47
+ base_model: config.base_model ?? null,
48
+ kind: config.kind ?? "rlhf-rollout",
49
+ cluster: {
50
+ ray_address: rayAddress,
51
+ vllm_host: vllmHost,
52
+ rollout_world_size: rolloutWorldSize,
53
+ actor_world_size: actorWorldSize
54
+ }
55
+ });
56
+ stream.push({
57
+ v: TRAINING_PROTOCOL_VERSION,
58
+ type: TMSG.DONE,
59
+ id: jobId,
60
+ reason: "not_implemented",
61
+ finished_at: new Date().toISOString(),
62
+ note: "OpenRLHF integration pending. Will join Ray cluster $RAY_ADDRESS, drive $ROLLOUT_WORLD vLLM workers at $VLLM_HOST for generation, $ACTOR_WORLD DeepSpeed workers for updates."
63
+ });
64
+ stream.end();
65
+ })();
66
+
67
+ return { id: jobId, stream, cancel: () => ctrl.abort() };
68
+ },
69
+ async shutdown() {}
70
+ };
71
+ }
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Petals backend — trustless P2P inference + fine-tuning of large LLMs.
3
+ *
4
+ * Pattern: pipeline-parallel sharding across volunteer GPUs over the
5
+ * public internet. Each peer holds N transformer layers; inference is
6
+ * a chain of forward-pass calls between peers. Fine-tuning works the
7
+ * same way (gradients propagate backwards through the chain).
8
+ *
9
+ * Closest existing FOSS to "trustless P2P training" — built by the
10
+ * BigScience/HuggingFace team, MIT-licensed, demonstrated up to ~176B
11
+ * params (BLOOM). Latency makes it batch-only for inference; training
12
+ * works in long-running async jobs.
13
+ *
14
+ * Status: placeholder. Real integration: spawn a Python worker that
15
+ * joins the public swarm (or a private one), advertises which layers
16
+ * it holds, accepts forward/backward calls.
17
+ *
18
+ * https://github.com/bigscience-workshop/petals
19
+ */
20
+
21
+ import { randomUUID } from "node:crypto";
22
+ import { AsyncQueue } from "@infernetprotocol/engine";
23
+ import { TMSG, TRAINING_PROTOCOL_VERSION } from "../protocol.js";
24
+
25
+ export function createPetalsBackend({
26
+ swarm = process.env.PETALS_SWARM ?? "public",
27
+ initialPeers = process.env.PETALS_INITIAL_PEERS ?? null
28
+ } = {}) {
29
+ return {
30
+ kind: "petals",
31
+ swarm,
32
+ initialPeers,
33
+ start({ config = {}, id } = {}) {
34
+ const jobId = id ?? randomUUID();
35
+ const stream = new AsyncQueue();
36
+ const ctrl = new AbortController();
37
+
38
+ (async () => {
39
+ stream.push({
40
+ v: TRAINING_PROTOCOL_VERSION,
41
+ type: TMSG.META,
42
+ id: jobId,
43
+ backend: "petals",
44
+ started_at: new Date().toISOString(),
45
+ base_model: config.base_model ?? null,
46
+ kind: config.kind ?? "lora",
47
+ swarm: { name: swarm, initial_peers: initialPeers }
48
+ });
49
+ stream.push({
50
+ v: TRAINING_PROTOCOL_VERSION,
51
+ type: TMSG.DONE,
52
+ id: jobId,
53
+ reason: "not_implemented",
54
+ finished_at: new Date().toISOString(),
55
+ note: "Petals worker integration pending. Will join swarm '$SWARM' (initial peers $PETALS_INITIAL_PEERS), advertise locally-held layers of $BASE_MODEL, accept forward/backward passes."
56
+ });
57
+ stream.end();
58
+ })();
59
+
60
+ return { id: jobId, stream, cancel: () => ctrl.abort() };
61
+ },
62
+ async shutdown() {}
63
+ };
64
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Stub trainer — emits a synthetic training run in-process.
3
+ *
4
+ * Lets the rest of the system (job queue, event sink, dashboard) be
5
+ * exercised end-to-end without a real PyTorch / DeepSpeed / Petals
6
+ * runtime. Real backends slot in behind the same interface.
7
+ */
8
+
9
+ import { randomUUID } from "node:crypto";
10
+ import { AsyncQueue } from "@infernetprotocol/engine";
11
+ import { TMSG, TRAINING_PROTOCOL_VERSION } from "../protocol.js";
12
+
13
+ export function createStubTrainer({ steps = 8, stepDelayMs = 25 } = {}) {
14
+ return {
15
+ kind: "stub",
16
+ start({ config = {}, id } = {}) {
17
+ const jobId = id ?? randomUUID();
18
+ const stream = new AsyncQueue();
19
+ const ctrl = new AbortController();
20
+
21
+ (async () => {
22
+ stream.push({
23
+ v: TRAINING_PROTOCOL_VERSION,
24
+ type: TMSG.META,
25
+ id: jobId,
26
+ started_at: new Date().toISOString(),
27
+ backend: "stub",
28
+ world_size: 1,
29
+ base_model: config.base_model ?? null,
30
+ kind: config.kind ?? "fine-tune"
31
+ });
32
+
33
+ for (let s = 1; s <= steps; s += 1) {
34
+ if (ctrl.signal.aborted) break;
35
+ await sleep(stepDelayMs, ctrl.signal);
36
+ stream.push({
37
+ v: TRAINING_PROTOCOL_VERSION,
38
+ type: TMSG.STEP,
39
+ id: jobId,
40
+ step: s,
41
+ loss: Math.exp(-s / 4) + 0.1,
42
+ lr: 1e-4,
43
+ throughput: 1024
44
+ });
45
+ }
46
+
47
+ stream.push({
48
+ v: TRAINING_PROTOCOL_VERSION,
49
+ type: TMSG.DONE,
50
+ id: jobId,
51
+ reason: ctrl.signal.aborted ? "cancel" : "complete",
52
+ final_step: steps,
53
+ finished_at: new Date().toISOString()
54
+ });
55
+ stream.end();
56
+ })();
57
+
58
+ return { id: jobId, stream, cancel: () => ctrl.abort() };
59
+ },
60
+ async shutdown() {}
61
+ };
62
+ }
63
+
64
+ function sleep(ms, signal) {
65
+ return new Promise((resolve) => {
66
+ const t = setTimeout(resolve, ms);
67
+ if (signal) {
68
+ signal.addEventListener("abort", () => {
69
+ clearTimeout(t);
70
+ resolve();
71
+ }, { once: true });
72
+ }
73
+ });
74
+ }
package/src/index.js ADDED
@@ -0,0 +1,57 @@
1
+ /**
2
+ * @infernetprotocol/training — pluggable training orchestration.
3
+ *
4
+ * const trainer = await createTrainer(); // auto-selects
5
+ * const { stream } = trainer.start({ config });
6
+ * for await (const ev of stream) {
7
+ * // ev.type ∈ "meta" | "step" | "checkpoint" | "eval" | "done" | "error"
8
+ * }
9
+ * await trainer.shutdown();
10
+ *
11
+ * Backends (each is a placeholder until the underlying runtime is wired in):
12
+ * - "deepspeed" — trusted-cluster sharded training (DeepSpeed/torchrun).
13
+ * Class B: one provider's hardware.
14
+ * - "openrlhf" — RLHF with vLLM rollouts + DeepSpeed updates.
15
+ * Class B-RLHF: trusted cluster, leverages our vLLM engine.
16
+ * - "opendiloco" — cross-provider async training (Prime Intellect's
17
+ * OpenDiLoCo). Class C: WAN-tolerant delta exchange.
18
+ * - "petals" — pipeline-parallel sharding for fine-tunes across
19
+ * volunteer GPUs. Class C-LLM: BigScience's Petals.
20
+ * - "stub" — synthetic training run, no GPU required. Default.
21
+ *
22
+ * Auto-selection precedence (only if `opts.backend` is not set):
23
+ * 1. process.env.INFERNET_TRAINING_BACKEND — explicit
24
+ * 2. "stub" — until real runtime detection lands
25
+ */
26
+
27
+ import { createDeepspeedBackend } from "./backends/deepspeed.js";
28
+ import { createOpenDiLoCoBackend } from "./backends/opendiloco.js";
29
+ import { createOpenRLHFBackend } from "./backends/openrlhf.js";
30
+ import { createPetalsBackend } from "./backends/petals.js";
31
+ import { createStubTrainer } from "./backends/stub.js";
32
+
33
+ export * from "./protocol.js";
34
+
35
+ export async function createTrainer(opts = {}) {
36
+ const backend = opts.backend ?? autoSelectBackend();
37
+ switch (backend) {
38
+ case "deepspeed":
39
+ return createDeepspeedBackend(opts);
40
+ case "openrlhf":
41
+ return createOpenRLHFBackend(opts);
42
+ case "opendiloco":
43
+ return createOpenDiLoCoBackend(opts);
44
+ case "petals":
45
+ return createPetalsBackend(opts);
46
+ case "stub":
47
+ return createStubTrainer(opts);
48
+ default:
49
+ throw new Error(`unknown training backend: ${backend}`);
50
+ }
51
+ }
52
+
53
+ function autoSelectBackend() {
54
+ const explicit = process.env.INFERNET_TRAINING_BACKEND;
55
+ if (explicit) return explicit;
56
+ return "stub";
57
+ }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Training IPC protocol — v1.
3
+ *
4
+ * Mirrors @infernetprotocol/engine/protocol but for training jobs. NDJSON
5
+ * over stdio between the JS sidecar and a Python training runner (DeepSpeed
6
+ * launcher, OpenDiLoCo worker, Petals client, etc.).
7
+ *
8
+ * Outbound (JS → trainer):
9
+ * { v:1, type:"start", id, config }
10
+ * { v:1, type:"cancel", id }
11
+ * { v:1, type:"shutdown" }
12
+ *
13
+ * Inbound (trainer → JS):
14
+ * { v:1, type:"meta", id, started_at, world_size?, backend }
15
+ * { v:1, type:"step", id, step, loss, lr?, throughput?, grad_norm? }
16
+ * { v:1, type:"checkpoint", id, step, path, size_bytes? }
17
+ * { v:1, type:"eval", id, step, metrics }
18
+ * { v:1, type:"done", id, reason:"complete"|"cancel"|"error"|"not_implemented", final_step?, finished_at }
19
+ * { v:1, type:"error", id?, message }
20
+ * { v:1, type:"log", level:"info"|"warn"|"error", message }
21
+ *
22
+ * Job config shape (extend as needed; backends ignore fields they don't use):
23
+ * {
24
+ * kind: "fine-tune" | "lora" | "rlhf-rollout" | "pretrain",
25
+ * base_model: string,
26
+ * dataset: { url, sha256?, format?, split? },
27
+ * hyperparams: { lr?, batch_size?, epochs?, max_steps? },
28
+ * output: { destination_url, format? }
29
+ * }
30
+ *
31
+ * Bumping TRAINING_PROTOCOL_VERSION is a breaking change.
32
+ */
33
+
34
+ export const TRAINING_PROTOCOL_VERSION = 1;
35
+
36
+ export const TMSG = Object.freeze({
37
+ // outbound
38
+ START: "start",
39
+ CANCEL: "cancel",
40
+ SHUTDOWN: "shutdown",
41
+ // inbound
42
+ META: "meta",
43
+ STEP: "step",
44
+ CHECKPOINT: "checkpoint",
45
+ EVAL: "eval",
46
+ DONE: "done",
47
+ ERROR: "error",
48
+ LOG: "log"
49
+ });
50
+
51
+ export const JOB_KINDS = Object.freeze(["fine-tune", "lora", "rlhf-rollout", "pretrain"]);
52
+
53
+ export const DONE_REASONS = Object.freeze(["complete", "cancel", "error", "not_implemented"]);
54
+
55
+ export function encodeTraining(msg) {
56
+ return JSON.stringify({ v: TRAINING_PROTOCOL_VERSION, ...msg }) + "\n";
57
+ }