@arkyc/face-match 1.2.10 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Driver-based face matching for [Arkyc](https://github.com/arkstack-hq/arkyc) — an
 open-source, multi-tenant identity-verification platform. Compares the document
-portrait against the selfie; the active driver (`mock` or `external` HTTP) is
+portrait against the selfie; the active driver (`mock`, `external` HTTP, or `local` ONNX models) is
 chosen by config behind a stable result contract.
 
 ## Install

package/dist/drivers/local.d.mts

@@ -0,0 +1,23 @@
+import { FaceEmbedding, FaceMatchConfig, FaceMatchDriver, FaceMatchRequest } from "../types.mjs";
+import { FaceMatchResultData } from "@arkyc/types";
+
+//#region src/drivers/local.d.ts
+/**
+ * Face matching in-process with open models: YuNet finds and aligns the face,
+ * SFace embeds it, and the two embeddings are compared by cosine similarity.
+ * The similarity is mapped to a score where the match threshold sits at 0.6.
+ */
+declare class LocalFaceMatchDriver implements FaceMatchDriver {
+  readonly name = "local";
+  private loaded?;
+  private readonly store;
+  constructor(config: FaceMatchConfig);
+  compare(request: FaceMatchRequest): Promise<FaceMatchResultData>;
+  embed(image: Uint8Array): Promise<(FaceEmbedding & {
+    detection: number;
+  }) | null>;
+  private models;
+}
+//#endregion
+export { LocalFaceMatchDriver };
+//# sourceMappingURL=local.d.mts.map

package/dist/drivers/local.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.mts","names":[],"sources":["../../src/drivers/local.ts"],"mappings":";;;;;;AAsBA;;;cAAa,oBAAA,YAAgC,eAAA;EAAA,SAClC,IAAA;EAAA,QAED,MAAA;EAAA,iBACS,KAAA;cAEL,MAAA,EAAQ,eAAA;EAKd,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;EAqB5C,KAAA,CAAM,KAAA,EAAO,UAAA,GAAa,OAAA,EAAS,aAAA;IAAkB,SAAA;EAAA;EAAA,QAoBnD,MAAA;AAAA"}

package/dist/drivers/local.mjs

@@ -0,0 +1,83 @@
+import { ALIGNED_SIZE, FaceDetector, ModelStore, OnnxModel, alignFace, decodeImage, toTensor } from "@arkyc/vision";
+//#region src/drivers/local.ts
+/** Cosine similarity at which SFace embeddings are the same person (OpenCV's calibrated value). */
+const SFACE_MATCH = .363;
+const MODEL = "sface-2021dec";
+/**
+* Face matching in-process with open models: YuNet finds and aligns the face,
+* SFace embeds it, and the two embeddings are compared by cosine similarity.
+* The similarity is mapped to a score where the match threshold sits at 0.6.
+*/
+var LocalFaceMatchDriver = class {
+	name = "local";
+	loaded;
+	store;
+	constructor(config) {
+		if (!config.modelDirectory) throw new Error("LocalFaceMatchDriver requires config.modelDirectory");
+		this.store = new ModelStore(config.modelDirectory);
+	}
+	async compare(request) {
+		const [portrait, selfie] = await Promise.all([this.embed(request.documentPortrait), this.embed(request.selfie)]);
+		if (!portrait || !selfie) return {
+			passed: false,
+			similarityScore: 0,
+			confidence: 0,
+			raw: {
+				provider: "local",
+				model: MODEL,
+				faceFound: {
+					portrait: !!portrait,
+					selfie: !!selfie
+				}
+			}
+		};
+		const cosine = portrait.vector.reduce((sum, value, i) => sum + value * selfie.vector[i], 0);
+		return {
+			passed: cosine >= SFACE_MATCH,
+			similarityScore: clamp01(.6 + (cosine - SFACE_MATCH) * 1.5),
+			confidence: Math.min(portrait.detection, selfie.detection),
+			raw: {
+				provider: "local",
+				model: MODEL,
+				cosine
+			}
+		};
+	}
+	async embed(image) {
+		if (!image.length) return null;
+		const { detector, recognizer } = await this.models();
+		const decoded = await decodeImage(image);
+		const face = largest(await detector.detect(decoded));
+		if (!face) return null;
+		const aligned = alignFace(decoded, face);
+		const output = Object.values(await recognizer.run(toTensor(aligned, "rgb"), [
+			1,
+			3,
+			ALIGNED_SIZE,
+			ALIGNED_SIZE
+		]))[0];
+		const norm = Math.hypot(...output) || 1;
+		return {
+			vector: Array.from(output, (value) => value / norm),
+			model: MODEL,
+			matchThreshold: SFACE_MATCH,
+			detection: face.score
+		};
+	}
+	models() {
+		this.loaded ??= (async () => ({
+			detector: await FaceDetector.load(this.store.path("yunet")),
+			recognizer: await OnnxModel.load(this.store.path("sface"))
+		}))();
+		return this.loaded;
+	}
+};
+/** The face with the largest box. */
+function largest(faces) {
+	return faces.reduce((best, face) => !best || face.box[2] * face.box[3] > best.box[2] * best.box[3] ? face : best, null);
+}
+const clamp01 = (n) => Math.min(1, Math.max(0, n));
+//#endregion
+export { LocalFaceMatchDriver };
+
+//# sourceMappingURL=local.mjs.map

package/dist/drivers/local.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.mjs","names":[],"sources":["../../src/drivers/local.ts"],"sourcesContent":["import type { FaceMatchResultData } from '@arkyc/types'\nimport {\n  ALIGNED_SIZE,\n  FaceDetector,\n  ModelStore,\n  OnnxModel,\n  alignFace,\n  decodeImage,\n  toTensor,\n  type DetectedFace,\n} from '@arkyc/vision'\nimport type { FaceEmbedding, FaceMatchConfig, FaceMatchDriver, FaceMatchRequest } from '../types'\n\n/** Cosine similarity at which SFace embeddings are the same person (OpenCV's calibrated value). */\nconst SFACE_MATCH = 0.363\nconst MODEL = 'sface-2021dec'\n\n/**\n * Face matching in-process with open models: YuNet finds and aligns the face,\n * SFace embeds it, and the two embeddings are compared by cosine similarity.\n * The similarity is mapped to a score where the match threshold sits at 0.6.\n */\nexport class LocalFaceMatchDriver implements FaceMatchDriver {\n  readonly name = 'local'\n\n  private loaded?: Promise<{ detector: FaceDetector; recognizer: OnnxModel }>\n  private readonly store: ModelStore\n\n  constructor(config: FaceMatchConfig) {\n    if (!config.modelDirectory) throw new Error('LocalFaceMatchDriver requires config.modelDirectory')\n    this.store = new ModelStore(config.modelDirectory)\n  }\n\n  async compare(request: FaceMatchRequest): Promise<FaceMatchResultData> {\n    const [portrait, selfie] = await Promise.all([this.embed(request.documentPortrait), this.embed(request.selfie)])\n    if (!portrait || !selfie) {\n      return {\n        passed: false,\n        similarityScore: 0,\n        confidence: 0,\n        raw: { provider: 'local', model: MODEL, faceFound: { portrait: !!portrait, selfie: !!selfie } },\n      }\n    }\n\n    const cosine = portrait.vector.reduce((sum, value, i) => sum + value * selfie.vector[i]!, 0)\n\n    return {\n      passed: cosine >= SFACE_MATCH,\n      similarityScore: clamp01(0.6 + (cosine - SFACE_MATCH) * 1.5),\n      confidence: Math.min(portrait.detection, selfie.detection),\n      raw: { provider: 'local', model: MODEL, cosine },\n    }\n  }\n\n  async embed(image: Uint8Array): Promise<(FaceEmbedding & { detection: number }) | null> {\n    if (!image.length) return null\n\n    const { detector, recognizer } = await this.models()\n    const decoded = await decodeImage(image)\n    const face = largest(await detector.detect(decoded))\n    if (!face) return null\n\n    const aligned = alignFace(decoded, face)\n    const output = Object.values(await recognizer.run(toTensor(aligned, 'rgb'), [1, 3, ALIGNED_SIZE, ALIGNED_SIZE]))[0]!\n    const norm = Math.hypot(...output) || 1\n\n    return {\n      vector: Array.from(output, (value) => value / norm),\n      model: MODEL,\n      matchThreshold: SFACE_MATCH,\n      detection: face.score,\n    }\n  }\n\n  private models() {\n    this.loaded ??= (async () => ({\n      detector: await FaceDetector.load(this.store.path('yunet')),\n      recognizer: await OnnxModel.load(this.store.path('sface')),\n    }))()\n\n    return this.loaded\n  }\n}\n\n/** The face with the largest box. */\nexport function largest(faces: DetectedFace[]): DetectedFace | null {\n  return faces.reduce<DetectedFace | null>(\n    (best, face) => (!best || face.box[2] * face.box[3] > best.box[2] * best.box[3] ? face : best),\n    null,\n  )\n}\n\nconst clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n"],"mappings":";;;AAcA,MAAM,cAAc;AACpB,MAAM,QAAQ;;;;;;AAOd,IAAa,uBAAb,MAA6D;CAC3D,OAAgB;CAEhB;CACA;CAEA,YAAY,QAAyB;EACnC,IAAI,CAAC,OAAO,gBAAgB,MAAM,IAAI,MAAM,qDAAqD;EACjG,KAAK,QAAQ,IAAI,WAAW,OAAO,cAAc;CACnD;CAEA,MAAM,QAAQ,SAAyD;EACrE,MAAM,CAAC,UAAU,UAAU,MAAM,QAAQ,IAAI,CAAC,KAAK,MAAM,QAAQ,gBAAgB,GAAG,KAAK,MAAM,QAAQ,MAAM,CAAC,CAAC;EAC/G,IAAI,CAAC,YAAY,CAAC,QAChB,OAAO;GACL,QAAQ;GACR,iBAAiB;GACjB,YAAY;GACZ,KAAK;IAAE,UAAU;IAAS,OAAO;IAAO,WAAW;KAAE,UAAU,CAAC,CAAC;KAAU,QAAQ,CAAC,CAAC;IAAO;GAAE;EAChG;EAGF,MAAM,SAAS,SAAS,OAAO,QAAQ,KAAK,OAAO,MAAM,MAAM,QAAQ,OAAO,OAAO,IAAK,CAAC;EAE3F,OAAO;GACL,QAAQ,UAAU;GAClB,iBAAiB,QAAQ,MAAO,SAAS,eAAe,GAAG;GAC3D,YAAY,KAAK,IAAI,SAAS,WAAW,OAAO,SAAS;GACzD,KAAK;IAAE,UAAU;IAAS,OAAO;IAAO;GAAO;EACjD;CACF;CAEA,MAAM,MAAM,OAA4E;EACtF,IAAI,CAAC,MAAM,QAAQ,OAAO;EAE1B,MAAM,EAAE,UAAU,eAAe,MAAM,KAAK,OAAO;EACnD,MAAM,UAAU,MAAM,YAAY,KAAK;EACvC,MAAM,OAAO,QAAQ,MAAM,SAAS,OAAO,OAAO,CAAC;EACnD,IAAI,CAAC,MAAM,OAAO;EAElB,MAAM,UAAU,UAAU,SAAS,IAAI;EACvC,MAAM,SAAS,OAAO,OAAO,MAAM,WAAW,IAAI,SAAS,SAAS,KAAK,GAAG;GAAC;GAAG;GAAG;GAAc;EAAY,CAAC,CAAC,CAAC,CAAC;EACjH,MAAM,OAAO,KAAK,MAAM,GAAG,MAAM,KAAK;EAEtC,OAAO;GACL,QAAQ,MAAM,KAAK,SAAS,UAAU,QAAQ,IAAI;GAClD,OAAO;GACP,gBAAgB;GAChB,WAAW,KAAK;EAClB;CACF;CAEA,SAAiB;EACf,KAAK,YAAY,aAAa;GAC5B,UAAU,MAAM,aAAa,KAAK,KAAK,MAAM,KAAK,OAAO,CAAC;GAC1D,YAAY,MAAM,UAAU,KAAK,KAAK,MAAM,KAAK,OAAO,CAAC;EAC3D,GAAA,CAAI;EAEJ,OAAO,KAAK;CACd;AACF;;AAGA,SAAgB,QAAQ,OAA4C;CAClE,OAAO,MAAM,QACV,MAAM,SAAU,CAAC,QAAQ,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,OAAO,MACzF,IACF;AACF;AAEA,MAAM,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC"}

package/dist/drivers/mock.d.mts

@@ -1,4 +1,4 @@
-import { FaceMatchDriver, FaceMatchRequest } from "../types.mjs";
+import { FaceEmbedding, FaceMatchDriver, FaceMatchRequest } from "../types.mjs";
 import { FaceMatchResultData } from "@arkyc/types";
 
 //#region src/drivers/mock.d.ts
@@ -9,6 +9,8 @@ import { FaceMatchResultData } from "@arkyc/types";
 declare class MockFaceMatchDriver implements FaceMatchDriver {
   readonly name = "mock";
   compare(request: FaceMatchRequest): Promise<FaceMatchResultData>;
+  /** A unit vector derived from the image bytes, so identical images embed identically. */
+  embed(image: Uint8Array): Promise<FaceEmbedding | null>;
 }
 //#endregion
 export { MockFaceMatchDriver };

package/dist/drivers/mock.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.mts","names":[],"sources":["../../src/drivers/mock.ts"],"mappings":";;;;;;AASA;;cAAa,mBAAA,YAA+B,eAAA;EAAA,SACjC,IAAA;EAEH,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;AAAA"}
+{"version":3,"file":"mock.d.mts","names":[],"sources":["../../src/drivers/mock.ts"],"mappings":";;;;;;AAYA;;cAAa,mBAAA,YAA+B,eAAA;EAAA,SACjC,IAAA;EAEH,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;EAAR;EAapC,KAAA,CAAM,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,aAAA;AAAA"}

package/dist/drivers/mock.mjs

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 //#region src/drivers/mock.ts
+const MOCK_EMBEDDING_SIZE = 128;
 const clamp01 = (n) => Math.min(1, Math.max(0, n));
 /**
 * Deterministic face-match driver for development + tests. Passes by default;
@@ -18,6 +20,22 @@ var MockFaceMatchDriver = class {
 			}
 		};
 	}
+	/** A unit vector derived from the image bytes, so identical images embed identically. */
+	async embed(image) {
+		if (!image.length) return null;
+		const values = [];
+		for (let block = 0; values.length < MOCK_EMBEDDING_SIZE; block += 1) {
+			const digest = createHash("sha256").update(image).update(String(block)).digest();
+			for (const byte of digest) values.push(byte / 127.5 - 1);
+		}
+		const vector = values.slice(0, MOCK_EMBEDDING_SIZE);
+		const norm = Math.hypot(...vector) || 1;
+		return {
+			vector: vector.map((v) => v / norm),
+			model: "mock-v1",
+			matchThreshold: .95
+		};
+	}
 };
 //#endregion
 export { MockFaceMatchDriver };

package/dist/drivers/mock.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mock.mjs","names":[],"sources":["../../src/drivers/mock.ts"],"sourcesContent":["import type { FaceMatchResultData } from '@arkyc/types'\nimport type { FaceMatchDriver, FaceMatchRequest } from '../types'\n\nconst clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n\n/**\n * Deterministic face-match driver for development + tests. Passes by default;\n * `hints` steer the similarity score and verdict.\n */\nexport class MockFaceMatchDriver implements FaceMatchDriver {\n  readonly name = 'mock'\n\n  async compare(request: FaceMatchRequest): Promise<FaceMatchResultData> {\n    const similarityScore = clamp01(request.hints?.similarityScore ?? 0.9)\n    const passed = request.hints?.passed ?? similarityScore >= 0.5\n\n    return {\n      passed,\n      similarityScore,\n      confidence: 0.93,\n      raw: { provider: 'mock', similarityScore },\n    }\n  }\n}\n"],"mappings":";AAGA,MAAM,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;;;;;AAMjE,IAAa,sBAAb,MAA4D;CAC1D,OAAgB;CAEhB,MAAM,QAAQ,SAAyD;EACrE,MAAM,kBAAkB,QAAQ,QAAQ,OAAO,mBAAmB,EAAG;EAGrE,OAAO;GACL,QAHa,QAAQ,OAAO,UAAU,mBAAmB;GAIzD;GACA,YAAY;GACZ,KAAK;IAAE,UAAU;IAAQ;GAAgB;EAC3C;CACF;AACF"}
+{"version":3,"file":"mock.mjs","names":[],"sources":["../../src/drivers/mock.ts"],"sourcesContent":["import type { FaceMatchResultData } from '@arkyc/types'\nimport { createHash } from 'node:crypto'\nimport type { FaceEmbedding, FaceMatchDriver, FaceMatchRequest } from '../types'\n\nconst MOCK_EMBEDDING_SIZE = 128\n\nconst clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n\n/**\n * Deterministic face-match driver for development + tests. Passes by default;\n * `hints` steer the similarity score and verdict.\n */\nexport class MockFaceMatchDriver implements FaceMatchDriver {\n  readonly name = 'mock'\n\n  async compare(request: FaceMatchRequest): Promise<FaceMatchResultData> {\n    const similarityScore = clamp01(request.hints?.similarityScore ?? 0.9)\n    const passed = request.hints?.passed ?? similarityScore >= 0.5\n\n    return {\n      passed,\n      similarityScore,\n      confidence: 0.93,\n      raw: { provider: 'mock', similarityScore },\n    }\n  }\n\n  /** A unit vector derived from the image bytes, so identical images embed identically. */\n  async embed(image: Uint8Array): Promise<FaceEmbedding | null> {\n    if (!image.length) return null\n\n    const values: number[] = []\n    for (let block = 0; values.length < MOCK_EMBEDDING_SIZE; block += 1) {\n      const digest = createHash('sha256').update(image).update(String(block)).digest()\n      for (const byte of digest) values.push(byte / 127.5 - 1)\n    }\n    const vector = values.slice(0, MOCK_EMBEDDING_SIZE)\n    const norm = Math.hypot(...vector) || 1\n\n    return { vector: vector.map((v) => v / norm), model: 'mock-v1', matchThreshold: 0.95 }\n  }\n}\n"],"mappings":";;AAIA,MAAM,sBAAsB;AAE5B,MAAM,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;;;;;AAMjE,IAAa,sBAAb,MAA4D;CAC1D,OAAgB;CAEhB,MAAM,QAAQ,SAAyD;EACrE,MAAM,kBAAkB,QAAQ,QAAQ,OAAO,mBAAmB,EAAG;EAGrE,OAAO;GACL,QAHa,QAAQ,OAAO,UAAU,mBAAmB;GAIzD;GACA,YAAY;GACZ,KAAK;IAAE,UAAU;IAAQ;GAAgB;EAC3C;CACF;;CAGA,MAAM,MAAM,OAAkD;EAC5D,IAAI,CAAC,MAAM,QAAQ,OAAO;EAE1B,MAAM,SAAmB,CAAC;EAC1B,KAAK,IAAI,QAAQ,GAAG,OAAO,SAAS,qBAAqB,SAAS,GAAG;GACnE,MAAM,SAAS,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,OAAO;GAC/E,KAAK,MAAM,QAAQ,QAAQ,OAAO,KAAK,OAAO,QAAQ,CAAC;EACzD;EACA,MAAM,SAAS,OAAO,MAAM,GAAG,mBAAmB;EAClD,MAAM,OAAO,KAAK,MAAM,GAAG,MAAM,KAAK;EAEtC,OAAO;GAAE,QAAQ,OAAO,KAAK,MAAM,IAAI,IAAI;GAAG,OAAO;GAAW,gBAAgB;EAAK;CACvF;AACF"}

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { FaceMatchConfig, FaceMatchDriver, FaceMatchDriverName, FaceMatchRequest } from "./types.mjs";
+import { FaceEmbedding, FaceMatchConfig, FaceMatchDriver, FaceMatchDriverName, FaceMatchRequest } from "./types.mjs";
 import { FaceMatchDriverFactory } from "./registry.mjs";
 import { MockFaceMatchDriver } from "./drivers/mock.mjs";
 import { ExternalFaceMatchDriver } from "./drivers/external.mjs";
-export { ExternalFaceMatchDriver, FaceMatchConfig, FaceMatchDriver, FaceMatchDriverFactory, FaceMatchDriverName, FaceMatchRequest, MockFaceMatchDriver };
+import { LocalFaceMatchDriver } from "./drivers/local.mjs";
+export { ExternalFaceMatchDriver, FaceEmbedding, FaceMatchConfig, FaceMatchDriver, FaceMatchDriverFactory, FaceMatchDriverName, FaceMatchRequest, LocalFaceMatchDriver, MockFaceMatchDriver };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { ExternalFaceMatchDriver } from "./drivers/external.mjs";
+import { LocalFaceMatchDriver } from "./drivers/local.mjs";
 import { MockFaceMatchDriver } from "./drivers/mock.mjs";
 import { FaceMatchDriverFactory } from "./registry.mjs";
-export { ExternalFaceMatchDriver, FaceMatchDriverFactory, MockFaceMatchDriver };
+export { ExternalFaceMatchDriver, FaceMatchDriverFactory, LocalFaceMatchDriver, MockFaceMatchDriver };

package/dist/registry.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.mts","names":[],"sources":["../src/registry.ts"],"mappings":";;;;cAMa,sBAAA;EAAA;;;;;;EAAA,OAOJ,MAAA,CAAO,MAAA,EAAQ,eAAA,GAAkB,eAAe;AAAA"}
+{"version":3,"file":"registry.d.mts","names":[],"sources":["../src/registry.ts"],"mappings":";;;;cAOa,sBAAA;EAAA;;;;;;EAAA,OAOJ,MAAA,CAAO,MAAA,EAAQ,eAAA,GAAkB,eAAe;AAAA"}

package/dist/registry.mjs

@@ -1,4 +1,5 @@
 import { ExternalFaceMatchDriver } from "./drivers/external.mjs";
+import { LocalFaceMatchDriver } from "./drivers/local.mjs";
 import { MockFaceMatchDriver } from "./drivers/mock.mjs";
 //#region src/registry.ts
 /** Selects a face-match driver from config. */
@@ -13,6 +14,7 @@ var FaceMatchDriverFactory = class {
 		switch (config.driver) {
 			case "mock": return new MockFaceMatchDriver();
 			case "external": return new ExternalFaceMatchDriver(config);
+			case "local": return new LocalFaceMatchDriver(config);
 			default: throw new Error(`Unknown face-match driver: ${config.driver}`);
 		}
 	}

package/dist/registry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"registry.mjs","names":[],"sources":["../src/registry.ts"],"sourcesContent":["import type { FaceMatchConfig, FaceMatchDriver } from './types'\n\nimport { ExternalFaceMatchDriver } from './drivers/external'\nimport { MockFaceMatchDriver } from './drivers/mock'\n\n/** Selects a face-match driver from config. */\nexport class FaceMatchDriverFactory {\n  /**'\n   * Resolve the face-match driver named by `config`.\n   *\n   * @param config\n   * @returns\n   */\n  static create(config: FaceMatchConfig): FaceMatchDriver {\n    switch (config.driver) {\n      case 'mock':\n        return new MockFaceMatchDriver()\n      case 'external':\n        return new ExternalFaceMatchDriver(config)\n      default:\n        throw new Error(`Unknown face-match driver: ${(config as FaceMatchConfig).driver}`)\n    }\n  }\n}\n"],"mappings":";;;;AAMA,IAAa,yBAAb,MAAoC;;;;;;;CAOlC,OAAO,OAAO,QAA0C;EACtD,QAAQ,OAAO,QAAf;GACE,KAAK,QACH,OAAO,IAAI,oBAAoB;GACjC,KAAK,YACH,OAAO,IAAI,wBAAwB,MAAM;GAC3C,SACE,MAAM,IAAI,MAAM,8BAA+B,OAA2B,QAAQ;EACtF;CACF;AACF"}
+{"version":3,"file":"registry.mjs","names":[],"sources":["../src/registry.ts"],"sourcesContent":["import type { FaceMatchConfig, FaceMatchDriver } from './types'\n\nimport { ExternalFaceMatchDriver } from './drivers/external'\nimport { LocalFaceMatchDriver } from './drivers/local'\nimport { MockFaceMatchDriver } from './drivers/mock'\n\n/** Selects a face-match driver from config. */\nexport class FaceMatchDriverFactory {\n  /**'\n   * Resolve the face-match driver named by `config`.\n   *\n   * @param config\n   * @returns\n   */\n  static create(config: FaceMatchConfig): FaceMatchDriver {\n    switch (config.driver) {\n      case 'mock':\n        return new MockFaceMatchDriver()\n      case 'external':\n        return new ExternalFaceMatchDriver(config)\n      case 'local':\n        return new LocalFaceMatchDriver(config)\n      default:\n        throw new Error(`Unknown face-match driver: ${(config as FaceMatchConfig).driver}`)\n    }\n  }\n}\n"],"mappings":";;;;;AAOA,IAAa,yBAAb,MAAoC;;;;;;;CAOlC,OAAO,OAAO,QAA0C;EACtD,QAAQ,OAAO,QAAf;GACE,KAAK,QACH,OAAO,IAAI,oBAAoB;GACjC,KAAK,YACH,OAAO,IAAI,wBAAwB,MAAM;GAC3C,KAAK,SACH,OAAO,IAAI,qBAAqB,MAAM;GACxC,SACE,MAAM,IAAI,MAAM,8BAA+B,OAA2B,QAAQ;EACtF;CACF;AACF"}

package/dist/types.d.mts

@@ -16,19 +16,31 @@ interface FaceMatchRequest {
     passed?: boolean;
   };
 }
+/** A face embedding: a vector two images of the same person land close together in. */
+interface FaceEmbedding {
+  vector: number[];
+  /** The model that produced it. Embeddings from different models are not comparable. */
+  model: string;
+  /** Cosine similarity at or above which two embeddings are the same person. */
+  matchThreshold: number;
+}
 /** A pluggable face-match provider. */
 interface FaceMatchDriver {
   readonly name: string;
   compare(request: FaceMatchRequest): Promise<FaceMatchResultData>;
+  /** Embed the most prominent face in an image, or `null` when there is none. Optional capability. */
+  embed?(image: Uint8Array): Promise<FaceEmbedding | null>;
 }
 /** Identifier for a registered face-match driver. */
-type FaceMatchDriverName = 'mock' | 'external';
+type FaceMatchDriverName = 'mock' | 'external' | 'local';
 /** Configuration selecting + parameterising the active face-match driver. */
 interface FaceMatchConfig {
   driver: FaceMatchDriverName;
   endpoint?: string;
   apiKey?: string;
+  /** Where the `local` driver finds its model files. */
+  modelDirectory?: string;
 }
 //#endregion
-export { FaceMatchConfig, FaceMatchDriver, FaceMatchDriverName, FaceMatchRequest };
+export { FaceEmbedding, FaceMatchConfig, FaceMatchDriver, FaceMatchDriverName, FaceMatchRequest };
 //# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;UAGiB,gBAAA;EAAA;EAEf,gBAAA,EAAkB,UAAA;;EAElB,MAAA,EAAQ,UAAU;EAFlB;;;;EAOA,KAAA;IAAU,eAAA;IAA0B,MAAA;EAAA;AAAA;AAItC;AAAA,UAAiB,eAAA;EAAA,SACN,IAAA;EACT,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;AAAA;;KAIlC,mBAAA;;UAGK,eAAA;EACf,MAAA,EAAQ,mBAAmB;EAC3B,QAAA;EACA,MAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;UAGiB,gBAAA;EAAA;EAEf,gBAAA,EAAkB,UAAA;;EAElB,MAAA,EAAQ,UAAU;EAFlB;;;;EAOA,KAAA;IAAU,eAAA;IAA0B,MAAA;EAAA;AAAA;AAItC;AAAA,UAAiB,aAAA;EACf,MAAA;EAD4B;EAG5B,KAAA;EAAA;EAEA,cAAA;AAAA;AAAc;AAAA,UAIC,eAAA;EAAA,SACN,IAAA;EACT,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;EAA3B;EAEjB,KAAA,EAAO,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,aAAA;AAAA;;KAIzB,mBAAA;;UAGK,eAAA;EACf,MAAA,EAAQ,mBAAmB;EAC3B,QAAA;EACA,MAAA;EAZiB;EAcjB,cAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkyc/face-match",
-  "version": "1.2.10",
+  "version": "2.0.0",
   "description": "Driver-based face matching",
   "license": "MIT",
   "keywords": [
@@ -36,7 +36,8 @@
     "dist"
   ],
   "dependencies": {
-    "@arkyc/types": "^1.2.10"
+    "@arkyc/types": "^2.0.0",
+    "@arkyc/vision": "^2.0.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",