From 10f6c79176524abd6204a4cc3c892ae3db8130d1 Mon Sep 17 00:00:00 2001
From: Biel Stela <biel.stela@gmail.com>
Date: Mon, 26 Nov 2018 21:24:42 +0100
Subject: [PATCH] updated readme and  package format

---
 README.md                                     | 67 ++++++++++++++++---
 mblearn/__init__.py                           |  3 +
 attack_model.py => mblearn/attack_model.py    |  0
 .../data_synthesis.py                         |  0
 shadow_model.py => mblearn/shadow_model.py    |  0
 setup.py                                      | 42 ++++++++++++
 6 files changed, 104 insertions(+), 8 deletions(-)
 create mode 100644 mblearn/__init__.py
 rename attack_model.py => mblearn/attack_model.py (100%)
 rename data_synthesis.py => mblearn/data_synthesis.py (100%)
 rename shadow_model.py => mblearn/shadow_model.py (100%)
 create mode 100644 setup.py

diff --git a/README.md b/README.md
index 01fbaa2..029a478 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,62 @@
 # Membership Inference Attacks
-Python package to create adversarial agents for membership inference attacks againts machine learning models.
+Python package to create adversarial agents for membership inference attacks against machine learning models.
 
-Implementation of the work done by Shokri _et al_: [paper](https://www.cs.cornell.edu/~shmat/shmat_oak17.pdf)
+Implementation of the work done by Shokri _et al_ ([paper](https://www.cs.cornell.edu/~shmat/shmat_oak17.pdf))
 
-## TO DO
-* Basic package outline
-* Shadow Model and Attack Model
-* Shadow dataset generator using the data synthesis algorithm proposeb by Shokri _et al_
-* Dummy example with Iris dataset
-* Expand functionality and generalization of the package
+# Examples
+Find some examples in `notebooks/`
+
+The main classes and functions are:
+
+### Data Synthetiser
+
+To synthesize data only using a black-box like model `target_model` and predictions using the algorithm proposed by Shokri _et al_
+
+```python 
+from mblearn import synthetize
+
+x = synthesize(target_model, fixed_class, k_max)
+```
+
+### Shadow models
+Train $n$ shadow models on synthetic data with a given learner. The learner must be a scikit-learn estimator with the `predict_proba` method.
+
+
+```python
+from mblearn import ShadowModels
+
+shadows = ShadowModels(n_models, data, target_classes, learner)
+
+shadow_data = shadows.results
+```
+
+### Attacker models
+
+Using the data generated with the shadow models, trains a attack models
+on each label of the shadow dataset.
+
+```python
+from mblearn import AttackerModels
+
+attacker = AttackModels(target_classes, attack_learner)
+
+# train the attacker with the shadow data
+attacker.fit(shadow_data)
+
+# query the target model and get the predicted class prob vector
+X = target_model.predict_proba(test_data)
+
+# especulate about the class this test_data belongs to
+y = 0
+
+# get the prediction:
+# True if `test_data` is classified as a member of
+# the private model training set for the given class
+# False otherwise
+attacker.predict(X, y)
+```
+Will 
+
+## Warning
+
+The maturity of the package is far from alpha. This is just a prove of concept and the whole interface and inner wheels may change constantly in the next few months.
\ No newline at end of file
diff --git a/mblearn/__init__.py b/mblearn/__init__.py
new file mode 100644
index 0000000..e7e866c
--- /dev/null
+++ b/mblearn/__init__.py
@@ -0,0 +1,3 @@
+from .attack_model import AttackModels
+from .data_synthesis import synthesize
+from .shadow_model import ShadowModels
\ No newline at end of file
diff --git a/attack_model.py b/mblearn/attack_model.py
similarity index 100%
rename from attack_model.py
rename to mblearn/attack_model.py
diff --git a/data_synthesis.py b/mblearn/data_synthesis.py
similarity index 100%
rename from data_synthesis.py
rename to mblearn/data_synthesis.py
diff --git a/shadow_model.py b/mblearn/shadow_model.py
similarity index 100%
rename from shadow_model.py
rename to mblearn/shadow_model.py
diff --git a/setup.py b/setup.py
new file mode 100644
index 0000000..062bcd2
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,42 @@
+from setuptools import setup
+
+def readme():
+    with open('README.md') as readme_file:
+        return readme_file.read()
+
+configuration = {
+    'name' : 'member-learn',
+    'version': '0.0.1',
+    'description' : 'Membership inference attacks with sklearn',
+    'long_description' : readme(),
+    'classifiers' : [
+        'Development Status :: 1 - Planning',
+        'Intended Audience :: Science/Research',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved',
+        'Programming Language :: Python',
+        'Topic :: Software Development',
+        'Topic :: Scientific/Engineering',
+        'Operating System :: Microsoft :: Windows',
+        'Operating System :: POSIX',
+        'Operating System :: Unix',
+        'Operating System :: MacOS',
+        'Programming Language :: Python :: 3.7',
+    ],
+    'keywords' : 'membership inference adversarial attack privacy machine-learning',
+    'url' : 'https://github.com/BielStela/membership_inference',
+    'maintainer' : 'Biel Stela',
+    'maintainer_email' : 'biel.stela@gmail.com',
+    'license' : 'BSD',
+    'packages' : ['mblearn'],
+    'install_requires': ['numpy >= 1.13',
+                         'scikit-learn >= 0.16',
+                         'scipy >= 0.19',
+                         'pandas',
+                         'tqdm'],
+    'ext_modules' : [],
+    'cmdclass' : {},
+    'data_files' : ()
+    }
+
+setup(**configuration)
\ No newline at end of file