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.
- package/LICENSE +21 -0
- package/README.md +150 -0
- package/bin/nanoodle.mjs +195 -0
- package/package.json +52 -0
- package/src/client.mjs +321 -0
- package/src/errors.mjs +32 -0
- package/src/graph.mjs +134 -0
- package/src/index.mjs +6 -0
- package/src/io.mjs +312 -0
- package/src/media.mjs +157 -0
- package/src/nodes.mjs +441 -0
- package/src/workflow.mjs +307 -0
package/src/workflow.mjs
ADDED
|
@@ -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
|
+
}
|