@whyparabola/cabar 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,289 @@
+import {
+  ADAPTIVE_DEFAULTS,
+  CHAR4_COUNTER,
+  CabarSelector,
+  DEFAULTS,
+  DEFAULT_RECENCY_DECAY_DAYS,
+  claimsRendering,
+  cosineSimilarity,
+  embeddingSimilarity,
+  estimateTokens,
+  extract,
+  jaccard,
+  mention,
+  normalizeScores,
+  recencyDecay,
+  splitSentences,
+  stripUndefined,
+  tokenize,
+  truncateToTokens,
+  verbatim
+} from "./chunk-UE4FTY7E.js";
+
+// src/prism.ts
+var FIDELITY_RANK = { mention: 0, claims: 1, extract: 2, verbatim: 3 };
+var DEFAULTS2 = {
+  budgetTokens: 4e3,
+  maxUnits: 12,
+  tailBudgetTokens: 600,
+  tauFloor: 0.15,
+  recencyLambda: 0.3,
+  recencyDecayDays: DEFAULT_RECENCY_DECAY_DAYS,
+  noveltyWeight: 1,
+  guaranteedTokens: 0,
+  hysteresisBonus: 0
+};
+var ADAPTIVE_DEFAULTS2 = {
+  minKeep: 3,
+  relFloor: 0.4,
+  novFloor: 0.2,
+  maxCeilingTokens: 4e3
+};
+var DEFAULT_FIDELITY_FACTORS = {
+  verbatim: 1,
+  extract: 0.85,
+  claims: 0.75,
+  mention: 0.3
+};
+var MS_PER_DAY = 864e5;
+var ALL_FIDELITIES = ["verbatim", "extract", "claims", "mention"];
+var PrismSelector = class {
+  /**
+   * MCKP-greedy multi-fidelity selection: build each unit's rendering menu,
+   * greedily apply the densest feasible ADD/UPGRADE move, run the KMN
+   * best-single swap, then floor the remainder into a mention tail.
+   */
+  static select(units, query, opts = {}) {
+    const cfg = { ...DEFAULTS2, ...stripUndefined(opts) };
+    const now = opts.now ?? /* @__PURE__ */ new Date();
+    const counter = opts.tokenCounter ?? CHAR4_COUNTER;
+    const phi = { ...DEFAULT_FIDELITY_FACTORS, ...opts.fidelityFactors };
+    const adaptive = opts.adaptive === true;
+    const minKeep = opts.minKeep ?? ADAPTIVE_DEFAULTS2.minKeep;
+    const relFloor = opts.relFloor ?? ADAPTIVE_DEFAULTS2.relFloor;
+    const novFloor = opts.novFloor ?? ADAPTIVE_DEFAULTS2.novFloor;
+    const maxCeilingTokens = opts.maxCeilingTokens ?? ADAPTIVE_DEFAULTS2.maxCeilingTokens;
+    const topScore = units.length > 0 ? Math.max(...units.map((u) => u.score)) : 1;
+    const effectiveBudget = adaptive ? maxCeilingTokens : cfg.budgetTokens;
+    const budget = Math.max(0, effectiveBudget - cfg.guaranteedTokens);
+    const unitById = /* @__PURE__ */ new Map();
+    const inputIndex = /* @__PURE__ */ new Map();
+    units.forEach((u, i) => {
+      unitById.set(u.id, u);
+      inputIndex.set(u.id, i);
+    });
+    const menuOf = /* @__PURE__ */ new Map();
+    let candidateTokens = 0;
+    for (const u of units) {
+      const vCost = counter.count(u.content);
+      candidateTokens += vCost;
+      const menu = [];
+      for (const f of ALL_FIDELITIES) {
+        const rendered = renderFidelity(u, f, query, counter);
+        if (rendered === null) continue;
+        const cost = counter.count(rendered);
+        if (f !== "verbatim" && cost >= vCost) continue;
+        menu.push({ fidelity: f, rendered, cost, tokens: tokenize(rendered), phi: phi[f], rank: FIDELITY_RANK[f] });
+      }
+      menuOf.set(u.id, menu);
+    }
+    const recencyOf = (u) => {
+      if (!u.timestamp || cfg.recencyLambda === 0) return 1;
+      const ageInDays = Math.max(0, (now.getTime() - u.timestamp.getTime()) / MS_PER_DAY);
+      const decay = recencyDecay(ageInDays, cfg.recencyDecayDays);
+      return cfg.recencyLambda * decay + (1 - cfg.recencyLambda);
+    };
+    const chosen = /* @__PURE__ */ new Map();
+    let selectedTokens = 0;
+    let totalUtility = 0;
+    let moves = 0;
+    const prevRank = /* @__PURE__ */ new Map();
+    for (const p of opts.prevSelected ?? []) {
+      const r = FIDELITY_RANK[p.fidelity];
+      const existing = prevRank.get(p.unitId);
+      if (existing === void 0 || r < existing) prevRank.set(p.unitId, r);
+    }
+    const noveltyOf = (u, tokens, excludeId) => {
+      let maxSim = 0;
+      for (const [id, r] of chosen) {
+        if (id === excludeId) continue;
+        const sim = opts.similarity ? opts.similarity(u, unitById.get(id)) : jaccard(tokens, r.tokens);
+        if (sim > maxSim) maxSim = sim;
+      }
+      return 1 - maxSim;
+    };
+    const utilityOf = (u, r, excludeId) => {
+      const noveltyRaw = noveltyOf(u, r.tokens, excludeId);
+      const effectiveNovelty = 1 - cfg.noveltyWeight * (1 - noveltyRaw);
+      let g = u.score * recencyOf(u) * effectiveNovelty * r.phi;
+      const pr = prevRank.get(u.id);
+      if (cfg.hysteresisBonus > 0 && pr !== void 0 && r.rank >= pr) {
+        g *= 1 + cfg.hysteresisBonus;
+      }
+      return g;
+    };
+    const better = (a, b) => b === null || a.density > b.density || a.density === b.density && a.deltaG > b.deltaG;
+    for (; ; ) {
+      let best = null;
+      for (const u of units) {
+        const menu = menuOf.get(u.id);
+        const current = chosen.get(u.id);
+        if (!current) {
+          if (!adaptive && chosen.size >= cfg.maxUnits) continue;
+          for (const r of menu) {
+            if (r.cost <= 0) continue;
+            if (selectedTokens + r.cost > budget) continue;
+            if (adaptive && chosen.size >= minKeep) {
+              const relFrac = u.score / (topScore || 1);
+              const nov = noveltyOf(u, r.tokens, null);
+              if (relFrac < relFloor || nov < novFloor) continue;
+            }
+            const deltaG = utilityOf(u, r, null);
+            if (deltaG <= 0) continue;
+            const move = { unitId: u.id, rendering: r, deltaG, deltaC: r.cost, density: deltaG / r.cost };
+            if (better(move, best)) best = move;
+          }
+        } else {
+          const baseG = utilityOf(u, current, u.id);
+          for (const r of menu) {
+            const deltaC = r.cost - current.cost;
+            if (deltaC <= 0) continue;
+            if (selectedTokens + deltaC > budget) continue;
+            const deltaG = utilityOf(u, r, u.id) - baseG;
+            if (deltaG <= 0) continue;
+            const move = { unitId: u.id, rendering: r, deltaG, deltaC, density: deltaG / deltaC };
+            if (better(move, best)) best = move;
+          }
+        }
+      }
+      if (!best) break;
+      selectedTokens += best.deltaC;
+      totalUtility += best.deltaG;
+      chosen.set(best.unitId, best.rendering);
+      moves++;
+    }
+    if (adaptive || cfg.maxUnits >= 1) {
+      let bestSingle = null;
+      for (const u of units) {
+        const vr = menuOf.get(u.id).find((r) => r.fidelity === "verbatim");
+        if (!vr || vr.cost > budget) continue;
+        const utility = u.score * recencyOf(u) * vr.phi;
+        if (!bestSingle || utility > bestSingle.utility) bestSingle = { unit: u, rendering: vr, utility };
+      }
+      if (bestSingle && bestSingle.utility > totalUtility) {
+        chosen.clear();
+        chosen.set(bestSingle.unit.id, bestSingle.rendering);
+        selectedTokens = bestSingle.rendering.cost;
+        totalUtility = bestSingle.utility;
+      }
+    }
+    const eligible = units.filter((u) => !chosen.has(u.id) && u.score >= cfg.tauFloor).sort((a, b) => b.score - a.score || inputIndex.get(a.id) - inputIndex.get(b.id));
+    const mentionLines = [];
+    let mentionUsed = 0;
+    for (const u of eligible) {
+      const line = mention(u, counter);
+      const lineTokens = counter.count(mentionLines.length === 0 ? line : `
+${line}`);
+      if (mentionUsed + lineTokens > cfg.tailBudgetTokens) break;
+      mentionLines.push(line);
+      mentionUsed += lineTokens;
+    }
+    const mentionBlock = mentionLines.join("\n");
+    const verbatimBlock = eligible.map((u) => u.content.trim()).join("\n");
+    let tailBlock = eligible.length === 0 ? "" : counter.count(verbatimBlock) < counter.count(mentionBlock) ? verbatimBlock : mentionBlock;
+    if (counter.count(tailBlock) > cfg.tailBudgetTokens) {
+      tailBlock = truncateToTokens(tailBlock, cfg.tailBudgetTokens, counter);
+    }
+    const tailTokens = counter.count(tailBlock);
+    const selected = [...chosen.entries()].map(([id, r]) => ({ unit: unitById.get(id), fidelity: r.fidelity, rendered: r.rendered, tokens: r.cost })).sort((a, b) => tsKey(a.unit) - tsKey(b.unit) || a.unit.id.localeCompare(b.unit.id));
+    const fidelityHistogram = { verbatim: 0, extract: 0, claims: 0, mention: 0 };
+    for (const s of selected) fidelityHistogram[s.fidelity]++;
+    return {
+      selected,
+      tail: eligible,
+      tailBlock,
+      stats: {
+        candidateTokens,
+        selectedTokens,
+        tailTokens,
+        budgetTokens: effectiveBudget,
+        utilizedTokens: cfg.guaranteedTokens + selectedTokens + tailTokens,
+        fidelityHistogram,
+        moves
+      }
+    };
+  }
+};
+function renderFidelity(u, f, query, counter) {
+  switch (f) {
+    case "verbatim":
+      return verbatim(u);
+    case "extract":
+      return extract(u, query, counter);
+    case "claims":
+      return claimsRendering(u);
+    case "mention":
+      return mention(u, counter);
+    default: {
+      const _exhaustive = f;
+      return _exhaustive;
+    }
+  }
+}
+function tsKey(u) {
+  return u.timestamp ? u.timestamp.getTime() : 0;
+}
+
+// src/context.ts
+function isPrism(r) {
+  return "tailBlock" in r;
+}
+function toContext(result, opts = {}) {
+  const separator = opts.separator ?? "\n\n";
+  const heading = opts.tailHeading ?? "Other possibly relevant notes:";
+  const format = opts.format ?? ((text) => text);
+  const parts = isPrism(result) ? result.selected.map((s) => format(s.rendered, s.unit.id)) : result.selected.map((u) => format(u.content, u.id));
+  const tail = isPrism(result) ? result.tailBlock : result.tailSummary;
+  if (tail) parts.push(heading ? `${heading}
+${tail}` : tail);
+  return parts.join(separator);
+}
+function shadowReport(units, query, opts = {}) {
+  const counter = opts.tokenCounter ?? CHAR4_COUNTER;
+  const result = CabarSelector.select(units, query, opts);
+  const sendAllTokens = units.reduce((n, u) => n + counter.count(u.content), 0);
+  const cabarTokens = result.stats.selectedTokens + result.stats.tailSummaryTokens;
+  const kept = new Set([...result.selected, ...result.tail].map((u) => u.id));
+  return {
+    sendAllTokens,
+    cabarTokens,
+    savedFraction: sendAllTokens === 0 ? 0 : 1 - cabarTokens / sendAllTokens,
+    selectedIds: result.selected.map((u) => u.id),
+    tailIds: result.tail.map((u) => u.id),
+    droppedIds: units.filter((u) => !kept.has(u.id)).map((u) => u.id),
+    result
+  };
+}
+export {
+  ADAPTIVE_DEFAULTS,
+  CHAR4_COUNTER,
+  CabarSelector,
+  DEFAULTS,
+  DEFAULT_RECENCY_DECAY_DAYS,
+  PrismSelector,
+  claimsRendering,
+  cosineSimilarity,
+  embeddingSimilarity,
+  estimateTokens,
+  extract,
+  jaccard,
+  mention,
+  normalizeScores,
+  recencyDecay,
+  shadowReport,
+  splitSentences,
+  toContext,
+  tokenize,
+  truncateToTokens,
+  verbatim
+};

package/dist/langchain.cjs

@@ -0,0 +1,358 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/langchain.ts
+var langchain_exports = {};
+__export(langchain_exports, {
+  CabarCompressor: () => CabarCompressor
+});
+module.exports = __toCommonJS(langchain_exports);
+var import_document_compressors = require("@langchain/core/retrievers/document_compressors");
+var import_documents = require("@langchain/core/documents");
+
+// src/shared.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+var CHAR4_COUNTER = { name: "char4", count: estimateTokens };
+var DEFAULT_RECENCY_DECAY_DAYS = 365;
+function recencyDecay(ageInDays, decayDays = DEFAULT_RECENCY_DECAY_DAYS) {
+  if (ageInDays < 0) throw new RangeError("ageInDays must be >= 0");
+  if (decayDays <= 0) throw new RangeError("decayDays must be > 0");
+  return Math.exp(-ageInDays / decayDays);
+}
+function stripUndefined(obj) {
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    if (obj[key] !== void 0) out[key] = obj[key];
+  }
+  return out;
+}
+
+// src/renderings.ts
+function truncateToTokens(text, maxTokens, counter) {
+  if (counter.count(text) <= maxTokens) return text;
+  const words = text.split(/\s+/).filter(Boolean);
+  let out = "";
+  for (const w of words) {
+    const candidate = out ? `${out} ${w}` : w;
+    if (counter.count(`${candidate}\u2026`) > maxTokens) break;
+    out = candidate;
+  }
+  if (!out) out = words[0] ?? "";
+  return `${out}\u2026`;
+}
+
+// src/cabar.ts
+var DEFAULTS = {
+  budgetTokens: 4e3,
+  maxUnits: 8,
+  tailBudgetTokens: 600,
+  tauFloor: 0.15,
+  recencyLambda: 0.3,
+  recencyDecayDays: DEFAULT_RECENCY_DECAY_DAYS,
+  noveltyWeight: 1,
+  guaranteedTokens: 0,
+  costExponent: 1
+};
+var ADAPTIVE_DEFAULTS = {
+  minKeep: 3,
+  relFloor: 0.4,
+  novFloor: 0.2,
+  maxCeilingTokens: 4e3
+};
+var MS_PER_DAY = 864e5;
+function tokenize(text) {
+  const matches = text.toLowerCase().match(/[a-z0-9]{3,}/g);
+  return new Set(matches ?? []);
+}
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const t of a) {
+    if (b.has(t)) intersection++;
+  }
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+var CabarSelector = class {
+  /**
+   * Select which units fit the budget, greedily maximizing utility/cost
+   * density, with a best-single-vs-greedy swap (budgeted-max-coverage 2-approx
+   * guarantee) and an extractive tail summary for the rest.
+   */
+  static select(units, query, opts = {}) {
+    const cfg = { ...DEFAULTS, ...stripUndefined(opts) };
+    const now = opts.now ?? /* @__PURE__ */ new Date();
+    const counter = opts.tokenCounter ?? CHAR4_COUNTER;
+    const count = (t) => counter.count(t);
+    const adaptive = opts.adaptive === true;
+    const minKeep = opts.minKeep ?? ADAPTIVE_DEFAULTS.minKeep;
+    const relFloor = opts.relFloor ?? ADAPTIVE_DEFAULTS.relFloor;
+    const novFloor = opts.novFloor ?? ADAPTIVE_DEFAULTS.novFloor;
+    const maxCeilingTokens = opts.maxCeilingTokens ?? ADAPTIVE_DEFAULTS.maxCeilingTokens;
+    const capToMaxUnits = opts.capToMaxUnits === true;
+    const topScore = units.length > 0 ? Math.max(...units.map((u) => u.score)) : 1;
+    const costOf = /* @__PURE__ */ new Map();
+    const tokensOf = /* @__PURE__ */ new Map();
+    let candidateTokens = 0;
+    for (const u of units) {
+      const cost = count(u.content);
+      costOf.set(u.id, cost);
+      tokensOf.set(u.id, tokenize(u.content));
+      candidateTokens += cost;
+    }
+    const effectiveBudget = adaptive ? maxCeilingTokens : cfg.budgetTokens;
+    const remainingBudget = Math.max(0, effectiveBudget - cfg.guaranteedTokens);
+    const recencyOf = (u) => {
+      if (!u.timestamp || cfg.recencyLambda === 0) return 1;
+      const ageInDays = Math.max(0, (now.getTime() - u.timestamp.getTime()) / MS_PER_DAY);
+      const decay = recencyDecay(ageInDays, cfg.recencyDecayDays);
+      return cfg.recencyLambda * decay + (1 - cfg.recencyLambda);
+    };
+    const noveltyOf = (u, selectedSoFar) => {
+      if (selectedSoFar.length === 0) return 1;
+      const a = tokensOf.get(u.id);
+      let maxSim = 0;
+      for (const s of selectedSoFar) {
+        const sim2 = opts.similarity ? opts.similarity(u, s) : jaccard(a, tokensOf.get(s.id));
+        if (sim2 > maxSim) maxSim = sim2;
+      }
+      return 1 - maxSim;
+    };
+    const utilityOf = (u, selectedSoFar) => {
+      const r = u.score;
+      const rho = recencyOf(u);
+      const noveltyRaw = noveltyOf(u, selectedSoFar);
+      const effectiveNovelty = 1 - cfg.noveltyWeight * (1 - noveltyRaw);
+      return r * rho * effectiveNovelty;
+    };
+    const selected = [];
+    const selectedIds = /* @__PURE__ */ new Set();
+    let selectedTokens = 0;
+    let greedyTotalUtility = 0;
+    while (adaptive && !capToMaxUnits || selected.length < cfg.maxUnits) {
+      let best = null;
+      for (const u of units) {
+        if (selectedIds.has(u.id)) continue;
+        const cost = costOf.get(u.id);
+        if (selectedTokens + cost > remainingBudget) continue;
+        const utility = utilityOf(u, selected);
+        if (utility <= 0) continue;
+        const density = cost > 0 ? utility / Math.pow(cost, cfg.costExponent) : Infinity;
+        if (!best || density > best.density) {
+          best = { unit: u, utility, density };
+        }
+      }
+      if (!best) break;
+      if (adaptive && selected.length >= minKeep) {
+        const relFrac = best.unit.score / (topScore || 1);
+        const nov = noveltyOf(best.unit, selected);
+        if (relFrac < relFloor || nov < novFloor) break;
+      }
+      selected.push(best.unit);
+      selectedIds.add(best.unit.id);
+      selectedTokens += costOf.get(best.unit.id);
+      greedyTotalUtility += best.utility;
+    }
+    let swapped = false;
+    if (adaptive || cfg.maxUnits >= 1) {
+      let bestSingle = null;
+      for (const u of units) {
+        const cost = costOf.get(u.id);
+        if (cost > remainingBudget) continue;
+        const utility = utilityOf(u, []);
+        if (!bestSingle || utility > bestSingle.utility) {
+          bestSingle = { unit: u, utility };
+        }
+      }
+      if (bestSingle && bestSingle.utility > greedyTotalUtility) {
+        swapped = true;
+        selected.length = 0;
+        selected.push(bestSingle.unit);
+        selectedIds.clear();
+        selectedIds.add(bestSingle.unit.id);
+        selectedTokens = costOf.get(bestSingle.unit.id);
+      }
+    }
+    const tail = units.filter((u) => !selectedIds.has(u.id) && u.score >= cfg.tauFloor);
+    const extractive = buildTailSummary(tail, query, cfg.tailBudgetTokens, count);
+    const verbatim = tail.map((u) => u.content.trim()).join("\n");
+    let tailSummary = tail.length === 0 ? "" : count(verbatim) < count(extractive) ? verbatim : extractive;
+    if (count(tailSummary) > cfg.tailBudgetTokens) {
+      tailSummary = counter === CHAR4_COUNTER ? truncateToTokens2(tailSummary, cfg.tailBudgetTokens) : truncateToTokens(tailSummary, cfg.tailBudgetTokens, counter);
+    }
+    const tailSummaryTokens = count(tailSummary);
+    const result = {
+      selected,
+      tail,
+      tailSummary,
+      stats: {
+        candidateCount: units.length,
+        candidateTokens,
+        selectedTokens,
+        tailSummaryTokens,
+        budgetTokens: effectiveBudget,
+        utilizedTokens: cfg.guaranteedTokens + selectedTokens + tailSummaryTokens
+      }
+    };
+    if (!opts.explain) return result;
+    const sim = (a, b) => opts.similarity ? opts.similarity(a, b) : jaccard(tokensOf.get(a.id), tokensOf.get(b.id));
+    const unitCap = !adaptive || capToMaxUnits;
+    result.decisions = units.map((u) => {
+      const tokens = costOf.get(u.id);
+      const others = selected.filter((s) => s.id !== u.id);
+      let maxSim = 0;
+      let closest;
+      for (const s of others) {
+        const v = sim(u, s);
+        if (v > maxSim) [maxSim, closest] = [v, s.id];
+      }
+      const base = { id: u.id, tokens, relevance: u.score, recency: recencyOf(u), novelty: 1 - maxSim };
+      if (selectedIds.has(u.id)) {
+        return { ...base, status: "selected", reason: swapped ? "best single unit: worth more alone than the greedy set" : "selected" };
+      }
+      if (u.score < cfg.tauFloor) {
+        return { ...base, status: "dropped", reason: `relevance ${u.score.toFixed(2)} is below tauFloor ${cfg.tauFloor}` };
+      }
+      let reason;
+      if (swapped) reason = "a single unit beat the greedy set";
+      else if (maxSim >= 1 - (adaptive ? novFloor : 0.2) && closest)
+        reason = `redundant with ${closest} (similarity ${maxSim.toFixed(2)})`;
+      else if (selectedTokens + tokens > remainingBudget) reason = `doesn't fit: needs ${tokens} tokens, ${Math.max(0, remainingBudget - selectedTokens)} left`;
+      else if (unitCap && selected.length >= cfg.maxUnits) reason = `maxUnits (${cfg.maxUnits}) reached`;
+      else if (adaptive && u.score / (topScore || 1) < relFloor) reason = `below the adaptive relevance cliff (${(u.score / (topScore || 1)).toFixed(2)} of the top score)`;
+      else reason = "adaptive stop: lower value per token than what was kept";
+      return { ...base, status: "tail", reason, ...reason.startsWith("redundant") ? { redundantWith: closest } : {} };
+    });
+    return result;
+  }
+};
+function truncateToTokens2(text, budgetTokens) {
+  const maxChars = budgetTokens * 4;
+  if (text.length <= maxChars) return text;
+  const cut = text.slice(0, maxChars);
+  const lastSpace = cut.lastIndexOf(" ");
+  return (lastSpace > maxChars * 0.8 ? cut.slice(0, lastSpace) : cut).trimEnd() + "\u2026";
+}
+function buildTailSummary(tail, query, tailBudgetTokens, count) {
+  if (tail.length === 0 || tailBudgetTokens <= 0) return "";
+  const queryTokens = tokenize(query);
+  const sentences = [];
+  let order = 0;
+  for (const unit of tail) {
+    const parts = unit.content.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean);
+    for (const text of parts) {
+      const tokens = tokenize(text);
+      let overlap = 0;
+      for (const t of tokens) {
+        if (queryTokens.has(t)) overlap++;
+      }
+      sentences.push({
+        text,
+        score: overlap + unit.score,
+        unitId: unit.id,
+        timestamp: unit.timestamp,
+        order: order++
+      });
+    }
+  }
+  sentences.sort((a, b) => b.score - a.score || a.order - b.order);
+  const seen = /* @__PURE__ */ new Set();
+  const lines = [];
+  let usedTokens = 0;
+  for (const s of sentences) {
+    const normalized = s.text.toLowerCase().replace(/\s+/g, " ").trim();
+    if (seen.has(normalized)) continue;
+    const idPart = s.timestamp ? `${s.unitId}@${s.timestamp.toISOString().slice(0, 10)}` : s.unitId;
+    const line = `[${idPart}] ${s.text}`;
+    const lineTokens = count(lines.length === 0 ? line : `
+${line}`);
+    if (usedTokens + lineTokens > tailBudgetTokens) break;
+    seen.add(normalized);
+    lines.push(line);
+    usedTokens += lineTokens;
+  }
+  return lines.join("\n");
+}
+
+// src/normalize.ts
+function normalizeScores(units, opts = {}) {
+  if (units.length === 0) return [];
+  const method = opts.method ?? "minmax";
+  const raw = units.map((u) => opts.higherIsBetter === false ? -u.score : u.score);
+  for (const s of raw) {
+    if (!Number.isFinite(s)) throw new RangeError("normalizeScores: every score must be a finite number");
+  }
+  const hi = Math.max(...raw);
+  const lo = Math.min(...raw);
+  let map;
+  if (method === "max") {
+    if (lo < 0) throw new RangeError("normalizeScores: method 'max' needs non-negative scores, use 'minmax'");
+    map = (s) => hi === 0 ? 1 : s / hi;
+  } else {
+    map = (s) => hi === lo ? 1 : (s - lo) / (hi - lo);
+  }
+  return units.map((u, i) => ({ ...u, score: map(raw[i]) }));
+}
+
+// src/langchain.ts
+var DEFAULT_SCORE_KEYS = ["relevance_score", "relevanceScore", "score"];
+function toDate(v) {
+  if (v instanceof Date) return v;
+  if (typeof v === "string" || typeof v === "number") {
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? void 0 : d;
+  }
+  return void 0;
+}
+var CabarCompressor = class extends import_document_compressors.BaseDocumentCompressor {
+  opts;
+  constructor(opts = {}) {
+    super();
+    this.opts = opts;
+  }
+  async compressDocuments(documents, query) {
+    if (documents.length === 0) return [];
+    const { scoreKeys = DEFAULT_SCORE_KEYS, timestampKey = "timestamp", includeTail = true, ...selectOpts } = this.opts;
+    const scored = documents.map((doc) => {
+      const key = scoreKeys.find((k) => typeof doc.metadata?.[k] === "number" && Number.isFinite(doc.metadata[k]));
+      return key ? doc.metadata[key] : null;
+    });
+    const useRank = scored.some((s) => s === null);
+    const units = normalizeScores(
+      documents.map((doc, i) => ({
+        id: String(i),
+        content: doc.pageContent,
+        score: useRank ? documents.length - i : scored[i],
+        timestamp: toDate(doc.metadata?.[timestampKey])
+      }))
+    );
+    const result = CabarSelector.select(units, query, selectOpts);
+    const out = result.selected.map((u) => documents[Number(u.id)]);
+    if (includeTail && result.tailSummary) {
+      out.push(new import_documents.Document({ pageContent: result.tailSummary, metadata: { cabar: "tail", units: result.tail.map((u) => Number(u.id)) } }));
+    }
+    return out;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CabarCompressor
+});

package/dist/langchain.d.cts

@@ -0,0 +1,35 @@
+import { BaseDocumentCompressor } from '@langchain/core/retrievers/document_compressors';
+import { DocumentInterface } from '@langchain/core/documents';
+import { b as CabarSelectOptions } from './cabar-B-R-rHby.cjs';
+
+/**
+ * LangChain.js adapter: CABAR as a document compressor.
+ *
+ *   import { ContextualCompressionRetriever } from '@langchain/classic/retrievers/contextual_compression';
+ *   import { CabarCompressor } from '@whyparabola/cabar/langchain';
+ *
+ *   const retriever = new ContextualCompressionRetriever({
+ *     baseCompressor: new CabarCompressor({ budgetTokens: 2000 }),
+ *     baseRetriever: vectorStore.asRetriever(24),
+ *   });
+ */
+
+interface CabarCompressorOptions extends CabarSelectOptions {
+    /**
+     * Metadata keys holding a relevance score, tried in order. Default:
+     * `relevance_score` (rerankers), `relevanceScore`, `score`. Documents without
+     * any of them are scored by their position in the retriever's order.
+     */
+    scoreKeys?: string[];
+    /** Metadata key holding a date (Date, ISO string or epoch ms) for recency. Default: `timestamp`. */
+    timestampKey?: string;
+    /** Append the tail summary as one extra Document (metadata `{ cabar: 'tail' }`). Default true. */
+    includeTail?: boolean;
+}
+declare class CabarCompressor extends BaseDocumentCompressor {
+    private readonly opts;
+    constructor(opts?: CabarCompressorOptions);
+    compressDocuments(documents: DocumentInterface[], query: string): Promise<DocumentInterface[]>;
+}
+
+export { CabarCompressor, type CabarCompressorOptions };