Metadata-Version: 2.3
Name: deepbridge
Version: 0.1.42
Summary: 
Author: Team DeepBridge
Author-email: gustavo.haase@gmail.com
Requires-Python: >=3.10,<3.13
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: dask[distributed] (>=2025.3.0,<2026.0.0)
Requires-Dist: ipython (>=8.32.0,<9.0.0)
Requires-Dist: ipywidgets (>=8.1.5,<9.0.0)
Requires-Dist: jinja2 (>=3.1.5,<4.0.0)
Requires-Dist: joblib (>=1.4.2,<2.0.0)
Requires-Dist: matplotlib (>=3.10.0,<4.0.0)
Requires-Dist: numpy (>=2.2.3,<3.0.0)
Requires-Dist: optuna (>=4.2.1,<5.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: plotly (>=6.0.0,<7.0.0)
Requires-Dist: pyarrow (>=19.0.1,<20.0.0)
Requires-Dist: rich (>=13.9.4,<14.0.0)
Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
Requires-Dist: scipy (>=1.15.1,<2.0.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: setuptools (>=76.0.0,<77.0.0)
Requires-Dist: statsmodels (>=0.14.4,<0.15.0)
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
Requires-Dist: typer[all] (>=0.15.1,<0.16.0)
Requires-Dist: xgboost (>=2.1.4,<3.0.0)
Project-URL: Código, https://github.com/DeepBridge-Validation/DeepBridge
Project-URL: Documentação, https://deepbridge.readthedocs.io/en/latest/
Description-Content-Type: text/markdown

# DeepBridge

[![Documentation Status](https://readthedocs.org/projects/deepbridge/badge/?version=latest)](https://deepbridge.readthedocs.io/en/latest/)
[![CI](https://github.com/DeepBridge-Validation/DeepBridge/actions/workflows/pipeline.yaml/badge.svg)](https://github.com/DeepBridge-Validation/DeepBridge/actions/workflows/pipeline.yaml)
[![PyPI version](https://badge.fury.io/py/deepbridge.svg)](https://badge.fury.io/py/deepbridge)
[![PyPI Downloads](https://static.pepy.tech/badge/deepbridge)](https://pepy.tech/projects/deepbridge)

DeepBridge is a comprehensive Python library for advanced machine learning model validation, distillation, and performance analysis. It provides powerful tools to manage experiments, validate models, create more efficient model versions, and conduct in-depth performance evaluations.

## Installation

You can install DeepBridge using pip:

```bash
pip install deepbridge
```

Or install from source:

```bash
git clone https://github.com/DeepBridge-Validation/DeepBridge.git
cd deepbridge
pip install -e .
```

## Key Features

- **Comprehensive Testing Framework**
  - Robustness testing with perturbation analysis
  - Uncertainty quantification using conformal prediction
  - Resilience testing under distribution shifts
  - Hyperparameter importance analysis

- **Model Validation**
  - Experiment tracking and management
  - Comprehensive model performance analysis
  - Advanced metric tracking
  - Model versioning support

- **Model Distillation**
  - Knowledge distillation across multiple model types
  - Automated distillation with hyperparameter optimization
  - Support for GBM, XGBoost, and neural networks
  - Performance optimization and model compression

- **Advanced Analytics & Reporting**
  - Interactive HTML reports with Plotly visualizations
  - Static reports for documentation
  - Detailed performance metrics and analysis
  - Multi-model comparison capabilities

- **Synthetic Data Generation**
  - Gaussian Copula method
  - Privacy-preserving data synthesis
  - Quality metrics and validation
  - Integration with validation pipeline

## Quick Start

### Model Validation
```python
from deepbridge.core.experiment import Experiment
from deepbridge.db_data import DBDataset

# Create dataset
dataset = DBDataset(
    data=df,
    target_column='target',
    features=['feature1', 'feature2', 'feature3']
)

# Create experiment
experiment = Experiment(
    name='model_validation',
    dataset=dataset,
    models={'my_model': trained_model}
)

# Run validation tests
robustness_results = experiment.run_test('robustness', config='medium')
uncertainty_results = experiment.run_test('uncertainty', config='medium')

# Generate comprehensive report
experiment.generate_report('robustness', output_dir='./reports')
```

### Model Distillation
```python
from deepbridge.distillation import AutoDistiller
from deepbridge.db_data import DBDataset

# Create dataset with predictions
dataset = DBDataset(
    data=df,
    target_column='target',
    features=features,
    prob_cols=['prob_class_0', 'prob_class_1']
)

# Run automated distillation
distiller = AutoDistiller(
    dataset=dataset,
    output_dir='results',
    test_size=0.2,
    n_trials=10
)
results = distiller.run(use_probabilities=True)
```

## Command-Line Interface
```bash
# Run model validation
deepbridge validate --dataset data.csv --model model.pkl --tests all

# Generate reports
deepbridge report --results ./results --output ./reports --format interactive

# Train distilled model
deepbridge distill train gbm predictions.csv features.csv -s ./models

# Generate synthetic data
deepbridge synthetic generate --data original.csv --method gaussian_copula --samples 10000
```

## Requirements

- Python 3.10-3.12
- Key Dependencies:
  - numpy >= 2.2.3
  - pandas >= 2.2.3
  - scikit-learn >= 1.6.1
  - xgboost >= 2.1.4
  - scipy >= 1.15.1
  - matplotlib >= 3.10.0
  - seaborn >= 0.13.2
  - plotly >= 6.0.0
  - optuna >= 4.2.1
  - jinja2 >= 3.1.5

## Documentation

Full documentation is available at: [DeepBridge Documentation](https://deepbridge.readthedocs.io/)

### Key Documentation Sections

- **[Getting Started](https://deepbridge.readthedocs.io/en/latest/tutorials/install/)** - Installation and basic examples
- **[User Guide](https://deepbridge.readthedocs.io/en/latest/guides/validation/)** - Core concepts and tutorials
- **[Technical Reference](https://deepbridge.readthedocs.io/en/latest/technical/implementation_guide/)** - Architecture and implementation details
- **[API Reference](https://deepbridge.readthedocs.io/en/latest/api/complete_reference/)** - Complete API documentation

### Quick Links

- [Installation Guide](https://deepbridge.readthedocs.io/en/latest/tutorials/install/)
- [Basic Examples](https://deepbridge.readthedocs.io/en/latest/tutorials/basic_examples/)
- [Complete Workflow](https://deepbridge.readthedocs.io/en/latest/tutorials/complete_workflow/)
- [FAQ](https://deepbridge.readthedocs.io/en/latest/resources/faq/)
- [Troubleshooting](https://deepbridge.readthedocs.io/en/latest/resources/troubleshooting/)

## Contributing

We welcome contributions! Please see our contribution guidelines for details on how to submit pull requests, report issues, and contribute to the project.

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

### Recent Updates

- **2025-07-02**: Added comprehensive documentation including Implementation Guide, Testing Framework, Report Generation, and complete API Reference
- **2025-05-15**: Fixed static report chart URLs to properly use relative paths with `./` prefix for improved portability across different environments

## Development Setup

```bash
# Clone the repository
git clone https://github.com/DeepBridge-Validation/DeepBridge.git
cd deepbridge

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

## Running Tests

```bash
pytest tests/
```

## License

MIT License

## Citation

If you use DeepBridge in your research, please cite:

```bibtex
@software{deepbridge2025,
  title = {DeepBridge: Advanced Model Validation and Distillation Library},
  author = {Gustavo Haase, Paulo Dourado},
  year = {2025},
  url = {https://github.com/DeepBridge-Validation/DeepBridge}
}
```

## Contact

- GitHub Issues: [DeepBridge Issues](https://github.com/DeepBridge-Validation/DeepBridge/issues)
- Email: gustavo.haase@gmail.com
