Metadata-Version: 2.4
Name: pyobfi
Version: 0.1.0
Summary: CLI for running OBFI and WS12 oblivious Bloom filter insertion experiments
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# pyobfi

CLI for running OBFI and WS12 oblivious Bloom filter insertion experiments.

`pyobfi` wraps the experiment runners for two oblivious Bloom filter insertion
protocols so you can launch a run from the command line instead of manually
editing source files or setting environment variables:

- **OBFI** — batch insertion via Oblivious Bucket Distribution, sort scope fixed
  at batch size `m`, independent of filter capacity
- **WS12** — Williams & Sion's single-round access privacy protocol, sort scope
  grows with filter capacity `M`

Full protocol implementations, experiment data, and the empirical crossover
analysis live in the parent repository:
[obfi-implementation-and-empirical-analysis](https://github.com/rahil1303/obfi-implementation-and-empirical-analysis)

## Install

```bash
pip install pyobfi
```

`pyobfi` itself has no dependencies beyond the standard library. Running an
actual experiment additionally requires the protocol implementations from the
main repo, plus their runtime dependencies:

```bash
git clone https://github.com/rahil1303/obfi-implementation-and-empirical-analysis.git
cd obfi-implementation-and-empirical-analysis
pip install -r variant1-obfi/requirements.txt
pip install -r variant2-ws12/requirements.txt
```

## Usage

Run from the repo root, or point `--repo-dir` at it:

```bash
# Run a single OBFI experiment
pyobfi run-obfi --s 2500 --n 50000

# Run a predefined OBFI phase (1, 2, or 3)
pyobfi run-obfi --phase 1
pyobfi run-obfi --phase 2 --log obfi_phase2_run1.txt

# Run a single WS12 experiment
pyobfi run-ws12 --s 2500 --n 50000

# Run a predefined WS12 phase, with a specific oblivious sort
pyobfi run-ws12 --phase 3
pyobfi run-ws12 --phase 1 --osort shellsort --log ws12_phase1_rss.txt
```

Output streams to the terminal and is written to a log file at the same time.
Log files are auto-named by default and saved under `results/` in the repo
root, unless overridden.

## Options

| Flag           | Description                                                        |
| -------------- | ------------------------------------------------------------------- |
| `--s`          | Batch size                                                          |
| `--n`          | Filter element capacity                                             |
| `--phase`      | Run a predefined phase (1, 2, or 3)                                 |
| `--osort`      | Oblivious sort type: `bucket` (default) or `shellsort` — WS12 only  |
| `--log`        | Custom log filename                                                 |
| `--repo-dir`   | Path to repo root (default: current directory)                      |
| `--output-dir` | Where to write results and logs (default: `<repo-root>/results`)    |

## License

MIT
