Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.0 KB
Raw Blame
/**
 * #7160: the entity card's name-variant arm. Runs only after the precision
 * arms (alias, exact title or slug, slug suffix) found nothing. One indexed
 * candidate read per source (title and slug trigram indexes), then the pure
 * matcher in entities/name-variants.ts scores every candidate. A variant
 * resolves only when exactly one live entity page holds the strongest match
 * and the candidate read was not capped (a full read may hide an equal
 * match), and a weak match (surname alone, one-letter typo) only when it is
 * the one page that matched at all. Anything else is
 * ambiguous: nothing resolves and the matches come back as suggestions, so a
 * near-name never lands on a different person.
 *
 * `entity.name_variants=false` turns the arm off.
 */

import type { BrainEngine } from '../engine.ts';
import { isQuarantined } from '../quarantine.ts';
import { followRetirement, isIdentityEntity } from '../entities/resolve.ts';
import { NAME_MATCH_RANK, NAME_TITLE_TOKENS, WEAK_NAME_MATCHES, hasLeadingTitle, matchNameVariant, parsePersonName, probeWords, stripLeadingTitles, type NameMatchKind } from '../entities/name-variants.ts';

/** Candidate rows read per source; a full read means another page may have matched, so nothing resolves. */
export const VARIANT_CANDIDATE_CAP = 200;
/** Names longer than this many words are not person or organization names. */
const MAX_NAME_WORDS = 5;

export interface VariantRow { slug: string; title: string | null; type: string | null; frontmatter: Record<string, unknown> | null }

export interface VariantMatch<R extends VariantRow> { row: R; kind: NameMatchKind }

export interface VariantResult<R extends VariantRow> {
  /** The one page the name resolves to, with how it matched. */
  hit?: VariantMatch<R>;
  /** Every entity page that matched, strongest first (the hit included). */
  matches: Array<VariantMatch<R>>;
}

export async function nameVariantsEnabled(engine: Pick<BrainEngine, 'getConfig'>): Promise<boolean> {
  const v = await engine.getConfig('entity.name_variants').catch(() => null);
  return !(typeof v === 'string' && /^(false|off|0|no)$/i.test(v.trim()));
}

const likeWord = (w: string) => `%${w.replace(/[\\%_]/g, m => `\\${m}`)}%`;
const basenameName = (slug: string) => (slug.split('/').pop() ?? '').replace(/[-_]+/g, ' ');

/** The strongest variant under which `name` names this page (by title or slug basename). */
function bestKind(name: string, row: VariantRow): NameMatchKind | null {
  if (isTitleStub(row.title || basenameName(row.slug))) return null;
  const kinds = [row.title ?? '', basenameName(row.slug)]
    .filter(candidate => !isTitleStub(candidate))
    .map(candidate => matchNameVariant(name, candidate))
    .filter((k): k is NameMatchKind => k !== null);
  return kinds.length ? kinds.reduce((a, b) => (NAME_MATCH_RANK[b] < NAME_MATCH_RANK[a] ? b : a)) : null;
}

/** "Mayor Example": a title in front of one name word. It names someone only through the page it duplicates, never as a variant target. */
export function isTitleStub(name: string): boolean {
  const parsed = parsePersonName(name);
  return parsed.titles.length > 0 && parsed.core.length === 1;
}

/**
 * Variant candidates for `name` in one source. `selectColumns` is the
 * caller's row projection over `pages`; `privatePredicate` its read
 * predicate (` AND ...` or empty) on `pages`, `retirementPrivacy` the same on
 * alias `p` (followRetirement); `entityTypes` the pack's linkable types.
 */
export async function resolveNameVariant<R extends VariantRow>(
  engine: BrainEngine,
  sourceId: string,
  name: string,
  opts: { selectColumns: string; privatePredicate: string; retirementPrivacy: string; entityTypes: ReadonlySet<string>; omitQuarantined?: boolean; exclude?: readonly string[] },
): Promise<VariantResult<R>> {
  const words = probeWords(name);
  if (!words.length || parsePersonName(name).core.length > MAX_NAME_WORDS || name.includes('/')) return { matches: [] };
  let rows: Array<R & { probe_hits: number }>;
  try {
    rows = await engine.executeRaw<R & { probe_hits: number }>(
      `SELECT ${opts.selectColumns},
              (SELECT count(*)::int FROM unnest($4::text[]) w WHERE pages.title ILIKE w OR pages.slug ILIKE w) AS probe_hits
         FROM pages
        WHERE deleted_at IS NULL AND source_id = $1
          AND (type = ANY($2::text[]) OR slug LIKE ANY($3::text[]))
          AND (title ILIKE ANY($4::text[]) OR slug ILIKE ANY($4::text[]))${opts.privatePredicate}
        ORDER BY probe_hits DESC, length(title), slug
        LIMIT ${VARIANT_CANDIDATE_CAP + 1}`,
      [sourceId, [...opts.entityTypes, 'person', 'company', 'fund', 'organization'],
        ['people/%', 'companies/%', 'funds/%', 'orgs/%', 'organizations/%'], words.map(likeWord)],
    );
  } catch {
    return { matches: [] };
  }
  const capped = rows.length > VARIANT_CANDIDATE_CAP;
  const exclude = new Set(opts.exclude ?? []);
  const best = new Map<string, VariantMatch<R>>();
  for (const row of rows.slice(0, VARIANT_CANDIDATE_CAP)) {
    if (exclude.has(row.slug) || !isIdentityEntity(row.slug, row.type) && !opts.entityTypes.has(row.type ?? '')) continue;
    if (opts.omitQuarantined && isQuarantined(row.frontmatter)) continue;
    const kind = bestKind(name, row);
    if (!kind) continue;
    const live = await followRetirement(engine, sourceId, row.slug, opts.retirementPrivacy).catch(() => null);
    if (!live || exclude.has(live.slug)) continue;
    let target: R | undefined = live.slug === row.slug ? row : rows.find(r => r.slug === live.slug);
    if (!target) {
      const [fetched] = await engine.executeRaw<R>(
        `SELECT ${opts.selectColumns} FROM pages WHERE deleted_at IS NULL AND source_id = $1 AND slug = $2${opts.privatePredicate}`,
        [sourceId, live.slug]).catch(() => [] as R[]);
      if (!fetched || (opts.omitQuarantined && isQuarantined(fetched.frontmatter))) continue;
      target = fetched;
    }
    const prev = best.get(target.slug);
    if (!prev || NAME_MATCH_RANK[kind] < NAME_MATCH_RANK[prev.kind]) best.set(target.slug, { row: target, kind });
  }
  const matches = [...best.values()].sort((a, b) => NAME_MATCH_RANK[a.kind] - NAME_MATCH_RANK[b.kind] || a.row.slug.localeCompare(b.row.slug));
  if (!matches.length) return { matches };
  const top = matches.filter(m => m.kind === matches[0]!.kind);
  const weak = WEAK_NAME_MATCHES.has(matches[0]!.kind);
  const unique = !capped && top.length === 1 && (!weak || matches.length === 1);
  return unique ? { hit: matches[0], matches } : { matches };
}

export interface PossibleDuplicate { slug: string; title: string; reason: 'title_prefix' }

/**
 * #7160: title-prefixed person pages that likely name the same person as
 * `row` ("people/mayor-example" next to "people/alice-example"). Reported,
 * never merged or substituted: a pair qualifies only when the prefixed
 * page's remaining name resolves by the variant rules to exactly one other
 * person page. For a prefixed page that is the unprefixed page it
 * duplicates; for an unprefixed page, every prefixed page whose remainder
 * resolves to it. Fail-soft: a read error reports nothing.
 */
export async function readPossibleDuplicates<R extends VariantRow>(
  engine: BrainEngine,
  sourceId: string,
  row: VariantRow,
  opts: { selectColumns: string; privatePredicate: string; retirementPrivacy: string; entityTypes: ReadonlySet<string>; omitQuarantined?: boolean },
): Promise<PossibleDuplicate[]> {
  if (!row.slug.startsWith('people/') && row.type !== 'person') return [];
  const basename = basenameName(row.slug);
  const resolveRemainder = async (stub: VariantRow): Promise<string | null> => {
    const name = [stub.title ?? '', basenameName(stub.slug)].find(hasLeadingTitle);
    if (!name) return null;
    const res = await resolveNameVariant<R>(engine, sourceId, stripLeadingTitles(name), { ...opts, exclude: [stub.slug] });
    return res.hit?.row.slug ?? null;
  };
  try {
    if (hasLeadingTitle(row.title ?? '') || hasLeadingTitle(basename)) {
      const target = await resolveRemainder(row);
      if (!target) return [];
      const [t] = await engine.executeRaw<{ slug: string; title: string | null }>('SELECT slug, title FROM pages WHERE source_id = $1 AND slug = $2', [sourceId, target]);
      return t ? [{ slug: t.slug, title: t.title ?? t.slug, reason: 'title_prefix' }] : [];
    }
    const core = parsePersonName(row.title || basename).core;
    if (core.length < 2) return [];
    const last = core[core.length - 1]!;
    const slugs = [...NAME_TITLE_TOKENS].flatMap(t => [`people/${t}-${last}`, `people/${t}-${core.join('-')}`]);
    const stubs = await engine.executeRaw<R>(
      `SELECT ${opts.selectColumns} FROM pages WHERE deleted_at IS NULL AND source_id = $1 AND slug = ANY($2::text[]) AND slug <> $3${opts.privatePredicate}`,
      [sourceId, slugs, row.slug]);
    const out: PossibleDuplicate[] = [];
    for (const stub of stubs) {
      if (opts.omitQuarantined && isQuarantined(stub.frontmatter)) continue;
      if (await resolveRemainder(stub) === row.slug) out.push({ slug: stub.slug, title: stub.title ?? stub.slug, reason: 'title_prefix' });
    }
    return out;
  } catch {
    return [];
  }
}