Metadata-Version: 2.4
Name: privsyn-core
Version: 0.1.0
Summary: Standalone PrivSyn core for differentially private discrete tabular synthesis.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: networkx>=3.2
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"

# 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

```bash
pip install privsyn-core
```

## Usage

```python
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.
