@camstack/addon-post-analysis 1.2.41 → 1.2.43

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-C09kySqI.js");
+const require_dist = require("../dist-BIBeAcEY.js");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 node_path = require_dist.__toESM(node_path);
@@ -5821,6 +5821,76 @@ function makeNcActionHandlers(deps) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/embedding-actions.ts
+/**
+* embedding-actions — operator buttons for the CLIP semantic-search index.
+*
+* These ride the generic `addons.custom` bridge rather than adding cap methods,
+* because the settings form already knows how to render an
+* `addon-action-button` and call it. The three operations they expose are the
+* ones an operator needs when the index and the world disagree:
+*
+*  - **Rebuild** re-embeds tracks from their key frames. It is the only way to
+*    change what a vector MEANS — crop margin, squaring, encoder model — since
+*    mixing feature spaces in one index makes cosine scores incomparable.
+*  - **Status** is what makes rebuild usable at all: a pass is ~1s per track,
+*    45 minutes for a fleet, so it runs detached and this is how progress is
+*    seen.
+*  - **Wipe** empties the index, for the clean slate before a policy change.
+*
+* Wipe is `danger` and carries a confirm prompt. It has already destroyed a
+* live index once when it was called casually — the button must not make that
+* easier than it needs to be.
+*/
+var RebuildInputSchema = require_dist.object({
+	/** Restrict to one camera; omit for the whole fleet. */
+	deviceId: require_dist.number().optional(),
+	/**
+	* Fraction added on EACH side of the detection box before cropping.
+	* ~0.2 (a 1.4x window) gives CLIP the surroundings it is trained on; 0 is
+	* the pixel-tight crop.
+	*/
+	cropMargin: require_dist.number().min(0).max(4).optional(),
+	/** Square the window so a tall subject is not squashed into CLIP's input. */
+	square: require_dist.boolean().optional(),
+	/** Stop after this many tracks; the status reports whether more remain. */
+	maxTracks: require_dist.number().int().positive().optional()
+});
+var RebuildStartedSchema = require_dist.object({
+	started: require_dist.boolean(),
+	alreadyRunning: require_dist.boolean()
+});
+var RebuildStatusSchema = require_dist.object({
+	running: require_dist.boolean(),
+	scanned: require_dist.number(),
+	rebuilt: require_dist.number(),
+	missingKeyFrame: require_dist.number(),
+	missingBbox: require_dist.number(),
+	failed: require_dist.number(),
+	complete: require_dist.boolean().nullable(),
+	startedAtMs: require_dist.number().nullable(),
+	finishedAtMs: require_dist.number().nullable(),
+	error: require_dist.string().nullable(),
+	/** Rows currently in the index — the number the operator is watching. */
+	indexed: require_dist.number()
+});
+var WipeResultSchema = require_dist.object({ deleted: require_dist.number() });
+/**
+* An input-less action still takes an OBJECT, never `z.void()`.
+*
+* The `addons.custom` envelope requires an `input` field — omitting it fails
+* envelope validation before the action is even looked up — and the settings
+* form's button always sends one. So `z.void()` makes an action that resolves
+* and can never be called: the bridge insists on `{}` and the schema rejects
+* it. Verified on the live hub, both directions.
+*/
+var NoInputSchema = require_dist.object({});
+var embeddingActions = require_dist.defineCustomActions({
+	"embedding.rebuild": require_dist.customAction(RebuildInputSchema, RebuildStartedSchema, { auth: "admin" }),
+	"embedding.rebuildStatus": require_dist.customAction(NoInputSchema, RebuildStatusSchema),
+	"embedding.wipe": require_dist.customAction(NoInputSchema, WipeResultSchema, { auth: "admin" })
+});
+//#endregion
 //#region src/pipeline-analytics/pipeline/face-clustering.ts
 /**
 * face-clustering — pure greedy clustering of face embeddings by cosine
@@ -12047,57 +12117,84 @@ async function rebuildObjectEmbeddings(deps, options = {}) {
 	const margin = options.cropMargin ?? .2;
 	const square = options.square ?? true;
 	const maxTracks = options.maxTracks ?? Number.POSITIVE_INFINITY;
-	const trackIds = await deps.listTrackIds();
-	const considered = trackIds.slice(0, Number.isFinite(maxTracks) ? maxTracks : void 0);
 	let rebuilt = 0;
 	let missingKeyFrame = 0;
 	let missingBbox = 0;
 	let failed = 0;
-	for (const trackId of considered) try {
-		const source = await deps.loadSource(trackId);
-		if (source === null) {
-			missingKeyFrame += 1;
-			continue;
-		}
-		if (source.keyFrame === null) {
-			missingKeyFrame += 1;
-			continue;
-		}
-		if (source.bbox === null || source.bbox.w <= 0 || source.bbox.h <= 0) {
-			missingBbox += 1;
-			continue;
-		}
-		const meta = await (0, sharp.default)(source.keyFrame).metadata();
-		if (meta.width === void 0 || meta.height === void 0) {
-			failed += 1;
-			continue;
+	let scanned = 0;
+	let cursor = null;
+	let exhausted = false;
+	let budgetExhausted = false;
+	while (scanned < maxTracks) {
+		const page = await deps.listTrackIdPage(cursor);
+		if (page.trackIds.length === 0) {
+			exhausted = true;
+			break;
 		}
-		const window = cropWindow(source.bbox, meta.width, meta.height, {
-			margin,
-			square
-		});
-		const cut = await cropFromJpeg(source.keyFrame, window);
-		if (cut === null) {
-			failed += 1;
-			continue;
+		const room = maxTracks - scanned;
+		const batch = page.trackIds.slice(0, Number.isFinite(room) ? room : void 0);
+		if (batch.length < page.trackIds.length) budgetExhausted = true;
+		for (const trackId of batch) {
+			scanned += 1;
+			try {
+				const source = await deps.loadSource(trackId);
+				if (source === null) {
+					missingKeyFrame += 1;
+					continue;
+				}
+				if (source.keyFrame === null) {
+					missingKeyFrame += 1;
+					continue;
+				}
+				if (source.bbox === null || source.bbox.w <= 0 || source.bbox.h <= 0) {
+					missingBbox += 1;
+					continue;
+				}
+				const meta = await (0, sharp.default)(source.keyFrame).metadata();
+				if (meta.width === void 0 || meta.height === void 0) {
+					failed += 1;
+					continue;
+				}
+				const window = cropWindow(source.bbox, meta.width, meta.height, {
+					margin,
+					square
+				});
+				const cut = await cropFromJpeg(source.keyFrame, window);
+				if (cut === null) {
+					failed += 1;
+					continue;
+				}
+				const embedding = await deps.encode(cut.crop, cut.width, cut.height);
+				if (embedding.length === 0) {
+					failed += 1;
+					continue;
+				}
+				await deps.store(source, embedding);
+				rebuilt += 1;
+			} catch (err) {
+				failed += 1;
+				deps.logger.warn("embedding rebuild failed for a track", { meta: {
+					trackId,
+					error: String(err)
+				} });
+			}
+			if (scanned % 25 === 0) options.onProgress?.({
+				scanned,
+				rebuilt,
+				missingKeyFrame,
+				missingBbox,
+				failed
+			});
 		}
-		const embedding = await deps.encode(cut.crop, cut.width, cut.height);
-		if (embedding.length === 0) {
-			failed += 1;
-			continue;
+		if (page.nextCursor === null) {
+			exhausted = true;
+			break;
 		}
-		await deps.store(source, embedding);
-		rebuilt += 1;
-	} catch (err) {
-		failed += 1;
-		deps.logger.warn("embedding rebuild failed for a track", { meta: {
-			trackId,
-			error: String(err)
-		} });
+		cursor = page.nextCursor;
 	}
-	const complete = considered.length === trackIds.length;
+	const complete = exhausted && !budgetExhausted;
 	deps.logger.info("object embedding rebuild finished", { meta: {
-		scanned: considered.length,
+		scanned,
 		rebuilt,
 		missingKeyFrame,
 		missingBbox,
@@ -12107,7 +12204,7 @@ async function rebuildObjectEmbeddings(deps, options = {}) {
 		square
 	} });
 	return {
-		scanned: considered.length,
+		scanned,
 		rebuilt,
 		missingKeyFrame,
 		missingBbox,
@@ -17530,26 +17627,6 @@ var SyntheticSensorTrackMaterializer = class {
 		return track;
 	}
 };
-var TRACK_RETENTION_DEFAULT_DAYS = require_dist.object({ trackRetentionDays: require_dist.number().min(0).default(7) }).parse({}).trackRetentionDays;
-/**
-* Sweep every device with persisted tracks: skip retention-disabled devices,
-* prune the rest at `now − retentionMs`. Per-device ISOLATED — one bad device
-* never aborts the sweep. Returns the total tracks pruned across devices.
-*/
-async function sweepTrackRetention(deps) {
-	const devices = await deps.listDeviceIds();
-	const nowMs = deps.now();
-	let totalTracks = 0;
-	for (const deviceId of devices) try {
-		const cutoffMs = await deps.resolveCutoffMs(deviceId, nowMs);
-		if (cutoffMs === null) continue;
-		const counts = await deps.pruneTracksBefore(deviceId, cutoffMs);
-		totalTracks += counts.tracks;
-	} catch (err) {
-		deps.onError?.(deviceId, err);
-	}
-	return totalTracks;
-}
 var TrackingSettingsSchema = require_dist.object({
 	/**
 	* How much of a detection's box must lie inside a zone (0-1 fraction of the
@@ -18345,6 +18422,26 @@ function buildDetectionSettingsSections() {
 		}
 	];
 }
+var TRACK_RETENTION_DEFAULT_DAYS = require_dist.object({ trackRetentionDays: require_dist.number().min(0).default(7) }).parse({}).trackRetentionDays;
+/**
+* Sweep every device with persisted tracks: skip retention-disabled devices,
+* prune the rest at `now − retentionMs`. Per-device ISOLATED — one bad device
+* never aborts the sweep. Returns the total tracks pruned across devices.
+*/
+async function sweepTrackRetention(deps) {
+	const devices = await deps.listDeviceIds();
+	const nowMs = deps.now();
+	let totalTracks = 0;
+	for (const deviceId of devices) try {
+		const cutoffMs = await deps.resolveCutoffMs(deviceId, nowMs);
+		if (cutoffMs === null) continue;
+		const counts = await deps.pruneTracksBefore(deviceId, cutoffMs);
+		totalTracks += counts.tracks;
+	} catch (err) {
+		deps.onError?.(deviceId, err);
+	}
+	return totalTracks;
+}
 /**
 * Re-home the global analytics sections into the per-device `Analytics`
 * top-tab. Every section defaults to the `Analytics` tab (so the
@@ -18455,6 +18552,59 @@ function buildGlobalSettingsSchema() {
 				default: true
 			}]
 		},
+		{
+			id: "embedding-index",
+			title: "Semantic search index",
+			description: "The CLIP vector index behind text search. Rebuild re-embeds stored tracks from their native key frames — the only way to change what a vector means, since a new crop margin or encoder model leaves two incomparable feature spaces in one index. Vectors live in the vector-store capability, alongside the events they are shown with.",
+			columns: 1,
+			fields: [
+				{
+					type: "number",
+					key: "rebuildCropMargin",
+					label: "Rebuild crop margin",
+					description: "Fraction added on EACH side of the detection box when re-embedding. 0.2 gives a 1.4x window: CLIP is trained on natural images WITH surroundings, and a pixel-tight crop removes what it is strongest on. 0 reproduces the tight crop. Only affects Rebuild — it does not change live capture, and the thumbnail is never re-cropped.",
+					default: .2,
+					min: 0,
+					max: 2,
+					step: .1
+				},
+				{
+					type: "addon-action-button",
+					key: "rebuildEmbeddingsButton",
+					label: "Rebuild index",
+					description: "Re-embed every stored track from its key frame, using the margin above. Runs in the background — press Progress to watch it. Tracks whose key frame has aged out cannot be rebuilt and are reported as skipped.",
+					addonId: "pipeline-analytics",
+					action: "embedding.rebuild",
+					buttonLabel: "Rebuild",
+					variant: "primary",
+					paramsFromForm: { cropMargin: "rebuildCropMargin" },
+					paramsStatic: { square: true },
+					successMessage: "Rebuild started — press Progress to follow it."
+				},
+				{
+					type: "addon-action-button",
+					key: "rebuildStatusButton",
+					label: "Progress",
+					description: "Rows currently indexed, plus the running pass: scanned, rebuilt, and what it had to skip.",
+					addonId: "pipeline-analytics",
+					action: "embedding.rebuildStatus",
+					buttonLabel: "Check progress",
+					successMessage: "Indexed {indexed} · scanned {scanned} · rebuilt {rebuilt} · no key frame {missingKeyFrame} · failed {failed}"
+				},
+				{
+					type: "addon-action-button",
+					key: "wipeEmbeddingsButton",
+					label: "Empty the index",
+					description: "Deletes every vector. Search returns nothing until a rebuild repopulates it, and only tracks still inside the retention window can be rebuilt — anything older is gone for good.",
+					addonId: "pipeline-analytics",
+					action: "embedding.wipe",
+					buttonLabel: "Empty index",
+					variant: "danger",
+					confirmMessage: "Delete every semantic-search vector? Search stops working until a rebuild finishes, and vectors whose tracks have aged out cannot be recovered.",
+					successMessage: "Removed {deleted} vectors."
+				}
+			]
+		},
 		{
 			id: "tracking-core",
 			title: "Tracking",
@@ -22949,10 +23099,30 @@ var ENCODER_INFO_TTL_MS = 6e4;
 var EMBEDDING_ORPHAN_SCAN_LIMIT = 2e4;
 /** Dimension of the zero probe vector used to enumerate the index. */
 var EMBEDDING_ORPHAN_PROBE_DIM = 512;
+/**
+* Tracks fetched per page while rebuilding.
+*
+* The page size is NOT the caller's `maxTracks`: that bounds the whole pass,
+* this bounds one round trip. Conflating them is what made the rebuild
+* re-embed the same newest N tracks on every call.
+*/
+var REBUILD_PAGE_SIZE = 200;
 var PIPELINE_ANALYTICS_ADDON_ID = "pipeline-analytics";
 /** Operator-visible name of the fixed integration. */
 var NC_INTEGRATION_NAME = "Notification Center";
 /**
+* The FULL action catalog for this addon.
+*
+* Must contain every action, not just the notification-center ones: the hub
+* harvests THIS named export, so an action registered only in what
+* `onInitialize` returns is invisible to the bridge and answers 404. That is
+* exactly what the embedding buttons did on their first deploy.
+*/
+var customActions = {
+	...ncActions,
+	...embeddingActions
+};
+/**
 * Pipeline Analytics addon — subscribes to `PipelineInferenceResult` +
 * `PipelineAudioInferenceResult` on the bus, refines raw detections
 * into tracks + per-kind events + persisted media, and emits canonical
@@ -23136,6 +23306,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	plateStore = null;
 	plateRecognizer = null;
 	objectEmbeddingStore = null;
+	/** Live state of the detached embedding rebuild — see `rebuildObjectEmbeddings`. */
+	rebuildState = { running: false };
 	/** Cached active-encoder model id — see `resolveEncoderModelId`. */
 	encoderInfoCache = null;
 	/** Two-plane detail scheduler/dispatcher: per-track on-demand face/clip/
@@ -23610,8 +23782,14 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		return {
 			providers,
 			...isHub && ncHandlers !== void 0 ? {
-				customActions: ncActions,
-				actionHandlers: ncHandlers
+				customActions: {
+					...ncActions,
+					...embeddingActions
+				},
+				actionHandlers: {
+					...ncHandlers,
+					...this.buildEmbeddingActionHandlers()
+				}
 			} : {}
 		};
 	}
@@ -23760,7 +23938,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		let storage = this.ctx.kernel.storage;
 		const mediaRoot = process.env.CAMSTACK_MEDIA_ROOT?.trim();
 		if (mediaRoot) {
-			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-DL2FM8_E.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-INtH-sDE.js"));
 			storage = new FilesystemStorageProvider(mediaRoot, { eventMedia: mediaRoot });
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -26864,33 +27042,40 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	* widened after the fact.
 	*/
 	async rebuildObjectEmbeddings(input) {
+		if (this.rebuildState.running) {
+			this.ctx.logger.info("object embedding rebuild already running — request ignored");
+			return {
+				started: false,
+				alreadyRunning: true
+			};
+		}
 		const store = this.objectEmbeddingStore;
 		const trackStore = this.trackStore;
 		const mediaStore = this.mediaStore;
 		const eventStore = this.eventStore;
 		const api = this.ctx.api;
-		const empty = {
-			scanned: 0,
-			rebuilt: 0,
-			missingKeyFrame: 0,
-			missingBbox: 0,
-			failed: 0,
-			complete: true
-		};
 		if (!store || !trackStore || !mediaStore || !eventStore || !api) {
 			this.ctx.logger.warn("rebuildObjectEmbeddings: analytics stores unavailable");
-			return empty;
+			return {
+				started: false,
+				alreadyRunning: false
+			};
 		}
 		const modelId = await this.resolveEncoderModelId(api) ?? "unknown";
 		const deviceIds = input.deviceId !== void 0 ? [input.deviceId] : await trackStore.listDeviceIds();
-		return rebuildObjectEmbeddings({
-			listTrackIds: async () => {
-				return (await trackStore.queryRecent({
+		const deps = {
+			listTrackIdPage: async (cursor) => {
+				const page = await trackStore.queryRecent({
 					deviceIds,
 					...input.since !== void 0 ? { since: input.since } : {},
 					...input.until !== void 0 ? { until: input.until } : {},
-					limit: input.maxTracks ?? 500
-				})).tracks.map((t) => t.trackId);
+					...cursor !== null ? { cursor } : {},
+					limit: REBUILD_PAGE_SIZE
+				});
+				return {
+					trackIds: page.tracks.map((t) => t.trackId),
+					nextCursor: page.nextCursor
+				};
 			},
 			loadSource: async (trackId) => {
 				const media = await mediaStore.listByOwner("track", trackId);
@@ -26936,11 +27121,93 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				info: (message, extras) => this.ctx.logger.info(message, extras),
 				warn: (message, extras) => this.ctx.logger.warn(message, extras)
 			}
-		}, {
+		};
+		this.rebuildState = {
+			running: true,
+			startedAtMs: Date.now(),
+			progress: {
+				scanned: 0,
+				rebuilt: 0,
+				missingKeyFrame: 0,
+				missingBbox: 0,
+				failed: 0
+			}
+		};
+		rebuildObjectEmbeddings(deps, {
 			...input.cropMargin !== void 0 ? { cropMargin: input.cropMargin } : {},
 			...input.square !== void 0 ? { square: input.square } : {},
-			...input.maxTracks !== void 0 ? { maxTracks: input.maxTracks } : {}
+			...input.maxTracks !== void 0 ? { maxTracks: input.maxTracks } : {},
+			onProgress: (progress) => {
+				if (this.rebuildState.running) this.rebuildState.progress = progress;
+				this.ctx.logger.info("object embedding rebuild progress", { meta: { ...progress } });
+			}
+		}).then((outcome) => {
+			this.rebuildState = {
+				running: false,
+				startedAtMs: this.rebuildState.startedAtMs ?? Date.now(),
+				finishedAtMs: Date.now(),
+				progress: outcome,
+				complete: outcome.complete
+			};
+		}).catch((err) => {
+			this.rebuildState = {
+				running: false,
+				startedAtMs: this.rebuildState.startedAtMs ?? Date.now(),
+				finishedAtMs: Date.now(),
+				error: String(err)
+			};
+			this.ctx.logger.warn("object embedding rebuild failed", { meta: { error: String(err) } });
 		});
+		this.ctx.logger.info("object embedding rebuild started", { meta: {
+			deviceId: input.deviceId ?? "all",
+			cropMargin: input.cropMargin ?? "default",
+			maxTracks: input.maxTracks ?? "unbounded"
+		} });
+		return {
+			started: true,
+			alreadyRunning: false
+		};
+	}
+	/**
+	* Handlers behind the embedding buttons in the settings form.
+	*
+	* They are thin wrappers over the cap methods on purpose: the button and the
+	* API must not be able to drift into two behaviours.
+	*/
+	buildEmbeddingActionHandlers() {
+		return {
+			"embedding.rebuild": async (input) => this.rebuildObjectEmbeddings(input),
+			"embedding.rebuildStatus": async () => {
+				const status = await this.getObjectEmbeddingRebuildStatus();
+				let indexed = 0;
+				try {
+					const api = this.ctx.api;
+					if (api) indexed = (await api.vectorStore.stats.query({ index: OBJECT_CLIP_INDEX })).count;
+				} catch {}
+				return {
+					...status,
+					indexed
+				};
+			},
+			"embedding.wipe": async () => this.wipeObjectEmbeddings()
+		};
+	}
+	/** Progress of the detached rebuild — the only way to observe a long pass. */
+	async getObjectEmbeddingRebuildStatus() {
+		const state = this.rebuildState;
+		const p = state.progress;
+		return {
+			running: state.running,
+			scanned: p?.scanned ?? 0,
+			rebuilt: p?.rebuilt ?? 0,
+			missingKeyFrame: p?.missingKeyFrame ?? 0,
+			missingBbox: p?.missingBbox ?? 0,
+			failed: p?.failed ?? 0,
+			complete: state.complete ?? null,
+			startedAtMs: state.startedAtMs ?? null,
+			finishedAtMs: state.finishedAtMs ?? null,
+			error: state.error ?? null
+		};
 	}
 	async searchObjectEvents(input) {
 		const store = this.objectEmbeddingStore;
@@ -27354,7 +27621,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 };
 //#endregion
 exports.DETECTION_PIPELINE_SECTION_IDS = DETECTION_PIPELINE_SECTION_IDS;
-exports.customActions = ncActions;
+exports.customActions = customActions;
 exports.default = PipelineAnalyticsAddon;
 exports.ncActions = ncActions;
 exports.pickCleanMedia = pickCleanMedia;