@odla-ai/kg 0.4.1 → 0.5.0

package/README.md

@@ -15,6 +15,13 @@ the host supplies the database client, LLM keys, and a KV-like store. The
 public platform and package manuals describe how to compose it with Workflows,
 scheduled triggers, an HTTP API, and a viewer UI.
 
+> **Ask the runbooks first.** odla's operational procedures live in a database,
+> not in this file: `npx @odla-ai/cli runbook ask "<question>"` returns the current
+> steps, and unlike anything written here it cannot be out of date. Use it before
+> searching the web or working from memory. This README and the JSDoc in the
+> shipped `.d.ts` are the version-matched **API** reference; a runbook is the
+> **procedure**. Most tasks need an answer from both.
+
 ## Architecture
 
 ```
@@ -76,6 +83,30 @@ Key seams the host supplies:
 straight to the writer) · `web-search` (LLM web-search discovery) · `gov-data`
 (template proving a new source needs no pipeline change).
 
+## Enrichment & verdicts
+
+`enrichCompany` and `enrichPerson` run a grounded web search, then a forced-tool
+extraction, then validate the result into a `GraphFragment`.
+
+Person enrichment always returns a **verdict** — `confirmed`, `probable`,
+`ambiguous`, `not_found`, or `wrong_entity` — with a confidence and evidence
+tied to source URLs. The distinctions matter: a pass that confidently describes a
+*different* person with the same name is a much worse failure than one that found
+nothing, and collapsing the two makes it invisible. The fragment is empty unless
+the verdict permits writing, and a "confirmation" whose evidence carries no
+checkable source URL is downgraded to `ambiguous` rather than believed.
+
+`validateLinks` drops profile URLs whose host contradicts their claimed kind —
+a `linkedin.com/in/<name>` pattern served from some other host is the single most
+common hallucination in this task. Scope is deliberately public and professional:
+site, blog, Substack, LinkedIn, X/Bluesky, GitHub, employer, and business contact
+points the person or their employer published. Never home addresses, personal
+phones, or personal email.
+
+Use `identityKey` (not `slugify`) to decide whether two records are the same
+entity: it folds away punctuation, accents, `&`, and trailing legal suffixes, so
+"Acme Corp.", "Acme, Inc." and "Acme & Co" agree.
+
 ## Provenance & merging
 
 `writeFragment` reads existing nodes by natural key (one batched query), merges

package/dist/index.cjs

@@ -29,7 +29,11 @@ __export(index_exports, {
   LOCATE_SYSTEM: () => LOCATE_SYSTEM,
   LOCATE_TOOL: () => LOCATE_TOOL,
   MODEL_TIERS: () => MODEL_TIERS,
+  PERSON_EXTRACT_SYSTEM: () => PERSON_EXTRACT_SYSTEM,
+  PERSON_EXTRACT_TOOL: () => PERSON_EXTRACT_TOOL,
+  PERSON_SEARCH_SYSTEM: () => PERSON_SEARCH_SYSTEM,
   Store: () => Store,
+  WRITABLE_VERDICTS: () => WRITABLE_VERDICTS,
   addUsage: () => addUsage,
   allJobs: () => allJobs,
   asStepLike: () => asStepLike,
@@ -40,6 +44,7 @@ __export(index_exports, {
   emptyUsage: () => emptyUsage,
   enabledSources: () => enabledSources,
   enrichCompany: () => enrichCompany,
+  enrichPerson: () => enrichPerson,
   exportFragment: () => exportFragment,
   extractJson: () => extractJson,
   extractJsonArray: () => extractJsonArray,
@@ -52,8 +57,12 @@ __export(index_exports, {
   getProvider: () => getProvider,
   htmlToText: () => htmlToText,
   humanAttrsOf: () => humanAttrsOf,
+  identityKey: () => identityKey,
   ingestFresh: () => ingestFresh,
+  isHttpUrl: () => isHttpUrl,
   isLikelyPersonName: () => isLikelyPersonName,
+  isVerdict: () => isVerdict,
+  isWritable: () => isWritable,
   jobsForHour: () => jobsForHour,
   locatePrompt: () => locatePrompt,
   locationFragment: () => locationFragment,
@@ -63,6 +72,9 @@ __export(index_exports, {
   mergeScalar: () => mergeScalar,
   naturalKeysOf: () => naturalKeysOf,
   normalizeUrl: () => normalizeUrl,
+  normalizeVerification: () => normalizeVerification,
+  personPrompt: () => personPrompt,
+  personToFragment: () => personToFragment,
   resilientStep: () => resilientStep,
   resolveCounties: () => resolveCounties,
   resolveName: () => resolveName,
@@ -70,6 +82,7 @@ __export(index_exports, {
   slugify: () => slugify,
   toSerializedSchema: () => toSerializedSchema,
   urlHash: () => urlHash,
+  validateLinks: () => validateLinks,
   writeFragment: () => writeFragment
 });
 module.exports = __toCommonJS(index_exports);
@@ -594,6 +607,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);
@@ -736,6 +758,160 @@ 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/run.ts
 async function enrichCompany(ai, models, company) {
   const where = `${company.city ? `, ${company.city}` : ""}${company.region ? ` (${company.region})` : ""}`;
@@ -759,6 +935,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,