nanoodle 0.1.0 → 0.1.1
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/README.md +83 -49
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,17 +1,30 @@
|
|
|
1
|
-
# nanoodle
|
|
1
|
+
# nanoodle (JavaScript)
|
|
2
2
|
|
|
3
|
-
**Run
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
as the app (topological order, concurrent lanes, wired-field overrides), against the same
|
|
8
|
-
[NanoGPT](https://nano-gpt.com) API. Build and test workflows visually at
|
|
9
|
-
[nanoodle.io](https://nanoodle.io); automate them here.
|
|
3
|
+
**Run visual AI workflows from Node.js.** Design them in the
|
|
4
|
+
[nanoodle](https://nanoodle.com) editor, save as `noodle-graph.json`, then load
|
|
5
|
+
and re-run them here — same graph, same [NanoGPT](https://nano-gpt.com) API,
|
|
6
|
+
your own key.
|
|
10
7
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
8
|
+
Zero runtime dependencies. Library + CLI in one install.
|
|
9
|
+
|
|
10
|
+
Looking for Python? → **[nanoodle-py](https://github.com/nanoodlecom/nanoodle-py)**
|
|
11
|
+
|
|
12
|
+
## At a glance
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
**Build once, run anywhere.** The browser app is for designing and testing.
|
|
17
|
+
This package is for automating the same workflows in scripts, servers, and
|
|
18
|
+
agents.
|
|
19
|
+
|
|
20
|
+

|
|
21
|
+
|
|
22
|
+
| | |
|
|
23
|
+
|---|---|
|
|
24
|
+
| **Package** | `nanoodle` on npm |
|
|
25
|
+
| **Runtime** | Node ≥ 20 · built-in `fetch` · no deps |
|
|
26
|
+
| **Sibling** | [Python package](https://github.com/nanoodlecom/nanoodle-py) (same graphs, same semantics) |
|
|
27
|
+
| **Editor** | [nanoodle.com](https://nanoodle.com) — wire nodes, hit 💾, download the graph |
|
|
15
28
|
|
|
16
29
|
## Install
|
|
17
30
|
|
|
@@ -27,21 +40,21 @@ import { Workflow } from "nanoodle";
|
|
|
27
40
|
|
|
28
41
|
const wf = await Workflow.load("noodle-graph.json"); // key from NANOGPT_API_KEY
|
|
29
42
|
const result = await wf.run({ Text: "a cozy ramen shop on a rainy night" });
|
|
30
|
-
await result.get("Image").save("ramen.png"); // media
|
|
43
|
+
await result.get("Image").save("ramen.png"); // media: MediaRef (url + bytes()/save())
|
|
31
44
|
console.log(result.costUsd, result.remainingBalance);
|
|
32
45
|
```
|
|
33
46
|
|
|
34
|
-
With the starter graph
|
|
47
|
+
With the app’s starter graph (text → LLM prompt-writer → image), that’s the whole program.
|
|
35
48
|
|
|
36
49
|
## Quickstart (CLI)
|
|
37
50
|
|
|
38
|
-
Inspect first —
|
|
51
|
+
Inspect first — offline; shows inputs, outputs, and settings:
|
|
39
52
|
|
|
40
53
|
```bash
|
|
41
54
|
npx nanoodle inspect graph.json
|
|
42
55
|
```
|
|
43
56
|
|
|
44
|
-
Then run (
|
|
57
|
+
Then run (calls NanoGPT and spends from your balance):
|
|
45
58
|
|
|
46
59
|
```bash
|
|
47
60
|
export NANOGPT_API_KEY=... # or --key K, or --env-file .env
|
|
@@ -49,9 +62,10 @@ npx nanoodle run graph.json --input Text="a cozy ramen shop" --out ./out
|
|
|
49
62
|
npx nanoodle run graph.json --input n2.system=@style.txt --set n3.size=1k --json
|
|
50
63
|
```
|
|
51
64
|
|
|
52
|
-
`--env-file path`
|
|
53
|
-
|
|
54
|
-
|
|
65
|
+
- `--env-file path` — load `NANOGPT_API_KEY` from a `.env`-style file (`--key` wins if both are set)
|
|
66
|
+
- `--input k=@path` — read a file (media as media; `.txt` / `.md` / `.json` as text)
|
|
67
|
+
- `--out dir` — save media outputs to disk
|
|
68
|
+
- `--json` — machine-readable result
|
|
55
69
|
|
|
56
70
|
## Inputs, outputs, settings
|
|
57
71
|
|
|
@@ -61,10 +75,11 @@ wf.outputs // [{ key: "Image", nodeId: "n3", type: "image", ports: [{ name: "i
|
|
|
61
75
|
wf.settings // [{ key: "n3.model", kind: "model", def: "nano-banana-2-lite" }, ...]
|
|
62
76
|
```
|
|
63
77
|
|
|
64
|
-
Input keys
|
|
65
|
-
`nodeId.field` (`"n2.system"`), a bare node id, or the input
|
|
66
|
-
node
|
|
67
|
-
a bare value: `wf.run("hello")`.
|
|
78
|
+
Input keys are flexible (case-insensitive): the node’s custom name (`"Text"`),
|
|
79
|
+
`nodeId.field` (`"n2.system"`), a bare node id, or the input’s label. Output
|
|
80
|
+
keys are the sink node’s custom name (or its type name). A workflow with
|
|
81
|
+
exactly one required input also accepts a bare value: `wf.run("hello")`.
|
|
82
|
+
Settings use `nodeId.field` keys (`"n3.model"`).
|
|
68
83
|
|
|
69
84
|
### Media inputs
|
|
70
85
|
|
|
@@ -76,8 +91,9 @@ await wf.run({ Image: "https://example.com/photo.jpg" }); // hosted URL
|
|
|
76
91
|
await wf.run({ Image: bytesUint8Array }); // raw bytes (MIME sniffed)
|
|
77
92
|
```
|
|
78
93
|
|
|
79
|
-
Media is sent inline as base64 (NanoGPT has no upload endpoint)
|
|
80
|
-
(~3.5 MB for transcription) are refused locally with a clear error
|
|
94
|
+
Media is sent inline as base64 (NanoGPT has no upload endpoint). Files over
|
|
95
|
+
~4.4 MB (~3.5 MB for transcription) are refused locally with a clear error
|
|
96
|
+
before any paid call.
|
|
81
97
|
|
|
82
98
|
### Progress and errors
|
|
83
99
|
|
|
@@ -92,10 +108,11 @@ const result = await wf.run(
|
|
|
92
108
|
);
|
|
93
109
|
```
|
|
94
110
|
|
|
95
|
-
`run()` rejects with `RunError` when an output (sink) node
|
|
96
|
-
|
|
97
|
-
only
|
|
98
|
-
|
|
111
|
+
`run()` rejects with `RunError` when an output (sink) node fails —
|
|
112
|
+
`err.result` still has partial results, per-node statuses, and cost so far.
|
|
113
|
+
Failures in lanes no output depends on only appear in `result.errors`.
|
|
114
|
+
Unknown/unsupported node types, missing required inputs, bad keys, and a
|
|
115
|
+
missing API key all fail **before** anything is spent.
|
|
99
116
|
|
|
100
117
|
## Supported nodes
|
|
101
118
|
|
|
@@ -105,46 +122,63 @@ keys, and a missing API key all fail **before** anything is spent.
|
|
|
105
122
|
| NanoGPT | llm (incl. vision + audio input), image, draw, edit, inpaint*, vision, tvideo, ivideo, vedit, lipsync, music, remix, tts, transcribe |
|
|
106
123
|
| **not supported** (browser-only media processing) | resize, vframes, combine, soundtrack, trim, extractaudio |
|
|
107
124
|
|
|
108
|
-
Workflows
|
|
109
|
-
`UnsupportedNodeError` — before any network call.
|
|
125
|
+
Workflows with unsupported node types load with a warning and fail fast at
|
|
126
|
+
`run()` with `UnsupportedNodeError` — before any network call.
|
|
110
127
|
|
|
111
|
-
\* inpaint
|
|
112
|
-
this library passes your mask through verbatim
|
|
113
|
-
source dimensions.
|
|
128
|
+
\* **inpaint:** the browser app composites the mask onto black at the source
|
|
129
|
+
pixel size; this library passes your mask through verbatim. Supply a
|
|
130
|
+
black/white mask matching the source dimensions.
|
|
114
131
|
|
|
115
132
|
## Use it as an agent skill
|
|
116
133
|
|
|
117
|
-
A saved workflow plus a short `SKILL.md` playbook
|
|
118
|
-
Claude Code
|
|
119
|
-
Recipe
|
|
120
|
-
|
|
134
|
+
A saved workflow plus a short `SKILL.md` playbook is a skill any coding agent
|
|
135
|
+
can run — Claude Code, Cursor, Grok, or anything that reads markdown and runs
|
|
136
|
+
shell. Recipe and template: [docs/agent-skills.md](docs/agent-skills.md).
|
|
137
|
+
|
|
138
|
+
**Example skill** (idea → LLM prompt → poster image):
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
npx skills add nanoodlecom/nanoodle-js@poster-generator -g -y
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Source: [examples/agent-skill/poster-generator/](examples/agent-skill/poster-generator/).
|
|
145
|
+
Media is saved as `Poster.<ext>` (MIME-derived; often `.jpg`) — use the path the
|
|
146
|
+
CLI prints. The Python package ships the same skill name; installing both
|
|
147
|
+
overwrites — pick one runtime (see [agent-skills.md](docs/agent-skills.md)).
|
|
121
148
|
|
|
122
149
|
## API key and cost
|
|
123
150
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
generation.
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
151
|
+
Bring your own [nano-gpt.com](https://nano-gpt.com) API key (or OAuth access
|
|
152
|
+
token) with balance. **Every `run()` spends real money** — NanoGPT bills per
|
|
153
|
+
generation.
|
|
154
|
+
|
|
155
|
+
- `result.costUsd` — total of prices NanoGPT returned
|
|
156
|
+
- `result.costExact` — `false` if any call omitted a price (total is then a floor)
|
|
157
|
+
- `result.remainingBalance` — freshest balance the API reported
|
|
158
|
+
|
|
159
|
+
A price of `0` means known-included (subscription), not unknown. `inspect`
|
|
160
|
+
and loading/validating workflows never call the API. No telemetry, no
|
|
161
|
+
analytics; the API key is never logged.
|
|
131
162
|
|
|
132
163
|
## Specs and testing
|
|
133
164
|
|
|
134
|
-
|
|
165
|
+
Format and execution semantics live in [docs/](docs/):
|
|
135
166
|
[DESIGN.md](docs/DESIGN.md), [SPEC-format.md](docs/SPEC-format.md),
|
|
136
167
|
[SPEC-engine.md](docs/SPEC-engine.md), [SPEC-io.md](docs/SPEC-io.md).
|
|
137
168
|
|
|
169
|
+
Same contract as the [Python package](https://github.com/nanoodlecom/nanoodle-py).
|
|
170
|
+
|
|
138
171
|
Tests run fully offline against a mock NanoGPT server (`tests/harness/`):
|
|
139
172
|
|
|
140
173
|
```bash
|
|
141
174
|
npm test
|
|
142
175
|
```
|
|
143
176
|
|
|
144
|
-
|
|
145
|
-
`node scripts/live-spot-check.mjs` (add `--image` to also run the starter
|
|
177
|
+
Opt-in live probe (spends a fraction of a cent):
|
|
178
|
+
`node scripts/live-spot-check.mjs` (add `--image` to also run the starter
|
|
179
|
+
graph’s image step).
|
|
146
180
|
|
|
147
181
|
## License
|
|
148
182
|
|
|
149
183
|
MIT — see [LICENSE](LICENSE). Not affiliated with NanoGPT. Build workflows at
|
|
150
|
-
[nanoodle.
|
|
184
|
+
[nanoodle.com](https://nanoodle.com).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nanoodle",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Run nanoodle visual AI workflows from JavaScript — zero-dependency executor for saved noodle-graph.json files",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/index.mjs",
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"node": ">=20"
|
|
17
17
|
},
|
|
18
18
|
"scripts": {
|
|
19
|
-
"test": "node --test
|
|
19
|
+
"test": "node --test"
|
|
20
20
|
},
|
|
21
21
|
"files": [
|
|
22
22
|
"src",
|
|
@@ -41,12 +41,12 @@
|
|
|
41
41
|
"zero-dependencies"
|
|
42
42
|
],
|
|
43
43
|
"license": "MIT",
|
|
44
|
-
"homepage": "https://nanoodle.
|
|
44
|
+
"homepage": "https://nanoodle.com",
|
|
45
45
|
"repository": {
|
|
46
46
|
"type": "git",
|
|
47
|
-
"url": "git+https://github.com/
|
|
47
|
+
"url": "git+https://github.com/nanoodlecom/nanoodle-js.git"
|
|
48
48
|
},
|
|
49
49
|
"bugs": {
|
|
50
|
-
"url": "https://github.com/
|
|
50
|
+
"url": "https://github.com/nanoodlecom/nanoodle-js/issues"
|
|
51
51
|
}
|
|
52
52
|
}
|