privsyn-core 0.1.0

Standalone PrivSyn core for differentially private discrete tabular synthesis.

privsyn-core

privsyn-core packages the discrete PrivSyn algorithm as a standalone Python library. It is intentionally narrower than the full privsyn-tabular project: it expects an already encoded dataframe whose values are integer ids within the provided per-column domain sizes.

Scope

• Includes the PrivSyn marginal selection and GUM synthesis core.
• Excludes the web app, FastAPI service, frontend, and framework-specific adapter/registry layers.
• Excludes raw tabular preprocessing from mixed numeric/categorical data.

Install

pip install privsyn-core

Usage

import pandas as pd

from privsyn import PrivSynModel

df = pd.DataFrame(
    {
        "age_bin": [0, 1, 0, 2, 1, 2],
        "sex": [0, 1, 1, 0, 1, 0],
        "race": [0, 1, 2, 0, 1, 2],
    }
)
domain = {"age_bin": 3, "sex": 2, "race": 3}

model = PrivSynModel(
    epsilon=1.0,
    delta=1e-6,
    random_state=0,
    extra_params={
        "update_iterations": 5,
        "consist_iterations": 25,
    },
)

model.fit(df, domain)
synthetic = model.sample(100)
print(synthetic.head())

Notes

• Use artifact_root=... if you want persisted marginal artifacts in a specific directory.
• By default the package uses a temp directory under the system temp root.

Release Automation

This repository includes a GitHub Actions workflow at .github/workflows/privsyn-core-package.yml that automates validation and publishing for privsyn-core.

• Pull requests and pushes touching packages/privsyn-core/ run package tests, build both sdist and wheel, run twine check, and smoke-test the built wheel in a fresh virtual environment.
• Manual publish: open the PrivSyn Core Package workflow and choose testpypi or pypi.
• Tag publish: pushing a tag named like privsyn-core-v0.1.0 triggers a PyPI publish.

One-time setup

Configure trusted publishing on PyPI and TestPyPI for this GitHub repository. Use these environment names in GitHub:

• testpypi
• pypi

Then add matching trusted publisher entries on the package index side for this repository, the privsyn-core-package.yml workflow, and the corresponding testpypi / pypi environment.

If you prefer token-based publishing instead, you can replace the publish steps with password: ${{ secrets.PYPI_API_TOKEN }} style configuration, but trusted publishing is the cleaner default.