deepfense 0.1__tar.gz

deepfense-0.1/MANIFEST.in

@@ -0,0 +1,27 @@
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+recursive-exclude docs *.md *.png
+recursive-exclude deepfense/config *.yaml
+recursive-exclude deepfense/config *.parquet
+
+# Exclude specific config subdirectories
+prune deepfense/config/experiments
+prune deepfense/config/augmentations
+prune deepfense/config/examples
+prune deepfense/config/parquets
+
+# Exclude fairseq and wavlm modules
+exclude deepfense/models/modules/fairseq
+exclude deepfense/models/modules/wavlm
+exclude deepfense/models/modules/*/__pycache__
+exclude deepfense/models/modules/*/*.pyc
+
+# Global excludes
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *.pth
+global-exclude *.pt
+global-exclude *.ckpt

deepfense-0.1/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: deepfense
+Version: 0.1
+Summary: A Modular, Extensible Framework for Deepfake Audio Detection (ASV Spoofing)
+Author: DeepFense Team
+License: Apache-2.0
+Project-URL: Homepage, https://deepfense.github.io/
+Project-URL: Documentation, https://deepfense.readthedocs.io/
+Project-URL: Repository, https://github.com/Yaselley/deepfense-framework
+Project-URL: Issues, https://github.com/Yaselley/deepfense-framework/issues
+Project-URL: Bug Tracker, https://github.com/Yaselley/deepfense-framework/issues
+Project-URL: HuggingFace, https://huggingface.co/DeepFense
+Keywords: deepfake,audio,spoofing,detection,asv,speech,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch<=2.9,>=2.1.0
+Requires-Dist: torchaudio<=2.9,>=2.1.0
+Requires-Dist: torchvision<=0.23,>=0.12.0
+Requires-Dist: numpy<2.2,>=1.24
+Requires-Dist: pandas<3.0,>=2.0
+Requires-Dist: scipy<1.16,>=1.9
+Requires-Dist: scikit-learn<1.8,>=1.2
+Requires-Dist: pyarrow
+Requires-Dist: librosa<0.12,>=0.10
+Requires-Dist: pydub
+Requires-Dist: soundfile
+Requires-Dist: soxr
+Requires-Dist: transformers<5.0,>=4.50
+Requires-Dist: tokenizers
+Requires-Dist: tqdm
+Requires-Dist: typing-extensions
+Requires-Dist: safetensors
+Requires-Dist: wandb<1.0,>=0.12
+Requires-Dist: einops<1.0,>=0.7
+Requires-Dist: matplotlib<4.0,>=3.7
+Requires-Dist: seaborn<0.14,>=0.12
+Requires-Dist: timm
+Requires-Dist: omegaconf==2.0.6
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+
+<div align="center">
+  <img src="docs/logo/logo.png" alt="DeepFense Logo" width="400">
+</div>
+
+<div align="center">
+
+# DeepFense Framework
+
+**A Modular, Extensible Framework for Deepfake Audio Detection**
+
+[![Website](https://img.shields.io/badge/🌐-Website-blue)](https://deepfense.github.io/)
+[![HuggingFace](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/DeepFense)
+[![Documentation](https://img.shields.io/badge/📚-Documentation-green)](https://deepfense.readthedocs.io/)
+[![Recipes](https://img.shields.io/badge/📖-Recipes-orange)](recipes/)
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-navy.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.8%2B-navy.svg)](https://www.python.org/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-navy.svg)](https://pytorch.org/)
+
+</div>
+
+---
+
+## What is DeepFense?
+
+**DeepFense** is a modular framework for building and training deepfake audio detection models. It provides a plug-and-play architecture where you can easily combine different **Frontends** (feature extractors), **Backends** (classifiers), and **Loss Functions** to create state-of-the-art detection systems.
+
+### Key Features
+
+- 🔄 **Modular Architecture** — Swap components with a single config change
+- ⚙️ **Configuration-Driven** — All experiments defined in YAML
+- 🎛️ **Advanced Augmentations** — RawBoost, RIR, Codec, Noise, and more
+- 📊 **Built-in Metrics** — EER, minDCF, F1-score, Accuracy
+- 🚀 **Simple CLI** — Train and test models with command-line interface
+- 📚 **Recipes** — Pre-configured training setups and example models ([see recipes](recipes/))
+
+**New to DeepFense?** Check out our [recipes](recipes/) for pre-configured training setups and example models to get started quickly!
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Understanding DeepFense Architecture](#understanding-deepfense-architecture)
+3. [Available Components](#available-components)
+4. [Training Models](#training-models)
+5. [Evaluating and Testing Models](#evaluating-and-testing-models)
+6. [Data Preparation](#data-preparation)
+7. [Extending DeepFense](#extending-deepfense)
+8. [Using the CLI (Alternative)](#using-the-cli-alternative)
+9. [Complete Pipeline Flow](#complete-pipeline-flow)
+10. [Documentation](#documentation)
+
+---
+
+## Installation
+
+```bash
+# From source (recommended for development)
+git clone https://github.com/Yaselley/deepfense-framework
+cd deepfense-framework
+pip install -e .
+
+# Or From PyPI 
+pip install deepfense
+```
+
+See [Installation Guide](docs/01_installation.md) for detailed instructions.
+
+---
+
+## Understanding DeepFense Architecture
+
+DeepFense uses a **modular pipeline** architecture:
+
+```
+Raw Audio → Frontend → Features → Backend → Embeddings → Loss → Scores
+```
+
+**Key Components**:
+- **Frontend**: Extracts features from audio (Wav2Vec2, WavLM, HuBERT, etc.)
+- **Backend**: Processes features into embeddings (AASIST, ECAPA-TDNN, MLP, etc.)
+- **Loss Function**: Computes loss and scores (CrossEntropy, OC-Softmax, etc.)
+
+See [Architecture Overview](docs/04_architecture.md) for detailed architecture explanation, or [Pipeline Flow](docs/pipeline_flow.md) for complete pipeline walkthrough.
+
+---
+
+## Available Components
+
+DeepFense provides a modular set of components that can be mixed and matched:
+
+- **Frontends**: Wav2Vec2, WavLM, HuBERT, EAT, MERT - See [Frontends Documentation](docs/components/frontends.md)
+- **Backends**: AASIST, ECAPA-TDNN, RawNet2, MLP, Nes2Net, TCM - See [Backends Documentation](docs/components/backends.md)
+- **Losses**: CrossEntropy, OC-Softmax, AM-Softmax, A-Softmax - See [Losses Documentation](docs/components/losses.md)
+- **Augmentations**: RawBoost, RIR, Codec, Noise, SpeedPerturb - See [Augmentations Documentation](docs/components/augmentations.md)
+
+See [Component Reference](docs/index.md#-component-reference) for complete details.
+
+**Looking for example configurations?** Check out our [recipes](recipes/) for pre-configured training setups and trained models.
+
+---
+
+## Training Models
+
+Train models using Python scripts:
+
+```bash
+python train.py --config deepfense/config/train.yaml
+```
+
+Training creates an experiment directory with checkpoints, logs, and metrics.
+
+**Alternative**: You can also use the CLI (see [Using the CLI](#using-the-cli) section below).
+
+See [Quick Start Guide](docs/02_quickstart.md) for detailed instructions and [Configuration Reference](docs/05_configuration.md) for all YAML parameters.
+
+---
+
+## Evaluating and Testing Models
+
+Test a trained model using Python scripts:
+
+```bash
+python test.py \
+    --config deepfense/config/train.yaml \
+    --checkpoint outputs/my_experiment/best_model.pth
+```
+
+DeepFense computes metrics automatically (EER, minDCF, F1, ACC) and saves results to the experiment directory.
+
+**Alternative**: You can also use the CLI (see [Using the CLI](#using-the-cli) section below).
+
+See [Evaluation & Inference Guide](docs/user_guide/inference.md) for details.
+
+---
+
+## Data Preparation
+
+DeepFense uses **Parquet files** for dataset metadata. Each parquet file should contain:
+- `ID`: Unique identifier
+- `path`: Path to audio file
+- `label`: Label string ("bonafide" or "spoof")
+- `dataset_name`: (Optional) Dataset identifier
+
+Example:
+```python
+import pandas as pd
+data = pd.DataFrame({
+    "ID": ["sample_001", "sample_002"],
+    "path": ["/path/to/audio1.flac", "/path/to/audio2.flac"],
+    "label": ["bonafide", "spoof"]
+})
+data.to_parquet("train.parquet")
+```
+
+### Data Transforms, Padding, and Cropping
+
+DeepFense applies transforms in two stages:
+1. **Base Transforms** (always): Padding, cropping, resampling
+2. **Augmentations** (training only): RawBoost, RIR, Noise, etc.
+
+**Critical**: All audio must be padded/cropped to the same length for batching. Configure this in your YAML:
+
+```yaml
+data:
+  train:
+    base_transform:
+      - type: "pad"
+        args:
+          max_len: 160000       # 10 seconds @ 16kHz
+          random_pad: True      # Random crop if longer
+          pad_type: "repeat"    # Repeat if shorteror
+```
+
+**See [Data Transforms Guide](docs/data_transforms.md)** for complete transform parameters, padding/cropping options, augmentations, and how to check/modify configurations.
+
+---
+
+## Extending DeepFense
+
+DeepFense makes it easy to add custom components using the registry pattern. Each component type has a detailed guide:
+
+- [Adding Backends](docs/user_guide/adding_backends.md) | [Adding Frontends](docs/user_guide/adding_frontends.md) | [Adding Losses](docs/user_guide/adding_losses.md)
+- [Adding Datasets](docs/user_guide/adding_datasets.md) | [Adding Augmentations](docs/user_guide/adding_augmentations.md)
+- [Adding Optimizers](docs/user_guide/adding_optimizers.md) | [Adding Metrics](docs/user_guide/adding_metrics.md) | [Adding Schedulers](docs/user_guide/adding_schedulers.md)
+
+See [Extending DeepFense (Quick Reference)](docs/user_guide/extending.md) for a quick overview of all component types.
+
+---
+
+## Using the CLI (Alternative)
+
+DeepFense provides a CLI as an alternative to Python scripts. The CLI supports:
+
+```bash
+# Train a model (alternative to python train.py)
+deepfense train --config config/train.yaml
+
+# Test a model (alternative to python test.py)
+deepfense test --config config/train.yaml --checkpoint outputs/exp/best_model.pth
+
+# List available components
+deepfense list
+```
+
+**Note**: The CLI currently supports training and testing existing models with different parameters. Future versions will support adding components via CLI.
+
+See [CLI Reference](docs/cli_reference.md) for complete documentation.
+
+---
+
+## Complete Pipeline Flow
+
+The DeepFense pipeline: **Data → Transforms → Frontend → Backend → Loss → Training → Evaluation**
+
+See [Pipeline Flow Documentation](docs/pipeline_flow.md) for the complete detailed pipeline with all stages, data shapes, and configuration flow.
+
+---
+
+## Documentation
+
+### Getting Started
+
+| Guide | Description |
+|-------|-------------|
+| [Installation](docs/01_installation.md) | Full installation instructions |
+| [Quick Start](docs/02_quickstart.md) | Train your first model in 5 minutes |
+| [Full Tutorial](docs/03_full_tutorial.md) | Complete config-driven training guide |
+| [Architecture](docs/04_architecture.md) | How DeepFense works internally |
+
+### Component Reference
+
+| Component | Documentation |
+|-----------|--------------|
+| [Frontends](docs/components/frontends.md) | Wav2Vec2, WavLM, HuBERT, MERT, EAT |
+| [Backends](docs/components/backends.md) | AASIST, ECAPA_TDNN, RawNet2, MLP, Pool, Nes2Net, TCM |
+| [Losses](docs/components/losses.md) | CrossEntropy, OC-Softmax, AM-Softmax, A-Softmax |
+| [Augmentations](docs/components/augmentations.md) | RawBoost, RIR, Codec, Noise, SpeedPerturb |
+| [Optimizers & Schedulers](docs/components/optimizers_schedulers.md) | Adam, SGD, CosineAnnealing, StepLR |
+
+### User Guides
+
+| Guide | Description |
+|-------|-------------|
+| [Training with CLI](docs/user_guide/training_with_cli.md) | How to train models using the CLI |
+| [Training Workflow](docs/user_guide/training.md) | Detailed training loop explanation |
+| [Evaluation & Inference](docs/user_guide/inference.md) | Testing and deployment |
+| [Configuration Reference](docs/05_configuration.md) | All YAML parameters explained |
+| [Library Usage](docs/06_library_usage.md) | Use DeepFense programmatically in Python |
+
+### Extending DeepFense
+
+| Guide | Description |
+|-------|-------------|
+| [Adding a New Backend](docs/user_guide/adding_backends.md) | Step-by-step guide to create custom backends |
+| [Adding a New Frontend](docs/user_guide/adding_frontends.md) | Step-by-step guide to create custom frontends |
+| [Adding a New Loss](docs/user_guide/adding_losses.md) | Step-by-step guide to create custom loss functions |
+| [Adding a New Dataset](docs/user_guide/adding_datasets.md) | Step-by-step guide to create custom datasets |
+| [Adding Augmentations](docs/user_guide/adding_augmentations.md) | Step-by-step guide to create custom data augmentations |
+| [Adding Optimizers](docs/user_guide/adding_optimizers.md) | Step-by-step guide to add custom optimizers |
+| [Adding Metrics](docs/user_guide/adding_metrics.md) | Step-by-step guide to add custom evaluation metrics |
+| [Adding Schedulers](docs/user_guide/adding_schedulers.md) | Step-by-step guide to add custom learning rate schedulers |
+| [Extending DeepFense (Quick Reference)](docs/user_guide/extending.md) | Quick reference for all component types |
+
+### CLI Reference
+
+| Guide | Description |
+|-------|-------------|
+| [CLI Reference](docs/cli_reference.md) | Complete CLI documentation |
+
+### Recipes
+
+| Resource | Description |
+|----------|-------------|
+| [Recipes](recipes/) | Pre-configured training setups and example models |
+
+---
+
+## Project Structure
+
+```
+deepfense/
+├── config/          # YAML configurations
+├── data/            # Data handling & transforms
+├── models/          # Frontends, backends, losses
+├── training/        # Training loop & evaluation
+├── utils/           # Registry & helpers
+└── cli/             # Command-line interface
+```
+
+See [Architecture Overview](docs/04_architecture.md) for detailed structure and component organization.
+
+---
+
+## Recipes
+
+DeepFense provides example recipes (pre-configured training setups) to help you get started quickly. Each recipe includes:
+- Complete configuration files
+- Pre-trained model checkpoints (where available)
+- Training scripts and evaluation results
+- Documentation on architecture choices and hyperparameters
+
+See the [recipes](recipes/) folder for available recipes. Each recipe includes detailed README files explaining the configuration and how to reproduce the results.
+
+---
+
+## Contributing
+
+We welcome contributions! See [Extending DeepFense](docs/user_guide/extending.md) for guidelines on adding new components.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.
+
+---
+
+## Citation
+
+If you use DeepFense in your research, please cite:
+
+```bibtex
+@software{deepfense2024,
+  title={DeepFense: A Modular Framework for Deepfake Audio Detection},
+  author={DeepFense Team},
+  year={2024},
+  url={https://github.com/Yaselley/deepfense-framework}
+}
+```