lightnode-sdk 0.5.1 → 0.6.1

package/README.md

@@ -205,6 +205,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/agent.d.ts

@@ -0,0 +1,122 @@
+import { type RunInferenceWithKeyArgs } from "./inference.js";
+/**
+ * One tool the agent can call. The model decides when by emitting a tool
+ * call block; the handler returns plain JSON which is threaded back into
+ * the next turn as an observation.
+ *
+ * The handler MUST return JSON-serializable data so the model can read
+ * it back. Use `String()` to stringify primitives, `JSON.stringify`-able
+ * objects otherwise.
+ */
+export interface AgentTool {
+    /** Short snake_case name. The model uses this exact string in tool calls. */
+    name: string;
+    /** One-line description shown to the model so it knows when to use the tool. */
+    description: string;
+    /**
+     * Argument schema, very informal: { argName: "string description" }. The
+     * model is told to fill in matching JSON values; the SDK does not enforce
+     * types beyond JSON parsing.
+     */
+    args: Record<string, string>;
+    /** Run the tool. Return JSON-serializable data (string, number, object, etc.). */
+    handler: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/** One step in the agent's reasoning loop. */
+export type AgentStep = {
+    kind: "thought";
+    text: string;
+} | {
+    kind: "tool_call";
+    name: string;
+    args: Record<string, unknown>;
+    result: unknown;
+} | {
+    kind: "tool_error";
+    name: string;
+    args: Record<string, unknown>;
+    error: string;
+} | {
+    kind: "answer";
+    text: string;
+};
+export interface AgentRunResult {
+    /** The model's final answer. May be empty if maxIterations was hit. */
+    answer: string;
+    /** Every step taken (thoughts + tool calls + final answer). Useful for debugging + UI. */
+    steps: AgentStep[];
+    /** Total inferences fired. Each iteration is one inference, so this is also iteration count. */
+    iterations: number;
+    /** True if the loop bailed because it ran out of iterations without an `answer` block. */
+    hitLimit: boolean;
+}
+export interface AgentOptions extends Omit<RunInferenceWithKeyArgs, "prompt" | "system"> {
+    /** Human-readable goal / persona. Becomes the BASE system prompt; the tool harness is appended automatically. */
+    system?: string;
+    /** Tools the model is allowed to call. */
+    tools: ReadonlyArray<AgentTool>;
+    /** Hard cap on reasoning steps. Default 5. */
+    maxIterations?: number;
+    /** Called after every step (thought / tool call / answer). Useful for live UI. */
+    onStep?: (step: AgentStep) => void;
+}
+/**
+ * ReAct-style agent on top of `runInferenceWithKey`. Each iteration:
+ *   1. The SDK sends a system prompt that lists tools + the JSON tool-call
+ *      format to the model, plus the running transcript.
+ *   2. The model emits either a tool call (`<tool>name {"k":"v"}</tool>`)
+ *      or a final answer (`<answer>...</answer>`).
+ *   3. The SDK parses, runs the tool, threads the result back, repeats.
+ *
+ * Designed for smaller open models (llama3-8b). The protocol is simple
+ * string markers, not native function calling, so it works on any model
+ * the LightChain network exposes.
+ *
+ * @example
+ * ```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,
+ * });
+ *
+ * const { answer, steps } = await agent.run("What is 17 + 25?");
+ * console.log(answer); // "42"
+ * ```
+ */
+export declare class Agent {
+    private readonly opts;
+    constructor(opts: AgentOptions);
+    run(userMessage: string): Promise<AgentRunResult>;
+    private buildSystemPrompt;
+}
+type ParsedOutput = {
+    kind: "tool_call";
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    kind: "answer";
+    text: string;
+} | {
+    kind: "thought";
+    text: string;
+};
+/**
+ * Parse the model's raw output into either a tool call, a final answer, or
+ * a thought (everything else). Tolerant of whitespace and the model
+ * forgetting to close a tag. Visible for testing.
+ */
+export declare function parseAgentOutput(raw: string): ParsedOutput;
+export {};

package/dist/agent.js

@@ -0,0 +1,176 @@
+import { runInferenceWithKey } from "./inference.js";
+/**
+ * ReAct-style agent on top of `runInferenceWithKey`. Each iteration:
+ *   1. The SDK sends a system prompt that lists tools + the JSON tool-call
+ *      format to the model, plus the running transcript.
+ *   2. The model emits either a tool call (`<tool>name {"k":"v"}</tool>`)
+ *      or a final answer (`<answer>...</answer>`).
+ *   3. The SDK parses, runs the tool, threads the result back, repeats.
+ *
+ * Designed for smaller open models (llama3-8b). The protocol is simple
+ * string markers, not native function calling, so it works on any model
+ * the LightChain network exposes.
+ *
+ * @example
+ * ```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,
+ * });
+ *
+ * const { answer, steps } = await agent.run("What is 17 + 25?");
+ * console.log(answer); // "42"
+ * ```
+ */
+export class Agent {
+    constructor(opts) {
+        if (!opts.tools || opts.tools.length === 0) {
+            throw new Error("Agent: at least one tool is required (use runInferenceWithKey for plain inference)");
+        }
+        // Tool names must be unique - the SDK matches model-emitted names by
+        // string and a dup would silently route to the wrong handler.
+        const seen = new Set();
+        for (const t of opts.tools) {
+            if (seen.has(t.name))
+                throw new Error(`Agent: duplicate tool name "${t.name}"`);
+            seen.add(t.name);
+        }
+        this.opts = opts;
+    }
+    async run(userMessage) {
+        const maxIter = Math.max(1, this.opts.maxIterations ?? 5);
+        const steps = [];
+        const transcript = [`User: ${userMessage}`];
+        const system = this.buildSystemPrompt();
+        let iterations = 0;
+        // Strip Agent-only fields before passing through to runInferenceWithKey.
+        const passthrough = { ...this.opts };
+        delete passthrough.tools;
+        delete passthrough.maxIterations;
+        delete passthrough.onStep;
+        delete passthrough.system;
+        while (iterations < maxIter) {
+            iterations++;
+            const prompt = `${system}\n\n${transcript.join("\n\n")}\n\nAssistant:`;
+            const { answer: raw } = await runInferenceWithKey({
+                ...passthrough,
+                prompt,
+            });
+            const parsed = parseAgentOutput(raw);
+            if (parsed.kind === "answer") {
+                const step = { kind: "answer", text: parsed.text };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                return { answer: parsed.text, steps, iterations, hitLimit: false };
+            }
+            if (parsed.kind === "thought") {
+                const step = { kind: "thought", text: parsed.text };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <think>${parsed.text}</think>`);
+                continue;
+            }
+            // tool_call: look up + execute
+            const tool = this.opts.tools.find((t) => t.name === parsed.name);
+            if (!tool) {
+                const step = {
+                    kind: "tool_error",
+                    name: parsed.name,
+                    args: parsed.args,
+                    error: `unknown tool "${parsed.name}"`,
+                };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <tool>${parsed.name} ${JSON.stringify(parsed.args)}</tool>`);
+                transcript.push(`Observation: error: unknown tool "${parsed.name}"`);
+                continue;
+            }
+            try {
+                const result = await tool.handler(parsed.args);
+                const step = { kind: "tool_call", name: parsed.name, args: parsed.args, result };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <tool>${parsed.name} ${JSON.stringify(parsed.args)}</tool>`);
+                transcript.push(`Observation: ${JSON.stringify(result)}`);
+            }
+            catch (err) {
+                const msg = err.message ?? String(err);
+                const step = {
+                    kind: "tool_error",
+                    name: parsed.name,
+                    args: parsed.args,
+                    error: msg,
+                };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <tool>${parsed.name} ${JSON.stringify(parsed.args)}</tool>`);
+                transcript.push(`Observation: error: ${msg}`);
+            }
+        }
+        return { answer: "", steps, iterations, hitLimit: true };
+    }
+    buildSystemPrompt() {
+        const base = this.opts.system?.trim() ?? "You are a helpful assistant.";
+        const toolDocs = this.opts.tools
+            .map((t) => {
+            const argList = Object.entries(t.args)
+                .map(([k, v]) => `    "${k}": <${v}>`)
+                .join(",\n");
+            return `- ${t.name}: ${t.description}\n  Call as: <tool>${t.name} {\n${argList}\n  }</tool>`;
+        })
+            .join("\n");
+        return `${base}
+
+You have access to these tools:
+${toolDocs}
+
+To call a tool, write EXACTLY one line:
+<tool>tool_name {"arg":"value"}</tool>
+
+After the tool runs, the user will reply with: Observation: <json>
+
+When you are done, respond with EXACTLY:
+<answer>your final reply to the user</answer>
+
+Use one tool at a time. Do not invent tools. Keep observations short.`;
+    }
+}
+/**
+ * Parse the model's raw output into either a tool call, a final answer, or
+ * a thought (everything else). Tolerant of whitespace and the model
+ * forgetting to close a tag. Visible for testing.
+ */
+export function parseAgentOutput(raw) {
+    const answer = raw.match(/<answer>([\s\S]*?)(?:<\/answer>|$)/i);
+    if (answer)
+        return { kind: "answer", text: answer[1].trim() };
+    const tool = raw.match(/<tool>\s*([a-zA-Z_][\w-]*)\s*(\{[\s\S]*?\})\s*(?:<\/tool>|$)/i);
+    if (tool) {
+        const name = tool[1];
+        let args = {};
+        try {
+            const parsed = JSON.parse(tool[2]);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                args = parsed;
+            }
+        }
+        catch {
+            // best-effort: leave args empty so the handler sees missing fields
+        }
+        return { kind: "tool_call", name, args };
+    }
+    return { kind: "thought", text: raw.trim() };
+}

package/dist/batch.d.ts

@@ -0,0 +1,88 @@
+import { type RunInferenceWithKeyArgs, type RunInferenceResult } from "./inference.js";
+/**
+ * One slot in a batch run. `prompt` is the only required field; everything
+ * else inherits from the shared base args passed to `runInferenceBatch`.
+ * A per-prompt `model` / `system` overrides the base when set.
+ */
+export interface BatchPrompt {
+    prompt: string;
+    model?: string;
+    system?: string;
+    /** Opaque per-slot tag returned on the result so the caller can correlate. */
+    tag?: string;
+}
+/** One slot's outcome. `error` is set on failure; `result` on success. Always exactly one. */
+export type BatchResult = {
+    index: number;
+    tag?: string;
+    prompt: string;
+    result: RunInferenceResult;
+    error: null;
+} | {
+    index: number;
+    tag?: string;
+    prompt: string;
+    result: null;
+    error: {
+        name: string;
+        message: string;
+        jobId?: string;
+    };
+};
+export interface RunInferenceBatchArgs extends Omit<RunInferenceWithKeyArgs, "prompt"> {
+    /** Prompts to run. Each slot becomes one independent encrypted inference. */
+    prompts: ReadonlyArray<string | BatchPrompt>;
+    /**
+     * Shared system prompt prepended to every slot. A per-slot `system`
+     * overrides this. Implemented by prefixing the prompt at submit time
+     * (the underlying inference call has no native system role).
+     */
+    system?: string;
+    /**
+     * Max parallel inferences in flight (default 4). Each slot is one
+     * createSession + submitJob pair, so this caps the concurrent wallet
+     * nonce pressure as well as the gateway socket fan-out.
+     */
+    concurrency?: number;
+    /**
+     * Called when ANY slot resolves (success or failure), useful for live
+     * progress UI. Fires in order of completion, not submission.
+     */
+    onSlotComplete?: (result: BatchResult) => void;
+    /**
+     * When set, abort all in-flight + queued slots if this signal fires.
+     * Slots already submitted on chain still settle on chain; the SDK just
+     * stops awaiting their answer.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Run many prompts as parallel encrypted inferences against the same
+ * worker pool. Returns a stable array indexed by submission order.
+ *
+ * Slots fail independently - a stalled worker on one prompt does not
+ * cancel the others. The caller decides what to retry from the per-slot
+ * error.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceBatch } from "lightnode-sdk";
+ *
+ * const results = await runInferenceBatch({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   model: "llama3-8b",
+ *   prompts: ["one", "two", "three"],
+ *   concurrency: 3,
+ *   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);
+ * }
+ * ```
+ */
+export declare function runInferenceBatch(args: RunInferenceBatchArgs): Promise<BatchResult[]>;

package/dist/batch.js

@@ -0,0 +1,102 @@
+import { runInferenceWithKey } from "./inference.js";
+import { StalledWorkerError } from "./errors.js";
+/**
+ * Run many prompts as parallel encrypted inferences against the same
+ * worker pool. Returns a stable array indexed by submission order.
+ *
+ * Slots fail independently - a stalled worker on one prompt does not
+ * cancel the others. The caller decides what to retry from the per-slot
+ * error.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceBatch } from "lightnode-sdk";
+ *
+ * const results = await runInferenceBatch({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   model: "llama3-8b",
+ *   prompts: ["one", "two", "three"],
+ *   concurrency: 3,
+ *   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);
+ * }
+ * ```
+ */
+export async function runInferenceBatch(args) {
+    const concurrency = Math.max(1, args.concurrency ?? 4);
+    const slots = args.prompts.map((p) => (typeof p === "string" ? { prompt: p } : p));
+    const out = new Array(slots.length);
+    let nextIndex = 0;
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+    };
+    if (args.signal) {
+        if (args.signal.aborted)
+            aborted = true;
+        else
+            args.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    const runOne = async (index) => {
+        if (aborted) {
+            out[index] = {
+                index,
+                tag: slots[index].tag,
+                prompt: slots[index].prompt,
+                result: null,
+                error: { name: "AbortError", message: "batch aborted before this slot ran" },
+            };
+            return;
+        }
+        const slot = slots[index];
+        try {
+            const system = slot.system ?? args.system;
+            const finalPrompt = system ? `${system.trim()}\n\n${slot.prompt}` : slot.prompt;
+            // Strip batch-only fields before passing through to runInferenceWithKey.
+            const passthrough = { ...args };
+            delete passthrough.prompts;
+            delete passthrough.system;
+            delete passthrough.concurrency;
+            delete passthrough.onSlotComplete;
+            const result = await runInferenceWithKey({
+                ...passthrough,
+                prompt: finalPrompt,
+                model: slot.model ?? args.model,
+            });
+            out[index] = { index, tag: slot.tag, prompt: slot.prompt, result, error: null };
+        }
+        catch (err) {
+            const e = err;
+            const jobId = e instanceof StalledWorkerError ? e.jobId.toString() : undefined;
+            out[index] = {
+                index,
+                tag: slot.tag,
+                prompt: slot.prompt,
+                result: null,
+                error: { name: e.name ?? "Error", message: e.message, jobId },
+            };
+        }
+        args.onSlotComplete?.(out[index]);
+    };
+    // N parallel workers pulling off the queue. Order of completion is
+    // non-deterministic, order of OUTPUT is stable via `index`.
+    const workers = new Array(Math.min(concurrency, slots.length)).fill(0).map(async () => {
+        while (true) {
+            const i = nextIndex++;
+            if (i >= slots.length)
+                return;
+            await runOne(i);
+        }
+    });
+    await Promise.all(workers);
+    if (args.signal)
+        args.signal.removeEventListener("abort", onAbort);
+    return out;
+}

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
@@ -392,8 +396,140 @@ async function main() {
             }
             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;
+        }
         default:
             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/dao.d.ts

@@ -17,22 +17,47 @@
  * This module covers the OZ Governor v5 surface: state machine, propose,
  * castVote, queue, execute. Plus convenience reads of the constants.
  */
-export type DaoChain = "ethereum";
+/**
+ * Both deployed DAOs we know about:
+ *
+ *   - `ethereum`         LCAIGovernor on Ethereum mainnet. Token holders
+ *                        wrap LCAI ERC-20 into LCAI-Ballots (IVotes) at
+ *                        https://ballots.lightchain.ai, then vote /
+ *                        propose / queue / execute through the Governor.
+ *                        Proposal threshold: 140,000 LCAI wrapped.
+ *
+ *   - `lightchain`       LightChainGovernor on LightChain mainnet (chain
+ *                        9200). Uses the NativeVotes precompile at
+ *                        0x...0001001 - native LCAI itself acts as the
+ *                        voting token, no wrapping needed. Governor is
+ *                        an upgradeable proxy controlled by the
+ *                        TimelockController.
+ *
+ * Addresses sourced from LightChain's official "Mainnet Contract Addresses"
+ * page.
+ */
+export type DaoChain = "ethereum" | "lightchain";
 export interface DaoAddresses {
     chainId: number;
-    /** OZ Governor contract. */
+    label: string;
+    /** OZ Governor contract (proxy when behind an upgradeable pattern). */
     governor: `0x${string}`;
     /** Timelock controller. queue/execute dispatch through this. */
     timelock: `0x${string}`;
-    /** ERC-20 wrapped as IVotes; this is what users delegate / hold to vote. */
-    ballots: `0x${string}`;
-    /** LCAI ERC-20 (the underlying governance token). */
-    token: `0x${string}`;
+    /** ERC-20 wrapped as IVotes (null when the chain uses a NativeVotes precompile). */
+    ballots: `0x${string}` | null;
+    /** Underlying governance token (LCAI ERC-20 on Ethereum, native LCAI on LightChain). */
+    token: `0x${string}` | null;
     /** Treasury contract holding DAO funds. */
     treasury: `0x${string}`;
+    /** Optional UI link (where regular users wrap / view proposals). */
+    wrapperUi?: string;
     explorer: string;
 }
-/** Confirmed Ethereum mainnet addresses (chain 1). */
+/**
+ * Confirmed deployment addresses. Each entry is what an SDK user passes to
+ * `new DAO(client, chainKey, walletClient?)`.
+ */
 export declare const DAO_ADDRESSES: Record<DaoChain, DaoAddresses>;
 /**
  * The 8-state OZ Governor v5 enum. The string label is what most builders

package/dist/dao.js

@@ -18,17 +18,33 @@
  * castVote, queue, execute. Plus convenience reads of the constants.
  */
 import { parseAbi } from "viem";
-/** Confirmed Ethereum mainnet addresses (chain 1). */
+/**
+ * Confirmed deployment addresses. Each entry is what an SDK user passes to
+ * `new DAO(client, chainKey, walletClient?)`.
+ */
 export const DAO_ADDRESSES = {
     ethereum: {
         chainId: 1,
+        label: "Ethereum mainnet",
         governor: "0x6dfa413B5900a1a7947BC75E68AbBA093cB2492d",
         timelock: "0xbE1c37F8C4DA77dD06F4A8AC5098Ec70273093d7",
         ballots: "0x75F3D01c4D960FE986A598B7954A3b786B29cE49",
         token: "0x9cA8530CA349c966Fe9ef903Df17a75B8A778927",
         treasury: "0x07A716a551E5f4CA7D6C71Da9dF1cb1429Dba826",
+        wrapperUi: "https://ballots.lightchain.ai",
         explorer: "https://etherscan.io",
     },
+    lightchain: {
+        chainId: 9200,
+        label: "LightChain mainnet",
+        governor: "0x262E9f9232933E8565253918db703baD58DE93aB",
+        timelock: "0x79e571420c5473Ca9b0FCd599B1b0062D7793c97",
+        // Native voting via the genesis predeploy precompile; no separate wrapping token.
+        ballots: "0x0000000000000000000000000000000000001001",
+        token: null,
+        treasury: "0x786eDe8C42Ca54E54c9dCECa9b30052CF4743389",
+        explorer: "https://mainnet.lightscan.app",
+    },
 };
 /**
  * The 8-state OZ Governor v5 enum. The string label is what most builders

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { fromWei } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
 import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream } from "./inference.js";
 import { Conversation, chat } from "./chat.js";
+import { runInferenceBatch } from "./batch.js";
+import { Agent, parseAgentOutput } from "./agent.js";
 import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
 import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer } from "./bridge.js";
 import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI } from "./dao.js";
@@ -88,11 +90,13 @@ 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.5.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, 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 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";
 export type { ChatRole, ChatMessage, ConversationOptions, ConversationSendResult } from "./chat.js";
+export type { BatchPrompt, BatchResult, RunInferenceBatchArgs } from "./batch.js";
+export type { AgentTool, AgentStep, AgentOptions, AgentRunResult } from "./agent.js";
 export type { WorkerPreflightArgs, WorkerPreflightResult, WorkerWatchOptions, WorkerEventKind, WorkerEvent, WorkerWatchHandle } from "./worker.js";
 export type { BridgeChain, BridgeEndpoints, BridgeTransferArgs } from "./bridge.js";
 export type { DaoChain, DaoAddresses, ProposalSummary, DaoConfig } from "./dao.js";

package/dist/index.js

@@ -4,6 +4,8 @@ import { isRegistered } from "./onchain.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
 import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, } from "./inference.js";
 import { Conversation, chat } from "./chat.js";
+import { runInferenceBatch } from "./batch.js";
+import { Agent, parseAgentOutput } from "./agent.js";
 import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
 import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, } from "./bridge.js";
 import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, } from "./dao.js";
@@ -143,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.5.1";
+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, 
@@ -155,6 +157,10 @@ runInferenceWithKey,
 runInferenceStream, 
 // v0.5.0 multi-turn conversation helper (history client-side; one inference per turn).
 Conversation, chat, 
+// v0.6.0 batch runner: many prompts, capped parallelism, stable result order.
+runInferenceBatch, 
+// v0.6.0 ReAct-style agent: tool calling on any LightChain-hosted model.
+Agent, parseAgentOutput, 
 // v0.5.0 worker preflight + watch (one real test inference + status polling).
 workerPreflight, workerWatch, 
 // v0.5.0 Bridge SDK (Hyperlane Warp Route wrapper for LCAI <-> Ethereum).

package/dist/inference.d.ts

@@ -171,6 +171,11 @@ export interface RunInferenceArgs {
      * Useful for tests / mirrors.
      */
     relayUrl?: string;
+    /**
+     * Cancellation signal. Aborts pending awaits inside the run; in-flight
+     * submitJob transactions still settle on chain (the SDK stops listening).
+     */
+    signal?: AbortSignal;
 }
 export interface RunInferenceResult {
     /** The decrypted, fully-assembled model answer. */
@@ -264,6 +269,13 @@ export interface RunInferenceWithKeyArgs {
      * Useful for tests / mirrors / proxying through your own backend.
      */
     gatewayUrl?: string;
+    /**
+     * Cancellation signal. Aborts the SIWE handshake and stops awaiting the
+     * relay; in-flight submitJob transactions still settle on chain (the SDK
+     * just stops listening). Throws `Error("aborted")` synchronously if the
+     * signal is already fired when the call starts.
+     */
+    signal?: AbortSignal;
 }
 /**
  * One call, key-in / answer-out encrypted inference. Builds viem clients,

package/dist/inference.js

@@ -428,12 +428,14 @@ export async function runInference(args) {
     const maxRetries = args.maxRetries ?? 2;
     const stalled = [];
     for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        if (args.signal?.aborted)
+            throw new Error("runInference: aborted");
         try {
             const result = await runOneAttempt(args, attempt);
             return { ...result, stalled };
         }
         catch (err) {
-            if (err instanceof StalledWorkerError && attempt <= maxRetries) {
+            if (err instanceof StalledWorkerError && attempt <= maxRetries && !args.signal?.aborted) {
                 stalled.push({ jobId: err.jobId, worker: err.worker, submitTx: err.submitTx });
                 continue;
             }
@@ -482,6 +484,9 @@ export async function runInferenceWithKey(args) {
     if (!key || !key.startsWith("0x") || key.length !== 66) {
         throw new Error("runInferenceWithKey: privateKey must be a 0x-prefixed 32-byte hex string");
     }
+    if (args.signal?.aborted) {
+        throw new Error("runInferenceWithKey: aborted before start");
+    }
     const account = viemPrivateKeyToAccount(key);
     const chain = {
         id: network.chainId,
@@ -504,7 +509,7 @@ export async function runInferenceWithKey(args) {
     // looks like a CORS or undici-level reachability error.
     const fetchOrFail = async (url, init, label) => {
         try {
-            return await fetch(url, init);
+            return await fetch(url, { ...init, signal: args.signal });
         }
         catch (err) {
             const cause = err.cause;
@@ -574,6 +579,7 @@ export async function runInferenceWithKey(args) {
         jobCompletedTimeoutMs: args.jobCompletedTimeoutMs,
         WebSocket: wsCtor,
         relayUrl: args.relayUrl,
+        signal: args.signal,
     });
 }
 /**

package/dist/networks.js

@@ -17,6 +17,12 @@ export const NETWORKS = {
         aiConfig: "0x24D11533C354092ed6E18b964257819cE78Ce77D",
         jobRegistry: "0xfB15F90298e4CcD7106E76fFB5e520315cC42B0b",
         minStakeLcai: 50000,
+        // Sourced from LightChain's official "Mainnet Contract Addresses" page.
+        feePool: "0x0000000000000000000000000000000000001004",
+        nativeVotes: "0x0000000000000000000000000000000000001001",
+        governor: "0x262E9f9232933E8565253918db703baD58DE93aB",
+        timelock: "0x79e571420c5473Ca9b0FCd599B1b0062D7793c97",
+        treasury: "0x786eDe8C42Ca54E54c9dCECa9b30052CF4743389",
     },
     testnet: {
         id: "testnet",
@@ -30,6 +36,9 @@ export const NETWORKS = {
         aiConfig: "0xeCF4Ca5Ba6D97ae586993e170764a1E92231b67e",
         jobRegistry: "0x531b3a87c5d785441b9cf55b98169f20fd9056a7",
         minStakeLcai: 5000,
+        // Same genesis predeploys as mainnet (chain bytecode is identical).
+        feePool: "0x0000000000000000000000000000000000001004",
+        nativeVotes: "0x0000000000000000000000000000000000001001",
     },
 };
 /** WorkerRegistry genesis predeploy (same address on both networks). */

package/dist/types.d.ts

@@ -12,6 +12,16 @@ export interface NetworkConfig {
     aiConfig: string;
     jobRegistry: string;
     minStakeLcai: number;
+    /** FeePool genesis predeploy. Where per-job fees accumulate before payout. */
+    feePool?: string;
+    /** NativeVotes precompile (mainnet only - backs LightChainGovernor). */
+    nativeVotes?: string;
+    /** On-chain DAO governor (mainnet only today). */
+    governor?: string;
+    /** Governor timelock controller (mainnet only). */
+    timelock?: string;
+    /** DAO-controlled treasury (mainnet only). */
+    treasury?: string;
 }
 export interface Worker {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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",