RIA_Example/README.md

# RIA Hub — Example Files

This repository contains example input files, configurations, and expected outputs for every tool on RIA Hub. If you are new to the platform, start here. Download any file and follow the walkthrough for the tool you want to try.

---

## What is RIA Hub?

RIA Hub is a collaborative platform for RF and machine learning workflows. It combines a Git-based repository system with a suite of specialized tools that cover the full pipeline from raw IQ recordings to live inference deployments:

| Stage | Tools |
|-------|-------|
| **Collect** | Library — browse, organize, and share RF recordings and models |
| **Curate** | Dataset Manager — slice, qualify, augment, and inspect radio datasets |
| **Train** | Model Builder — train, optimize, and compress PyTorch models |
| **Deploy** | Application Packager — compose and build inference applications |
| **Run** | Screens — deploy live RF inference pipelines on real hardware |

---

## Repository Structure

```
RIA_Example/
│
├── recordings/
│   └── example_iq_recording.h5          # Raw IQ capture (input to Curator)
│
├── datasets/
│   ├── example_radio_dataset.h5          # Curated radio dataset (Curator output / Model Trainer input)
│   └── example_synthetic_dataset.h5      # Synthetically generated dataset (Generator output)
│
├── models/
│   ├── example_model.pt                  # PyTorch Module (Model Trainer input / output)
│   └── example_model.onnx               # Exported ONNX model (Screens / Application Packager input)
│
├── applications/
│   └── example_application.json         # Application Composer output (Application Packager)
│
├── screens-apps/
│   └── zone-fingerprinting/
│       ├── manifest.json                 # Screens app manifest
│       ├── zone_fingerprint.onnx         # ONNX model for this app
│       └── zone-fingerprinting.tar.gz    # Packaged app (upload directly to Screens)
│
├── workflows/
│   ├── train.yaml                        # Example Model Trainer workflow (committed to .riahub/workflows/)
│   ├── hpo.yaml                          # Example HPO workflow
│   └── compression.yaml                 # Example Compression workflow
│
└── curator-configs/
    └── example_curator_config.json       # Example curation configuration for the Curator tool
```

---

## Tool Walkthroughs

### Library

The Library is a cross-repository browser for all RF and ML assets on the platform. It automatically discovers files pushed to any repository you have access to.

**To explore the example recording:**
1. Import `recordings/example_iq_recording.h5` into any repository via **New Repository → Upload Files** or by pushing via Git LFS.
2. Navigate to **Library** in the top navigation bar.
3. Select the **Recordings** tab. Your file will appear with metadata and a spectrogram thumbnail.
4. Click the file to open the detail view — you can inspect signal properties, view the spectrogram, and copy the file to another repository.

**Supported asset types in the Library:**

| Type | Extension | Description |
|------|-----------|-------------|
| Recording | `.h5` / `.hdf5` | Raw IQ capture files |
| Radio Dataset | `.h5` / `.hdf5` | Labelled, curated training datasets |
| PyTorch Module | `.pt` / `.pth` | Serialized PyTorch models |
| PyTorch State Dict | `.pt` / `.pth` | Model weight dictionaries |
| PyTorch Checkpoint | `.pt` / `.pth` | Mid-training checkpoints |
| ONNX Graph | `.onnx` | Portable inference models |

---

### Dataset Manager — Curator

The Curator takes raw IQ recordings and produces a labelled, ready-to-train HDF5 dataset. It applies a configurable DSP pipeline: slicing, quality filtering, and optional augmentation.

**Example files:** `recordings/example_iq_recording.h5`, `curator-configs/example_curator_config.json`  
**Expected output:** `datasets/example_radio_dataset.h5`

**Steps:**
1. Upload `example_iq_recording.h5` to a repository (the Curator reads from the Library).
2. Go to **Dataset Manager → Curator**.
3. Select your recording from the Library panel on the left.
4. Configure the pipeline using the settings below, or load `example_curator_config.json` as a reference:
   - **Data type:** `IQ`
   - **Slicer:** `simple` — slice length `1024`
   - **Qualifier:** `rms` — minimum threshold `0.01` (filters out silent/noise-only slices)
   - **Augmentation:** `basic` policy — `2` augmented copies per slice
5. Set a dataset name, description, and radio task label.
6. Click **Curate**. A progress bar tracks the Celery task.
7. When complete, commit the output dataset to your repository.

**Slicer options:**

| Slicer | Best for |
|--------|----------|
| `simple` | Fixed-length slices, good starting point |
| `random` | Randomized slice positions |
| `overlap` | Overlapping slices for smaller datasets |

**Qualifier options:**

| Qualifier | Filters on |
|-----------|-----------|
| `rms` | Root mean square amplitude |
| `snr` | Signal-to-noise ratio estimate |
| `energy` | Total signal energy |
| `bandwidth` | Occupied bandwidth |

---

### Dataset Manager — Inspector

The Inspector runs diagnostic analysis on an existing dataset — class balance, per-class statistics, anomaly detection, and dataset comparisons.

**Example file:** `datasets/example_radio_dataset.h5`

**Steps:**
1. Go to **Dataset Manager → Inspector**.
2. Select `example_radio_dataset.h5` from the file picker.
3. Choose an analysis type:
   - **Balance** — see how many samples exist per class label
   - **Per-Class Stats** — per-class mean, std, and distribution
   - **Anomaly Detection** — flag outlier samples
   - **Compare** — select a second dataset to diff against

---

### Dataset Manager — Generator

The Generator creates synthetic labelled datasets from a parameter sweep without requiring any hardware or recordings.

**Expected output:** `datasets/example_synthetic_dataset.h5`

**Steps:**
1. Go to **Dataset Manager → Generator**.
2. Configure a modulation sweep:
   - **Sampling strategy:** `grid`
   - **Parameters:** SNR from `-5` to `20` dB in steps of `5`; modulation types: `[BPSK, QPSK, 8PSK, 16QAM]`
   - **Signal:** length `1024`, sample rate `1e6`
   - **Channel model:** `awgn`
   - **Output backend:** `pytorch`
3. Click **Generate**. The task runs in the background.
4. Download the resulting `.h5` file when complete.

---

### Model Builder — Model Trainer

The Model Trainer builds a training workflow YAML and commits it to your repository. A Gitea Actions runner then executes the training job.

**Example files:** `datasets/example_radio_dataset.h5`, `models/example_model.pt` (optional pre-trained start)  
**Expected output:** `.riahub/workflows/train.yaml` in your repository, plus a trained `example_model.pt` artifact

**Steps:**
1. Go to **Model Builder → Model Trainer**.
2. In **Repository**, select the repository where you want to store the workflow and output artifacts.
3. In **Model**, choose an architecture (e.g. `ResNet1D`) or use `example_model.pt` as a starting checkpoint.
4. In **Dataset**, select `example_radio_dataset.h5` from the Library.
5. Configure training:
   - **Optimizer:** `Adam`, learning rate `1e-3`
   - **Epochs:** `20`
   - **Batch size:** `64`
   - **Criterion:** `CrossEntropyLoss`
6. Enable **ONNX Export** in the Evaluation section to automatically export the trained model.
7. Click **Commit Workflow**. A `train.yaml` is committed to `.riahub/workflows/` and a CI run starts.
8. Monitor the run in **Actions** within your repository.

The committed workflow file matches `workflows/train.yaml` in this repository.

---

### Model Builder — Hyperparameter Optimization

HPO runs a sweep over a configurable search space, training multiple model variants and ranking them by a target metric.

**Example file:** `datasets/example_radio_dataset.h5`  
**Expected output:** `.riahub/workflows/hpo.yaml`

**Steps:**
1. Go to **Model Builder → HPO**.
2. Configure the same model and dataset as in Model Trainer.
3. In the **Search Space** panel, define ranges to sweep:
   - Learning rate: `1e-4` to `1e-2` (log scale)
   - Optimizer: `[Adam, SGD]`
   - Batch size: `[32, 64, 128]`
4. Set **Trials:** `12` and **Target metric:** `val_accuracy`.
5. Click **Commit Workflow**. See `workflows/hpo.yaml` for the expected output format.

---

### Model Builder — Model Compression

Compression applies pruning and/or quantization to reduce model size for edge deployment. The output is an ONNX file.

**Example files:** `models/example_model.pt`, `datasets/example_radio_dataset.h5`  
**Expected output:** `models/example_model.onnx`

**Steps:**
1. Go to **Model Builder → Compression**.
2. Select `example_model.pt` as the source model and `example_radio_dataset.h5` as the calibration dataset.
3. Configure the compression pipeline (pruning ratio, quantization bits).
4. Click **Commit Workflow**. The Actions job exports the compressed model to ONNX automatically.
5. The resulting `.onnx` file is committed back to your repository.

---

### Application Packager — Application Composer

The Application Composer is a visual node-graph editor for wiring together C++ operator blocks into an inference application. The output is an application JSON file.

**Example file:** `applications/example_application.json`

**Steps:**
1. Go to **Application Packager → Application Composer**.
2. Browse the **Operators** panel on the left. Drag an operator onto the canvas.
3. Wire operator ports together by dragging from an output port to an input port.
4. Configure each operator's parameters in the sidebar.
5. Click **Commit Application** to save `example_application.json` to your repository.
6. Click **Build** to trigger a build workflow on a registered runner.

The application JSON format is documented in `schemas/application/ria_application.schema.json`. See `applications/example_application.json` for a minimal working example.

**Target profiles:**

| Profile | Use when |
|---------|----------|
| `native-x86` | Standard x86 Linux deployment |
| `native-arm64` | ARM edge devices |
| `nvidia-x86` | GPU-accelerated inference on x86 |

---

### Screens

Screens deploys a packaged RF inference application to a live pipeline. You upload a `.tar.gz` app package, configure a data source (live SDR, file playback, or synthetic), and start the pipeline. Results stream back to the browser in real time.

**Example files:** `screens-apps/zone-fingerprinting/zone-fingerprinting.tar.gz`

#### Uploading and running the Zone Fingerprinting demo

The Zone Fingerprinting app classifies RF devices in real time into five device classes (three authorized, two unauthorized) using an ONNX model and a 128-feature IQ preprocessor.

**Steps:**
1. Go to **Screens** and click **New App**.
2. Give it a name (e.g. `Zone Fingerprinting Demo`) and click **Create**.
3. On the app page, click **Upload Package** and upload `zone-fingerprinting.tar.gz`.
4. The app is now configured. To run it with a synthetic signal (no hardware needed):
   - The default `manifest.json` uses `dataSource.type: synthetic` — no changes required.
5. Click **Start**. The inference pipeline starts and begins streaming results.
6. The dashboard shows:
   - Live classification scores per device class
   - Confidence threshold control
   - Spectrogram panel
   - Preprocessor feature monitor
   - Event log

**To run with a real SDR (PlutoSDR):**
1. Ensure your SDR device is connected and detected.
2. Edit the app configuration and change `dataSource.type` to `sdr` with your device identifier.
3. Set `center_frequency`, `sample_rate`, and `gain` to match your signal of interest.
4. Click **Restart**.

#### App package format

A Screens app package is a `.tar.gz` containing:
- `manifest.json` — describes the app (models, GUI layout, data source, preprocessor)
- ONNX model file(s) at the path(s) listed in `manifest.models[].path`

See `screens-apps/zone-fingerprinting/manifest.json` for a complete annotated example. The full manifest schema is at `schemas/screens/app_manifest.schema.json`.

**Data source types:**

| Type | Description |
|------|-------------|
| `synthetic` | Built-in AWGN tone generator — no hardware required |
| `recording` | Play back a `.h5` IQ recording from the Library |
| `sdr` | Live data from a connected SDR device |
| `agent` | Live data from a remote SDR via an edge agent node |
| `numpy_raw` | Play back a `.npy` raw IQ file |

#### ONNX model requirements

The Zone Fingerprinting model contract:
- **Input:** `iq_features` — shape `[1, 128]`, dtype `float32`
- **Output:** `scores` — shape `[1, 5]`, dtype `float32` (softmax probabilities)
- **Opset:** >= 13

When building your own Screens app, export your model to ONNX with matching input/output names and shapes, then reference them in `manifest.json`.

---

### RIA Projects

Projects group your datasets, models, training runs, and deployed applications into a single tracked entity. The project dashboard shows a three-stage pipeline view: Data Management → Model Building → Deployment.

**Steps:**
1. Go to **Projects → New Project**.
2. Name your project and create it.
3. Link assets from the Library using the **Link Asset** button on each pipeline stage.
4. As you run Curator, Model Trainer, and Screens jobs, link the outputs to track progress through the pipeline.

---

## File Format Reference

### HDF5 Radio Dataset (`.h5`)

Curated and generated datasets share a common HDF5 layout:

```
dataset.h5
├── data/           # IQ samples, shape [N, slice_length, 2] (float32)
├── labels/         # Integer class labels, shape [N]
├── metadata/       # Recording metadata carried through from source
└── attrs           # Dataset-level attributes: name, version, radio_task, backend
```

### Screens App Manifest (`manifest.json`)

```json
{
  "name": "My App",
  "version": "1.0.0",
  "description": "Brief description",
  "author": "Your Name",
  "models": [
    {
      "name": "classifier",
      "path": "model.onnx",
      "backend": "onnxrt-cpu"
    }
  ],
  "preprocess": "magnitude_phase_window_stats",
  "dataSource": {
    "type": "synthetic",
    "params": {
      "sample_rate": 1000000,
      "center_frequency": 915000000,
      "buffer_size": 1024
    }
  },
  "components": [
    {
      "component": "BackendInferenceOutput",
      "props": { "modelName": "classifier", "topK": 3 }
    }
  ],
  "config": {
    "confidence_threshold": 0.75
  }
}
```

### Application JSON (`application.json`)

```json
{
  "app_name": "my_inference_app",
  "backend": "native",
  "target_profile": "native-x86",
  "ops": [
    {
      "name": "source",
      "class_name": "UDPSourceOp",
      "type": "source",
      "inputs": [],
      "outputs": [{ "name": "output" }],
      "specs": [
        { "name": "port", "value": "5000", "arg_type": "int" }
      ]
    }
  ],
  "flows": [
    {
      "upstream": "source",
      "downstream": "inference",
      "port_pairs": { "output": "input" }
    }
  ]
}
```

---

## Getting Help

- Full platform documentation is available in the **Docs** section of RIA Hub.
- Open an issue in this repository if an example file is missing, broken, or out of date.
- For tool-specific questions, use the in-app help panels (the `?` icon on each tool page).