Quick setup

git clone https://github.com/bajpai-labs/vortex-pqc.git
cd vortex-pqc

python3 -m venv .venv
source .venv/bin/activate

pip install -U pip wheel
pip install -e ".[dev]"

make test

Expected output ends with 26 passed (Python) and All tests passed (C).

Daily commands

Command	What it does
make test	Python + C test suites
make test-python	Python tests only
make test-c	C library tests only
make lint	flake8 + mypy
make build	Build Python wheel → dist/
make clean	Remove all build artifacts
make -C c demo	Run Alice–Bob CLI demo

Where to edit

Change	Files
Public Python API	src/vortex_pqc/core.py, __init__.py
Crypto logic (reference)	src/vortex_pqc/_pure.py
Scheme parameters	src/vortex_pqc/params.py
PEM encoding	src/vortex_pqc/pem.py
C KEM operations	c/src/vortex_core.c
C polynomial math	c/src/vortex_poly.c
Python ↔ C bindings	c/src/python_module.c
C public header	c/include/vortex_pqc.h

Golden rule: changes to _pure.py must be mirrored in the C implementation. Both backends must produce identical byte outputs.

Running tests

# Everything
make test

# Single Python test
python -m pytest src/tests/test_core.py::test_round_trip_basic -v

# With coverage
python -m pytest src/tests/ --cov=vortex_pqc --cov-report=term-missing

# C only
make -C c test

What must always pass

Suite	File	Covers
Python core	test_core.py	Round-trip, rejection, validation
Python PEM	test_pem.py	Encode/decode, file I/O, permissions
C library	test_vortex.c	Round-trip, tamper rejection, sizes

Rebuilding the native extension

After editing C sources:

pip install -e . --force-reinstall --no-deps

Verify:

import vortex_pqc
assert "native" in vortex_pqc.native_backend()

Debugging tips

Force pure-Python backend

Temporarily move the compiled extension aside to isolate C bugs:

mv src/vortex_pqc/_native*.so /tmp/
python -m pytest src/tests/ -v

Run the C demo

make -C c demo
./c/examples/demo

Benchmark both backends

from vortex_pqc import benchmark_throughput, native_backend

print(f"Backend: {native_backend()}")
print(benchmark_throughput(20))

Lint & type-check

make lint

# Individual
python -m flake8 src/vortex_pqc/ --max-line-length=100
python -m mypy src/vortex_pqc/ --ignore-missing-imports

Shipping a release

One-time PyPI setup

1. Create project vortex-pqc on pypi.org
2. Generate an API token
3. Add PYPI_API_TOKEN to GitHub → Settings → Secrets → Actions

Release checklist

□ Bump version in pyproject.toml
□ Bump __version__ in src/vortex_pqc/__init__.py
□ Run make test && make lint
□ Commit and push to main
□ Create GitHub Release (tag: v0.x.x)
□ CI publishes automatically via release.yml

Manual publish (emergency)

make build
twine check dist/*
twine upload dist/*

Contributor checklist

□ Implement in _pure.py (reference)
□ Mirror in C if performance-critical
□ Export from core.py / __init__.py if public
□ Add tests in src/tests/
□ Update docs/api-reference.md
□ Update docs/getting-started.md if user-facing
□ Run make test && make lint

Security rules

Do	Don't
Use hmac.compare_digest for secret comparisons	Log keys, seeds, or shared secrets
Clear secret buffers in C with secure_zero	Commit .pem, .key, or .env files
Report vulnerabilities to hello@bajpailabs.com	Skip security tests to make CI green

CI pipeline

Every push and PR to main runs:

Job	Matrix	Steps
Python	Ubuntu + macOS × 3.10/3.11/3.12	install → pytest → lint → mypy
C library	Ubuntu + macOS	make -C c test

→ Defined in .github/workflows/ci.yml

Documentation sync

Published docs live in the central Bajpai Labs documentation repo:

bajpai-labs/documentation → docs/vortex-pqc

Automatic (CI)

On every push to main that changes docs/**, the workflow .github/workflows/sync-docs.yml rsyncs this folder to documentation/docs/vortex-pqc/ and commits the result.

One-time GitHub setup

1. Create a fine-grained or classic PAT with Contents: Read and write on bajpai-labs/documentation
2. In vortex-pqc → Settings → Secrets → Actions, add:
   • Name: DOCS_SYNC_TOKEN
   • Value: your PAT

Manual sync (local)

git clone https://github.com/bajpai-labs/documentation.git ../documentation
chmod +x scripts/sync-docs.sh
./scripts/sync-docs.sh ../documentation
cd ../documentation
git add docs/vortex-pqc/
git commit -m "docs(vortex-pqc): manual sync"
git push origin main