Metadata-Version: 2.4
Name: datatunner
Version: 0.1.0
Summary: Ferramenta para determinar a proporção ideal de dados sintéticos em modelos de ML
Home-page: https://github.com/leandro-rocha/datatunner
Author: Leandro Rocha
Author-email: Leandro Rocha <leandro.rocha@example.com>
License: MIT
Project-URL: Homepage, https://github.com/leandro-rocha/datatunner
Project-URL: Documentation, https://datatunner.readthedocs.io
Project-URL: Repository, https://github.com/leandro-rocha/datatunner
Keywords: machine learning,deep learning,synthetic data,data augmentation,neural networks
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🎯 DataTunner

**Otimização Automática de Proporções de Dados Sintéticos para Modelos de Deep Learning**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## 📖 Sobre

DataTunner é uma ferramenta Python de código aberto que automatiza o processo de determinação da proporção ideal de dados sintéticos para maximizar a performance de modelos de redes neurais. 

A crescente demanda por grandes volumes de dados para treinamento de modelos de Deep Learning tem impulsionado o uso de dados sintéticos como solução para escassez e desbalanceamento de datasets. O DataTunner sistematiza esse processo, que tradicionalmente é empírico e não estruturado.

## ✨ Características Principais

- 🔄 **Geração Automática de Datasets Híbridos**: Combina dados reais e sintéticos em diferentes proporções
- 🖼️ **Suporte a Imagens**: CNNs (ResNet, VGG, MobileNet) com data augmentation
- 📊 **Suporte a Dados Tabulares**: MLPs, Random Forest, XGBoost com SMOTE e CTGAN
- 📈 **Métricas Abrangentes**: Accuracy, Precision, Recall, F1-Score, ROC-AUC
- 🎨 **Visualizações Ricas**: Gráficos interativos e relatórios detalhados
- 🔬 **Reprodutibilidade Garantida**: Seeds fixas e hiperparâmetros controlados
- ⚡ **Suporte a GPU**: Aceleração via CUDA
- 💾 **Checkpointing**: Retome experimentos interrompidos

## 🚀 Instalação

### Instalação Básica

```bash
pip install datatunner
```

### Instalação para Desenvolvimento

```bash
git clone https://github.com/leandro-rocha/datatunner.git
cd datatunner
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

## 📚 Guia Rápido

### Exemplo com Imagens (CIFAR-10)

```python
from datatunner import DataTunner
from datatunner.models.cnn import ResNetClassifier
from datatunner.generators.augmentation import ImageAugmentation

# Configurar o otimizador
tunner = DataTunner(
    data_type='image',
    real_data_path='data/cifar10/real',
    synthetic_data_path='data/cifar10/synthetic',
    output_dir='results/cifar10'
)

# Definir modelo
model = ResNetClassifier(num_classes=10, architecture='resnet18')

# Executar otimização
results = tunner.optimize(
    model=model,
    proportions=[0.0, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0],
    epochs=50,
    batch_size=64,
    n_trials=3  # Repetições para robustez
)

# Visualizar resultados
tunner.plot_results()
print(f"Melhor proporção: {results['best_proportion']}")
```

### Exemplo com Dados Tabulares

```python
from datatunner import DataTunner
from datatunner.models.mlp import MLPClassifier
from datatunner.generators.smote import SMOTEGenerator

# Configurar o otimizador
tunner = DataTunner(
    data_type='tabular',
    real_data_path='data/adult/train.csv',
    test_data_path='data/adult/test.csv',
    output_dir='results/adult'
)

# Gerar dados sintéticos com SMOTE
generator = SMOTEGenerator(k_neighbors=5)
synthetic_data = generator.generate(data=tunner.real_data, n_samples=5000)

# Definir modelo
model = MLPClassifier(hidden_layers=[128, 64, 32], dropout=0.3)

# Executar otimização
results = tunner.optimize(
    model=model,
    synthetic_data=synthetic_data,
    proportions=[0.0, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0],
    epochs=100,
    batch_size=128
)

# Relatório detalhado
tunner.generate_report(format='html')
```

## 📊 Metodologia

### Para Datasets de Imagem

1. **Entrada**: Imagens reais + imagens sintéticas (augmentation, GANs, difusão)
2. **Mistura**: Combinação em proporções variadas com balanceamento de classes
3. **Treinamento**: CNNs (ResNet, VGG, MobileNet) com hiperparâmetros fixos
4. **Avaliação**: Métricas em conjunto de teste independente

### Para Datasets Tabulares

1. **Entrada**: Dados tabulares reais + sintéticos (SMOTE, CTGAN)
2. **Mistura**: Preservação de distribuições e correlações
3. **Treinamento**: MLPs, Random Forest, XGBoost, LightGBM
4. **Avaliação**: Métricas específicas para desbalanceamento

## 🏗️ Arquitetura

```
datatunner/
├── core/           # Motor de otimização e avaliação
├── generators/     # Geradores de dados sintéticos
├── models/         # Modelos de ML/DL
├── utils/          # Utilitários e visualização
└── config/         # Configurações
```

## 🧪 Testes

```bash
pytest tests/ -v --cov=datatunner
```

## 📖 Documentação

Documentação completa disponível em: [https://datatunner.readthedocs.io](https://datatunner.readthedocs.io)

## 🤝 Contribuindo

Contribuições são bem-vindas! Por favor, leia nosso [guia de contribuição](CONTRIBUTING.md).

## 📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.

## 📚 Citação

Se você usar o DataTunner em sua pesquisa, por favor cite:

```bibtex
@software{datatunner2026,
  author = {Rocha, Leandro},
  title = {DataTunner: Otimização de Proporções de Dados Sintéticos},
  year = {2026},
  url = {https://github.com/leandro-rocha/datatunner}
}
```

## 👥 Autores

- **Leandro Rocha** - *Desenvolvedor Principal* - [@leandrocr.adv](https://instagram.com/leandrocr.adv)

## 🙏 Agradecimentos

Baseado na pesquisa sobre otimização de dados sintéticos para modelos de Deep Learning.

---

**Desenvolvido com ❤️ para a comunidade de Data Science**
