# Privacy Tuner

**Privacy Tuner** 是一个通用的隐私保护数据发布工具。它通过智能参数搜索，在用户指定的隐私预算和效用目标约束下，自动寻找最优的数据扰动参数（如噪声尺度、泛化粒度、采样比例等），从而在保护隐私的同时最大化数据的实用性。最终输出净化后的数据集、最优参数组合以及可视化报告。

## 特性

- **模块化设计**：支持可插拔的隐私机制、风险度量、效用评估和优化器，方便扩展与定制。
- **多种隐私模型**：内置差分隐私（拉普拉斯、高斯）、经验风险（KNN 成员推断攻击）等，并预留接口支持 k-匿名等传统方法。
- **多种数据类型**：表格数据原生支持，并预留文本、图像数据加载接口。
- **自动参数搜索**：提供网格搜索、贝叶斯优化、遗传算法等多种优化器，自动探索参数空间。
- **可解释性**：生成风险-效用曲线和自然语言报告，帮助理解参数选择的理由。
- **结果可复现**：支持保存最优参数、扰动数据和报告，便于审计和二次使用。

## 安装

### 通过 PyPI 安装（推荐）

```bash
pip install privacy-tuner
```

### 从源码安装

如果你已经获取了项目源码（例如从本地目录或压缩包），可以在项目根目录下执行以下命令进行安装：

```bash
cd privacy_tuner   # 进入项目根目录
pip install -e .
```

> 注：`-e` 选项表示以可编辑模式安装，方便修改代码后立即生效。如果不需要修改源码，也可以去掉 `-e` 进行普通安装。

## 快速开始

以下示例使用 Adult 数据集，演示完整的隐私保护流程。

```python
import numpy as np
from sklearn.datasets import fetch_openml
from privacy_tuner.input import CSVLoader
from privacy_tuner.core.mechanisms import CopulaMechanism
from privacy_tuner.core.risk import EmpiricalRiskMeter
from privacy_tuner.core.utility import TSTRClassifier
from privacy_tuner.core.optimizers import GridSearchOptimizer
from privacy_tuner.output import CSVExporter, SimpleReporter

# 加载数据
adult = fetch_openml(data_id=1590, as_frame=True)
df = adult.data.select_dtypes(include=[np.number]).dropna()
y = (adult.target == '>50K').astype(int).values
data = np.column_stack([df.values, y])

# 定义组件
mechanism = CopulaMechanism()               # 生成合成数据
risk_meter = EmpiricalRiskMeter()           # 使用 KNN 成员推断风险
utility = TSTRClassifier(target_column=-1)  # 使用分类准确率作为效用
optimizer = GridSearchOptimizer()           # 网格搜索参数

# 设置参数空间和风险约束
param_space = {
    'sampling_ratio': [0.5, 1.0, 2.0],
    'noise_scale': [0.0, 0.1, 0.5]
}
risk_constraint = (0.0, 1.0)  # 允许风险 ≤ 1.0（风险值越小越安全）

# 执行搜索
best_params, best_utility, best_risk = optimizer.search(
    original_data=data,
    mechanism=mechanism,
    risk_meter=risk_meter,
    utility_evaluator=utility,
    param_space=param_space,
    risk_constraint=risk_constraint
)

# 输出结果
print(f"最优参数: {best_params}")
print(f"最优效用 (准确率): {best_utility:.4f}")
print(f"对应风险: {best_risk:.4f}")

# 生成最终扰动数据并导出
final_perturbed = mechanism.apply(data, best_params)
CSVExporter().export(final_perturbed, "output/perturbed.csv")
SimpleReporter().generate(
    original_info={"shape": data.shape},
    mechanism=mechanism,
    search_results={
        "best_params": best_params,
        "best_utility": best_utility,
        "best_risk": best_risk
    },
    output_path="output/report.txt"
)
```

> 运行上述代码后，你将在 `output/` 目录下得到扰动后的数据文件 `perturbed.csv` 和一份简要报告 `report.txt`。

更多示例请参考项目中的 [examples](./privacy_tuner/examples) 目录。

## 核心模块

| 模块 | 描述 | 内置实现 |
|------|------|----------|
| **输入层** | 数据加载与特征分析 | `CSVLoader`, `FeatureAnalyzer` |
| **隐私机制** | 数据扰动算法 | `CopulaMechanism`, `LaplaceMechanism`, `GaussianMechanism` |
| **风险度量** | 隐私风险评估 | `EmpiricalRiskMeter`, `DPRisk` |
| **效用评估** | 数据实用性评估 | `TSTRClassifier`, `QueryError`, `ClusteringSilhouette` |
| **优化器** | 参数自动搜索 | `GridSearchOptimizer`, `BayesianOptimizer`, `GeneticOptimizer` |
| **输出层** | 结果导出与报告 | `CSVExporter`, `HTMLReporter` |
| **可视化** | 图表绘制 | `Visualizer` |

## 目录结构

```
privacy_tuner/
├── privacy_tuner/               # 主代码包
│   ├── input/                   # 数据加载与特征分析
│   ├── core/                    # 核心模块（机制、风险、效用、优化器）
│   ├── output/                  # 数据导出与报告生成
│   ├── visualization/           # 可视化工具
│   ├── validation/              # 验证与案例库
│   └── examples/                # 使用示例
├── tests/                       # 单元测试
├── docs/                        # 文档
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── MANIFEST.in
├── setup.py
└── requirements.txt
```

## 开发与贡献

欢迎参与开发！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境搭建、代码风格和测试流程。

### 本地开发环境

```bash
# 进入项目根目录
cd privacy_tuner

# 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate   # Linux/Mac
venv\Scripts\activate      # Windows

# 安装开发依赖
pip install -e .
pip install pytest flake8 black
```

### 运行测试

```bash
pytest tests/
```

## 许可证

本项目采用 [MIT 许可证](LICENSE)。