Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.6 KB
Raw Blame
/**
 * Zero-LLM fact subject inference (#5836).
 *
 * A fact saved without an entity is invisible to everything that groups facts
 * by entity: the `## Facts` fence, entity-scoped recall and the System One
 * conflict sweep. This module names the entity a fact is about using identity
 * evidence only, so the write paths (remember, the facts backstop) and the
 * `gbrain facts relink` repair share one rule:
 *
 *   - page: the fact came from a live fact-entity page (the page being written,
 *     or a recorded page provenance for relink), and the text names no other
 *     entity.
 *   - mention: the text names exactly one live fact-entity page by exact slug,
 *     unique slug basename or unique alias (relink also accepts the same-name
 *     trigram arm), and no other real name competes with it.
 *
 * A competing name vetoes the link even when it has no page ("Northstar
 * Example copied Acme Example's pricing" names two companies; only one has a
 * page, so the subject is unknown, not Acme). Bare first names are never
 * guessed. Every lookup is source-scoped; `excludePrivate` keeps a remote
 * caller from inferring (or detecting) pages it cannot read.
 */

import type { BrainEngine } from '../engine.ts';
import { extractCandidates, isCommonCapitalizedWord } from '../context/entity-salience.ts';
import { isFactEntityPage, resolveStrictEntityReference, type StrictResolution } from '../entities/resolve.ts';
import { remoteReadFloorSql } from '../search/private-visibility.ts';
import { PAGE_EXTRACTION_SOURCE_LIST } from './gone-page-facts.ts';

export type InferredVia = 'page' | 'mention';
export type InferMissReason = 'ambiguous' | 'unverified_match' | 'no_mention' | 'no_page';
/** A miss carries the distinct entities the text did resolve to, so a later tier can stay within them. */
export type InferResult = { slug: string; via: InferredVia } | { slug: null; reason: InferMissReason; resolved: string[] };

export interface InferSubjectInput {
  fact: string;
  /** A trusted page the fact came from: the page being written, or relink's recorded page provenance. */
  pageSlug?: string | null;
  /** `write` (remember, backstop) accepts identity arms only; `relink` also accepts the same-name trigram arm. */
  mode: 'write' | 'relink';
  /** Remote callers: private pages never resolve and never count toward uniqueness. */
  excludePrivate?: boolean;
}

/** The note separator every fact context annotation uses ("<page slug> — <note>"). */
export const CONTEXT_NOTE_SEPARATOR = ' — ';

/** Append a provenance note to a fact context cell, keeping any page slug prefix parseable. */
export function appendContextNote(context: string | null | undefined, note: string): string {
  return context ? `${context}${CONTEXT_NOTE_SEPARATOR}${note}` : note;
}

/** The context cell with every appended note removed (the original page slug or free text). */
export function contextHead(context: string | null | undefined): string | null {
  if (!context) return null;
  const head = context.split(CONTEXT_NOTE_SEPARATOR, 1)[0]!.trim();
  return head || null;
}

const PAGE_EXTRACTION_SOURCES = new Set<string>(PAGE_EXTRACTION_SOURCE_LIST);

/**
 * The page a stored fact was extracted from, when its row records one: a
 * page-extraction source and a context head that is a path-shaped slug.
 * Liveness and entity type are checked by inferFactSubject. Free-text
 * provenance (remember's "chat 2026-06-12") is never page provenance.
 */
export function recordedPageSlug(context: string | null | undefined, source: string | null | undefined): string | null {
  if (!source || !PAGE_EXTRACTION_SOURCES.has(source)) return null;
  const head = contextHead(context);
  return head && head.includes('/') && !/\s/.test(head) ? head : null;
}

/** `facts.entity_inference` off values disable write-time inference (relink is unaffected). */
export async function isEntityInferenceEnabled(engine: BrainEngine): Promise<boolean> {
  const raw = await engine.getConfig('facts.entity_inference');
  return !/^(off|false|0|no|disabled)$/i.test((raw ?? '').trim());
}

/**
 * Capitalized role and business terms that are not names, so they never veto
 * ("Acme Example hired a CFO"). Real acronym names (a company called IBM) are
 * not here and still compete.
 */
const ROLE_AND_TERM_TOKENS = new Set([
  'ceo', 'cfo', 'cto', 'coo', 'cmo', 'cpo', 'cro', 'vp', 'svp', 'evp', 'gm', 'pm', 'hr', 'qa', 'ops',
  'api', 'sdk', 'ai', 'ml', 'mvp', 'kpi', 'okr', 'okrs', 'arr', 'mrr', 'ipo', 'loi', 'nda', 'saas', 'b2b', 'b2c',
  'pr', 'ui', 'ux', 'q1', 'q2', 'q3', 'q4', 'h1', 'h2', 'fy', 'eod', 'eow', 'asap', 'faq', 'tbd', 'n/a',
]);

/**
 * Words that commonly open a note or memory line without naming anyone. Only
 * these may be ignored at the start of a sentence; any other unresolved
 * capitalized opener ("Blake joined Acme Example") is treated as a name that
 * competes with the match.
 */
const SENTENCE_OPENERS = new Set([
  'met', 'meeting', 'talked', 'spoke', 'called', 'emailed', 'texted', 'messaged', 'asked', 'told', 'said', 'says', 'heard',
  'raised', 'closed', 'signed', 'hired', 'fired', 'lost', 'won', 'launched', 'shipped', 'released', 'announced', 'opened',
  'moved', 'booked', 'bought', 'sold', 'sent', 'paid', 'got', 'had', 'has', 'have', 'went', 'came', 'saw', 'ate', 'ran', 'slept',
  'started', 'finished', 'stopped', 'decided', 'agreed', 'declined', 'approved', 'rejected', 'scheduled', 'cancelled', 'canceled',
  'need', 'needs', 'want', 'wants', 'prefer', 'prefers', 'likes', 'loves', 'hates', 'dislikes', 'thinks', 'believes', 'plans',
  'remember', 'remind', 'reminder', 'note', 'todo', 'follow', 'followup', 'introduced', 'intro', 'invested', 'joined', 'left',
  'currently', 'recently', 'previously', 'usually', 'always', 'never', 'often', 'sometimes', 'probably', 'apparently',
  'not', 'no', 'yes', 'after', 'before', 'during', 'since', 'until', 'while', 'per', 'via', 're', 'fyi', 'update', 'updated',
  'lunch', 'dinner', 'breakfast', 'coffee', 'drinks', 'call', 'sync', 'standup', 'interview', 'demo', 'pitch', 'board',
  'favorite', 'favourite', 'birthday', 'anniversary', 'allergic', 'vegetarian', 'vegan', 'lives', 'lived', 'works', 'worked',
  'captured', 'watched', 'reviewed', 'logged',
]);

/**
 * #7405: record-label openers ("Invoice total ...", "Work session ...", "Notes from ..."). Like SENTENCE_OPENERS they are no name evidence
 * when they open a sentence and resolve to no page, but they are never shed from a candidate, so "Work Example" stays a name.
 */
const LABEL_OPENERS = new Set(['work', 'invoice', 'invoiced', 'billed', 'receipt', 'payment', 'notes', 'capture', 'log', 'review', 'watch']);

/** #7827: the speaker labels the fact extractor writes ("User accepted ...", "Assistant recommended ...", extract.ts ATTRIBUTION_BLOCK). */
const ATTRIBUTION_LABELS = new Set(['user', 'assistant']);

/** #7405: ISO 4217 codes; one counts as a unit (not a name) only where every use sits next to an amount ("CHF 80", "80 CHF"). */
const CURRENCY_CODES = new Set(Intl.supportedValuesOf('currency'));

/**
 * Slugs written verbatim in the fact text ("people/alice-example owns the checklist", "people/例子").
 * Segments use the lowercase page-slug letters the strict resolver's exact arm accepts (combining
 * marks are not among them, so a marked literal is never a literal). A literal glued to further
 * letters or marks on either side is not a literal, so "people/alice-example未知" never resolves to
 * its ASCII prefix.
 */
const SLUG_SEG = '[\\p{Ll}\\p{Lm}\\p{Lo}\\p{N}][\\p{Ll}\\p{Lm}\\p{Lo}\\p{N}_-]*';
const SLUG_EDGE = '[\\p{L}\\p{M}\\p{N}_/-]';
const SLUG_IN_TEXT_RE = new RegExp(`(?<!${SLUG_EDGE})${SLUG_SEG}(?:/${SLUG_SEG})+(?!${SLUG_EDGE})`, 'gu');

/** Two distinct entities already make the subject unknown; more resolution is wasted work. */
const DISTINCT_ENTITY_LIMIT = 2;

/**
 * #7827: a run of capitalised and digit-led tokens ("Acme 42", "42 Acme"). extractCandidates keeps only the capitalised
 * words of such a name, so inference tries the whole run as well; it counts only when it resolves to a page.
 */
const NAME_TOKEN = "(?:\\p{Lu}[\\p{L}\\p{N}'’-]*|\\p{N}[\\p{L}\\p{N}'’-]*)";
const DIGIT_NAME_RUN_RE = new RegExp(`(?<![\\p{L}\\p{N}'’-])${NAME_TOKEN}(?:\\s+${NAME_TOKEN}){1,3}(?![\\p{L}\\p{N}'’-])`, 'gu');

export async function inferFactSubject(engine: BrainEngine, sourceId: string, input: InferSubjectInput): Promise<InferResult> {
  const memo = new Map<string, StrictResolution>();
  const resolve = async (query: string): Promise<StrictResolution> => {
    const key = query.toLowerCase();
    let r = memo.get(key);
    if (!r) {
      r = await resolveStrictEntityReference(engine, sourceId, query,
        { sameName: input.mode === 'relink', excludePrivate: input.excludePrivate });
      memo.set(key, r);
    }
    return r;
  };
  // A digit-led name that resolves replaces the capitalised words inside it, which alone name no page.
  const digitNames: Array<{ query: string; start: number; end: number }> = [];
  for (const m of input.fact.matchAll(DIGIT_NAME_RUN_RE)) {
    const tokens = m[0].split(/\s+/);
    if (!tokens.some(t => /^\p{N}/u.test(t)) || !tokens.some(t => /^\p{Lu}/u.test(t))) continue;
    const query = (SENTENCE_OPENERS.has(tokens[0]!.toLowerCase()) ? tokens.slice(1) : tokens).join(' ');
    if ((await resolve(query)).slug !== null) digitNames.push({ query, start: m.index, end: m.index + m[0].length });
  }
  const insideDigitName = (query: string) => {
    const uses = referenceUses(input.fact, query);
    return uses.length > 0 && uses.every(at => digitNames.some(d => at >= d.start && at + query.length <= d.end));
  };
  const candidates: Array<{ query: string; sentenceStart?: true }> = [
    ...[...new Set(input.fact.match(SLUG_IN_TEXT_RE) ?? [])].map(query => ({ query })),
    ...digitNames.map(({ query }) => ({ query })),
    ...extractCandidates(input.fact).filter(c => !c.weak).map(shedOpener).filter(c => !insideDigitName(c.query)),
  ];
  const resolved = new Set<string>();
  const subjects = new Set<string>();
  const misses: Array<Exclude<StrictResolution, { slug: string }>['miss']> = [];
  let vetoed = false;
  for (const candidate of candidates) {
    const r = await resolve(candidate.query);
    if (r.slug !== null) {
      resolved.add(r.slug);
      if (!onlyExampleUses(input.fact, candidate.query)) subjects.add(r.slug);
      if (resolved.size >= DISTINCT_ENTITY_LIMIT) return { slug: null, reason: 'ambiguous', resolved: [...resolved] };
      continue;
    }
    misses.push(r.miss);
    // A name that is not an entity page (a meeting title) does not compete. A
    // capitalized sentence opener ("Met", "Raised") or a currency code next to
    // an amount with no page is no name evidence; anything else unresolved is
    // a real competing reference.
    if (r.miss === 'not_entity') continue;
    if (r.miss === 'no_page' && (isNonName(candidate.query) || isAmountUnit(input.fact, candidate.query)
      || (candidate.sentenceStart && (SENTENCE_OPENERS.has(candidate.query.toLowerCase()) || LABEL_OPENERS.has(candidate.query.toLowerCase()))))) continue;
    vetoed = true;
  }

  const page = input.pageSlug ? await liveFactEntityPage(engine, sourceId, input.pageSlug, input.excludePrivate) : null;
  if (page) {
    if (vetoed || (resolved.size === 1 && !resolved.has(page))) return { slug: null, reason: 'ambiguous', resolved: [...resolved] };
    return { slug: page, via: 'page' };
  }
  if (subjects.size === 1 && !vetoed) return { slug: [...subjects][0]!, via: 'mention' };
  const miss = (reason: InferMissReason): InferResult => ({ slug: null, reason, resolved: [...resolved] });
  if (resolved.size > 0 || misses.includes('ambiguous')) return miss('ambiguous');
  if (misses.includes('unverified')) return miss('unverified_match');
  if (misses.some(m => m === 'no_page')) return miss(vetoed ? 'no_page' : 'no_mention');
  return miss('no_mention');
}

/** "Joined Acme Example" glues the opener into the name run; resolve the name without it. */
function shedOpener<T extends { query: string }>(c: T): T {
  const [first, ...rest] = c.query.split(/\s+/);
  return rest.length && SENTENCE_OPENERS.has(first!.toLowerCase()) ? { ...c, query: rest.join(' ') } : c;
}

function isNonName(query: string): boolean {
  if (/\s/.test(query)) return false;
  return isCommonCapitalizedWord(query) || ROLE_AND_TERM_TOKENS.has(query.toLowerCase()) || ATTRIBUTION_LABELS.has(query.toLowerCase());
}

const WORD_CHAR = /[\p{L}\p{N}_/-]/u;
/** The start offsets of every whole-word use of `query` in the fact, case-insensitive. */
function referenceUses(fact: string, query: string): number[] {
  const haystack = fact.toLowerCase(), needle = query.toLowerCase(), starts: number[] = [];
  if (!needle || haystack.length !== fact.length) return starts;
  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + 1)) {
    if (!WORD_CHAR.test(fact.charAt(at - 1)) && !WORD_CHAR.test(fact.charAt(at + needle.length))) starts.push(at);
  }
  return starts;
}

/**
 * #7405: a currency code is a unit only when every use is next to an amount ("CHF 80", "80 CHF"), never a date or time
 * ("2025-01-01 CHF"); resolution runs first, so a page named CHF still competes.
 */
const AMOUNT_AFTER = /^\s*\d[\d,.']*(?![\d/:-])/u;
const AMOUNT_BEFORE = /(?:^|[^\d,.'/:-])\d[\d,.']*\s*$/u;
function isAmountUnit(fact: string, query: string): boolean {
  if (!CURRENCY_CODES.has(query)) return false;
  const uses = referenceUses(fact, query);
  return uses.length > 0 && uses.every(at => AMOUNT_AFTER.test(fact.slice(at + query.length)) || AMOUNT_BEFORE.test(fact.slice(0, at)));
}

/**
 * #7405: an entity named only as an example ("... including Automation Example notes", "for example, Automation Example")
 * resolves, but cannot be the subject. The example phrase must introduce the mention: only other names of the same list
 * may sit between them, so "notes including weekly items belong to Alice Example" keeps Alice.
 */
const EXAMPLE_LIST_LEAD = /(?:^|[^\p{L}])(?:[Ii]ncluding|[Ss]uch as|[Ff]or example|[Ff]or instance|[Ee]\.g\.)[,:]?\s+(?:\p{Lu}[\p{L}\p{N}'’./-]*(?:\s+\p{Lu}[\p{L}\p{N}'’./-]*)*\s*(?:,\s*(?:and\s+|or\s+)?|\s+(?:and|or)\s+))*$/u;
function onlyExampleUses(fact: string, query: string): boolean {
  const uses = referenceUses(fact, query);
  return uses.length > 0 && uses.every(at => EXAMPLE_LIST_LEAD.test(fact.slice(0, at)));
}

async function liveFactEntityPage(engine: BrainEngine, sourceId: string, slug: string, excludePrivate?: boolean): Promise<string | null> {
  const privacy = excludePrivate ? `AND ${remoteReadFloorSql('p')}` : '';
  const [row] = await engine.executeRaw<{ slug: string; type: string | null }>(
    `SELECT p.slug, p.type FROM pages p WHERE p.source_id = $1 AND p.slug = $2 AND p.deleted_at IS NULL ${privacy} LIMIT 1`,
    [sourceId, slug],
  );
  return row && isFactEntityPage(row.slug, row.type) ? row.slug : null;
}