lightnode-sdk 0.6.0 → 0.6.2

package/README.md

@@ -16,6 +16,12 @@ npm install lightnode-sdk viem
 LightChain's own docs list official SDKs as "soon"; this fills the gap. Not
 affiliated with LightChain.
 
+New to blockchain or Node.js? Read the
+[Getting Started guide](../GETTING-STARTED.md) first. It covers wallets, testnet
+vs mainnet, the `.env` file, and your first AI call in about 5 minutes. Then come
+back here for the full reference. The rest of this README assumes you're
+comfortable with TypeScript and a terminal.
+
 ## Five-line "hello world"
 
 ```ts
@@ -205,6 +211,84 @@ for await (const event of handle.events) {
 }
 ```
 
+### Batch runner (new in 0.6.0)
+
+Fan out many prompts as parallel encrypted inferences. Capped concurrency, stable result order, per-slot errors so one stalled worker does not kill the batch.
+
+```ts
+import { runInferenceBatch } from "lightnode-sdk";
+
+const results = await runInferenceBatch({
+  network: "testnet",
+  privateKey: process.env.PRIVATE_KEY!,
+  model: "llama3-8b",
+  system: "Reply in one short sentence.",
+  concurrency: 4,
+  prompts: [
+    "one-line fact about the ocean",
+    "one-line fact about the moon",
+    "one-line fact about coffee",
+  ],
+  onSlotComplete: ({ index, result, error }) => {
+    console.log(`#${index}`, error?.message ?? result?.answer);
+  },
+});
+
+for (const r of results) {
+  if (r.error) console.warn(`slot ${r.index} failed:`, r.error.message);
+  else console.log(r.result.answer);
+}
+```
+
+Fits: batch evals, content scoring, RAG re-ranking, parallel rewrites. Pass `{signal}` (`AbortSignal`) to cancel queued slots mid-run.
+
+### Agent class (new in 0.6.0)
+
+ReAct-style tool calling on top of `runInferenceWithKey`. The model emits `<tool>name {"k":"v"}</tool>` or `<answer>...</answer>`; the SDK parses, runs the handler, threads the observation back. Works on small open models (llama3-8b) without native function calling.
+
+```ts
+import { Agent } from "lightnode-sdk";
+
+const agent = new Agent({
+  network: "testnet",
+  privateKey: process.env.PRIVATE_KEY!,
+  model: "llama3-8b",
+  system: "You are a careful research assistant.",
+  tools: [
+    {
+      name: "add",
+      description: "Add two integers and return the sum.",
+      args: { a: "first integer", b: "second integer" },
+      handler: ({ a, b }) => Number(a) + Number(b),
+    },
+  ],
+  maxIterations: 3,
+  onStep: (step) => console.log(step.kind, step),
+});
+
+const { answer, steps, hitLimit } = await agent.run("What is 17 + 25?");
+console.log(answer);   // "42"
+console.log(steps);    // [{ kind: "tool_call", ... }, { kind: "answer", text: "42" }]
+```
+
+Each iteration is one inference (one on-chain `submitJob`); cap `maxIterations` to keep wall-clock + cost bounded. Tool handlers are plain functions that may be async; return JSON-serializable data so the model can read the observation.
+
+### Cancellation (new in 0.6.0)
+
+`runInference` and `runInferenceWithKey` accept an `AbortSignal`. In-flight on-chain transactions still settle (the protocol is the source of truth); the SDK just stops awaiting and rejects with `Error("aborted")`.
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 15_000);
+
+await runInferenceWithKey({
+  network: "testnet",
+  privateKey: process.env.PRIVATE_KEY!,
+  prompt: "short answer please",
+  signal: controller.signal,
+});
+```
+
 ### Typed errors
 
 ```ts

package/dist/add.js

@@ -341,7 +341,9 @@ function depsNeeded(template) {
         return ["lightnode-sdk", "viem", "ws"];
     if (template === "hono")
         return ["lightnode-sdk", "viem", "ws"];
-    return ["lightnode-sdk", "viem", "ws"];
+    // The node/script template is run with `npx tsx <file>.ts`, so tsx must be
+    // installed too, otherwise `tsx ...` fails with "command not found".
+    return ["lightnode-sdk", "viem", "ws", "tsx"];
 }
 /**
  * Implementation called by `lightnode add inference [...]`.

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, isStalledWorker, workerPreflight, workerWatch, BRIDGE_ROUTE, DAO, DAO_ADDRESSES } from "./index.js";
+import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, runInferenceBatch, Agent, isStalledWorker, workerPreflight, workerWatch, BRIDGE_ROUTE, DAO, DAO_ADDRESSES } from "./index.js";
 import { addInference, addAnalyticsDashboard, addNftMint, addChat, addAgent } from "./add.js";
 import { createPublicClient, http, parseEther } from "viem";
 import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
@@ -22,6 +22,10 @@ const HELP = `lightnode <command> [--net mainnet|testnet]
 Run one inference (needs PRIVATE_KEY in env):
   chat <prompt>            stream one encrypted inference answer to stdout
                            ([--model llama3-8b] [--key 0x...])
+  batch <prompts.json>     run N prompts in parallel, JSON line per result
+                           ([--model] [--concurrency 4])
+  agent <task>             ReAct-style agent with built-in add + now tools
+                           ([--model] [--max-iter 4])
 
 Wallet helpers:
   wallet new               generate a fresh testnet key, print it
@@ -343,7 +347,7 @@ async function main() {
                 console.log("\nNothing to do - all target files already exist. Pass --force to overwrite.");
             }
             else {
-                console.log(`\nNext steps:`);
+                console.log(`\nNext steps (these files were added to your CURRENT folder, not a new project):`);
                 console.log(`  1. ${result.install}`);
                 if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent") {
                     console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
@@ -352,14 +356,14 @@ async function main() {
                         console.log(`  4. Deploy. Vercel Cron fires /api/agent on the schedule in vercel.json`);
                     }
                     else if (sub === "agent") {
-                        console.log(`  3. AGENT_INTERVAL_MS=3600000 tsx agent.ts   # or run under pm2/systemd`);
+                        console.log(`  3. AGENT_INTERVAL_MS=3600000 npx tsx agent.ts   # or run under pm2/systemd`);
                     }
                     else if (sub === "chat" && result.template === "nextjs-api") {
                         console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
                         console.log(`  4. npm run dev, open /chat`);
                     }
                     else if (sub === "chat") {
-                        console.log(`  3. tsx chat-repl.ts  (interactive terminal chat)`);
+                        console.log(`  3. npx tsx chat-repl.ts  (interactive terminal chat)`);
                     }
                     else if (sub === "nft-mint-with-inference" && result.template === "nextjs-api") {
                         console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
@@ -372,10 +376,10 @@ async function main() {
                         console.log(`  3. wire inferenceHandler into your Hono app, then start it`);
                     }
                     else if (sub === "nft-mint-with-inference") {
-                        console.log(`  3. tsx nft-metadata.ts "My NFT" "concept goes here"`);
+                        console.log(`  3. npx tsx nft-metadata.ts "My NFT" "concept goes here"`);
                     }
                     else {
-                        console.log(`  3. tsx lightchain-inference.ts "your prompt"`);
+                        console.log(`  3. npx tsx lightchain-inference.ts "your prompt"`);
                     }
                 }
                 else {
@@ -384,11 +388,114 @@ async function main() {
                         console.log(`  2. npm run dev, open /lightnode-analytics`);
                     }
                     else {
-                        console.log(`  2. tsx lightnode-analytics.ts`);
+                        console.log(`  2. npx tsx lightnode-analytics.ts`);
                     }
                 }
+                if (result.network === "testnet") {
+                    console.log(`\nNo wallet yet? Make one:  npx lightnode wallet new   then fund it free below.`);
+                }
                 console.log(`\nFree testnet LCAI: https://lightfaucet.ai`);
                 console.log(`Builder docs:     https://lightnode.app/build`);
+                console.log(`New to all this?  See GETTING-STARTED.md in the lightnode repo.`);
+            }
+            break;
+        }
+        case "batch": {
+            // `lightnode batch <prompts.json>` or `lightnode batch -` (stdin).
+            // Input shape: ["prompt one","prompt two"] OR
+            //   { "model": "llama3-8b", "system": "...", "prompts": ["...", "..."] }
+            // Output: one JSON object per line (index, answer or error). Composes
+            // with `jq` for downstream processing.
+            const arg = positionals[1] ?? "";
+            if (!arg)
+                die("usage: lightnode batch <prompts.json>   (or `lightnode batch -` to read stdin)");
+            const raw = await (arg === "-" ? readStdin() : readFile(arg));
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (e) {
+                die("invalid JSON: " + e.message);
+            }
+            const cfg = normalizeBatchInput(parsed);
+            const model = flag("--model") ?? cfg.model ?? "llama3-8b";
+            const concurrency = Number(flag("--concurrency") ?? "4") || 4;
+            const privateKey = pickKey();
+            process.stderr.write(`Running ${cfg.prompts.length} prompts on ${net} via ${model} (concurrency=${concurrency})\n`);
+            const results = await runInferenceBatch({
+                network: net,
+                privateKey,
+                model,
+                system: cfg.system,
+                concurrency,
+                prompts: cfg.prompts,
+                onSlotComplete: ({ index, result, error }) => {
+                    process.stdout.write(JSON.stringify({
+                        index,
+                        ok: error == null,
+                        answer: result?.answer ?? null,
+                        error: error?.message ?? null,
+                        jobId: result?.jobId.toString() ?? error?.jobId ?? null,
+                    }) + "\n");
+                },
+            });
+            const okCount = results.filter((r) => r.error == null).length;
+            process.stderr.write(`Done: ${okCount}/${results.length} succeeded\n`);
+            break;
+        }
+        case "agent": {
+            // Quick one-shot agent demo: built-in `add` + `now` tools. Bring the
+            // model your prompt as positional args (or pipe via stdin) and watch
+            // the step trace on stderr while the answer streams to stdout.
+            const inline = positionals.slice(1).join(" ").trim();
+            const task = inline || (await readStdin()).trim();
+            if (!task)
+                die("usage: lightnode agent <task>   (or pipe the task to stdin)");
+            const model = flag("--model") ?? "llama3-8b";
+            const maxIter = Number(flag("--max-iter") ?? "4") || 4;
+            const privateKey = pickKey();
+            // A tiny built-in toolset so the command is runnable without writing
+            // a wrapper. For real tools, import Agent from the SDK and pass your own.
+            const tools = [
+                {
+                    name: "add",
+                    description: "Add two integers and return the sum.",
+                    args: { a: "first integer", b: "second integer" },
+                    handler: ({ a, b }) => Number(a) + Number(b),
+                },
+                {
+                    name: "now",
+                    description: "Return the current ISO timestamp.",
+                    args: {},
+                    handler: () => new Date().toISOString(),
+                },
+            ];
+            const agent = new Agent({
+                network: net,
+                privateKey,
+                model,
+                system: "You are a careful assistant. Use tools when they help; otherwise answer directly.",
+                tools,
+                maxIterations: maxIter,
+                onStep: (step) => {
+                    if (step.kind === "tool_call") {
+                        process.stderr.write(`[tool] ${step.name}(${JSON.stringify(step.args)}) -> ${JSON.stringify(step.result)}\n`);
+                    }
+                    else if (step.kind === "tool_error") {
+                        process.stderr.write(`[tool-error] ${step.name}: ${step.error}\n`);
+                    }
+                    else if (step.kind === "thought") {
+                        process.stderr.write(`[think] ${step.text.slice(0, 200)}\n`);
+                    }
+                },
+            });
+            try {
+                const { answer, steps, iterations, hitLimit } = await agent.run(task);
+                process.stdout.write(answer + "\n");
+                process.stderr.write(JSON.stringify({ iterations, steps: steps.length, hitLimit }) + "\n");
+            }
+            catch (e) {
+                die("agent failed: " + e.message);
             }
             break;
         }
@@ -396,4 +503,37 @@ async function main() {
             console.log(HELP);
     }
 }
+async function readStdin() {
+    return new Promise((resolve) => {
+        let buf = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (d) => (buf += d));
+        process.stdin.on("end", () => resolve(buf));
+    });
+}
+async function readFile(path) {
+    const fs = await import("node:fs/promises");
+    return fs.readFile(path, "utf8");
+}
+function normalizeBatchInput(parsed) {
+    if (Array.isArray(parsed)) {
+        const prompts = parsed.filter((p) => typeof p === "string");
+        if (!prompts.length)
+            die("batch input: array must contain at least one string prompt");
+        return { prompts };
+    }
+    if (parsed && typeof parsed === "object") {
+        const obj = parsed;
+        const prompts = Array.isArray(obj.prompts) ? obj.prompts.filter((p) => typeof p === "string") : [];
+        if (!prompts.length)
+            die("batch input: object must have a `prompts` array of strings");
+        return {
+            prompts,
+            system: typeof obj.system === "string" ? obj.system : undefined,
+            model: typeof obj.model === "string" ? obj.model : undefined,
+        };
+    }
+    die("batch input: expected JSON array of strings OR object { prompts, system?, model? }");
+    return { prompts: [] };
+}
 main().catch((e) => die(String(e?.message ?? e)));

package/dist/index.d.ts

@@ -90,7 +90,7 @@ export declare class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.6.1";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, Conversation, chat, runInferenceBatch, Agent, parseAgentOutput, workerPreflight, workerWatch, Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
 export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult } from "./inference.js";

package/dist/index.js

@@ -145,7 +145,7 @@ export class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export const SDK_VERSION = "0.6.0";
+export const SDK_VERSION = "0.6.1";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
 GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Read-only TypeScript client for LightChain AI: workers, jobs, models, on-chain registration, and per-model network analytics. Independent, community-built (not an official LightChain package).",
   "type": "module",
   "main": "./dist/index.js",