@prosopo/datasets-fs 3.0.43 → 3.0.77

package/src/commands/generateV2.ts

@@ -0,0 +1,293 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import fs from "node:fs";
+import { ProsopoDatasetError } from "@prosopo/common";
+import {
+	CaptchaTypes,
+	type CaptchaWithoutId,
+	type Captchas,
+	CaptchasContainerSchema,
+	type Item,
+	type RawSolution,
+} from "@prosopo/types";
+import { at, get } from "@prosopo/util";
+import { blake2AsHex } from "@prosopo/util-crypto";
+import { lodash } from "@prosopo/util/lodash";
+import bcrypt from "bcrypt";
+import cliProgress from "cli-progress";
+import * as z from "zod";
+import { Generate, ArgsSchema as GenerateArgsSchema } from "./generate.js";
+
+export const ArgsSchema = GenerateArgsSchema.extend({
+	minCorrect: z.number().optional(),
+	minIncorrect: z.number().optional(),
+	minLabelled: z.number().optional(),
+	maxLabelled: z.number().optional(),
+	count: z.number().optional(),
+});
+export type ArgsSchemaType = typeof ArgsSchema;
+export type Args = z.infer<ArgsSchemaType>;
+
+export class GenerateV2 extends Generate<ArgsSchemaType> {
+	#size = 0;
+	#minCorrect = 0;
+	#saltRounds = 10;
+	#allowDuplicatesLabelled = false;
+	#allowDuplicatesUnlabelled = false;
+	#minIncorrect = 0;
+	#minLabelled = 0;
+	#maxLabelled = 0;
+	#count = 0;
+	#nCorrect = 0;
+	#nIncorrect = 0;
+	#nLabelled = 0;
+	#nUnlabelled = 0;
+	#target = "";
+	#targets: string[] = [];
+	#targetItems: Item[] = [];
+	#notTargetItems: Item[] = [];
+
+	public override getArgSchema() {
+		return ArgsSchema;
+	}
+
+	public override getDescription(): string {
+		return "Generate distinct captchas producing captcha challenges comprising one or more rounds, mixing labelled and unlabelled data into a single round";
+	}
+
+	public override getOptions() {
+		return lodash().merge(super.getOptions(), {
+			count: {
+				number: true,
+				description: "Number of captchas to generate",
+			},
+			minCorrect: {
+				number: true,
+				description: "Minimum number of correct images in each captcha",
+			},
+			minIncorrect: {
+				number: true,
+				description: "Minimum number of incorrect images in each captcha",
+			},
+			minLabelled: {
+				number: true,
+				description: "Minimum number of labelled images in each captcha",
+			},
+			maxLabelled: {
+				number: true,
+				description: "Maximum number of labelled images in each captcha",
+			},
+		});
+	}
+
+	private setupTarget(i: number) {
+		const _ = lodash();
+		if (this.targets.length <= 1) {
+			throw new ProsopoDatasetError(
+				new Error("not enough different labels in labelled data"),
+				{
+					translationKey: "DATASET.NOT_ENOUGH_LABELS",
+				},
+			);
+		}
+
+		// uniformly sample targets
+		const target = at(this.targets, i % this.targets.length);
+		const notTargets = this.targets.filter((t) => t !== target);
+		// how many labelled images should be in the captcha?
+		const nLabelled = this.unlabelled.length
+			? _.random(this.#minLabelled, this.#maxLabelled)
+			: this.#size;
+		// how many correct labelled images should be in the captcha?
+		const maxCorrect = nLabelled - this.#minCorrect;
+		const nCorrect = _.random(this.#minCorrect, maxCorrect);
+		const nIncorrect = nLabelled - nCorrect;
+		const nUnlabelled = this.#size - nLabelled;
+
+		const targetItems = get(this.labelToImages, target);
+		const notTargetItems: Item[] = notTargets.flatMap((notTarget) =>
+			get(this.labelToImages, notTarget),
+		);
+
+		if (this.unlabelled.length > 0 && nUnlabelled > this.unlabelled.length) {
+			throw new ProsopoDatasetError(new Error("not enough unlabelled data"), {
+				translationKey: "DATASET.NOT_ENOUGH_IMAGES",
+			});
+		}
+		if (nCorrect > targetItems.length) {
+			throw new ProsopoDatasetError(
+				new Error(`not enough images for target (${target})`),
+				{
+					translationKey: "DATASET.NOT_ENOUGH_IMAGES",
+				},
+			);
+		}
+		if (nIncorrect > notTargetItems.length) {
+			throw new ProsopoDatasetError(
+				new Error(`not enough non-matching images for target (${target})`),
+				{
+					translationKey: "DATASET.NOT_ENOUGH_IMAGES",
+				},
+			);
+		}
+
+		this.#nCorrect = nCorrect;
+		this.#nIncorrect = nIncorrect;
+		this.#nLabelled = nLabelled;
+		this.#nUnlabelled = nUnlabelled;
+		this.#target = target;
+		this.#targets = notTargets;
+		this.#targetItems = targetItems;
+		this.#notTargetItems = notTargetItems;
+	}
+
+	public override async _run(args: Args) {
+		await super._run(args);
+
+		const outFile: string = args.output;
+
+		// get lodash (with seeded rng)
+		const _ = lodash();
+
+		this.#size = args.size || 9;
+		this.#minCorrect = args.minCorrect || 1;
+		this.#saltRounds = 10;
+		this.#allowDuplicatesLabelled =
+			args.allowDuplicatesLabelled || args.allowDuplicates || false;
+		this.#allowDuplicatesUnlabelled =
+			args.allowDuplicatesUnlabelled || args.allowDuplicates || false;
+		this.#minIncorrect = Math.max(args.minIncorrect || 1, 1); // at least 1 incorrect image
+		this.#minLabelled = this.#minCorrect + this.#minIncorrect; // min incorrect + correct
+		this.#maxLabelled = Math.min(args.maxLabelled || this.#size, this.#size); // at least 1 labelled image
+		this.#count = args.count || 0;
+
+		// the captcha contains n images. Each of these images are either labelled, being correct or incorrect against the target, or unlabelled. To construct one of these captchas, we need to decide how many of the images should be labelled vs unlabelled, and then how many of the labelled images should be correct vs incorrect
+		// in the traditional captcha, two rounds are produced, one with labelled images and the other with unlabelled images. This gives 18 images overall, 9 labels produced.
+		// the parameters for generation can regulate how many labels are collected vs how much of a test the captcha posses. E.g. 18 images could have 16 unlabelled and 2 labelled, or 2 unlabelled and 16 labelled. The former is a better test of the user being human, but the latter is a better for maximising label collection.
+		// if we focus on a single captcha round of 9 images, we must have at least 1 labelled correct image in the captcha for it to work, otherwise it's just a labelling phase, which normally isn't a problem but if we're treating these as tests for humanity too then we need some kind of test in there. (e.g. we abolish the labelled then unlabelled pattern of the challenge rounds in favour of mixing labelled and unlabelled data, but we then run a small chance of serving two completely unlabelled rounds if we don't set the min number of labelled images to 1 per captcha round)
+
+		const bar = new cliProgress.SingleBar(
+			{},
+			cliProgress.Presets.shades_classic,
+		);
+		bar.start(this.#count, 0);
+
+		// generate n captchas
+		const captchas: CaptchaWithoutId[] = [];
+		for (let i = 0; i < this.#count; i++) {
+			bar.increment();
+			// this.logger.info(`generating captcha ${i + 1} of ${count}`)
+			this.setupTarget(i);
+
+			// get the correct items
+			const correctItems: Item[] = _.sampleSize(
+				this.#targetItems,
+				this.#nCorrect,
+			);
+
+			// get the incorrect items
+			const incorrectItems: Item[] = _.sampleSize(
+				this.#notTargetItems,
+				this.#nIncorrect,
+			);
+
+			// get the unlabelled items
+			const unlabelledItems = new Set<Item>();
+			if (this.unlabelled.length > 0) {
+				while (unlabelledItems.size < this.#size - this.#nLabelled) {
+					// get a random image from the unlabelled data
+					const image = at(
+						this.unlabelled,
+						_.random(0, this.unlabelled.length - 1),
+					);
+					unlabelledItems.add(image);
+				}
+			}
+
+			const itemsConcat: Item[] = [
+				...correctItems,
+				...incorrectItems,
+				...unlabelledItems,
+			];
+			let indices: number[] = [...Array(itemsConcat.length).keys()];
+			indices = _.shuffle(indices);
+			const items = indices
+				.map((i) => at(itemsConcat, i))
+				.map((item) => {
+					return {
+						data: item.data,
+						hash: item.hash,
+						type: item.type,
+					};
+				});
+
+			// the first n indices are the correct items
+			const solution: RawSolution[] = indices
+				.map((index, i) => {
+					return {
+						pre: index, // the index of the item in the items array before shuffle
+						post: i, // the index of the item in the shuffled array
+					};
+				})
+				.filter((item) => item.pre < correctItems.length) // keep all items that were in the first n slots of the original item array - these were the correct items
+				.map((item) => {
+					return item.post; // return the index in the shuffled array
+				});
+
+			// the unlabelled indices were after the correct and incorrect
+			const unlabelledIndices: RawSolution[] = indices
+				.map((index, i) => {
+					return {
+						pre: index, // the index of the item in the items array before shuffle
+						post: i, // the index of the item in the shuffled array
+					};
+				})
+				.filter(
+					(item) => item.pre >= correctItems.length + incorrectItems.length,
+				) // keep all items that were in the first n slots of the original item array - these were the correct items
+				.map((item) => {
+					return item.post; // return the index in the shuffled array
+				});
+
+			const salt = blake2AsHex(bcrypt.genSaltSync(this.#saltRounds));
+			// create the captcha
+			const captcha: CaptchaWithoutId = {
+				salt,
+				target: this.#target,
+				items,
+				solution,
+				unlabelled: unlabelledIndices,
+			};
+			captchas.push(captcha);
+		}
+		bar.stop();
+
+		// write to file
+		const output: Captchas = {
+			captchas,
+			format: CaptchaTypes.SelectAll,
+		};
+
+		// verify the output
+		this.logger.info(() => ({ msg: "verifying data" }));
+		CaptchasContainerSchema.parse(output);
+
+		this.logger.info(() => ({ msg: "writing data" }));
+		fs.mkdirSync(args.output.split("/").slice(0, -1).join("/"), {
+			recursive: true,
+		});
+		fs.writeFileSync(outFile, JSON.stringify(output, null, 4));
+	}
+}

package/src/commands/get.ts

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import { get } from "@prosopo/util";
+import { lodash } from "@prosopo/util/lodash";
+import cliProgress from "cli-progress";
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import * as z from "zod";
+import { InputArgsSchema, InputCliCommand } from "../utils/input.js";
+
+export const ArgsSchema = InputArgsSchema.extend({});
+export type ArgsSchemaType = typeof ArgsSchema;
+export type Args = z.infer<ArgsSchemaType>;
+export class Get extends InputCliCommand<ArgsSchemaType> {
+	public override getArgSchema() {
+		return ArgsSchema;
+	}
+
+	public override getOptions() {
+		return lodash().merge(super.getOptions(), {
+			input: {
+				description: 'JSON file containing urls under a "data" key',
+			},
+		});
+	}
+
+	public override async _run(args: Args) {
+		await super._run(args);
+		const bar = new cliProgress.SingleBar(
+			{},
+			cliProgress.Presets.shades_classic,
+		);
+
+		const list: string[] = [];
+		// biome-ignore lint/suspicious/noExplicitAny: TODO fix
+		const traverse = async (data: any) => {
+			if (Array.isArray(data)) {
+				for (let i = 0; i < data.length; i++) {
+					data[i] = await traverse(data[i]);
+				}
+			} else if (data instanceof Object) {
+				for (const key of Object.keys(data)) {
+					if (key === "data") {
+						const value = get(data, key);
+						const url = z.string().parse(value);
+						list.push(url);
+					} else {
+						await traverse(get(data, key));
+					}
+				}
+			}
+			return data;
+		};
+
+		const file = args.input;
+
+		// read the map file
+		// biome-ignore lint/suspicious/noExplicitAny: TODO fix
+		const data: any = JSON.parse(fs.readFileSync(file, "utf8"));
+		await traverse(data);
+
+		bar.start(list.length, 0);
+		for (const url of list) {
+			bar.increment();
+			if (url.startsWith("http")) {
+				try {
+					const response = await fetch(url);
+					if (!response.ok) {
+						this.logger.error(() => ({
+							url,
+							status: response.status,
+							statusText: response.statusText,
+							msg: `GET ${url} failed`,
+						}));
+					} else {
+						this.logger.info(() => ({ msg: `GET ${url} OK` }));
+					}
+				} catch (err) {
+					this.logger.error(() => ({
+						err,
+						data: { url },
+						msg: `GET ${url} failed`,
+					}));
+				}
+			} else {
+				// resolve locally
+				try {
+					fs.readFileSync(url);
+					this.logger.info(() => ({ msg: `GET ${url} OK` }));
+				} catch (err) {
+					this.logger.error(() => ({
+						err,
+						data: { url },
+						msg: `GET ${url} failed`,
+					}));
+				}
+			}
+		}
+		bar.stop();
+	}
+
+	public override getDescription(): string {
+		return "Test a GET request at image URLs";
+	}
+}

package/src/commands/labels.ts

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import { ProsopoDatasetError } from "@prosopo/common";
+import { LabelledDataSchema, type LabelledItem } from "@prosopo/types";
+import { lodash } from "@prosopo/util/lodash";
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import type * as z from "zod";
+import {
+	InputOutputArgsSchema,
+	InputOutputCliCommand,
+} from "../utils/inputOutput.js";
+
+export const ArgsSchema = InputOutputArgsSchema.extend({});
+export type ArgsSchemaType = typeof ArgsSchema;
+export type Args = z.infer<ArgsSchemaType>;
+
+export class Labels extends InputOutputCliCommand<ArgsSchemaType> {
+	public override getArgSchema() {
+		return ArgsSchema;
+	}
+
+	public override getOptions() {
+		return lodash().merge(super.getOptions(), {
+			input: {
+				description: "JSON file containing labelled data",
+			},
+			output: {
+				description: "Where to put the JSON file containing labels",
+			},
+		});
+	}
+
+	public override async _run(args: Args) {
+		await super._run(args);
+
+		const file = args.input;
+		if (!fs.existsSync(file)) {
+			throw new ProsopoDatasetError(new Error(`file does not exist: ${file}`), {
+				translationKey: "FS.FILE_NOT_FOUND",
+			});
+		}
+
+		const labelled: LabelledItem[] = file
+			? LabelledDataSchema.parse(JSON.parse(fs.readFileSync(file, "utf8")))
+					.items
+			: [];
+
+		const labels = new Set<string>();
+		for (const item of labelled) {
+			labels.add(item.label);
+		}
+		const labelArray = Array.from(labels);
+		labelArray.sort();
+
+		fs.mkdirSync(args.output.split("/").slice(0, -1).join("/"), {
+			recursive: true,
+		});
+		fs.writeFileSync(
+			args.output,
+			JSON.stringify({ labels: labelArray }, null, 4),
+		);
+	}
+
+	public override getDescription(): string {
+		return "get all labels from some data";
+	}
+}

package/src/commands/relocate.ts

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import { get } from "@prosopo/util";
+import { lodash } from "@prosopo/util/lodash";
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import * as z from "zod";
+import {
+	InputOutputArgsSchema,
+	InputOutputCliCommand,
+} from "../utils/inputOutput.js";
+
+export const ArgsSchema = InputOutputArgsSchema.extend({
+	from: z.string(),
+	to: z.string(),
+});
+export type ArgsSchemaType = typeof ArgsSchema;
+export type Args = z.infer<ArgsSchemaType>;
+
+export class Relocate extends InputOutputCliCommand<ArgsSchemaType> {
+	public override getArgSchema() {
+		return ArgsSchema;
+	}
+
+	public override getOptions() {
+		return lodash().merge(super.getOptions(), {
+			input: {
+				description:
+					"A json file containing a list of objects with (at least) a url",
+			},
+			output: {
+				description: "Where to write the new json file containing the new urls",
+			},
+			from: {
+				string: true,
+				demand: true,
+				description: "The string to replace in the urls",
+			},
+			to: {
+				description: "The string to substitute in the urls",
+				string: true,
+				demand: true,
+			},
+		});
+	}
+
+	public override async _run(args: Args) {
+		await super._run(args);
+
+		const replace = (data: unknown, from: string, to: string) => {
+			if (Array.isArray(data)) {
+				for (let i = 0; i < data.length; i++) {
+					data[i] = replace(data[i], from, to);
+				}
+			} else if (typeof data === "object") {
+				const obj = data as {
+					[key: string]: unknown;
+				};
+				for (const key of Object.keys(obj)) {
+					if (key === "data") {
+						const value = get(obj, key);
+						if (typeof value === "string") {
+							if (value.startsWith(from)) {
+								this.logger.debug(() => ({
+									msg: "replacing",
+									data: { value },
+								}));
+								obj[key] = to + value.slice(from.length);
+								this.logger.debug(() => ({
+									msg: "replaced",
+									data: { value: obj[key] },
+								}));
+							}
+						}
+					} else {
+						obj[key] = replace(obj[key], from, to);
+					}
+				}
+			}
+			return data;
+		};
+
+		const file: string = args.input;
+		this.logger.info(() => ({ data: args, msg: "relocate" }));
+		// read the file
+		let data = JSON.parse(fs.readFileSync(file, "utf8"));
+		// replace the urls by recursively traversing the data
+		data = replace(data, args.from, args.to);
+		// write the file
+		fs.mkdirSync(args.output.split("/").slice(0, -1).join("/"), {
+			recursive: true,
+		});
+		fs.writeFileSync(args.output, JSON.stringify(data, null, 4));
+	}
+
+	public override getDescription(): string {
+		return "Relocate urls in a JSON file using string substitution";
+	}
+}