Quick Start

Get started with a simple API flow!

This page offers two quick paths:

  • Path A: Minimal — insert and search with the simplest API

  • Path B: Full Crypto Cycle — explicit key generation, item encryption, query encryption, scoring, decryption, top‑k

Tip: An index is a logical collection of same‑dimension vectors with optional metadata — think of it like a table in an RDBMS.

Path A — Minimal (Insert & Search)

1

Install SDK

# Create & activate a virtual environment
python -m venv ev-env
source ev-env/bin/activate

# Install client SDK
pip install pyenvector
2

Connect + Create Index

import pyenvector as ev

ev.init(address="localhost:50050", key_path="keys", key_id="quickstart")
index = ev.create_index("my_ev_index", dim=512)
3

Insert Vectors

You can pass plaintext vectors; the SDK encrypts them before sending so the server never sees plaintext.

import numpy as np

vecs = np.random.rand(10, 512)
vecs = vecs / np.linalg.norm(vecs, axis=1, keepdims=True)  # normalize for IP
metadata = [f"Item {i+1}" for i in range(10)]

index.insert(vecs, metadata)
4

Search

search() performs: (1) encrypted scoring on the server, (2) client‑side decrypt, (3) top‑k metadata retrieval.

search_index = ev.Index("my_ev_index")
query = vecs[0]
results = search_index.search(query, top_k=3, output_fields=["metadata"])[0]
print(results)

Scoring = server‑side encrypted similarity; decrypt + top‑k complete the search on the client.

Path B — Explicit Crypto Cycle

1

Install + Connect

import pyenvector as ev

# Connect only (no auto key setup)
ev.init_connect(address="localhost:50050")
2

Generate Keys

from pyenvector.crypto import KeyGenerator

# Generate keys locally under key_dir = keys/crypto-qs
keygen = KeyGenerator(key_path="keys/crypto-qs")
keygen.generate_keys()
3

Init Index Config

# Point SDK to the generated keys; avoid auto generation
ev.init_index_config(
    key_path="keys",
    key_id="crypto-qs",
    query_encryption="cipher",
    auto_key_setup=False,
)
4

Register Key

# Register and load the key on the server
ev.register_key(key_id="crypto-qs")
ev.load_key(key_id="crypto-qs")

# Create an index bound to this key config
index = ev.create_index("crypto_qs_index", dim=512)
5

Encrypt Items + Insert

import numpy as np
from pyenvector.crypto import Cipher

vecs = np.random.rand(10, 512)
vecs = vecs / np.linalg.norm(vecs, axis=1, keepdims=True)
metadata = [f"Item {i+1}" for i in range(10)]

cipher = Cipher(dim=512, enc_key_path="keys/crypto-qs/EncKey.json")

# Explicitly encrypt each item (vector) before sending
enc_vectors = [cipher.encrypt(v, "item") for v in vecs]

# Insert encrypted items with metadata
index.insert(enc_vectors, metadata)
6

Encrypt Query + Scoring

search_index = ev.Index("crypto_qs_index")

# Encrypt the query explicitly (query encryption)
query = vecs[0]
enc_query = cipher.encrypt(query, "query")

# Server performs encrypted similarity scoring; response is encrypted
encrypted_scores = search_index.scoring(enc_query)[0]
7

Decrypt + Top‑k

sec_key_path = "keys/crypto-qs/SecKey.json"
scores = cipher.decrypt_score(encrypted_scores, sec_key_path=sec_key_path)

topk = search_index.get_topk_metadata_results(scores, top_k=3, output_fields=["metadata"])
print(topk)

References

PreviousIntroductionNextMCP Guide

Last updated