🎯Scoring

A full search consists of three steps:

1. Scoring – compute similarity scores in ciphertext

2. Decryption – decrypt the score vector locally on the client

3. Metadata retrieval – request the top-k metadata entries mapped to the scores

The scoring API corresponds to the first step in this process. Instead of performing the entire full search pipeline, you can call scoring() directly to obtain the encrypted similarity scores only.

The query can be:

• A plaintext query (if query_encryption=False in the index configuration), or

• A ciphertext query (manually encrypted, or automatically if query_encryption=True).

---

Scoring with Plaintext Query

Example

import pyenvector as ev
import numpy as np

# Prepare normalized data
vecs = np.random.rand(100, 512)
vecs = vecs / np.linalg.norm(vecs, axis=1, keepdims=True)

# Initialize with plaintext query option
ev.init(
    address="localhost:50050",
    key_path="keys",
    key_id="example",
    query_encryption=False
)

# Create index and insert vectors
index = ev.create_index("example_index", dim=512)
metadata = [f"metadata_{i}" for i in range(100)]
index.insert(vecs, metadata)

# Perform scoring with a plaintext query
search_index = ev.Index("example_index")
query = vecs[0]
scores = search_index.scoring(query)[0]

print(scores)
# Output:
# <pyenvector.crypto.block.CipherBlock object at 0x7fac8052d6d0>

---

Scoring with Ciphertext Query

Example

import pyenvector as ev
import numpy as np

# Prepare normalized data
vecs = np.random.rand(100, 512)
vecs = vecs / np.linalg.norm(vecs, axis=1, keepdims=True)

# Initialize with automatic query encryption enabled
ev.init(
    address="localhost:50050",
    key_path="keys",
    key_id="example",
    query_encryption=True
)

# Create index and insert vectors
index = ev.create_index("example_index", dim=512)
metadata = [f"metadata_{i}" for i in range(100)]
index.insert(vecs, metadata)

# Manually encrypt the query (optional when query_encryption=True)
search_index = ev.Index("example_index")
query = vecs[0]
encrypted_query = search_index.cipher.encrypt(query, "query")

# Perform scoring with the ciphertext query
# scores_1 = search_index.scoring(query)[0]   # would work if query_encryption is enabled
scores_2 = search_index.scoring(encrypted_query)[0]

print(scores_2)
# Output:
# <pyenvector.crypto.block.CipherBlock object at 0x7fac8052d6d0>

---

📌 Summary

• scoring() returns an encrypted vector of similarity scores (one encrypted score for each vector stored in the index).

• With query_encryption=False, you can pass a plaintext query.

• With query_encryption=True, you can either pass a plaintext query (auto-encrypted) or an explicitly encrypted query.