@camstack/addon-post-analysis 1.1.3 → 1.1.5

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { a as faceGalleryCapability, b as number, c as videoclipsCapability, d as BaseAddon, f as DeviceType, g as hydrateSchema, l as zoneAnalyticsCapability, n as audioMetricsCapability, o as pipelineAnalyticsCapability, p as EventCategory, r as cosineSimilarity, s as plateGalleryCapability, t as addonWidgetsSourceCapability, u as errMsg, x as object, y as boolean } from "../dist-BUE-vLMt.mjs";
+import { S as object, _ as hydrateSchema, a as faceGalleryCapability, b as boolean, c as plateGalleryCapability, d as errMsg, f as BaseAddon, l as videoclipsCapability, m as EventCategory, n as audioMetricsCapability, p as DeviceType, r as cosineSimilarity, s as pipelineAnalyticsCapability, t as addonWidgetsSourceCapability, u as zoneAnalyticsCapability, x as number } from "../dist-BpGP9ago.mjs";
 import { n as extractCrop, t as resolveFrame } from "../resolve-frame-CT1T1tWy.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
 import sharp from "sharp";
@@ -4475,6 +4475,178 @@ var FaceStore = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/store/object-embedding-store.ts
+var OBJECT_EMBEDDINGS_COLLECTION = "pipeline-analytics:object-embeddings";
+var OBJECT_EMBEDDING_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "deviceId",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "trackId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "timestamp",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "className",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "embedding",
+		type: "JSON",
+		notNull: true
+	},
+	{
+		name: "modelId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "dim",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "confidence",
+		type: "REAL",
+		notNull: true
+	},
+	{
+		name: "mediaKey",
+		type: "TEXT"
+	}
+];
+var ObjectEmbeddingStore = class {
+	store;
+	logger;
+	constructor(deps) {
+		this.store = deps.store;
+		this.logger = deps.logger;
+	}
+	static async declare(store) {
+		await store.declareCollection.mutate({
+			collection: OBJECT_EMBEDDINGS_COLLECTION,
+			columns: [...OBJECT_EMBEDDING_COLUMNS],
+			indexes: [{
+				name: "idx_obj_emb_device_ts",
+				columns: ["deviceId", "timestamp"]
+			}, {
+				name: "idx_obj_emb_track",
+				columns: ["trackId"]
+			}]
+		});
+	}
+	/**
+	* Upsert the best-confidence CLIP embedding for a track. The id is the
+	* trackId so there is at most ONE row per track. An upsert only replaces
+	* the row when the new confidence is strictly higher than the stored value,
+	* keeping the best-crop embedding for the track over its lifetime.
+	*/
+	async upsertIfBetter(input) {
+		const existing = await this.store.get.query({
+			collection: OBJECT_EMBEDDINGS_COLLECTION,
+			key: input.trackId
+		});
+		if (existing !== void 0 && existing !== null) {
+			const storedConf = existing.confidence;
+			if (typeof storedConf === "number" && input.confidence <= storedConf) return;
+		}
+		const record = {
+			deviceId: input.deviceId,
+			trackId: input.trackId,
+			timestamp: input.timestamp,
+			className: input.className,
+			embedding: input.embedding,
+			modelId: input.modelId,
+			dim: input.embedding.length,
+			confidence: input.confidence,
+			...input.mediaKey !== void 0 ? { mediaKey: input.mediaKey } : {}
+		};
+		try {
+			await this.store.set.mutate({
+				collection: OBJECT_EMBEDDINGS_COLLECTION,
+				key: input.trackId,
+				value: record
+			});
+		} catch (err) {
+			this.logger.warn("ObjectEmbeddingStore.upsertIfBetter failed", { meta: {
+				trackId: input.trackId,
+				error: String(err)
+			} });
+		}
+	}
+	/**
+	* Load all embeddings for a device within a time range. Applies `modelId`
+	* and `className` filters when provided. Used by `searchObjectEvents`.
+	*/
+	async query(input) {
+		const where = {};
+		if (input.deviceId !== void 0) where["deviceId"] = input.deviceId;
+		if (input.className !== void 0) where["className"] = input.className;
+		if (input.modelId !== void 0) where["modelId"] = input.modelId;
+		const filter = { where };
+		if (input.since !== void 0 || input.until !== void 0) filter["whereBetween"] = { timestamp: [input.since ?? 0, input.until ?? Date.now()] };
+		if (input.limit !== void 0) filter["limit"] = input.limit;
+		return (await this.store.query.query({
+			collection: OBJECT_EMBEDDINGS_COLLECTION,
+			filter
+		})).map((r) => {
+			const data = r.data;
+			return {
+				id: r.id,
+				...data,
+				mediaKey: data.mediaKey ?? void 0
+			};
+		});
+	}
+	/**
+	* Retention sweep: delete all embeddings whose timestamp < cutoffMs across
+	* every device. Drains fully: loops a page at a time until no stale rows
+	* remain. Returns deleted row ids.
+	*/
+	async pruneAll(cutoffMs) {
+		const ids = [];
+		for (;;) {
+			const rows = await this.store.query.query({
+				collection: OBJECT_EMBEDDINGS_COLLECTION,
+				filter: {
+					whereBetween: { timestamp: [0, cutoffMs] },
+					limit: 500
+				}
+			});
+			if (rows.length === 0) break;
+			let deletedInPage = 0;
+			for (const row of rows) {
+				const id = typeof row.id === "string" ? row.id : void 0;
+				if (!id) continue;
+				try {
+					await this.store.delete.mutate({
+						collection: OBJECT_EMBEDDINGS_COLLECTION,
+						key: id
+					});
+					ids.push(id);
+					deletedInPage++;
+				} catch {}
+			}
+			if (deletedInPage === 0) break;
+		}
+		return ids;
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/pipeline/face-matcher.ts
 /**
 * Assign at most one identity per track AND at most one track per identity for
@@ -5135,6 +5307,41 @@ function buildEventChildCrops(objectEvents, detections) {
 	return result;
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/embedding-search.ts
+/**
+* embedding-search — CLIP text→embedding cosine ranking helper.
+*
+* `rankByText` mirrors `face-matcher.matchEmbedding` with the identity-grouping
+* removed: it compares a single query vector against all rows, enforces the
+* same-modelId/dim gate, and returns the top-N rows above `minScore` sorted
+* descending by cosine similarity.
+*/
+/**
+* Brute-force cosine rank of `rows` against `queryVec`.
+*
+* Gate: same-modelId (when `opts.modelId` is set) AND same dimension as
+* `queryVec.length`. Rows that fail either gate are skipped.
+* Returns at most `opts.limit` rows with `score >= opts.minScore`,
+* ordered descending by score. Immutable — does not modify inputs.
+*/
+function rankByText(queryVec, rows, opts) {
+	const queryDim = queryVec.length;
+	const scored = [];
+	for (const row of rows) {
+		if (opts.modelId !== void 0 && row.modelId !== opts.modelId) continue;
+		if (row.dim !== queryDim) continue;
+		if (row.embedding.length !== queryDim) continue;
+		const score = cosineSimilarity(queryVec, new Float32Array(row.embedding));
+		if (score < opts.minScore) continue;
+		scored.push({
+			row,
+			score
+		});
+	}
+	scored.sort((a, b) => b.score - a.score);
+	return scored.slice(0, opts.limit);
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/bbox-pad.ts
 /**
 * Pad a normalized bounding box by a fractional amount relative to its own
@@ -5367,6 +5574,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	faceRecognizer = null;
 	plateStore = null;
 	plateRecognizer = null;
+	objectEmbeddingStore = null;
 	/** Frame-based event/track media (crop + boxed full-frame) from the
 	*  detection-pipeline DECODED frame — the ONLY image source (never the
 	*  snapshot cap). Null when shm frame access is unavailable. */
@@ -5432,6 +5640,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		await IdentityStore.declare(api.settingsStore);
 		await FaceStore.declare(api.settingsStore);
 		await PlateStore.declare(api.settingsStore);
+		await ObjectEmbeddingStore.declare(api.settingsStore);
 		const logger = this.ctx.logger;
 		const storage = this.ctx.kernel.storage;
 		if (!storage) throw new Error("pipeline-analytics requires ctx.kernel.storage");
@@ -5530,6 +5739,10 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			captureCrop,
 			logger: logger.child("PlateRecognizer")
 		});
+		this.objectEmbeddingStore = new ObjectEmbeddingStore({
+			store: api.settingsStore,
+			logger: logger.child("ObjectEmbeddingStore")
+		});
 		this.bindingCache = new BindingCache({
 			api,
 			logger: logger.child("BindingCache")
@@ -6092,6 +6305,17 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			} });
 		}
 		await Promise.all(result.objectEvents.map((e) => this.eventStore.insertObject(e)));
+		if (this.objectEmbeddingStore) {
+			for (const t of result.tracked) if (t.embedding !== void 0 && t.embeddingModelId !== void 0 && t.embeddingModelId.startsWith("mobileclip-")) this.objectEmbeddingStore.upsertIfBetter({
+				trackId: t.trackId,
+				deviceId,
+				timestamp: result.timestamp,
+				className: t.className,
+				embedding: t.embedding,
+				modelId: t.embeddingModelId,
+				confidence: t.confidence
+			});
+		}
 		const faceSettings = this.faceRecognizer ? await this.resolveDeviceFaceSettings(deviceId) : null;
 		const faceGloballyEnabled = this.faceRecognizer ? await this.resolveGlobalFaceEnabled() : false;
 		const mediaSettings = await this.resolveDeviceMediaSettings(deviceId);
@@ -6590,6 +6814,12 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			} catch (err) {
 				this.ctx.logger.debug("plate buffer prune failed", { meta: { error: String(err) } });
 			}
+			if (this.objectEmbeddingStore) try {
+				const deletedEmbIds = await this.objectEmbeddingStore.pruneAll(objectCutoffMs);
+				if (deletedEmbIds.length > 0) this.ctx.logger.info("object embedding retention prune", { meta: { deleted: deletedEmbIds.length } });
+			} catch (err) {
+				this.ctx.logger.debug("object embedding prune failed", { meta: { error: String(err) } });
+			}
 		} catch (err) {
 			this.ctx.logger.debug("sweepRetention failed", { meta: { error: String(err) } });
 		}
@@ -6734,6 +6964,90 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	async getTrackMedia(input) {
 		return this.mediaStore?.listByOwner("track", input.trackId) ?? [];
 	}
+	/**
+	* Search object events by text using CLIP cosine similarity.
+	*
+	* Flow:
+	*   1. Call `embedding-encoder.encodeText` to embed `text` → `queryVec`.
+	*   2. Query `objectEmbeddingStore` with optional prefilters (deviceId,
+	*      since/until, classFilter, modelId from encoder).
+	*   3. Rank candidates via `rankByText` (same-model/dim gate + cosine).
+	*   4. Fetch the corresponding ObjectEvents by trackId (via getObjectEvents
+	*      with each winner's deviceId + trackId filter) and join score.
+	*   5. Return at most `limit` ScoredObjectEvents sorted descending by score.
+	*/
+	async searchObjectEvents(input) {
+		const store = this.objectEmbeddingStore;
+		if (!store) return [];
+		const api = this.ctx.api;
+		if (!api) return [];
+		const encodeResult = await api.embeddingEncoder.encodeText.query({ text: input.text }).catch((err) => {
+			this.ctx.logger.warn("searchObjectEvents: encodeText failed", { meta: { error: String(err) } });
+			return null;
+		});
+		if (!encodeResult) return [];
+		const queryVec = new Float32Array(encodeResult.embedding);
+		const embeddingRows = await store.query({
+			deviceId: input.deviceId,
+			since: input.since,
+			until: input.until,
+			className: input.classFilter
+		});
+		if (embeddingRows.length === 0) return [];
+		const encoderInfo = await api.embeddingEncoder.getInfo.query().catch((err) => {
+			this.ctx.logger.warn("searchObjectEvents: getInfo failed, proceeding without modelId gate", { meta: { error: String(err) } });
+			return null;
+		});
+		const ranked = rankByText(queryVec, embeddingRows, {
+			minScore: input.minScore,
+			limit: input.limit,
+			...encoderInfo !== null ? { modelId: encoderInfo.modelId } : {}
+		});
+		if (ranked.length === 0) return [];
+		const byDevice = /* @__PURE__ */ new Map();
+		for (const { row, score } of ranked) {
+			const existing = byDevice.get(row.deviceId);
+			if (existing !== void 0) existing.push({
+				trackId: row.trackId,
+				score
+			});
+			else byDevice.set(row.deviceId, [{
+				trackId: row.trackId,
+				score
+			}]);
+		}
+		const scoreByTrackId = /* @__PURE__ */ new Map();
+		for (const { row, score } of ranked) scoreByTrackId.set(row.trackId, score);
+		const scored = [];
+		for (const [deviceId, winners] of byDevice) {
+			const trackIds = new Set(winners.map((w) => w.trackId));
+			const events = await (this.eventStore?.queryObject({
+				deviceId,
+				since: input.since,
+				until: input.until,
+				classFilter: input.classFilter,
+				limit: 5e3
+			}) ?? Promise.resolve([]));
+			const bestEventByTrackId = /* @__PURE__ */ new Map();
+			for (const ev of events) {
+				if (!ev.trackId || !trackIds.has(ev.trackId)) continue;
+				const score = scoreByTrackId.get(ev.trackId) ?? 0;
+				const existing = bestEventByTrackId.get(ev.trackId);
+				const newConf = ev.confidence ?? 0;
+				const prevConf = existing?.event.confidence ?? 0;
+				if (existing === void 0 || newConf > prevConf) bestEventByTrackId.set(ev.trackId, {
+					event: ev,
+					score
+				});
+			}
+			for (const { event, score } of bestEventByTrackId.values()) scored.push({
+				...event,
+				score
+			});
+		}
+		scored.sort((a, b) => b.score - a.score);
+		return scored.slice(0, input.limit);
+	}
 	async pruneEventsBefore(input) {
 		if (!this.eventStore) return {
 			motion: 0,

package/dist/pipeline-analytics/remoteEntry.js

@@ -30,7 +30,7 @@ async function d(e) {
 	}
 }
 async function f() {
-	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-D5LAGg5T.mjs")).catch((e) => {
+	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-DgAlWohT.mjs")).catch((e) => {
 		throw l = void 0, e;
 	}), l;
 }

package/dist/{resolve-frame-B2Do-e7z.js → resolve-frame-DB2NdMu2.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-BY1NQ5oi.js");
+const require_dist = require("./dist-n-zJ0Uox.js");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
 //#region src/shared/frame/crop-extractor.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-post-analysis",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "CamStack Post-Analysis bundle — enrichment, embedding-encoder, pipeline-analytics. Multi-entry npm package shipping addons that consume pipeline output.",
   "keywords": [
     "camstack",
@@ -34,6 +34,7 @@
   },
   "files": [
     "dist",
+    "python",
     "assets"
   ],
   "camstack": {

package/python/raw_tensor_inference.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Raw-tensor ONNX inference subprocess for the embedding encoder.
+
+Loads an ONNX model and runs raw, already-preprocessed tensors through
+onnxruntime in the embedded portable Python — replacing the former Node
+`onnxruntime-node` raw-tensor engine so the platform ships no Node ONNX
+runtime. The caller (PythonRawTensorEngine) handles all preprocessing; this
+script is a thin tensor in → tensor out bridge.
+
+Wire protocol (both directions): [4B little-endian payload_len][payload]
+  ready    (stdout, once):  payload = b"\\x01"
+  request  (stdin):         payload = [1B ndims][ndims × 4B LE uint32 dims][float32 LE data]
+  response (stdout):        payload = [1B ndims][ndims × 4B LE uint32 dims][float32 LE data]
+
+The Node side always sends float32; this script casts to the model's declared
+input dtype (e.g. int64 for CLIP text token ids) before running. Diagnostics go
+to stderr (stdout is the binary framing channel only).
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+import numpy as np
+import onnxruntime as ort
+
+from tensor_frames import (
+    READY_FRAME,
+    decode_tensor,
+    encode_tensor,
+    read_frame,
+    write_frame,
+)
+
+
+def numpy_dtype_for(onnx_type: str):
+    if "int64" in onnx_type:
+        return np.int64
+    if "int32" in onnx_type:
+        return np.int32
+    if "float16" in onnx_type:
+        return np.float16
+    return np.float32
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("model")
+    args = ap.parse_args()
+
+    print(f"raw_tensor_inference: loading model {args.model}", file=sys.stderr)
+    sess = ort.InferenceSession(args.model, providers=["CPUExecutionProvider"])
+    inp = sess.get_inputs()[0]
+    input_name = inp.name
+    input_dtype = numpy_dtype_for(inp.type)
+    output_name = sess.get_outputs()[0].name
+
+    write_frame(READY_FRAME)  # ready
+
+    while True:
+        payload = read_frame()
+        if payload is None:
+            break
+
+        data = decode_tensor(payload)
+        feed = data.astype(input_dtype, copy=False)
+
+        out = sess.run([output_name], {input_name: feed})[0]
+        write_frame(encode_tensor(np.asarray(out)))
+
+
+if __name__ == "__main__":
+    main()

package/python/requirements-embedding.txt

@@ -0,0 +1,8 @@
+# Raw-tensor ONNX inference for the embedding encoder (raw_tensor_inference.py),
+# run in the embedded portable Python. Installed lazily via
+# ctx.deps.installPythonRequirements the first time an embedding engine boots.
+numpy>=1.26,<3
+onnxruntime>=1.20,<2
+# HF Rust tokenizers — exact CLIP BPE for text_encoder_inference.py (linux-x86_64
+# + macOS-arm64 wheels). Replaces the former hand-rolled TS CLIP BPE.
+tokenizers>=0.20,<1

package/python/tensor_frames.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Length-prefixed binary tensor framing shared by the embedding-encoder
+Python inference scripts (`raw_tensor_inference.py`, `text_encoder_inference.py`).
+
+Wire protocol (both directions): [4B little-endian payload_len][payload]
+  ready    (stdout, once):  payload = b"\\x01"
+  tensor   (either way):    payload = [1B ndims][ndims × 4B LE uint32 dims][float32 LE data]
+  text     (stdin):         payload = UTF-8 encoded request text (text encoder only)
+
+stdout is the binary framing channel ONLY — all diagnostics go to stderr.
+"""
+from __future__ import annotations
+
+import struct
+import sys
+
+import numpy as np
+
+READY_FRAME = b"\x01"
+
+
+def write_frame(payload: bytes) -> None:
+    """Write a single length-prefixed frame to stdout and flush."""
+    sys.stdout.buffer.write(struct.pack("<I", len(payload)))
+    sys.stdout.buffer.write(payload)
+    sys.stdout.buffer.flush()
+
+
+def read_exact(n: int) -> bytes | None:
+    """Read exactly n bytes from stdin, or None on EOF."""
+    buf = bytearray()
+    while len(buf) < n:
+        chunk = sys.stdin.buffer.read(n - len(buf))
+        if not chunk:
+            return None
+        buf.extend(chunk)
+    return bytes(buf)
+
+
+def read_frame() -> bytes | None:
+    """Read one length-prefixed frame payload from stdin, or None on EOF."""
+    header = read_exact(4)
+    if header is None:
+        return None
+    (plen,) = struct.unpack("<I", header)
+    payload = read_exact(plen)
+    return payload
+
+
+def encode_tensor(arr: np.ndarray) -> bytes:
+    """Encode a numpy array as a float32 tensor frame payload."""
+    arr = np.ascontiguousarray(arr, dtype=np.float32)
+    out = bytearray()
+    out.append(arr.ndim)
+    for d in arr.shape:
+        out += struct.pack("<I", int(d))
+    out += arr.tobytes()
+    return bytes(out)
+
+
+def decode_tensor(payload: bytes) -> np.ndarray:
+    """Decode a float32 tensor frame payload into a numpy array."""
+    ndims = payload[0]
+    off = 1
+    dims = []
+    for _ in range(ndims):
+        (d,) = struct.unpack_from("<I", payload, off)
+        off += 4
+        dims.append(d)
+    return np.frombuffer(payload, dtype=np.float32, offset=off).reshape(dims)

package/python/test_text_encoder.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Reference-parity test for the CLIP text tokenization done in Python.
+
+Proves the HF `tokenizers` Rust BPE (loaded from the same hosted
+`tokenizer.json` that ships beside every MobileCLIP text encoder) reproduces the
+canonical CLIP reference ids and pads/truncates to the fixed 77-token context
+window — i.e. tokenization is exact by construction, replacing the former
+hand-rolled TypeScript BPE.
+
+Run in a throwaway venv with the embedding requirements installed:
+
+    python3 -m venv /tmp/tokv
+    /tmp/tokv/bin/pip install tokenizers onnxruntime numpy
+    /tmp/tokv/bin/python -m pytest packages/addon-post-analysis/python/test_text_encoder.py
+"""
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from text_encoder_inference import CONTEXT_LENGTH, build_tokenizer
+
+# The locally-staged tokenizer.json (sibling of the MobileCLIP S1 text onnx).
+TOKENIZER_PATH = os.environ.get(
+    "CLIP_TOKENIZER_JSON", "/tmp/mobileclip/s1/tokenizer.json"
+)
+
+# Ground-truth ids from the HF `tokenizers` reference (include SOT 49406 + EOT
+# 49407, exclude padding). The Python tokenization MUST reproduce these exactly.
+REFERENCE_TEXT = "a photo of a cat"
+REFERENCE_IDS = [49406, 320, 1125, 539, 320, 2368, 49407]
+
+
+@pytest.mark.skipif(
+    not os.path.exists(TOKENIZER_PATH),
+    reason=f"tokenizer.json not staged at {TOKENIZER_PATH}",
+)
+def test_clip_reference_parity_and_padding() -> None:
+    tokenizer = build_tokenizer(TOKENIZER_PATH)
+    encoded = tokenizer.encode(REFERENCE_TEXT)
+
+    # The first 7 ids are SOT + 5 body tokens + EOT — the canonical CLIP ids.
+    assert encoded.ids[:7] == REFERENCE_IDS
+    # truncation + padding fixed the sequence to exactly the CLIP context window.
+    assert len(encoded.ids) == CONTEXT_LENGTH
+    # Everything after the reference ids is pad (id 0).
+    assert all(i == 0 for i in encoded.ids[7:])

package/python/text_encoder_inference.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""CLIP text-encoder inference subprocess for the embedding encoder.
+
+Loads a CLIP text-encoder ONNX model plus its HuggingFace `tokenizers`-format
+`tokenizer.json`, then for each request: tokenizes UTF-8 text into the fixed
+77-token CLIP context window (exact-by-construction via the HF Rust tokenizer),
+feeds the int64 token-id tensor through onnxruntime, and returns the output
+embedding as a float32 tensor frame.
+
+This replaces the hand-rolled TypeScript CLIP BPE — tokenization here is exact
+by construction (same `tokenizers` library that produced the reference ids).
+
+Wire protocol (both directions): [4B little-endian payload_len][payload]
+  ready    (stdout, once):  payload = b"\\x01"
+  request  (stdin):         payload = UTF-8 encoded text
+  response (stdout):        payload = [1B ndims][ndims × 4B LE uint32 dims][float32 LE data]
+
+Diagnostics go to stderr (stdout is the binary framing channel only).
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+import numpy as np
+import onnxruntime as ort
+from tokenizers import Tokenizer
+
+from tensor_frames import READY_FRAME, encode_tensor, read_frame, write_frame
+
+# CLIP fixed context length — token ids are truncated/padded to exactly this.
+CONTEXT_LENGTH = 77
+PAD_ID = 0
+
+
+def build_tokenizer(tokenizer_path: str) -> Tokenizer:
+    tok = Tokenizer.from_file(tokenizer_path)
+    tok.enable_truncation(max_length=CONTEXT_LENGTH)
+    tok.enable_padding(length=CONTEXT_LENGTH, pad_id=PAD_ID)
+    return tok
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("model")
+    ap.add_argument("tokenizer")
+    args = ap.parse_args()
+
+    print(
+        f"text_encoder_inference: loading model {args.model} "
+        f"tokenizer {args.tokenizer}",
+        file=sys.stderr,
+    )
+    sess = ort.InferenceSession(args.model, providers=["CPUExecutionProvider"])
+    input_name = sess.get_inputs()[0].name
+    output_name = sess.get_outputs()[0].name
+    tokenizer = build_tokenizer(args.tokenizer)
+
+    write_frame(READY_FRAME)  # ready
+
+    while True:
+        payload = read_frame()
+        if payload is None:
+            break
+
+        text = payload.decode("utf-8")
+        encoded = tokenizer.encode(text)
+        # `enable_truncation`/`enable_padding` already fixed this to length 77.
+        ids = np.asarray(encoded.ids, dtype=np.int64).reshape(1, CONTEXT_LENGTH)
+
+        out = sess.run([output_name], {input_name: ids})[0]
+        write_frame(encode_tensor(np.asarray(out)))
+
+
+if __name__ == "__main__":
+    main()