promptgraph-mcp 2.4.6 → 2.4.8

package/search.js

@@ -2,6 +2,26 @@ import { embed, cosineSimilarity } from './embedder.js';
 import { getDb, blobToVec } from './db.js';
 import { annSearch } from './ann.js';
 
+let embedWeight = 0.7;
+let bm25Weight = 0.3;
+
+export function setHybridWeights(ew, bw) {
+  embedWeight = ew;
+  bm25Weight = bw;
+}
+
+function adaptWeights(query) {
+  // Technical terms (caps, digits) → BM25 matters more
+  const hasTechTerms = /[A-Z]|\d/.test(query);
+  if (hasTechTerms) {
+    embedWeight = 0.5;
+    bm25Weight = 0.5;
+  } else {
+    embedWeight = 0.7;
+    bm25Weight = 0.3;
+  }
+}
+
 function applyRatingBoost(db, id, score) {
   const r = db.prepare('SELECT success, fail FROM ratings WHERE skill_id = ?').get(id);
   if (r && (r.success + r.fail) > 3) {
@@ -11,13 +31,13 @@ function applyRatingBoost(db, id, score) {
   return score;
 }
 
-export async function search(query, topK = 5) {
-  const db = getDb();
-  const queryVec = await embed(query);
-
-  // Try ANN index first (fast, O(log N))
-  const annResults = await annSearch(queryVec, topK * 4);
+function normalizeBM25(raw) {
+  return Math.max(0, 1 + raw / 10);
+}
 
+async function runEmbeddingSearch(db, queryVec, topK) {
+  // Try ANN index first (fast)
+  const annResults = await annSearch(queryVec, topK);
   if (annResults && annResults.length > 0) {
     const bestBySkill = new Map();
     for (const r of annResults) {
@@ -25,11 +45,8 @@ export async function search(query, topK = 5) {
       if (!prev || r.score > prev) bestBySkill.set(r.skill_id, r.score);
     }
     return [...bestBySkill.entries()]
-      .map(([id, score]) => ({ id, score: applyRatingBoost(db, id, score) }))
-      .sort((a, b) => b.score - a.score)
-      .slice(0, topK)
-      .map(({ id, score }) => skillWithSnippet(db, id, score))
-      .filter(Boolean);
+      .map(([id, score]) => ({ id, score: Math.max(0, score) }))
+      .sort((a, b) => b.score - a.score);
   }
 
   // Fallback: brute force cosine (used before first reindex)
@@ -42,14 +59,14 @@ export async function search(query, topK = 5) {
       if (!prev || score > prev) bestBySkill.set(chunk.skill_id, score);
     }
     return [...bestBySkill.entries()]
-      .map(([id, score]) => ({ id, score: applyRatingBoost(db, id, score) }))
-      .sort((a, b) => b.score - a.score)
-      .slice(0, topK)
-      .map(({ id, score }) => skillWithSnippet(db, id, score))
-      .filter(Boolean);
+      .map(([id, score]) => ({ id, score: Math.max(0, score) }))
+      .sort((a, b) => b.score - a.score);
   }
 
-  // Fast-mode fallback: FTS5 keyword search (no embeddings)
+  return [];
+}
+
+function runBM25Search(db, query, topK) {
   try {
     const terms = query.replace(/[^\w\s]/g, ' ').trim().split(/\s+/).filter(Boolean).join(' OR ');
     const rows = db.prepare(
@@ -57,14 +74,61 @@ export async function search(query, topK = 5) {
        JOIN skills s ON skills_fts.id = s.id
        WHERE skills_fts MATCH ? ORDER BY score LIMIT ?`
     ).all(terms, topK);
-    return rows.map(r => skillWithSnippet(db, r.id, Math.max(0, 1 + r.score / 10))).filter(Boolean);
+    return rows.map(r => ({ id: r.id, score: normalizeBM25(r.score) }));
   } catch {
     return [];
   }
 }
 
+export async function search(query, topK = 5) {
+  const db = getDb();
+  adaptWeights(query);
+  const queryVec = await embed(query);
+
+  const embedResults = await runEmbeddingSearch(db, queryVec, topK * 4);
+  const bm25Results = runBM25Search(db, query, topK * 4);
+
+  // Fallback: pure BM25 if embeddings unavailable
+  if (!embedResults.length) {
+    return bm25Results.slice(0, topK)
+      .map(r => skillWithSnippet(db, r.id, applyRatingBoost(db, r.id, r.score)))
+      .filter(Boolean);
+  }
+
+  // Fallback: pure embedding if BM25 returns nothing
+  if (!bm25Results.length) {
+    return embedResults.slice(0, topK)
+      .map(({ id, score }) => skillWithSnippet(db, id, applyRatingBoost(db, id, score)))
+      .filter(Boolean);
+  }
+
+  // Hybrid: combine normalized scores from both signals
+  const combined = new Map();
+  for (const { id, score } of embedResults) {
+    combined.set(id, { embedScore: score, bm25Score: 0 });
+  }
+  for (const { id, score } of bm25Results) {
+    const entry = combined.get(id);
+    if (entry) {
+      entry.bm25Score = score;
+    } else {
+      combined.set(id, { embedScore: 0, bm25Score: score });
+    }
+  }
+
+  return [...combined.entries()]
+    .map(([id, s]) => ({
+      id,
+      score: embedWeight * s.embedScore + bm25Weight * s.bm25Score,
+    }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, topK)
+    .map(({ id, score }) => skillWithSnippet(db, id, applyRatingBoost(db, id, score)))
+    .filter(Boolean);
+}
+
 function skillWithSnippet(db, id, score) {
-  const skill = db.prepare('SELECT id, name, description, path, source, content FROM skills WHERE id = ?').get(id);
+  const skill = db.prepare('SELECT id, name, description, path, source, content, version, author, license, updated_at, downloads, verified FROM skills WHERE id = ?').get(id);
   if (!skill) return null;
   const { content, ...rest } = skill;
   const snippet = content?.replace(/^---[\s\S]*?---\n?/, '').trim().slice(0, 400) || '';
@@ -131,5 +195,5 @@ export function getImpact(nameOrId) {
 
 export function listAll() {
   const db = getDb();
-  return db.prepare('SELECT id, name, description, source FROM skills ORDER BY source, name').all();
+  return db.prepare('SELECT id, name, description, source, version, author, license, updated_at, downloads, verified FROM skills ORDER BY source, name').all();
 }

package/src/filter/classifier.js

@@ -0,0 +1,88 @@
+import { cosineSimilarity } from '../../embedder.js';
+
+const SKILL_THRESHOLD = 0.35;
+const UNSURE_THRESHOLD = 0.15;
+
+const DOC_FIRST_HEADERS = /^(overview|introduction|about|background|welcome|getting started|what is|why |table of contents|toc|foreword|preface|readme)/i;
+const INSTRUCTION_HEADERS = /^#{1,3}\s+(steps?|usage|instructions?|how\s+to|when\s+to\s+use|workflow|process|procedure|example|examples?|commands?|output|result)/i;
+const IMPERATIVE_HEADERS = /\b(run|use|apply|execute|check|debug|fix|create|add|remove|deploy|test|write|generate|analyze|review|refactor|optimize|configure|setup|install|scan|audit|validate|search|find|extract|parse)\b/i;
+
+export function getFeatureVector(raw) {
+  const lines = raw.split('\n');
+  const nonEmpty = lines.filter(l => l.trim());
+  const headers = nonEmpty.filter(l => /^#{1,3}\s/.test(l));
+  const paragraphs = raw.split(/\n\n+/).filter(p => p.trim() && !p.trim().startsWith('#'));
+  const words = raw.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+
+  const firstHeader = headers[0]?.replace(/^#+\s*/, '') || '';
+  const longProse = paragraphs.filter(p => p.split(' ').length > 60 && !/```/.test(p));
+  const wordRatio = words.length > 80 ? new Set(words).size / words.length : 1;
+
+  return [
+    Number(raw.length >= 150),
+    Number(headers.length >= 1),
+    Number(lines.some(l => INSTRUCTION_HEADERS.test(l))),
+    Number(headers.some(h => IMPERATIVE_HEADERS.test(h))),
+    Number(raw.includes('```') || raw.includes('    ')),
+    Number(nonEmpty.some(l => /^\d+\.\s/.test(l))),
+    Number(nonEmpty.some(l => /^[-*+]\s/.test(l))),
+    Number(headers.length >= 2),
+    Number(headers.length >= 4),
+    Number(DOC_FIRST_HEADERS.test(firstHeader)) ? 1 : 0,
+    Number(longProse.length > paragraphs.length * 0.6 && paragraphs.length > 3) ? 1 : 0,
+    Number(wordRatio >= 0.22) ? 0 : 1,
+    Number(raw.length < 150) ? 1 : 0,
+    Number(headers.length < 1) ? 1 : 0,
+  ];
+}
+
+/**
+ * Rule A override: if centroid says reject/unsure but file clearly looks like
+ * a skill by content (code + instructions + list + verbs, no SKILL in name/path),
+ * override to skill. Catches adversarial wrong-heading cases with 0 FP cost.
+ */
+function ruleA(rawVec, raw, filePath) {
+  const fv = getFeatureVector(raw);
+  const hasCode = fv[4];
+  const hasInstructions = fv[2];
+  const hasNumberedList = fv[5];
+  const hasVerb = fv[3];
+  const filename = filePath ? filePath.split(/[/\\]/).pop().replace(/\.md$/i, '').toUpperCase() : '';
+  const pathUpper = filePath ? filePath.toUpperCase() : '';
+  const hasSkillName = filename.includes('SKILL');
+  const hasSkillPath = /SKILL/.test(pathUpper);
+
+  if (hasCode && hasInstructions && hasNumberedList && hasVerb && !hasSkillName && !hasSkillPath) {
+    return { label: 'skill', score: 0.6, method: 'ruleA' };
+  }
+  return null;
+}
+
+export function classify(rawVec, centroids, raw, filePath) {
+  if (!centroids) {
+    return { label: 'skill', score: 1, method: 'fallback' };
+  }
+
+  const goodSim = centroids.good ? cosineSimilarity(rawVec, centroids.good) : 0;
+  const badSim = centroids.bad ? cosineSimilarity(rawVec, centroids.bad) : 0;
+
+  const rawScore = goodSim - badSim;
+  const score = (rawScore + 1) / 2;
+
+  if (score >= SKILL_THRESHOLD) {
+    return { label: 'skill', score, goodSim, badSim, method: 'centroid' };
+  }
+
+  // Below threshold — try Rule A content override
+  if (raw && filePath) {
+    const override = ruleA(rawVec, raw, filePath);
+    if (override) return override;
+  }
+
+  if (score >= UNSURE_THRESHOLD) {
+    return { label: 'unsure', score, goodSim, badSim, method: 'centroid' };
+  }
+  return { label: 'reject', score, goodSim, badSim, method: 'centroid' };
+}
+
+export { SKILL_THRESHOLD, UNSURE_THRESHOLD };

package/src/filter/cluster.js

@@ -0,0 +1,52 @@
+import { cosineSimilarity } from '../../embedder.js';
+
+const INFERENCE_THRESHOLD = 0.35;
+
+export function findClusters(skills, embeddings) {
+  if (!skills.length || !embeddings) return [];
+  const clusters = [];
+  const assigned = new Set();
+
+  for (let i = 0; i < skills.length; i++) {
+    if (assigned.has(i)) continue;
+    const cluster = { centroid: embeddings[i], members: [skills[i]], indices: [i] };
+    assigned.add(i);
+
+    for (let j = i + 1; j < skills.length; j++) {
+      if (assigned.has(j)) continue;
+      if (cosineSimilarity(embeddings[i], embeddings[j]) >= INFERENCE_THRESHOLD) {
+        cluster.members.push(skills[j]);
+        cluster.indices.push(j);
+        assigned.add(j);
+      }
+    }
+
+    clusters.push(cluster);
+  }
+
+  return clusters;
+}
+
+export function expandResults(annResults, db) {
+  if (!annResults || annResults.length === 0) return annResults;
+
+  const seenIds = new Set();
+  const expanded = [];
+
+  for (const r of annResults) {
+    if (!seenIds.has(r.skill_id)) {
+      seenIds.add(r.skill_id);
+      expanded.push(r);
+    }
+
+    const callees = db.prepare('SELECT to_skill FROM edges WHERE from_skill = ?').all(r.skill_id);
+    for (const c of callees) {
+      if (!seenIds.has(c.to_skill)) {
+        seenIds.add(c.to_skill);
+        expanded.push({ skill_id: c.to_skill, score: r.score * 0.85 });
+      }
+    }
+  }
+
+  return expanded.sort((a, b) => b.score - a.score);
+}

package/src/filter/dedup.js

@@ -0,0 +1,36 @@
+import { cosineSimilarity } from '../../embedder.js';
+
+const DEDUP_THRESHOLD = 0.97;
+
+export function dedup(skills, embeddings) {
+  if (!skills.length) return { skills: [], embeddings: [] };
+  if (embeddings && embeddings.length !== skills.length) {
+    throw new Error('embeddings length must match skills length');
+  }
+
+  const keep = [true]; // first skill always kept
+  const kept = [0];
+
+  for (let i = 1; i < skills.length; i++) {
+    let dup = false;
+    if (embeddings) {
+      for (const j of kept) {
+        if (cosineSimilarity(embeddings[i], embeddings[j]) >= DEDUP_THRESHOLD) {
+          dup = true;
+          break;
+        }
+      }
+    }
+    if (dup) {
+      keep.push(false);
+    } else {
+      keep.push(true);
+      kept.push(i);
+    }
+  }
+
+  return {
+    skills: skills.filter((_, i) => keep[i]),
+    embeddings: embeddings ? embeddings.filter((_, i) => keep[i]) : undefined,
+  };
+}

package/src/filter/hard-filter.js

@@ -0,0 +1,59 @@
+import fs from 'fs';
+
+const SKIP_FILENAMES = new Set([
+  'readme', 'changelog', 'license', 'contributing', 'code-of-conduct',
+  'security', 'authors', 'credits', 'install', 'installation', 'usage',
+  'engagements', 'contributors', 'maintainers', 'acknowledgements',
+  'faq', 'glossary', 'index', 'overview', 'summary', 'roadmap', 'todo',
+  'notes', 'template', 'example', 'sample', 'demo', 'getting-started',
+  'quickstart', 'guide', 'tutorial', 'walkthrough', 'architecture',
+  'design', 'spec', 'specification', 'requirements', 'privacy', 'terms',
+  'disclaimer', 'notice', 'copying', 'warranty', 'codeofconduct',
+  'pull_request_template', 'issue_template', 'funding',
+]);
+
+const SKIP_FILENAME_RE = /^(_|\.)|^v?\d+[\.\-]\d+|^\d{4}[\-_]\d{2}|^readme|^license|^changelog|^contributing|^code.of.conduct|^security|^authors|^credits|^disclaimer|^notice|^copying|^warranty|^promotion|^funding/i;
+
+const SKIP_DIRS = new Set([
+  '.github', 'docs', 'doc', 'documentation', 'examples', 'example',
+  'tests', 'test', '__tests__', 'spec', 'fixtures', 'assets', 'images',
+  'img', 'screenshots', 'media', 'static', 'public', 'dist', 'build',
+  'node_modules', 'vendor', 'third_party',
+  'references', 'reference', 'refs', 'cheatsheet', 'cheat-sheet',
+  'cheatsheets', 'resources',
+]);
+
+const BADGE_RE = /!\[.*\]\(https?:\/\/(img\.shields\.io|badge\.fury|travis-ci|github\.com\/[^)]+\/badge)/i;
+const README_HEADER_RE = /^#\s*readme\b/i;
+
+export function hardFilter(filePath, raw) {
+  const parts = filePath.replace(/\\/g, '/').split('/');
+  const filename = parts[parts.length - 1];
+  const base = filename.replace(/\.md$/i, '').toLowerCase();
+
+  if (SKIP_FILENAMES.has(base)) {
+    return { pass: false, reason: `skip filename: ${base}` };
+  }
+
+  if (SKIP_FILENAME_RE.test(base)) {
+    return { pass: false, reason: `skip filename pattern: ${base}` };
+  }
+
+  for (const part of parts.slice(0, -1)) {
+    if (SKIP_DIRS.has(part.toLowerCase())) {
+      return { pass: false, reason: `skip dir: ${part}` };
+    }
+  }
+
+  if (raw) {
+    const firstLines = raw.trimStart().slice(0, 300);
+    if (README_HEADER_RE.test(firstLines)) {
+      return { pass: false, reason: 'starts with # Readme' };
+    }
+    if (BADGE_RE.test(firstLines)) {
+      return { pass: false, reason: 'badge-only content' };
+    }
+  }
+
+  return { pass: true };
+}

package/src/filter/train.js

@@ -0,0 +1,66 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { globSync } from 'glob';
+import { embedBatch } from '../../embedder.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TRAINING_DIR = path.resolve(__dirname, '../../registry/training');
+const MODEL_PATH = path.join(os.homedir(), '.claude', '.promptgraph', 'model.json');
+
+function readAllMd(dir) {
+  const files = globSync(`${dir}/**/*.md`);
+  return files.map(f => fs.readFileSync(f, 'utf8'));
+}
+
+function meanVector(vectors) {
+  if (!vectors.length) return null;
+  const dim = vectors[0].length;
+  const centroid = new Float32Array(dim);
+  for (const v of vectors) {
+    for (let i = 0; i < dim; i++) centroid[i] += v[i];
+  }
+  for (let i = 0; i < dim; i++) centroid[i] /= vectors.length;
+  return Array.from(centroid);
+}
+
+export async function train() {
+  const goodDir = path.join(TRAINING_DIR, 'good');
+  const badDir = path.join(TRAINING_DIR, 'bad');
+
+  const goodTexts = readAllMd(goodDir);
+  const badTexts = readAllMd(badDir);
+
+  if (goodTexts.length < 1 || badTexts.length < 1) {
+    throw new Error(`Need at least 1 good and 1 bad training example (good: ${goodTexts.length}, bad: ${badTexts.length})`);
+  }
+
+  const allTexts = [...goodTexts, ...badTexts];
+  const allVecs = await embedBatch(allTexts);
+
+  const goodVecs = allVecs.slice(0, goodTexts.length);
+  const badVecs = allVecs.slice(goodTexts.length);
+
+  const model = {
+    version: 1,
+    good: meanVector(goodVecs),
+    bad: meanVector(badVecs),
+    counts: { good: goodTexts.length, bad: badTexts.length },
+  };
+
+  fs.mkdirSync(path.dirname(MODEL_PATH), { recursive: true });
+  fs.writeFileSync(MODEL_PATH, JSON.stringify(model));
+  return model;
+}
+
+export function loadModel() {
+  try {
+    const raw = fs.readFileSync(MODEL_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export { MODEL_PATH };

package/src/store/flat-store.js

@@ -0,0 +1,61 @@
+import { VectorStore } from './vector-store.js';
+
+export class FlatVectorStore extends VectorStore {
+  constructor() {
+    super();
+    this._items = [];
+  }
+
+  async add(id, vector) {
+    this._items.push({ skill_id: id, vec: new Float32Array(vector) });
+  }
+
+  async addBatch(entries) {
+    for (const { id, vector } of entries) {
+      this._items.push({ skill_id: id, vec: new Float32Array(vector) });
+    }
+  }
+
+  async remove(id) {
+    this._items = this._items.filter(item => item.skill_id !== id);
+  }
+
+  async search(vector, topK = 20) {
+    const qArr = new Float32Array(vector);
+    const bestBySkill = new Map();
+    for (const entry of this._items) {
+      const score = cosineSim(qArr, entry.vec);
+      const prev = bestBySkill.get(entry.skill_id);
+      if (!prev || score > prev) bestBySkill.set(entry.skill_id, score);
+    }
+    return [...bestBySkill.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, topK)
+      .map(([skill_id, score]) => ({ skill_id, score }));
+  }
+
+  async build(entries) {
+    this._items = [];
+    for (const { skill_id, vector } of entries) {
+      this._items.push({ skill_id, vec: new Float32Array(vector) });
+    }
+  }
+
+  async clear() {
+    this._items = [];
+  }
+
+  get size() {
+    return this._items.length;
+  }
+}
+
+function cosineSim(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-8);
+}