@littlebigbrain/create 0.4.0 → 0.6.0

package/templates/sections/workflow.ts

@@ -19,13 +19,19 @@
 //    to 44);
 // 4. with `represents`, writes `Document REPRESENTS <instance>` when the
 //    file's name names exactly one instance of that class;
-// 5. records the derivation.
+// 5. records the derivation, for the upload its check named. When the file
+//    was deleted (or deleted and uploaded again) since, nothing is recorded,
+//    and the run of the new upload reads the file again. A file deleted and
+//    not uploaded again answers 404 to the next read of its bytes: the run
+//    ends there and counts the file as skipped.
 //
 // A turn writes at most `sectionsPerTurn` sections; the rest goes to a new
 // turn (`ctx.continue`).
 import { createHash } from "node:crypto";
 import {
+  LbbError,
   entityRef,
+  isDerivationUploadChanged,
   triggeredWorkflow,
   type LbbActivities,
   type Schemas,
@@ -121,7 +127,7 @@ export interface ContentPorts {
 export interface SectionsState {
   /** Files read to their end. */
   contents: number;
-  /** Files skipped: read before with these settings, another name or type, or no file. */
+  /** Files skipped: read before with these settings, another name or type, no file, or deleted while read. */
   skipped: number;
   sections: number;
   represents: number;
@@ -135,9 +141,11 @@ interface FileInfo {
   mediaType: string;
 }
 
-/** What the check of a file found: the file to read, or why it is skipped. */
+/** What the check of a file found: the file to read and its upload, or why it is skipped. */
 interface Checked {
   file?: FileInfo;
+  /** The `content_uploaded_at` of the check: absent without a file record. */
+  uploadedAt?: string;
   skip?: string;
 }
 
@@ -148,6 +156,8 @@ interface Plan {
   name: string;
   count: number;
   represents: string | null;
+  /** The upload of the file the check named: the record names it. */
+  uploadedAt?: string;
 }
 
 /** Where a file's next turn starts, and the commits of its writes so far. */
@@ -174,6 +184,10 @@ const LABEL = "http://www.w3.org/2000/01/rdf-schema#label";
 /** The media type without parameters, in lower case. */
 const baseType = (mediaType: string) => mediaType.split(";")[0]!.trim().toLowerCase();
 
+/** Whether an error is the 404 of a file's bytes: the file was deleted and not uploaded again. */
+export const fileGone = (error: unknown) =>
+  error instanceof LbbError && error.status === 404 && error.code === "file_not_found";
+
 /** A file name without its last extension. */
 export const stem = (name: string) => name.replace(/\.[^./\\]*$/, "");
 
@@ -244,108 +258,133 @@ export function createWorkflow(
         delete plain.cursor;
         return ctx.continue(next, plain);
       };
-      const document = message.instances[0];
-      if (!document) return { state };
-      let split: Promise<Section[]> | undefined;
-      const sectionsOf = (sha256: string, name: string) =>
-        (split ??= ports.files
-          .content(sha256)
-          .then((bytes) => markdownSections(new TextDecoder().decode(bytes), stem(name))));
-
-      let cursor = message.cursor;
-      if (!cursor) {
-        const checked = await ctx.step("check", async (s): Promise<Checked> => {
-          s.progress("checking the file", { done: 0, total: 1, unit: "documents" });
-          const file = await readDocument(message, document);
-          if (!file) return { skip: "no file" };
-          if (!isMarkdown(file.mediaType, file.name)) return { skip: "media type" };
-          if (match && !match.test(file.name)) return { skip: "name" };
-          const found = await ports.workflows.derivations.check(
-            derivationKey(file.sha256, settings),
-          );
-          return found.exists ? { skip: "derived" } : { file };
-        });
-        if (!checked.file) return rest({ ...state, skipped: state.skipped + 1 });
-        const file = checked.file;
-        const planned = await ctx.step("plan", async (s) => {
-          s.progress("reading sections", { done: 0, unit: "sections" });
-          const count = (await sectionsOf(file.sha256, file.name)).length;
-          s.progress("reading sections", { done: count, total: count, unit: "sections" });
-          const found = settings.represents ? await representsOf(file.name) : null;
-          const plan: Plan = { ...file, count, represents: found?.iri ?? null };
-          return { plan, label: found?.label ?? null };
-        });
-        const commits: number[] = [];
-        const p = planned.plan;
-        if (p.represents) {
-          const written = await lbb.writeOwned(ctx, "represents", (s) => {
-            s.progress("writing facts", { done: 0, total: 1, unit: "documents" });
-            return {
-              subjects: [entityRef(p.document, "Document", p.name)],
-              relations: [REPRESENTS],
-              triplets: [
-                {
-                  source: entityRef(p.document, "Document", p.name),
-                  relation: REPRESENTS,
-                  target: entityRef(
-                    p.represents!,
-                    settings.represents!.class,
-                    planned.label ?? undefined,
-                  ),
-                  confidence: 1,
-                  evidence: { text: p.name, source_id: p.document },
-                },
-              ],
+      try {
+        const document = message.instances[0];
+        if (!document) return { state };
+        let split: Promise<Section[]> | undefined;
+        const sectionsOf = (sha256: string, name: string) =>
+          (split ??= ports.files
+            .content(sha256)
+            .then((bytes) => markdownSections(new TextDecoder().decode(bytes), stem(name))));
+
+        let cursor = message.cursor;
+        if (!cursor) {
+          const checked = await ctx.step("check", async (s): Promise<Checked> => {
+            s.progress("checking the file", { done: 0, total: 1, unit: "documents" });
+            const file = await readDocument(message, document);
+            if (!file) return { skip: "no file" };
+            if (!isMarkdown(file.mediaType, file.name)) return { skip: "media type" };
+            if (match && !match.test(file.name)) return { skip: "name" };
+            const found = await ports.workflows.derivations.check(
+              derivationKey(file.sha256, settings),
+            );
+            if (found.exists) return { skip: "derived" };
+            const uploadedAt = found.content_uploaded_at ?? undefined;
+            return uploadedAt ? { file, uploadedAt } : { file };
+          });
+          if (!checked.file) return rest({ ...state, skipped: state.skipped + 1 });
+          const file = checked.file;
+          const planned = await ctx.step("plan", async (s) => {
+            s.progress("reading sections", { done: 0, unit: "sections" });
+            const count = (await sectionsOf(file.sha256, file.name)).length;
+            s.progress("reading sections", { done: count, total: count, unit: "sections" });
+            const found = settings.represents ? await representsOf(file.name) : null;
+            const plan: Plan = {
+              ...file,
+              count,
+              represents: found?.iri ?? null,
+              ...(checked.uploadedAt ? { uploadedAt: checked.uploadedAt } : {}),
             };
+            return { plan, label: found?.label ?? null };
+          });
+          const commits: number[] = [];
+          const p = planned.plan;
+          if (p.represents) {
+            const written = await lbb.writeOwned(ctx, "represents", (s) => {
+              s.progress("writing facts", { done: 0, total: 1, unit: "documents" });
+              return {
+                subjects: [entityRef(p.document, "Document", p.name)],
+                relations: [REPRESENTS],
+                triplets: [
+                  {
+                    source: entityRef(p.document, "Document", p.name),
+                    relation: REPRESENTS,
+                    target: entityRef(
+                      p.represents!,
+                      settings.represents!.class,
+                      planned.label ?? undefined,
+                    ),
+                    confidence: 1,
+                    evidence: { text: p.name, source_id: p.document },
+                  },
+                ],
+              };
+            });
+            if (written.commit_seq !== null) commits.push(written.commit_seq);
+          }
+          cursor = { next: 0, plan: p, commits };
+        }
+
+        // The sections of this turn, written in parts.
+        const { plan, next: from } = cursor;
+        const to = Math.min(plan.count, from + settings.sectionsPerTurn);
+        const commits = [...cursor.commits];
+        for (let n = 0; from + n * PART < to; n++) {
+          const written = await lbb.writeOwned(ctx, `write-${n}`, async (s) => {
+            s.progress("writing facts", { done: n * PART, total: to - from, unit: "sections" });
+            const all = await sectionsOf(plan.sha256, plan.name);
+            const start = from + n * PART;
+            return partWrite(plan, all, all.slice(start, Math.min(to, start + PART)));
           });
           if (written.commit_seq !== null) commits.push(written.commit_seq);
         }
-        cursor = { next: 0, plan: p, commits };
-      }
+        const counted = { ...state, sections: state.sections + (to - from) };
+        if (to < plan.count)
+          return ctx.continue(counted, {
+            ...message,
+            removed: [],
+            cursor: { next: to, plan, commits: commits.slice(0, 256) },
+          });
 
-      // The sections of this turn, written in parts.
-      const { plan, next: from } = cursor;
-      const to = Math.min(plan.count, from + settings.sectionsPerTurn);
-      const commits = [...cursor.commits];
-      for (let n = 0; from + n * PART < to; n++) {
-        const written = await lbb.writeOwned(ctx, `write-${n}`, async (s) => {
-          s.progress("writing facts", { done: n * PART, total: to - from, unit: "sections" });
-          const all = await sectionsOf(plan.sha256, plan.name);
-          const start = from + n * PART;
-          return partWrite(plan, all, all.slice(start, Math.min(to, start + PART)));
+        const recorded = await ctx.step("record", async (s) => {
+          s.progress("recording the derivation", { done: 0, total: 1, unit: "documents" });
+          const all = plan.count ? await sectionsOf(plan.sha256, plan.name) : [];
+          const levels: Record<string, number> = {};
+          for (const section of all) levels[section.level] = (levels[section.level] ?? 0) + 1;
+          try {
+            const answer = await ports.workflows.derivations.record({
+              ...derivationKey(plan.sha256, settings),
+              run_id: ctx.messageId,
+              outputs: {
+                sections: plan.count,
+                levels,
+                represents: plan.represents,
+                commits: commits.slice(0, 256),
+              },
+              ...(plan.uploadedAt ? { content_uploaded_at: plan.uploadedAt } : {}),
+            });
+            return answer.recorded;
+          } catch (error) {
+            // The file was deleted while this run read it: nothing is
+            // recorded, and the run of a new upload reads it again.
+            if (isDerivationUploadChanged(error)) return "upload changed";
+            throw error;
+          }
         });
-        if (written.commit_seq !== null) commits.push(written.commit_seq);
-      }
-      const counted = { ...state, sections: state.sections + (to - from) };
-      if (to < plan.count)
-        return ctx.continue(counted, {
-          ...message,
-          removed: [],
-          cursor: { next: to, plan, commits: commits.slice(0, 256) },
+        if (recorded === "upload changed")
+          return rest({ ...counted, skipped: counted.skipped + 1 });
+        return rest({
+          ...counted,
+          contents: counted.contents + 1,
+          represents: counted.represents + (plan.represents ? 1 : 0),
         });
-
-      await ctx.step("record", async (s) => {
-        s.progress("recording the derivation", { done: 0, total: 1, unit: "documents" });
-        const all = plan.count ? await sectionsOf(plan.sha256, plan.name) : [];
-        const levels: Record<string, number> = {};
-        for (const section of all) levels[section.level] = (levels[section.level] ?? 0) + 1;
-        const recorded = await ports.workflows.derivations.record({
-          ...derivationKey(plan.sha256, settings),
-          run_id: ctx.messageId,
-          outputs: {
-            sections: plan.count,
-            levels,
-            represents: plan.represents,
-            commits: commits.slice(0, 256),
-          },
-        });
-        return recorded.recorded;
-      });
-      return rest({
-        ...counted,
-        contents: counted.contents + 1,
-        represents: counted.represents + (plan.represents ? 1 : 0),
-      });
+      } catch (error) {
+        // The file was deleted while this run read it, and not uploaded
+        // again: its bytes answer 404. Nothing is recorded, and the file
+        // counts as skipped.
+        if (!fileGone(error)) throw error;
+        return rest({ ...state, skipped: state.skipped + 1 });
+      }
     },
   });
 

package/templates/values-extract/README.md

@@ -11,31 +11,73 @@ The LBB-run version is the starter workflow `values.extract@v1`
 
 ## How it runs
 
+The template follows the rules of LBB's version
+(`lbb-graph-query/src/infer_llm.rs`). Its eval runs both on the same
+recorded model answers and finds the same calls and outputs
+([`../_evals/README.md`](../_evals/README.md)).
+
 The triggered workflow watches the class and its text field. For each
 instance of a trigger message, two steps:
 
-1. **Values.** The reasoning model reads the text and returns
-   `{values: [{property, value, quote}]}`; the schema allows only the
-   settings' property names. The prompt is the LBB version's: the values of
-   the instance's own item in its base version, not those of a part, an
-   accessory, an alternative or a variant under a condition; an approximate
-   value is stated. Then the checks without a model: a value takes its
-   property's type (`typed`), its quote is in the text with at least three
-   words or the value in it (`quoteHolds`), and one value per property.
+1. **Values.** The text is the field's values as LBB composes it
+   (`text: <values>`, each value's whitespace as single spaces). The
+   reasoning model reads it and returns `{values: [{property, value, unit,
+   quote}]}`; the schema allows only the settings' property names, in name
+   order, and a number property names its unit. A number comes as the text
+   states it, with its unit, and the model never converts it. The prompt is
+   the LBB version's: the values of the instance's own item in its base
+   version, not those of a part, an accessory, an alternative or a variant
+   under a condition; an approximate value is stated. Then the checks
+   without a model, in LBB's order (`check`): the property is one the
+   workflow fills (else `unknown_property`), the value is the first of its
+   property (else `duplicate`), it takes its property's type (else
+   `invalid_value`), and its quote is in the text with at least three words
+   or the value in it (else `quote_not_found`). A number of a property with
+   a unit must come in that unit, with the unit in its quote
+   (`unitProblem`); otherwise it goes to review at most, with LBB's reason.
 2. **Support.** The decision model scores how well each quote supports its
    value: `supported`, `weak` or `not_supported`. The support is the
    probability of `supported`.
 
-Then the gate: a value at or above `gate` is written, one from 0.5 to the
-gate becomes a review item with the value as its facts, one below 0.5 is
-dropped. One owned write per turn replaces the values of the turn's
-instances: a property the workflow does not write again loses its value and
-its source. An accepted review item's value is written with the others the
-next time its instance is read. An instance that leaves the class loses the
-values this workflow wrote.
-
-A turn reads at most 24 instances; the rest of a message goes to a new turn
-(`ctx.continue`).
+Then the gate: a value at or above `gate` is `written`, one from 0.5 to the
+gate goes to `review`, one below 0.5 or without an answer is
+`weak_support` and is dropped. A value in review becomes a `value` review
+item (`lbb.review({ kind: "value" })`) with the property's unit and the
+quote, one per property of an instance, under LBB's key
+`starter:<workflow>:value:<hash of instance and property>` (`valueItemKey`,
+with `stableHashHex`). One owned write per turn replaces the values of the
+turn's instances: a property the workflow does not write again loses its
+value and its source. Each value's evidence is its quote, with the
+instance's page box as its region when the instance has one (`page`, `x0`,
+`y0`, `x1`, `y1`, as a `DocEntry` has).
+
+Before it writes, the workflow reads the items (`lbb.reviewItems(keys)`): a
+person's answer wins over the model, for the evidence it was given on
+(`evidence_hash`: a hash of the value's quote and of the unit the text
+states, `evidenceOf`). With the same evidence, the value in force, or the
+value the person decided on, a value a person accepted, or corrected with
+a number in the property's unit, is written as answered. New evidence that
+reads another value asks the person again, and the answered value and its
+source link stay (the instance is written on its own, without that
+property) until a new answer is written. A value a person rejected is
+not written again, nor is one the graph refused (`effects.commit_error`; the
+item is open again for the person). An earlier version filed a value in
+review as a suggestion, one per value (`legacyValueKey`): an accepted one is
+written again, an open one stays the question, and a dismissed one is a
+reject of its value. An instance that leaves the class keeps its values:
+they go with its fields when it is retracted.
+
+The write's request id is its step's effect id, which no other turn
+repeats, so a value that changes back (A, then B, then A) is written again.
+When a model call is refused, the instance goes back to the watch
+(`lbb.requeue`, after 1, 4 and 16 minutes, at most 3 times) and keeps its
+values; the turn completes and the shard goes on. A spent budget fails the
+turn with the time to retry, and the worker waits without an attempt.
+
+The state counts what LBB's version counts: `instances`,
+`values_proposed`, one counter per outcome, `failed`, `commits` and
+`removed`. A turn reads at most 24 instances; the rest of a message goes to
+a new turn (`ctx.continue`).
 
 ## Settings
 
@@ -48,6 +90,7 @@ A turn reads at most 24 instances; the rest of a message goes to a new turn
 | `properties` | `width_cm`, `depth_cm` (`f64`), `material` (`text`), `water_supply` (`keyword`) | The properties to fill, with their types (`text`, `keyword`, `i64`, `f64`, `bool`, `date_time`) |
 | `context` | the samples' | One sentence about what the text is |
 | `gate` | 0.8 | The support a value needs to be written |
+| `units` | `width_cm`, `depth_cm`: `cm` | The unit of each number property; `ontology()` declares it on the property |
 
 `trigger(settings)` names the triggered workflow `values-extract` and
 owns the class `ValueSource`, the relation `HAS_VALUE_SOURCE` and the
@@ -57,14 +100,22 @@ relation.
 ## What the LBB-run version adds
 
 - `params.where`: a SPARQL pattern that limits the instances it reads.
-- Texts built from several watched fields, as fit sources build them, and
-  the fields chosen for you when the watch names none.
-- The instance's page box as the region of each value's evidence, for an
-  instance that has one (a `DocEntry`).
+- Texts built from several watched fields, and the fields chosen for you
+  when the watch names none.
 - A check at creation that each property is in the property registry with
   a type it can write.
 - Its own monthly budget, a preview with the values of up to 3 instances,
-  and counters per outcome in the workflow's status.
+  and its counters in the workflow's status.
+
+It differs in three places. It commits once per instance, the template once
+per turn, so its `commits` counter is larger. When the reasoning model gives
+no usable answer, it counts the instance `failed` and clears its values; the
+template sends the instance back to the watch and keeps them. And it
+converts a number the text states in another unit of the same kind (`600 mm`
+for a property in `cm`) to the unit the property declares, and refuses a
+unit it does not know or of another kind; the template sends such a number
+to review. So the question of such a number differs: LBB's item asks the
+converted value, the template's the value as stated.
 
 ## Samples and test
 
@@ -79,3 +130,21 @@ or a conditional variant (`Bei Einsatz`) does not support its value. The run
 writes the values of the answer key and none it leaves out. The test also
 checks the review path, the checks of type and quote, an instance that
 leaves the class, and a message larger than a turn.
+
+## Test on examples
+
+`npm run test:examples` runs the workflow on instances of your graph with
+the real models, and writes nothing (`test-examples.ts`). The activities go
+through `captureActivities`: the server checks each owned write with the
+commit's dry run, and keeps it. Each review item is kept too. The script
+prints, for each input, the values the workflow would write and the values
+it would give a person to review.
+
+```sh
+LBB_URL=... LBB_API_KEY=... LBB_GRAPH=tender npm run test:examples           # the first 6 instances
+LBB_URL=... LBB_API_KEY=... LBB_GRAPH=tender npm run test:examples -- <iri>  # chosen instances
+```
+
+The model calls count in your environment's budget. For the LBB-run
+version, test the workflow in the console (the workflow's Test tab) or with
+`client.workflows.tests`.

package/templates/values-extract/samples/expected.json

@@ -12,6 +12,7 @@
       "material": "text",
       "water_supply": "keyword"
     },
+    "units": { "width_cm": "cm", "depth_cm": "cm" },
     "context": "Entries of the sanitary equipment list of a school building tender, in German."
   },
   "records": [

package/templates/values-extract/test-examples.ts

@@ -0,0 +1,155 @@
+// Test the workflow on examples before it writes. `npm run test:examples`
+// runs it with the real models on chosen instances of your graph, through
+// `captureActivities`, which writes nothing: each owned write is checked
+// with the commit's dry run and kept, and each review item is kept. Then it
+// prints, per input, the values the workflow would write and the values it
+// would give a person to review.
+//
+//   LBB_URL=... LBB_API_KEY=... LBB_GRAPH=... npm run test:examples -- [<iri> …]
+//
+// Without IRIs it tests the first 6 instances of the class. The model calls
+// count in your environment's budget.
+import { pathToFileURL } from "node:url";
+import {
+  LbbClient,
+  captureActivities,
+  entityIdFromIri,
+  lbbActivities,
+  type ActivityCaptureResult,
+  type LbbActivities,
+  type WorkflowTriggerMessage,
+} from "@littlebigbrain/client";
+import { runMessage } from "../_shared/testing.js";
+import { createWorkflow, defaults, type Settings } from "./workflow.js";
+
+/** A value the workflow would write. */
+export interface ExampleValue {
+  property: string;
+  value: string;
+  quote?: string;
+  support?: number;
+}
+
+/** What the workflow would do with one input. */
+export interface ExampleResult {
+  iri: string;
+  /** Values at or above the gate, which it writes. */
+  written: ExampleValue[];
+  /** Values it gives a person to review: each item's title. */
+  review: string[];
+  /** Why the server's dry run (or the local check) refused a write. */
+  errors: string[];
+}
+
+/** The first `limit` instances of the class, and the commit they were read at. */
+export async function firstInstances(
+  client: LbbClient,
+  settings: Settings = defaults,
+  limit = 6,
+): Promise<{ iris: string[]; seq: number }> {
+  const read = await client.sparqlRows({
+    query: `SELECT ?s WHERE { ?s a <https://littlebigbrain.com/class/${encodeURIComponent(settings.className.toLowerCase())}> } LIMIT ${limit}`,
+  });
+  return {
+    iris: read.rows.map((row) => row.s!).filter(Boolean),
+    seq: read.snapshot?.served_at_seq ?? 0,
+  };
+}
+
+/** Per input, what the captured writes and review items say. */
+export function resultsOf(iris: string[], captured: ActivityCaptureResult): ExampleResult[] {
+  return iris.map((iri) => {
+    const id = entityIdFromIri(iri);
+    const mine = (key: string | null | undefined) => key?.startsWith(`value:${id}:`) ?? false;
+    const written: ExampleValue[] = [];
+    const errors: string[] = [];
+    for (const write of captured.writes) {
+      const about = (write.body.triplets ?? []).filter(
+        (edge) => edge.relation === "HAS_VALUE_SOURCE" && mine(edge.target.key),
+      );
+      if (about.length) errors.push(...write.errors);
+      for (const edge of about) {
+        const source = (write.body.entity_properties ?? []).find(
+          (entity) => entity.type === "ValueSource" && entity.key === edge.target.key,
+        );
+        const properties = (source?.properties ?? {}) as Record<string, unknown>;
+        const quote = typeof edge.evidence === "object" ? edge.evidence?.text : undefined;
+        written.push({
+          property: String(properties.property ?? edge.target.key?.split(":")[2] ?? ""),
+          value: String(properties.value ?? ""),
+          ...(quote ? { quote } : {}),
+          ...(edge.confidence != null ? { support: edge.confidence } : {}),
+        });
+      }
+    }
+    const review = captured.reviews
+      .filter((item) => item.request.key?.includes(`:value:${id}:`))
+      .map((item) => item.request.title);
+    return { iri, written, review, errors };
+  });
+}
+
+/**
+ * Run the workflow on `iris` with `activities` captured
+ * (`captureActivities`): the models run, and nothing is written. `seq` is
+ * the commit the workflow reads the texts at.
+ */
+export async function testExamples(
+  activities: LbbActivities,
+  iris: string[],
+  options: { settings?: Settings; seq?: number; graph?: string } = {},
+): Promise<ExampleResult[]> {
+  const settings = options.settings ?? defaults;
+  const capture = captureActivities(activities, { workflow: "values-extract" });
+  const message: WorkflowTriggerMessage = {
+    type: "instances",
+    workflow: "values-extract-test",
+    graph: options.graph ?? "main",
+    as_of_commit_seq: options.seq ?? 0,
+    reason: "refresh",
+    instances: iris,
+    removed: [],
+  };
+  await runMessage(createWorkflow(capture.activities, settings), message);
+  return resultsOf(iris, capture.result());
+}
+
+/** The results as lines of text. */
+export function report(results: ExampleResult[]): string[] {
+  const lines: string[] = [];
+  for (const result of results) {
+    lines.push(result.iri);
+    for (const value of result.written)
+      lines.push(
+        `  write   ${value.property} = ${value.value}${value.support != null ? ` (support ${value.support.toFixed(2)})` : ""}${value.quote ? ` "${value.quote}"` : ""}`,
+      );
+    for (const title of result.review) lines.push(`  review  ${title}`);
+    if (!result.written.length && !result.review.length) lines.push("  no value");
+    for (const error of result.errors) lines.push(`  refused ${error}`);
+  }
+  return lines;
+}
+
+async function main() {
+  const graph = process.env.LBB_GRAPH;
+  if (!graph) throw new Error("set LBB_GRAPH to the graph to test on");
+  const client = new LbbClient({
+    baseUrl: process.env.LBB_URL ?? "http://127.0.0.1:7400",
+    apiKey: process.env.LBB_API_KEY,
+    graph,
+  });
+  const named = process.argv.slice(2).filter((arg) => !arg.startsWith("-"));
+  const first = await firstInstances(client);
+  const iris = named.length ? named : first.iris;
+  if (!iris.length) throw new Error(`the graph ${graph} has no ${defaults.className} to test`);
+  const results = await testExamples(lbbActivities(client), iris, { seq: first.seq, graph });
+  for (const line of report(results)) console.log(line);
+  console.log("Nothing was written.");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  });
+}