@dench.com/cli 2.7.4 → 2.7.6-staging.1

package/lib/exa-people.ts

@@ -0,0 +1,682 @@
+/**
+ * Exa People Search — entity parsing, Apollo-shape projection, and match gating.
+ *
+ * Exa's People Search (`POST /search` with `category: "people"`) returns
+ * structured person metadata on `results[].entities[]`, each
+ * `{ id, type: "person", version, properties }`. The gateway passes Exa's
+ * response through untouched (gateway/src/http.ts), so those entities arrive
+ * here verbatim.
+ *
+ * Two jobs live in this file:
+ *
+ *  1. **Projection.** `toApolloEnvelope` rewrites a person entity into the
+ *     Apollo-shaped envelope the rest of the codebase already speaks, so the
+ *     existing extraction machinery (`extractEnrichmentValue` /
+ *     `apolloPath` / `crmFields.enrichment`) works against Exa with no new
+ *     extraction path. Exa becomes just another provider.
+ *
+ *  2. **Match gating.** Unlike FullEnrich and Aviato, Exa is a *search*, not a
+ *     lookup by identifier — it always returns *somebody*. Writing the top hit
+ *     into a CRM cell would silently corrupt data with a plausible-looking
+ *     stranger. `matchExaPerson` therefore refuses to return a candidate
+ *     unless identity is corroborated (exact LinkedIn URL, or name AND company
+ *     agreement), and callers are expected to surface `not_found` rather than
+ *     write a low-confidence guess.
+ *
+ * Everything here is pure and I/O-free so it can be unit tested directly, and
+ * it lives in `cli/lib/` because that is where this repo keeps logic shared
+ * between the `dench` CLI and the agent workflow steps (see
+ * src/workflows/enrichment-steps.ts, which already imports from here).
+ *
+ * Exa's docs are explicit that profile sources vary in what they include, so
+ * every field is treated as optional and every nested value defensively.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ExaDateRange = {
+  from?: string | null;
+  to?: string | null;
+};
+
+export type ExaCompanyRef = {
+  id?: string | null;
+  name?: string | null;
+};
+
+export type ExaWorkHistoryItem = {
+  title?: string;
+  location?: string;
+  dates?: ExaDateRange | null;
+  company?: ExaCompanyRef | null;
+};
+
+export type ExaInstitutionRef = {
+  id?: string | null;
+  name?: string | null;
+};
+
+export type ExaEducationItem = {
+  degree?: string;
+  dates?: ExaDateRange | null;
+  institution?: ExaInstitutionRef | null;
+};
+
+export type ExaPerson = {
+  /** Stable Exa person entity id, when present. */
+  id?: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+  location?: string;
+  workHistory: ExaWorkHistoryItem[];
+  educationHistory: ExaEducationItem[];
+};
+
+export type ExaPersonHit = {
+  /** Profile URL from the enclosing search result. May be "" if absent. */
+  url: string;
+  title?: string;
+  highlights?: string[];
+  person: ExaPerson;
+};
+
+// ---------------------------------------------------------------------------
+// Defensive readers
+// ---------------------------------------------------------------------------
+
+export function asString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function asObject(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+export function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value.filter(
+    (item): item is string =>
+      typeof item === "string" && item.trim().length > 0,
+  );
+  return out.length > 0 ? out : undefined;
+}
+
+/**
+ * `dates` is documented as `{ from, to } | null`, but a source may omit it
+ * entirely or hand back a bare string. Anything we cannot read as an object
+ * becomes `null` — "unknown", which is deliberately NOT the same as
+ * `{ to: null }` ("still there"). `currentRole` depends on that distinction.
+ */
+function readDates(value: unknown): ExaDateRange | null {
+  const raw = asObject(value);
+  if (!raw) return null;
+  const from = asString(raw.from);
+  const to = asString(raw.to);
+  const range: ExaDateRange = {};
+  if (from !== undefined) range.from = from;
+  // Preserve an explicit null `to` — it is the "current role" signal.
+  if (to !== undefined) range.to = to;
+  else if ("to" in raw) range.to = null;
+  return range;
+}
+
+function readCompanyRef(value: unknown): ExaCompanyRef | null {
+  const raw = asObject(value);
+  if (!raw) return null;
+  const name = asString(raw.name);
+  const id = asString(raw.id);
+  if (name === undefined && id === undefined) return null;
+  return { id: id ?? null, name: name ?? null };
+}
+
+function readWorkHistory(value: unknown): ExaWorkHistoryItem[] {
+  const out: ExaWorkHistoryItem[] = [];
+  for (const entry of asArray(value)) {
+    const raw = asObject(entry);
+    if (!raw) continue;
+    const item: ExaWorkHistoryItem = {
+      title: asString(raw.title),
+      location: asString(raw.location),
+      dates: readDates(raw.dates),
+      company: readCompanyRef(raw.company),
+    };
+    // A row with nothing usable in it is noise, not history.
+    if (!item.title && !item.company && !item.dates) continue;
+    out.push(item);
+  }
+  return out;
+}
+
+function readEducationHistory(value: unknown): ExaEducationItem[] {
+  const out: ExaEducationItem[] = [];
+  for (const entry of asArray(value)) {
+    const raw = asObject(entry);
+    if (!raw) continue;
+    const item: ExaEducationItem = {
+      degree: asString(raw.degree),
+      dates: readDates(raw.dates),
+      institution: readCompanyRef(raw.institution),
+    };
+    if (!item.degree && !item.institution) continue;
+    out.push(item);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk an Exa `/search` response and pull out every person entity.
+ *
+ * Only `type: "person"` entities are kept — the docs describe `entities` as
+ * populated "for result rows that resolve to a person", so a result without
+ * one is a page we could not resolve, not a person with no data.
+ */
+export function parseExaPeopleResults(data: unknown): ExaPersonHit[] {
+  const root = asObject(data);
+  if (!root) return [];
+  const hits: ExaPersonHit[] = [];
+
+  for (const entry of asArray(root.results)) {
+    const result = asObject(entry);
+    if (!result) continue;
+    const url = asString(result.url) ?? asString(result.link) ?? "";
+    const title = asString(result.title);
+    const highlights = asStringArray(result.highlights);
+
+    for (const entityEntry of asArray(result.entities)) {
+      const entity = asObject(entityEntry);
+      if (!entity) continue;
+      if (asString(entity.type) !== "person") continue;
+      const properties = asObject(entity.properties);
+      if (!properties) continue;
+
+      const person: ExaPerson = {
+        id: asString(entity.id),
+        name: asString(properties.name),
+        firstName: asString(properties.firstName),
+        lastName: asString(properties.lastName),
+        location: asString(properties.location),
+        workHistory: readWorkHistory(properties.workHistory),
+        educationHistory: readEducationHistory(properties.educationHistory),
+      };
+
+      hits.push({ url, title, highlights, person });
+    }
+  }
+
+  return hits;
+}
+
+/** Full name, falling back to first + last when `name` is absent. */
+export function personFullName(person: ExaPerson): string | undefined {
+  if (person.name) return person.name;
+  const parts = [person.firstName, person.lastName].filter(
+    (part): part is string => typeof part === "string" && part.length > 0,
+  );
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
+/**
+ * Best guess at the person's current role.
+ *
+ * Only an entry whose `dates.to` is explicitly null counts as current. Ended
+ * or undated roles are historical/unknown; projecting either as current writes
+ * stale employment data into CRM fields.
+ */
+export function currentRole(person: ExaPerson): ExaWorkHistoryItem | null {
+  const history = person.workHistory;
+  if (history.length === 0) return null;
+
+  const open = history.filter(
+    (item) => item.dates != null && "to" in item.dates && item.dates.to == null,
+  );
+  if (open.length > 0) {
+    return open.reduce((best, item) =>
+      compareDateStrings(item.dates?.from, best.dates?.from) > 0 ? item : best,
+    );
+  }
+  return null;
+}
+
+/**
+ * Order two partial date strings. Exa mixes granularities ("2014",
+ * "2022-01-01"), but both are zero-padded and year-first, so lexicographic
+ * comparison orders them correctly. Missing sorts before present.
+ */
+function compareDateStrings(
+  a: string | null | undefined,
+  b: string | null | undefined,
+): number {
+  const left = asString(a);
+  const right = asString(b);
+  if (left === right) return 0;
+  if (left === undefined) return -1;
+  if (right === undefined) return 1;
+  return left < right ? -1 : 1;
+}
+
+// ---------------------------------------------------------------------------
+// Apollo-shape projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Prefix a bare host with a scheme so `new URL` can parse it.
+ *
+ * The scheme test must be case-insensitive: "HTTPS://Example.com" does not
+ * start with lowercase "http", so a naive check prepends a second scheme and
+ * `new URL("https://HTTPS://Example.com").hostname` quietly evaluates to
+ * "https" — a wrong domain rather than a parse error. CRM data is pasted by
+ * humans, so mixed-case URLs really do show up.
+ */
+export function withScheme(value: string): string {
+  return /^https?:\/\//i.test(value) ? value : `https://${value}`;
+}
+
+const LINKEDIN_PROFILE_PATTERN = /(^|\.)linkedin\.com$/i;
+
+/** True when the URL looks like a LinkedIn *person* profile (`/in/...`). */
+export function isLinkedInProfileUrl(url: string): boolean {
+  const trimmed = url.trim();
+  if (!trimmed) return false;
+  try {
+    const parsed = new URL(withScheme(trimmed));
+    return (
+      LINKEDIN_PROFILE_PATTERN.test(parsed.hostname) &&
+      /\/in\/[^/]+/i.test(parsed.pathname)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Split Exa's single location string into the city/state/country fields the
+ * `__computed.location` extractor reads (see `computeLocation` in
+ * cli/lib/crm-enrichment.ts, which joins city + state + country).
+ *
+ * Exa formats these as "San Francisco, California, United States". We only
+ * assign parts when the shape is unambiguous; the raw string is always kept
+ * on `person.location` regardless, which is a declared extraction fallback.
+ */
+function splitLocation(location: string | undefined): {
+  city?: string;
+  state?: string;
+  country?: string;
+} {
+  if (!location) return {};
+  const parts = location
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  if (parts.length >= 3) {
+    return {
+      city: parts[0],
+      state: parts[1],
+      country: parts[parts.length - 1],
+    };
+  }
+  if (parts.length === 2) return { city: parts[0], country: parts[1] };
+  if (parts.length === 1) return { city: parts[0] };
+  return {};
+}
+
+/**
+ * Project a person hit into the Apollo-shaped envelope the existing
+ * enrichment extractors understand.
+ *
+ * The keys here are load-bearing: they are the `apolloPath` targets declared
+ * by enrichment columns. `extractApolloValue` (cli/lib/crm-enrichment.ts) is a
+ * generic dot-path resolver, so any path listed in an Exa-backed column
+ * definition must exist in this object.
+ */
+export function toApolloEnvelope(hit: ExaPersonHit): Record<string, unknown> {
+  const { person } = hit;
+  const role = currentRole(person);
+  const title = role?.title;
+  const companyName = role?.company?.name ?? undefined;
+  const name = personFullName(person);
+  const { city, state, country } = splitLocation(person.location);
+
+  const employmentHistory = person.workHistory.map((item) => ({
+    title: item.title ?? null,
+    organization_name: item.company?.name ?? null,
+    location: item.location ?? null,
+    start_date: item.dates?.from ?? null,
+    end_date: item.dates?.to ?? null,
+    current: item.dates != null && "to" in item.dates && item.dates.to == null,
+  }));
+
+  const education = person.educationHistory.map((item) => ({
+    degree: item.degree ?? null,
+    school_name: item.institution?.name ?? null,
+    start_date: item.dates?.from ?? null,
+    end_date: item.dates?.to ?? null,
+  }));
+
+  const personEnvelope: Record<string, unknown> = {
+    id: person.id ?? null,
+    name: name ?? null,
+    first_name: person.firstName ?? null,
+    last_name: person.lastName ?? null,
+    title: title ?? null,
+    headline:
+      title && companyName ? `${title} at ${companyName}` : (title ?? null),
+    location: person.location ?? null,
+    city: city ?? null,
+    state: state ?? null,
+    country: country ?? null,
+    organization: companyName ? { name: companyName } : null,
+    organization_name: companyName ?? null,
+    linkedin_url: isLinkedInProfileUrl(hit.url) ? hit.url : null,
+    employment_history: employmentHistory,
+    education,
+  };
+
+  return {
+    person: personEnvelope,
+    // Top-level organization mirror so company-category columns
+    // (apolloPath "organization.name") resolve against the same payload.
+    organization: companyName ? { name: companyName } : null,
+    // Provenance — this is a search result, not an identifier lookup, so the
+    // source URL matters when a human audits the written cell.
+    // Provenance the model and a human auditor both want — the profile this
+    // came from. Deliberately NOT the provider name: this envelope is
+    // returned as the tool result, and naming the source there is exactly
+    // what the enrichment surface is meant to keep internal.
+    source: { url: hit.url || null },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Match gating
+// ---------------------------------------------------------------------------
+
+export type ExaMatchCriteria =
+  | { kind: "linkedin_url"; linkedinUrl: string }
+  | {
+      kind: "name_company";
+      fullName?: string;
+      firstName?: string;
+      lastName?: string;
+      organizationName?: string;
+    };
+
+export type ExaMatchConfidence = "exact" | "high";
+
+export type ExaPersonMatch = {
+  hit: ExaPersonHit;
+  confidence: ExaMatchConfidence;
+  /** Human-readable reason the candidate was accepted, for observability. */
+  matchedOn: string;
+};
+
+export type ExaMatchOutcome =
+  | { status: "matched"; match: ExaPersonMatch }
+  | { status: "no_match" }
+  | { status: "insufficient_criteria"; missing: string[] };
+
+/**
+ * Build the natural-language query for resolving ONE known person.
+ *
+ * Exa People Search takes no structured filters at all — every constraint has
+ * to live in the sentence (see exa-search-constraints.ts). Naming the company
+ * alongside the person is also what makes the match gate able to corroborate
+ * identity, so it is included whenever we have it.
+ */
+export function buildPersonLookupQuery(criteria: ExaMatchCriteria): string {
+  if (criteria.kind === "linkedin_url") return criteria.linkedinUrl;
+  const name =
+    criteria.fullName ??
+    [criteria.firstName, criteria.lastName].filter(Boolean).join(" ");
+  return criteria.organizationName
+    ? `${name} at ${criteria.organizationName}`
+    : name;
+}
+
+/** Lowercase, strip combining marks and punctuation, preserve every script. */
+export function normalizeName(value: string): string {
+  return value
+    .normalize("NFKD")
+    .replace(/(\p{Script=Latin})\p{M}+/gu, "$1")
+    .toLocaleLowerCase()
+    .replace(/[^\p{L}\p{N}\p{M}]+/gu, " ")
+    .trim()
+    .normalize("NFC");
+}
+
+const TRAILING_LEGAL_SUFFIXES = new Set([
+  "inc",
+  "incorporated",
+  "llc",
+  "ltd",
+  "limited",
+  "corp",
+  "corporation",
+  "co",
+  "gmbh",
+  "bv",
+  "nv",
+  "sa",
+  "ag",
+  "plc",
+  "pte",
+  "pty",
+]);
+
+/**
+ * Normalize a company name and drop only trailing legal forms. Removing these
+ * words from the middle destroys real brands ("The Company Store", "Acme
+ * Labs") and can collapse unrelated companies onto the same identity.
+ */
+export function normalizeCompany(value: string): string {
+  const tokens = normalizeName(value).split(" ").filter(Boolean);
+  while (
+    tokens.length > 1 &&
+    TRAILING_LEGAL_SUFFIXES.has(tokens[tokens.length - 1])
+  ) {
+    tokens.pop();
+  }
+  return tokens.join(" ");
+}
+
+/**
+ * Reduce a LinkedIn URL to a comparable identity: no protocol, no `www.`, no
+ * query or hash, no trailing slash, lowercased.
+ */
+export function normalizeLinkedInUrl(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  let working = trimmed;
+  try {
+    const parsed = new URL(withScheme(trimmed));
+    const profile = parsed.pathname.match(/^\/in\/([^/]+)/i);
+    working =
+      LINKEDIN_PROFILE_PATTERN.test(parsed.hostname) && profile
+        ? `linkedin.com/in/${profile[1]}`
+        : `${parsed.hostname}${parsed.pathname}`;
+  } catch {
+    working = trimmed.split(/[?#]/)[0];
+  }
+  return working
+    .toLowerCase()
+    .replace(/^www\./, "")
+    .replace(/\/+$/, "");
+}
+
+/**
+ * Company identity evidence must be exact after legal-suffix normalization.
+ * Substring matching makes short names dangerous ("Meta" matched
+ * "Metaverse"), which defeats the two-factor name + employer gate.
+ */
+function companiesAgree(left: string, right: string): boolean {
+  const a = normalizeCompany(left);
+  const b = normalizeCompany(right);
+  if (!a || !b) return false;
+  return a === b;
+}
+
+/**
+ * First and last name must agree positionally. Matching an initial is allowed
+ * only for the candidate's final surname token.
+ *
+ * One concession to how LinkedIn actually stores names: a surname abbreviated
+ * to an initial on the CANDIDATE side ("Adarsh K.") counts as agreeing with a
+ * full wanted token starting with that letter ("Adarsh Kumar"). Without it
+ * these profiles never match their own CRM row — abbreviated surnames showed
+ * up in the first handful of live results. It is safe here only because the
+ * caller additionally requires company agreement, so a false positive needs
+ * the same first name AND same surname initial AND the same employer.
+ */
+function namesAgree(
+  candidate: string,
+  first: string | undefined,
+  last: string | undefined,
+): boolean {
+  const normalizedCandidate = normalizeName(candidate);
+  if (!normalizedCandidate) return false;
+  const candidateTokens = normalizedCandidate.split(" ").filter(Boolean);
+  const wantedFirst = first
+    ? normalizeName(first).split(" ").filter(Boolean)
+    : [];
+  const wantedLast = last ? normalizeName(last).split(" ").filter(Boolean) : [];
+  if (
+    candidateTokens.length < 2 ||
+    wantedFirst.length === 0 ||
+    wantedLast.length === 0
+  ) {
+    return false;
+  }
+
+  const candidateFirst = candidateTokens[0];
+  const candidateLast = candidateTokens[candidateTokens.length - 1];
+  const requestedFirst = wantedFirst[0];
+  const requestedLast = wantedLast[wantedLast.length - 1];
+  const firstMatches = candidateFirst === requestedFirst;
+  const lastMatches =
+    candidateLast === requestedLast ||
+    (candidateLast.length === 1 &&
+      requestedLast.length > 1 &&
+      requestedLast.startsWith(candidateLast));
+  return firstMatches && lastMatches;
+}
+
+function splitFullName(fullName: string): {
+  firstName?: string;
+  lastName?: string;
+} {
+  const parts = normalizeName(fullName)
+    .split(" ")
+    .filter((part) => part.length > 0);
+  if (parts.length < 2) return {};
+  return { firstName: parts[0], lastName: parts[parts.length - 1] };
+}
+
+/**
+ * Pick the one candidate we are willing to write into a CRM cell, or refuse.
+ *
+ * This is the data-integrity boundary for Exa-backed enrichment. Exa ranks by
+ * relevance and always returns *someone*, so "the first result" is never
+ * sufficient evidence of identity. A caller that gets `no_match` must report
+ * `not_found` — it must not fall back to `hits[0]`.
+ */
+export function matchExaPerson(
+  hits: ExaPersonHit[],
+  criteria: ExaMatchCriteria,
+): ExaMatchOutcome {
+  if (criteria.kind === "linkedin_url") {
+    const wanted = normalizeLinkedInUrl(criteria.linkedinUrl);
+    if (!wanted || !isLinkedInProfileUrl(criteria.linkedinUrl)) {
+      return { status: "insufficient_criteria", missing: ["linkedinUrl"] };
+    }
+    for (const hit of hits) {
+      if (
+        hit.url &&
+        isLinkedInProfileUrl(hit.url) &&
+        normalizeLinkedInUrl(hit.url) === wanted
+      ) {
+        return {
+          status: "matched",
+          match: { hit, confidence: "exact", matchedOn: "linkedin_url" },
+        };
+      }
+    }
+    return { status: "no_match" };
+  }
+
+  // name_company: identity needs BOTH halves. A name alone cannot
+  // disambiguate — the index has many people per common name, and picking one
+  // is exactly how the wrong person's title lands in a cell.
+  const derived = criteria.fullName ? splitFullName(criteria.fullName) : {};
+  const firstName = criteria.firstName ?? derived.firstName;
+  const lastName = criteria.lastName ?? derived.lastName;
+  const organizationName = criteria.organizationName?.trim();
+
+  // Structured as one guard so both names and the company narrow to `string`
+  // for the comparisons below.
+  if (!firstName || !lastName || !organizationName) {
+    const missing: string[] = [];
+    if (!firstName || !lastName) missing.push("name");
+    if (!organizationName) missing.push("organizationName");
+    return { status: "insufficient_criteria", missing };
+  }
+
+  const currentMatches = new Map<string, ExaPersonMatch>();
+  for (const hit of hits) {
+    const candidateName = personFullName(hit.person);
+    if (!candidateName) continue;
+    if (!namesAgree(candidateName, firstName, lastName)) continue;
+
+    // Check every role at the target company, not just the best-guess current
+    // one: `currentRole` falls back to the most recently *ended* role, so
+    // keying off it would read "left Example AI in 2018" as "works at Example
+    // AI now" for anyone with a single, finished stint there.
+    const rolesAtCompany = hit.person.workHistory.filter(
+      (item) =>
+        item.company?.name &&
+        companiesAgree(item.company.name, organizationName),
+    );
+    if (rolesAtCompany.length === 0) continue;
+
+    if (
+      rolesAtCompany.some(
+        (item) =>
+          item.dates != null && "to" in item.dates && item.dates.to == null,
+      )
+    ) {
+      const identity =
+        hit.person.id ||
+        normalizeLinkedInUrl(hit.url) ||
+        `${normalizeName(candidateName)}:${currentMatches.size}`;
+      currentMatches.set(identity, {
+        hit,
+        confidence: "high",
+        matchedOn: "name+current_company",
+      });
+    }
+
+    // Ended or undated employment is not enough to claim the CRM's company is
+    // current. False negatives are safer than writing another person's data.
+  }
+
+  if (currentMatches.size === 1) {
+    return {
+      status: "matched",
+      match: [...currentMatches.values()][0],
+    };
+  }
+  return { status: "no_match" };
+}