nx_imgsearch.nx

nx_imgsearch.nx -- THE REVERSE-IMAGE SERVICE ORGAN: the MCP/API face of the multi-tier engine. Every verb emits STRICT JSON on stdout, because the callers are agents and workflows, not humans. That drives three rules the whole file obeys: * HONEST ABSENT. "not found" is `{"present":false}` with a reason, never an empty list that a caller can mistake for "not searched" and never the nearest thing dressed up as a match. * SELF-DESCRIBING. `status` returns the live tier roster, every threshold, and the MEASURED per-class robustness with its gaps named, so an agent can decide whether this engine can answer its question before asking. A tool that cannot state its own limits cannot be trusted with one. * EVERY RESULT CARRIES ITS PROVENANCE -- which tier matched, at what distance, at which orientation, and whether that tier was CONFIDENT (inside its own threshold) or merely nearest. INDEX FORMAT (versioned, fixed-stride, mmap-first -- the scale decision): header 32B : magic "NXIMGIDX" | u32 version | u32 stride | i64 count | i64 cidblob_off record 96B : i64 dhash | u8 visdesc[80] | u32 cid_off | u32 cid_len then : the cid string blob Fixed stride means O(1) random access and no parsing, so the index is opened with sys_map_file -- the same read-only file-backed map that moved the text shard off the RAM ceiling onto the page cache. The 80-dimension descriptor is QUANTISED TO u8 AT INGEST (its dimensions are already on a 0..256 scale, so this costs at most one unit on a saturated bin): 96 bytes per image on disk against 648 bytes unquantised, which is the difference between a 10M-image index fitting a NAS volume and not. Same integer-quantisation-at-ingest discipline the text engine rides. HONEST CEILING, reported in the JSON rather than hidden: `query` currently EXPANDS the mmap'd records into the engine's i64 descriptor arrays, so serving RAM is ~648 bytes/image even though storage is 96. The named fix is a u8-native similarity tier that computes L1 straight off the mapped bytes, making serving disk-bound like the text side. Until that lands the ceiling is real and this tool prints it. license_tier: ORIGINAL