Metadata-Version: 2.1
Name: amuletml
Version: 0.1.0
Summary: Amulet is a Python machine learning (ML) package to evaluate the susceptibility of different risks to security, privacy, and fairness.
License: Apache-2.0
Author: Asim Waheed
Author-email: asim.waheed29@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: captum (==0.7.0)
Requires-Dist: cleverhans (==4.0.0)
Requires-Dist: matplotlib (==3.8.3)
Requires-Dist: numpy (==1.26.4)
Requires-Dist: opacus (==1.4.1)
Requires-Dist: pandas (==2.2.1)
Requires-Dist: scikit-learn (==1.4.1.post1)
Requires-Dist: scipy (==1.12.0)
Requires-Dist: torch (>=2.2.0,<3.0.0)
Requires-Dist: torchvision (>=0.18.0,<0.19.0)
Requires-Dist: tqdm (==4.66.2)
Requires-Dist: ucimlrepo (==0.0.3)
Requires-Dist: wget (==3.2.0)
Description-Content-Type: text/markdown

# Amulet
Amulet is a Python machine learning (ML) package to evaluate the susceptibility of different risks to security, privacy, and fairness. Amulet is applicable to evaluate how algorithms designed to reduce one risk may impact another unrelated risk and compare different attacks/defenses for a given risk.

Amulet builds upon prior work titled [“SoK: Unintended Interactions among Machine Learning Defenses and Risks”](https://arxiv.org/abs/2312.04542) which appears in IEEE Symposium on Security and Privacy 2024. The SoK covers only two interactions and identifies the design of a software library to evaluate unintended interactions as future work. Amulet addresses this gap by including eight different risks each covering their own attacks, defenses and metrics.

Amulet is:
- Comprehensive: Covers the most representative attacks/defenses/metrics for different risks.
- Extensible: Easy to include additional risks, attacks, defenses, or metrics.
- Consistent: Allows using different attacks/defenses/metrics with a consistent, easy-to-use API.
- Applicable: Allows evaluating unintended interactions among defenses and attacks.


Built to work with PyTorch, you can incorporate Amulet into your current ML pipeline to test how your model interacts with these state-of-the-art defenses and risks. Alternatively, you can use the example pipelines to bootstrap your pipeline.

## Requirements

**Note:** The package requires the CUDA version to be 11.8 or above for PyTorch 2.2

### Install poetry

`python3 -m venv .poetry_venv`

`. .poetry_venv/bin/activate` or `. .venv/bin/activate.fish`

`python -m pip install --upgrade pip`

`pip install poetry`

`deactivate`

Consider setting `.poetry_venv/bin/poetry config virtualenvs.create false` to prevent poetry from creating its own venv.

### Main venv

To create the virtual environemnt:
`python3 -m venv .venv`

To activate it:
`source .venv/bin/activate` or if using fish `. .venv/bin/activate.fish`

Then, to install the dependencies:
`.poetry_venv/bin/poetry install`

**DISCLAIMER:** Installing `pytorch` with `poetry` is [still weird](https://github.com/python-poetry/poetry/blob/main/docs/repositories.md#explicit-package-sources) but should work.

### Using poetry

(Inside your `.venv`);
when you add or modify any dependencies in `pyproject.toml`, run `.poetry_venv/bin/poetry lock --no-update` to rebuild the dependency graph.
Then run `.poetry_venv/bin/poetry install` to install the dependencies.

### pre-commit

There're some pre-commit hooks configured for this project.
Also, `poetry` installs `pre-commit` as a dev dependency.

Run `pre-commit install` for consistent development.

## Getting Started
### Test installation
To test your installation, please run [amulet/examples/get_started.py](https://github.com/ssg-research/amulet/blob/main/examples/get_started.py). This script also serves as a starting point to learn how to use the library.

### Learn More
For more information on the basics about the library, please see the [Getting Started guide](https://github.com/ssg-research/amulet/blob/main/docs/GETTING_STARTED.md).

To see the attacks, defenses, and risks (modules) that Amulet implements, please refer to the **Module Heirarchy** (link TBD) in the Tutorial (link TBD).

For each module, please see [amulet/examples](https://github.com/ssg-research/amulet/tree/main/examples) for implementations of pipelines that include recommendations on how to run each module.

