nanoodle 0.1.0__tar.gz

nanoodle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nanoodle contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nanoodle-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# sdist contents: package sources + docs; tests stay in the repo
+# (the default template would ship tests/test_*.py without their
+# harness/fixtures — a broken subset, so exclude them entirely)
+prune tests
+recursive-include docs *.md

nanoodle-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: nanoodle
+Version: 0.1.0
+Summary: Run nanoodle visual AI workflows from Python — zero-dependency executor for saved noodle-graph.json files
+Author: 255BITS
+License: MIT
+Project-URL: Homepage, https://nanoodle.io
+Project-URL: Repository, https://github.com/255BITS/nanoodle-py
+Keywords: nanoodle,nanogpt,workflow,ai,generative,image,video,audio,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nanoodle
+
+Run [nanoodle](https://nanoodle.io) AI workflows server-side. Build a workflow visually in the
+nanoodle editor, hit 💾 to download `noodle-graph.json`, and re-execute it anywhere Python runs —
+against the same [NanoGPT](https://nano-gpt.com) API the app uses.
+
+- **Zero runtime dependencies** (Python >= 3.9, stdlib only)
+- Same execution semantics as the app: topological order, concurrent lanes, wired-field overrides
+- Text, image, video (submit + poll), audio (sync + async poll), vision, transcription
+- Cost tracking per node and per run
+
+## Quickstart
+
+```bash
+pip install nanoodle
+export NANOGPT_API_KEY=...   # nano-gpt.com API key (or OAuth access token)
+```
+
+```python
+from nanoodle import Workflow
+
+wf = Workflow.load("noodle-graph.json")
+result = wf.run({"Text": "a cozy ramen shop on a rainy night"})
+result["Image"].save("ramen.png")            # media outputs are MediaRef (url + bytes()/save())
+print(result.cost_usd, result.remaining_balance)
+```
+
+With the starter graph from the app (text → LLM prompt-writer → image), that's the whole program.
+
+### Discover a workflow's interface
+
+```python
+wf.inputs    # [InputSpec(key="Text", node_id="n1", field="text", kind="textarea", ...)]
+wf.outputs   # [OutputSpec(key="Image", node_id="n3", type="image", ports=["image"])]
+wf.settings  # [SettingSpec(key="n3.size", kind="select", default="1k", ...)]
+```
+
+Input keys resolve flexibly (case-insensitive): the node's custom name, `nodeId.field`
+(`"n2.system"`), or the input's label when unique. A workflow with exactly one required
+input also accepts a bare value: `wf.run("hello")`.
+
+### Media inputs
+
+```python
+from nanoodle import media_from_file
+
+wf.run({"Image": media_from_file("photo.jpg")})            # local file
+wf.run({"Image": "https://example.com/photo.jpg"})         # hosted or data: URL
+wf.run({"Image": raw_bytes})                               # raw bytes (MIME sniffed)
+```
+
+Media is sent inline as base64 (NanoGPT has no upload endpoint); files over ~4.4 MB
+(~3.5 MB for transcription) are refused locally with a clear error before any paid call.
+
+### Settings, progress, errors
+
+```python
+result = wf.run(
+    {"Text": "sunset harbor"},
+    settings={"n3.model": "flux-dev", "n3.size": "1k"},
+    timeout=600,
+    on_progress=lambda evt: print(evt["type"], evt.get("name", "")),
+)
+```
+
+`run()` raises `RunError` when an output (sink) node failed — `error.result` still carries
+the partial results, per-node statuses, and cost so far. Failures in lanes no output depends
+on only surface in `result.errors`. Unknown/unsupported node types, missing required inputs,
+bad keys, and a missing API key all fail **before** anything is spent.
+
+### CLI
+
+Installed as `nanoodle-py` (and `python -m nanoodle` always works):
+
+```bash
+nanoodle-py inspect graph.json
+nanoodle-py run graph.json --input Text="a cozy ramen shop" --set n3.size=1k --out ./out
+nanoodle-py run graph.json --input n2.system=@style.txt --json
+nanoodle-py run graph.json --env-file .env --input Text="hello"   # NANOGPT_API_KEY from a .env file
+```
+
+`--out DIR` saves media outputs to files; `--json` prints a machine-readable result;
+`--env-file PATH` loads `.env`-style `KEY=VALUE` lines (existing environment variables win).
+
+## Supported nodes
+
+| runs | node types |
+|---|---|
+| local | text, upload (image/audio/video), choice, join, comment |
+| NanoGPT | llm (incl. vision + audio input), image, draw, edit, inpaint*, vision, tvideo, ivideo, vedit, lipsync, music, remix, tts, transcribe |
+| **not supported** (browser-only media processing) | resize, vframes, combine, soundtrack, trim, extractaudio |
+
+Workflows containing unsupported node types load with a warning and fail fast at `run()` with
+`UnsupportedNodeError` — before any network call.
+
+\* inpaint caveat: the browser app composites the mask onto black at the source's pixel size;
+this library passes your mask through verbatim, so supply a black/white mask matching the
+source dimensions.
+
+## Use it as an agent skill
+
+A saved workflow plus a short `SKILL.md` playbook makes a skill any coding agent can run —
+Claude Code (`.claude/skills/<name>/SKILL.md`) or anything that reads markdown and runs shell.
+Recipe + copy-pasteable template: [docs/agent-skills.md](docs/agent-skills.md); complete
+example: [examples/agent-skill/poster-generator/](examples/agent-skill/poster-generator/).
+
+## Cost
+
+You bring your own NanoGPT API key; NanoGPT bills your balance per generation and reports the
+price on each response. `result.cost_usd` totals it and `result.cost_exact` turns `False` when
+any call omitted a price (the total is then a floor). `result.remaining_balance` is the freshest
+balance the API reported. A price of 0 means known-included (subscription), not unknown.
+No telemetry, no analytics, and your API key is never logged.
+
+## Testing
+
+Tests run fully offline against a mock NanoGPT server (`tests/harness/`):
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+An opt-in live probe (spends a fraction of a cent) exists for hand-verification:
+`python3 scripts/live-spot-check.py` (add `--image` to also run the starter graph's image step).
+
+## Docs
+
+Design contract and format/engine/io specs live in [`docs/`](docs/): `DESIGN.md`,
+`SPEC-format.md`, `SPEC-engine.md`, `SPEC-io.md`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Not affiliated with NanoGPT. Build workflows at
+[nanoodle.io](https://nanoodle.io).

nanoodle-0.1.0/README.md

@@ -0,0 +1,134 @@
+# nanoodle
+
+Run [nanoodle](https://nanoodle.io) AI workflows server-side. Build a workflow visually in the
+nanoodle editor, hit 💾 to download `noodle-graph.json`, and re-execute it anywhere Python runs —
+against the same [NanoGPT](https://nano-gpt.com) API the app uses.
+
+- **Zero runtime dependencies** (Python >= 3.9, stdlib only)
+- Same execution semantics as the app: topological order, concurrent lanes, wired-field overrides
+- Text, image, video (submit + poll), audio (sync + async poll), vision, transcription
+- Cost tracking per node and per run
+
+## Quickstart
+
+```bash
+pip install nanoodle
+export NANOGPT_API_KEY=...   # nano-gpt.com API key (or OAuth access token)
+```
+
+```python
+from nanoodle import Workflow
+
+wf = Workflow.load("noodle-graph.json")
+result = wf.run({"Text": "a cozy ramen shop on a rainy night"})
+result["Image"].save("ramen.png")            # media outputs are MediaRef (url + bytes()/save())
+print(result.cost_usd, result.remaining_balance)
+```
+
+With the starter graph from the app (text → LLM prompt-writer → image), that's the whole program.
+
+### Discover a workflow's interface
+
+```python
+wf.inputs    # [InputSpec(key="Text", node_id="n1", field="text", kind="textarea", ...)]
+wf.outputs   # [OutputSpec(key="Image", node_id="n3", type="image", ports=["image"])]
+wf.settings  # [SettingSpec(key="n3.size", kind="select", default="1k", ...)]
+```
+
+Input keys resolve flexibly (case-insensitive): the node's custom name, `nodeId.field`
+(`"n2.system"`), or the input's label when unique. A workflow with exactly one required
+input also accepts a bare value: `wf.run("hello")`.
+
+### Media inputs
+
+```python
+from nanoodle import media_from_file
+
+wf.run({"Image": media_from_file("photo.jpg")})            # local file
+wf.run({"Image": "https://example.com/photo.jpg"})         # hosted or data: URL
+wf.run({"Image": raw_bytes})                               # raw bytes (MIME sniffed)
+```
+
+Media is sent inline as base64 (NanoGPT has no upload endpoint); files over ~4.4 MB
+(~3.5 MB for transcription) are refused locally with a clear error before any paid call.
+
+### Settings, progress, errors
+
+```python
+result = wf.run(
+    {"Text": "sunset harbor"},
+    settings={"n3.model": "flux-dev", "n3.size": "1k"},
+    timeout=600,
+    on_progress=lambda evt: print(evt["type"], evt.get("name", "")),
+)
+```
+
+`run()` raises `RunError` when an output (sink) node failed — `error.result` still carries
+the partial results, per-node statuses, and cost so far. Failures in lanes no output depends
+on only surface in `result.errors`. Unknown/unsupported node types, missing required inputs,
+bad keys, and a missing API key all fail **before** anything is spent.
+
+### CLI
+
+Installed as `nanoodle-py` (and `python -m nanoodle` always works):
+
+```bash
+nanoodle-py inspect graph.json
+nanoodle-py run graph.json --input Text="a cozy ramen shop" --set n3.size=1k --out ./out
+nanoodle-py run graph.json --input n2.system=@style.txt --json
+nanoodle-py run graph.json --env-file .env --input Text="hello"   # NANOGPT_API_KEY from a .env file
+```
+
+`--out DIR` saves media outputs to files; `--json` prints a machine-readable result;
+`--env-file PATH` loads `.env`-style `KEY=VALUE` lines (existing environment variables win).
+
+## Supported nodes
+
+| runs | node types |
+|---|---|
+| local | text, upload (image/audio/video), choice, join, comment |
+| NanoGPT | llm (incl. vision + audio input), image, draw, edit, inpaint*, vision, tvideo, ivideo, vedit, lipsync, music, remix, tts, transcribe |
+| **not supported** (browser-only media processing) | resize, vframes, combine, soundtrack, trim, extractaudio |
+
+Workflows containing unsupported node types load with a warning and fail fast at `run()` with
+`UnsupportedNodeError` — before any network call.
+
+\* inpaint caveat: the browser app composites the mask onto black at the source's pixel size;
+this library passes your mask through verbatim, so supply a black/white mask matching the
+source dimensions.
+
+## Use it as an agent skill
+
+A saved workflow plus a short `SKILL.md` playbook makes a skill any coding agent can run —
+Claude Code (`.claude/skills/<name>/SKILL.md`) or anything that reads markdown and runs shell.
+Recipe + copy-pasteable template: [docs/agent-skills.md](docs/agent-skills.md); complete
+example: [examples/agent-skill/poster-generator/](examples/agent-skill/poster-generator/).
+
+## Cost
+
+You bring your own NanoGPT API key; NanoGPT bills your balance per generation and reports the
+price on each response. `result.cost_usd` totals it and `result.cost_exact` turns `False` when
+any call omitted a price (the total is then a floor). `result.remaining_balance` is the freshest
+balance the API reported. A price of 0 means known-included (subscription), not unknown.
+No telemetry, no analytics, and your API key is never logged.
+
+## Testing
+
+Tests run fully offline against a mock NanoGPT server (`tests/harness/`):
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+An opt-in live probe (spends a fraction of a cent) exists for hand-verification:
+`python3 scripts/live-spot-check.py` (add `--image` to also run the starter graph's image step).
+
+## Docs
+
+Design contract and format/engine/io specs live in [`docs/`](docs/): `DESIGN.md`,
+`SPEC-format.md`, `SPEC-engine.md`, `SPEC-io.md`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Not affiliated with NanoGPT. Build workflows at
+[nanoodle.io](https://nanoodle.io).

nanoodle-0.1.0/docs/DESIGN.md

@@ -0,0 +1,70 @@
+# nanoodle executor libraries — DESIGN (binding decisions)
+
+Two sibling repos, both MIT, both ZERO runtime dependencies:
+- /home/ntc/dev/nanoodle-js  — npm package `nanoodle` (ESM, Node >= 20, built-in fetch, node:test)
+- /home/ntc/dev/nanoodle-py  — PyPI package `nanoodle` (Python >= 3.9, stdlib urllib only, unittest)
+
+Read SPEC-format.md, SPEC-engine.md, SPEC-io.md in this directory first. They are the contract.
+
+## Public API — JS
+```js
+import { Workflow, NanoodleError, UnsupportedNodeError, RunError } from "nanoodle";
+
+const wf = await Workflow.load("noodle-graph.json", { apiKey });   // path, or pass a parsed object / JSON string to Workflow.fromJSON(objOrString, opts)
+wf.inputs    // [{ key, nodeId, field, kind, label, optional, def, options? }]  key = resolved friendly name
+wf.outputs   // [{ key, nodeId, type, ports }]
+wf.settings  // [{ key, nodeId, field, kind, def, options? }]
+
+const result = await wf.run({ "Text": "a cozy ramen shop" }, { settings: { "n3.model": "..." }, timeoutMs, signal, onProgress });
+result.get("Image")          // primary output value of that sink node
+result.outputs               // { [key]: value } (plus node-id keys)
+result.costUsd, result.costExact, result.remainingBalance
+result.nodes                 // per-node { status, out, error, costUsd, ms }
+result.errors                // [] of { nodeId, name, message }
+```
+- run() REJECTS with RunError when any SINK node failed (RunError carries .result with partials). Non-sink failure that no sink depends on → warning in result.errors only. (A failed non-sink makes its downstream sinks fail with "upstream failed: <name>" — so effectively any failure that matters rejects.)
+- Media values: class MediaRef { url (data: or https), mime?, async bytes(), async save(path), toString() → url }. Text outputs are plain strings. Inputs accept: string (text), data: URL, https URL, Buffer/Uint8Array (+ mime option via {data, mime}), or local file path via Workflow helpers (mediaFromFile(path)).
+- onProgress(evt): { type: "node-start"|"node-done"|"node-error"|"poll", nodeId, name, ... }.
+- Constructor opts: { apiKey = process.env.NANOGPT_API_KEY, baseUrl = "https://nano-gpt.com", fetch = globalThis.fetch, pollIntervals, timeouts } — injectable fetch/baseUrl is what the test harness uses.
+
+CLI (bin/nanoodle.mjs, "nanoodle" bin entry):
+```
+nanoodle run graph.json --input Text="a cozy ramen shop" --input n2.system=@file.txt --set n3.size=1k --out ./out [--json]
+nanoodle inspect graph.json      # prints inputs/outputs/settings + node table
+```
+--out saves media outputs to files (fetch https, decode data:), prints text outputs; --json prints machine-readable result.
+
+## Public API — Python (mirror, pythonic)
+```python
+from nanoodle import Workflow, NanoodleError, UnsupportedNodeError, RunError, media_from_file
+
+wf = Workflow.load("noodle-graph.json", api_key=None)   # env NANOGPT_API_KEY fallback; Workflow.from_dict(d) too
+wf.inputs / wf.outputs / wf.settings                     # lists of dataclasses, same fields as JS
+result = wf.run({"Text": "a cozy ramen shop"}, settings=None, timeout=None, on_progress=None)
+result["Image"]              # __getitem__ = outputs lookup (friendly key or node id)
+result.outputs, result.cost_usd, result.cost_exact, result.remaining_balance, result.nodes, result.errors
+```
+- Sync API (urllib + concurrent.futures ThreadPoolExecutor for node concurrency). Same RunError semantics.
+- MediaRef: .url, .mime, .bytes(), .save(path), __str__ → url.
+- Injectable transport: Workflow(..., base_url=..., http=callable) for the harness (default small urllib wrapper).
+- CLI: `python -m nanoodle run|inspect ...` mirroring the JS flags.
+
+## Shared behaviors (both)
+- run() input validation UPFRONT: unknown input key → error listing valid keys; missing required input with empty field default → error naming it; no API key while graph has network nodes → error BEFORE any node runs.
+- Unsupported node types (resize/vframes/combine/soundtrack/trim/extractaudio) and unknown types that must RUN → UnsupportedNodeError at run start (fail fast, before spending), naming node + type. Workflow.load only warns.
+- No locale suffix, no catalog fetch, no seed skip-cache, no telemetry/analytics of ANY kind. Never log the API key. Media over 4.4MB inline → clear local error.
+- Version: 0.1.0.
+
+## Repo layout (each)
+README.md (quickstart: download the save from https://nanoodle.io → 3-line usage; the starter-graph example; supported node matrix; cost note; link to nanoodle app)
+LICENSE (MIT, "Copyright (c) 2026 nanoodle contributors")
+src/... (js: src/*.mjs re-exported from src/index.mjs; py: src/nanoodle/*.py)
+tests/ (harness + unit tests; node:test / unittest — NO third-party test deps)
+tests/fixtures/*.json (starter graph copy + purpose-built graphs: join/choice chain, llm-vision, edit multi-image, video poll, tts binary, music async-poll, transcribe, unsupported-node, cycle, field-override, duplicate-names, unknown-key errors)
+tests/harness/ mock NanoGPT server (js: node:http; py: http.server in a thread) — canned per-endpoint responses, records every request (method/path/headers/body) for payload assertions, scriptable sequences (video pending→pending→completed; audio runId→poll; 401/402 errors; binary audio response with x-cost header).
+scripts/live-spot-check.{mjs,py} — OPT-IN live test: reads NANOGPT_API_KEY from env or --env-file, runs fixture text→llm (model zai-org/glm-5.2, maxTokens 60) and prints text + cost; --image flag additionally runs the starter graph image step. NEVER run by CI.
+.github/workflows/test.yml — offline unit tests only, on push.
+.gitignore (node_modules, dist, __pycache__, .env, out/)
+
+## Test plan (harness-first; the workflow phase will extend it)
+Cover at minimum: graph load/aliases/link-migration/unknown-type; topo order + cycle error; concurrency (two parallel lanes both hit server); wiring incl. field override via textarea port; input derivation + all key-resolution orders + ambiguity errors + bare-scalar single-input; settings override + wired-field-refused; every network node type's payload EXACTLY (assert recorded body against spec) + response parse incl. b64 mime sniff, draw message.images, video poll loop + failure + timeout, audio JSON-url/JSON-runId-poll/binary branches, transcribe multipart (assert field name "file"); cost extraction priority incl. zero-cost-kept and header fallback; 401/402/500 error mapping; RunError partial results; MediaRef bytes/save; unsupported node fail-fast BEFORE any network call; no Authorization header leak in errors/repr.

nanoodle-0.1.0/docs/SPEC-engine.md

@@ -0,0 +1,127 @@
+# Nanoodle Run Engine — server-side re-implementation spec
+
+Blueprint = play.html RUNTIME_JS (the exported-app runtime). Line refs are play.html.
+
+## Endpoints & auth
+```
+NANOGPT = https://nano-gpt.com
+IMG_ENDPOINT   POST {NANOGPT}/v1/images/generations      (note: NOT /api/v1)
+CHAT_ENDPOINT  POST {NANOGPT}/api/v1/chat/completions
+VIDEO submit   POST {NANOGPT}/api/generate-video
+VIDEO poll     GET  {NANOGPT}/api/video/status?requestId=<id>
+AUDIO speech   POST {NANOGPT}/api/v1/audio/speech        (music + tts + remix)
+AUDIO poll     GET  {NANOGPT}/api/tts/status?<qs>
+TRANSCRIBE     POST {NANOGPT}/api/v1/audio/transcriptions   (multipart)
+Catalogs (public, no key): /api/v1/models?detailed=true, /api/v1/image-models,
+                           /api/v1/video-models, /api/v1/audio-models
+```
+Every JSON call: `Content-Type: application/json` + BOTH `Authorization: Bearer <key>` and `x-api-key: <key>`.
+Multipart transcribe: the two auth headers, NO explicit Content-Type (let the http lib set boundary). File form field MUST be named "file"; also fields `model`, optional `language`.
+
+All media is inlined as base64 `data:` URLs in JSON bodies (no upload endpoint). MEDIA_INLINE_MAX = 4.4MB — guard locally and raise a clear error above it. Chat runs NON-STREAMING (no `stream` key); parse `r.json()` once.
+
+Model strings pass through VERBATIM (`body.model = node.fields.model`). Missing model → error "pick a model first". Endpoint choice is by node TYPE, never by model lookup. The catalog is optional/best-effort (capability gating + clamps); the library must run fine with no catalog fetch.
+
+## Per-node payloads
+
+### llm → CHAT_ENDPOINT (genChat 1481-1504, run 2574-2603)
+```
+body = { model, messages, temperature: 0.8 }
+if maxTokens          body.max_tokens = +maxTokens
+if format == "JSON"   body.response_format = { type: "json_object" }
+if reasoningEffort set and != "default"  body.reasoning_effort = value
+```
+messages: optional {role:"system", content: fields.system} then user message.
+User content = plain string prompt, UNLESS wired images (img1,img2,... sorted by index) or wired audio:
+then array `[{type:"text",text:prompt}, {type:"image_url",image_url:{url:<value verbatim>}}..., audioPart?]`.
+audioPart = `{type:"input_audio", input_audio:{data:<base64 body, no data: prefix>, format:"mp3"|"wav"|...}}`.
+prompt = wired `prompt` port value ?? fields.prompt; error "no prompt" if empty.
+Parse: `j.choices[0].message.content` (if array, join `.map(p=>p.text)`); throw "no text in response" if null/empty.
+(withLocale non-English system suffix: SKIP in the library / make opt-in.)
+
+### vision → same as llm: one user message [{text: q||"Describe this image."}, {image_url: inp.image}]
+
+### image / edit / inpaint → IMG_ENDPOINT (genImage 1465-1480)
+```
+body = { model, size: fields.size || "1024x1024", n: variations||1, response_format: "b64_json" }
+if prompt        body.prompt = prompt
+if source image  body.imageDataUrl = <string OR array of strings (edit multi-ref)>
+if mask          body.maskDataUrl = <mask data URL; white = repaint>
++ seed (when numeric), + customCivitaiAir (model "custom-civitai"), + LoRA params
+```
+- image node: `variations` → n (multi output = j.data list).
+- edit: sources from wired `image, image2, ...` ports; single → string, multiple → array. Prompt may be empty for upscaler models — do not hard-require.
+- inpaint: source+mask from ports or fields. (Browser composites mask onto black at source size via canvas; library v1: pass mask through verbatim and document the caveat.)
+Parse: `j.data[]` → `d.b64_json ? "data:<sniffed mime>;base64,"+b64 : d.url`. Sniff mime from magic bytes (PNG \x89PNG, JPEG \xFF\xD8, GIF, WEBP RIFF....WEBP; default image/png). Throw "no image in response" if empty.
+
+### draw → CHAT_ENDPOINT (genChatImage 1508-1523)
+body = {model, messages, temperature:0.8} (no response_format). Wired images like llm.
+Parse: images from `j.choices[0].message.images[]` → `im.image_url.url || im.url || im`; text from message.content (may be null — fine).
+
+### tvideo / ivideo / vedit / lipsync → submit + poll (genVideo 1527-1588)
+```
+body = { model, prompt }
++ dims from node fields: aspect → aspect_ratio, duration → duration, resolution → resolution
+  (catalog can rename e.g. aspect→orientation / duration→seconds; WITHOUT catalog use the standard names)
++ ivideo/lipsync source image → body.imageDataUrl (data: or https, verbatim)
++ ivideo wired endframe → body.last_image
++ vedit source: https URL → body.videoUrl ; local data → body.videoDataUrl
++ lipsync audio: https → body.audioUrl ; local → body.audioDataUrl
++ Object.assign(body, fields.modelOpts || {})   (per-model knobs incl. seed)
++ tvideo wired ref1.. → body.reference_images (array) — catalog may rename key; default "reference_images"
+```
+Submit response: `runId = j.runId || j.id`. Then poll every 5s: GET /api/video/status?requestId=<runId>.
+status = (s.data?.status || s.status).toUpperCase().
+COMPLETED|SUCCEEDED → url = s.data?.output?.video?.url || out.url || out.video?.[0]?.url (out = s.data?.output or s).
+FAILED|ERROR|CANCELED → raise "video failed: " + (s.data?.error || status). Timeout 600s.
+
+### music / tts / remix → AUDIO speech endpoint (genAudio 1591-1637)
+```
+body = { model, input: <wired text ?? fields.prompt> } + params
+music params: lyrics, instrumental(bool), duration(number), negative_prompt, seed, response_format(default "mp3")
+tts params:   voice, speed(omit when 1), instructions, response_format(default "mp3")
+remix params: lyrics, duration, response_format + body.audio = <source: https as-is | local data URL>
++ merge fields.extraJson (parsed object) verbatim last
+Omit empty params. (Catalog gating of voice/duration: skip in v1 — send what the node has.)
+```
+Response handling:
+- content-type JSON → url = j.url||j.audioUrl||j.data?.url||j.data?.audioUrl; if none but j.runId||j.id → poll
+  GET /api/tts/status?runId=..&model=..&cost=..&paymentSource=..&isApiRequest=true every 3s;
+  status lowercase: completed|succeeded → s.audioUrl||s.url||s.data?.audioUrl||s.data?.url;
+  error|failed|content_policy_violation → raise. Timeout 300s.
+- else BINARY body → the audio bytes; mime from response content-type (pin from requested format if generic).
+  Library returns bytes+mime (a data: URL or MediaRef), not an object URL.
+
+### transcribe → multipart (1641-1666)
+FormData: file=<audio blob> (field name "file"), model, language?. Local guard: >3.5MB raise.
+Parse: `j.transcription ?? j.text ?? j.data?.transcription ?? j.data?.text`.
+
+## Cost extraction (costFromJson 998-1013)
+USD priority: j.cost (if >0) → j.x_nanogpt_pricing.(costUsd|cost|amount) → j.metadata?.cost → header x-cost / x-nano-cost.
+Balance: header x-remaining-balance (wins) → j.remainingBalance → x_nanogpt_pricing.remainingBalance.
+Present-but-zero = known-included (subscription), keep 0. Absent → cost unknown (mark total inexact).
+
+## HTTP errors (922-935)
+- 401/403 → auth error ("API key rejected").
+- 402 OR body matching /insufficient|balance|funds|not enough|payment required/i → out-of-funds error.
+- else → error "<status>: <body first 160 chars>".
+No streaming retries needed (engine is non-streaming). Poll GET failures: silently continue the loop until timeout.
+
+## Execution (runGraph 3000-3133)
+1. Alias/filter nodes (materialize): audio→tts, drop unknown types + orphaned links, migrate music/tts inbound "text" port → "prompt".
+2. Kahn topological order; cyclic → error naming the cyclic nodes.
+3. Concurrency: node starts when ITS deps finish (siblings run concurrently). Library: same semantics (asyncio / Promise per node).
+4. Input resolution per node: for declared ports, value = srcNode.out[from.port]. Dynamic families: img\d+ / image\d*, vid\d+, clip\d+, audio, endframe, ref\d+, frame\d+ (vframes outputs). ANY other inbound link = FIELD OVERRIDE: run with fields = {...fields, [port]: value} (that's how wired prompt/system/lyrics/q override typed values).
+5. Node failure: record error for that node, continue independent lanes (library default: collect; raise at end if a sink failed — see DESIGN).
+6. comment nodes never run. Fixed-seed skip-cache: optional for a library (stateless one-shot runs don't need it) — SKIP in v1.
+
+## Local nodes to IMPLEMENT (pure logic)
+- text: out.text = fields.text
+- upload/aupload/vupload: out = the stored/provided data URL
+- choice: options = fields.options.split("\n") non-empty trimmed; out = fields.selected if in options else first; error if no options
+- join: [a,b].filter(non-empty).join(sep) where sep = fields.sep ?? " ", literal "\\n" in sep means newline
+- comment: skip
+
+## Local nodes UNSUPPORTED in v1 (browser media ops — raise UnsupportedNodeError naming node + type)
+resize, vframes, combine, soundtrack, trim, extractaudio.
+Error message must say: "node type 'X' does local media processing that requires the nanoodle browser app; not supported by this library yet".

nanoodle-0.1.0/docs/SPEC-format.md

@@ -0,0 +1,70 @@
+# Nanoodle Workflow JSON Format (the downloadable "save")
+
+Verified against /home/ntc/dev/nanoodle/index.html (editor). The 💾 Save button writes
+`noodle-graph.json` = exactly `JSON.stringify(serializeGraph(), null, 2)` — no wrapper.
+
+## Top-level shape
+```json
+{
+  "v": 1,
+  "nodes": [ { "id":"n1", "type":"text", "x":60, "y":130, "fields":{...}, "w":220, "sizes":{"system":120}, "name":"optional custom name" } ],
+  "links": [ { "id":"l1", "from":{"node":"n1","port":"text"}, "to":{"node":"n2","port":"prompt"} } ],
+  "nid": 4, "lid": 3,
+  "view": { "panX":40, "panY":60, "scale":1 }
+}
+```
+- `v` — always 1.
+- Node: `id` (string "nN"), `type` (NODE_TYPES key), `x/y/w/sizes` layout-only (ignore), `fields` (param bag, type-specific), `name` (optional user label — the display name).
+- Link: `{id, from:{node,port}, to:{node,port}}`.
+- `nid/lid/view` — editor counters/camera; ignore for execution.
+- ALL keys except `nodes` are optional to a loader: `d.nodes||[]`, `d.links||[]`. Accept `{nodes, links}` minimal form.
+
+## Loader semantics (applyGraphData, index.html:8815-8860) — REPLICATE THESE
+- Type alias: `audio` → `tts` (legacy).
+- Unknown node type → node silently skipped (library: keep node but error only if it must run — see DESIGN; simplest faithful behavior: drop unknown-type nodes AND their links, but surface a warning).
+- Links kept only if BOTH endpoints exist after node filtering.
+- Migration: links into a `music`/`tts` node with `to.port === "text"` are rewritten to `"prompt"`.
+- Media fields are `data:` URLs inline in `fields` (image/audio/video/mask). Share links may have them blanked to "".
+
+## Node type registry (NODE_TYPES, index.html:5015-5679)
+Port kinds: text | image | audio | video. Only matching kinds connect.
+Every `<textarea>` field is also a wireable text input port with port name == field name
+(EXCEPT on node types `text`, `choice`, comments, and the `extraJson` field). A wire into a
+field-port overrides the typed field value at run time.
+
+| type | title | static inputs | dynamic inputs | outputs | key fields |
+|---|---|---|---|---|---|
+| text | Text | — | — | text:text | text (the literal value; NOT wireable) |
+| upload | Image input | — | — | image:image | image (data: URL) |
+| aupload | Audio input | — | — | audio:audio | audio (data: URL) |
+| vupload | Video input | — | — | video:video | video (data: URL) |
+| choice | Choice | — | — | text:text | options (newline-separated), selected |
+| join | Join | a:text, b:text | — | text:text | sep (default " "; literal "\n" means newline) |
+| llm | LLM | — | img1..:image (vision), audio:audio | text:text | model, system, prompt, temperature, maxTokens, format(Text\|JSON), reasoningEffort, showThinking |
+| image | Image | — | — | image:image | model, prompt, size, variations, seed, customCivitaiAir |
+| draw | Draw | — | img1..:image | image:image, text:text | model, system, prompt, showThinking |
+| edit | Edit | — | image,image2..:image | image:image | model, prompt, size, seed |
+| inpaint | Inpaint | image:image, mask:image | — | image:image | model, prompt, size, seed, brush |
+| resize | Resize/crop | image:image | — | image:image | mode(fit\|fill\|exact), width, height (LOCAL) |
+| vision | Vision | image:image | — | text:text | model, q |
+| tvideo | Text→Video | — | ref1..:image | video:video | model, prompt, duration, aspect, resolution, modelOpts |
+| ivideo | Image→Video | image:image | endframe:image | video:video | model, prompt, duration, aspect, resolution, modelOpts |
+| vedit | Video edit | video:video | — | video:video | model, prompt, resolution, modelOpts |
+| vframes | Video→frames | video:video | — | frame1..frameN:image (dynamic, fields.frames) | frames(1-12), gap, dir(end\|start) (LOCAL) |
+| combine | Combine videos | — | clip1..:video | video:video | dedup (LOCAL) |
+| soundtrack | Soundtrack | video:video, audio:audio | — | video:video | loop (LOCAL) |
+| lipsync | Avatar/lipsync | image:image, audio:audio | — | video:video | model, prompt, resolution, modelOpts |
+| music | Music | — | — | audio:audio | model, prompt, lyrics, instrumental, duration, negative_prompt, seed, extraJson |
+| remix | Remix audio | audio:audio | — | audio:audio | model, prompt, lyrics, duration, extraJson |
+| tts | Speech | — | — | audio:audio | model, prompt, voice, speed, instructions, extraJson |
+| trim | Trim audio | audio:audio | — | audio:audio | start, length (LOCAL) |
+| extractaudio | Extract audio | video:video | — | audio:audio | start, length (LOCAL) |
+| transcribe | Transcribe | audio:audio | — | text:text | model, language |
+| comment | Comment | none (note:true, never runs) | — | — | text, color |
+
+Display name resolution (play.html `displayName`): `node.name` (trimmed, if set) → NODE_TYPES[type].title → type → "?".
+
+## Canonical fixture
+/home/ntc/dev/nanoodle/noodle-graph.json — starter graph: text("a cozy ramen shop on a rainy night")
+→ llm(model "zai-org/glm-5.2", system prompt-writer) → image(model "nano-banana-2-lite", size "1k", variations "1").
+Wire n1.text→n2.prompt, n2.text→n3.prompt.

nanoodle-0.1.0/docs/SPEC-io.md

@@ -0,0 +1,45 @@
+# Nanoodle Workflow Public Interface (inputs / outputs / naming)
+
+## Inputs — deriveInputs (play.html 3140-3206)
+An input = an INPUT_SPECS field on a node that is NOT fed by a wire (`links.some(l => l.to.node===id && l.to.port===field)` → hidden).
+
+INPUT_SPECS table (only these node types contribute; kind in parens):
+- text: text (textarea)
+- upload: image (image) · aupload: audio (audio) · vupload: video (video)
+- llm: prompt (textarea, required); system (textarea, OPTIONAL, def "You are a helpful, concise assistant.")
+- image: prompt · tvideo: prompt · music: prompt · remix: prompt · tts: prompt (all textarea, required)
+- draw: prompt (required); system (optional)
+- inpaint (special): prompt ("What to paint in"); image and/or mask when not wired
+- choice (special): field `selected`, kind choice, options from fields.options newline-split
+
+Required unless marked optional. `def` = prefilled default.
+
+## Input NAMING (for run({name: value}) resolution)
+- Node display name = node.name (trimmed) → NODE_TYPES[type].title → type.
+- The app labels an input with its generic spec label ("Image prompt", "Text", ...), EXCEPT:
+  when a node contributes exactly ONE required input AND has a custom name, that custom name is the label (PR #138).
+- upload nodes feeding role ports get role labels ("End frame", "Reference N", "Image N") — UI nicety; library can skip.
+- Unique key = (nodeId, field). LIBRARY RESOLUTION ORDER for a user-supplied key (case-insensitive, trimmed):
+  1. exact node custom name (if that node has exactly one derived input → that input; ambiguous → error listing candidates)
+  2. "nodeId.field" (e.g. "n2.prompt") and bare nodeId (if single input on the node)
+  3. the input's label / field name if unique across inputs
+  Unknown key → error listing available input names.
+- If the workflow has exactly one required input, allow a bare scalar: run("hello").
+
+## Settings — deriveSettings (play.html 3229-3328)
+Per-node knobs (model, size, temperature, duration, voice, seed, ...) that are NOT part of IO shape.
+Library: expose overrides via run(..., settings={...}) resolved the same way (name/nodeId.field), applied as
+node.fields[field] = value before execution. Same wired-hides rule (cannot override a wired field via settings).
+
+## Outputs — deriveOutputs (play.html 3208-3214)
+Output nodes = nodes with a non-empty outputs list AND no outgoing link (sinks). No explicit marker.
+Result value = node.out[NODE_TYPES[type].outputs[0].name] (primary port). draw also has secondary text; expose all ports.
+Result keying: displayName(node) (custom name → type title); on duplicate display names, suffix " 2", " 3" in topo order; always ALSO keyed by node id.
+Intermediate nodes still run; expose them under result.nodes / result.steps for debugging.
+
+## Key & auth
+- One key: NanoGPT API key (or OAuth access token — identical usage).
+- Headers on every call: Authorization: Bearer <key> AND x-api-key: <key>.
+- Library: constructor arg api_key, fallback env NANOGPT_API_KEY. No key + graph has network nodes → clear upfront error.
+- Balance: /api/check-balance POST {} returns {usd_balance} with ACAO * (works server-side fine). Optional helper.
+- Whole-graph runs only (like exported apps). No subset/runGroup in v1.