Metadata-Version: 2.4
Name: dpst
Version: 0.1.0
Summary: Differentially private document generation leveraging semantic triples.
Author-email: Stephen Meisenbacher <sjmeis@gtgd.com>
Maintainer-email: Stephen Meisenbacher <sjmeis@gtgd.com>
License: MIT License
        
        Copyright (c) 2025-2026 Stephen Meisenbacher
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: weaviate-client>=4.0.0
Requires-Dist: transformers
Requires-Dist: sentence-transformers
Requires-Dist: openie
Requires-Dist: tqdm
Requires-Dist: numpy
Requires-Dist: spacy
Requires-Dist: torch
Requires-Dist: datasketch
Requires-Dist: nltk
Provides-Extra: setup
Requires-Dist: datasets; extra == "setup"
Requires-Dist: scikit-learn; extra == "setup"
Dynamic: license-file

<div align="center">

  # DP-ST

  [![PyPI version](https://img.shields.io/pypi/v/dpst.svg)](https://pypi.org/project/dpst/)
  [![GitHub stars](https://img.shields.io/github/stars/sjmeis/DPST.svg?style=social)](https://github.com/sjmeis/DPST/stargazers)
  [![License](https://img.shields.io/github/license/sjmeis/DPST.svg)](https://github.com/sjmeis/DPST/blob/main/LICENSE)

</div>

Code repository for the EMNLP 2025 paper: *Leveraging Semantic Triples for Private Document Generation with Local Differential Privacy Guarantees*

## Getting Started
### Installation
You can now install `DP-ST` directly as a Python package.

```bash
# Install the core runtime engine
pip install dpst

# Install the optional data-preparation extensions required for the initial setup
pip install "dpst[setup]"
```

**Note on Heavy Runtimes**: We highly recommend installing the correct flavor of PyTorch matching your hardware's CUDA capability before installing this package.

### Automated Database & Cluster Setup
In order to run `DP-ST`, you must first run the *preparation* stage as described in the paper. This includes booting up your local vector database, extracting triples from a public text corpus, clustering them, and storing them locally.

Ensure your local Weaviate instance is running, then execute the following automated command in your terminal:

```bash
dpst setup
```

**Note:** This can take a very long time! We recommend you set it and forget it. Alternatively, you can tweak the `max_rows` parameter of `initialize_database` to use less texts for the database preparation.

The above replaces the legacy workflow of manually executing `Triple2DB.ipynb` and `triple_cluster.ipynb`. The command will automatically stream the FineWeb public corpus dataset, extract/embed triples into Weaviate, run the MiniBatchKMeans allocations (50k, 100k, and 200k), and write the resulting cluster assets straight into the package data directory. If you prefer a more tailored approach, we still recommend using the notebooks.

## Usage

Running `DP-ST` is simple once the automated setup has completed:

```python
from dpst import DPST

# Initialize the engine (specify mode: "50k", "100k", or "200k")
X = DPST(mode="50k", model_checkpoint=MODEL_NAME, hf_token=TOKEN)

# Privatize your text corpus
private_texts = X.privatize([TEXTS], epsilon=DOC_PRIVACY_BUDGET)
```

`MODEL_NAME` refers to the model used for text reconstruction (i.e., the `Llama-3.2` models we use in the work), and `hf_token` is only necessary for gated models on Hugging Face.

## Running other DP Methods
In this repository (under the `comparison` directory), you will find a number of scripts (`*_perturb.py`) to reproduce the privatized texts as performed in our work.

The code for `DP-BART` and `DP-Prompt` can be found in `LLMDP.py`. `DP-MLM` can be found [here](https://github.com/sjmeis/DPMLM/) and the code for `TEM` can be found [here](https://github.com/sjmeis/MLDP/).

We also include the evaluation code for cosine similarity (`CS.py`) and G-Eval (`Geval.ipynb`), located in `evaluation`.

NOTE: in all provided notebooks, please make sure to include the correct libraries and link the paths accordingly. This is necessary for the code to run correctly!

## Citation
If you use this code in your research, please consider citing the published work:

```
@inproceedings{meisenbacher-etal-2025-leveraging,
    title = "Leveraging Semantic Triples for Private Document Generation with Local Differential Privacy Guarantees",
    author = "Meisenbacher, Stephen  and
      Chevli, Maulik  and
      Matthes, Florian",
    editor = "Christodoulopoulos, Christos  and
      Chakraborty, Tanmoy  and
      Rose, Carolyn  and
      Peng, Violet",
    booktitle = "Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing",
    month = nov,
    year = "2025",
    address = "Suzhou, China",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2025.emnlp-main.455/",
    doi = "10.18653/v1/2025.emnlp-main.455",
    pages = "8976--8992",
    ISBN = "979-8-89176-332-6"
}
```
