@sateeshreddy/n8n-nodes-nvidia-nim 0.1.1 → 1.0.3

package/README.md

@@ -1,21 +1,245 @@
+<div align="center">
+
+<img src="https://upload.wikimedia.org/wikipedia/commons/a/a4/NVIDIA_logo.svg" height="48" alt="NVIDIA Logo" />
+
 # n8n-nodes-nvidia-nim
 
-n8n community node for NVIDIA NIM (build.nvidia.com). Allows calling any free model from NVIDIA NIM directly in n8n workflows.
+**Connect any free NVIDIA NIM language model to your n8n workflows — in one node.**
+
+[![npm version](https://img.shields.io/npm/v/n8n-nodes-nvidia-nim?color=76b900&label=npm&style=flat-square)](https://www.npmjs.com/package/n8n-nodes-nvidia-nim)
+[![n8n community node](https://img.shields.io/badge/n8n-community%20node-EA4B71?style=flat-square&logo=n8n)](https://n8n.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+</div>
+
+---
+
+## Overview
+
+`n8n-nodes-nvidia-nim` is an n8n community node that gives you access to **NVIDIA NIM's free hosted language models** directly inside your workflows.  
+It plugs into n8n's **AI Agent** as a drop-in language model — just like the built-in OpenAI or Anthropic nodes.
+
+### Why use this?
+
+- ✅ Free tier models via [build.nvidia.com](https://build.nvidia.com)
+- ✅ Works as a proper **AI sub-node** (connect to any AI Agent)  
+- ✅ Supports 17+ models including Llama 4, Mistral, Qwen3, Gemma, and more
+- ✅ Drop-in OpenAI-compatible API — no extra setup
+
+---
+
+## Supported Models
+
+| Model | Value |
+|---|---|
+| Llama 4 Maverick 17B 128E Instruct *(default)* | `meta/llama-4-maverick-17b-128e-instruct` |
+| Mistral Large 3 675B Instruct | `mistralai/mistral-large-3-675b-instruct-2512` |
+| Qwen3 Coder 480B A35B Instruct | `qwen/qwen3-coder-480b-a35b-instruct` |
+| Mistral Nemotron (Function Calling) | `mistralai/mistral-nemotron` |
+| Mistral Medium 3 Instruct | `mistralai/mistral-medium-3-instruct` |
+| Magistral Small 2506 | `mistralai/magistral-small-2506` |
+| Step 3.5 Flash (Agentic) | `stepfun-ai/step-3.5-flash` |
+| Seed OSS 36B Instruct (Agentic) | `bytedance/seed-oss-36b-instruct` |
+| GLM-4.7 (Tool Calling) | `thudm/glm-4.7` |
+| MiniMax M2.7 | `minimax/minimax-m2.7` |
+| Phi-4 Multimodal Instruct | `microsoft/phi-4-multimodal-instruct` |
+| Gemma 3N E4B IT | `google/gemma-3n-e4b-it` |
+| Gemma 3N E2B IT | `google/gemma-3n-e2b-it` |
+| Gemma 2 2B IT | `google/gemma-2-2b-it` |
+| Dracarys Llama 3.1 70B Instruct | `abacusai/dracarys-llama-3.1-70b-instruct` |
+| Nemotron Mini 4B Instruct | `nvidia/nemotron-mini-4b-instruct` |
+| Solar 10.7B Instruct | `upstage/solar-10.7b-instruct` |
+
+---
 
 ## Installation
 
-1. Copy the `dist` folder to your n8n custom nodes directory (usually `~/.n8n/custom/`).
-2. Restart n8n.
+### Via n8n Community Nodes (Recommended)
+
+1. Open your n8n instance
+2. Go to **Settings → Community Nodes**
+3. Click **Install**
+4. Enter `n8n-nodes-nvidia-nim` and confirm
+
+### Manual Installation
+
+```bash
+# Navigate to your n8n custom nodes directory
+cd ~/.n8n/custom/
+
+# Install the package
+npm install n8n-nodes-nvidia-nim
+```
+
+Then restart n8n.
+
+---
+
+## Getting Your API Key
+
+1. Visit [build.nvidia.com](https://build.nvidia.com)
+2. Sign in or create a free account
+3. Navigate to **API Keys** in your dashboard
+4. Generate a new key and copy it
+
+> **Note:** The free tier gives you a generous number of inference credits — no credit card required.
+
+---
 
 ## Usage
 
-Add the NVIDIA NIM node to your workflow and configure it with your API key (obtainable from [build.nvidia.com](https://build.nvidia.com)).
+### 1. Add Credentials
+
+In n8n, go to **Credentials → New → NVIDIA NIM API** and paste your API key.
+
+### 2. Add the Node to a Workflow
+
+1. Add an **AI Agent** node to your workflow
+2. In the Agent's **Model** slot, click the `+` button
+3. Search for **NVIDIA NIM** and select it
+4. Configure the model, temperature, and max tokens
+5. Run your workflow
+
+The node acts as a language model supplier — it connects to AI Agents, chains, and any other LangChain-compatible n8n node.
+
+---
+
+## Configuration Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| **Model** | Dropdown | `llama-4-maverick-17b-128e-instruct` | The NIM model to use |
+| **Temperature** | Number (0–2) | `0.7` | Controls output randomness. Lower = more deterministic |
+| **Max Tokens** | Number (1–4096) | `1000` | Maximum tokens in the response |
+
+---
+
+## Known Issue — Routing Light Not Animating
+
+> ⚠️ **This section documents a bug found in earlier versions of this node and how it was fixed.**  
+> If you installed version `1.0.0` or earlier, please update to the latest version.
+
+### What was happening
+
+When users ran a workflow containing this node, the **routing light** (the animated glow/pulse around a node that shows it is actively executing) never appeared — even though the node was working correctly behind the scenes.
+
+Every other node in the workflow showed the animation, but the NVIDIA NIM node stayed visually "dark" throughout execution.
+
+### Root Cause
+
+This node uses n8n's `supplyData()` method instead of `execute()` — which is the correct pattern for **AI sub-nodes** (language model supply nodes that connect to AI Agents). However, `supplyData` has a different execution lifecycle than `execute`, and n8n tracks visual status through that lifecycle.
+
+Three things were missing:
+
+**1. No `closeFunction` returned**
+
+`supplyData` must return a `closeFunction` alongside the model response. n8n uses this callback as the signal that the node has finished its work — which is what triggers the routing light to complete its animation and mark the node as done.
+
+```ts
+// ❌ Before — n8n never knew the node finished
+return {
+  response: chatModel,
+};
+
+// ✅ After — n8n now correctly tracks completion
+return {
+  response: chatModel,
+  closeFunction: async () => {},
+};
+```
+
+**2. Errors were not re-thrown as `NodeOperationError`**
+
+When the node threw an error (bad API key, network failure, etc.), n8n had no way to update the node's visual state to "failed". The routing light would simply never appear.
+
+```ts
+// ❌ Before — silent failure, n8n UI stays blank
+} catch (error) {
+  console.error(error);
+}
+
+// ✅ After — n8n marks the node as failed with an error badge
+} catch (error) {
+  throw new NodeOperationError(this.getNode(), error as Error);
+}
+```
+
+**3. Missing `outputConnectionTypes` in node descriptor**
+
+Without declaring `outputConnectionTypes`, n8n's UI couldn't properly register the node as a typed AI supply node, which prevented the execution tracker from attaching to it.
+
+```json
+// ✅ Added to NvidiaNim.node.json
+"outputConnectionTypes": {
+  "ai_languageModel": [{ "type": "ai_languageModel" }]
+}
+```
+
+### The Fix (v1.1.0+)
+
+All three issues were resolved in `v1.1.0`. The node now correctly shows the routing light animation during execution, displays an error badge on failure, and cleans up properly after each run.
+
+---
 
 ## Development
 
-- `npm install` - install dependencies
-- `npm run dev` - TypeScript watch mode
-- `npm run lint` - lint code
-- `npm run lintfix` - auto-fix lint issues
-- `npm run format` - format code with Prettier
-- `npm run build` - build distributable files
+```bash
+# Install dependencies
+npm install
+
+# TypeScript watch mode (auto-recompile on save)
+npm run dev
+
+# Build distributable files
+npm run build
+
+# Lint code
+npm run lint
+
+# Auto-fix lint issues
+npm run lintfix
+
+# Format with Prettier
+npm run format
+```
+
+### Project Structure
+
+```
+n8n-nodes-nvidia-nim/
+├── credentials/
+│   └── NvidiaNimApi.credentials.ts   # API key credential definition
+├── nodes/
+│   └── NvidiaNim/
+│       ├── NvidiaNim.node.ts          # Node logic (supplyData)
+│       ├── NvidiaNim.node.json        # Node descriptor & UI properties
+│       └── nvidia-nim.png             # Node icon
+├── dist/                              # Compiled output (generated)
+├── package.json
+└── README.md
+```
+
+---
+
+## Contributing
+
+Pull requests are welcome! If you'd like to add a new model, fix a bug, or improve documentation:
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feat/your-feature`
+3. Commit your changes: `git commit -m 'feat: add your feature'`
+4. Push and open a PR
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+<div align="center">
+
+Made with ☕ for the n8n community · Powered by [NVIDIA NIM](https://build.nvidia.com)
+
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sateeshreddy/n8n-nodes-nvidia-nim",
-  "version": "0.1.1",
+  "version": "1.0.3",
   "description": "n8n community node for NVIDIA NIM",
   "main": "dist/nodes/NvidiaNim/NvidiaNim.node.js",
   "scripts": {

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run *)"
-    ]
-  }
-}

package/Claude.md

@@ -1,87 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-This repository contains the `n8n-nodes-nvidia-nim` package - an n8n community node that allows users to call any free model from NVIDIA NIM (build.nvidia.com) directly in their workflows. The node wraps NVIDIA's OpenAI-compatible REST API (`https://integrate.api.nvidia.com/v1`) with a friendly n8n UI.
-
-## Repository Structure
-```
-n8n-nodes-nvidia-nim/
-├── package.json
-├── tsconfig.json
-├── tsconfig.build.json
-├── gulpfile.js
-├── eslint.config.mjs
-├── .gitignore
-├── README.md
-├── nodes/
-│   └── NvidiaNim/
-│       ├── NvidiaNim.node.ts      # Main node logic (TypeScript)
-│       ├── NvidiaNim.node.json    # Node metadata/codex
-│       └── nvidia-nim.svg         # Node icon
-└── credentials/
-    └── NvidiaNimApi.credentials.ts # API key credential definition
-```
-
-## Key Commands
-All commands are executed by Claude Code within the project directory:
-
-- **Install dependencies**: `npm install`
-- **Lint code**: `npm run lint` (checks for TypeScript errors and enforces coding standards)
-- **Fix lint issues**: `npm run lintfix` (auto-fixes lintable issues)
-- **Format code**: `npm run format` (uses Prettier to format TypeScript and JSON files)
-- **Build package**: `npm run build` (compiles TypeScript to dist/ and copies SVG icons)
-- **Watch for changes**: `npm run dev` (TypeScript watch mode during development)
-- **Prepublish checks**: `npm run prepublishOnly` (runs build and lint before publishing)
-
-## Development Workflow
-1. **Setup**: Run `npm install` to install dependencies
-2. **Develop**: Use `npm run dev` for continuous TypeScript compilation
-3. **Code Quality**: 
-   - Run `npm run lint` to check for issues
-   - Run `npm run lintfix` to automatically fix lint issues
-   - Run `npm run format` to format code with Prettier
-4. **Build**: Run `npm run build` to generate distributable files in `dist/`
-5. **Test**: Manual testing can be done by linking to n8n (see notes below)
-
-## Architecture Highlights
-- **Node Implementation**: The main logic resides in `nodes/NvidiaNim/NvidiaNim.node.ts` which implements the `INodeType` interface from `n8n-workflow`
-- **Credentials**: API key handling is defined in `credentials/NvidiaNimApi.credentials.ts` using n8n's credential system
-- **Build Process**: 
-  - TypeScript compilation via `tsc` (using `tsconfig.build.json` for production builds)
-  - SVG icon copying via Gulp (`gulpfile.js`)
-  - Output directed to `dist/` directory as specified in package.json
-- **n8n Integration**: 
-  - Package.json includes `n8n` section specifying nodes and credentials paths
-  - Uses `n8nNodesApiVersion: 1` for compatibility
-  - Leverages n8n's built-in `httpRequest` helper for API calls (no external dependencies)
-
-## Testing Approach
-While the project doesn't include automated test files, validation includes:
-- **Build verification**: Confirming `npm run build` succeeds and produces expected output in `dist/`
-- **TypeScript checking**: Ensuring no `any` type errors (warnings allowed) via ESLint
-- **Lint compliance**: Zero warnings from `npm run lint`
-- **Structural checks**: Verifying required files exist in correct locations post-build
-- **Manual verification**: Smoke test script (`test/manual.ts`) to validate node description loads correctly
-
-## Important Notes for Claude Code
-1. **Do not ask users to run commands** - execute all commands yourself
-2. **Always verify build output** - after `npm run build`, check that `dist/` contains:
-   - `dist/nodes/NvidiaNim/NvidiaNim.node.js`
-   - `dist/nodes/NvidiaNim/nvidia-nim.svg` 
-   - `dist/credentials/NvidiaNimApi.credentials.js`
-3. **Use n8n helpers** - rely on `this.helpers.httpRequest` for API calls, not external libraries
-4. **Handle streaming properly** - when `stream: true`, collect SSE chunks before outputting
-5. **Respect continueOnFail()** - wrap per-item processing in try/catch blocks
-6. **No runtime dependencies** - avoid adding axios, node-fetch, etc.; use n8n's built-in helpers
-7. **Expression support** - n8n automatically resolves expressions in `userMessage` and `systemPrompt` fields
-
-## Common Issues to Watch For
-- **Module not found**: Ensure `npm install` has been run for `n8n-workflow` dependency
-- **Gulp not found**: Use `npx gulp build:icons` if gulp command missing
-- **SVG not copied**: Verify gulpfile.js correctly copies SVG to dist/nodes/
-- **Node not appearing**: Check package.json → n8n.nodes path matches actual dist file
-- **Authentication errors**: API key must start with `nvapi-` and be obtained from build.nvidia.com
-- **Model not found**: Use exact vendor/model-name format from build.nvidia.com
-- **Rate limiting**: Free tier allows ~40 RPM; consider Wait nodes in tight loops