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.
Files changed (2) hide show
  1. package/README.md +83 -49
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,17 +1,30 @@
1
- # nanoodle
1
+ # nanoodle (JavaScript)
2
2
 
3
- **Run [nanoodle](https://nanoodle.io) visual AI workflows from JavaScript.** nanoodle is a
4
- no-server, bring-your-own-key editor where you wire AI nodes (LLMs, image, video, audio) into a
5
- graph and download it as `noodle-graph.json`. This package is the zero-dependency executor for
6
- those files: load a saved workflow, feed it inputs, get its outputs — same execution semantics
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
- - Zero runtime dependencies — Node >= 20, built-in `fetch`
12
- - Text, image, video (submit + poll), audio (sync + async poll), vision, transcription
13
- - Cost tracking per node and per run
14
- - Library and CLI in one install
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
+ ![Pipeline: nanoodle editor → noodle-graph.json → JS executor → NanoGPT API](docs/diagram-pipeline.jpg)
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
+ ![Execution: Workflow.load → wf.run → topological order / concurrent lanes → result](docs/diagram-execution.jpg)
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 outputs: MediaRef (url + bytes()/save())
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 from the app (text → LLM prompt-writer → image), that's the whole program.
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 — it's offline and shows the workflow's inputs, outputs, and settings:
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 (this calls the NanoGPT API and spends from your balance):
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` reads `NANOGPT_API_KEY` from a `.env`-style file (`--key` wins if both are
53
- given). `--input k=@path` reads a file — media files ride as media, `.txt`/`.md`/`.json` as
54
- text. `--out dir` saves media outputs to disk; `--json` prints a machine-readable result.
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 resolve flexibly (case-insensitive): the node's custom name (`"Text"`),
65
- `nodeId.field` (`"n2.system"`), a bare node id, or the input's label. Output keys are the sink
66
- node's custom name (or its type name). A workflow with exactly one required input also accepts
67
- a bare value: `wf.run("hello")`. Settings use `nodeId.field` keys (`"n3.model"`).
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); files over ~4.4 MB
80
- (~3.5 MB for transcription) are refused locally with a clear error before any paid call.
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 failed — `err.result` still carries
96
- the partial results, per-node statuses, and cost so far. Failures in lanes no output depends on
97
- only surface in `result.errors`. Unknown/unsupported node types, missing required inputs, bad
98
- keys, and a missing API key all fail **before** anything is spent.
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 containing unsupported node types load with a warning and fail fast at `run()` with
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 caveat: the browser app composites the mask onto black at the source's pixel size;
112
- this library passes your mask through verbatim, so supply a black/white mask matching the
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 makes a skill any coding agent can run —
118
- Claude Code (`.claude/skills/<name>/SKILL.md`) or anything that reads markdown and runs shell.
119
- Recipe + copy-pasteable template: [docs/agent-skills.md](docs/agent-skills.md); complete
120
- example: [examples/agent-skill/poster-generator/](examples/agent-skill/poster-generator/).
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
- This is bring-your-own-key: you need a [nano-gpt.com](https://nano-gpt.com) API key (or OAuth
125
- access token) with balance, and **every `run()` spends real money** — NanoGPT bills per
126
- generation. The library reports what each run cost: `result.costUsd` totals the prices NanoGPT
127
- returned, `result.costExact` turns false when any call omitted a price (the total is then a
128
- floor), and `result.remainingBalance` is the freshest balance the API reported. A price of 0
129
- means known-included (subscription), not unknown. `inspect` and loading/validating workflows
130
- never call the API.
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
- The format and execution semantics are specified in [docs/](docs/):
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
- An opt-in live probe (spends a fraction of a cent) exists for hand-verification:
145
- `node scripts/live-spot-check.mjs` (add `--image` to also run the starter graph's image step).
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.io](https://nanoodle.io).
184
+ [nanoodle.com](https://nanoodle.com).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nanoodle",
3
- "version": "0.1.0",
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 \"tests/**/*.test.mjs\""
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.io",
44
+ "homepage": "https://nanoodle.com",
45
45
  "repository": {
46
46
  "type": "git",
47
- "url": "git+https://github.com/255BITS/nanoodle-js.git"
47
+ "url": "git+https://github.com/nanoodlecom/nanoodle-js.git"
48
48
  },
49
49
  "bugs": {
50
- "url": "https://github.com/255BITS/nanoodle-js/issues"
50
+ "url": "https://github.com/nanoodlecom/nanoodle-js/issues"
51
51
  }
52
52
  }