Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/pytest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,10 +60,10 @@ jobs:
- name: Verify pylock.toml is up to date with pyproject.toml
if: steps.check_pyproject.outputs.changed == 'true'
run: |
uv export --format pylock.toml --all-extras --default-index https://pypi.org/simple -o pylock_generated.toml --python 3.12
grep -v '^#' pylock.toml > pylock_current_clean.toml
grep -v '^#' pylock_generated.toml > pylock_new_clean.toml
diff -u pylock_current_clean.toml pylock_new_clean.toml || {
uv export -q --format pylock.toml --all-extras --default-index https://pypi.org/simple -o pylock.toml --python 3.12
go run github.com/google/addlicense@v1.2.0 -c "Google LLC" -y "2026" -l apache pylock.toml
git diff --stat pylock.toml
git diff --exit-code pylock.toml || {
echo -e "\n---> pylock.toml is out of sync with pyproject.toml." >&2
echo -e "---> Run 'uv export --format pylock.toml --all-extras --default-index https://pypi.org/simple -o pylock.toml --python 3.12' locally and commit the changes." >&2
exit 1
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/update_lockfile.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ jobs:
- name: Regenerate pylock.toml
run: |
uv export --format pylock.toml --all-extras --default-index https://pypi.org/simple -o pylock.toml --python 3.12
go run github.com/google/addlicense@v1.1.1 -c "Google LLC" -y "2026" -l apache pylock.toml
go run github.com/google/addlicense@v1.2.0 -c "Google LLC" -y "2026" -l apache pylock.toml

- name: Create Pull Request
uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7
Expand Down
101 changes: 50 additions & 51 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,12 @@ We welcome contributions in many forms:

### Bug Fixes, Issues, and Documentation

- **Bug reports**: Open an [issue](https://github.com/google/dpsynth/issues)
describing what went wrong and how to reproduce it.
- **Bug fixes**: Small, focused PRs that fix a specific issue are always
appreciated.
- **Documentation**: Improving docstrings, adding examples, or clarifying
existing docs.
- **Bug reports**: Open an [issue](https://github.com/google/dpsynth/issues)
describing what went wrong and how to reproduce it.
- **Bug fixes**: Small, focused PRs that fix a specific issue are always
appreciated.
- **Documentation**: Improving docstrings, adding examples, or clarifying
existing docs.

### Privacy Hardening

Expand All @@ -36,16 +36,16 @@ welcome.

We accept new mechanisms at every level of the stack:

- **Tabular data mechanisms**: New algorithms for discrete synthetic data
generation (e.g., alternatives to AIM, SWIFT, MST).
- **Text generation mechanisms**: New approaches for differentially private text
synthesis or fine-tuning.
- **Primitives**: New building blocks such as partition selection algorithms or
numerical discretization strategies.
- **Higher-level components**: Mechanisms that build on top of synthetic data
generation — for example, adaptive insights from unstructured text, or
modality-specific pipelines that decompose complex problems into
subproblems the library already handles well.
- **Tabular data mechanisms**: New algorithms for discrete synthetic data
generation (e.g., alternatives to AIM, SWIFT, MST).
- **Text generation mechanisms**: New approaches for differentially private
text synthesis or fine-tuning.
- **Primitives**: New building blocks such as partition selection algorithms
or numerical discretization strategies.
- **Higher-level components**: Mechanisms that build on top of synthetic data
generation — for example, adaptive insights from unstructured text, or
modality-specific pipelines that decompose complex problems into subproblems
the library already handles well.

### API Design Proposals

Expand All @@ -59,13 +59,13 @@ backwards-incompatible wrappers later.
DP Synth is co-developed with several companion libraries, and improvements to
any of them directly benefit DP Synth:

- [**MBI**](https://github.com/ryan112358/mbi): Graphical model estimation
and inference engine used by the tabular mechanisms.
- [**dp_accounting**](https://github.com/google/differential-privacy/tree/main/python/dp_accounting):
Privacy accounting and budget composition.
- [**jax_privacy**](https://github.com/google-deepmind/jax_privacy):
Differentially private training primitives used by the text generation
module.
- [**MBI**](https://github.com/ryan112358/mbi): Graphical model estimation and
inference engine used by the tabular mechanisms.
- [**dp_accounting**](https://github.com/google/differential-privacy/tree/main/python/dp_accounting):
Privacy accounting and budget composition.
- [**jax_privacy**](https://github.com/google-deepmind/jax_privacy):
Differentially private training primitives used by the text generation
module.

Contributions to these libraries — bug fixes, performance improvements, new
features — can be surfaced into DP Synth once they land upstream.
Expand All @@ -81,52 +81,51 @@ library.
Once a contribution in `contrib/` has landed, matured, and proven useful, we'll
work with you to migrate it into the appropriate core module.

If your contribution is a bug fix, documentation improvement, or a change to
an existing module, submit it directly to the relevant file — `contrib/` is
only for new standalone additions.
If your contribution is a bug fix, documentation improvement, or a change to an
existing module, submit it directly to the relevant file — `contrib/` is only
for new standalone additions.

## Acceptance Criteria

When reviewing contributions, we primarily look for two things:

### 1. Simplicity

Simpler contributions with smaller diffs are more likely to be accepted. For
new mechanisms in particular:
Simpler contributions with smaller diffs are more likely to be accepted. For new
mechanisms in particular:

- **Aim for a single file** with at most ~500 lines of code.
- You don't need to use the same internal helper functions that existing
mechanisms use. If your approach is novel, a self-contained implementation
is perfectly fine.
- However, your mechanism **should conform to the same API contract** as
existing mechanisms (e.g., implementing `DPMechanism`, accepting the same
calibration/configuration interface). The exception is mechanisms designed
for a new data modality (e.g., relational data), where a new API surface
may be necessary.
- **Aim for a single file** with at most ~500 lines of code.
- You don't need to use the same internal helper functions that existing
mechanisms use. If your approach is novel, a self-contained implementation
is perfectly fine.
- However, your mechanism **should conform to the same API contract** as
existing mechanisms (e.g., implementing `DPMechanism`, accepting the same
calibration/configuration interface). The exception is mechanisms designed
for a new data modality (e.g., relational data), where a new API surface may
be necessary.

### 2. No New Heavy Dependencies

DP Synth deliberately keeps its dependency footprint small:

- **Do not introduce PyTorch, TensorFlow, or other heavyweight
dependencies.**
- If you need numerical computing, use **JAX**. If you need neural network
layers, use **Flax**.
- If your contribution requires a new dependency, discuss it in the issue
tracker first.
- **Do not introduce PyTorch, TensorFlow, or other heavyweight dependencies.**
- If you need numerical computing, use **JAX**. If you need neural network
layers, use **Flax**.
- If your contribution requires a new dependency, discuss it in the issue
tracker first.

## Development Setup

We use [uv](https://docs.astral.sh/uv/) for managing your development
environment. It provides support for managing `pylock.toml` lock files and
is significantly faster than `pip`.
environment. It provides support for managing `pylock.toml` lock files and is
significantly faster than `pip`.

> [!NOTE]
> The `pylock.toml` file is generated using `uv`, but it follows standard
> specifications as per PEP 751 and should work with modern package managers
> that support it.
> [!NOTE] The `pylock.toml` file is generated using `uv`, but it follows
> standard specifications as per PEP 751 and should work with modern package
> managers that support it.

1. **Install uv:** Follow the [official instructions](https://docs.astral.sh/uv/getting-started/installation/).
1. **Install uv:** Follow the
[official instructions](https://docs.astral.sh/uv/getting-started/installation/).
2. **Create an environment and install dependencies:**

```bash
Expand All @@ -144,7 +143,7 @@ is significantly faster than `pip`.

```bash
uv export --format pylock.toml --all-extras --default-index https://pypi.org/simple -o pylock.toml --python 3.12
go run github.com/google/addlicense@v1.1.1 -c "Google LLC" -y "2026" -l apache pylock.toml
go run github.com/google/addlicense@v1.2.0 -c "Google LLC" -y "2026" -l apache pylock.toml
```

Commit the updated `pylock.toml` to ensure CI and contributors remain in
Expand Down
Loading
Loading