@odla-ai/kg 0.4.1 → 0.6.0

package/dist/index.js

@@ -345,6 +345,15 @@ function findConnectors(fragment, config) {
 function slugify(input) {
   return input.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
 }
+var LEGAL_SUFFIXES = /* @__PURE__ */ new Set(["co", "company", "corp", "corporation", "inc", "incorporated", "llc", "llp", "ltd", "limited", "pllc"]);
+function identityKey(value) {
+  const tokens = value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/&/g, " and ").match(/[a-z0-9]+/g) ?? [];
+  while (tokens.length > 1 && LEGAL_SUFFIXES.has(tokens.at(-1) ?? "")) {
+    tokens.pop();
+    if (tokens.at(-1) === "and") tokens.pop();
+  }
+  return tokens.join("");
+}
 function normalizeUrl(raw) {
   try {
     const u = new URL(raw);
@@ -487,6 +496,213 @@ function locationFragment(slug, name, fips) {
   };
 }
 
+// src/enrich/verify.ts
+var WRITABLE_VERDICTS = ["confirmed", "probable"];
+var ALL = ["confirmed", "probable", "ambiguous", "not_found", "wrong_entity"];
+function isVerdict(value) {
+  return typeof value === "string" && ALL.includes(value);
+}
+function isWritable(verdict) {
+  return WRITABLE_VERDICTS.includes(verdict);
+}
+function normalizeVerification(draft, retrievedAt) {
+  const d = draft ?? {};
+  const verdict = isVerdict(d.verdict) ? d.verdict : "ambiguous";
+  const raw = typeof d.confidence === "number" && Number.isFinite(d.confidence) ? d.confidence : 0;
+  const confidence = Math.min(1, Math.max(0, raw));
+  const evidence = [];
+  for (const item of Array.isArray(d.evidence) ? d.evidence.slice(0, 12) : []) {
+    const e = item ?? {};
+    const sourceUrl = typeof e.sourceUrl === "string" ? e.sourceUrl.trim() : "";
+    const claim = typeof e.claim === "string" ? e.claim.trim() : "";
+    if (!claim || !isHttpUrl(sourceUrl)) continue;
+    evidence.push({ claim: claim.slice(0, 300), sourceUrl, ...retrievedAt ? { retrievedAt } : {} });
+  }
+  if (evidence.length === 0 && isWritable(verdict)) return { verdict: "ambiguous", confidence, evidence };
+  return { verdict, confidence, evidence };
+}
+function isHttpUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === "https:" || u.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+// src/enrich/person.ts
+var LINK_KINDS = ["website", "blog", "substack", "linkedin", "x", "bluesky", "github", "other"];
+var CANONICAL_HOSTS = {
+  linkedin: ["linkedin.com"],
+  github: ["github.com"],
+  x: ["x.com", "twitter.com"],
+  bluesky: ["bsky.app"]
+};
+var PLACEHOLDER_HOSTS = ["example.com", "example.org", "example.net", "yourdomain.com", "domain.com"];
+var PERSON_SEARCH_SYSTEM = "You are a research assistant with web search, confirming the identity of a specific named person and finding their PUBLIC PROFESSIONAL presence. Look for: a personal website, blog, or Substack; LinkedIn, X/Bluesky, or GitHub profiles; their current employer and role; and a business email or phone that they or their employer have published openly (a company contact page, a conference bio). Do NOT look for or report home addresses, personal phone numbers, or personal email addresses. Also report disambiguating facts: city or region, alma mater, and other companies named alongside them. Names are not unique. If the results describe more than one person with this name and you cannot tell which is meant, say so explicitly. If you find a different person with the same name, say that too. Cite the URL for every claim. Never guess a profile URL from a name pattern \u2014 report only URLs you actually saw. If you found nothing, say so plainly.";
+var PERSON_EXTRACT_SYSTEM = "Extract the structured profile from the research notes. Use null for anything the notes do not establish. Set verdict to 'confirmed' only when the notes identify this exact person beyond doubt; 'probable' when the evidence is strong but circumstantial; 'ambiguous' when several same-named people cannot be told apart; 'not_found' when nothing was established; 'wrong_entity' when the notes describe a different person with the same name. Every claim in evidence must carry the source URL it came from.";
+var PERSON_EXTRACT_TOOL = {
+  name: "person_profile",
+  description: "Verified identity plus public professional profile for one person",
+  parameters: {
+    type: "object",
+    properties: {
+      verdict: { type: "string", enum: ["confirmed", "probable", "ambiguous", "not_found", "wrong_entity"] },
+      confidence: { type: "number", description: "0..1 \u2014 how sure you are this is the right person" },
+      links: {
+        type: "array",
+        description: "Only URLs actually seen in the results; never a guessed profile pattern.",
+        items: {
+          type: "object",
+          properties: {
+            kind: { type: "string", enum: [...LINK_KINDS] },
+            url: { type: "string" }
+          },
+          required: ["kind", "url"]
+        }
+      },
+      employer: { type: ["string", "null"], description: "Current employer name" },
+      role: { type: ["string", "null"], description: "Current title at that employer" },
+      businessEmail: { type: ["string", "null"], description: "Publicly published work email only" },
+      businessPhone: { type: ["string", "null"], description: "Publicly published work phone only" },
+      city: { type: ["string", "null"] },
+      region: { type: ["string", "null"], description: "State, province, or country" },
+      almaMater: { type: ["string", "null"] },
+      otherCompanies: { type: "array", items: { type: "string" }, description: "Companies named alongside them" },
+      evidence: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { claim: { type: "string" }, sourceUrl: { type: "string" } },
+          required: ["claim", "sourceUrl"]
+        }
+      }
+    },
+    required: ["verdict", "confidence", "links", "evidence"]
+  }
+};
+function personPrompt(person) {
+  const at = person.companyName ? ` (${person.role ? `${person.role}, ` : ""}${person.companyName})` : "";
+  const where = [person.city, person.region].filter(Boolean).join(", ");
+  return `Person: ${person.name}${at}${where ? `
+Known location: ${where}` : ""}
+
+Confirm this is a real, identifiable person and find their public professional presence.`;
+}
+function validateLinks(raw, limit = 8) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of (raw ?? []).slice(0, 24)) {
+    const kind = LINK_KINDS.includes(String(item?.kind)) ? item.kind : "other";
+    const url = String(item?.url ?? "").trim();
+    const parsed = httpsUrl(url);
+    if (!parsed) continue;
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, "");
+    if (PLACEHOLDER_HOSTS.includes(host)) continue;
+    const required = CANONICAL_HOSTS[kind];
+    if (required && !required.some((h) => host === h || host.endsWith(`.${h}`))) continue;
+    if (seen.has(url)) continue;
+    seen.add(url);
+    out.push({ kind, url });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+function personToFragment(person, draft, retrievedAt) {
+  const verification = normalizeVerification(draft, retrievedAt);
+  const links = validateLinks(draft.links);
+  if (!isWritable(verification.verdict)) return { verification, links, fragment: { nodes: [], edges: [] } };
+  const attrs = { name: person.name };
+  for (const link of links) if (!attrs[link.kind]) attrs[link.kind] = link.url;
+  const city = str(draft.city, 60);
+  if (city && !person.city) attrs.city = city;
+  const region = str(draft.region, 60);
+  if (region && !person.region) attrs.region = region;
+  const email = str(draft.businessEmail, 120);
+  if (email && /^[^@\s]+@[^@\s.]+\.[^@\s]+$/.test(email)) attrs.businessEmail = email;
+  const phone = str(draft.businessPhone, 40);
+  if (phone) attrs.businessPhone = phone;
+  const almaMater = str(draft.almaMater, 120);
+  if (almaMater) attrs.almaMater = almaMater;
+  const nodes = [{ type: "person", key: person.slug, attrs }];
+  const edges = [];
+  const employer = str(draft.employer, 120);
+  const known = person.companySlug && person.companyName && identityKey(person.companyName) === identityKey(employer);
+  const companySlug = employer ? known ? person.companySlug : slugify(employer) : "";
+  if (employer && companySlug) {
+    const key = `${person.slug}~${companySlug}`;
+    nodes.push({ type: "company", key: companySlug, attrs: { name: known ? person.companyName : employer } });
+    nodes.push({ type: "affiliation", key, attrs: { role: str(draft.role, 60) || person.role || "" } });
+    edges.push({ from: { type: "affiliation", key }, to: { type: "person", key: person.slug }, label: "of_person" });
+    edges.push({ from: { type: "affiliation", key }, to: { type: "company", key: companySlug }, label: "of_company" });
+  }
+  return { verification, links, fragment: { nodes, edges } };
+}
+function str(value, max) {
+  return typeof value === "string" ? value.trim().slice(0, max) : "";
+}
+function httpsUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/enrich/grade.ts
+var DEFAULT_STANDARD = {
+  minimumSources: 2,
+  minimumFacts: 3,
+  anchors: ["first-party", "authoritative"],
+  anchorRequiredForMedium: false
+};
+function independentHosts(sources) {
+  const hosts = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    try {
+      hosts.add(new URL(source.sourceUrl).hostname.toLowerCase().replace(/^www\./, ""));
+    } catch {
+    }
+  }
+  return [...hosts];
+}
+function gradeSources(sources, standard = DEFAULT_STANDARD) {
+  const supporting = sources.filter((s) => s.corroboration === "confirmed" || s.corroboration === "name-only");
+  const contradicting = sources.filter((s) => s.corroboration === "absent");
+  const unreadable = sources.filter((s) => s.corroboration === "unreachable" || s.corroboration === "unchecked");
+  const facts = [...new Set(supporting.flatMap((s) => s.facts))];
+  const hosts = independentHosts(supporting);
+  const hasAnchor = supporting.some((s) => standard.anchors.includes(s.sourceClass));
+  const base = {
+    independentSources: hosts.length,
+    factsCorroborated: facts,
+    hasAnchor,
+    contradictions: contradicting.map((s) => s.sourceUrl)
+  };
+  if (supporting.length === 0) {
+    return unreadable.length > 0 && contradicting.length === 0 ? { ...base, grade: "unverifiable", reason: `no source could be read (${unreadable.length} unreachable)` } : { ...base, grade: "unresolved", reason: "no source corroborated the subject" };
+  }
+  if (base.contradictions.length > 0) {
+    return { ...base, grade: "unresolved", reason: `${base.contradictions.length} source(s) named someone else` };
+  }
+  if (hosts.length >= standard.minimumSources && hasAnchor && facts.length >= standard.minimumFacts) {
+    return { ...base, grade: "high", reason: `${hosts.length} independent sources, anchored, agreeing on ${facts.length} facts` };
+  }
+  if (hosts.length >= standard.minimumSources && (hasAnchor || !standard.anchorRequiredForMedium)) {
+    return {
+      ...base,
+      grade: "medium",
+      reason: hasAnchor ? `${hosts.length} sources but only ${facts.length} corroborated facts` : `${hosts.length} sources, none first-party or authoritative`
+    };
+  }
+  return { ...base, grade: "unresolved", reason: hosts.length < standard.minimumSources ? "only one independent source" : "no anchoring source" };
+}
+var ACTIONABLE = ["high", "medium"];
+function isActionable(value) {
+  return ACTIONABLE.includes(value);
+}
+
 // src/enrich/run.ts
 async function enrichCompany(ai, models, company) {
   const where = `${company.city ? `, ${company.city}` : ""}${company.region ? ` (${company.region})` : ""}`;
@@ -510,6 +726,27 @@ ${text}`,
   const { value } = await extractOnce().catch(extractOnce);
   return factsToFragment(company, value);
 }
+async function enrichPerson(ai, models, person, retrievedAt) {
+  const { text, citations } = await ai.search({
+    model: models.search,
+    system: PERSON_SEARCH_SYSTEM,
+    user: personPrompt(person),
+    maxTokens: 1200
+  });
+  const extractOnce = () => ai.extract({
+    model: models.extract,
+    system: PERSON_EXTRACT_SYSTEM,
+    user: `Person: ${person.name}
+
+Notes:
+${text}`,
+    tool: PERSON_EXTRACT_TOOL,
+    maxTokens: 4e3
+    // reasoning headroom before the forced tool call
+  });
+  const { value } = await extractOnce().catch(extractOnce);
+  return { ...personToFragment(person, value, retrievedAt), citations, notes: text };
+}
 async function resolveCounties(ai, model, rows, gazetteer) {
   const { value } = await ai.extract({
     model,
@@ -527,6 +764,409 @@ async function resolveCounties(ai, model, rows, gazetteer) {
   return out;
 }
 
+// src/enrich/match.ts
+function fold(value) {
+  return value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+function mentionsName(haystack, name) {
+  const tokens = fold(name).split(" ").filter((t) => t.length > 2);
+  if (tokens.length < 2) return false;
+  const words = haystack.split(" ");
+  const positions = /* @__PURE__ */ new Map();
+  for (const [i, word] of words.entries()) {
+    if (tokens.includes(word)) positions.set(word, [...positions.get(word) ?? [], i]);
+  }
+  if (tokens.some((t) => !positions.has(t))) return false;
+  const span = tokens.length;
+  const anchors = positions.get(tokens[0]) ?? [];
+  return anchors.some(
+    (anchor) => tokens.every((token) => (positions.get(token) ?? []).some((at) => Math.abs(at - anchor) <= span))
+  );
+}
+function snippetAround(text, name, width = 240) {
+  const hay = fold(text);
+  const first = fold(name).split(" ")[0] ?? "";
+  const at = hay.indexOf(first);
+  if (at < 0) return "";
+  const start = Math.max(0, at - width / 2);
+  return text.slice(start, start + width).replace(/\s+/g, " ").trim();
+}
+function stripMarkup(html) {
+  return html.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/\s+/g, " ").slice(0, 2e5);
+}
+
+// src/enrich/strategy.ts
+async function investigatePerson(context, strategies, standard = DEFAULT_STANDARD) {
+  const skipped = [];
+  const runnable = [];
+  for (const strategy of strategies) {
+    if (strategy.applicable(context)) runnable.push(strategy);
+    else skipped.push(strategy.name);
+  }
+  const findings = await Promise.all(
+    runnable.map(async (strategy) => {
+      try {
+        return await strategy.run(context);
+      } catch (err) {
+        return {
+          strategy: strategy.name,
+          sources: [],
+          links: [],
+          notes: "",
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    })
+  );
+  const sources = dedupeBy(findings.flatMap((f) => f.sources), (s) => s.sourceUrl);
+  const links = dedupeBy(findings.flatMap((f) => f.links), (l) => l.url);
+  const report = gradeSources(sources, standard);
+  return { person: context.person, grade: report.grade, report, sources, links, findings, skipped };
+}
+function dedupeBy(items, key) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const at = key(item);
+    if (!seen.has(at)) seen.set(at, item);
+  }
+  return [...seen.values()];
+}
+
+// src/enrich/strategies/org-site.ts
+var TEAM_PATHS = [
+  "/team",
+  "/about",
+  "/about-us",
+  "/our-team",
+  "/leadership",
+  "/people",
+  "/staff",
+  "/who-we-are",
+  "/company/team",
+  "/press",
+  "/news"
+];
+var PEOPLE_WORDS = [
+  "team",
+  "about",
+  "leadership",
+  "staff",
+  "people",
+  "who we are",
+  "our story",
+  "founders",
+  "management",
+  "board",
+  "press",
+  "news",
+  "advisors",
+  "bios"
+];
+function rootOf(website) {
+  try {
+    return new URL(website.startsWith("http") ? website : `https://${website}`).origin;
+  } catch {
+    return null;
+  }
+}
+function candidatePages(website, limit = 4) {
+  const origin = rootOf(website);
+  if (!origin) return [];
+  return TEAM_PATHS.map((p) => `${origin}${p}`).slice(0, limit);
+}
+function peopleLinks(html, origin, limit = 5) {
+  const found = /* @__PURE__ */ new Map();
+  const anchor = /<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]{0,200}?)<\/a>/gi;
+  for (const match of html.matchAll(anchor)) {
+    let url;
+    try {
+      url = new URL(match[1] ?? "", origin);
+    } catch {
+      continue;
+    }
+    if (url.origin !== origin) continue;
+    const text = (match[2] ?? "").replace(/<[^>]+>/g, " ").toLowerCase();
+    const rank = PEOPLE_WORDS.findIndex((w) => `${text} ${url.pathname.toLowerCase()}`.includes(w));
+    if (rank < 0) continue;
+    const clean = `${url.origin}${url.pathname}`.replace(/\/$/, "");
+    if (clean === origin) continue;
+    const prior = found.get(clean);
+    if (prior === void 0 || rank < prior) found.set(clean, rank);
+  }
+  return [...found.entries()].sort((a, b) => a[1] - b[1]).slice(0, limit).map(([url]) => url);
+}
+function judgeOrgPage(name, url, text) {
+  const named = mentionsName(fold(text), name);
+  return { url, named, snippet: named ? snippetAround(text, name) : "" };
+}
+var orgSiteStrategy = {
+  name: "org-site",
+  applicable(context) {
+    return Boolean(context.readPage && rootOf(context.person.companyWebsite ?? ""));
+  },
+  async run(context) {
+    const { person, readPage, retrievedAt } = context;
+    const origin = rootOf(person.companyWebsite ?? "");
+    if (!origin || !readPage) {
+      return { strategy: "org-site", sources: [], links: [], notes: "no employer website to read" };
+    }
+    const hits = [];
+    let read = 0;
+    const visit = async (url) => {
+      const html = await readPage(url);
+      if (html === null) return null;
+      read += 1;
+      const hit = judgeOrgPage(person.name, url, stripMarkup(html));
+      if (hit.named) hits.push(hit);
+      return html;
+    };
+    const home = await visit(origin);
+    const followable = home && hits.length === 0 ? peopleLinks(home, origin) : [];
+    const fallback = read <= 1 ? candidatePages(person.companyWebsite ?? "") : [];
+    for (const url of [...followable, ...fallback]) {
+      if (hits.length > 0) break;
+      await visit(url);
+    }
+    const sources = hits.map((hit) => ({
+      sourceUrl: hit.url,
+      sourceClass: "first-party",
+      facts: ["employer", "affiliation"],
+      verifiedOn: retrievedAt,
+      corroboration: "confirmed"
+    }));
+    return {
+      strategy: "org-site",
+      sources,
+      links: [],
+      notes: hits[0] ? `named on ${hits[0].url}
+
+${hits[0].snippet}` : read > 0 ? `read ${read} page(s) on the employer's site; none named them` : "no page on the employer's site could be read"
+    };
+  }
+};
+
+// src/enrich/strategies/research.ts
+var SELF_ASSERTED_HOSTS = ["linkedin.com", "x.com", "twitter.com", "bsky.app", "github.com", "substack.com"];
+function hostOf(url) {
+  try {
+    return new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+  } catch {
+    return "";
+  }
+}
+function classifySource(url, companyWebsite) {
+  const host = hostOf(url);
+  if (!host) return "third-party";
+  const company = companyWebsite ? hostOf(companyWebsite.startsWith("http") ? companyWebsite : `https://${companyWebsite}`) : "";
+  if (company && (host === company || host.endsWith(`.${company}`))) return "first-party";
+  if (SELF_ASSERTED_HOSTS.some((h) => host === h || host.endsWith(`.${h}`))) return "self-asserted";
+  return "third-party";
+}
+function isAttributed(citation) {
+  return Boolean(citation.citedText || citation.startIndex !== void 0 || citation.endIndex !== void 0);
+}
+var researchStrategy = {
+  name: "research",
+  applicable(context) {
+    return Boolean(context.ai && context.models?.search && context.models?.extract);
+  },
+  async run(context) {
+    const { ai, models, person, retrievedAt } = context;
+    if (!ai || !models) return { strategy: "research", sources: [], links: [], notes: "no models available" };
+    const result = await enrichPerson(ai, models, person, retrievedAt);
+    const sources = result.citations.map((citation) => {
+      const corroboration = isAttributed(citation) ? "name-only" : "unchecked";
+      return {
+        sourceUrl: citation.url,
+        sourceClass: classifySource(citation.url, person.companyWebsite),
+        facts: ["identity"],
+        verifiedOn: retrievedAt,
+        corroboration
+      };
+    });
+    return {
+      strategy: "research",
+      sources,
+      links: result.links,
+      notes: `[${result.verification.verdict}] ${result.notes}`
+    };
+  }
+};
+
+// src/enrich/strategies/targeted-profile.ts
+var PROFILE_HOSTS = {
+  "linkedin.com": /\/in\/[^/?#]+/i,
+  "github.com": /^\/[^/?#]+\/?$/i,
+  "bsky.app": /\/profile\/[^/?#]+/i,
+  "x.com": /^\/[^/?#]+\/?$/i,
+  "twitter.com": /^\/[^/?#]+\/?$/i
+};
+function kindOf(host) {
+  if (host.startsWith("linkedin")) return "linkedin";
+  if (host.startsWith("github")) return "github";
+  if (host.startsWith("bsky")) return "bluesky";
+  if (host.startsWith("x.") || host.startsWith("twitter")) return "x";
+  return "other";
+}
+function targetedQuery(person, platform = "linkedin") {
+  const company = person.companyName ? ` "${person.companyName}"` : "";
+  return `"${person.name}"${company} ${platform}`;
+}
+function candidatesFrom(citations) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const citation of citations) {
+    let url;
+    try {
+      url = new URL(citation.url);
+    } catch {
+      continue;
+    }
+    const host = url.hostname.toLowerCase().replace(/^www\./, "").replace(/^[a-z]{2}\./, "");
+    const match = PROFILE_HOSTS[host]?.exec(url.pathname);
+    if (!match) continue;
+    const handle = match[0].replace(/\/+$/, "").toLowerCase();
+    if (!seen.has(`${host}${handle}`)) seen.set(`${host}${handle}`, { url: citation.url, host, handle });
+  }
+  return [...seen.values()];
+}
+var targetedProfileStrategy = {
+  name: "targeted-profile",
+  applicable(context) {
+    return Boolean(context.ai && context.models?.search);
+  },
+  async run(context) {
+    const { ai, models, person, retrievedAt } = context;
+    if (!ai || !models) return { strategy: "targeted-profile", sources: [], links: [], notes: "no search model" };
+    const query = targetedQuery(person);
+    const { citations } = await ai.search({
+      model: models.search,
+      system: "Search for the exact query given and report what you find. Do not guess a profile URL that did not appear in the results.",
+      user: query,
+      maxTokens: 600
+    });
+    const candidates = candidatesFrom(citations);
+    if (candidates.length !== 1) {
+      return {
+        strategy: "targeted-profile",
+        sources: [],
+        links: [],
+        notes: candidates.length === 0 ? `${query}
+
+no profile matched` : `${query}
+
+${candidates.length} distinct profiles matched \u2014 the name is ambiguous`
+      };
+    }
+    const only = candidates[0];
+    const link = { kind: kindOf(only.host), url: only.url };
+    const source = {
+      sourceUrl: only.url,
+      sourceClass: "self-asserted",
+      facts: ["profile"],
+      verifiedOn: retrievedAt,
+      corroboration: "confirmed"
+    };
+    return {
+      strategy: "targeted-profile",
+      sources: [source],
+      links: [link],
+      notes: `${query}
+
+exactly one distinct profile matched the name and company`
+    };
+  }
+};
+
+// src/identity/person.ts
+var DURABLE_KINDS = ["linkedin", "github", "bluesky", "x"];
+function settled(config) {
+  return {
+    aliasType: config.aliasType,
+    aliasKeyAttr: config.aliasKeyAttr ?? "alias",
+    personKeyAttr: config.personKeyAttr ?? "personKey",
+    personType: config.personType ?? "person",
+    edgeLabel: config.edgeLabel ?? "of_person"
+  };
+}
+function mintPersonKey(random = () => crypto.randomUUID()) {
+  return `p_${random()}`;
+}
+function isMintedKey(key) {
+  return key.startsWith("p_");
+}
+function profileAlias(kind, url) {
+  try {
+    const parsed = new URL(url);
+    const handle = parsed.pathname.replace(/\/+$/, "").toLowerCase();
+    return handle && handle !== "/" ? `${kind}:${handle}` : null;
+  } catch {
+    return null;
+  }
+}
+function nameAlias(name, companyName) {
+  const person = identityKey(name);
+  const company = companyName ? identityKey(companyName) : "";
+  return person && company ? `name:${person}~${company}` : null;
+}
+function aliasesFor(person, links = []) {
+  const out = [];
+  for (const kind of DURABLE_KINDS) {
+    for (const link of links.filter((l) => l.kind === kind)) {
+      const alias = profileAlias(kind, link.url);
+      if (alias && !out.includes(alias)) out.push(alias);
+    }
+  }
+  const byName = nameAlias(person.name, person.companyName);
+  if (byName) out.push(byName);
+  return out;
+}
+async function resolvePersonKey(db, config, aliases) {
+  const { aliasType, aliasKeyAttr, personKeyAttr } = settled(config);
+  if (aliases.length === 0) return null;
+  const result = await db.query({
+    [aliasType]: { $: { where: { [aliasKeyAttr]: { $in: [...aliases] } } } }
+  });
+  const found = /* @__PURE__ */ new Map();
+  for (const row of result[aliasType] ?? []) {
+    const alias = row[aliasKeyAttr];
+    const personKey = row[personKeyAttr];
+    if (typeof alias === "string" && typeof personKey === "string" && personKey) found.set(alias, personKey);
+  }
+  for (const alias of aliases) {
+    const hit = found.get(alias);
+    if (hit) return hit;
+  }
+  return null;
+}
+function applyPersonIdentity(fragment, from, to, aliases, config) {
+  const { aliasType, aliasKeyAttr, personKeyAttr, personType, edgeLabel } = settled(config);
+  const rekey = (type, key) => type === personType && key === from ? to : key;
+  const nodes = fragment.nodes.map((n) => ({ ...n, key: rekey(n.type, n.key) }));
+  const edges = fragment.edges.map((e) => ({
+    from: { type: e.from.type, key: rekey(e.from.type, e.from.key) },
+    to: { type: e.to.type, key: rekey(e.to.type, e.to.key) },
+    label: e.label
+  }));
+  for (const alias of [...new Set(aliases)]) {
+    nodes.push({ type: aliasType, key: alias, attrs: { [personKeyAttr]: to } });
+    edges.push({ from: { type: aliasType, key: alias }, to: { type: personType, key: to }, label: edgeLabel });
+  }
+  return { nodes, edges };
+}
+
+// src/identity/identify.ts
+async function identifyPerson(db, config, person, links, fragment) {
+  const aliases = aliasesFor(person, links);
+  const existing = await resolvePersonKey(db, config, aliases);
+  const personKey = existing ?? mintPersonKey();
+  return {
+    personKey,
+    minted: existing === null,
+    aliases,
+    fragment: applyPersonIdentity(fragment, person.slug, personKey, aliases, config)
+  };
+}
+
 // src/llm/provider.ts
 import { init, extractText } from "@odla-ai/ai";
 var MODEL_TIERS = {
@@ -1206,7 +1846,9 @@ async function ingestFresh(step, deps, fresh, kind, resolve = false) {
   );
 }
 export {
+  ACTIONABLE,
   COMMIT_STEP_CONFIG,
+  DEFAULT_STANDARD,
   FACTS_EXTRACT_SYSTEM,
   FACTS_EXTRACT_TOOL,
   FACTS_SEARCH_SYSTEM,
@@ -1215,17 +1857,28 @@ export {
   LOCATE_SYSTEM,
   LOCATE_TOOL,
   MODEL_TIERS,
+  PERSON_EXTRACT_SYSTEM,
+  PERSON_EXTRACT_TOOL,
+  PERSON_SEARCH_SYSTEM,
   Store,
+  TEAM_PATHS,
+  WRITABLE_VERDICTS,
   addUsage,
+  aliasesFor,
   allJobs,
+  applyPersonIdentity,
   asStepLike,
+  candidatePages,
+  candidatesFrom,
   canonicalizeFragment,
+  classifySource,
   connectorIds,
   countyKey,
   createProvider,
   emptyUsage,
   enabledSources,
   enrichCompany,
+  enrichPerson,
   exportFragment,
   extractJson,
   extractJsonArray,
@@ -1233,29 +1886,59 @@ export {
   fetchText,
   fetchUrl,
   findConnectors,
+  fold,
   fragmentToOps,
   getConnector,
   getProvider,
+  gradeSources,
   htmlToText,
   humanAttrsOf,
+  identifyPerson,
+  identityKey,
+  independentHosts,
   ingestFresh,
+  investigatePerson,
+  isActionable,
+  isAttributed,
+  isHttpUrl,
   isLikelyPersonName,
+  isMintedKey,
+  isVerdict,
+  isWritable,
   jobsForHour,
+  judgeOrgPage,
   locatePrompt,
   locationFragment,
   makeContext,
+  mentionsName,
   mergeAttrs,
   mergeRulesOf,
   mergeScalar,
+  mintPersonKey,
+  nameAlias,
   naturalKeysOf,
   normalizeUrl,
+  normalizeVerification,
+  orgSiteStrategy,
+  peopleLinks,
+  personPrompt,
+  personToFragment,
+  profileAlias,
+  researchStrategy,
   resilientStep,
   resolveCounties,
   resolveName,
+  resolvePersonKey,
+  rootOf,
   searchEntities,
   slugify,
+  snippetAround,
+  stripMarkup,
+  targetedProfileStrategy,
+  targetedQuery,
   toSerializedSchema,
   urlHash,
+  validateLinks,
   writeFragment
 };
 //# sourceMappingURL=index.js.map