nanoodle 0.1.0

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.
@@ -0,0 +1,307 @@
1
+ import { readFile } from "node:fs/promises";
2
+ import { NanoodleError, RunError, UnsupportedNodeError } from "./errors.mjs";
3
+ import { NODE_TYPES, displayName, isInputPort, materialize, topoSort } from "./graph.mjs";
4
+ import { deriveInputs, deriveOutputs, deriveSettings, resolveInputKey, resolveSettingKey } from "./io.mjs";
5
+ import { NanoClient } from "./client.mjs";
6
+ import { MediaRef, coerceMediaInput } from "./media.mjs";
7
+ import { RUNNERS, unsupportedNodeError } from "./nodes.mjs";
8
+
9
+ const MEDIA_KINDS = new Set(["image", "audio", "video", "inpaint"]);
10
+
11
+ /** The outcome of Workflow.run(). Media values are MediaRef; text values plain strings. */
12
+ export class RunResult {
13
+ constructor({ outputs, nodes, errors, costUsd, costExact, remainingBalance }) {
14
+ /** { [friendlyKey | nodeId]: value } — sink node primary outputs */
15
+ this.outputs = outputs;
16
+ /** per-node { status: "done"|"error"|"skipped", out, error, costUsd, ms } */
17
+ this.nodes = nodes;
18
+ /** [{ nodeId, name, message }] for every node that failed (incl. non-sink warnings) */
19
+ this.errors = errors;
20
+ /** summed USD cost of all calls that reported one */
21
+ this.costUsd = costUsd;
22
+ /** false when any network call omitted its price (total is a floor) */
23
+ this.costExact = costExact;
24
+ /** last remaining-balance the API reported, or null */
25
+ this.remainingBalance = remainingBalance;
26
+ }
27
+
28
+ /** Output lookup by friendly key or node id (case-insensitive). */
29
+ get(key) {
30
+ // own-key check: `in` would leak Object.prototype members (get("toString") → a function)
31
+ if (Object.hasOwn(this.outputs, key)) return this.outputs[key];
32
+ const norm = String(key).trim().toLowerCase();
33
+ for (const k of Object.keys(this.outputs)) {
34
+ if (k.toLowerCase() === norm) return this.outputs[k];
35
+ }
36
+ throw new NanoodleError(`no output "${key}" — available outputs: ${Object.keys(this.outputs).map((k) => `"${k}"`).join(", ") || "(none)"}`);
37
+ }
38
+ }
39
+
40
+ function isPlainObject(v) {
41
+ if (v == null || typeof v !== "object") return false;
42
+ const proto = Object.getPrototypeOf(v);
43
+ return proto === Object.prototype || proto === null;
44
+ }
45
+
46
+ export class Workflow {
47
+ /**
48
+ * @param {object} graphData parsed noodle-graph.json
49
+ * @param {{ apiKey?, baseUrl?, fetch?, pollIntervals?, timeouts?, quiet? }} [opts]
50
+ */
51
+ constructor(graphData, opts = {}) {
52
+ const { nodes, links, warnings } = materialize(graphData);
53
+ this.graph = { nodes, links };
54
+ /** Load-time warnings (unknown / unsupported node types). load() only warns; run() fails fast. */
55
+ this.warnings = warnings;
56
+ this.client = new NanoClient({
57
+ apiKey: opts.apiKey !== undefined ? opts.apiKey : process.env.NANOGPT_API_KEY,
58
+ baseUrl: opts.baseUrl,
59
+ fetch: opts.fetch,
60
+ pollIntervals: opts.pollIntervals,
61
+ timeouts: opts.timeouts,
62
+ });
63
+ /** [{ key, nodeId, field, kind, label, optional, def, options? }] */
64
+ this.inputs = deriveInputs(this.graph);
65
+ /** [{ key, nodeId, type, ports }] */
66
+ this.outputs = deriveOutputs(this.graph);
67
+ /** [{ key, nodeId, field, kind, def, options? }] */
68
+ this.settings = deriveSettings(this.graph);
69
+ if (warnings.length && !opts.quiet) {
70
+ for (const w of warnings) process.emitWarning(w, { code: "NANOODLE_GRAPH" });
71
+ }
72
+ }
73
+
74
+ /** Load a downloaded noodle-graph.json save from disk. */
75
+ static async load(path, opts = {}) {
76
+ return Workflow.fromJSON(await readFile(path, "utf8"), opts);
77
+ }
78
+
79
+ /** Build from a parsed object or a JSON string. */
80
+ static fromJSON(objOrString, opts = {}) {
81
+ const data = typeof objOrString === "string" ? JSON.parse(objOrString) : objOrString;
82
+ return new Workflow(data, opts);
83
+ }
84
+
85
+ /**
86
+ * Execute the whole graph.
87
+ * @param {object|string|Uint8Array|MediaRef} inputs friendly-keyed values, or a bare scalar
88
+ * when the workflow has exactly one required input
89
+ * @param {{ settings?, timeoutMs?, signal?, onProgress? }} [runOpts]
90
+ * @returns {Promise<RunResult>} rejects with RunError (carrying .result) when a sink failed
91
+ */
92
+ async run(inputs = {}, runOpts = {}) {
93
+ const { settings = {}, timeoutMs, signal, onProgress } = runOpts;
94
+ const graph = this.graph;
95
+
96
+ // bare scalar → the single required input
97
+ if (!isPlainObject(inputs)) {
98
+ const required = this.inputs.filter((i) => !i.optional);
99
+ if (required.length !== 1) {
100
+ throw new NanoodleError(
101
+ `a bare input value needs exactly one required input; this workflow has ${required.length} ` +
102
+ `(${required.map((i) => `"${i.key}"`).join(", ")}) — pass an object instead`);
103
+ }
104
+ inputs = { [required[0].key]: inputs };
105
+ }
106
+
107
+ // ---- upfront validation: resolve every key BEFORE running/spending anything ----
108
+ const inputAssignments = [];
109
+ for (const [key, value] of Object.entries(inputs)) {
110
+ const entry = resolveInputKey(graph, this.inputs, key);
111
+ inputAssignments.push({ entry, value });
112
+ }
113
+ const settingAssignments = [];
114
+ for (const [key, value] of Object.entries(settings)) {
115
+ const entry = resolveSettingKey(graph, this.settings, key);
116
+ settingAssignments.push({ entry, value });
117
+ }
118
+
119
+ // unsupported / unknown node types fail fast — before any network call
120
+ for (const n of graph.nodes) {
121
+ if (n.unknown) {
122
+ throw new UnsupportedNodeError(
123
+ `node ${n.id}: unknown node type '${n.type}' — this graph needs a newer nanoodle library`,
124
+ { nodeId: n.id, nodeType: n.type });
125
+ }
126
+ if (NODE_TYPES[n.type].unsupported) throw unsupportedNodeError(n);
127
+ }
128
+
129
+ const order = topoSort(graph); // throws naming cyclic nodes
130
+
131
+ // effective fields: graph fields + settings overrides + user inputs
132
+ const effFields = new Map(graph.nodes.map((n) => [n.id, { ...n.fields }]));
133
+ for (const { entry, value } of settingAssignments) {
134
+ effFields.get(entry.nodeId)[entry.field] = this._coerceSetting(entry, value);
135
+ }
136
+ const explicit = new Set();
137
+ for (const { entry, value } of inputAssignments) {
138
+ effFields.get(entry.nodeId)[entry.field] = this._coerceInput(entry, value);
139
+ explicit.add(entry);
140
+ }
141
+ // defaults + required check
142
+ for (const entry of this.inputs) {
143
+ const fields = effFields.get(entry.nodeId);
144
+ const v = fields[entry.field];
145
+ if (v == null || String(v).trim() === "") {
146
+ // an EXPLICIT empty value clears an optional input (e.g. run with no system prompt) —
147
+ // the def only backfills when the key wasn't supplied at all (the app's prefilled textarea)
148
+ if (entry.optional && explicit.has(entry)) continue;
149
+ if (entry.def != null && String(entry.def) !== "") fields[entry.field] = entry.def;
150
+ else if (!entry.optional) {
151
+ throw new NanoodleError(`missing required input "${entry.key}" (${entry.nodeId}.${entry.field})`);
152
+ }
153
+ }
154
+ }
155
+
156
+ // API key required only when the graph actually calls NanoGPT
157
+ if (!this.client.apiKey && graph.nodes.some((n) => NODE_TYPES[n.type].network)) {
158
+ throw new NanoodleError("no API key — pass { apiKey } to Workflow.load/fromJSON or set NANOGPT_API_KEY (this workflow calls the NanoGPT API)");
159
+ }
160
+
161
+ // ---- execution ----
162
+ const ac = new AbortController();
163
+ let timer = null;
164
+ const onOuterAbort = () => ac.abort(signal.reason);
165
+ if (signal) {
166
+ if (signal.aborted) ac.abort(signal.reason);
167
+ else signal.addEventListener("abort", onOuterAbort, { once: true });
168
+ }
169
+ if (timeoutMs) {
170
+ timer = setTimeout(() => ac.abort(new NanoodleError(`run timed out after ${timeoutMs}ms`, { code: "timeout" })), timeoutMs);
171
+ }
172
+
173
+ const emit = (evt) => { if (onProgress) { try { onProgress(evt); } catch { /* listener errors never kill the run */ } } };
174
+ const nodesRec = {};
175
+ const errors = [];
176
+ const cost = { total: 0, exact: true, balance: null };
177
+ const byId = new Map(graph.nodes.map((n) => [n.id, n]));
178
+ const promises = new Map();
179
+
180
+ const ctxFor = (node, rec) => {
181
+ const onCost = (c) => {
182
+ if (!c) return;
183
+ if (c.usd != null) { rec.costUsd = (rec.costUsd || 0) + c.usd; cost.total += c.usd; }
184
+ else cost.exact = false;
185
+ if (c.balance != null) cost.balance = c.balance;
186
+ };
187
+ const onPoll = (info) => emit({ type: "poll", nodeId: node.id, name: displayName(node), ...info });
188
+ const io = { onCost, onPoll, signal: ac.signal };
189
+ return {
190
+ chat: (messages, model, opts) => this.client.chat(messages, model, opts, io),
191
+ chatImage: (messages, model, opts) => this.client.chatImage(messages, model, opts, io),
192
+ image: (args) => this.client.image(args, io),
193
+ video: (model, prompt, opts, imageDataUrl) => this.client.video(model, prompt, opts, imageDataUrl, io),
194
+ audio: (model, input, extra) => this.client.audio(model, input, extra, io),
195
+ transcribe: (model, audioUrl, language) => this.client.transcribe(model, audioUrl, language, io),
196
+ fetchMedia: (url) => this.client.fetchMediaDataUrl(url, io),
197
+ };
198
+ };
199
+
200
+ const execNode = async (n) => {
201
+ const rec = nodesRec[n.id];
202
+ try {
203
+ const inbound = graph.links.filter((l) => l.to.node === n.id);
204
+ const inp = {};
205
+ let fields = effFields.get(n.id);
206
+ let upstreamFail = null;
207
+ for (const l of inbound) {
208
+ let srcOut;
209
+ try { srcOut = await promises.get(l.from.node); }
210
+ catch { if (!upstreamFail) upstreamFail = displayName(byId.get(l.from.node)); continue; }
211
+ const v = srcOut[l.from.port];
212
+ if (isInputPort(n, l.to.port)) inp[l.to.port] = v;
213
+ // wired textarea port = field override; a missing upstream port (degraded save) must
214
+ // NOT clobber the typed field with undefined — the app only applies v != null
215
+ else if (v != null) fields = { ...fields, [l.to.port]: v };
216
+ }
217
+ if (upstreamFail) throw new NanoodleError("upstream failed: " + upstreamFail);
218
+ emit({ type: "node-start", nodeId: n.id, name: displayName(n) });
219
+ const t0 = Date.now();
220
+ const out = await RUNNERS[n.type]({ ...n, fields }, inp, ctxFor(n, rec));
221
+ rec.status = "done";
222
+ rec.out = out;
223
+ rec.ms = Date.now() - t0;
224
+ emit({ type: "node-done", nodeId: n.id, name: displayName(n), ms: rec.ms, costUsd: rec.costUsd });
225
+ return out;
226
+ } catch (e) {
227
+ rec.status = "error";
228
+ rec.error = e.message;
229
+ errors.push({ nodeId: n.id, name: displayName(n), message: e.message });
230
+ emit({ type: "node-error", nodeId: n.id, name: displayName(n), error: e.message });
231
+ throw e;
232
+ }
233
+ };
234
+
235
+ try {
236
+ for (const n of order) {
237
+ if (NODE_TYPES[n.type].note) { nodesRec[n.id] = { status: "skipped", out: null, error: null, costUsd: null, ms: null }; continue; }
238
+ nodesRec[n.id] = { status: "pending", out: null, error: null, costUsd: null, ms: null };
239
+ promises.set(n.id, execNode(n)); // siblings run concurrently; a node starts when ITS deps finish
240
+ }
241
+ await Promise.allSettled([...promises.values()]);
242
+ } finally {
243
+ if (timer) clearTimeout(timer);
244
+ if (signal) signal.removeEventListener("abort", onOuterAbort);
245
+ }
246
+
247
+ // ---- result ----
248
+ const outputsMap = {};
249
+ for (const o of this.outputs) {
250
+ const rec = nodesRec[o.nodeId];
251
+ if (!rec || rec.status !== "done") continue;
252
+ const primary = o.ports[0];
253
+ const value = this._wrapValue(rec.out[primary.name], primary.type);
254
+ outputsMap[o.key] = value;
255
+ outputsMap[o.nodeId] = value;
256
+ }
257
+ const result = new RunResult({
258
+ outputs: outputsMap,
259
+ nodes: nodesRec,
260
+ errors,
261
+ costUsd: cost.total,
262
+ costExact: cost.exact,
263
+ remainingBalance: cost.balance,
264
+ });
265
+
266
+ const failedSinks = this.outputs.filter((o) => nodesRec[o.nodeId] && nodesRec[o.nodeId].status === "error");
267
+ if (failedSinks.length) {
268
+ const detail = failedSinks.map((o) => `"${o.key}": ${nodesRec[o.nodeId].error}`).join("; ");
269
+ throw new RunError("run failed — " + detail, result);
270
+ }
271
+ return result;
272
+ }
273
+
274
+ _coerceInput(entry, value) {
275
+ if (MEDIA_KINDS.has(entry.kind)) {
276
+ return coerceMediaInput(value, `input "${entry.key}"`);
277
+ }
278
+ if (entry.kind === "choice") {
279
+ const v = String(value);
280
+ if (!(entry.options || []).includes(v)) {
281
+ throw new NanoodleError(`input "${entry.key}": "${v}" is not one of the choices (${(entry.options || []).join(", ")})`);
282
+ }
283
+ return v;
284
+ }
285
+ if (value != null && typeof value === "object" && !(value instanceof String)) {
286
+ throw new NanoodleError(`input "${entry.key}" expects text — got ${Array.isArray(value) ? "an array" : "an object"}`);
287
+ }
288
+ return value == null ? value : String(value);
289
+ }
290
+
291
+ _coerceSetting(entry, value) {
292
+ // settings come from DOM inputs in the app, so runners assume strings — coerce scalars
293
+ // (numbers/booleans) the same way instead of crashing a runner mid-run
294
+ if (value == null) return value;
295
+ if (typeof value === "object" && !(value instanceof String)) {
296
+ throw new NanoodleError(`setting "${entry.key}" expects a scalar — got ${Array.isArray(value) ? "an array" : "an object"}`);
297
+ }
298
+ return String(value);
299
+ }
300
+
301
+ _wrapValue(value, portType) {
302
+ if (portType !== "text" && typeof value === "string" && value) {
303
+ return new MediaRef(value, { fetch: this.client.fetch });
304
+ }
305
+ return value;
306
+ }
307
+ }