@opennodes/registry 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opennodes/registry",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "OpenNodes (ONP) reference registry: node registration with proof-of-resource qualification (Stage A/B/C), transparent ranking, enforceable estimates, catalog importers (OpenRouter, Hugging Face, models.dev, Ollama), MCP surface, and the web app (catalog, chat, advisor, Node Builder)",
   "license": "Apache-2.0",
   "type": "module",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@opennodes/core": "0.1.1",
+    "@opennodes/core": "0.1.2",
     "pg": "^8.13.1"
   }
 }

package/src/importers.js

@@ -5,6 +5,12 @@ import { validateCard } from '@opennodes/core';
 
 const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[^a-z0-9]+/, '').slice(0, 100);
 const vendorSlug = (s) => slug(s).replace(/[._]/g, '-');
+/** The value as a string if it is a concrete http(s) URL, else undefined. Templated
+ *  per-account URLs (models.dev writes `https://${DATABRICKS_HOST}/...`) have no single base. */
+const httpsUrl = (v) => {
+  if (typeof v !== 'string' || v.includes('${')) return undefined;
+  try { return ['https:', 'http:'].includes(new URL(v).protocol) ? v : undefined; } catch { return undefined; }
+};
 
 /** Map input/output modality arrays (the shape both HF and OpenRouter use) to the ONP enum. */
 export function mapModalities(inputs = ['text'], outputs = ['text']) {
@@ -40,9 +46,26 @@ async function saveImportedCard(store, nodeId, origin, sourceRef, card) {
   return null;
 }
 
+/**
+ * OpenAI-compatible API bases for major providers whose models.dev entry has no `api`
+ * (models.dev omits it when a dedicated AI SDK package knows the URL). Each checked
+ * against the provider's docs and live (401 on unauthenticated /models), 2026-10-19.
+ */
+export const MODELS_DEV_API_BASES = {
+  groq: 'https://api.groq.com/openai/v1',
+  togetherai: 'https://api.together.xyz/v1',   // docs now show api.together.ai; both serve, and the gateway keys TOGETHER_API_KEY to .xyz
+  deepinfra: 'https://api.deepinfra.com/v1/openai',
+  'fireworks-ai': 'https://api.fireworks.ai/inference/v1',
+  mistral: 'https://api.mistral.ai/v1',
+  openai: 'https://api.openai.com/v1',
+};
+
 /**
  * Import a models.dev-shaped catalog: { providerId: { id, name, api?, doc?, models: { key: model } } }.
  * Each provider becomes a synthetic node `import.modelsdev.{provider}`; each model an offering.
+ * The API base is the provider's `api`, else MODELS_DEV_API_BASES; `doc` is never used as one.
+ * A provider with neither is still listed, but without endpoints.openai/health (not invocable),
+ * keeping `doc` as the informational endpoints.docs link.
  * Returns { providers, offerings, skipped }.
  */
 export async function importModelsDev(store, catalog) {
@@ -79,7 +102,8 @@ export async function importModelsDev(store, catalog) {
     if (!offeringList.length) { skipped.push(providerId); continue; }
 
     const nodeId = `import.modelsdev.${slug(providerId).replace(/[._]/g, '-')}`;
-    const base = provider?.api ?? provider?.doc ?? 'https://models.dev';
+    const base = httpsUrl(provider?.api ?? MODELS_DEV_API_BASES[providerId])?.replace(/\/+$/, '') ?? null;
+    const docs = httpsUrl(provider?.doc);
     const card = {
       onp: '0.1',
       revision: new Date().toISOString(),
@@ -89,14 +113,20 @@ export async function importModelsDev(store, catalog) {
         description: `Imported from models.dev; metadata only, unclaimed by the operator.`,
         operator: { name: provider?.name ?? providerId },
       },
-      endpoints: { openai: base, health: `${base.replace(/\/$/, '')}/health` },
+      endpoints: {
+        ...(base ? { openai: base, health: `${base}/health` } : {}),
+        ...(docs ? { docs } : {}),
+      },
       offerings: offeringList,
       payment: { schemes: [{ scheme: 'prepaid' }] },
     };
-    const errors = validateCard(card);
+    // A listing-only card deliberately lacks the schema's required invocation endpoints.
+    const errors = validateCard(card)
+      .filter((e) => base || !/^\/endpoints must have required property '(openai|health)'$/.test(e));
     if (errors.length) { skipped.push(`${providerId}: ${errors[0]}`); continue; }
 
-    await store.upsertNode(nodeId, new URL(base).origin, `import:modelsdev:${providerId}`, 'indexed', 'import');
+    const origin = new URL(base ?? docs ?? 'https://models.dev').origin;
+    await store.upsertNode(nodeId, origin, `import:modelsdev:${providerId}`, 'indexed', 'import');
     await store.saveRevision(nodeId, card.revision, card, false);
     providers++;
     offerings += offeringList.length;

package/src/mcp.js

@@ -1,78 +1,33 @@
 // DS-MCP-01: the registry as an MCP server (streamable HTTP, stateless).
 // Minimal JSON-RPC handler covering initialize / tools/list / tools/call so any
-// MCP host gets ONP discovery (search_offerings, get_offering, estimate) for free.
-import { readJson, sendJson, problem, estimateBounds, round6, extractFeatures, recommend } from '@opennodes/core';
-import { searchOfferings, collectOfferings } from './search.js';
+// MCP host gets ONP discovery (recommend, search_offerings, get_offering, get_node, estimate) for free.
+import { readFileSync } from 'node:fs';
+import { readJson, sendJson, problem, estimateBounds, round6, extractFeatures, recommend, MCP_TOOLS, MCP_INSTRUCTIONS, summarizeNode } from '@opennodes/core';
+import { searchOfferingsPaged, searchOfferings, collectOfferings } from './search.js';
 
 const PROTOCOL_VERSION = '2025-06-18';
+const { version: VERSION } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
-const TOOLS = [
-  {
-    name: 'search_offerings',
-    description: 'Search AI inference offerings in the OpenNodes registry. Filters: modality (text|image|audio|video|embedding|multimodal|agent), family, min_context, supports (comma list: tool_calls,json_mode,vision,streaming), max_input_price (USD per MTok), scheme (free|prepaid|x402), tier (community|verified|attested), lang ("en:strong"), q (free text), sort (rank|price). Returns offerings with pricing, trust tier, and rank explanation.',
+// Same tools as the stdio server in @opennodes/cli (definitions live in core). Two differences
+// on a remote endpoint: a `task` passed to recommend is sent here, so the schema says so and
+// offers `features` (from a local extractFeatures) as the private alternative.
+const TOOLS = MCP_TOOLS.map((tool) => {
+  if (tool.name !== 'recommend') return tool;
+  const { task, ...rest } = tool.inputSchema.properties;
+  return {
+    ...tool,
+    description: "Recommend the best AI node + model for a task, with an enforceable cost estimate and human-readable reasons. Use this first when you know the task but not the model. Pass `task` (sent to this registry, which extracts features and discards the text) or `features` already extracted on your side with extractFeatures from @opennodes/core, which keeps the prompt private. Returns ranked candidates with score components, a cost estimate pinned to the node's card revision, an optional cheaper two-step scenario, and MCP tool categories the task likely needs. To browse instead, use search_offerings; to price a specific chain, use estimate.",
     inputSchema: {
-      type: 'object',
+      ...tool.inputSchema,
+      required: [],
       properties: {
-        modality: { type: 'string' }, family: { type: 'string' },
-        min_context: { type: 'number' }, supports: { type: 'string' },
-        max_input_price: { type: 'number' }, scheme: { type: 'string' },
-        tier: { type: 'string' }, lang: { type: 'string' },
-        q: { type: 'string' }, sort: { type: 'string' }, limit: { type: 'number' },
+        task: { ...task, description: 'The task description or the prompt itself. Sent to the registry for feature extraction; use `features` to keep it private. Give this or `features`.' },
+        features: { type: 'object', description: 'Features from extractFeatures(prompt) in @opennodes/core: task class, size, language and needs, no prompt text. Give this or `task`.' },
+        ...rest,
       },
     },
-  },
-  {
-    name: 'get_offering',
-    description: 'Get full detail for one offering by node_id and offering_id, including endpoints, pricing, serving capabilities, and observed probe results.',
-    inputSchema: {
-      type: 'object',
-      required: ['node_id', 'offering_id'],
-      properties: { node_id: { type: 'string' }, offering_id: { type: 'string' } },
-    },
-  },
-  {
-    name: 'estimate',
-    description: 'Estimate cost bounds for a planned invocation chain BEFORE spending money. Each step names a concrete offering ("node_id/offering_id") or a select query (same filters as search_offerings), plus est_input_tokens and est_output_tokens. Returns per-step cost, pinned card_revision (making the estimate enforceable at invocation), and totals.',
-    inputSchema: {
-      type: 'object',
-      required: ['steps'],
-      properties: {
-        steps: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              offering: { type: 'string' },
-              select: { type: 'object' },
-              est_input_tokens: { type: 'number' },
-              est_output_tokens: { type: 'number' },
-            },
-          },
-        },
-      },
-    },
-  },
-  {
-    name: 'recommend',
-    description: 'Recommend the best AI node + model for a task. Give the task (a description or the prompt itself) and an optional policy; returns the top offerings with score components, human-readable reasons, an enforceable cost estimate with pinned card_revision, an optional two-step scenario (cheap triage/draft → strong expert/refine) when it would save money, and MCP tool categories the task likely needs. Prefer passing `features` (from a local extractFeatures) instead of `task` when the prompt is private.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task: { type: 'string', description: 'task description or prompt' },
-        features: { type: 'object', description: 'pre-extracted features (privacy-preserving alternative to task)' },
-        est_output_tokens: { type: 'number' },
-        policy: {
-          type: 'object',
-          properties: {
-            min_tier: { type: 'string' }, max_input_per_mtok: { type: 'number' }, max_total_usd: { type: 'number' },
-            region: { type: 'string' }, prefer_local: { type: 'boolean' },
-            preset: { type: 'string', description: 'cheap | fast | quality | private' }, limit: { type: 'number' },
-          },
-        },
-      },
-    },
-  },
-];
+  };
+});
 
 async function runTool(store, name, args = {}) {
   switch (name) {
@@ -80,12 +35,12 @@ async function runTool(store, name, args = {}) {
       const features = args.features ?? (args.task != null
         ? extractFeatures(String(args.task), { est_output_tokens: args.est_output_tokens ?? null }) : null);
       if (!features) throw new Error('recommend needs "task" or "features"');
-      return recommend(await collectOfferings(store), features, args.policy ?? {});
+      return recommend((await collectOfferings(store)).filter((o) => o.invocable), features, args.policy ?? {});
     }
     case 'search_offerings': {
       const query = new URLSearchParams();
       for (const [k, v] of Object.entries(args)) if (v !== undefined && v !== null) query.set(k, String(v));
-      return { offerings: await searchOfferings(store, query) };
+      return searchOfferingsPaged(store, query);
     }
     case 'get_offering': {
       const found = (await collectOfferings(store)).find(
@@ -93,6 +48,16 @@ async function runTool(store, name, args = {}) {
       if (!found) throw new Error(`unknown offering: ${args.node_id}/${args.offering_id}`);
       return found;
     }
+    case 'get_node': {
+      const node = await store.getNode(args.node_id);
+      if (!node) throw new Error(`unknown node: ${args.node_id} (node ids come from search_offerings or recommend results)`);
+      return summarizeNode({
+        ...node,
+        card: await store.latestCard(node.id),
+        probes: (await store.probesFor(node.id)).slice(0, 20),
+        history: await store.transitionsFor(node.id),
+      }, args.offering_limit ?? 25);
+    }
     case 'estimate': {
       const all = await collectOfferings(store);
       const steps = [];
@@ -137,8 +102,8 @@ async function handleRpc(store, msg) {
       return reply({
         protocolVersion: params?.protocolVersion ?? PROTOCOL_VERSION,
         capabilities: { tools: { listChanged: false } },
-        serverInfo: { name: 'opennodes-registry', version: '0.1.0' },
-        instructions: 'OpenNodes registry: search AI inference offerings, inspect them, and pre-price invocation chains. Typical flow: search_offerings -> estimate -> invoke via the offering endpoints (invocation itself is not exposed here).',
+        serverInfo: { name: 'opennodes-registry', title: 'OpenNodes registry', version: VERSION },
+        instructions: MCP_INSTRUCTIONS,
       });
     case 'ping':
       return reply({});

package/src/search.js

@@ -52,6 +52,8 @@ export async function collectOfferings(store) {
           availability,
         },
         endpoints: card.endpoints,
+        // false for listing-only imports (no known API endpoint): shown, never called
+        invocable: Boolean(card.endpoints?.openai),
       });
     }
   }
@@ -63,6 +65,8 @@ export async function searchOfferingsPaged(store, query) {
   let items = await collectOfferings(store);
 
   const q = (k) => query.get(k);
+  if (q('invocable') === 'true') items = items.filter((o) => o.invocable);
+  if (q('invocable') === 'false') items = items.filter((o) => !o.invocable);
   if (q('modality')) items = items.filter((o) => o.modality === q('modality'));
   if (q('family')) items = items.filter((o) => o.model.family === q('family') || o.model.artifact === q('family'));
   if (q('min_context')) items = items.filter((o) => (o.serving?.context_window ?? 0) >= Number(q('min_context')));

package/src/server.js

@@ -399,7 +399,8 @@ export async function startRegistry({
         ? extractFeatures(String(body.task), { attachments: body.attachments ?? [], est_output_tokens: body.est_output_tokens ?? null, messages: body.messages ?? [] })
         : null);
       if (!features) return problem(res, 400, 'missing-task', 'body must carry "task" (text) or "features" (from extractFeatures)');
-      const all = await collectOfferings(store);
+      // only what a client could actually call: listing-only imports are never recommended
+      const all = (await collectOfferings(store)).filter((o) => o.invocable);
       sendJson(res, 200, recommend(all, features, body.policy ?? {}));
     }],
 

package/src/web/index.html

@@ -589,11 +589,17 @@ function ctxBit(o) {
   const basis = (o.source === 'import' && !o.serving.context_capped_from) ? ' <span class="micro m-claimed">CLAIMED</span>' : '';
   return `<span>ctx <b class="num">${fmtInt(o.serving.context_window)}</b>${cap}${basis}</span>`;
 }
+/** Listing-only imports carry no endpoints.openai: they are shown but never called. */
+const invocable = (o) => o.invocable !== false && Boolean(o.endpoints?.openai);
+/** endpoints.docs only when it is a plain web link (cards are third-party data). */
+const docsUrl = (endpoints) => /^https?:\/\//i.test(endpoints?.docs ?? '') ? endpoints.docs : null;
 function provLine(o) {
   const obs = o.observed || {};
   const bits = [`revision ${esc((o.card_revision || '').slice(0, 10))}`];
   if (obs.probes > 0) bits.push(`probes ${Math.round((obs.probe_success ?? 0) * obs.probes)}/${obs.probes} pass`);
   if (o.source === 'import') bits.push('catalog import — operator can claim this listing to get verified');
+  if (!invocable(o)) bits.push('listing only — no known API endpoint, so it cannot be called from here'
+    + (docsUrl(o.endpoints) ? ` (<a href="${esc(docsUrl(o.endpoints))}" target="_blank" rel="noopener">provider docs ↗</a>)` : ''));
   return bits.join(' · ');
 }
 
@@ -833,11 +839,11 @@ async function loadModel(artifact) {
     const navBits = [['#sec-offerings', 'OFFERINGS'], ['#sec-play', 'PLAYGROUND']];
 
     // playground targets: this page's offerings + a custom endpoint (e.g. local Ollama)
-    pgOfferings = list;
-    $('#pg-target').innerHTML = list.map((o, i) =>
+    pgOfferings = list.filter(invocable);
+    $('#pg-target').innerHTML = pgOfferings.map((o, i) =>
       `<option value="${i}">${esc(o.node_id)} — ${priceStr(o.pricing)} [${esc(o.tier)}]</option>`).join('')
       + '<option value="custom">custom endpoint (your local Ollama / any OpenAI-compatible server)</option>';
-    $('#pg-customrow').hidden = true;
+    $('#pg-customrow').hidden = pgOfferings.length > 0;   // listing-only offerings leave just the custom endpoint
     $('#pg-out').textContent = '';
     $('#pg-meta').textContent = '';
     $('#md-offerings').innerHTML = `<table class="grid num"><thead><tr>
@@ -997,7 +1003,7 @@ async function loadChatTargets() {
       const key = (o) => o.node_id + '/' + o.offering_id;
       const ready = reg.offerings.filter((o) => o.source !== 'import');
       const seen = new Set(ready.map(key));
-      const rest = all.offerings.filter((o) => !seen.has(key(o)));
+      const rest = all.offerings.filter((o) => !seen.has(key(o)) && invocable(o));
       const local = rest.filter((o) => o.local);            // Ollama library: runs on the visitor's own machine
       const imports = rest.filter((o) => !o.local);
       chat.offerings = [...ready, ...local, ...imports];
@@ -1030,6 +1036,7 @@ async function applyAdvisorHandoff() {
     const [nodeId, offeringId] = key.split('/');
     let o = chat.offerings.find((x) => x.node_id === nodeId && x.offering_id === offeringId);
     if (!o) { try { o = await api(`/v0/offerings/${encodeURIComponent(nodeId)}/${encodeURIComponent(offeringId)}`); } catch { continue; } }
+    if (!invocable(o)) continue;
     if (!chat.roster.some((t) => t.offering && t.offering.node_id === nodeId && t.offering.offering_id === offeringId)) chat.roster.push({ offering: o });
   }
   if (chat.roster.length > 1) { $('#ch-mode').value = 'compare'; $('#ch-modenote').textContent = MODE_NOTES.compare; }
@@ -1422,8 +1429,9 @@ async function scApply(sc, verb = 'loaded') {
       o = chat.offerings.find((x) => x.node_id === nodeId && x.offering_id === offId);
       if (!o) { try { o = await api(`/v0/offerings/${encodeURIComponent(nodeId)}/${encodeURIComponent(offId)}`); } catch { o = null; } }
     } else if (entry.select) {            // ONP-6 late binding: resolve the requirement against this registry now
-      try { o = (await api('/v0/offerings?limit=1&' + new URLSearchParams(entry.select))).offerings[0] ?? null; } catch { o = null; }
+      try { o = (await api('/v0/offerings?limit=1&invocable=true&' + new URLSearchParams(entry.select))).offerings[0] ?? null; } catch { o = null; }
     }
+    if (o && !invocable(o)) o = null;   // a pinned listing-only import cannot be called
     if (o) chat.roster.push({ offering: o }); else missing.push(entry.pin ?? JSON.stringify(entry.select));
   }
   const MODES = ['single', 'compare', 'jury', 'pipeline', 'iterative'];
@@ -1765,7 +1773,8 @@ async function loadNode(id) {
         ${n.source === 'import' ? stat('<span class="chip imp">IMPORTED</span>', 'SOURCE — unclaimed by operator') : ''}
       </div>
       <div class="panel pad" style="max-width:56rem; margin-top:0.6rem"><table class="grid">
-        <tr><td style="color:var(--muted); width:8rem" class="mono">endpoint</td><td class="mono" style="font-size:0.74rem">${esc(card.endpoints?.openai ?? '—')}</td></tr>
+        <tr><td style="color:var(--muted); width:8rem" class="mono">endpoint</td><td class="mono" style="font-size:0.74rem">${card.endpoints?.openai ? esc(card.endpoints.openai) : '— <span style="font-family:inherit; color:var(--muted)">listing only: no known API endpoint, not callable from OpenNodes</span>'}</td></tr>
+        ${docsUrl(card.endpoints) ? `<tr><td style="color:var(--muted)" class="mono">docs</td><td class="mono" style="font-size:0.74rem"><a href="${esc(docsUrl(card.endpoints))}" target="_blank" rel="noopener">${esc(docsUrl(card.endpoints))}</a></td></tr>` : ''}
         ${card.hardware ? `<tr><td style="color:var(--muted)" class="mono">hardware</td><td style="font-size:0.78rem">${hwStr({ hardware: card.hardware })}</td></tr>` : ''}
         <tr><td style="color:var(--muted)" class="mono">revision</td><td class="mono" style="font-size:0.74rem">${esc(card.revision ?? '—')}</td></tr>
       </table></div>