@littlebigbrain/create 0.0.0-stage → 0.1.0

package/templates/documents-link/workflow.ts

@@ -0,0 +1,457 @@
+// documents-link: find the identifiers the documents of a graph define and the spans that mention
+// them, and link each mention to its entry.
+//
+// A triggered workflow of the starter workflow `workflow` watches the class `Document` and its
+// field `parse_status` (LBB's parse writes it), and sends the parsed documents here. The workflow
+// reads each document in windows of pages, one window per turn:
+//
+// 1. Define: the reasoning model (`reason`) lists the identifiers each page defines; they are
+//    written as `DocEntry` entities `DEFINED_IN` the document. Every defining window of a message
+//    runs before its first link window, so the catalogue holds them all.
+// 2. Link: the reasoning model lists the spans of each page that may be codes. Each span gets
+//    candidates from the catalogue (every `DocEntry` of the graph) by characters and by meaning
+//    (`embed`), and the decision model (`decide`) answers what the span is and which entry it
+//    names. A mention is written as a `DocMention` `MENTIONED_IN` the document, with a
+//    `REFERS_TO` link to its entry when the link's confidence reaches the gate; a link below the
+//    gate becomes a review item.
+//
+// Each model call runs in a step and passes the step's effect id, so a turn that runs again after
+// a crash pays for nothing twice.
+import {
+  entityRef,
+  isActivityRefused,
+  LbbError,
+  splitInHalves,
+  triggeredWorkflow,
+  type DecideAnswer,
+  type LbbActivities,
+  type Schemas,
+  type WorkflowContext,
+  type WorkflowTriggerMessage,
+} from "@littlebigbrain/client";
+import * as link from "./link.js";
+
+/** The part of a document: `defines` adds entries, `refers` has its mentions linked, `both` does both. */
+export type Role = "defines" | "refers" | "both";
+
+export interface Settings {
+  /** A link below this confidence goes to review instead of the graph. */
+  gate: number;
+  /** The role of each document by file name. A document the map does not name is `both`. */
+  roles: Record<string, Role>;
+  /** Pages of one window, 1 to 20: one turn reads one window. */
+  pagesPerWindow: number;
+}
+
+/** The settings: edit them for your documents. The roles are those of the samples. */
+export const defaults: Settings = {
+  gate: 0.8,
+  roles: {
+    "ausstattungsliste.pdf": "defines",
+    "baubeschreibung.pdf": "defines",
+    "raumblaetter.pdf": "refers",
+  },
+  pagesPerWindow: 12,
+};
+
+/** The workflow type and version the triggered workflow names. */
+export const workflowType = { workflow_type: "documents-link", version: "v1" };
+
+/** The triggered workflow that sends the documents here: `client.workflows.starters.use(trigger())`. */
+export function trigger(): Schemas["TriggeredWorkflowRequest"] {
+  return {
+    starter: "workflow",
+    name: "documents-link",
+    watch: { class: "Document", fields: ["parse_status"] },
+    workflow: workflowType,
+    owns: {
+      classes: ["DocEntry", "DocMention"],
+      relations: ["DEFINED_IN", "MENTIONED_IN", "REFERS_TO"],
+    },
+    batch: 16,
+  };
+}
+
+const FIELD_TYPES: Record<string, string> = { context: "text", line_text: "text", page: "i64" };
+
+/** The classes, properties and relations the workflow writes: `lbb.evolve(ontology())`. */
+export function ontology(): Schemas["OntologyEvolveOp"][] {
+  const fields = [...new Set([...link.ENTRY_FIELDS, ...link.MENTION_FIELDS])];
+  return [
+    { op: "add_entity_type", name: "Document" },
+    { op: "add_entity_type", name: "DocEntry" },
+    { op: "add_entity_type", name: "DocMention" },
+    ...fields.map((name) => ({
+      op: "add_property" as const,
+      name,
+      value_type: FIELD_TYPES[name] ?? (/^[xy][01]$/.test(name) ? "f64" : "keyword"),
+    })),
+    { op: "add_relation", name: "DEFINED_IN", domain: ["DocEntry"], range: ["Document"] },
+    { op: "add_relation", name: "MENTIONED_IN", domain: ["DocMention"], range: ["Document"] },
+    { op: "add_relation", name: "REFERS_TO", domain: ["DocMention"], range: ["DocEntry"] },
+  ];
+}
+
+/** What the workflow has written, over all its turns. */
+export interface LinkState {
+  entries: number;
+  mentions: number;
+  links: number;
+  review: number;
+}
+
+/** A trigger message; a continued turn names the window it reads in `cursor`. */
+type LinkMessage = WorkflowTriggerMessage & { cursor?: number };
+interface Doc extends link.Doc {
+  pages: number;
+  parsed: boolean;
+}
+interface Window {
+  stage: "define" | "link";
+  doc: number;
+  from: number;
+  to: number;
+}
+
+const P = "PREFIX p: <https://littlebigbrain.com/p/>\nPREFIX r: <https://littlebigbrain.com/r/>\n";
+const ENTRY_CLASS = "https://littlebigbrain.com/class/docentry";
+const MENTION_CLASS = "https://littlebigbrain.com/class/docmention";
+const values = (iris: string[]) =>
+  iris
+    .filter((iri) => /^[^\s<>"{}|\\^`]+$/.test(iri))
+    .map((iri) => `<${iri}>`)
+    .join(" ");
+const label = (doc: Doc, page: number, what: string) =>
+  `${doc.name.slice(0, 40)} p${page + 1} ${what}`;
+/** The effect id of the `n`th call of one kind in a step: the step's own, then `.1`, `.2`, … */
+const effect = (id: string, n: number) => (n === 0 ? id : `${id}.${n}`);
+
+/** The workflow, for a `WorkflowWorker`. `lbb` is `lbbActivities(client)`, or a mock in a test. */
+export function createWorkflow(lbb: LbbActivities, settings: Settings = defaults) {
+  if (!(settings.pagesPerWindow >= 1 && settings.pagesPerWindow <= 20))
+    throw new RangeError("pagesPerWindow is from 1 to 20: a turn holds 64 steps");
+  return triggeredWorkflow<LinkState>({
+    name: workflowType.workflow_type,
+    version: workflowType.version,
+    initialState: { entries: 0, mentions: 0, links: 0, review: 0 },
+    async onInstances(ctx, message: LinkMessage, state) {
+      const docs = await ctx.step("documents", () => readDocuments(lbb, message));
+      if (message.cursor === undefined) {
+        const gone = [...message.removed, ...docs.filter((d) => !d.parsed).map((d) => d.iri)];
+        if (gone.length) await dropOutputs(ctx, lbb, gone);
+      }
+      const plan = windows(docs, settings);
+      const at = message.cursor ?? 0;
+      const w = plan[at];
+      if (!w) return { state };
+      const doc = docs[w.doc]!;
+      const next =
+        w.stage === "define"
+          ? await define(ctx, lbb, doc, w, state)
+          : await linkMentions(ctx, lbb, doc, w, state, settings, message.workflow);
+      if (at + 1 === plan.length) return { state: next };
+      return ctx.continue(next, { ...message, removed: [], cursor: at + 1 });
+    },
+  });
+}
+
+/** The windows of a message: every defining window first, so the catalogue is complete before a link. */
+function windows(docs: Doc[], settings: Settings): Window[] {
+  const roleOf = (doc: Doc) =>
+    Object.entries(settings.roles).find(([name]) => name.normalize() === doc.name.normalize())?.[1];
+  const of = (stage: Window["stage"], skip: Role) =>
+    docs.flatMap((doc, i) => {
+      if (!doc.parsed || roleOf(doc) === skip) return [];
+      const out: Window[] = [];
+      for (let from = 0; from < doc.pages; from += settings.pagesPerWindow)
+        out.push({ stage, doc: i, from, to: Math.min(doc.pages, from + settings.pagesPerWindow) });
+      return out;
+    });
+  return [...of("define", "refers"), ...of("link", "defines")];
+}
+
+/** The name, file and parse of each document, at the message's commit. */
+async function readDocuments(lbb: LbbActivities, message: WorkflowTriggerMessage): Promise<Doc[]> {
+  if (!message.instances.length) return [];
+  const query = `# documents-link: documents\n${P}SELECT ?doc ?name ?sha ?status ?pages WHERE {
+  VALUES ?doc { ${values(message.instances)} }
+  OPTIONAL { ?doc p:name ?name } OPTIONAL { ?doc p:file_sha256 ?sha }
+  OPTIONAL { ?doc p:parse_status ?status } OPTIONAL { ?doc p:page_count ?pages }
+}`;
+  const { rows } = await lbb.sparql({ query, as_of_commit_seq: message.as_of_commit_seq });
+  return message.instances.map((iri) => {
+    const row = rows.find((r) => r.doc === iri) ?? {};
+    const parsed = row.status === "parsed" && Boolean(row.sha);
+    return {
+      iri,
+      name: row.name ?? iri,
+      sha256: row.sha ?? "",
+      pages: Number(row.pages ?? 0),
+      parsed,
+    };
+  });
+}
+
+/** Retract the entries and mentions of documents that left the class or lost their parse. */
+async function dropOutputs(ctx: WorkflowContext, lbb: LbbActivities, gone: string[]) {
+  const found = await ctx.step("drop-find", async () => {
+    // Deleting a file retracts the edges to its Document: its entries and mentions are left without one.
+    const query = `# documents-link: outputs\n${P}SELECT ?entity ?class WHERE {
+  { VALUES ?doc { ${values(gone)} } ?entity r:defined_in|r:mentioned_in ?doc }
+  UNION { ?entity a <${ENTRY_CLASS}> FILTER NOT EXISTS { ?entity r:defined_in ?any } }
+  UNION { ?entity a <${MENTION_CLASS}> FILTER NOT EXISTS { ?entity r:mentioned_in ?any } }
+  ?entity a ?class .
+}`;
+    const { rows } = await lbb.sparql(query, { consistency: "strong" });
+    return rows
+      .filter((r) => r.class === ENTRY_CLASS || r.class === MENTION_CLASS)
+      .map((r) => ({ iri: r.entity!, type: r.class === ENTRY_CLASS ? "DocEntry" : "DocMention" }));
+  });
+  const retract = found.map((e) => entityRef(e.iri, e.type));
+  if (retract.length)
+    await lbb.writeOwned(ctx, "drop", { subjects: [], retract_entities: retract });
+}
+
+/** The pages of the window and the catalogue, read inside the steps that need them, once per attempt. */
+function reader(lbb: LbbActivities, doc: Doc, w: Window) {
+  let pages: Promise<link.FilePage[]> | undefined;
+  let catalogue: Promise<link.Entry[]> | undefined;
+  const query = `# documents-link: catalogue\n${P}SELECT ?identifier ?context ?line ?doc ?name ?sha WHERE {
+  ?entry a <${ENTRY_CLASS}> ; p:identifier ?identifier ; r:defined_in ?doc .
+  ?doc p:name ?name ; p:file_sha256 ?sha .
+  OPTIONAL { ?entry p:context ?context } OPTIONAL { ?entry p:line_id ?line }
+}`;
+  const read = {
+    pages: () => (pages ??= lbb.pages(doc.sha256, { from: w.from, to: w.to }).then((r) => r.pages)),
+    page: async (page: number) => (await read.pages())[page - w.from]!,
+    /** Every entry of the graph, this workflow's own writes included, in a stable order. */
+    catalogue: () =>
+      (catalogue ??= lbb.sparql(query, { consistency: "strong" }).then(({ rows }) =>
+        rows
+          .map((r) => ({
+            identifier: r.identifier!,
+            context: r.context ?? r.identifier!,
+            line: r.line ?? "",
+            document: r.doc!,
+            documentName: r.name!,
+            sha256: r.sha!,
+          }))
+          .sort((a, b) => link.order(a).localeCompare(link.order(b))),
+      )),
+  };
+  return read;
+}
+
+/** A define window: each page's definitions, then the window's entries, owned per entry. */
+async function define(
+  ctx: WorkflowContext,
+  lbb: LbbActivities,
+  doc: Doc,
+  w: Window,
+  state: LinkState,
+): Promise<LinkState> {
+  const read = reader(lbb, doc, w);
+  const found: link.Definition[] = [];
+  for (let page = w.from; page < w.to; page++) {
+    const kept = await ctx.step(`define-p${page + 1}`, async (s) => {
+      const p = await read.page(page);
+      const answer = await lbb.reason(link.definitionsRequest(p), {
+        effectId: s.effectId,
+        label: label(doc, page, "definitions"),
+      });
+      return link.checkDefinitions(answer.value, p);
+    });
+    found.push(...kept);
+  }
+  // A commit names at most 1,000 entities: the entries go in parts of at most 900.
+  const count = new Set(found.map((d) => d.identifier)).size;
+  for (let n = 0; n * link.PART < count; n++)
+    await lbb.writeOwned(ctx, `entries-${n}`, async () =>
+      link.part(link.entriesWrite(doc, await read.pages(), found), n),
+    );
+  return { ...state, entries: state.entries + count };
+}
+
+/** A link window: each page's mentions, their candidates and answers, the gate, the writes. */
+async function linkMentions(
+  ctx: WorkflowContext,
+  lbb: LbbActivities,
+  doc: Doc,
+  w: Window,
+  state: LinkState,
+  settings: Settings,
+  workflow: string,
+): Promise<LinkState> {
+  const read = reader(lbb, doc, w);
+  const pages = Array.from({ length: w.to - w.from }, (_, n) => w.from + n);
+  const mentions: link.Mention[][] = [];
+  for (const page of pages) {
+    const kept = await ctx.step(`mention-p${page + 1}`, async (s) => {
+      const p = await read.page(page);
+      const answer = await lbb.reason(link.mentionsRequest(p), {
+        effectId: s.effectId,
+        label: label(doc, page, "mentions"),
+      });
+      return link.checkMentions(answer.value, p);
+    });
+    mentions.push(kept);
+  }
+  const byMeaning = await ctx.step("meaning", (s) => meaning(s.effectId, lbb, doc, read, mentions));
+  const resolved: link.Resolved[][] = [];
+  for (const [n, page] of pages.entries()) {
+    const answers = await ctx.step(`decide-p${page + 1}`, (s) =>
+      decidePage(s.effectId, lbb, doc, read, page, mentions[n]!, byMeaning[n]!),
+    );
+    resolved.push(answers);
+  }
+
+  // The link rule, then the gate: written, or a review item, or no link.
+  const all = mentions.flatMap((list, n) =>
+    list.map((m, k) => ({
+      m,
+      page: pages[n]!,
+      ...link.linkRule(resolved[n]![k]!),
+      r: resolved[n]![k]!,
+    })),
+  );
+  const written = all.filter((x) => x.target !== null && x.confidence >= settings.gate);
+  const below = all.filter((x) => x.target !== null && x.confidence < settings.gate);
+  await ctx.step("review", async () => {
+    const catalogue = await read.catalogue();
+    // One item per span and entry: S1.1 on two pages is one item with two links.
+    const groups = new Map<string, typeof below>();
+    for (const x of below) {
+      const key = `${link.identifierKey(x.m.span)}\u0000${x.target}`;
+      groups.set(key, [...(groups.get(key) ?? []), x]);
+    }
+    // An item holds at most 100 links, so its facts stay within the 64 KiB a suggestion takes.
+    const items = [...groups.values()].flatMap((group) =>
+      Array.from({ length: Math.ceil(group.length / 100) }, (_, n) => ({
+        n,
+        group: group.slice(n * 100, (n + 1) * 100),
+      })),
+    );
+    for (const { n, group } of items) {
+      const entry = catalogue[group[0]!.target!]!;
+      const span = group[0]!.m.span;
+      const lowest = Math.min(...group.map((x) => x.confidence));
+      const pages = await read.pages();
+      const triplets = group.map((x) => link.refersTo(doc, pages, x.m, entry, x.confidence));
+      await lbb.review({
+        workflow,
+        key: `starter:${workflow}:link:${doc.sha256.slice(0, 16)}:${link.keyPart(span)}:${entry.sha256.slice(0, 16)}:${link.keyPart(entry.identifier)}:${n}`,
+        title: `Link "${span}" in ${doc.name} to ${entry.identifier}`.slice(0, 200),
+        rationale: `${group.length} mentions of "${span}" in ${doc.name} name the entry ${entry.identifier} with a confidence below the gate ${settings.gate} (lowest ${lowest}).`,
+        facts: {
+          triplets,
+          summary: `${triplets.length} REFERS_TO links from "${span}" to ${entry.identifier}`,
+        },
+        evidence: {
+          records: group.length,
+          samples: group
+            .slice(0, 20)
+            .map((x) => ({ page: x.page, line_id: x.m.line, confidence: x.confidence })),
+        },
+      });
+    }
+    return items.length;
+  });
+  for (let n = 0; n * link.PART < all.length; n++)
+    await lbb.writeOwned(ctx, `mentions-${n}`, async () => {
+      const [pages, catalogue] = [await read.pages(), await read.catalogue()];
+      const links = written.map((x) => ({ ...x, entry: catalogue[x.target!]! }));
+      return link.part(link.mentionsWrite(doc, pages, all, links), n);
+    });
+  return {
+    entries: state.entries,
+    mentions: state.mentions + all.length,
+    links: state.links + written.length,
+    review: state.review + below.length,
+  };
+}
+
+/** The catalogue's entries closest in meaning to each mention (`span — row`), per page. */
+async function meaning(
+  effectId: string,
+  lbb: LbbActivities,
+  doc: Doc,
+  read: ReturnType<typeof reader>,
+  mentions: link.Mention[][],
+): Promise<number[][][]> {
+  const none = () => mentions.map((list) => list.map(() => []));
+  const catalogue = await read.catalogue();
+  const queries: string[] = [];
+  for (const list of mentions)
+    for (const m of list)
+      queries.push(
+        `${m.span} — ${link.rowOf(
+          (await read.pages()).flatMap((p) => p.lines),
+          m.line,
+        )}`,
+      );
+  if (!catalogue.length || !queries.length) return none();
+  const texts = [...catalogue.map((e) => `${e.identifier}: ${e.context}`), ...queries].map((t) =>
+    t.slice(0, 8_000),
+  );
+  const vectors: number[][] = [];
+  try {
+    for (let n = 0; n * 256 < texts.length; n++) {
+      const chunk = texts.slice(n * 256, (n + 1) * 256);
+      const embedded = await lbb.embed(
+        { texts: chunk },
+        { effectId: effect(effectId, n), label: `${doc.name.slice(0, 40)} meaning` },
+      );
+      vectors.push(...embedded.vectors);
+    }
+  } catch (error) {
+    // Without an embedding model the candidates come by characters only.
+    if (error instanceof LbbError && error.code === "activity_model_unavailable") return none();
+    throw error;
+  }
+  const entries = vectors.slice(0, catalogue.length);
+  let next = catalogue.length;
+  return mentions.map((list) => list.map(() => link.nearest(vectors[next++]!, entries)));
+}
+
+/** The decision model's answers for one page's mentions: a refused request is split in halves. */
+async function decidePage(
+  effectId: string,
+  lbb: LbbActivities,
+  doc: Doc,
+  read: ReturnType<typeof reader>,
+  page: number,
+  mentions: link.Mention[],
+  byMeaning: number[][],
+): Promise<link.Resolved[]> {
+  if (!mentions.length) return [];
+  const catalogue = await read.catalogue();
+  const p = await read.page(page);
+  const asked = mentions.map((mention, position) => ({
+    position,
+    mention,
+    lineText: p.lines.find((l) => l.id === mention.line)!.text,
+    candidates: link.candidatesFor(mention, doc.iri, catalogue, byMeaning[position]!),
+  }));
+  const state = link.pageState(doc.name, p, catalogue);
+  const answers: Record<string, DecideAnswer> = {};
+  const ask = async (part: link.Asked[], id: string): Promise<void> => {
+    try {
+      const request = link.decideRequest(state, part, catalogue);
+      const answered = await lbb.decide(request, {
+        effectId: id,
+        label: label(doc, page, "resolve"),
+      });
+      Object.assign(answers, answered.answers);
+    } catch (error) {
+      if (!isActivityRefused(error)) throw error;
+      // Too large for the model: ask each half. One mention the model refuses stays unanswered.
+      const halves = splitInHalves(part);
+      if (halves) for (const [n, half] of halves.entries()) await ask(half, `${id}.${n}`);
+    }
+  };
+  const requests = link.packRequests(state, asked, catalogue);
+  for (const [n, part] of requests.entries()) await ask(part, effect(effectId, n));
+  return asked.map(({ position }) =>
+    link.resolve(answers[`m${position}-kind`], answers[`m${position}-names`]),
+  );
+}

package/templates/ontology-fit/README.md

@@ -0,0 +1,81 @@
+# ontology-fit
+
+Reads the text of each new or changed instance of a class and proposes the
+ontology changes the text supports: a class `Mangel` for the defects a set
+of site reports follows, its properties `frist` and `status`, a relation
+`zustaendig` to `Firma`. Each change becomes a review item with its
+evolve operations and the quotes that support it; a person accepts it, and
+the ontology changes.
+
+The LBB-run version is the starter workflow `ontology.fit@v1`, the fit
+sources of `/v1/ontology/fit-sources` (`docs/reference/fit-sources.md`).
+
+## How it runs
+
+The triggered workflow watches the class and its text field. For each
+instance of a trigger message, one step:
+
+1. The reasoning model reads the text with the ontology
+   (`lbb.ontology()`, as classes, relations with their domain and range,
+   and properties) and the changes the earlier texts of the turn proposed,
+   and returns up to 12 proposals: `add_class`, `add_property`,
+   `add_relation` or `widen_relation`, each with a sentence of the text as
+   its quote. The prompt and schema are the LBB version's.
+2. Each proposal becomes a change (`shape`): its key, its title and its
+   evolve operations. A class the change names that the ontology lacks is
+   added first, and a new relation with the name of an existing one widens
+   it. The key follows the LBB version:
+   `fit:<workflow name>/add_class/mangel`,
+   `fit:<workflow name>/add_relation/mangel/zustaendig/firma`,
+   `fit:<workflow name>/widen_relation/betrifft-raum/mangel/x`.
+3. A change is kept when its quote is in the text with at least three
+   words, and a dry run (`lbb.evolve(change, { dryRun: true })`) says the
+   ontology does not have it yet.
+
+A last step files one review item per key, with the quotes of every text of
+the turn that supports it. The same key again updates the item. A turn reads
+at most 48 texts; the rest goes to a new turn.
+
+## Settings
+
+`defaults` in `workflow.ts`, which fit the samples:
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `className` | `Baustellenbericht` | The class whose instances hold the text |
+| `textField` | `text` | The property that holds the text |
+| `context` | the samples' | One sentence about what the text is |
+
+`trigger(settings)` names the triggered workflow `berichte`; the name starts
+every key. The workflow writes no graph facts, so it owns nothing.
+
+## What the LBB-run version adds
+
+- **Support scores.** The decision model scores how well each quote
+  supports its change; a change below 0.5 is dropped.
+- **Support across instances.** The instances that support each key are
+  counted over every run, and a dismissed change opens again when twice its
+  support and three more instances support it.
+- **The proposals of the source.** The open suggestions of the source and
+  the names of the dismissed ones go into every prompt, so the model reuses
+  names and does not propose a rejected change again.
+- **Name style.** A new relation or property name is written in the
+  ontology's style (`works_in` or `WORKS_IN`).
+- **Long texts.** A text past 40,000 characters is read in overlapping
+  chunks.
+- Its own monthly budget, a preview with the proposals of a sample, and
+  counters per outcome in the source's status.
+
+## Samples and test
+
+`samples/texts.json` holds five invented site reports and meeting minutes;
+`samples/expected.md` describes the graph before the run, the proposals a
+good run makes with their keys, those it may make, and those it does not
+make. `samples.ts` sets up that graph for `npm run try`.
+
+`workflow.test.ts` runs the workflow with a mock reasoning model whose rules
+are fixed (a sentence about a `Mangel` proposes the class, `Frist`, `Status`
+and `Zuständig` its facts, a room widens `betrifft_raum`). The run files
+the five keys of `expected.md` and no other: the relation `anwesend`, which
+the ontology has, is dropped by the dry run, and a proposal whose quote is
+not in its text is dropped by the quote check.

package/templates/ontology-fit/samples/expected.md

@@ -0,0 +1,88 @@
+# Fit from text samples: what a good run proposes
+
+The five texts in `texts.json` are invented site reports and meeting minutes
+of one project, Neubau Grundschule Musterstadt. They follow the defects found
+on site over four weeks: in which room, which company must fix each one, by
+when, and whether it is fixed. The graph has no class for a defect, so a fit
+run over these texts should propose one, with the facts the texts give about
+each defect. Texts are numbered 1 to 5 in the order of `texts.json`.
+
+## The graph before the run
+
+Each text is an instance of `Baustellenbericht`: its name is the label, its
+text is the property `text`. The ontology holds:
+
+| Class | Properties |
+| --- | --- |
+| `Baustellenbericht` | `text` (text), `datum` (datetime) |
+| `Raum` | `nummer` (keyword), `bezeichnung` (text) |
+| `Firma` | `name` (text), `gewerk` (keyword) |
+
+| Relation | From | To |
+| --- | --- | --- |
+| `betrifft_raum` | `Baustellenbericht` | `Raum` |
+| `anwesend` | `Baustellenbericht` | `Firma` |
+
+The fit source:
+
+```json
+{
+  "class": "Baustellenbericht",
+  "name": "berichte",
+  "from": ["text"],
+  "context": "Site reports and meeting minutes of a school building project, in German"
+}
+```
+
+## Proposals a good run makes
+
+The names follow the ontology: lower snake_case in ASCII (`zustaendig` for
+"zuständig"). A run can spell a name another way with the same meaning. The
+keys hold for the names in this table (a suggestion key keeps lowercase ASCII
+letters and digits, and writes every other run of characters as one dash; a
+missing class in a widen key is `x`).
+
+| Change | Key | Texts | Quote (one of them) |
+| --- | --- | --- | --- |
+| Add class `Mangel` | `fit:berichte/add_class/mangel` | 1 to 5 | "Der Mangel wurde der Fliesenbau Muster GmbH gemeldet" |
+| Add property `frist` (datetime) to `Mangel` | `fit:berichte/add_property/mangel/frist` | 1 to 4 | "die Frist zur Beseitigung endet am 16.09.2026" |
+| Add property `status` (keyword: `offen`, `behoben`) to `Mangel` | `fit:berichte/add_property/mangel/status` | 3 to 5 | "Frist 23.09.2026, Status offen" |
+| Add relation `zustaendig` from `Mangel` to `Firma` | `fit:berichte/add_relation/mangel/zustaendig/firma` | 1 to 4 | "Zuständig ist die Trockenbau Probe GmbH" |
+| Let `betrifft_raum` start at `Mangel` | `fit:berichte/widen_relation/betrifft-raum/mangel/x` | 1 to 5 | "In Raum 0.12 fehlt der Spiegel über dem Waschtisch" |
+
+The last row tests reuse. Every defect names its room, and the ontology
+already has a relation to `Raum`, so a good run widens `betrifft_raum`. A new
+relation from `Mangel` to `Raum` with another name (`liegt_in`,
+`befindet_sich_in`) is a synonym of it.
+
+## Proposals a good run may make
+
+- Add property `einstufung` (keyword: `wesentlich`, `unwesentlich`) to
+  `Mangel`. Only text 5 gives it: "die Bauleitung stuft diesen Mangel als
+  unwesentlich ein".
+- Add property `beschreibung` (text) to `Mangel`.
+- Add relation `stellt_fest` from `Baustellenbericht` to `Mangel`, for the
+  report that records a defect.
+- Add class `Bauteil`, for the part a defect concerns (Bodenfliesen, Spiegel,
+  Trennwand).
+- Add class `Abnahme` with a date. Only text 5 names it.
+- Add class `Lieferung` with a `liefertermin` (datetime). Texts 2 and 4 give
+  the delivery date of the ceiling lights.
+
+## Proposals a good run does not make
+
+- A relation from `Baustellenbericht` to `Firma` for the companies present
+  ("Anwesend: …", "Teilnehmer: …"). `anwesend` holds it; the check drops
+  such a change as `already_covered`.
+- A property for the date of a report. `datum` holds it.
+- A class for one company, one room or one defect (`Fliesenbau Muster GmbH`,
+  `Flur 0.10`, `Trennwand Kabine 2`). These are instances.
+- A second name for a change the run proposes: `Maengel` or `Defect` beside
+  `Mangel`, `deadline` beside `frist`, `verantwortlich` beside `zustaendig`.
+
+## How to check a run
+
+1. Every change in "Proposals a good run makes" is filed.
+2. No change in "Proposals a good run does not make" is filed.
+3. Every filed quote is in its text, with whitespace runs as one space, and
+   holds at least three words.

package/templates/ontology-fit/samples/texts.json

@@ -0,0 +1,22 @@
+[
+  {
+    "name": "Baustellenbericht 12",
+    "text": "Baustellenbericht 12 vom 02.09.2026. Begehung des Erdgeschosses mit der Bauleitung. Anwesend: Fliesenbau Muster GmbH, Bodenbau Beispiel GmbH. In Raum 0.14 (WC Mädchen) sind zwei Bodenfliesen gerissen. Der Mangel wurde der Fliesenbau Muster GmbH gemeldet, die Frist zur Beseitigung endet am 16.09.2026. In Raum 0.12 ist der Estrich trocken; die Bodenbau Beispiel GmbH verlegt das Linoleum ab dem 07.09.2026."
+  },
+  {
+    "name": "Baubesprechung 05.09.2026",
+    "text": "Protokoll der Baubesprechung vom 05.09.2026. Teilnehmer: Bauleitung, Elektro Beispiel GmbH, Haustechnik Exempel KG. Die Elektro Beispiel GmbH meldet, dass die Deckenleuchten erst am 21.09.2026 geliefert werden. Die Haustechnik Exempel KG hat die Waschtische im Erdgeschoss montiert. Mangel: In Raum 0.12 fehlt der Spiegel über dem Waschtisch. Zuständig ist die Haustechnik Exempel KG, Frist 12.09.2026."
+  },
+  {
+    "name": "Baustellenbericht 13",
+    "text": "Baustellenbericht 13 vom 09.09.2026. Mängelbegehung in Raum 0.14: Die gerissenen Bodenfliesen sind ersetzt, der Mangel ist behoben. Neu festgestellt: Die Trennwand der WC-Kabine 2 in Raum 0.14 steht schief. Zuständig ist die Trockenbau Probe GmbH, Frist 23.09.2026, Status offen."
+  },
+  {
+    "name": "Baustellenbericht 14",
+    "text": "Baustellenbericht 14 vom 16.09.2026. In Raum 0.12 ist der Spiegel montiert, der Mangel ist behoben. Im Flur 0.10 hat das Linoleum an zwei Stellen tiefe Kratzer. Zuständig ist die Bodenbau Beispiel GmbH, Frist 30.09.2026, Status offen. Die Deckenleuchten sind geliefert und werden bis zum 25.09.2026 montiert."
+  },
+  {
+    "name": "Vorbegehung zur Abnahme",
+    "text": "Vorbegehung zur Abnahme am 28.09.2026 mit Bauherr und Bauleitung. Die Trennwand der Kabine 2 in Raum 0.14 ist ausgerichtet, der Mangel ist behoben. Offen bleiben die Kratzer im Flur 0.10; die Bauleitung stuft diesen Mangel als unwesentlich ein. Wesentliche Mängel liegen nicht vor. Die Abnahme ist für den 02.10.2026 geplant."
+  }
+]