@littlebigbrain/create 0.0.0-stage → 0.1.0

package/templates/ontology-fit/samples.ts

@@ -0,0 +1,40 @@
+// The samples of ontology-fit, for `npm run try`: the ontology of
+// samples/expected.md and five invented site reports (samples/texts.json),
+// committed as instances of the class the settings name.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { LbbClient, Schemas } from "@littlebigbrain/client";
+import { defaults, ontology } from "./workflow.js";
+
+/** The graph before the run: the classes, properties and relations of expected.md. */
+export const sampleOntology: Schemas["OntologyEvolveOp"][] = [
+  ...ontology(),
+  { op: "add_entity_type", name: "Raum" },
+  { op: "add_entity_type", name: "Firma" },
+  { op: "add_property", name: "datum", value_type: "date_time" },
+  { op: "add_property", name: "nummer", value_type: "keyword" },
+  { op: "add_property", name: "bezeichnung", value_type: "text" },
+  { op: "add_property", name: "gewerk", value_type: "keyword" },
+  { op: "add_relation", name: "betrifft_raum", domain: [defaults.className], range: ["Raum"] },
+  { op: "add_relation", name: "anwesend", domain: [defaults.className], range: ["Firma"] },
+];
+
+/** Set up the sample ontology and commit the sample texts to the client's graph. */
+export async function loadSamples(client: LbbClient, dir: string): Promise<void> {
+  const texts = JSON.parse(await readFile(join(dir, "texts.json"), "utf8")) as {
+    name: string;
+    text: string;
+  }[];
+  await client.ontology.evolve({ ops: sampleOntology });
+  await client.commit(
+    {
+      entity_properties: texts.map((t) => ({
+        type: defaults.className,
+        name: t.name,
+        properties: { [defaults.textField]: t.text },
+      })),
+    },
+    { idempotencyKey: "ontology-fit-samples" },
+  );
+  console.log(`Committed ${texts.length} ${defaults.className} texts`);
+}

package/templates/ontology-fit/workflow.test.ts

@@ -0,0 +1,264 @@
+// ontology-fit on its samples, with a mock reasoning model whose rules are
+// fixed: a sentence about a defect (`Mangel`) proposes the class `Mangel`,
+// `Frist`, `Status` and `Zuständig` propose its facts, a room in the same
+// text widens `betrifft_raum`, a list of who was present proposes the
+// relation `anwesend` the ontology has, and a text about the acceptance
+// (`Abnahme`) gets a quote that is not in the text. The expected keys come
+// from samples/expected.md.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ENTITY_IRI_NAMESPACE, type Schemas } from "@littlebigbrain/client";
+import {
+  MockActivities,
+  mockId,
+  readJson,
+  runMessage,
+  samplesDir,
+  triggerMessage,
+  type MockRules,
+} from "../_shared/testing.js";
+import { createWorkflow, keyPart, quoteInText } from "./workflow.js";
+import { sampleOntology } from "./samples.js";
+
+const SAMPLES = samplesDir(import.meta.url, "ontology-fit");
+const TEXTS = readJson<{ name: string; text: string }[]>(join(SAMPLES, "texts.json"));
+const EXPECTED_MD = readFileSync(join(SAMPLES, "expected.md"), "utf8");
+/** The keys of the table "Proposals a good run makes". */
+const EXPECTED_KEYS = [
+  ...EXPECTED_MD.split("## Proposals a good run makes")[1]!
+    .split("## Proposals a good run may make")[0]!
+    .matchAll(/`(fit:[^`]+)`/g),
+].map((m) => m[1]!);
+
+const iriOf = (name: string) => ENTITY_IRI_NAMESPACE + mockId(`Baustellenbericht:${name}`);
+
+/** The ontology view of the graph before the run, built from the sample ontology. */
+function view(): Schemas["OntologyView"] {
+  const ops = sampleOntology;
+  const types = ops.flatMap((op) => (op.op === "add_entity_type" ? [op.name] : []));
+  return {
+    graph: { tenant_id: "t", graph_id: "samples", branch_id: "main" },
+    ontology_version: 3,
+    entity_types: [],
+    relations: [],
+    entity_type_defs: types.map((name) => ({
+      name,
+      stable_id: `type:${name}`,
+      properties: [],
+      resolvable: true,
+      since_version: 1,
+    })),
+    relation_defs: ops.flatMap((op) =>
+      op.op === "add_relation"
+        ? [
+            {
+              name: op.name,
+              src_types: op.domain ?? [],
+              dst_types: op.range ?? [],
+              cardinality: "many_to_many",
+              since_version: 1,
+              symmetric: false,
+              temporal_semantics: "bitemporal",
+              transitive: false,
+            },
+          ]
+        : [],
+    ),
+    property_defs: ops.flatMap((op) =>
+      op.op === "add_property"
+        ? [{ name: op.name, value_type: op.value_type ?? "text", required: false }]
+        : [],
+    ),
+  } as Schemas["OntologyView"];
+}
+
+/** Whether the ontology has a change already: the dry run's no-op. */
+function covered(op: Schemas["OntologyEvolveOp"], v: Schemas["OntologyView"]): boolean {
+  const has = (names: { name: string }[] | undefined, name: string) =>
+    (names ?? []).some((n) => n.name.toLowerCase() === name.toLowerCase());
+  if (op.op === "add_entity_type") return has(v.entity_type_defs, op.name);
+  if (op.op === "add_property") return has(v.property_defs, op.name);
+  if (op.op === "add_relation") return has(v.relation_defs, op.name);
+  if (op.op === "widen_relation") {
+    const r = v.relation_defs?.find((d) => d.name.toLowerCase() === op.relation.toLowerCase());
+    return Boolean(
+      r &&
+      (op.add_domain ?? []).every((d) => r.src_types.includes(d)) &&
+      (op.add_range ?? []).every((d) => r.dst_types.includes(d)),
+    );
+  }
+  return false;
+}
+
+const proposal = (fields: Partial<Record<string, string>>) => ({
+  kind: "",
+  name: "",
+  parent: "",
+  class: "",
+  value_type: "",
+  domain: "",
+  range: "",
+  quote: "",
+  reason: "",
+  ...fields,
+});
+
+function propose(text: string) {
+  const sentences = text.split(/(?<=\.)\s+/);
+  const find = (pattern: RegExp) => sentences.find((s) => pattern.test(s));
+  const out = [];
+  const defect = find(/Mangel|Mängel/);
+  if (defect)
+    out.push(
+      proposal({
+        kind: "add_class",
+        name: "Mangel",
+        quote: defect,
+        reason: "The texts follow defects.",
+      }),
+    );
+  const deadline = find(/Frist/);
+  if (defect && deadline)
+    out.push(
+      proposal({
+        kind: "add_property",
+        name: "frist",
+        class: "Mangel",
+        value_type: "date_time",
+        quote: deadline,
+      }),
+    );
+  const status = find(/Status/);
+  if (defect && status)
+    out.push(
+      proposal({
+        kind: "add_property",
+        name: "status",
+        class: "Mangel",
+        value_type: "keyword",
+        quote: status,
+      }),
+    );
+  const owner = find(/Zuständig/);
+  if (defect && owner)
+    out.push(
+      proposal({
+        kind: "add_relation",
+        name: "zustaendig",
+        domain: "Mangel",
+        range: "Firma",
+        quote: owner,
+      }),
+    );
+  const room = find(/Raum 0\.\d+/);
+  if (defect && room)
+    out.push(
+      proposal({ kind: "widen_relation", name: "betrifft_raum", domain: "Mangel", quote: room }),
+    );
+  const present = find(/Anwesend:|Teilnehmer:/);
+  if (present)
+    out.push(
+      proposal({
+        kind: "add_relation",
+        name: "anwesend",
+        domain: "Baustellenbericht",
+        range: "Firma",
+        quote: present,
+      }),
+    );
+  if (find(/Abnahme/))
+    out.push(
+      proposal({ kind: "add_class", name: "Abnahme", quote: "Die Abnahme findet morgen statt." }),
+    );
+  return out;
+}
+
+function rules(more: MockRules = {}): MockRules {
+  const v = view();
+  return {
+    ontology: v,
+    reason: (request) => ({
+      proposals: propose((JSON.parse(request.prompt) as { text: string }).text),
+    }),
+    evolve: (ops) => ({ no_op: ops.every((op) => covered(op, v)) }),
+    sparql: (query) =>
+      TEXTS.filter((t) => query.includes(iriOf(t.name))).map((t) => ({
+        s: iriOf(t.name),
+        label: t.name,
+        text: t.text,
+      })),
+    ...more,
+  };
+}
+
+test("the samples give the changes of expected.md, one review item per key", async () => {
+  const lbb = new MockActivities(rules());
+  const { state } = await runMessage(
+    createWorkflow(lbb),
+    triggerMessage(
+      "berichte",
+      TEXTS.map((t) => iriOf(t.name)),
+    ),
+  );
+
+  assert.equal(EXPECTED_KEYS.length, 5);
+  assert.deepEqual([...lbb.reviews.keys()].sort(), [...EXPECTED_KEYS].sort());
+  assert.deepEqual(state, { texts: 5, proposals: 3 + 4 + 5 + 5 + 2, filed: 5 });
+  const mangel = lbb.reviews.get("fit:berichte/add_class/mangel")!;
+  assert.equal(mangel.workflow, "berichte");
+  assert.deepEqual(mangel.change, [{ op: "add_entity_type", name: "Mangel" }]);
+  assert.equal(mangel.evidence!.records, 5);
+});
+
+test("a change names the classes it needs, and a widening keeps the relation's name", async () => {
+  const lbb = new MockActivities(rules());
+  await runMessage(
+    createWorkflow(lbb),
+    triggerMessage(
+      "berichte",
+      TEXTS.map((t) => iriOf(t.name)),
+    ),
+  );
+
+  assert.deepEqual(lbb.reviews.get("fit:berichte/add_relation/mangel/zustaendig/firma")!.change, [
+    { op: "add_entity_type", name: "Mangel" },
+    { op: "add_relation", name: "zustaendig", domain: ["Mangel"], range: ["Firma"] },
+  ]);
+  assert.deepEqual(lbb.reviews.get("fit:berichte/widen_relation/betrifft-raum/mangel/x")!.change, [
+    { op: "add_entity_type", name: "Mangel" },
+    { op: "widen_relation", relation: "betrifft_raum", add_domain: ["Mangel"], add_range: [] },
+  ]);
+  assert.equal(
+    lbb.reviews.get("fit:berichte/add_property/mangel/frist")!.title,
+    "Add property frist to Mangel",
+  );
+});
+
+test("a change the ontology has, and a quote that is not in the text, are not filed", async () => {
+  const lbb = new MockActivities(rules());
+  await runMessage(
+    createWorkflow(lbb),
+    triggerMessage(
+      "berichte",
+      TEXTS.map((t) => iriOf(t.name)),
+    ),
+  );
+  const keys = [...lbb.reviews.keys()];
+
+  assert.ok(!keys.some((k) => k.includes("anwesend")), "anwesend is already in the ontology");
+  assert.ok(!keys.some((k) => k.includes("abnahme")), "its quote is not in the text");
+  for (const item of lbb.reviews.values())
+    for (const sample of item.evidence!.samples! as { entity: string; quote: string }[]) {
+      const text = TEXTS.find((t) => iriOf(t.name) === sample.entity)!.text;
+      assert.ok(quoteInText(sample.quote, text), sample.quote);
+    }
+});
+
+test("keys keep lowercase ASCII letters and digits, other runs as one dash", () => {
+  assert.equal(keyPart("Mangel"), "mangel");
+  assert.equal(keyPart("betrifft_raum"), "betrifft-raum");
+  assert.equal(keyPart("-"), "x");
+  assert.equal(keyPart("zuständig"), "zust-ndig");
+});