Metadata-Version: 2.2
Name: es2
Version: 1.1.0rc1
Summary: A client application for performing encrypted vector search using homomorphic encryption.
Author-Email: cryptolabinc <pypi@cryptolab.co.kr>
License: Proprietary
Classifier: License :: Other/Proprietary License
Requires-Python: <3.14,>=3.9
Requires-Dist: grpcio<=1.74.0,>=1.49.1
Requires-Dist: protobuf<6.0.0,>=5.0.0
Requires-Dist: loguru
Requires-Dist: numpy>=2.0.2
Requires-Dist: tqdm
Requires-Dist: cryptography
Provides-Extra: colab
Requires-Dist: numpy==2.0.2; extra == "colab"
Description-Content-Type: text/markdown

# What is ES2?
ES2 (Encrypted Similarity Search) is a high-performance encrypted vector search engine designed to protect data privacy during similarity search. It enables users to search over encrypted vectors without ever exposing the raw data or query.

By leveraging advanced encryption techniques such as homomorphic encryption and secure computation, ES2 ensures that both the vector data and similarity scores remain confidential — even during computation.

ES2 is provided as a Python client package. For more details, visit https://heaan.com/.

# ES2 Example

This example demonstrates the complete workflow of the ES2 Self-Hosted Python SDK, showcasing its capabilities for encrypted similarity search and vector database operations.

---

## Import ES2

At the very first time, you should install and import the `es2` package to use Python APIs.

```bash
pip install es2
```

```python
import es2
```

---

## 🔍 Vector Search

### 1. Initialize ES2

To use the ES2 service, initialization is required. This includes establishing a connection to the ES2 server and configuring settings necessary for vector search.

```python
es2.init(
    host="localhost",
    port=50050,
    key_path="./keys",
    key_id="quickstart_key",
)
```

---

### 2. Create Index

You need to create an index before inserting data. The index is defined by its name and vector dimensionality.

```python
index = es2.create_index("quickstart_index", dim=512)
```

---

### 3. Insert Data

You can insert random or real vectors into the created index. Below is an example using random 512-dimensional vectors with normalization and metadata.

```python
import numpy as np

# Function to generate normalized random vectors
def generate_random_vector(dim):
    if dim <= 16 or dim > 4096:
        raise ValueError(f"Invalid dimension: {dim}.")

    vec = np.random.uniform(-1.0, 1.0, dim)
    norm = np.linalg.norm(vec)

    if norm > 0:
        vec = vec / norm

    return vec

# Prepare sample data
num_data = 10
db_vectors = [generate_random_vector(512) for _ in range(num_data)]
db_metadata = [f"data_{i+1}" for i in range(num_data)]

# Insert into index
index.insert(db_vectors, metadata=db_metadata)
```

---

### 4. Encrypted Similarity Search

Use a query vector to find similar vectors. The `index` object enables encrypted search and decryption of scores on the client side.

```python
query = db_vectors[1]
top_k = 2

result = index.search(query, top_k=top_k, output_fields=["metadata"])
print(result)
```

---

## 🧹 Clean Up

To remove test data and release keys, you can call:

```python
es2.drop_index("quickstart_index")
es2.release_key("quickstart_key")
```

---
