@littlebigbrain/create 0.1.0 → 0.3.0

package/templates/link/reads.ts

@@ -0,0 +1,302 @@
+// The reads of the link workflow: records, the mentions it wrote, and the
+// things they belong to. Each query starts with a `# link: <name>` line, so
+// the call log and a test's mock can tell them apart.
+import {
+  CLASS_IRI,
+  P,
+  PROPERTY_IRI,
+  RDFS_LABEL,
+  RELATION_IRI,
+  iriSegment,
+  iris,
+  propertyIri,
+} from "./candidates.js";
+import type { SourceRecord } from "./sources/records.js";
+
+/** The properties of a mention that the workflow writes, by name. */
+export const MENTION_FIELDS = [
+  "span",
+  "role",
+  "kind",
+  "field",
+  "offset",
+  "length",
+  "block_key",
+  "window",
+];
+/** The properties of a mention that the things identity writes: its links and a person's constraints. */
+export const LINK_FIELDS = ["linked_to", "must_link", "cannot_link"];
+/** The properties of a thing. */
+export const THING_FIELDS = ["anchor_key", "kind", "alias"];
+
+/** Records one read names, at most. */
+export const PER_READ = 400;
+
+/** A field named `name` or `label` is the record's display name: `rdfs:label`. */
+export const isDisplayName = (field: string) => field === "name" || field === "label";
+/** The predicate of a field: `rdfs:label` for the display name, else the property. */
+export const fieldIri = (field: string) => (isDisplayName(field) ? RDFS_LABEL : propertyIri(field));
+
+/** The values of the fields of records, and their names. */
+export function sourcesQuery(records: string[], fields: string[]): string {
+  const predicates = [...new Set([RDFS_LABEL, ...fields.map(fieldIri)])]
+    .map((iri) => `<${iri}>`)
+    .join(", ");
+  return `# link: sources\n${P}SELECT ?s ?p ?v WHERE {
+  VALUES ?s { ${iris(records)} }
+  ?s ?p ?v FILTER(?p IN (${predicates}))
+}`;
+}
+
+/** The records of a read: each field's values in the order the rows give them. */
+export function parseSources(
+  rows: Record<string, string>[],
+  records: string[],
+  cls: string,
+  fields: string[],
+): Map<string, SourceRecord> {
+  const out = new Map<string, SourceRecord>();
+  const byIri = new Map(fields.map((f) => [fieldIri(f), f]));
+  for (const iri of records) out.set(iri, { iri, class: cls, name: "", values: {} });
+  const found = new Set<string>();
+  for (const r of rows) {
+    const record = out.get(r.s ?? "");
+    if (!record || r.v === undefined) continue;
+    found.add(record.iri);
+    if (r.p === RDFS_LABEL) record.name ||= r.v;
+    const field = byIri.get(r.p ?? "");
+    if (!field) continue;
+    const values = (record.values[field] ??= []);
+    if (!values.includes(r.v)) values.push(r.v);
+  }
+  for (const iri of records) if (!found.has(iri)) out.delete(iri);
+  return out;
+}
+
+/** The mentions the workflow wrote for records, with the thing each is in and its cannot-links. */
+export function sourceMentionsQuery(records: string[]): string {
+  return `# link: source mentions\n${P}SELECT ?s ?m ?thing ?c WHERE {
+  VALUES ?s { ${iris(records)} }
+  ?m r:mentioned_in ?s .
+  OPTIONAL { ?m r:refers_to ?thing } OPTIONAL { ?m p:cannot_link ?c }
+} LIMIT 5000`;
+}
+
+/** Mentions of the workflow whose source is gone: deleting a record retracts the edges to it. */
+export function orphanMentionsQuery(): string {
+  return `# link: orphan mentions\n${P}SELECT ?m ?thing WHERE {
+  ?m a <${CLASS_IRI}mention> .
+  FILTER NOT EXISTS { ?m r:mentioned_in ?any }
+  OPTIONAL { ?m r:refers_to ?thing }
+} LIMIT 900`;
+}
+
+export interface WrittenMention {
+  mention: string;
+  thing: string | null;
+  cannot: string[];
+}
+
+export function parseSourceMentions(rows: Record<string, string>[]): Map<string, WrittenMention[]> {
+  const out = new Map<string, Map<string, WrittenMention>>();
+  for (const r of rows) {
+    if (!r.s || !r.m) continue;
+    const byMention = out.get(r.s) ?? out.set(r.s, new Map()).get(r.s)!;
+    const m = byMention.get(r.m) ?? { mention: r.m, thing: null, cannot: [] };
+    if (r.thing) m.thing = r.thing;
+    if (r.c && !m.cannot.includes(r.c)) m.cannot.push(r.c);
+    byMention.set(r.m, m);
+  }
+  return new Map([...out].map(([s, ms]) => [s, [...ms.values()]]));
+}
+
+/** Rows of one read of the members of things, at most: a larger thing is read in part (the supernode bound). */
+export const MEMBER_ROWS = 5_000;
+
+/** The members of things. */
+export function thingMembersQuery(things: string[]): string {
+  return `# link: thing members\n${P}SELECT ?t ?x WHERE {
+  VALUES ?t { ${iris(things)} }
+  ?x r:refers_to ?t .
+} LIMIT ${MEMBER_ROWS}`;
+}
+
+export function parseThingMembers(rows: Record<string, string>[]): Map<string, Set<string>> {
+  const members = new Map<string, Set<string>>();
+  for (const r of rows) {
+    if (!r.t || !r.x) continue;
+    (members.get(r.t) ?? members.set(r.t, new Set()).get(r.t)!).add(r.x);
+  }
+  return members;
+}
+
+/** The facts of mentions: their properties, their source, their thing and their links with the confidence of each. */
+export function mentionFactsQuery(mentions: string[]): string {
+  const props = ["role", "span", "kind", "field", "window", "block_key", ...LINK_FIELDS]
+    .map((f) => `p:${f}`)
+    .join(", ");
+  return `# link: mention facts\n${P}PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX lbb: <https://littlebigbrain.com/ns#>
+SELECT ?m ?p ?v ?c WHERE {
+  VALUES ?m { ${iris(mentions)} }
+  { ?m ?p ?v FILTER(?p IN (${props}, r:mentioned_in, r:refers_to)) }
+  UNION {
+    ?m r:same_thing_as ?v BIND(r:same_thing_as AS ?p)
+    OPTIONAL { ?st rdf:subject ?m ; rdf:predicate r:same_thing_as ; rdf:object ?v ; lbb:confidence ?c }
+  }
+}`;
+}
+
+/** A mention as the graph holds it. */
+export interface MentionFacts {
+  iri: string;
+  role: "self" | "refers" | "defines";
+  span: string;
+  kind: string;
+  field: string;
+  window: string | null;
+  source: string;
+  thing: string | null;
+  keys: string[];
+  linkedTo: string[];
+  must: string[];
+  cannot: string[];
+  /** Its `SAME_THING_AS` targets, with the confidence of each. */
+  same: { target: string; confidence: number | null }[];
+}
+
+export function parseMentionFacts(rows: Record<string, string>[]): Map<string, MentionFacts> {
+  const out = new Map<string, MentionFacts>();
+  const get = (iri: string) => {
+    let m = out.get(iri);
+    if (!m) {
+      m = {
+        iri,
+        role: "refers",
+        span: "",
+        kind: "",
+        field: "",
+        window: null,
+        source: "",
+        thing: null,
+        keys: [],
+        linkedTo: [],
+        must: [],
+        cannot: [],
+        same: [],
+      };
+      out.set(iri, m);
+    }
+    return m;
+  };
+  const add = (list: string[], v: string) => {
+    if (!list.includes(v)) list.push(v);
+  };
+  for (const r of rows) {
+    if (!r.m || !r.p || r.v === undefined) continue;
+    const m = get(r.m);
+    const p = r.p.startsWith(PROPERTY_IRI)
+      ? `p:${decodeURIComponent(r.p.slice(PROPERTY_IRI.length))}`
+      : `r:${decodeURIComponent(r.p.slice(RELATION_IRI.length))}`;
+    if (p === "p:role") m.role = r.v === "self" || r.v === "defines" ? r.v : "refers";
+    else if (p === "p:span") m.span = r.v;
+    else if (p === "p:kind") m.kind = r.v;
+    else if (p === "p:field") m.field = r.v;
+    else if (p === "p:window") m.window = r.v;
+    else if (p === "p:block_key") add(m.keys, r.v);
+    else if (p === "p:linked_to") add(m.linkedTo, r.v);
+    else if (p === "p:must_link") add(m.must, r.v);
+    else if (p === "p:cannot_link") add(m.cannot, r.v);
+    else if (p === "r:mentioned_in") m.source = r.v;
+    else if (p === "r:refers_to") m.thing = r.v;
+    else if (p === "r:same_thing_as" && !m.same.some((s) => s.target === r.v))
+      m.same.push({ target: r.v, confidence: r.c !== undefined ? Number(r.c) : null });
+  }
+  // A mention without a span or a source is gone, or no mention of this workflow.
+  for (const [iri, m] of out) if (!m.span || !m.source) out.delete(iri);
+  return out;
+}
+
+/** The names and classes of records. */
+export function recordsQuery(records: string[]): string {
+  return `# link: records\n${P}SELECT ?s ?name ?class WHERE {
+  VALUES ?s { ${iris(records)} }
+  OPTIONAL { ?s rdfs:label ?name } OPTIONAL { ?s a ?class }
+}`;
+}
+
+export interface RecordFacts {
+  name: string;
+  /** The class as the settings name it, else the local name of its IRI. */
+  class: string;
+}
+
+export function parseRecords(
+  rows: Record<string, string>[],
+  classes: string[],
+): Map<string, RecordFacts> {
+  const bySegment = new Map(classes.map((c) => [iriSegment(c), c]));
+  const out = new Map<string, RecordFacts>();
+  for (const r of rows) {
+    if (!r.s) continue;
+    const entry = out.get(r.s) ?? { name: "", class: "" };
+    if (r.name && !entry.name) entry.name = r.name;
+    if (r.class?.startsWith(CLASS_IRI)) {
+      const segment = r.class.slice(CLASS_IRI.length);
+      const named = bySegment.get(segment);
+      if (named || !entry.class) entry.class = named ?? decodeURIComponent(segment);
+    }
+    out.set(r.s, entry);
+  }
+  return out;
+}
+
+/** The anchor keys and labels of things, and where a merged thing points. */
+export function thingFactsQuery(things: string[]): string {
+  return `# link: thing facts\n${P}SELECT ?t ?p ?v WHERE {
+  VALUES ?t { ${iris(things)} }
+  ?t ?p ?v FILTER(?p IN (p:anchor_key, rdfs:label, r:merged_into))
+}`;
+}
+
+export function parseThingFacts(rows: Record<string, string>[]) {
+  const out = new Map<string, { anchorKey: string; label: string; mergedInto: string | null }>();
+  for (const r of rows) {
+    if (!r.t || r.v === undefined) continue;
+    const entry = out.get(r.t) ?? { anchorKey: "", label: "", mergedInto: null };
+    if (r.p === propertyIri("anchor_key")) entry.anchorKey = r.v;
+    else if (r.p === RDFS_LABEL) entry.label = r.v;
+    else entry.mergedInto = r.v;
+    out.set(r.t, entry);
+  }
+  return out;
+}
+
+/** The accepted identities (`SAME_AS`) of records, both ways. */
+export function sameAsQuery(records: string[]): string {
+  return `# link: same as\n${P}SELECT ?a ?b WHERE {
+  VALUES ?a { ${iris(records)} }
+  { ?a r:same_as ?b } UNION { ?b r:same_as ?a }
+}`;
+}
+
+export function parseSameAs(rows: Record<string, string>[]): [string, string][] {
+  const seen = new Set<string>();
+  const out: [string, string][] = [];
+  for (const r of rows) {
+    if (!r.a || !r.b || r.a === r.b) continue;
+    const pair = [r.a, r.b].sort() as [string, string];
+    const key = pair.join("\u0000");
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(pair);
+    }
+  }
+  return out;
+}
+
+/** `list` in parts of at most `size`. */
+export const parts = <T>(list: T[], size = PER_READ): T[][] =>
+  Array.from({ length: Math.ceil(list.length / size) }, (_, n) =>
+    list.slice(n * size, (n + 1) * size),
+  );

package/templates/link/samples/gold.json

@@ -0,0 +1,108 @@
+{
+  "format": "lbb.link.gold.v1",
+  "about": "The gold groups of the invented CRM of samples/records.json. Each group is one real thing: the mentions that name it, by record, field and span. Every name, company and address is invented.",
+  "complete": true,
+  "groups": [
+    { "id": "mira", "kind": "person", "mentions": [
+      { "record": "person-mira", "field": "name", "span": "Mira Tannenholt-Ruiz" },
+      { "record": "person-mira", "field": "email", "span": "mira.tannenholt@northbay.example" },
+      { "record": "lead-mira", "field": "first_name+last_name", "span": "Mira Ruiz" },
+      { "record": "lead-mira", "field": "email", "span": "mira.tannenholt@northbay.example" },
+      { "record": "deal-northbay", "field": "name", "span": "M. Tannenholt" },
+      { "record": "note-1", "field": "body", "span": "Mimi T." }
+    ] },
+    { "id": "robert", "kind": "person", "mentions": [
+      { "record": "person-robert", "field": "name", "span": "Robert Haldane" },
+      { "record": "person-robert", "field": "email", "span": "r.haldane@quillfield.example" },
+      { "record": "note-2", "field": "body", "span": "Bob Haldane" },
+      { "record": "note-11", "field": "body", "span": "Robert Haldane" }
+    ] },
+    { "id": "soren", "kind": "person", "mentions": [
+      { "record": "person-soren", "field": "name", "span": "Søren Vestergaard" },
+      { "record": "person-soren", "field": "email", "span": "soren@brightmoor.example" },
+      { "record": "lead-soren", "field": "first_name+last_name", "span": "Soren Vestergaard" },
+      { "record": "lead-soren", "field": "email", "span": "s.vestergaard@brightmoor.example" },
+      { "record": "note-3", "field": "body", "span": "Vestergaard, S." }
+    ] },
+    { "id": "dana", "kind": "person", "mentions": [
+      { "record": "person-dana", "field": "name", "span": "Dana Okafor" },
+      { "record": "person-dana", "field": "email", "span": "dana.okafor@northbay.example" },
+      { "record": "note-5", "field": "body", "span": "D. Okafor" }
+    ] },
+    { "id": "felix", "kind": "person", "mentions": [
+      { "record": "person-felix", "field": "name", "span": "Felix Okafor" },
+      { "record": "person-felix", "field": "email", "span": "felix.okafor@ridgeway.example" },
+      { "record": "note-4", "field": "body", "span": "F. Okafor" }
+    ] },
+    { "id": "jurgen", "kind": "person", "mentions": [
+      { "record": "person-jurgen", "field": "name", "span": "Jürgen Kessler" },
+      { "record": "person-jurgen", "field": "email", "span": "juergen.kessler@harbourline.example" },
+      { "record": "deal-harbourline", "field": "name", "span": "Jurgen Kessler" },
+      { "record": "note-6", "field": "body", "span": "Juergen Kessler" }
+    ] },
+    { "id": "zoe", "kind": "person", "mentions": [
+      { "record": "person-zoe", "field": "name", "span": "Zoë Lindqvist" },
+      { "record": "person-zoe", "field": "email", "span": "zoe@lumen-ash.example" },
+      { "record": "lead-zoe", "field": "first_name+last_name", "span": "Zoe Lindqvist" }
+    ] },
+    { "id": "kit", "kind": "person", "mentions": [
+      { "record": "person-kit", "field": "name", "span": "Kit Marsh" },
+      { "record": "person-kit", "field": "email", "span": "k.marsh@fernway.example" },
+      { "record": "lead-kit", "field": "email", "span": "k.marsh@fernway.example" },
+      { "record": "note-7", "field": "body", "span": "k.marsh@fernway.example" }
+    ] },
+    { "id": "tobias", "kind": "person", "mentions": [
+      { "record": "person-tobias", "field": "name", "span": "Tobias Wren" },
+      { "record": "person-tobias", "field": "email", "span": "tobias.wren@quillfield.example" },
+      { "record": "deal-quillfield", "field": "name", "span": "Wren, Tobias" },
+      { "record": "note-11", "field": "body", "span": "Tobias Wren" }
+    ] },
+    { "id": "priya", "kind": "person", "mentions": [
+      { "record": "person-priya", "field": "name", "span": "Priya Ramaswamy" },
+      { "record": "person-priya", "field": "email", "span": "priya.r@brightmoor.example" },
+      { "record": "note-8", "field": "body", "span": "Priya Ramaswamey" }
+    ] },
+    { "id": "alex-northbay", "kind": "person", "mentions": [
+      { "record": "person-alex-northbay", "field": "name", "span": "Alex Brandt" },
+      { "record": "person-alex-northbay", "field": "email", "span": "alex.brandt@northbay.example" }
+    ] },
+    { "id": "alex-ridgeway", "kind": "person", "mentions": [
+      { "record": "person-alex-ridgeway", "field": "name", "span": "Alex Brandt" },
+      { "record": "person-alex-ridgeway", "field": "email", "span": "a.brandt@ridgeway.example" },
+      { "record": "note-10", "field": "body", "span": "Alex Brandt" }
+    ] },
+    { "id": "casey", "kind": "person", "mentions": [
+      { "record": "lead-casey", "field": "first_name+last_name", "span": "Casey Moreau" },
+      { "record": "lead-casey", "field": "email", "span": "casey.moreau@gmail.com" }
+    ] },
+    { "id": "northbay", "kind": "organization", "mentions": [
+      { "record": "org-northbay", "field": "name", "span": "Northbay Water GmbH" },
+      { "record": "org-northbay", "field": "website", "span": "https://www.northbay.example/" },
+      { "record": "note-9", "field": "body", "span": "Northbay Water" }
+    ] },
+    { "id": "quillfield", "kind": "organization", "mentions": [
+      { "record": "org-quillfield", "field": "name", "span": "Quillfield Labs" },
+      { "record": "org-quillfield", "field": "website", "span": "https://quillfield.example" }
+    ] },
+    { "id": "brightmoor", "kind": "organization", "mentions": [
+      { "record": "org-brightmoor", "field": "name", "span": "Brightmoor Foods" },
+      { "record": "org-brightmoor", "field": "website", "span": "brightmoor.example" }
+    ] },
+    { "id": "ridgeway", "kind": "organization", "mentions": [
+      { "record": "org-ridgeway", "field": "name", "span": "Ridgeway Transit" },
+      { "record": "org-ridgeway", "field": "website", "span": "https://ridgeway.example/" }
+    ] },
+    { "id": "harbourline", "kind": "organization", "mentions": [
+      { "record": "org-harbourline", "field": "name", "span": "Harbourline Marine" },
+      { "record": "org-harbourline", "field": "website", "span": "https://www.harbourline.example" }
+    ] },
+    { "id": "lumen", "kind": "organization", "mentions": [
+      { "record": "org-lumen", "field": "name", "span": "Lumen & Ash" },
+      { "record": "org-lumen", "field": "website", "span": "https://lumen-ash.example" }
+    ] },
+    { "id": "fernway", "kind": "organization", "mentions": [
+      { "record": "org-fernway", "field": "name", "span": "Fernway Studio" },
+      { "record": "org-fernway", "field": "website", "span": "https://fernway.example" }
+    ] }
+  ]
+}

package/templates/link/samples/records.json

@@ -0,0 +1,48 @@
+[
+  { "id": "org-northbay", "class": "Organization", "name": "Northbay Water GmbH", "fields": { "website": "https://www.northbay.example/" } },
+  { "id": "org-quillfield", "class": "Organization", "name": "Quillfield Labs", "fields": { "website": "https://quillfield.example" } },
+  { "id": "org-brightmoor", "class": "Organization", "name": "Brightmoor Foods", "fields": { "website": "brightmoor.example" } },
+  { "id": "org-ridgeway", "class": "Organization", "name": "Ridgeway Transit", "fields": { "website": "https://ridgeway.example/" } },
+  { "id": "org-harbourline", "class": "Organization", "name": "Harbourline Marine", "fields": { "website": "https://www.harbourline.example" } },
+  { "id": "org-lumen", "class": "Organization", "name": "Lumen & Ash", "fields": { "website": "https://lumen-ash.example" } },
+  { "id": "org-fernway", "class": "Organization", "name": "Fernway Studio", "fields": { "website": "https://fernway.example" } },
+
+  { "id": "person-mira", "class": "Person", "name": "Mira Tannenholt-Ruiz", "fields": { "email": "mira.tannenholt@northbay.example", "job_title": "Procurement Lead" }, "relations": { "WORKS_AT": ["org-northbay"] } },
+  { "id": "person-robert", "class": "Person", "name": "Robert Haldane", "fields": { "email": "r.haldane@quillfield.example", "job_title": "Lab Manager" }, "relations": { "WORKS_AT": ["org-quillfield"] } },
+  { "id": "person-soren", "class": "Person", "name": "Søren Vestergaard", "fields": { "email": "soren@brightmoor.example", "job_title": "Head of Quality" }, "relations": { "WORKS_AT": ["org-brightmoor"] } },
+  { "id": "person-dana", "class": "Person", "name": "Dana Okafor", "fields": { "email": "dana.okafor@northbay.example", "job_title": "Site Engineer" }, "relations": { "WORKS_AT": ["org-northbay"] } },
+  { "id": "person-felix", "class": "Person", "name": "Felix Okafor", "fields": { "email": "felix.okafor@ridgeway.example", "job_title": "Fleet Manager" }, "relations": { "WORKS_AT": ["org-ridgeway"] } },
+  { "id": "person-jurgen", "class": "Person", "name": "Jürgen Kessler", "fields": { "email": "juergen.kessler@harbourline.example", "job_title": "Technical Director" }, "relations": { "WORKS_AT": ["org-harbourline"] } },
+  { "id": "person-zoe", "class": "Person", "name": "Zoë Lindqvist", "fields": { "email": "zoe@lumen-ash.example", "job_title": "Founder" }, "relations": { "WORKS_AT": ["org-lumen"] } },
+  { "id": "person-kit", "class": "Person", "name": "Kit Marsh", "fields": { "email": "k.marsh@fernway.example", "job_title": "Studio Lead" }, "relations": { "WORKS_AT": ["org-fernway"] } },
+  { "id": "person-tobias", "class": "Person", "name": "Tobias Wren", "fields": { "email": "tobias.wren@quillfield.example", "job_title": "Buyer" }, "relations": { "WORKS_AT": ["org-quillfield"] } },
+  { "id": "person-priya", "class": "Person", "name": "Priya Ramaswamy", "fields": { "email": "priya.r@brightmoor.example", "job_title": "Operations Manager" }, "relations": { "WORKS_AT": ["org-brightmoor"] } },
+  { "id": "person-alex-northbay", "class": "Person", "name": "Alex Brandt", "fields": { "email": "alex.brandt@northbay.example", "job_title": "Planner" }, "relations": { "WORKS_AT": ["org-northbay"] } },
+  { "id": "person-alex-ridgeway", "class": "Person", "name": "Alex Brandt", "fields": { "email": "a.brandt@ridgeway.example", "job_title": "Depot Lead" }, "relations": { "WORKS_AT": ["org-ridgeway"] } },
+
+  { "id": "lead-mira", "class": "Lead", "name": "Mira Ruiz", "fields": { "first_name": "Mira", "last_name": "Ruiz", "email": "mira.tannenholt@northbay.example", "company_name": "Northbay Water" } },
+  { "id": "lead-soren", "class": "Lead", "name": "Soren Vestergaard", "fields": { "first_name": "Soren", "last_name": "Vestergaard", "email": "s.vestergaard@brightmoor.example", "company_name": "Brightmoor Foods" } },
+  { "id": "lead-zoe", "class": "Lead", "name": "Zoe Lindqvist", "fields": { "first_name": "Zoe", "last_name": "Lindqvist", "company_name": "Lumen & Ash" } },
+  { "id": "lead-kit", "class": "Lead", "name": "k.marsh@fernway.example", "fields": { "email": "k.marsh@fernway.example" } },
+  { "id": "lead-casey", "class": "Lead", "name": "Casey Moreau", "fields": { "first_name": "Casey", "last_name": "Moreau", "email": "casey.moreau@gmail.com", "company_name": "Moreau Design" } },
+
+  { "id": "deal-northbay", "class": "Deal", "name": "Northbay PX-200 retrofit (M. Tannenholt)", "relations": { "INVOLVES": ["person-mira"], "FOR_ORGANIZATION": ["org-northbay"] } },
+  { "id": "deal-ridgeway", "class": "Deal", "name": "Ridgeway depot pumps", "relations": { "INVOLVES": ["person-felix", "person-alex-ridgeway"], "FOR_ORGANIZATION": ["org-ridgeway"] } },
+  { "id": "deal-quillfield", "class": "Deal", "name": "Wren, Tobias - annual renewal", "relations": { "INVOLVES": ["person-tobias"], "FOR_ORGANIZATION": ["org-quillfield"] } },
+  { "id": "deal-brightmoor", "class": "Deal", "name": "Brightmoor cold-room filters", "relations": { "INVOLVES": ["person-soren"], "FOR_ORGANIZATION": ["org-brightmoor"] } },
+  { "id": "deal-harbourline", "class": "Deal", "name": "Harbourline service plan (Jurgen Kessler)", "relations": { "INVOLVES": ["person-jurgen"], "FOR_ORGANIZATION": ["org-harbourline"] } },
+  { "id": "deal-audit", "class": "Deal", "name": "Brightmoor line audit", "relations": { "INVOLVES": ["person-priya"], "FOR_ORGANIZATION": ["org-brightmoor"] } },
+  { "id": "deal-survey", "class": "Deal", "name": "Northbay site survey", "relations": { "INVOLVES": ["person-dana"], "FOR_ORGANIZATION": ["org-northbay"] } },
+
+  { "id": "note-1", "class": "Note", "name": "Note 1", "fields": { "body": "Call with Mimi T.: she wants four filters before March." }, "relations": { "ABOUT": ["deal-northbay"] } },
+  { "id": "note-2", "class": "Note", "name": "Note 2", "fields": { "body": "Bob Haldane asked for the new price list." }, "relations": { "ABOUT": ["person-robert"] } },
+  { "id": "note-3", "class": "Note", "name": "Note 3", "fields": { "body": "Vestergaard, S. confirmed the trial for May." }, "relations": { "ABOUT": ["deal-brightmoor"] } },
+  { "id": "note-4", "class": "Note", "name": "Note 4", "fields": { "body": "F. Okafor wants the invoice split in two." }, "relations": { "ABOUT": ["deal-ridgeway"] } },
+  { "id": "note-5", "class": "Note", "name": "Note 5", "fields": { "body": "D. Okafor sent the site drawings." }, "relations": { "ABOUT": ["deal-survey"] } },
+  { "id": "note-6", "class": "Note", "name": "Note 6", "fields": { "body": "Juergen Kessler called back about the service plan." }, "relations": { "ABOUT": ["deal-harbourline"] } },
+  { "id": "note-7", "class": "Note", "name": "Note 7", "fields": { "body": "Forwarded the quote to k.marsh@fernway.example." }, "relations": { "ABOUT": ["lead-kit"] } },
+  { "id": "note-8", "class": "Note", "name": "Note 8", "fields": { "body": "Priya Ramaswamey will join the call on Friday." }, "relations": { "ABOUT": ["deal-audit"] } },
+  { "id": "note-9", "class": "Note", "name": "Note 9", "fields": { "body": "Northbay Water confirmed the delivery address." }, "relations": { "ABOUT": ["deal-northbay"] } },
+  { "id": "note-10", "class": "Note", "name": "Note 10", "fields": { "body": "Alex Brandt from Ridgeway asked about lead times." }, "relations": { "ABOUT": ["deal-ridgeway"] } },
+  { "id": "note-11", "class": "Note", "name": "Note 11", "fields": { "body": "Tobias Wren signed the renewal; Robert Haldane is in copy." }, "relations": { "ABOUT": ["deal-quillfield"] } }
+]

package/templates/link/samples.ts

@@ -0,0 +1,64 @@
+// The samples of link, for `npm run try`: an invented CRM (samples/records.json)
+// of organizations, contacts, leads, deals and notes, committed with the
+// classes, fields and relations it needs. Every name, company and address
+// is invented.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { LbbClient, Schemas } from "@littlebigbrain/client";
+
+interface SampleRecord {
+  id: string;
+  class: string;
+  name: string;
+  fields?: Record<string, string>;
+  relations?: Record<string, string[]>;
+}
+
+/** The ontology of the samples: their classes, fields and relations. */
+export function sampleOntology(records: SampleRecord[]): Schemas["OntologyEvolveOp"][] {
+  const classes = [...new Set(records.map((r) => r.class))];
+  const fields = [...new Set(records.flatMap((r) => Object.keys(r.fields ?? {})))];
+  const relations = new Map<string, { domain: Set<string>; range: Set<string> }>();
+  const classOf = new Map(records.map((r) => [r.id, r.class]));
+  for (const r of records)
+    for (const [relation, targets] of Object.entries(r.relations ?? {})) {
+      const entry = relations.get(relation) ?? { domain: new Set(), range: new Set() };
+      entry.domain.add(r.class);
+      for (const t of targets) entry.range.add(classOf.get(t)!);
+      relations.set(relation, entry);
+    }
+  return [
+    ...classes.map((name) => ({ op: "add_entity_type" as const, name })),
+    ...fields.map((name) => ({
+      op: "add_property" as const,
+      name,
+      value_type: name === "body" ? "text" : "keyword",
+    })),
+    ...[...relations].map(([name, { domain, range }]) => ({
+      op: "add_relation" as const,
+      name,
+      domain: [...domain],
+      range: [...range],
+    })),
+  ] as Schemas["OntologyEvolveOp"][];
+}
+
+/** Add the classes of the samples, then commit the records and their relations to the client's graph. */
+export async function loadSamples(client: LbbClient, dir: string): Promise<void> {
+  const records = JSON.parse(await readFile(join(dir, "records.json"), "utf8")) as SampleRecord[];
+  await client.ontology.evolve({ ops: sampleOntology(records) });
+  const ref = (r: SampleRecord) => ({ type: r.class, name: r.name, key: r.id });
+  const byId = new Map(records.map((r) => [r.id, r]));
+  await client.commit(
+    {
+      entity_properties: records.map((r) => ({ ...ref(r), properties: { ...(r.fields ?? {}) } })),
+      triplets: records.flatMap((r) =>
+        Object.entries(r.relations ?? {}).flatMap(([relation, targets]) =>
+          targets.map((t) => ({ source: ref(r), relation, target: ref(byId.get(t)!) })),
+        ),
+      ),
+    },
+    { idempotencyKey: "link-samples" },
+  );
+  console.log(`Committed ${records.length} records`);
+}