---
title: Visual Lookup
framework: Private Cloud Compute Security Guide
role: article
role_heading: Article
path: private-cloud-compute/visuallookup
---

# Visual Lookup

PCC identifies visual entities from image embeddings, using private information retrieval so the host does not learn which entries a query reads.

## Overview

Overview Visual Lookup (VLU) enables users to identify visual entities — such as pets, landmarks, art, and books — by matching image embeddings against a database of known entities. Because VLU queries reveal information about content a user views, we designed the system to help protect query privacy by pairing PCC with private information retrieval. VLU workflow VLUAgent is a PCC Agent workflows that performs visual search using the following steps: Receives an embedding and metadata from the user’s device Retrieves a target cluster from the visual entity database using Private Information Retrieval (PIR) Applies custom ranking logic within the cluster Returns candidate documents with resolved metadata to the user’s device Visual entity database The visual entity database contains embeddings and metadata for known entities. Its cluster index is hosted on a server outside the PCC High-security inference, so VLU relies on PIR to prevent the database server from learning which entries a query accesses. The database is organized into clusters to enable an efficient two-stage search: first selecting the index of the most relevant cluster using the codebook and retrieving it using PIR, then identifying the best match within that cluster. This clustering approach reduces the search space for each query and lowers the computational cost of PIR operations. The database consists of three data structures: Cloud asset distribution delivers both the stash and the codebook to PCC nodes. An index can also ship to the node in full. When the delivered asset includes an offline variant of an index, CipherMLSE answers lookups against it from node-local storage without a PIR query. VLUAgent searches that variant alongside the PIR-backed indexes for book and media lookups, so a result in those domains can come from an index the node holds in full. Request flow VLU query processing proceeds as follows: The user’s device generates an image embedding on-device. Because the embedding is generated locally, the raw image does not leave the device. The user’s device uses the PCC client to send this embedding to the VLUAgent workflow. VLUAgent makes a Delegated tool calls with the embedding to a PCCAgentWorkerApp running on another PCC node. PCCAgentWorkerApp forwards the embedding to its associated cb_jobhelper, which uses the CipherMLSE framework to find the cluster centroid in the codebook nearest to the embedding. This determines which cluster is most likely to contain matching entities. cb_jobhelper generates and submits a PIR query for the index of the relevant cluster, following the Request flow. cb_jobhelper returns the resulting cluster (from either the decrypted PIR response or the stash) to PCCAgentWorkerApp, which returns it to VLUAgent. Both PCCAgentWorkerApp and cb_jobhelper then terminate. VLUAgent re-ranks the results within the cluster to find the nearest or best-matching entries. VLUAgent performs additional delegated tool calls to resolve the metadata for the best-matching entries. VLUAgent attaches metadata (such as titles) to the best-matching entries and returns them to the user’s device. For additional information about the cryptographic operations performed, see Private Information Retrieval. note: cb_jobhelper: The per-request job helper that runs steps 4 through 6. PIRHelper: The class implementing the PIR logic for those steps. It imports CipherMLSE, issues the PIR query, and processes the response. CipherMLSE framework The CipherMLSE framework provides VLU-specific operations for embedding-based search: tip: To exercise the PIR retrieval path end to end in the VRE against the test PIR server in the pcc-vre-pir-service repository, follow Exercise Visual Lookup. Security properties Visual Lookup is designed to provide security and privacy properties specific to visual search: