@littlebigbrain/create 0.1.0 → 0.3.0

package/templates/link/README.md

@@ -0,0 +1,203 @@
+# link
+
+Connects the mentions of one thing across the records of a graph. A
+contact, a lead, a deal and a note can each name one person in a different
+way: `Mira Tannenholt-Ruiz`, `Mira Ruiz`, `M. Tannenholt`, `Mimi T.`. The
+workflow groups those mentions into one `LinkedThing`. The links are
+references across the graph, and later checks compare what each source says
+about the thing.
+
+This is phase L1 of the design
+[general linking](../../../docs/architecture/general-linking.md): identities
+on records. Documents (pages) come in phase L2.
+
+## What it writes
+
+| Term | Kind | Holds |
+| --- | --- | --- |
+| `Mention` | class | `span`, `role` (`self` or `refers`), `kind`, `field`, `offset`, `length`, `block_key` (several), `window` (the sentence of a span of text); the links and constraints `linked_to`, `must_link` and `cannot_link` |
+| `LinkedThing` | class | its name (the anchor's name), `kind`, `anchor_key`, `alias` (several: the other names its members use) |
+| `MENTIONED_IN` | relation, mention to record | the record that holds the mention |
+| `SAME_THING_AS` | relation, mention to mention | a decided or accepted pair, with its confidence and its evidence (the sentence and the record's name) |
+| `REFERS_TO` | relation, mention to `LinkedThing` | the thing the mention is in |
+| `HAS_RECORD` | relation, `LinkedThing` to record | the records whose names and keys are in the thing |
+| `MERGED_INTO` | relation, `LinkedThing` to `LinkedThing` | where an old thing is now: a thing whose anchor changed, or that merged |
+| `SAME_AS` | relation, record to record | two records of one thing: a person writes it when they accept an identity |
+
+A record's own names and keys are `self` mentions. Each record anchors a
+thing. A span in a text field that names something is a `refers` mention.
+
+## How it links
+
+1. **Mentions.** A `name` or `key:*` field gives one `self` mention per
+   value. A `text` field gives `refers` mentions: first the gazetteer pass,
+   which keeps each span whose name or key a mention of the graph has; then
+   the spans written like a name or a key (`M. Tannenholt`, an email).
+2. **Block keys.** Each mention gets normal forms of its name or key as
+   graph facts (`block_key`): the sorted name, the initials forms, the name
+   parts and their sound, an email, a web address, a code. A key that more
+   than 200 mentions hold is a stop key and finds nothing.
+3. **Candidates.** The mentions that share a key, and the things of the
+   records within two hops (the deal that a note is about). At most 30, the
+   ones with a strong key first.
+4. **Decision.** See the next section.
+5. **Things.** The things identity groups the decided pairs. A person's
+   decisions are constraints. Two records are never one thing until a person
+   accepts their identity.
+
+The thing's IRI is a hash of the graph and its anchor's key. The anchor is a
+record's name first, then any other mention. So the same inputs give the
+same IRIs. A thing whose anchor changes keeps one statement, `MERGED_INTO`
+the thing that holds its members now.
+
+## Model reads of record values
+
+`modelsReadRecords` is off by default (general linking 12, decision 1).
+
+- **Off.** No model reads a record value. A strong key (an email, a web
+  address, a phone number, a handle, a code) links at confidence 1. Every
+  other candidate goes to a person, grouped by thing.
+- **On.** The decision model reads the names, keys and context fields of
+  the records. It answers a kind question and a names question per mention,
+  and a same-record question per pair of records. A link at or above `gate`
+  (0.8) is written; a link below it goes to a person. The reasoning model
+  reads only the text fields that opt in: `{ "role": "text", "extract": true }`
+  (decision 8).
+
+Every model call has an effect id made from its request. The same question
+gets its first answer from the effect cache, at no cost.
+
+## Review items
+
+| Item | One per | Accept writes |
+| --- | --- | --- |
+| Link (`starter:<name>:link:…`) | Thing | The kept `SAME_THING_AS` rows. A row left out keeps its mention apart from the thing. |
+| No link (`starter:<name>:nolink:…`) | Thing of the best candidate | The kept rows: the model chose no thing, and a person disagrees. |
+| Identity (`starter:<name>:identity:…`) | Group of 2 to 10 records | `SAME_AS` between the records, and `SAME_THING_AS` between their names. |
+
+A person always accepts an identity (decision 2). The `identityGate` (0.99)
+only orders and groups the identity items (`mapping.identity.above_gate`).
+Each item has the origin `starter:<name>` with the label `link`, so the
+inbox labels and patterns of the producer `link` read it.
+
+A person's decisions feed back. A kept row is a must-link. A row left out,
+or a dismissed item, is a cannot-link. No model answer joins what a
+cannot-link keeps apart.
+
+## Settings
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `name` | `link` | The named workflows are `<name>-<class>` and `<name>-reviews`; the things identity is `<name>-things` |
+| `fields` | the samples' CRM | The role of each field of each class (below) |
+| `gate` | 0.8 | A link at or above it is written, with model reads on |
+| `identityGate` | 0.99 | Orders and groups the identity items |
+| `modelsReadRecords` | `false` | Whether models may read record values |
+| `shards` | 4 | Source shards of each named workflow |
+| `sourcesPerTurn` | 16 | Records per message |
+| `textPerTurn` | 8,000 | Characters of text per turn; the rest continues in a new turn |
+
+| Field role | Gives |
+| --- | --- |
+| `name` | One `self` mention per value |
+| `name:given`, `name:family` | One `self` mention of the two joined (`first_name+last_name`) |
+| `key:email`, `key:phone`, `key:web`, `key:handle`, `key:code` | One `self` mention per value, with a strong key |
+| `text`, `{ "role": "text", "extract": true }` | `refers` mentions found in the text |
+| `context` | No mention; read for the decisions |
+
+A field named `name` (or `label`) is the record's display name, which the
+published graph holds as `rdfs:label`; the workflow watches it as `label`.
+Any other field is a property of the record.
+
+## Run it
+
+```sh
+npm create @littlebigbrain -- --template link my-links
+cd my-links && npm install
+npm test                                           # the workflow on the samples, with mock models
+LBB_GRAPH=try-link npm run try                     # the samples on a graph of your stack
+LBB_GRAPH=try-link npm start                       # serve it
+LBB_GRAPH=try-link npm run grade -- --gold samples/gold.json
+LBB_GRAPH=crm npm run setup && npm start           # your graph
+```
+
+`npm run setup` creates the classes and properties, one named workflow per
+class of the settings, the named workflow that watches accepted items, and
+the things identity. It is safe to repeat. The workflow is for a records
+graph. Do not run it on a graph where `documents.link` runs: both write
+`MENTIONED_IN` and `REFERS_TO`.
+
+## Grade a run
+
+`npm run grade` (`src/grade-run.ts`) prints the metrics of general linking
+9.2: link precision at the gate and its 95% Wilson interval, pairwise
+precision and recall over things, cluster purity and completeness
+(B-cubed), the review share, and identity precision and recall.
+
+```sh
+LBB_URL=... LBB_API_KEY=... LBB_GRAPH=crm npm run grade -- --gold .lbb-datasets/link-eval/gold.json --save run.json
+npm run grade -- --gold .lbb-datasets/link-eval/gold.json --run run.json
+```
+
+The gold file (`lbb.link.gold.v1`) lists the groups. Each group is one real
+thing, with the mentions that name it:
+
+```json
+{
+  "format": "lbb.link.gold.v1",
+  "complete": false,
+  "records": { "contact-1": "https://littlebigbrain.com/e/…" },
+  "groups": [
+    { "id": "mira", "kind": "person", "mentions": [
+      { "record": "contact-1", "field": "name", "span": "Mira Tannenholt-Ruiz" },
+      { "record": "https://littlebigbrain.com/e/…", "field": "body", "span": "Mimi T.", "occurrence": 0 }
+    ] }
+  ]
+}
+```
+
+A mention names its record (an IRI, or a name of `records`), its field
+(`first_name+last_name` for a joined name), its span as the field writes it,
+and which equal span of the field it is (`occurrence`, default 0). With
+`complete: true`, a mention that the gold does not list is a thing of its
+own. Without it, a link to such a mention counts apart as unjudged. Keep a
+gold file of real records out of git, under `.lbb-datasets/`.
+
+## The samples
+
+`samples/records.json` is an invented CRM: 7 organizations, 12 contacts, 5
+leads, 7 deals and 11 notes. Every name, company and address is invented.
+The names vary: a nickname (`Bob` for `Robert`), initials (`M. Tannenholt`,
+`F. Okafor`), accents and transliterations (`Jürgen`, `Juergen`, `Jurgen`;
+`Søren`, `Soren`; `Zoë`, `Zoe`), name order (`Wren, Tobias`), a typo
+(`Ramaswamey`), a person known only by an email, a surname that two people
+share (`Okafor`), two people of one name at two organizations (`Alex
+Brandt`), and company domains. `samples/gold.json` holds the gold groups.
+
+## How the template differs from the design
+
+- A named workflow takes one watch trigger in this release, so each class is
+  a named workflow of its own. All of them run the workflow type `link`.
+- The candidates by the name index and by meaning wait for work tokens that
+  reach those routes (N3). The keys and the neighbours find the candidates.
+- A source turn sends its decided pairs in messages of at most 24,000
+  bytes; a larger message goes in parts (`.1`, `.2`, …) until blobs (G11).
+- The things identity is an engine identity that `npm run setup` creates.
+  It reads the review items it filed to learn a person's decisions.
+
+## Files
+
+| File | Holds |
+| --- | --- |
+| `workflow.ts` | The workflow, the named workflows (`workflows()`), the ontology, the ports (`linkPorts()`) and `setup()` |
+| `settings.ts` | The settings and the names of the parts, and the decided message |
+| `names.ts` | Normal forms and block keys |
+| `candidates.ts` | The candidate reads, the scoring and the bounds |
+| `decide.ts` | The questions, the packing, the link rule and the rules without models |
+| `things.ts` | The grouping with constraints, anchors, IRIs, merges and splits |
+| `sources/records.ts` | Field roles, and the mentions of record fields |
+| `source-turn.ts`, `things-turn.ts` | The turns of a source shard and of the things identity |
+| `items.ts`, `reads.ts` | The review items, and the reads of the graph |
+| `grade.ts`, `grade-run.ts` | The grading, and its command |
+| `fixture.ts` | The test support: the graph in memory, mock models and ports, a reviewer that follows a gold file |
+| `setup.ts`, `worker.ts`, `try.ts`, `samples.ts` | The commands |

package/templates/link/candidates.ts

@@ -0,0 +1,432 @@
+// The candidates of a mention (general linking 4.3) and their bounds (4.4).
+// The queries are built here and run by the workflow; the scoring is pure.
+//
+// Block keys are graph facts: `block_key` values on each `Mention`. One read
+// counts the mentions per key, so a key that more than 200 mentions hold is
+// a stop key and finds nothing. A second read returns the mentions of the
+// other keys, with the thing each one belongs to. The neighbours are the
+// things of the records within two hops of the mention's source.
+import { KEY_KINDS, keyKind, keyWeight, nameSimilarity, type KeyKind } from "./names.js";
+
+/** The bounds of the candidate sources and of a mention (4.4). */
+export const BOUNDS = {
+  /** Candidates with an equal strong key, per mention. */
+  strong: 10,
+  /** Candidates that share a medium or weak key, per mention. */
+  other: 10,
+  /** Candidates among the neighbours, per mention. */
+  neighbours: 10,
+  /** Records the neighbours read reads, per source turn. */
+  neighbourRecords: 50,
+  /** Hops from a mention's source to its neighbours. */
+  hops: 2,
+  /** Candidates of one mention, from every source. */
+  total: 30,
+  /** A key that more mentions hold is a stop key. */
+  stopKey: 200,
+  /** Mentions one text value gives. */
+  textMentions: 100,
+  /** Rows one key read returns. */
+  keyRows: 4_000,
+  /** Keys one read asks about. */
+  keysPerRead: 500,
+};
+
+/** The lowest score a candidate found by a medium or weak key keeps. */
+export const MIN_SCORE = 0.55;
+/** The lowest name similarity a neighbour keeps. */
+export const MIN_NEIGHBOUR_SIMILARITY = 0.6;
+
+export const P =
+  "PREFIX p: <https://littlebigbrain.com/p/>\nPREFIX r: <https://littlebigbrain.com/r/>\nPREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>\n";
+/** A record's display name, and an entity's name, in the published RDF. */
+export const RDFS_LABEL = "http://www.w3.org/2000/01/rdf-schema#label";
+export const RELATION_IRI = "https://littlebigbrain.com/r/";
+export const PROPERTY_IRI = "https://littlebigbrain.com/p/";
+export const CLASS_IRI = "https://littlebigbrain.com/class/";
+
+/** The local part of a class, property or relation IRI, normalized and escaped as the server mints it. */
+export function iriSegment(name: string): string {
+  const normalized = name.trim().toLowerCase().split(/\s+/).join(" ");
+  let out = "";
+  for (const byte of new TextEncoder().encode(normalized)) {
+    const char = String.fromCharCode(byte);
+    out += /[A-Za-z0-9\-_.~]/.test(char)
+      ? char
+      : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+  }
+  return out;
+}
+
+export const classIri = (name: string) => `${CLASS_IRI}${iriSegment(name)}`;
+export const propertyIri = (name: string) => `${PROPERTY_IRI}${iriSegment(name)}`;
+export const relationIri = (name: string) => `${RELATION_IRI}${iriSegment(name)}`;
+
+/** IRIs as a VALUES list; an IRI a query cannot hold is left out. */
+export const iris = (list: string[]) =>
+  list
+    .filter((iri) => /^[^\s<>"{}|\\^`]+$/.test(iri))
+    .map((iri) => `<${iri}>`)
+    .join(" ");
+
+/** Strings as a VALUES list of literals. */
+export const literals = (list: string[]) => list.map((s) => JSON.stringify(s)).join(" ");
+
+/** The relations of the link vocabulary: a neighbour is never found through them. */
+export const LINK_RELATIONS = [
+  "mentioned_in",
+  "refers_to",
+  "same_thing_as",
+  "has_record",
+  "merged_into",
+];
+
+// ---- the reads ------------------------------------------------------------------
+
+/** How many mentions hold each key. */
+export function keyCountsQuery(keys: string[]): string {
+  return `# link: key counts\n${P}SELECT ?key (COUNT(?m) AS ?n) WHERE {
+  VALUES ?key { ${literals(keys)} }
+  ?m p:block_key ?key .
+} GROUP BY ?key`;
+}
+
+export function parseCounts(rows: Record<string, string>[]): Map<string, number> {
+  return new Map(rows.map((r) => [r.key!, Number(r.n ?? 0)]));
+}
+
+/** The keys that more than `limit` mentions hold. */
+export function stopKeys(counts: Map<string, number>, limit = BOUNDS.stopKey): string[] {
+  return [...counts]
+    .filter(([, n]) => n > limit)
+    .map(([key]) => key)
+    .sort();
+}
+
+/** The mentions that hold the keys, with what they belong to. */
+export function keyHitsQuery(keys: string[]): string {
+  return `# link: keys\n${P}SELECT ?key ?m ?role ?span ?src ?kind ?window ?thing ?label WHERE {
+  VALUES ?key { ${literals(keys)} }
+  ?m p:block_key ?key ; p:role ?role ; p:span ?span ; r:mentioned_in ?src .
+  OPTIONAL { ?m p:kind ?kind } OPTIONAL { ?m p:window ?window }
+  OPTIONAL { ?m r:refers_to ?thing . OPTIONAL { ?thing rdfs:label ?label } }
+} LIMIT ${BOUNDS.keyRows}`;
+}
+
+/** A mention that holds a looked-up key. */
+export interface KeyHit {
+  key: string;
+  mention: string;
+  role: string;
+  span: string;
+  source: string;
+  kind: string | null;
+  window: string | null;
+  thing: string | null;
+  label: string | null;
+}
+
+export function parseHits(rows: Record<string, string>[]): KeyHit[] {
+  return rows
+    .filter((r) => r.key && r.m && r.src)
+    .map((r) => ({
+      key: r.key!,
+      mention: r.m!,
+      role: r.role ?? "refers",
+      span: r.span ?? "",
+      source: r.src!,
+      kind: r.kind ?? null,
+      window: r.window ?? null,
+      thing: r.thing ?? null,
+      label: r.label ?? null,
+    }));
+}
+
+/** One hop of relations from records, both ways, without the link vocabulary. */
+export function hopQuery(records: string[]): string {
+  const skip = LINK_RELATIONS.map((r) => `r:${r}`).join(", ");
+  return `# link: hop\n${P}SELECT ?a ?r ?b ?dir ?name ?class WHERE {
+  VALUES ?a { ${iris(records)} }
+  { ?a ?r ?b BIND("out" AS ?dir) } UNION { ?b ?r ?a BIND("in" AS ?dir) }
+  FILTER(STRSTARTS(STR(?r), "${RELATION_IRI}") && ?r NOT IN (${skip}))
+  OPTIONAL { ?b rdfs:label ?name } OPTIONAL { ?b a ?class }
+} LIMIT 500`;
+}
+
+/** A relation from a record to a neighbour. */
+export interface Hop {
+  from: string;
+  relation: string;
+  to: string;
+  dir: "out" | "in";
+  name: string;
+  class: string;
+}
+
+const local = (iri: string, base: string) =>
+  iri.startsWith(base) ? decodeURIComponent(iri.slice(base.length)) : iri;
+
+export function parseHops(rows: Record<string, string>[]): Hop[] {
+  const seen = new Set<string>();
+  const out: Hop[] = [];
+  for (const r of rows) {
+    if (!r.a || !r.r || !r.b) continue;
+    const key = `${r.a}\u0000${r.r}\u0000${r.b}\u0000${r.dir}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({
+      from: r.a,
+      relation: local(r.r, RELATION_IRI).toUpperCase(),
+      to: r.b,
+      dir: r.dir === "in" ? "in" : "out",
+      name: r.name ?? "",
+      class: r.class ? local(r.class, CLASS_IRI) : "",
+    });
+  }
+  return out;
+}
+
+/** The mentions of the neighbour records, with the things they belong to. */
+export function neighbourMentionsQuery(records: string[]): string {
+  return `# link: neighbour mentions\n${P}SELECT ?n ?m ?role ?span ?thing ?label WHERE {
+  VALUES ?n { ${iris(records)} }
+  ?m r:mentioned_in ?n ; p:role ?role ; p:span ?span .
+  OPTIONAL { ?m r:refers_to ?thing . OPTIONAL { ?thing rdfs:label ?label } }
+} LIMIT 2000`;
+}
+
+/** A mention of a neighbour record, and how the neighbour is reached from the source. */
+export interface NeighbourMention {
+  record: string;
+  mention: string;
+  role: string;
+  span: string;
+  thing: string | null;
+  label: string | null;
+}
+
+export function parseNeighbourMentions(rows: Record<string, string>[]): NeighbourMention[] {
+  return rows
+    .filter((r) => r.n && r.m)
+    .map((r) => ({
+      record: r.n!,
+      mention: r.m!,
+      role: r.role ?? "refers",
+      span: r.span ?? "",
+      thing: r.thing ?? null,
+      label: r.label ?? null,
+    }));
+}
+
+/**
+ * The records within `hops` of each source, and how each is reached: a
+ * breadth-first walk over `hops` (one read per hop), at most `limit`
+ * records. A neighbour's path reads `ABOUT → Deal "…" → INVOLVES`.
+ */
+export function neighbourPaths(
+  sources: string[],
+  hopsByLevel: Hop[][],
+  limit = BOUNDS.neighbourRecords,
+): Map<string, Map<string, string>> {
+  const out = new Map<string, Map<string, string>>();
+  let total = 0;
+  for (const source of sources) {
+    const reached = new Map<string, string>([[source, ""]]);
+    let frontier = [source];
+    for (const level of hopsByLevel) {
+      const next: string[] = [];
+      for (const hop of level) {
+        if (!frontier.includes(hop.from) || reached.has(hop.to) || total >= limit) continue;
+        const before = reached.get(hop.from)!;
+        const step = `${hop.relation}${hop.dir === "in" ? " (from)" : ""} → ${hop.class || "record"} "${hop.name.slice(0, 60)}"`;
+        reached.set(hop.to, before ? `${before} → ${step}` : step);
+        next.push(hop.to);
+        total += 1;
+      }
+      frontier = next;
+    }
+    reached.delete(source);
+    out.set(source, reached);
+  }
+  return out;
+}
+
+// ---- candidates -------------------------------------------------------------------
+
+/** A mention whose candidates are wanted. */
+export interface MentionInput {
+  iri: string;
+  source: string;
+  role: "self" | "refers";
+  span: string;
+  keys: string[];
+  /** Mentions a person keeps apart from this one. */
+  cannot: string[];
+  /** The thing the mention is in now: for a self mention, what it holds is no candidate (it is linked already). */
+  thing?: string | null;
+}
+
+/** One candidate of a mention: a thing, or a lone mention. */
+export interface Candidate {
+  /** The mention a link pairs with: the one that matched, or a member of the neighbour thing. */
+  target: string;
+  /** The thing the target belongs to; null for a lone mention. */
+  thing: string | null;
+  label: string;
+  /** Up to three spans of the candidate's members that the reads returned. */
+  spans: string[];
+  /** The records whose self mentions are among those members. */
+  records: string[];
+  score: number;
+  /** The key kind that found it, or `neighbour`. */
+  found: KeyKind | "neighbour";
+  strong: boolean;
+  /** For a neighbour: how it is reached from the mention's source. */
+  via?: string;
+  /** For a lone mention of text: its sentence. */
+  window?: string;
+}
+
+/** Group key of a hit: its thing, else the mention itself. */
+const groupOf = (thing: string | null, mention: string) => thing ?? mention;
+
+/**
+ * The candidates of a mention: the things and lone mentions with an equal
+ * strong key (up to 10), the ones that share a medium or weak key, scored
+ * by the key weights and the name similarity (up to 10), and the things of
+ * the neighbours that are named alike (up to 10); at most 30, the strong
+ * ones first. The mention itself, the other self mentions of its record,
+ * and what a person keeps apart from it are left out.
+ */
+export function candidatesFor(
+  m: MentionInput,
+  hits: KeyHit[],
+  stop: Set<string>,
+  neighbours: { mention: NeighbourMention; via: string }[] = [],
+): Candidate[] {
+  const own = new Set(m.keys.filter((k) => !stop.has(k)));
+  const banned = new Set(m.cannot);
+  const groups = new Map<
+    string,
+    {
+      target: string;
+      thing: string | null;
+      label: string;
+      spans: Set<string>;
+      records: Set<string>;
+      keys: Set<string>;
+      window?: string;
+      via?: string;
+    }
+  >();
+  const entry = (thing: string | null, mention: string, label: string) => {
+    const key = groupOf(thing, mention);
+    let g = groups.get(key);
+    if (!g) {
+      g = { target: mention, thing, label, spans: new Set(), records: new Set(), keys: new Set() };
+      groups.set(key, g);
+    }
+    return g;
+  };
+  const skip = (mention: string, source: string, role: string) =>
+    mention === m.iri ||
+    banned.has(mention) ||
+    (m.role === "self" && role === "self" && source === m.source);
+  for (const hit of hits) {
+    if (!own.has(hit.key) || skip(hit.mention, hit.source, hit.role)) continue;
+    if (hit.thing && (banned.has(hit.thing) || (m.role === "self" && hit.thing === m.thing)))
+      continue;
+    const g = entry(hit.thing, hit.mention, hit.label ?? hit.span);
+    g.keys.add(hit.key);
+    g.spans.add(hit.span);
+    if (hit.role === "self") g.records.add(hit.source);
+    if (!hit.thing && hit.window) g.window = hit.window;
+    // A strong key names its target: the member that holds it.
+    if ([...g.keys].some((k) => keyWeight(k) === "strong") && keyWeight(hit.key) === "strong")
+      g.target = hit.mention;
+  }
+  const scored: Candidate[] = [];
+  for (const g of groups.values()) {
+    const strongKey = [...g.keys].find((k) => keyWeight(k) === "strong");
+    const similarity = Math.max(0, ...[...g.spans].map((s) => nameSimilarity(m.span, s)));
+    const keyScore = Math.min(
+      1,
+      [...g.keys].reduce((sum, k) => sum + KEY_KINDS[keyKind(k)!].value, 0),
+    );
+    const best = [...g.keys].sort(
+      (a, b) => KEY_KINDS[keyKind(b)!].value - KEY_KINDS[keyKind(a)!].value,
+    )[0]!;
+    scored.push({
+      target: g.target,
+      thing: g.thing,
+      label: g.label,
+      spans: [...g.spans].slice(0, 3),
+      records: [...g.records].sort(),
+      score: strongKey ? 1 : round(0.5 * keyScore + 0.5 * similarity),
+      found: keyKind(strongKey ?? best)!,
+      strong: Boolean(strongKey),
+      ...(g.window ? { window: g.window } : {}),
+    });
+  }
+  const strong = scored
+    .filter((c) => c.strong)
+    .sort(byScore)
+    .slice(0, BOUNDS.strong);
+  const other = scored
+    .filter((c) => !c.strong && c.score >= MIN_SCORE)
+    .sort(byScore)
+    .slice(0, BOUNDS.other);
+
+  // The neighbours: the things (and lone mentions) of the records near the source.
+  const near = new Map<string, Candidate>();
+  for (const { mention: n, via } of neighbours) {
+    if (
+      skip(n.mention, n.record, n.role) ||
+      (n.thing && (banned.has(n.thing) || (m.role === "self" && n.thing === m.thing)))
+    )
+      continue;
+    if (n.record === m.source) continue;
+    const key = groupOf(n.thing, n.mention);
+    const similarity = nameSimilarity(m.span, n.span);
+    if (similarity < MIN_NEIGHBOUR_SIMILARITY) continue;
+    const before = near.get(key);
+    const score = round(0.3 + 0.5 * similarity);
+    if (before && before.score >= score) continue;
+    near.set(key, {
+      target: n.mention,
+      thing: n.thing,
+      label: n.label ?? n.span,
+      spans: [n.span],
+      records: n.role === "self" ? [n.record] : [],
+      score,
+      found: "neighbour",
+      strong: false,
+      via: n.role === "self" ? via : `named in ${via}`,
+    });
+  }
+  const out: Candidate[] = [];
+  const taken = new Map<string, Candidate>();
+  for (const c of [...strong, ...other]) {
+    out.push(c);
+    taken.set(groupOf(c.thing, c.target), c);
+  }
+  for (const c of [...near.values()].sort(byScore).slice(0, BOUNDS.neighbours)) {
+    const key = groupOf(c.thing, c.target);
+    const found = taken.get(key);
+    if (found) {
+      // Found by a key and near the source: both count.
+      found.via ??= c.via;
+      if (!found.strong) found.score = round(Math.min(1, found.score + 0.05));
+      continue;
+    }
+    out.push(c);
+  }
+  return [...out.filter((c) => c.strong), ...out.filter((c) => !c.strong).sort(byScore)].slice(
+    0,
+    BOUNDS.total,
+  );
+}
+
+const round = (x: number) => Math.round(x * 1000) / 1000;
+const byScore = (a: Candidate, b: Candidate) =>
+  b.score - a.score || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0);