n8n-nodes-openrouter-selector 0.3.0

package/README.md

@@ -0,0 +1,307 @@
+# n8n-nodes-openrouter-selector
+
+n8n community node for intelligent OpenRouter model selection based on task, budget, and benchmarks.
+
+## Features
+
+- **Task-Based Selection**: Optimized model recommendations for:
+  - Translation (Chinese ↔ English optimized)
+  - Coding & Development
+  - Data Analysis & Reasoning
+  - Vision & Image Analysis
+  - Conversational Chat
+  - Text Embedding
+  - Summarization
+  - Mathematical Reasoning
+
+- **Budget Awareness**: Three budget tiers:
+  - **Cheap**: Lowest cost, quality secondary
+  - **Balanced**: Good price-performance ratio
+  - **Premium**: Best quality, cost no concern
+
+- **Benchmark-Based Scoring**: Uses external benchmark data:
+  - Artificial Analysis (Intelligence, Coding, Math indices)
+  - LMSYS Chatbot Arena (Elo ratings)
+  - LiveBench (Coding, Math, Reasoning scores)
+
+- **Dynamic Model Override**: Select specific models with real-time scoring preview
+
+- **Flexible Filtering**:
+  - Minimum context length
+  - JSON mode requirement
+  - Vision/multimodal requirement
+  - Cost limits
+  - Provider whitelist/blacklist
+
+## Installation
+
+### In n8n
+
+1. Go to **Settings** → **Community Nodes**
+2. Click **Install a community node**
+3. Enter: `n8n-nodes-openrouter-selector`
+4. Click **Install**
+
+### Manual Installation
+
+```bash
+# In your n8n custom nodes directory
+cd ~/.n8n/custom
+npm install n8n-nodes-openrouter-selector
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/ecolights/n8n-nodes-openrouter-selector.git
+cd n8n-nodes-openrouter-selector
+pnpm install
+pnpm build
+
+# Link to n8n
+cd ~/.n8n/custom
+npm link /path/to/n8n-nodes-openrouter-selector
+```
+
+## Prerequisites
+
+This node requires:
+
+1. **Supabase Database** with the benchmark schema (see [docs/BENCHMARK_SYSTEM.md](docs/BENCHMARK_SYSTEM.md)):
+   - `models_catalog` - OpenRouter model data (synced via separate workflow)
+   - `model_name_mappings` - Master mapping table (manually maintained)
+   - `model_benchmarks` - Benchmark scores (auto-synced weekly)
+   - `task_profiles` - Task-specific scoring weights
+   - `unmatched_models` - Review queue for new models
+
+2. **n8n Workflow**: `TN_benchmark_sync_artificial_analysis` for weekly benchmark sync
+
+3. **Credentials**: Supabase URL and API key (service role for write access)
+
+### Quick Schema Setup
+
+The full schema with triggers, functions, and RLS policies is documented in [docs/BENCHMARK_SYSTEM.md](docs/BENCHMARK_SYSTEM.md).
+
+**Core Tables Overview**:
+
+```sql
+-- Model name mappings (Source of Truth - manually maintained)
+CREATE TABLE model_name_mappings (
+  openrouter_id TEXT UNIQUE NOT NULL,      -- e.g. "anthropic/claude-sonnet-4"
+  canonical_name TEXT NOT NULL,             -- Display name
+  aa_name TEXT,                             -- Artificial Analysis name
+  aa_slug TEXT,                             -- AA URL slug
+  provider TEXT,                            -- anthropic, openai, google, etc.
+  verified BOOLEAN DEFAULT false
+);
+
+-- Benchmark scores (auto-filled by sync workflow)
+CREATE TABLE model_benchmarks (
+  openrouter_id TEXT REFERENCES model_name_mappings(openrouter_id),
+  -- Artificial Analysis
+  aa_intelligence_index DECIMAL(5,2),
+  aa_coding_index DECIMAL(5,2),
+  aa_math_index DECIMAL(5,2),
+  -- LMSYS Arena
+  lmsys_elo INTEGER,
+  -- LiveBench
+  livebench_overall DECIMAL(5,2),
+  livebench_coding DECIMAL(5,2),
+  -- Computed composites (via trigger)
+  composite_general DECIMAL(5,2),
+  composite_code DECIMAL(5,2),
+  composite_math DECIMAL(5,2)
+);
+
+-- Task-specific scoring weights
+CREATE TABLE task_profiles (
+  task_name TEXT UNIQUE NOT NULL,           -- general, code, translation, etc.
+  weight_aa_intelligence DECIMAL(3,2),
+  weight_aa_coding DECIMAL(3,2),
+  weight_lmsys_elo DECIMAL(3,2),
+  weight_livebench DECIMAL(3,2),
+  boost_anthropic DECIMAL(3,2),
+  boost_openai DECIMAL(3,2),
+  boost_deepseek DECIMAL(3,2)
+);
+```
+
+## Usage
+
+### Basic Usage
+
+1. Add the **OpenRouter Model Selector** node to your workflow
+2. Configure credentials (Supabase URL + API Key)
+3. Select a **Task Category** (e.g., "coding")
+4. Select a **Budget** (e.g., "balanced")
+5. Execute to get the recommended model
+
+### Output Format
+
+**Full Output** (default):
+```json
+{
+  "recommended": {
+    "modelId": "anthropic/claude-sonnet-4",
+    "provider": "anthropic",
+    "displayName": "Claude Sonnet 4",
+    "contextLength": 200000,
+    "supportsJson": true,
+    "modality": "text+image->text",
+    "pricing": {
+      "promptPer1kUsd": 0.003,
+      "completionPer1kUsd": 0.015,
+      "combinedPer1kUsd": 0.009
+    },
+    "score": 87.5,
+    "scoreBreakdown": {
+      "benchmarkFit": 38,
+      "taskFit": 28,
+      "budgetFit": 18,
+      "capabilityFit": 9,
+      "providerBonus": 1.5
+    },
+    "reasoning": "Excellent benchmark performance for Coding & Development, ideal balanced pricing, anthropic provider bonus (+15%)."
+  },
+  "alternatives": [...],
+  "queryMetadata": {
+    "task": "coding",
+    "budget": "balanced",
+    "totalModelsEvaluated": 313,
+    "modelsPassingFilters": 187,
+    "executionTimeMs": 245
+  }
+}
+```
+
+### Using the Selected Model
+
+Connect the output to an HTTP Request node or OpenRouter integration:
+
+```
+[OpenRouter Model Selector] → [HTTP Request to OpenRouter API]
+                                 URL: https://openrouter.ai/api/v1/chat/completions
+                                 Body: { "model": "={{$json.recommended.modelId}}", ... }
+```
+
+## Scoring Algorithm
+
+The scoring formula is deterministic and based on external benchmarks:
+
+```
+score = (benchmark_fit × 0.4) + (task_fit × 0.3) + (budget_fit × 0.2) + (capability_fit × 0.1) × provider_boost
+```
+
+### Components
+
+| Component | Weight | Description |
+|-----------|--------|-------------|
+| Benchmark Fit | 40% | Score from external benchmarks (AA, LMSYS, LiveBench) |
+| Task Fit | 30% | How well the model matches task requirements |
+| Budget Fit | 20% | Cost alignment with budget preference |
+| Capability Fit | 10% | Context length, JSON support, verification status |
+| Provider Boost | ×1.0-1.2 | Task-specific provider bonuses |
+
+### Provider Boosts by Task
+
+| Task | Provider Boosts |
+|------|-----------------|
+| Translation | DeepSeek +20%, Qwen +15%, Anthropic +10% |
+| Coding | Anthropic +15%, OpenAI +10%, DeepSeek +8% |
+| Analysis | Anthropic +15%, OpenAI +10%, Google +5% |
+| Vision | OpenAI +15%, Google +12%, Anthropic +8% |
+| Math | DeepSeek +15%, Qwen +12%, OpenAI +10% |
+
+## Configuration
+
+### Node Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| Task Category | Dropdown | Type of task (coding, translation, etc.) |
+| Budget | Dropdown | Cost preference (cheap, balanced, premium) |
+| Model Override | Dynamic Dropdown | Override with specific model |
+| Filters | Collection | Advanced filtering options |
+| Options | Collection | Output configuration |
+
+### Filter Options
+
+| Filter | Type | Default | Description |
+|--------|------|---------|-------------|
+| Min Context Length | Number | 8000 | Minimum tokens |
+| Require JSON Mode | Boolean | false | Only JSON-capable models |
+| Require Vision | Boolean | false | Only multimodal models |
+| Max Cost per 1K | Number | 0 | Cost limit (0 = no limit) |
+| Provider Whitelist | Multi-select | [] | Include only these providers |
+| Provider Blacklist | Multi-select | [] | Exclude these providers |
+
+## Benchmark Sync Workflow
+
+The node requires benchmark data to be synced weekly via n8n workflow.
+
+### n8n Workflow: `TN_benchmark_sync_artificial_analysis`
+
+**Trigger**: Weekly (Sunday 03:00 UTC) + Manual + Webhook
+
+**Data Flow**:
+```
+[1. Fetch Artificial Analysis] ──────┐
+                                      │
+[2. Fetch OpenRouter Catalog] ────────┼──► [4. Merge All Data]
+                                      │           │
+[3. Fetch Existing Mappings] ────────┘            ▼
+                                      [5. Process & Match Models]
+                                              │
+                               ┌──────────────┴──────────────┐
+                               ▼                             ▼
+                    [6. Upsert Benchmarks]      [7. Store Unmatched]
+                               │                             │
+                               └──────────────┬──────────────┘
+                                              ▼
+                                   [8. Merge Results]
+                                              │
+                                              ▼
+                                   [9. Telegram Notification]
+```
+
+**Detailed Documentation**: See [docs/BENCHMARK_SYSTEM.md](docs/BENCHMARK_SYSTEM.md)
+
+### Manual Sync Trigger
+
+```bash
+# Via n8n Webhook
+curl -X POST https://n8n.dev.ecolights.de/webhook/benchmark-sync
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Lint
+pnpm lint
+
+# Format
+pnpm format
+```
+
+## License
+
+MIT
+
+## Author
+
+EcoLights (dev@ecolights.de)
+
+## Links
+
+- [OpenRouter](https://openrouter.ai)
+- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)
+- [Supabase](https://supabase.com)

package/dist/credentials/OpenRouterApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class OpenRouterApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}
+//# sourceMappingURL=OpenRouterApi.credentials.d.ts.map

package/dist/credentials/OpenRouterApi.credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenRouterApi.credentials.d.ts","sourceRoot":"","sources":["../../credentials/OpenRouterApi.credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,eAAe,EAChB,MAAM,cAAc,CAAC;AAEtB,qBAAa,aAAc,YAAW,eAAe;IACnD,IAAI,SAAmB;IACvB,WAAW,SAAoB;IAC/B,gBAAgB,SAA+C;IAC/D,UAAU,EAAE,eAAe,EAAE,CAY3B;IAEF,YAAY,EAAE,oBAAoB,CAOhC;IAEF,IAAI,EAAE,sBAAsB,CAM1B;CACH"}

package/dist/credentials/OpenRouterApi.credentials.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenRouterApi = void 0;
+class OpenRouterApi {
+    name = 'openRouterApi';
+    displayName = 'OpenRouter API';
+    documentationUrl = 'https://openrouter.ai/docs#authentication';
+    properties = [
+        {
+            displayName: 'API Key',
+            name: 'apiKey',
+            type: 'string',
+            typeOptions: {
+                password: true,
+            },
+            default: '',
+            required: true,
+            description: 'Your OpenRouter API key from openrouter.ai/keys',
+        },
+    ];
+    authenticate = {
+        type: 'generic',
+        properties: {
+            headers: {
+                Authorization: '=Bearer {{$credentials.apiKey}}',
+            },
+        },
+    };
+    test = {
+        request: {
+            baseURL: 'https://openrouter.ai/api/v1',
+            url: '/models',
+            method: 'GET',
+        },
+    };
+}
+exports.OpenRouterApi = OpenRouterApi;
+//# sourceMappingURL=OpenRouterApi.credentials.js.map

package/dist/credentials/OpenRouterApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenRouterApi.credentials.js","sourceRoot":"","sources":["../../credentials/OpenRouterApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,aAAa;IACxB,IAAI,GAAG,eAAe,CAAC;IACvB,WAAW,GAAG,gBAAgB,CAAC;IAC/B,gBAAgB,GAAG,2CAA2C,CAAC;IAC/D,UAAU,GAAsB;QAC9B;YACE,WAAW,EAAE,SAAS;YACtB,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE;gBACX,QAAQ,EAAE,IAAI;aACf;YACD,OAAO,EAAE,EAAE;YACX,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,iDAAiD;SAC/D;KACF,CAAC;IAEF,YAAY,GAAyB;QACnC,IAAI,EAAE,SAAS;QACf,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,aAAa,EAAE,iCAAiC;aACjD;SACF;KACF,CAAC;IAEF,IAAI,GAA2B;QAC7B,OAAO,EAAE;YACP,OAAO,EAAE,8BAA8B;YACvC,GAAG,EAAE,SAAS;YACd,MAAM,EAAE,KAAK;SACd;KACF,CAAC;CACH;AAlCD,sCAkCC"}

package/dist/credentials/SupabaseModelCatalogApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class SupabaseModelCatalogApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}
+//# sourceMappingURL=SupabaseModelCatalogApi.credentials.d.ts.map

package/dist/credentials/SupabaseModelCatalogApi.credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupabaseModelCatalogApi.credentials.d.ts","sourceRoot":"","sources":["../../credentials/SupabaseModelCatalogApi.credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,eAAe,EAChB,MAAM,cAAc,CAAC;AAEtB,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,IAAI,SAA6B;IACjC,WAAW,SAAgC;IAC3C,gBAAgB,SAA0C;IAC1D,UAAU,EAAE,eAAe,EAAE,CAsB3B;IAEF,YAAY,EAAE,oBAAoB,CAQhC;IAEF,IAAI,EAAE,sBAAsB,CAS1B;CACH"}

package/dist/credentials/SupabaseModelCatalogApi.credentials.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupabaseModelCatalogApi = void 0;
+class SupabaseModelCatalogApi {
+    name = 'supabaseModelCatalogApi';
+    displayName = 'Supabase Model Catalog API';
+    documentationUrl = 'https://supabase.com/docs/guides/api';
+    properties = [
+        {
+            displayName: 'Supabase URL',
+            name: 'url',
+            type: 'string',
+            default: '',
+            placeholder: 'https://your-project.supabase.co',
+            description: 'Your Supabase project URL',
+            required: true,
+        },
+        {
+            displayName: 'API Key',
+            name: 'apiKey',
+            type: 'string',
+            typeOptions: {
+                password: true,
+            },
+            default: '',
+            description: 'Your Supabase anon/public key. Found in Project Settings > API.',
+            required: true,
+        },
+    ];
+    authenticate = {
+        type: 'generic',
+        properties: {
+            headers: {
+                apikey: '={{$credentials.apiKey}}',
+                Authorization: '=Bearer {{$credentials.apiKey}}',
+            },
+        },
+    };
+    test = {
+        request: {
+            baseURL: '={{$credentials.url}}',
+            url: '/rest/v1/models_catalog?select=model&limit=1',
+            headers: {
+                apikey: '={{$credentials.apiKey}}',
+                Authorization: '=Bearer {{$credentials.apiKey}}',
+            },
+        },
+    };
+}
+exports.SupabaseModelCatalogApi = SupabaseModelCatalogApi;
+//# sourceMappingURL=SupabaseModelCatalogApi.credentials.js.map

package/dist/credentials/SupabaseModelCatalogApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupabaseModelCatalogApi.credentials.js","sourceRoot":"","sources":["../../credentials/SupabaseModelCatalogApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,uBAAuB;IAClC,IAAI,GAAG,yBAAyB,CAAC;IACjC,WAAW,GAAG,4BAA4B,CAAC;IAC3C,gBAAgB,GAAG,sCAAsC,CAAC;IAC1D,UAAU,GAAsB;QAC9B;YACE,WAAW,EAAE,cAAc;YAC3B,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,kCAAkC;YAC/C,WAAW,EAAE,2BAA2B;YACxC,QAAQ,EAAE,IAAI;SACf;QACD;YACE,WAAW,EAAE,SAAS;YACtB,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE;gBACX,QAAQ,EAAE,IAAI;aACf;YACD,OAAO,EAAE,EAAE;YACX,WAAW,EACT,iEAAiE;YACnE,QAAQ,EAAE,IAAI;SACf;KACF,CAAC;IAEF,YAAY,GAAyB;QACnC,IAAI,EAAE,SAAS;QACf,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,MAAM,EAAE,0BAA0B;gBAClC,aAAa,EAAE,iCAAiC;aACjD;SACF;KACF,CAAC;IAEF,IAAI,GAA2B;QAC7B,OAAO,EAAE;YACP,OAAO,EAAE,uBAAuB;YAChC,GAAG,EAAE,8CAA8C;YACnD,OAAO,EAAE;gBACP,MAAM,EAAE,0BAA0B;gBAClC,aAAa,EAAE,iCAAiC;aACjD;SACF;KACF,CAAC;CACH;AAhDD,0DAgDC"}

package/dist/nodes/OpenRouterChatCompletion/OpenRouterChatCompletion.node.d.ts

@@ -0,0 +1,11 @@
+import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class OpenRouterChatCompletion implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getModels(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}
+//# sourceMappingURL=OpenRouterChatCompletion.node.d.ts.map

package/dist/nodes/OpenRouterChatCompletion/OpenRouterChatCompletion.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenRouterChatCompletion.node.d.ts","sourceRoot":"","sources":["../../../nodes/OpenRouterChatCompletion/OpenRouterChatCompletion.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,oBAAoB,EAErB,MAAM,cAAc,CAAC;AAyCtB,qBAAa,wBAAyB,YAAW,SAAS;IACxD,WAAW,EAAE,oBAAoB,CAgK/B;IAEF,OAAO;;4BAEmB,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;;MA0C/E;IAEI,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;CAuHxE"}