enVector Python SDK: Development Environment Setup

Requirements

Ubuntu

• OS: Ubuntu 22.04+
• Shell: bash
• Python: 3.12 (recommended)
• Virtual Environment: pipenv

Mac

• OS: macOS Sequoia 15.5+
• Shell: zsh
• Package Manager: Homebrew
• Python: 3.12 (recommended)
• Virtual Environment: pipenv

---

0. Install Dependencies (Linux)

sudo apt-get update
sudo apt-get install -y make build-essential \
  libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev \
  libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev git

1. Clone the Repository

Tip: Make sure your SSH key is registered with GitHub for private repo access.

git config url."git@github.com:".insteadOf https://github.com/
git clone git@github.com:CryptoLabInc/envector-python-sdk.git

---

2. Quick Setup (Recommended)

For SDK developers:

Use this quick setup to prepare a full development environment.

For SDK User:

See section 4 (B) below if you only want to build the wheel file for distribution or installation.

./scripts/setup.sh --python 3.12
# Check importing pyenvector and its version
pipenv run python -c "import pyenvector as ev; print(ev.__version__)"
# Activate Pipenv
pipenv shell

• Default Python version is 3.12.
• All dependencies, submodules, and build steps are automated.

---

3. Manual Step-by-Step Setup

# 1. Initialize submodules
./scripts/init_evi_crypto.sh

# 3. Install Python & pipenv
#
# If the above scripts do not work for your system, please ensure that Python 3.12 and pipenv are installed manually.
# You can use your OS package manager, pyenv, conda, or any other method to install Python 3.12 and pipenv.
# After installation, continue with the next steps.
./scripts/install_deps_linux.sh   # For Linux
./scripts/install_deps_mac.sh     # For Mac

# 4. Set up pipenv environment
./scripts/setup_pipenv.sh

# 5. Build and install the SDK
pipenv run ./scripts/build_and_install.sh

# 6. Check importing pyenvector and its version
pipenv run python -c "import pyenvector as ev; print(ev.__version__)"

# 7. Activate Pipenv
pipenv shell

---

4. Build a Wheel File

Note: The wheel file (.whl) is intended for deployment and distribution, not for development. SDK developers should NOT use the wheel build for development. If you are developing the SDK, skip this section and use the Quick Setup above. Only follow these instructions if you need to generate a wheel for deployment or installation elsewhere.

(A) If you have already run ./scripts/setup.sh and have a working pipenv environment:

# Activate Pipenv
pipenv shell

pipenv run export-wheel

pip install dist/pyenvector-XXX.whl

(B) If you have NOT run ./scripts/setup.sh (or want to only build the wheel):

./scripts/setup.sh --type wheel
# The wheel file will be generated in the dist/ directory
pipenv shell

pip install dist/pyenvector-XXX.whl

---

5. Run Tests

pipenv run pytest

---

6. Build Documentation

Note: Make sure the SDK is installed before building docs.

pipenv run docs

---

7. CLI Key Generation Example

You can generate keys using the CLI after installing the SDK wheel. Keys will be stored in {key_path}/{key_id}.

Basic Usage

source .venv/bin/activate
# Generate keys without KEK (Key Encryption Key)
pyenvector-keygen --key-path keys --key-id id --seal-mode none --metadata-encryption true

Generate keys with AES KEK

pyenvector-keygen --key-path keys --key-id seal --seal-mode aes --seal-key-path aes.kek --eval-mode rmp --preset ip

Upload keys directly to AWS

pyenvector-keygen \
  --key-store aws \
  --key-id test-envector \
  --region-name ap-northeast-2 \
  --bucket-name envector-cli \
  --secret-prefix envector/keys

Arguments (with defaults):

• --dim / --dim_list: Dimensions to generate (default: 32 64 128 256 512 1024 2048 4096)
• --key-path / --key_path: Directory to store keys (default: ./keys; ignored when using --key-store aws)
• --key-id / --key_id: Key identifier (required for AWS mode)
• --preset: Parameter preset (e.g. ip, default: ip)
• --eval-mode / --eval_mode: Evaluation mode (e.g. rmp, default: rmp)
• --seal-mode / --seal_mode: Seal mode (none or aes, default: none; must stay none when using AWS)
• --seal-key-path / --seal_key_path: Path to AES KEK file (required when --seal-mode aes)
• --seal-key-stdin / --seal_key_stdin: Read AES KEK from stdin (overrides --seal-key-path)
• --metadata-encryption / --metadata_encryption: Metadata encryption (true by default)
• --key-store / --key_store: local (default) writes JSON files, aws uploads key streams to AWS
• --region-name / --region_name: AWS region (required when --key-store aws)
• --bucket-name / --bucket_name: AWS S3 bucket for encrypted/eval keys (required for AWS)
• --secret-prefix / --secret_prefix: AWS Secrets Manager prefix for Sec/Metadata keys (required for AWS)

When using --key-store aws, keys are generated in-memory using generate_keys_stream and uploaded directly to AWS (no local files are written, and sealing options are disabled).

If you use --seal_kek_stdin, you can provide the KEK via standard input:

echo "your-32-byte-kek" | pyenvector-keygen \
--key-path keys \
--key-id seal \
--seal-mode aes \
--seal-key-stdin \
--eval-mode rmp \
--preset ip \
--metadata-encryption true

Or, you can use file redirection:

pyenvector-keygen --key-path keys --key-id seal --seal-mode aes --seal-key-stdin --eval-mode rmp --preset ip < aes.kek

---

For troubleshooting or custom setups, refer to each script's comments and logs. If you encounter issues with Python or pipenv installation, please install them manually and retry the setup steps.

Whl User (MacOS)

brew install virtualenv python@3.12 libomp
virtualenv -p python3.12 pyenvector_venv
source pyenvector_venv/bin/activate
pip install dist/pyenvector-1.0.0-cp312-cp312-macosx_15_0_arm64.whl

Whl User (Linux)

# Make sure Python 3.12 is available in your virtual environment, or use pyenv to install python3.12

# Install Pyenv (if you do not have python3.12 and virtualenv)
rm -rf "$HOME/.pyenv"  # Remove existing pyenv directory if it exists
curl https://pyenv.run | bash
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
pyenv install 3.12
pyenv global 3.12

# Activate virtualenv and install whl file
pip install virtualenv
virtualenv -p python3.12 pyenvector_venv
source pyenvector_venv/bin/activate
pip install dist/pyenvector-1.0.0-cp312-cp312-linux_x86_64.whl

Log Level Troubleshooting:

• By default, SDK logs are hidden. To enable detailed loguru logs (for debugging), set the environment variable before running any Python commands:

export PYENVECTOR_LOG_LEVEL=DEBUG  # PYENVECTOR_LOG_LEVEL is still accepted for compatibility

• This will show debug-level logs for SDK operations.

How to Deploy a Wheel to PyPI

export GITHUB_TOKEN="{your_github_token}"
export WHEEL_VERSION="x.x.x"
# build wheel by os
./scripts/build_wheel_by_os.sh

export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="{your_pypi_api_token}"
# uplooad test pypi
./scripts/upload_wheel_to_pypi.sh
# upload to pypi
UPLOAD_TARGET="release-pypi" ./scripts/upload_wheel_to_pypi.sh

# download stable version
pip install pyenvector
# download pre-release version
pip install pyenvector --pre