Metadata-Version: 2.4
Name: rf-signal-classification
Version: 1.0.0
Summary: Modular, production-grade deep learning framework for RF signal classification and modulation recognition
Author-email: AI Engineering Team <anujmundu@gmail.com>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: h5py>=3.8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: torch>=2.0.0
Requires-Dist: scikit-learn>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.3.0; extra == "dev"
Requires-Dist: mypy>=1.3.0; extra == "dev"
Requires-Dist: black>=23.3.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# RF Signal Classification Framework

<div align="center">

[![Release](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md)
[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-brightgreen.svg)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](.github/workflows/tests.yml)
[![Tests](https://img.shields.io/badge/tests-128%20passed-success.svg)](#testing--verification)

**A Modular, Production-Grade Deep Learning Framework for Radio Frequency (RF) Signal Classification and Automatic Modulation Recognition (AMC)**

</div>

---

## 📌 Project Overview & Motivation

Automatic Modulation Classification (AMC) is a critical component in modern software-defined radios (SDR), cognitive radio systems, spectrum monitoring, and electronic warfare. Real-world wireless environments introduce severe channel impairments—including multipath fading, Rayleigh fading, phase offsets, frequency drift, and additive white Gaussian noise (AWGN)—making robust RF signal classification challenging.

This repository provides a **modular, clean-architecture Python framework (v1.0.0)** designed for end-to-end processing, feature extraction, neural network training, evaluation, experiment tracking, deployment, and observability of complex I/Q time-series signals.

### Key Capabilities
- **Format-Agnostic Inspection**: Non-loading metadata extraction for RadioML 2016.10A (`.pkl`) and RadioML 2018.01A (`.hdf5`) datasets.
- **Zero-Copy Ingestion**: Memory-efficient lazy dataset adapters supporting deterministic dataset splitters (`DataSplitter`).
- **Signal Preprocessing Pipeline**: Reusable signal validation, power/Z-score normalizers (`ZScoreNormalizer`, `UnitPowerNormalizer`), and IQ transforms.
- **Model-Independent Feature Extraction**: Extraction of raw I/Q, FFT magnitude/phase, STFT time-frequency representations, and Spectrograms into standardized `FeatureArtifact` objects.
- **Extensible Model Registry**: Pluggable PyTorch architecture registry (`MLPModel`, `CNNModel`) decoupled from training and evaluation logic.
- **Training Engine**: Modular optimizer, scheduler, loss factories, and atomic checkpoint management (`CheckpointManager`).
- **Stateless Metrics Engine**: Framework-independent metric computations (`Accuracy`, `Precision`, `Recall`, `F1Score`, `ConfusionMatrix`, `PerClassAccuracy`).
- **Read-Only Evaluation Engine**: Deterministic batch evaluation ensuring zero model parameter corruption and parameter hash immutability.
- **Experiment Tracking Subsystem**: Immutable experiment run records (`ExperimentRun`), configuration snapshots, parent-child experiment lineage, and side-by-side metric comparisons.
- **Self-Describing Deployment Subsystem**: Pluggable model exporters (`PyTorchCheckpointExporter`), self-describing versioned `DeploymentArtifact` packages, real-time SHA256 checksum integrity verification, and high-level `Predictor` wrappers.
- **Passive Observability Subsystem**: Non-intrusive structured logging (`StructuredLogger`), stage timing (`Profiler`), system resource diagnostics (`DiagnosticsCollector`), and timezone-aware execution summaries (`ExecutionSummary`).

---

## 📊 Supported Datasets

The framework provides native adapters for standard benchmark datasets in RF signal classification:

| Dataset | Storage Format | Modulation Classes | SNR Range (dB) | Sample Dimensions |
| :--- | :--- | :--- | :--- | :--- |
| **RadioML 2016.10A** | `.pkl` Pickle Dictionary | 11 Classes (BPSK, QPSK, 8PSK, QAM16, QAM64, CPFSK, GFSK, PAM4, WFM, AM-DSB, AM-SSB) | -20 dB to +18 dB (step 2 dB) | $2 \times 128$ (I/Q Channels) |
| **RadioML 2018.01A** | `.hdf5` HDF5 Format | 24 Classes (OOK, 4ASK, 8ASK, BPSK, QPSK, 8PSK, 16PSK, 32PSK, 16APSK, 32APSK, 64APSK, 128APSK, 16QAM, 32QAM, 64QAM, 128QAM, 256QAM, AM-SSB-WC, AM-SSB-SC, AM-DSB-WC, AM-DSB-SC, FM, GFSK, CPFSK) | -20 dB to +30 dB (step 2 dB) | $1024 \times 2$ (I/Q Samples) |

---

## 🏗 Subsystem Architecture & Workflow

The architecture strictly adheres to **Clean Architecture Principles**, ensuring high cohesion and low coupling across all 12 core subsystems:

```mermaid
flowchart TD
    subgraph Ingestion["1. Data Ingestion & Inspection"]
        A[Raw Dataset Files .pkl / .hdf5] --> B[DatasetInspector]
        B --> C[InspectionReport]
        C --> D[DatasetAdapter]
    end

    subgraph SignalProcessing["2. Processing & Feature Extraction"]
        D --> E[PreprocessingPipeline]
        E --> F[FeatureExtractorFactory]
        F --> G[FeatureArtifact]
    end

    subgraph Optimization["3. Model Registry & Training"]
        G --> H[ModelRegistry / ModelFactory]
        H --> I[BaseModel]
        I --> J[Trainer & CheckpointManager]
        J --> K[TrainingArtifact & Checkpoint]
    end

    subgraph EvaluationMetrics["4. Metrics & Read-Only Evaluation"]
        I --> L[EvaluationEngine]
        G --> L
        L --> M[PredictionArtifact]
        M --> N[MetricsEngine]
        N --> O[EvaluationReport]
    end

    subgraph Management["5. Experiments, Deployment & Observability"]
        J & O --> P[ExperimentManager]
        I --> Q[DeploymentManager]
        Q --> R[DeploymentArtifact & Predictor]
        Ingestion & SignalProcessing & Optimization & EvaluationMetrics & Q --> S[ObservabilityManager]
    end
```

---

## 📂 Repository Directory Tree

```text
rf-signal-classification/
├── .github/
│   └── workflows/
│       └── tests.yml               # GitHub Actions CI workflow
├── datasets/
│   ├── README.md                   # Dataset download instructions
│   └── .gitkeep
├── outputs/                        # Default output directory (git-ignored)
├── src/
│   └── rf_signal_classification/
│       ├── __init__.py
│       ├── core/                   # Subsystem 1: Core abstractions & domain entities
│       ├── inspection/             # Subsystem 2: Format inspection & metadata detection
│       ├── dataset/                # Subsystem 3: Dataset adapters & splitters
│       ├── preprocessing/          # Subsystem 4: Signal validation & normalization
│       ├── feature_extraction/     # Subsystem 5: Signal representation extractors
│       ├── models/                 # Subsystem 6: Neural network model registry
│       ├── training/               # Subsystem 7: Optimization engine & checkpoints
│       ├── metrics/                # Subsystem 8: Stateless metric computations
│       ├── evaluation/             # Subsystem 9: Read-only evaluation pipeline
│       ├── experiment/             # Subsystem 10: Immutable experiment tracking
│       ├── deployment/             # Subsystem 11: Pluggable export & predictor engine
│       └── observability/          # Subsystem 12: Passive telemetry & structured logging
├── tests/
│   └── unit/                       # 128 comprehensive unit tests
│       ├── test_core.py
│       ├── test_inspection.py
│       ├── test_dataset.py
│       ├── test_preprocessing.py
│       ├── test_feature_extraction.py
│       ├── test_models.py
│       ├── test_training.py
│       ├── test_metrics.py
│       ├── test_evaluation.py
│       ├── test_experiment.py
│       ├── test_deployment.py
│       └── test_observability.py
├── validate_deployment.py          # End-to-end deployment validation script
├── validate_observability.py       # End-to-end observability validation script
├── .gitignore
├── CHANGELOG.md                    # Release history (v1.0.0)
├── CODE_OF_CONDUCT.md              # Contributor Covenant v2.1
├── CONTRIBUTING.md                 # Contribution guidelines
├── LICENSE                         # MIT License
├── pyproject.toml                  # PEP 518 build configuration
├── requirements.txt                # Runtime dependencies
└── SECURITY.md                     # Security vulnerability policy
```

---

## 🚀 Installation & Environment Setup

### 1. Prerequisites
- Python `>= 3.10`
- `pip` or `conda`

### 2. Clone & Setup Virtual Environment
```bash
# Clone the repository
git clone https://github.com/anujmundu/rf-signal-classification.git
cd rf-signal-classification

# Create and activate virtual environment
python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate
```

### 3. Install Dependencies
```bash
# Install runtime dependencies
pip install -r requirements.txt

# Install framework in editable mode with development tools
pip install -e .[dev]
```

---

## 💡 Quick Start & Usage Examples

### 1. Dataset Inspection Subsystem
Inspect raw dataset files without loading tensor data into memory:
```python
from pathlib import Path
from rf_signal_classification.inspection import DatasetInspector

inspector = DatasetInspector()
report = inspector.inspect(Path("datasets/radioml2016/RML2016.10a_dict.pkl"))

print(report.format_summary())
# Discovered: 220,000 samples, 11 modulation classes, SNR range [-20 to +18 dB]
```

### 2. Dataset Adapter & Data Splitter Subsystem
Access samples lazily and partition datasets deterministically:
```python
from pathlib import Path
from rf_signal_classification.dataset import RadioML2016Adapter, DataSplitter

adapter = RadioML2016Adapter(Path("datasets/radioml2016/RML2016.10a_dict.pkl"))

# Deterministic 80/10/10 Train/Val/Test Split
splitter = DataSplitter(seed=42)
train_idx, val_idx, test_idx = splitter.split(total_samples=len(adapter), train_ratio=0.8, val_ratio=0.1)

sample = adapter[train_idx[0]]
print(f"Sample signal shape: {sample.signals.shape}, Label: {sample.labels}, SNR: {sample.snrs} dB")
adapter.close()
```

### 3. Signal Preprocessing Subsystem
Normalize I/Q signals using composable preprocessing pipelines:
```python
from rf_signal_classification.preprocessing import PreprocessingConfig, PreprocessingPipeline

# Configure Z-Score normalization and float32 dtype transform
config = PreprocessingConfig(normalization_strategy="zscore", target_dtype="float32")
pipeline = PreprocessingPipeline.from_config(config)

processed_sample = pipeline(sample)
print(f"Normalized mean: {processed_sample.signals.mean():.6f}, std: {processed_sample.signals.std():.6f}")
```

### 4. Feature Extraction Subsystem
Transform I/Q time-series into spectrograms or FFT representations:
```python
from rf_signal_classification.feature_extraction import FeatureExtractionConfig, FeatureExtractorFactory

config = FeatureExtractionConfig(feature_type="spectrogram", fft_length=128, window_size=64, hop_length=16)
extractor = FeatureExtractorFactory.create(config)

feature_artifact = extractor.extract(processed_sample)
print(f"Feature tensor shape: {feature_artifact.tensor_shape}, type: {feature_artifact.feature_type}")
```

### 5. Model Registry & Training Subsystem
Instantiate models dynamically and train with automatic checkpointing:
```python
from rf_signal_classification.models import ModelConfig, ModelFactory
from rf_signal_classification.training import TrainingConfig, Trainer

# Create 2D CNN model for Spectrogram classification
model_config = ModelConfig(model_name="cnn", num_classes=11, input_shape=feature_artifact.tensor_shape)
model = ModelFactory.create(model_config)

# Train model
train_config = TrainingConfig(epochs=5, batch_size=32, learning_rate=1e-3, checkpoint_dir="outputs/checkpoints")
trainer = Trainer(model=model, config=train_config)
training_artifact = trainer.fit([feature_artifact] * 100)

print(f"Final training loss: {training_artifact.final_loss:.4f}")
```

### 6. Read-Only Evaluation Subsystem
Execute read-only model evaluation without parameter side effects:
```python
from rf_signal_classification.evaluation import EvaluationConfig, EvaluationEngine

eval_config = EvaluationConfig(eval_dataset_name="RadioML2016.10A", batch_size=32)
eval_engine = EvaluationEngine(config=eval_config)

eval_report = eval_engine.evaluate(model, [feature_artifact] * 50)
print(eval_report.format_summary())
```

### 7. Experiment Tracking Subsystem
Record immutable experiment runs, configurations, and parent-child lineage:
```python
from rf_signal_classification.experiment import ExperimentConfig, ExperimentManager

manager = ExperimentManager(output_dir="outputs/experiments")
exp_config = ExperimentConfig(experiment_name="cnn_spectrogram_baseline", tags=("radioml2016", "cnn"))

run = manager.start_run(config=exp_config, config_snapshot={"model": model_config.to_dict()})
manager.record_artifact(run.run_id, "checkpoint", training_artifact.checkpoint_paths[0])
manager.record_metrics(run.run_id, eval_report.metrics)

completed_run = manager.complete_run(run.run_id)
print(completed_run.format_summary())
```

### 8. Deployment Subsystem & High-Level Predictor
Export self-describing deployment packages with SHA256 checksum validation:
```python
from rf_signal_classification.deployment import DeploymentConfig, DeploymentManager

# 1. Export model package
dep_config = DeploymentConfig(export_dir="outputs/deployments", package_version="1.0.0")
deployment_artifact = DeploymentManager.export_model(model, dep_config)

# 2. Create high-level Predictor from exported package
predictor = DeploymentManager.create_predictor(Path(deployment_artifact.exported_model_path).parent)

# 3. Perform inference (automatically handles eval mode & no_grad)
prediction_artifact = predictor.predict(feature_artifact)
print(f"Predicted modulation class index: {prediction_artifact.predicted_classes}")
```

### 9. Passive Observability Subsystem
Track stage execution timing and health diagnostics non-intrusively:
```python
from rf_signal_classification.observability import ObservabilityConfig, ObservabilityManager

obs_mgr = ObservabilityManager(config=ObservabilityConfig(log_level="INFO"))
obs_mgr.start_session("production_inference_pipeline")

with obs_mgr.time_stage("inference_stage"):
    result = predictor.predict(feature_artifact)

execution_summary = obs_mgr.end_session()
print(execution_summary.format_summary())
```

---

## 🧪 Testing & Verification

The repository includes a comprehensive unit test suite (`tests/unit/`) achieving **100% test pass rate** across all 12 subsystems:

```bash
# Execute the full pytest repository test suite
python -m pytest
```

### Automated Subsystem Test Distribution (128 Total Tests)
- `test_core.py` (9 tests): Domain entities, types, shape validators, exception hierarchy.
- `test_inspection.py` (13 tests): PKL/HDF5 inspectors, non-loading metadata detection, orchestrator.
- `test_dataset.py` (9 tests): Dataset adapters, lazy indexing, deterministic data splitters.
- `test_preprocessing.py` (19 tests): Signal validators, normalizers, IQ transforms, pipeline order.
- `test_feature_extraction.py` (12 tests): Raw IQ, FFT, STFT, Spectrogram extractors, factory.
- `test_models.py` (12 tests): PyTorch MLP & CNN models, model registry, prediction artifacts.
- `test_training.py` (10 tests): Optimization engine, loss/optimizer factories, checkpoint manager.
- `test_metrics.py` (12 tests): Stateless metrics (Accuracy, Precision, Recall, F1, Confusion Matrix).
- `test_evaluation.py` (6 tests): Read-only evaluation engine, model parameter weight preservation.
- `test_experiment.py` (6 tests): Immutable experiment runs, parent-child lineage, history query.
- `test_deployment.py` (7 tests): Pluggable exporters, SHA256 checksum validation, predictor inference.
- `test_observability.py` (13 tests): Telemetry events, structured logger, profiler timings, diagnostics.

### Real-World Dataset Validation Scripts
Execute end-to-end validation scripts verifying real dataset pipelines:
```bash
python validate_deployment.py
python validate_observability.py
```

---

## ⚙️ Software Architecture & Design Philosophy

1. **Open/Closed Principle (OCP)**: All major components (Inspectors, Adapters, Normalizers, Extractors, Models, Metrics, Exporters) use pluggable registries and factories. New models or feature extractors can be added without modifying core execution pipelines.
2. **Immutability & Artifact Safety**: Artifacts (`SampleBatch`, `FeatureArtifact`, `PredictionArtifact`, `MetricsArtifact`, `EvaluationReport`, `ExperimentRun`, `DeploymentArtifact`, `ExecutionSummary`) are implemented as frozen dataclasses to prevent unexpected side effects.
3. **Read-Only Model Operations**: Evaluation and Inference components enforce evaluation mode (`model.net.eval()`) and disable gradient tracking (`torch.no_grad()`), verifying parameter weight checksum immutability.
4. **Passive Observability**: Telemetry collection and logging operate strictly as passive observers, guaranteeing zero mutation of signal data or execution logic.

---

## 🗺 Roadmap & Future Enhancements

- [ ] **TorchScript & ONNX Exporters**: Extend pluggable `ExporterFactory` in the Deployment package to support TorchScript JIT and ONNX runtime formats.
- [ ] **Advanced Model Architectures**: Implement ResNet, DenseNet, and Transformer-based CLDNN (Convolutional LSTM Deep Neural Network) models for RF signal classification.
- [ ] **Real-Time SDR Integration**: Add streaming adapters for GNU Radio and USRP hardware inputs.

---

## 📄 Citation

If you use this framework or repository in your research or project, please cite it as follows:

```bibtex
@software{rf_signal_classification_2026,
  author = {AI Engineering Team},
  title = {RF Signal Classification Framework: Production-Grade Deep Learning for Automatic Modulation Recognition},
  year = {2026},
  version = {1.0.0},
  url = {https://github.com/anujmundu/rf-signal-classification}
}
```

---

## 📜 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🤝 Contact & Acknowledgements

- **Author**: Anuj Mundu ([anujmundu@gmail.com](mailto:anujmundu@gmail.com))
- **Repository**: [github.com/anujmundu/rf-signal-classification](https://github.com/anujmundu/rf-signal-classification)
- **Datasets Acknowledgement**: DeepSig Inc. & RadioML Benchmark Datasets (Timothy O'Shea et al.).
