@flame0510/project-aether 1.5.2 → 1.6.1

package/scripts/model-info-suggest.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Suggests what to write in a catalogue entry's curated `info` block — the facts no API
+ * publishes in a usable shape: an active parameter count, real benchmark numbers, the
+ * vendor's documentation link, notes.
+ *
+ * **It never writes.** Prints the material and, with `--json`, a skeleton to complete:
+ * the assistant or the maintainer reads the model card, transcribes the numbers and
+ * records the source, exactly as the plan requires (plans/MODEL-DETAILS-PLAN.md: facts
+ * plus curation, never derived).
+ *
+ * Sources, in order: the model card on Hugging Face (a README, so readable), then the
+ * vendor's documentation, which the card usually links. No card and no citable page means
+ * the model keeps its automatic data only.
+ *
+ * Usage:
+ *   node scripts/model-info-suggest.mjs <model id> [<model id> …]
+ *   node scripts/model-info-suggest.mjs <model id> --json
+ *   node scripts/model-info-suggest.mjs --all            # every model with a card
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fetchUpstream, matchUpstream } from './lib/model-upstream.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const MODELS_FILE = path.join(ROOT, 'models.config.json');
+const DETAILS_FILE = path.join(ROOT, 'model-details.json');
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+const ids = args.filter((a) => !a.startsWith('--'));
+const catalogue = JSON.parse(fs.readFileSync(MODELS_FILE, 'utf-8')).models;
+const details = (() => {
+  try { return JSON.parse(fs.readFileSync(DETAILS_FILE, 'utf-8')).models ?? {}; } catch { return {}; }
+})();
+
+const readmeUrl = (hfId) => `https://huggingface.co/${hfId}/raw/main/README.md`;
+
+/** Lines that read like the vendor describing its own size or sparsity. */
+function sizeSentences(md) {
+  // Raw markdown carries HTML blocks and images with no sentence boundaries: strip them
+  // first, or the first "sentence" is the whole badge header.
+  const text = md
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\|/g, ' ');
+  return text
+    .split(/(?<=[.!?])\s+/)
+    .map((s) => s.replace(/\s+/g, ' ').trim())
+    .map((s) => s.replace(/\s+/g, ' ').trim())
+    .filter((s) => s.length > 20 && s.length < 320)
+    .filter((s) => /(active|activated|backbone|total)\s+(parameter|params)|Mixture-of-Experts|number of experts|routed experts/i.test(s))
+    .slice(0, 6);
+}
+
+/** Markdown tables that look like benchmark results, header included. */
+function benchmarkTables(md) {
+  const lines = md.split('\n');
+  const tables = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*\|/.test(lines[i])) continue;
+    const block = [];
+    while (i < lines.length && /^\s*\|/.test(lines[i])) { block.push(lines[i].trim()); i++; }
+    const head = block[0] ?? '';
+    const body = block.slice(1);
+    const numeric = body.filter((row) => (row.match(/\b\d+(\.\d+)?\b/g) ?? []).length >= 2).length;
+    if (/bench|eval|score|metric/i.test(head) || numeric >= 3) tables.push(block);
+  }
+  return tables.slice(0, 3);
+}
+
+/** Candidate documentation links the card points at. */
+function docLinks(md) {
+  const urls = new Set();
+  for (const m of md.matchAll(/https?:\/\/[^\s)"'<>\]]+/g)) {
+    const url = m[0].replace(/[.,;]$/, '');
+    if (/docs\.|github\.com|arxiv\.org|platform\.|api-docs/.test(url)) urls.add(url);
+  }
+  return [...urls].slice(0, 8);
+}
+
+async function suggest(entry, live) {
+  const upstream = matchUpstream(live, entry.id);
+  const detail = details[entry.id] ?? {};
+  const hfId = detail.hf?.id ?? upstream?.hugging_face_id ?? null;
+
+  const out = {
+    id: entry.id,
+    name: entry.name,
+    provider: entry.provider,
+    currentInfo: entry.info ?? null,
+    upstreamId: upstream?.id ?? null,
+    huggingFaceId: hfId,
+    cardUrl: hfId ? `https://huggingface.co/${hfId}` : null,
+  };
+
+  if (!hfId) {
+    console.log(`${entry.id}  —  no Hugging Face card: look for the vendor's own model page (no card → no citable size).`);
+    return out;
+  }
+
+  const res = await fetch(readmeUrl(hfId), { signal: AbortSignal.timeout(20_000) });
+  if (!res.ok) {
+    console.log(`${entry.id}  —  card ${hfId}: README returned HTTP ${res.status}`);
+    return out;
+  }
+  const md = await res.text();
+  out.paramsSentences = sizeSentences(md);
+  out.benchmarkTables = benchmarkTables(md);
+  out.docLinks = docLinks(md);
+
+  if (!asJson) {
+    console.log(`\n=== ${entry.id} — ${entry.name}`);
+    console.log(`  card: ${out.cardUrl}`);
+    if (detail.hf) {
+      const h = detail.hf;
+      console.log(`  automatic: total ${h.total ?? '—'}, experts ${h.moe ? `${h.moe.experts} (${h.moe.perToken ?? '?'}/token)` : '—'}, licence ${h.license ?? '—'}, published ${h.published ?? '—'}`);
+    }
+    if (out.paramsSentences.length) {
+      console.log('  size sentences (candidates for info.params):');
+      for (const s of out.paramsSentences) console.log(`    · ${s}`);
+    }
+    for (const t of out.benchmarkTables) {
+      console.log('  benchmark table (pick the model\'s own column):');
+      for (const row of t.slice(0, 10)) console.log(`    ${row}`);
+    }
+    if (out.docLinks.length) {
+      console.log(`  doc link candidates: ${out.docLinks.join(' , ')}`);
+    }
+    if (out.currentInfo) console.log(`  current info: ${JSON.stringify(out.currentInfo)}`);
+  }
+  return out;
+}
+
+async function main() {
+  const live = await fetchUpstream();
+  const targets = args.includes('--all')
+    ? catalogue.filter((m) => details[m.id]?.hf?.id)
+    : ids.map((id) => catalogue.find((m) => m.id === id) ?? { id, name: '(not in the catalogue)', provider: '?' });
+  const out = [];
+  for (const entry of targets) out.push(await suggest(entry, live));
+  if (asJson) console.log(JSON.stringify(out, null, 2));
+}
+
+main().catch((e) => {
+  console.error(`✗ ${e instanceof Error ? e.message : String(e)}`);
+  process.exit(1);
+});

package/scripts/refresh-model-pricing.mjs

@@ -31,10 +31,39 @@ import { fileURLToPath } from 'node:url';
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const PRICING_FILE = path.join(ROOT, 'model-pricing.json');
 const MODELS_FILE = path.join(ROOT, 'models.config.json');
-const CATALOGUE_URL = 'https://openrouter.ai/api/v1/models';
+/** Generated: descriptions, specs, benchmarks. Never hand-edited (see the plan). */
+const DETAILS_FILE = path.join(ROOT, 'model-details.json');
+import { CATALOGUE_URL, fetchUpstream, matchUpstream } from './lib/model-upstream.mjs';
 
 const dryRun = process.argv.includes('--dry-run');
 
+/**
+ * A direct provider's OpenRouter vendor name, when it differs from ours:
+ * `glm/glm-5.3` is `z-ai/glm-5.3` upstream, `kimi/kimi-k3` is `moonshotai/kimi-k3`.
+ * Used for details only — prices for direct entries come from the vendor's own price list.
+ */
+const VENDOR_ALIAS = { glm: 'z-ai', kimi: 'moonshotai' };
+
+/**
+ * Same model, different name on OpenRouter. Only exact same-model cases belong here: a
+ * different tier (`-highspeed`) or another vendor's copy of the weights is a curated
+ * `info` block, not an alias, because description and benchmarks would be someone else's.
+ */
+const MODEL_ALIAS = {
+  'deepseek/deepseek-flash': 'deepseek/deepseek-v4.1-flash',   // our name for DeepSeek's V4.1
+};
+
+/**
+ * Try the id with its version separators swapped: our `claude-haiku-4-5` is OpenRouter's
+ * `claude-haiku-4.5`. A normalisation, not an alias: the name is otherwise identical.
+ */
+function separatorVariants(id) {
+  return [
+    id.replace(/-(\d+)-(\d+)$/, '-$1.$2'),   // claude-haiku-4-5 → claude-haiku-4.5
+    id.replace(/-(\d+)\.(\d+)$/, '-$1-$2'), // and the other way round
+  ].filter((v) => v !== id);
+}
+
 function perMillion(raw) {
   if (raw === undefined || raw === null) return null;
   const n = parseFloat(raw);
@@ -72,19 +101,119 @@ function upstreamCandidates(id) {
   return stripped === id ? [id] : [stripped, id];
 }
 
+/** The fields the details modal shows, taken from the OpenRouter entry. */
+function detailsFor(up) {
+  const a = up.architecture ?? {};
+  const tp = up.top_provider ?? {};
+  const fields = {
+    description: up.description,
+    created: up.created ? new Date(up.created * 1000).toISOString().slice(0, 10) : undefined,
+    context: up.context_length,
+    providerContext: tp.context_length,
+    maxOutput: tp.max_completion_tokens,
+    tokenizer: a.tokenizer,
+    instructType: a.instruct_type,
+    knowledgeCutoff: up.knowledge_cutoff,
+    huggingFaceId: up.hugging_face_id,
+    canonicalSlug: up.canonical_slug,
+    url: `https://openrouter.ai/${up.id}`,
+    reasoning: up.reasoning,
+    supportedParameters: up.supported_parameters,
+    moderated: tp.is_moderated === true ? true : undefined,
+    benchmarks: up.benchmarks,
+  };
+  // Drop what upstream does not have: the modal hides absent fields, it never prints "n/a".
+  return Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined && v !== null));
+}
+
+/**
+ * Parameter count and architecture, from the model's Hugging Face card. OpenRouter does
+ * not publish sizes and only the open-weight models have a card: a model without one (or
+ * a card without safetensors metadata) simply gets no `params`, and the modal hides the
+ * row. `--no-hf` skips the lookups entirely.
+ */
+async function huggingFaceFacts(hfId) {
+  try {
+    const [meta, config] = await Promise.all([
+      fetch(`https://huggingface.co/api/models/${hfId}?blobs=true`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(20_000) })
+        .then((r) => (r.ok ? r.json() : null)).catch(() => null),
+      // The API's summary config is reduced; the raw file is what carries the architecture.
+      fetch(`https://huggingface.co/${hfId}/raw/main/config.json`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(20_000) })
+        .then((r) => (r.ok ? r.json() : null)).catch(() => null),
+    ]);
+    if (!meta && !config) return null;
+
+    const out = {};
+    const total = meta?.safetensors?.total;
+    if (typeof total === 'number' && total > 0) out.params = total;
+
+    // A multimodal model nests its language model under text_config; text-only ones are flat.
+    const cfg = config ?? meta?.config ?? {};
+    const text = cfg.text_config ?? cfg;
+    const num = (v) => (typeof v === 'number' ? v : undefined);
+    const experts = num(text.num_experts) ?? num(text.n_routed_experts);
+    const perToken = num(text.num_experts_per_tok) ?? num(text.n_experts_per_tok);
+    const byDtype = meta?.safetensors?.parameters;
+    const tags = Array.isArray(meta?.tags) ? meta.tags : [];
+    const card = meta?.cardData ?? {};
+    // The weights' on-disk size: what pulling this model actually costs.
+    const weightsBytes = (Array.isArray(meta?.siblings) ? meta.siblings : [])
+      .filter((f) => typeof f?.rfilename === 'string' && f.rfilename.endsWith('.safetensors'))
+      .reduce((sum, f) => sum + (Number(f.size) || 0), 0);
+
+    const hf = {
+      id: hfId,
+      total,
+      byDtype: byDtype && Object.keys(byDtype).length ? byDtype : undefined,
+      family: (Array.isArray(cfg.architectures) ? cfg.architectures[0] : undefined) ?? undefined,
+      modelType: typeof cfg.model_type === 'string' ? cfg.model_type : undefined,
+      moe: experts ? { experts, perToken, shared: num(text.n_shared_experts) } : undefined,
+      layers: num(text.num_hidden_layers),
+      hidden: num(text.hidden_size),
+      heads: num(text.num_attention_heads),
+      kvHeads: num(text.num_key_value_heads),
+      vocab: num(text.vocab_size),
+      context: num(text.max_position_embeddings),
+      vision: cfg.vision_config ? true : undefined,
+      quantization: cfg.quantization_config?.quant_method ?? (tags.includes('compressed-tensors') ? 'compressed-tensors' : undefined),
+      task: typeof meta?.pipeline_tag === 'string' ? meta.pipeline_tag : undefined,
+      languages: Array.isArray(card.language) ? card.language : undefined,
+      license: typeof card.license === 'string' ? card.license : undefined,
+      // `license: other` carries a custom name in license_name (often the model's own, not an id).
+      licenseName: typeof card.license_name === 'string' && card.license_name !== card.license ? card.license_name : undefined,
+      published: typeof meta?.createdAt === 'string' ? meta.createdAt.slice(0, 10) : undefined,
+      updated: typeof meta?.lastModified === 'string' ? meta.lastModified.slice(0, 10) : undefined,
+      weightsBytes: weightsBytes > 0 ? weightsBytes : undefined,
+      // Keep the tags that say something about the model; drop the plumbing
+      // (transformers, safetensors, the model type, the task, languages, licence/arxiv markers).
+      tags: (() => {
+        const drop = new Set(['transformers', 'safetensors', 'eval-results', 'endpoints_compatible', 'region:us',
+          'text-generation', 'image-text-to-text', 'feature-extraction', 'conversational', cfg.model_type]);
+        const kept = tags.filter((t) => typeof t === 'string' && !t.includes(':') && !drop.has(t) && !/^[a-z]{2}$/.test(t));
+        return kept.length ? kept : undefined;
+      })(),
+      downloads: num(meta?.downloads),
+      likes: num(meta?.likes),
+    };
+    const cleaned = Object.fromEntries(Object.entries(hf).filter(([, v]) => v !== undefined));
+    if (Object.keys(cleaned).length > 1) out.hf = cleaned;  // > 1: the id alone says nothing
+    out.paramsSource = 'huggingface';
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf-8')); } catch { return null; }
+}
+
 async function main() {
   console.log(`Fetching ${CATALOGUE_URL} …`);
-  const res = await fetch(CATALOGUE_URL, { headers: { accept: 'application/json' } });
-  if (!res.ok) {
-    console.error(`✗ Catalogue returned HTTP ${res.status}`);
-    process.exit(1);
-  }
-  const body = await res.json();
-  if (!Array.isArray(body?.data) || body.data.length === 0) {
-    console.error('✗ Unexpected catalogue shape');
+  const live = await fetchUpstream().catch((e) => {
+    console.error(`✗ ${e instanceof Error ? e.message : String(e)}`);
     process.exit(1);
-  }
-  const live = new Map(body.data.map((m) => [m.id, m]));
+  });
   console.log(`  ${live.size} models upstream\n`);
 
   const modelsDoc = JSON.parse(fs.readFileSync(MODELS_FILE, 'utf-8'));
@@ -99,10 +228,7 @@ async function main() {
   for (const m of models) {
     if (m.provider !== 'openrouter') continue;
 
-    let up = null;
-    for (const candidate of upstreamCandidates(m.id)) {
-      if (live.has(candidate)) { up = live.get(candidate); break; }
-    }
+    const up = matchUpstream(live, m.id);
     if (!up) {
       missing++;
       console.log(`  ? ${m.id} — not in the upstream catalogue, left as-is`);
@@ -140,6 +266,38 @@ async function main() {
   console.log(`\nPricing:  ${priceChanges.length} changed`);
   for (const c of priceChanges) console.log(`  ${c.id}\n      ${c.from}  →  ${c.to}`);
 
+  // ── Details ────────────────────────────────────────────────────────────────
+  // One entry per catalogue model we can match upstream, so the file's key space is
+  // our catalogue's. Direct entries are matched through VENDOR_ALIAS for the data
+  // only; their price stays in model-pricing.json, from their own vendor.
+  const upstreamMatch = (id) => matchUpstream(live, id);
+  const details = {};
+  for (const m of models) {
+    const up = upstreamMatch(m.id);
+    if (up) details[m.id] = detailsFor(up);
+  }
+  // Hugging Face pass: sizes for the open-weight models, small concurrency.
+  if (!process.argv.includes('--no-hf')) {
+    const withHf = Object.entries(details).filter(([, v]) => v.huggingFaceId);
+    const queue = [...withHf];
+    const worker = async () => {
+      while (queue.length) {
+        const [id, entry] = queue.shift();
+        const facts = await huggingFaceFacts(entry.huggingFaceId);
+        if (facts) Object.assign(entry, facts, { paramsSource: 'huggingface' });
+      }
+    };
+    await Promise.all(Array.from({ length: 8 }, worker));
+    console.log(`\nParameters: ${withHf.filter(([, v]) => v.params).length} of ${withHf.length} Hugging Face cards answered`);
+  }
+
+  const previous = readJson(DETAILS_FILE);
+  const sameDetails = previous?.models && JSON.stringify(previous.models) === JSON.stringify(details);
+  const generatedAt = sameDetails && previous.generatedAt ? previous.generatedAt : new Date().toISOString();
+
+  console.log(`\nDetails: ${Object.keys(details).length} of ${models.length} models matched upstream` +
+    (sameDetails ? ' (unchanged)' : ''));
+
   console.log(`\nModality: ${modalityChanges.length} changed`);
   for (const c of modalityChanges) console.log(`  ${c.id}\n      ${c.from}  →  ${c.to}`);
 
@@ -149,7 +307,7 @@ async function main() {
     `${direct} direct-provider (different vendor, different rates — update by hand)`,
   );
 
-  if (priceChanges.length === 0 && modalityChanges.length === 0) {
+  if (priceChanges.length === 0 && modalityChanges.length === 0 && sameDetails) {
     console.log('\n✓ Already up to date.');
     return;
   }
@@ -161,6 +319,7 @@ async function main() {
 
   fs.writeFileSync(PRICING_FILE, serialisePricing(pricing), 'utf-8');
   fs.writeFileSync(MODELS_FILE, JSON.stringify(modelsDoc, null, 2) + '\n', 'utf-8');
+  fs.writeFileSync(DETAILS_FILE, JSON.stringify({ source: 'openrouter', generatedAt, models: details }, null, 2) + '\n', 'utf-8');
   console.log('\n✓ Wrote model-pricing.json and models.config.json');
   console.log('  Review the diff before committing.');
 }