### Python Docstring Example for PrivacyRaven

Source: https://github.com/trailofbits/privacyraven/blob/master/CONTRIBUTING.md

Demonstrates the expected format for docstrings in Python code for functions and classes within the PrivacyRaven project. Docstrings should clearly explain the purpose, parameters, attributes, and return values of code elements.

```python
def example(a):
   """Does something

   Parameters:
      a: data type that represents something

   Returns:
      a data type that represents something else"""

class another(object):
    """Does another thing

    Attributes:
       a: data type that represents something else"""
```

--------------------------------

### Execute Pre-built Model Extraction Attacks

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Illustrates the usage of pre-configured attack functions like copycat_attack. These functions simplify the process of running model extraction by wrapping the core attack logic.

```python
from privacyraven.extraction.attacks import copycat_attack
from privacyraven.utils.data import get_emnist_data
from privacyraven.utils.query import get_target
from privacyraven.models.victim import train_four_layer_mnist_victim
from privacyraven.models.four_layer import FourLayerClassifier

model = train_four_layer_mnist_victim(gpus=1)

def query_mnist(input_data):
    return get_target(model, input_data, (1, 28, 28, 1))

emnist_train, emnist_test = get_emnist_data()

copycat_result = copycat_attack(
    query=query_mnist,
    query_limit=100,
    victim_input_shape=(1, 28, 28, 1),
    victim_output_targets=10,
    substitute_input_shape=(3, 1, 28, 28),
    substitute_model_arch=FourLayerClassifier,
    substitute_input_size=784,
    seed_data_train=emnist_train,
    seed_data_test=emnist_test,
    gpus=1
)
```

--------------------------------

### Query Utilities

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Utilities for interacting with PyTorch models in a black-box manner, including retrieving labels and prediction probabilities.

```APIDOC
## GET /utils/query/get_target

### Description
Queries a victim model to retrieve only the predicted labels for a given input batch.

### Method
GET

### Parameters
#### Query Parameters
- **model** (object) - Required - The PyTorch model to query.
- **input_data** (tensor) - Required - The input data batch.
- **input_size** (tuple) - Required - Expected input shape.

### Response
#### Success Response (200)
- **labels** (tensor) - The predicted class labels for the input data.
```

--------------------------------

### Load Datasets with PrivacyRaven Utilities

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Demonstrates how to load EMNIST and MNIST datasets using built-in utilities. It includes configuring custom transforms and creating PyTorch DataLoaders with specific hyperparameters.

```python
from privacyraven.utils.data import get_emnist_data, get_mnist_data, get_mnist_loaders
from privacyraven.utils.model_creation import set_hparams
from torchvision import transforms

emnist_train, emnist_test = get_emnist_data(transform=None, RGB=True)

custom_transform = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize((0.1307,), (0.3081,))
])

mnist_train, mnist_val, mnist_test = get_mnist_data(hparams={
    "rand_split_val": [55000, 5000],
    "transform": custom_transform
})

hparams = set_hparams(
    transform=custom_transform,
    batch_size=100,
    num_workers=4,
    gpus=1,
    max_epochs=10,
    learning_rate=1e-3,
    input_size=784,
    targets=10
)

train_loader, val_loader, test_loader = get_mnist_loaders(hparams)
```

--------------------------------

### Launch Model Extraction Attack in PrivacyRaven (Python)

Source: https://github.com/trailofbits/privacyraven/blob/master/README.md

Demonstrates how to initiate a model extraction attack using PrivacyRaven. This involves defining a query function for the target model, obtaining seed data, and configuring the ModelExtractionAttack with parameters such as query limits, input shapes, and substitute model architecture. The attack leverages a copycat synthesizer to reconstruct the victim model.

```Python
import privacyraven as pr
from privacyraven.utils.data import get_emnist_data
from privacyraven.extraction.core import ModelExtractionAttack
from privacyraven.utils.query import get_target
from privacyraven.models.victim import train_four_layer_mnist_victim
from privacyraven.models.four_layer import FourLayerClassifier

# Create a query function for a target PyTorch Lightning model
model = train_four_layer_mnist_victim()

def query_mnist(input_data):
    # PrivacyRaven provides built-in query functions
    return get_target(model, input_data, (1, 28, 28, 1))


# Obtain seed (or public) data to be used in extraction
emnist_train, emnist_test = get_emnist_data()

# Run a model extraction attack
attack = ModelExtractionAttack(
    query_mnist, # query function
    200,  # query limit
    (1, 28, 28, 1), # victim input shape
    10, # number of targets
    (3, 1, 28, 28),  # substitute input shape
    "copycat", # synthesizer name
    FourLayerClassifier, # substitute model architecture
    784,  # substitute input size
    emnist_train, # seed train data
    emnist_test, # seed test data
)
```

--------------------------------

### Query Victim Models with PrivacyRaven Utilities

Source: https://context7.com/trailofbits/privacyraven/llms.txt

This snippet shows how to use PrivacyRaven's query utilities to interact with PyTorch models. It covers retrieving predicted labels, obtaining prediction probabilities, and reshaping input data for model compatibility.

```python
import torch
from privacyraven.utils.query import get_target, query_model, reshape_input
from privacyraven.models.victim import train_four_layer_mnist_victim

model = train_four_layer_mnist_victim(gpus=0)
input_data = torch.randn(10, 1, 28, 28)

predicted_labels = get_target(
    model=model,
    input_data=input_data,
    input_size=(1, 28, 28, 1)
)
print(f"Predicted labels: {predicted_labels}")

predictions, targets = query_model(
    model=model,
    input_data=input_data,
    input_size=(1, 28, 28, 1)
)
print(f"Prediction probabilities shape: {predictions.shape}")
print(f"Predicted targets: {targets}")

reshaped_data = reshape_input(
    input_data=input_data,
    input_size=(10, 1, 28, 28),
    single=True,
    warning=True
)
```

--------------------------------

### Train Victim and Inversion Models with PrivacyRaven

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Demonstrates how to train a four-layer MNIST classifier as a victim model and subsequently train an inversion model to assess training data leakage. The process uses PyTorch and PrivacyRaven utilities to handle model conversion and training parameters.

```python
import torch
from privacyraven.models.victim import (
    train_four_layer_mnist_victim,
    train_mnist_victim,
    train_mnist_inversion
)
from privacyraven.utils.model_creation import convert_to_inference

victim_model = train_four_layer_mnist_victim(
    transform=None,
    batch_size=100,
    num_workers=4,
    rand_split_val=None,
    gpus=1,
    max_epochs=8,
    learning_rate=1e-3
)

print(f"Model in eval mode: {not victim_model.training}")

sample_input = torch.randn(1, 1, 28, 28)
with torch.no_grad():
    output = victim_model(sample_input)
    prediction = torch.argmax(output, dim=1)
    print(f"Predicted class: {prediction.item()}")

inversion_model = train_mnist_inversion(
    gpus=1,
    forward_model=victim_model,
    inversion_params={
        "nz": 10,
        "ngf": 128,
        "affine_shift": 50,
        "truncate": 1
    },
    max_epochs=100,
    batch_size=100
)
```

--------------------------------

### Cloud Leak Attack

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Demonstrates how to perform a cloud leak attack to return an array of attacks using different evasion synthesizers.

```APIDOC
## Cloud Leak Attack

### Description
Performs a cloud leak attack to identify potential data leakage by analyzing model behavior with different evasion synthesizers.

### Method
POST (Assumed, as it involves data processing and generation)

### Endpoint
`/api/cloudleak` (Assumed)

### Parameters
#### Query Parameters
- **query** (object) - Required - The query object for the attack.
- **query_limit** (integer) - Required - The limit for the query.
- **victim_input_shape** (tuple) - Required - The input shape of the victim model.
- **victim_output_targets** (integer) - Required - The number of output targets for the victim model.
- **substitute_input_shape** (tuple) - Required - The input shape for the substitute model.
- **substitute_model_arch** (class) - Required - The architecture of the substitute model.
- **substitute_input_size** (integer) - Required - The input size for the substitute model.
- **seed_data_train** (object) - Required - Training data for the substitute model.
- **seed_data_test** (object) - Required - Test data for the substitute model.
- **gpus** (integer) - Optional - Number of GPUs to use.

### Request Example
```json
{
  "query": "...",
  "query_limit": 100,
  "victim_input_shape": [1, 28, 28, 1],
  "victim_output_targets": 10,
  "substitute_input_shape": [3, 1, 28, 28],
  "substitute_model_arch": "FourLayerClassifier",
  "substitute_input_size": 784,
  "seed_data_train": "...",
  "seed_data_test": "...",
  "gpus": 1
}
```

### Response
#### Success Response (200)
- **attacks** (array) - An array of identified attacks.

#### Response Example
```json
{
  "attacks": [
    {
      "type": "evasion_attack_1",
      "details": "..."
    },
    {
      "type": "evasion_attack_2",
      "details": "..."
    }
  ]
}
```
```

--------------------------------

### Register Custom Synthesizer for Model Extraction

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Shows how to define a custom data synthesis strategy using the @register_synth decorator. This allows users to implement custom logic for labeling seed data via victim model queries during an attack.

```python
import torch
from privacyraven.extraction.synthesis import register_synth, synths
from privacyraven.extraction.core import ModelExtractionAttack
from privacyraven.utils.query import get_target, reshape_input
from privacyraven.utils.data import get_emnist_data
from privacyraven.models.victim import train_four_layer_mnist_victim
from privacyraven.models.four_layer import FourLayerClassifier

@register_synth
def custom_synthesizer(data, query, query_limit, art_model, victim_input_shape, substitute_input_shape, victim_output_targets, reshape=True):
    x_data, y_data = data
    y_data = query(x_data)
    if reshape:
        x_data = reshape_input(x_data, substitute_input_shape)
    return x_data, y_data

model = train_four_layer_mnist_victim(gpus=torch.cuda.device_count())
emnist_train, emnist_test = get_emnist_data()

def query_mnist(input_data):
    return get_target(model, input_data, (1, 28, 28, 1))

attack = ModelExtractionAttack(
    query=query_mnist,
    query_limit=100,
    victim_input_shape=(1, 28, 28, 1),
    victim_output_targets=10,
    substitute_input_shape=(3, 1, 28, 28),
    synthesizer="custom_synthesizer",
    substitute_model_arch=FourLayerClassifier,
    substitute_input_size=784,
    seed_data_train=emnist_train,
    seed_data_test=emnist_test,
    gpus=1
)
```

--------------------------------

### PyTorch Lightning Callbacks Integration

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Integrates PrivacyRaven with PyTorch Lightning callbacks for enhanced monitoring and customization during attack training.

```APIDOC
## PyTorch Lightning Callbacks Integration

### Description
Supports PyTorch Lightning callbacks to monitor and customize the training process during privacy attacks. Users can leverage built-in or custom callbacks.

### Method
POST (Assumed, as it involves model training and attack execution)

### Endpoint
`/api/attack/callbacks` (Assumed)

### Parameters
#### Path Parameters
- **callback** (Callback object) - Required - The PyTorch Lightning callback to integrate.

#### Query Parameters
- **query** (function) - Required - The query function for the target model.
- **query_limit** (integer) - Required - The limit for the query.
- **victim_input_shape** (tuple) - Required - The input shape of the victim model.
- **victim_output_targets** (integer) - Required - The number of output targets for the victim model.
- **substitute_input_shape** (tuple) - Required - The input shape for the substitute model.
- **synthesizer** (string) - Required - The synthesizer to use for model extraction.
- **substitute_model_arch** (class) - Required - The architecture of the substitute model.
- **substitute_input_size** (integer) - Required - The input size for the substitute model.
- **seed_data_train** (object) - Required - Training data for the substitute model.
- **seed_data_test** (object) - Required - Test data for the substitute model.
- **gpus** (integer) - Optional - Number of GPUs to use.
- **trainer_args** (list of tuples) - Optional - Arguments to pass to the PyTorch Lightning trainer.

### Request Example
```json
{
  "query": "query_mnist_function",
  "query_limit": 100,
  "victim_input_shape": [1, 28, 28, 1],
  "victim_output_targets": 10,
  "substitute_input_shape": [3, 1, 28, 28],
  "synthesizer": "copycat",
  "substitute_model_arch": "FourLayerClassifier",
  "substitute_input_size": 784,
  "seed_data_train": "...",
  "seed_data_test": "...",
  "gpus": 1,
  "callback": "AttackProgressCallback()", 
  "trainer_args": [["deterministic", true], ["profiler", "simple"]]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the attack execution.
- **message** (string) - A message detailing the outcome of the attack.

#### Response Example
```json
{
  "status": "success",
  "message": "Model extraction attack completed successfully with custom callbacks."
}
```
```

--------------------------------

### Perform Model Extraction Attack using PrivacyRaven

Source: https://context7.com/trailofbits/privacyraven/llms.txt

This snippet demonstrates how to initialize and execute a black-box label-only model extraction attack. It involves training a victim model, defining a query function, and configuring the ModelExtractionAttack class to train a substitute model.

```python
import privacyraven as pr
from privacyraven.utils.data import get_emnist_data
from privacyraven.extraction.core import ModelExtractionAttack
from privacyraven.utils.query import get_target
from privacyraven.models.victim import train_four_layer_mnist_victim
from privacyraven.models.four_layer import FourLayerClassifier

victim_model = train_four_layer_mnist_victim(gpus=1)

def query_victim(input_data):
    return get_target(victim_model, input_data, (1, 28, 28, 1))

emnist_train, emnist_test = get_emnist_data()

attack = ModelExtractionAttack(
    query=query_victim,
    query_limit=200,
    victim_input_shape=(1, 28, 28, 1),
    victim_output_targets=10,
    substitute_input_shape=(3, 1, 28, 28),
    synthesizer="copycat",
    substitute_model_arch=FourLayerClassifier,
    substitute_input_size=784,
    seed_data_train=emnist_train,
    seed_data_test=emnist_test,
    gpus=1,
    max_epochs=10,
    batch_size=100,
    learning_rate=1e-3
)

print(f"Label Agreement: {attack.label_agreement}")
substitute_model = attack.substitute_model
```

--------------------------------

### Measure Model Extraction Fidelity with Label Agreement

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Shows how to execute a model extraction attack and calculate the label agreement metric. This metric quantifies the success of an extraction by comparing the predictions of the substitute model against the victim model on test data.

```python
import torch
from privacyraven.extraction.metrics import label_agreement
from privacyraven.utils.data import get_emnist_data
from privacyraven.utils.query import get_target
from privacyraven.models.victim import train_four_layer_mnist_victim
from privacyraven.extraction.core import ModelExtractionAttack
from privacyraven.models.four_layer import FourLayerClassifier

victim_model = train_four_layer_mnist_victim(gpus=1)
emnist_train, emnist_test = get_emnist_data()

def query_victim(input_data):
    return get_target(victim_model, input_data, (1, 28, 28, 1))

attack = ModelExtractionAttack(
    query=query_victim,
    query_limit=200,
    victim_input_shape=(1, 28, 28, 1),
    victim_output_targets=10,
    substitute_input_shape=(3, 1, 28, 28),
    synthesizer="copycat",
    substitute_model_arch=FourLayerClassifier,
    substitute_input_size=784,
    seed_data_train=emnist_train,
    seed_data_test=emnist_test,
    gpus=1,
)

agreement = label_agreement(
    test_data=emnist_test,
    substitute_model=attack.substitute_model,
    query_victim=query_victim,
    victim_input_shape=(1, 28, 28, 1),
    substitute_input_shape=(3, 1, 28, 28)
)

print(f"Attack fidelity: {agreement}% agreement")
```

--------------------------------

### Perform Model Inversion Attack with PrivacyRaven

Source: https://context7.com/trailofbits/privacyraven/llms.txt

This snippet demonstrates how to train a substitute model and an inversion network to reconstruct input data from model predictions. It uses the joint_train_inversion_model function and evaluates performance using test_inversion_model.

```python
from privacyraven.inversion.core import (joint_train_inversion_model, test_inversion_model, save_inversion_results)
from privacyraven.utils.data import get_emnist_data
import random

emnist_train, emnist_test = get_emnist_data()
forward_model, inversion_model = joint_train_inversion_model(
    dataset_train=emnist_train,
    dataset_test=emnist_test,
    data_dimensions=(1, 28, 28, 1),
    max_epochs=300,
    gpus=1,
    t=1,
    c=50
)

num_test = 10
test_indices = random.sample(range(len(emnist_test)), num_test)
for idx in test_indices:
    image, label = emnist_test[idx]
    reconstruction_loss = test_inversion_model(
        forward_model=forward_model,
        inversion_model=inversion_model,
        image=image,
        filename=f"recovered_{idx}",
        save=True,
        label=str(label),
        debug=True
    )
    print(f"Image {idx} (label={label}): MSE Loss = {reconstruction_loss:.4f}")
```

--------------------------------

### Integrate PyTorch Lightning Callbacks for Model Extraction

Source: https://context7.com/trailofbits/privacyraven/llms.txt

This snippet shows how to monitor and customize the model extraction attack process by passing custom or built-in PyTorch Lightning callbacks to the ModelExtractionAttack class.

```python
import torch
from pytorch_lightning.callbacks import Callback
from pl_bolts.callbacks import PrintTableMetricsCallback
from privacyraven.extraction.core import ModelExtractionAttack
from privacyraven.utils.data import get_emnist_data
from privacyraven.utils.query import get_target
from privacyraven.models.victim import train_four_layer_mnist_victim
from privacyraven.models.four_layer import FourLayerClassifier

class AttackProgressCallback(Callback):
    def on_epoch_start(self, trainer, pl_module):
        print(f"Starting epoch {trainer.current_epoch}")
    def on_epoch_end(self, trainer, pl_module):
        print(f"Completed epoch {trainer.current_epoch}")

model = train_four_layer_mnist_victim(gpus=torch.cuda.device_count())
emnist_train, emnist_test = get_emnist_data()

def query_mnist(input_data):
    return get_target(model, input_data, (1, 28, 28, 1))

attack_with_callback = ModelExtractionAttack(
    query=query_mnist,
    query_limit=100,
    victim_input_shape=(1, 28, 28, 1),
    victim_output_targets=10,
    substitute_input_shape=(3, 1, 28, 28),
    synthesizer="copycat",
    substitute_model_arch=FourLayerClassifier,
    substitute_input_size=784,
    seed_data_train=emnist_train,
    seed_data_test=emnist_test,
    gpus=1,
    callback=AttackProgressCallback(),
    trainer_args=[("deterministic", True), ("profiler", "simple")]
)
```

--------------------------------

### Model Inversion Attack

Source: https://context7.com/trailofbits/privacyraven/llms.txt

Implements a black-box model inversion attack to reconstruct training data from a target model's predictions.

```APIDOC
## Model Inversion Attack

### Description
Reconstructs training data from a target model's predictions using a black-box approach. It involves extracting a substitute model and then training an inversion network.

### Method
POST (Assumed, as it involves training and testing models)

### Endpoint
`/api/inversion` (Assumed)

### Parameters
#### Query Parameters
- **dataset_train** (object) - Required - Training dataset for the inversion model.
- **dataset_test** (object) - Required - Test dataset for the inversion model.
- **data_dimensions** (tuple) - Required - Dimensions of the input data.
- **max_epochs** (integer) - Optional - Maximum training epochs for the inversion model.
- **gpus** (integer) - Optional - Number of GPUs to use.
- **t** (integer) - Optional - Truncation parameter for prediction vector.
- **c** (integer) - Optional - Affine shift parameter.
- **num_test** (integer) - Optional - Number of test samples to use for reconstruction.
- **save** (boolean) - Optional - Whether to save reconstruction results.
- **debug** (boolean) - Optional - Whether to enable debug mode for printing prediction vectors.

### Request Example
```json
{
  "dataset_train": "...",
  "dataset_test": "...",
  "data_dimensions": [1, 28, 28, 1],
  "max_epochs": 300,
  "gpus": 1,
  "t": 1,
  "c": 50,
  "num_test": 10,
  "save": true,
  "debug": true
}
```

### Response
#### Success Response (200)
- **reconstruction_loss** (float) - The Mean Squared Error loss of the image reconstruction.

#### Response Example
```json
{
  "reconstruction_loss": 0.1234
}
```
```

--------------------------------

### ModelExtractionAttack Class

Source: https://context7.com/trailofbits/privacyraven/llms.txt

The ModelExtractionAttack class is the primary interface for performing black-box label-only model extraction attacks to synthesize training data and train a substitute model.

```APIDOC
## POST /extraction/model-extraction-attack

### Description
Launches a model extraction attack against a target victim model to train a substitute model that replicates the victim's behavior.

### Method
POST

### Parameters
#### Request Body
- **query** (function) - Required - Function to query the victim model.
- **query_limit** (int) - Required - Maximum number of queries allowed.
- **victim_input_shape** (tuple) - Required - Input shape expected by the victim model.
- **victim_output_targets** (int) - Required - Number of output classes.
- **synthesizer** (string) - Required - Synthesis method for training data (e.g., "copycat").
- **substitute_model_arch** (class) - Required - Architecture for the substitute model.
- **seed_data_train** (dataset) - Required - Seed training data for synthesis.

### Request Example
{
  "query": "query_victim_function",
  "query_limit": 200,
  "synthesizer": "copycat",
  "max_epochs": 10
}

### Response
#### Success Response (200)
- **label_agreement** (float) - The fidelity score between the victim and substitute model.
- **substitute_model** (object) - The trained substitute model instance.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.