Skip to main content

​
Development Guide

Welcome to the VeriSynth Core developer guide.
This document walks you through setting up your local environment, running the CLI, writing tests, and contributing to the project. VeriSynth Core is fully open source (MIT licensed) and welcomes community contributions.

​
1. Clone the Repository

git clone https://github.com/verisynth/verisynth-core.git
cd verisynth-core

​
2. Create a Virtual Environment

We recommend using Python 3.10+ and a virtual environment for isolation. 
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# OR
.venv\Scripts\activate     # Windows

​
3. Install Dependencies

pip install -r requirements.txt
For development (with linting, testing, and docs): 
pip install -e ".[dev]"

​
4. Project Structure

verisynth-core/
│
├── verisynth/              # Core library
│   ├── cli.py              # CLI entrypoint
│   ├── synth.py            # Synthesis logic (Gaussian Copula, etc.)
│   ├── proof.py            # Merkle root + hashing utilities
│   ├── metrics.py          # Correlation + privacy metrics
│   └── __init__.py
│
├── data/                   # Sample datasets
├── tests/                  # Unit tests
├── out/                    # Synthetic output + proof receipts (ignored in .gitignore)
├── README.md
├── setup.py / pyproject.toml
└── requirements.txt

​
5. Run the CLI (Development Mode)

You can run VeriSynth directly from source: 
python -m verisynth.cli data/sample_patients.csv -o out/ --rows 1000
Or after install: 
verisynth data/sample_patients.csv -o out/ --rows 1000

​
6. Testing

We use pytest as our primary testing framework. Run all tests: 
pytest
Run a single test file: 
pytest tests/test_synth.py -v
To see coverage: 
pytest --cov=verisynth --cov-report=term-missing

​
7. Contributing

We welcome pull requests from the community! Basic PR process:
  1. Fork the repository
  2. Create a new branch (feature/add-metrics, fix/cli-output, etc.)
  3. Commit cleanly with clear messages
  4. Run pytest before pushing
  5. Submit your PR and link to any related issue
Example commit: 
git checkout -b feature/add-proof-verifier
git add .
git commit -m "feat: added local proof verification"
git push origin feature/add-proof-verifier

​
8. Publishing (for Maintainers)

Tag a release: 
git tag -a v0.1.0 -m "Initial public release"
git push origin v0.1.0
Build and upload to PyPI: 
python -m build
twine upload dist/*

​
9. Development Roadmap

AreaStatusNotes
Core Synthesis (Gaussian Copula)✅Working prototype
Differential Privacy metrics🧩 PlannedAdd diffprivlib epsilon tracking
FastAPI microservice🧩 PlannedREST endpoint for /synthesize
Proof verification tool🧩 PlannedLocal CLI verifier
UI Proof Viewer (React)🧩 PlannedOpen source dashboard for receipts

​
❤️ Community

Join the discussion, report issues, or propose features: