@odla-ai/kg 0.3.2 → 0.4.0

package/dist/index.js

@@ -1,6 +1,12 @@
 import {
-  parseDateMs
-} from "./chunk-V3N2GRYU.js";
+  blendPairs,
+  bridgingScores,
+  labelPropagation,
+  parseDateMs,
+  projectBridges,
+  reifiedBridgeTargets,
+  topBridges
+} from "./chunk-T6SYIVST.js";
 
 // src/types.ts
 function emptyUsage() {
@@ -292,6 +298,235 @@ async function canonicalizeFragment(db, fragment, ontology) {
   };
 }
 
+// src/graph/connectors.ts
+function findConnectors(fragment, config) {
+  const nameOf = /* @__PURE__ */ new Map();
+  for (const n of fragment.nodes) {
+    const label = n.attrs.name ?? n.attrs.title;
+    if (typeof label === "string" && label) nameOf.set(`${n.type}:${n.key}`, label);
+  }
+  const sets = config.lenses.map((l) => ({
+    pairs: projectBridges(reifiedBridgeTargets(fragment, { reified: l.reified, bridgeLabel: l.bridge, targetLabel: l.of }), {
+      maxPerBridge: config.maxPerBridge ?? 12
+    }),
+    weight: l.weight ?? 1
+  }));
+  const pairs = blendPairs([...sets, ...config.extraPairs ?? []]);
+  if (pairs.length === 0) return { connectors: [], communities: 0, nodes: 0 };
+  const nodes = [...new Set(pairs.flatMap((p) => [p.a, p.b]))].sort();
+  const edges = pairs.map((p) => ({ a: p.a, b: p.b, weight: p.w }));
+  const labels = labelPropagation(nodes, edges, { seed: 1 });
+  const groupName = /* @__PURE__ */ new Map();
+  for (const id of nodes) {
+    const g = labels.get(id);
+    if (!groupName.has(g)) groupName.set(g, nameOf.get(id) ?? id);
+  }
+  const bridging = bridgingScores(edges, labels);
+  const viaOf = (id) => {
+    const names = /* @__PURE__ */ new Set();
+    for (const p of pairs) {
+      if (p.a !== id && p.b !== id) continue;
+      for (const v of p.via) names.add(nameOf.get(v) ?? v.split(":").pop());
+    }
+    return [...names].slice(0, 6);
+  };
+  const connectors = topBridges(bridging, config.top ?? 12).map((b) => ({
+    ref: b.id,
+    name: nameOf.get(b.id) ?? b.id,
+    score: b.score,
+    groups: b.groups.map((g) => groupName.get(g)),
+    // every label has an anchor name
+    via: viaOf(b.id)
+  }));
+  return { connectors, communities: new Set(labels.values()).size, nodes: nodes.length };
+}
+
+// src/util/identity.ts
+function slugify(input) {
+  return input.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+}
+function normalizeUrl(raw) {
+  try {
+    const u = new URL(raw);
+    u.hash = "";
+    const drop = [/^utm_/i, /^ref$/i, /^ref_/i, /^fbclid$/i, /^gclid$/i, /^mc_/i];
+    for (const key of [...u.searchParams.keys()]) {
+      if (drop.some((re) => re.test(key))) u.searchParams.delete(key);
+    }
+    let s = u.toString();
+    s = s.replace(/\/$/, "");
+    return s;
+  } catch {
+    return raw.trim().replace(/#.*$/, "").replace(/\/$/, "");
+  }
+}
+function urlHash(raw) {
+  const s = normalizeUrl(raw);
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(36);
+}
+function isLikelyPersonName(name) {
+  const n = name.trim();
+  if (!n || /\d/.test(n)) return false;
+  const parts = n.split(/\s+/);
+  if (parts.length < 2 || parts.length > 4) return false;
+  return parts.every((p) => /^[A-Z][a-zA-Z'’.-]*$/.test(p));
+}
+
+// src/enrich/facts.ts
+var LOCATE_SYSTEM = "You resolve US business locations to counties. For each company you are given a city and/or a free-text region. Name the US county containing that city (for independent cities, use the city's own county-equivalent name) plus its 2-letter state. Use nulls when the location is ambiguous, outside the US, or unknown.";
+var LOCATE_TOOL = {
+  name: "resolve_counties",
+  description: "County name + state per company",
+  parameters: {
+    type: "object",
+    properties: {
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            slug: { type: "string" },
+            county: { type: ["string", "null"], description: 'county name WITHOUT the word "County", e.g. "Santa Clara"' },
+            state: { type: ["string", "null"], description: "2-letter USPS state" }
+          },
+          required: ["slug", "county", "state"]
+        }
+      }
+    },
+    required: ["items"]
+  }
+};
+function locatePrompt(batch) {
+  return "Companies:\n" + batch.map((c) => `- slug ${c.slug}: city=${c.city ?? "?"} region=${c.region ?? "?"}`).join("\n");
+}
+var FACTS_SEARCH_SYSTEM = "You are a research assistant with web search. Find concrete facts about the company: founding year/date, headquarters city and state, founders and key executives (names, roles), and funding (rounds, dates, amounts, investor names). Prefer official/reputable sources. Report dense factual notes; say 'not found' for anything you cannot establish. Do not speculate.";
+var FACTS_EXTRACT_SYSTEM = "Extract structured facts from the research notes. Use null for anything the notes do not establish.";
+var FACTS_EXTRACT_TOOL = {
+  name: "company_facts",
+  description: "Structured company facts from research notes",
+  parameters: {
+    type: "object",
+    properties: {
+      founded: { type: ["string", "null"], description: "YYYY or YYYY-MM or YYYY-MM-DD" },
+      city: { type: ["string", "null"] },
+      state: { type: ["string", "null"], description: "2-letter USPS" },
+      people: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { name: { type: "string" }, role: { type: "string" } },
+          required: ["name", "role"]
+        }
+      },
+      rounds: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            round: { type: ["string", "null"] },
+            date: { type: ["string", "null"] },
+            amount: { type: ["string", "null"] },
+            investors: { type: "array", items: { type: "string" } }
+          },
+          required: ["investors"]
+        }
+      }
+    },
+    required: ["people", "rounds"]
+  }
+};
+var DATE_RE = /^\d{4}(-\d{2}){0,2}$/;
+var isoDate = (v) => !DATE_RE.test(v) ? null : v.length === 4 ? `${v}-01-01` : v.length === 7 ? `${v}-01` : v;
+var countyKey = (name, st) => `${String(name).toLowerCase().replace(/\bcounty\b|\bparish\b|\bborough\b/g, "").replace(/[^a-z]/g, "")}|${String(st).toUpperCase()}`;
+function factsToFragment(company, draft) {
+  const nodes = [];
+  const edges = [];
+  const attrs = {};
+  const founded = draft.founded ? isoDate(draft.founded) : null;
+  if (founded) attrs.founded = founded;
+  if (draft.city && !company.city) attrs.city = String(draft.city).slice(0, 60);
+  if (Object.keys(attrs).length > 0) {
+    nodes.push({ type: "company", key: company.slug, attrs: { name: company.name, ...attrs } });
+  }
+  const anchorDate = attrs.founded ?? company.founded ?? company.first_seen ?? "";
+  for (const p of (draft.people ?? []).slice(0, 5)) {
+    const personSlug = slugify(p.name);
+    if (!personSlug || personSlug === company.slug) continue;
+    nodes.push({ type: "person", key: personSlug, attrs: { name: p.name } });
+    const key = `${personSlug}~${company.slug}`;
+    nodes.push({ type: "affiliation", key, attrs: { date: anchorDate, role: String(p.role).slice(0, 60) } });
+    edges.push({ from: { type: "affiliation", key }, to: { type: "person", key: personSlug }, label: "of_person" });
+    edges.push({ from: { type: "affiliation", key }, to: { type: "company", key: company.slug }, label: "of_company" });
+  }
+  (draft.rounds ?? []).slice(0, 4).forEach((r, i) => {
+    const investors = (r.investors ?? []).map(slugify).filter(Boolean).slice(0, 6);
+    const date = r.date ? isoDate(r.date) : null;
+    if (investors.length === 0 && !date) return;
+    const key = `${company.slug}~e${i}`;
+    const rAttrs = { date: date ?? anchorDate };
+    if (r.round) rAttrs.round = String(r.round).slice(0, 40);
+    if (r.amount) rAttrs.amount = String(r.amount).slice(0, 40);
+    nodes.push({ type: "funding_round", key, attrs: rAttrs });
+    edges.push({ from: { type: "funding_round", key }, to: { type: "company", key: company.slug }, label: "round_of" });
+    for (const [j, invSlug] of investors.entries()) {
+      nodes.push({ type: "investor", key: invSlug, attrs: { name: (r.investors ?? [])[j] } });
+      edges.push({ from: { type: "funding_round", key }, to: { type: "investor", key: invSlug }, label: "raised_from" });
+    }
+  });
+  return { nodes, edges };
+}
+function locationFragment(slug, name, fips) {
+  return {
+    nodes: [{ type: "company", key: slug, attrs: { name, fips } }],
+    edges: [{ from: { type: "company", key: slug }, to: { type: "county", key: fips }, label: "located_in" }]
+  };
+}
+
+// src/enrich/run.ts
+async function enrichCompany(ai, models, company) {
+  const where = `${company.city ? `, ${company.city}` : ""}${company.region ? ` (${company.region})` : ""}`;
+  const { text } = await ai.search({
+    model: models.search,
+    system: FACTS_SEARCH_SYSTEM,
+    user: `Company: ${company.name}${where}. Research its founding, headquarters, key people, and funding.`,
+    maxTokens: 900
+  });
+  const extractOnce = () => ai.extract({
+    model: models.extract,
+    system: FACTS_EXTRACT_SYSTEM,
+    user: `Company: ${company.name}
+
+Notes:
+${text}`,
+    tool: FACTS_EXTRACT_TOOL,
+    maxTokens: 4e3
+    // reasoning headroom before the forced tool call
+  });
+  const { value } = await extractOnce().catch(extractOnce);
+  return factsToFragment(company, value);
+}
+async function resolveCounties(ai, model, rows, gazetteer) {
+  const { value } = await ai.extract({
+    model,
+    system: LOCATE_SYSTEM,
+    user: locatePrompt(rows),
+    tool: LOCATE_TOOL,
+    maxTokens: 6e3
+    // reasoning models spend tokens before the tool call
+  });
+  const out = [];
+  for (const item of value.items ?? []) {
+    const fips = item.county && item.state ? gazetteer.get(countyKey(item.county, item.state)) : void 0;
+    if (fips) out.push({ slug: item.slug, fips });
+  }
+  return out;
+}
+
 // src/llm/provider.ts
 import { init, extractText } from "@odla-ai/ai";
 var MODEL_TIERS = {
@@ -533,42 +768,6 @@ var gdeltConnector = {
   }
 };
 
-// src/util/identity.ts
-function slugify(input) {
-  return input.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
-}
-function normalizeUrl(raw) {
-  try {
-    const u = new URL(raw);
-    u.hash = "";
-    const drop = [/^utm_/i, /^ref$/i, /^ref_/i, /^fbclid$/i, /^gclid$/i, /^mc_/i];
-    for (const key of [...u.searchParams.keys()]) {
-      if (drop.some((re) => re.test(key))) u.searchParams.delete(key);
-    }
-    let s = u.toString();
-    s = s.replace(/\/$/, "");
-    return s;
-  } catch {
-    return raw.trim().replace(/#.*$/, "").replace(/\/$/, "");
-  }
-}
-function urlHash(raw) {
-  const s = normalizeUrl(raw);
-  let h = 2166136261;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 16777619);
-  }
-  return (h >>> 0).toString(36);
-}
-function isLikelyPersonName(name) {
-  const n = name.trim();
-  if (!n || /\d/.test(n)) return false;
-  const parts = n.split(/\s+/);
-  if (parts.length < 2 || parts.length > 4) return false;
-  return parts.every((p) => /^[A-Z][a-zA-Z'’.-]*$/.test(p));
-}
-
 // src/connectors/fred.ts
 async function fetchSeries(seriesId, apiKey, start) {
   const url = `https://api.stlouisfed.org/fred/series/observations?series_id=${encodeURIComponent(seriesId)}&api_key=${encodeURIComponent(apiKey)}&file_type=json&observation_start=${encodeURIComponent(start)}`;
@@ -1008,8 +1207,13 @@ async function ingestFresh(step, deps, fresh, kind, resolve = false) {
 }
 export {
   COMMIT_STEP_CONFIG,
+  FACTS_EXTRACT_SYSTEM,
+  FACTS_EXTRACT_TOOL,
+  FACTS_SEARCH_SYSTEM,
   IO_STEP_CONFIG,
   LLM_STEP_CONFIG,
+  LOCATE_SYSTEM,
+  LOCATE_TOOL,
   MODEL_TIERS,
   Store,
   addUsage,
@@ -1017,14 +1221,18 @@ export {
   asStepLike,
   canonicalizeFragment,
   connectorIds,
+  countyKey,
   createProvider,
   emptyUsage,
   enabledSources,
+  enrichCompany,
   exportFragment,
   extractJson,
   extractJsonArray,
+  factsToFragment,
   fetchText,
   fetchUrl,
+  findConnectors,
   fragmentToOps,
   getConnector,
   getProvider,
@@ -1033,6 +1241,8 @@ export {
   ingestFresh,
   isLikelyPersonName,
   jobsForHour,
+  locatePrompt,
+  locationFragment,
   makeContext,
   mergeAttrs,
   mergeRulesOf,
@@ -1040,6 +1250,7 @@ export {
   naturalKeysOf,
   normalizeUrl,
   resilientStep,
+  resolveCounties,
   resolveName,
   searchEntities,
   slugify,