Repository Public Research preview
1/**2 * =============================================================================3 * SP BOUCHER | SOFTWARE & RESEARCH4 * ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING5 * =============================================================================6 *7 * Project : LLM API toolkits8 * File : scholarly/mcp/lib/match.mjs9 * Module : scholarly10 * Repository : https://git.spboucher.ai/llm-api-toolkits11 * Created : 2026-11-1012 * Last Modified : 2026-11-1013 *14 * Author : Simon-Pierre Boucher15 * Position : Professor of Finance16 * Institution : Université du Québec en Outaouais (UQO)17 * Organization : SP Boucher18 * Website : https://spboucher.ai19 * Git : https://git.spboucher.ai20 *21 * Preferred Contact: dev@spboucher.ai22 * Development : dev@spboucher.ai23 * Support : support@spboucher.ai24 * Security/Admin : admin@spboucher.ai25 *26 * Copyright (c) 202627 * Simon-Pierre Boucher28 * All rights reserved where applicable. This file is governed by the29 * applicable project license, copyright notices and relevant law.30 * Existing third-party rights and notices remain unaffected.31 *32 * License : None specified (no license file in this repository)33 *34 * Do not embed credentials, private keys, access tokens,35 * certificates or confidential personal information.36 *37 * =============================================================================38 * END OF SP BOUCHER SOURCE HEADER39 * =============================================================================40 */4142import { extractArxivId, extractDoi, familyName, foldText, normalizeTitle, parseYear, sameFamily, titleSimilarity, titleTokens } from "./normalize.mjs";4344/**45 * Compare what a citation claims with what a registry says, and decide whether a search hit is46 * the cited work. Everything here is a heuristic on strings: thresholds are documented, and the47 * verdict always comes with the per-field evidence so a human can overrule it.48 */49export const THRESHOLDS = { title_match: 0.9, title_close: 0.75 };5051const venueTokens = (s) => foldText(s).replace(/&/g, " and ").replace(/[^a-z0-9. ]+/g, " ").split(/\s+/).map((t) => t.replace(/\.+$/, "")).filter((t) => t && !["of", "the", "and", "for", "in", "on", "de", "la", "des", "et", "a", "an"].includes(t));5253/** "J. Econom." matches "Journal of Econometrics": every claimed token is a prefix of the next registry tokens, in order. */54export function sameVenue(claimed, actual) {55 const a = venueTokens(claimed), b = venueTokens(actual);56 if (!a.length || !b.length) return null;57 if (a.join(" ") === b.join(" ")) return true;58 const abbrev = (x, y) => { let j = 0; for (const t of x) { while (j < y.length && !y[j].startsWith(t)) j++; if (j >= y.length) return false; j++; } return true; };59 if (abbrev(a, b) || abbrev(b, a)) return true;60 // Acronym against full name: "JFE" vs "Journal of Financial Economics".61 const acr = (x, y) => x.length === 1 && x[0].length >= 2 && x[0] === y.map((t) => t[0]).join("");62 if (acr(a, b) || acr(b, a)) return true;63 const A = new Set(a), inter = b.filter((t) => A.has(t)).length;64 return (2 * inter) / (a.length + b.length) >= 0.8;65}6667const firstPage = (p) => /[A-Za-z]?\d+/.exec(String(p ?? ""))?.[0]?.toLowerCase() ?? null;68const claimAuthors = (c) => (Array.isArray(c.authors) && c.authors.length ? c.authors : c.first_author ? [c.first_author] : []);6970/**71 * Field-by-field comparison. Status per field: "match", "close" (title only), "off_by_one" (year only),72 * "mismatch", or "not_claimed" / "not_in_record" when one side is empty.73 * Verdict: "match" (nothing differs), "minor_differences" (only close title, off-by-one year, venue or74 * author-count differences) or "mismatch" (title, first author or year disagree).75 */76export function compareWork(claim, work) {77 const fields = {}, mismatches = [], warnings = [];78 const put = (name, claimed, actual, status, extra = {}) => { fields[name] = { claimed: claimed ?? null, actual: actual ?? null, status, ...extra }; };7980 if (claim.title) {81 const full = work.subtitle ? `${work.title}: ${work.subtitle}` : work.title;82 const sim = Math.max(titleSimilarity(claim.title, work.title), work.subtitle ? titleSimilarity(claim.title, full) : 0);83 const status = !work.title ? "not_in_record" : sim >= THRESHOLDS.title_match ? "match" : sim >= THRESHOLDS.title_close ? "close" : "mismatch";84 put("title", claim.title, work.title, status, { similarity: sim });85 if (status === "mismatch") mismatches.push("title"); else if (status === "close") warnings.push("title");86 } else put("title", null, work.title, "not_claimed");8788 const ca = claimAuthors(claim), wa = work.authors ?? [];89 if (ca.length) {90 const status = !wa.length ? "not_in_record" : sameFamily(ca[0], wa[0]) ? "match" : wa.some((a) => sameFamily(ca[0], a)) ? "order_differs" : "mismatch";91 put("first_author", typeof ca[0] === "string" ? ca[0] : ca[0].name ?? ca[0].family, wa[0]?.name ?? wa[0]?.family ?? null, status);92 if (status === "mismatch") mismatches.push("first_author"); else if (status === "order_differs") warnings.push("first_author");93 if (ca.length > 1 && wa.length && !claim.authors_truncated) {94 const missing = ca.filter((c) => !wa.some((a) => sameFamily(c, a))).map((c) => (typeof c === "string" ? c : c.name ?? c.family));95 const status2 = missing.length ? "mismatch" : ca.length !== wa.length ? "count_differs" : "match";96 put("authors", ca.length, wa.length, status2, missing.length ? { not_in_record: missing } : {});97 if (status2 === "mismatch") mismatches.push("authors"); else if (status2 === "count_differs") warnings.push("authors");98 }99 } else put("first_author", null, wa[0]?.name ?? null, "not_claimed");100101 const cy = parseYear(claim.year);102 if (cy) {103 const status = !work.year ? "not_in_record" : cy === work.year ? "match" : Math.abs(cy - work.year) === 1 ? "off_by_one" : "mismatch";104 put("year", cy, work.year, status);105 if (status === "mismatch") mismatches.push("year"); else if (status === "off_by_one") warnings.push("year");106 } else put("year", null, work.year, "not_claimed");107108 if (claim.venue) {109 const same = sameVenue(claim.venue, work.venue ?? "");110 const status = same == null ? "not_in_record" : same ? "match" : "differs";111 put("venue", claim.venue, work.venue, status);112 if (status === "differs") warnings.push("venue");113 }114 if (claim.volume && work.volume) { const s = String(claim.volume).trim() === String(work.volume).trim() ? "match" : "differs"; put("volume", claim.volume, work.volume, s); if (s === "differs") warnings.push("volume"); }115 if (claim.pages && work.pages) { const s = firstPage(claim.pages) === firstPage(work.pages) ? "match" : "differs"; put("pages", claim.pages, work.pages, s); if (s === "differs") warnings.push("pages"); }116117 const checked = Object.values(fields).filter((f) => !["not_claimed", "not_in_record"].includes(f.status)).length;118 return { verdict: mismatches.length ? "mismatch" : warnings.length ? "minor_differences" : "match", mismatches, warnings, fields_checked: checked, fields };119}120121/** Share of a registry title's tokens that appear in a free-text reference, in 0..1. */122export function titleContainment(text, title) {123 const hay = new Set(normalizeTitle(text).split(" ")), toks = titleTokens(title);124 if (!toks.length) return 0;125 return Math.round((toks.filter((t) => hay.has(t)).length / toks.length) * 1000) / 1000;126}127128/**129 * Best-effort split of a free-text reference into fields. Works on the common author-date and130 * numeric styles; the caller also keeps the raw text, because the registry search uses it whole.131 */132export function parseReference(text) {133 const raw = String(text ?? "").replace(/\s+/g, " ").trim();134 const doi = extractDoi(raw), arxiv = extractArxivId(raw);135 let body = raw.replace(/^\s*(?:\[\d+\]|\(\d+\)|\d+[.)])\s+/, "").replace(/https?:\/\/\S+/g, " ").replace(/\bdoi:\s*\S+/gi, " ");136 const paren = /\(((?:1[5-9]|20)\d\d)[a-z]?(?:,[^)]*)?\)/.exec(body);137 const years = [...body.matchAll(/\b((?:1[5-9]|20)\d\d)[a-z]?\b/g)].map((m) => ({ y: Number(m[1]), i: m.index }));138 const year = paren ? Number(paren[1]) : years.length ? years.at(-1).y : null;139 let title = null, authorsPart = null;140 const quoted = /[“"]([^”"]{8,})[”"]/.exec(body);141 if (quoted) { title = quoted[1]; authorsPart = body.slice(0, quoted.index); }142 else if (paren) { // Author, A. (1986). Title. Venue…143 authorsPart = body.slice(0, paren.index);144 const rest = body.slice(paren.index + paren[0].length).replace(/^[\s.,:]+/, "");145 title = /^(.+?[?!]|.+?)(?:\.\s|\.$|$)/.exec(rest)?.[1] ?? null;146 } else { // Author A, Author B. Title. Venue. 1986;…147 const segs = body.split(/\.\s+/).map((s) => s.trim()).filter(Boolean);148 if (segs.length >= 2) { authorsPart = segs[0]; title = segs.slice(1).find((s) => s.split(/\s+/).length >= 3 && !/^\d/.test(s)) ?? null; }149 }150 if (title) title = title.replace(/[\s.,;:]+$/, "").trim();151 if (title && title.split(/\s+/).length < 2) title = null;152 let first_author = null;153 if (authorsPart) {154 const a = authorsPart.replace(/\bet al\.?/i, "").split(/,|\band\b|&|;/)[0].trim();155 if (a && a.length <= 60 && /\p{L}{2,}/u.test(a)) first_author = a.replace(/[\s.]+$/, "") || null;156 // Vancouver style puts initials after the family name without a comma: "Vaswani A", "Engle RF".157 const van = first_author && /^(.+?)\s+((?:\p{Lu}\.?){1,3})$/u.exec(first_author);158 if (van && van[1].length >= 2) first_author = `${van[1]}, ${van[2]}`;159 }160 return { raw, doi, arxiv, title, first_author, first_author_family: first_author ? familyName(first_author) || null : null, year };161}162163/**164 * Is this search candidate the cited work? Confident when the title agrees (similarity >= 0.9, or165 * >= 0.9 of the candidate's title words appear in the raw reference) and the first author or the166 * year agrees, with no field contradicting. Very short titles need both author and year.167 */168export function judgeCandidate(claim, work) {169 const sim = claim.title ? titleSimilarity(claim.title, work.title) : 0;170 const contain = claim.raw && work.title ? titleContainment(claim.raw, work.title) : 0;171 const ntok = titleTokens(work.title).length;172 const titleOk = sim >= THRESHOLDS.title_match || (!claim.title && contain >= 0.9 && ntok >= 3) || (claim.title && contain === 1 && ntok >= 5 && sim >= THRESHOLDS.title_close);173 const ca = claimAuthors(claim), w0 = work.authors?.[0];174 let authorOk = ca.length && w0 ? (work.authors ?? []).some((a) => sameFamily(ca[0], a)) : null;175 if (authorOk == null && claim.raw && w0) { const fam = familyName(w0).split(" ").at(-1); authorOk = fam && fam.length >= 3 ? foldText(claim.raw).includes(fam) : null; }176 const cy = parseYear(claim.year);177 const yearOk = cy && work.year ? Math.abs(cy - work.year) <= 1 : null;178 const short = ntok < 3;179 const confident = titleOk && authorOk !== false && yearOk !== false && (short ? authorOk === true && yearOk === true : authorOk === true || yearOk === true);180 const close = !confident && (sim >= THRESHOLDS.title_close || contain >= 0.8) && ntok >= 2;181 const score = Math.round((Math.max(sim, contain * 0.95) * 0.7 + (authorOk === true ? 0.15 : authorOk === false ? -0.15 : 0) + (yearOk === true ? (cy === work.year ? 0.15 : 0.1) : yearOk === false ? -0.15 : 0)) * 1000) / 1000;182 return { confident, close, score, title_similarity: sim, title_containment: contain, first_author_agrees: authorOk, year_agrees: yearOk };183}184