docs: add PR template, CI workflow, architecture docs, research log, and module docstrings

.github/pull_request_template.md

@@ -0,0 +1,79 @@
+<!--
+Before submitting, link any related issue in the Description section below
+by writing "Closes #issue_number" so GitHub auto-closes it on merge.
+-->
+
+## Description
+
+<!-- What does this PR do and why? Be specific: what problem does it solve,
+what approach was taken, and what alternatives were considered and ruled out. -->
+
+Closes #
+
+---
+
+## PR Type
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Data contribution (URN database)
+- [ ] Documentation update
+- [ ] Model / algorithm improvement
+- [ ] Performance improvement
+- [ ] Tests
+- [ ] Other (describe below)
+
+---
+
+## Modules Affected
+
+- [ ] Module 1 — Design Input Engine
+- [ ] Module 2 — URN Prediction Core
+- [ ] Module 3 — IMO Compliance Checker
+- [ ] Module 4 — Marine Bioacoustic Impact Module
+- [ ] Module 5 — Mitigation Recommendation Engine
+- [ ] Module 6 — Open URN Database
+- [ ] General / Infrastructure
+
+---
+
+## Scientific Basis
+
+<!-- Required if this PR changes any prediction algorithm, bioacoustic
+calculation, compliance logic, or data processing pipeline.
+Provide either a citation to a published paper or a clear technical
+explanation of the methodology. If this PR does not touch any of the
+above, write N/A. -->
+
+**N/A**
+
+---
+
+## Testing
+
+<!-- Describe what tests were run, what the results were, and whether any
+edge cases were covered. Paste the relevant pytest output below. -->
+```
+# pytest output here
+```
+
+---
+
+## Screenshots / Output
+
+<!-- For UI changes or visualization updates: paste a screenshot.
+For model or algorithm changes: paste a before/after metric comparison.
+For data contributions: paste a sample row showing the expected data format.
+Not applicable for documentation-only PRs. -->
+
+---
+
+## Pre-Merge Checklist
+
+- [ ] Code follows PEP 8 and all new functions include type hints
+- [ ] All new functions have docstrings (Google-style)
+- [ ] `pytest` passes locally with no new failures
+- [ ] No raw data files, `.pt` model weights, or `.env` files are included
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` with a summary of changes
+- [ ] If any module algorithm or methodology was changed, a scientific reference
+      or technical justification is provided in the Scientific Basis section above

.github/workflows/tests.yml

@@ -0,0 +1,67 @@
+# SONARIS Test Suite
+# Runs on every push to any branch and every PR targeting main.
+
+name: SONARIS Test Suite
+
+on:
+  push:
+    branches: ["**"]          # Catch all branches, not just main
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Run pytest
+    runs-on: ubuntu-latest
+
+    steps:
+      # Step 1: Pull the full repository into the runner
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Step 2: Set up Python 3.11.
+      # Local development uses 3.14 on Windows, but 3.11 has stable wheel
+      # support on Ubuntu CI runners. All SONARIS dependencies install cleanly
+      # on 3.11 without C++ compiler errors.
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # Step 3: Cache pip's download cache so repeated runs don't re-download
+      # packages. Cache key includes the OS and the hash of requirements.txt
+      # so the cache invalidates automatically when dependencies change.
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      # Step 4: Install all project dependencies from requirements.txt.
+      # Upgrade pip first to avoid resolver warnings on older bundled versions.
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest pytest-cov
+
+      # Step 5: Run pytest.
+      # --tb=short keeps failure output readable without being verbose.
+      # --cov generates a coverage report for the modules/ package.
+      # The || true at the end ensures the step exits 0 even when no test
+      # files are found, so the CI badge stays green during early development.
+      - name: Run tests
+        run: |
+          pytest tests/ -v --tb=short --cov=modules --cov-report=xml \
+            || ([ $? -eq 5 ] && echo "No tests collected, exiting cleanly." && exit 0)
+
+      # Step 6: Upload the XML coverage report as a workflow artifact so it
+      # can be retrieved and fed into a coverage service (e.g. Codecov) later.
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml
+          if-no-files-found: ignore   # Don't fail if no coverage file was generated

docs/architecture.md

@@ -1,217 +1,363 @@
-# SONARIS Project Architecture
+# SONARIS System Architecture
 
-**Full Name:** Ship-Ocean Noise Acoustic Radiated Intelligence System  
-**License:** MIT  
-**Python:** 3.10+
+This document describes the technical structure of the SONARIS codebase, the
+purpose of every file in the repository, the data flow between modules, and
+the design decisions made during Phase 0 setup. It serves as the primary
+reference for contributors onboarding to the project and will be cited in the
+SONARIS research paper as the system architecture reference.
 
-This document describes the complete folder structure of the SONARIS repository and the intended contents of every file.
+The six core modules form a linear processing pipeline: user-supplied vessel
+parameters enter Module 1 and are progressively transformed into an acoustic
+spectrum (Module 2), a compliance verdict (Module 3), a biological impact score
+(Module 4), and a set of mitigation recommendations (Module 5). Every record
+produced or consumed by this pipeline can optionally be written to or read from
+the Open URN Database (Module 6). No module performs computation before the
+previous module's output is available, which keeps the data contract between
+modules explicit and testable.
 
 ---
 
-## Folder Tree
-
+## Repository Tree
 ```
-sonaris/
-|
-|-- app.py                          # Streamlit entry point; assembles all module UIs into one application
-|-- requirements.txt                # All Python dependencies, pinned with minimum version constraints
-|-- .env.example                    # Template for environment variables (database path, API keys, debug flags)
-|-- .gitignore                      # Ignores venv, __pycache__, .env, model weights, large data files
-|-- LICENSE                         # MIT License text
-|-- README.md                       # Project overview, architecture summary, setup instructions
-|-- CONTRIBUTING.md                 # Contribution guidelines: code standards, PR process, scientific validation
-|-- CHANGELOG.md                    # Version history and release notes
-|
-|-- docs/
-|   |-- architecture.md             # This file: folder structure and per-file descriptions
-|   |-- methodology.md              # Scientific methodology: FW-H equation, MFCC application, BIS scoring
-|   |-- imo_guidelines.md           # Summary of IMO MEPC.1/Circ.906 Rev.1 (2024) limits used in Module 3
-|   |-- datasets.md                 # Dataset descriptions, download instructions, and citation information
-|   |-- api_reference.md            # Python API reference for headless use of each module
-|   |-- deployment.md               # Instructions for deploying to Hugging Face Spaces and Streamlit Cloud
-|
-|-- sonaris/                        # Main Python package
-|   |-- __init__.py                 # Package init; exposes URNPredictor, ComplianceChecker, BioacousticImpact
-|   |
-|   |-- module1_input/              # Module 1: Design Input Engine
-|   |   |-- __init__.py
-|   |   |-- input_schema.py         # Pydantic models defining and validating all vessel input parameters
-|   |   |-- input_ui.py             # Streamlit UI component for Module 1: form fields, units, help tooltips
-|   |   |-- parameter_utils.py      # Derived parameter calculations (e.g. advance ratio J from RPM and speed)
-|   |   |-- validators.py           # Range checks and cross-parameter validation (e.g. propeller diameter vs draft)
-|   |
-|   |-- module2_urn/                # Module 2: URN Prediction Core
-|   |   |-- __init__.py
-|   |   |-- predictor.py            # Main URNPredictor class: orchestrates physics and AI layers, returns spectrum
-|   |   |-- physics_layer.py        # OpenFOAM run management and libAcoustics FW-H post-processing wrapper
-|   |   |-- ai_layer.py             # Loads trained model, runs inference, returns residual correction to physics output
-|   |   |-- feature_engineering.py  # MFCC extraction, spectral envelope fitting, 1/3-octave band aggregation
-|   |   |-- model_architecture.py   # PyTorch definition of the 1D-CNN + LSTM URN prediction network
-|   |   |-- train.py                # Training script: data loading, loss function, optimizer, checkpoint saving
-|   |   |-- evaluate.py             # Evaluation script: computes per-band MAE, RMSE against held-out test set
-|   |   |-- uncertainty.py          # Monte Carlo dropout for prediction confidence interval estimation
-|   |   |-- spectrum_utils.py       # Conversion utilities: Pa to dB, 1/1-octave to 1/3-octave, frequency array generation
-|   |
-|   |-- module3_compliance/         # Module 3: IMO Compliance Checker
-|   |   |-- __init__.py
-|   |   |-- checker.py              # ComplianceChecker class: loads limits, compares spectrum, returns verdict per band
-|   |   |-- imo_limits.py           # Hard-coded URN limits from MEPC.1/Circ.906 Rev.1 by vessel type and frequency band
-|   |   |-- report_generator.py     # Builds the downloadable PDF compliance report using ReportLab
-|   |   |-- compliance_ui.py        # Streamlit UI component: compliance bar chart, pass/fail table, download button
-|   |
-|   |-- module4_bioacoustics/       # Module 4: Marine Bioacoustic Impact Module
-|   |   |-- __init__.py
-|   |   |-- impact_scorer.py        # BioacousticImpact class: computes BIS per species group from input spectrum
-|   |   |-- audiograms.py           # Digitized hearing sensitivity curves for all 5 functional hearing groups
-|   |   |-- masking_model.py        # Psychoacoustic masking model: excitation patterns, masking threshold calculation
-|   |   |-- harmonic_overlap.py     # Finds ship tonal peaks within +/- 1/3 octave of published species call frequencies
-|   |   |-- species_calls.py        # Published frequency ranges for vocalizations of each target species group
-|   |   |-- bis_scoring.py          # BIS formula: integrates masked proportion of species frequency range (0-100 scale)
-|   |   |-- bioacoustics_ui.py      # Streamlit UI: spectrogram overlay, BIS gauges, species selection panel
-|   |
-|   |-- module5_mitigation/         # Module 5: Mitigation Recommendation Engine
-|   |   |-- __init__.py
-|   |   |-- recommender.py          # MitigationRecommender class: takes compliance gaps and BIS, returns ranked actions
-|   |   |-- speed_optimizer.py      # Predicts URN reduction as a function of speed reduction for given vessel type
-|   |   |-- propeller_advisor.py    # Maps compliance gap magnitude to specific propeller geometry modification targets
-|   |   |-- hull_treatment.py       # Recommends hull panel damping treatments based on dominant tonal frequencies
-|   |   |-- routing_advisor.py      # Generates routing avoidance polygons around marine protected areas and known habitats
-|   |   |-- mitigation_ui.py        # Streamlit UI: ranked recommendation cards with estimated dB reduction per action
-|   |
-|   |-- module6_database/           # Module 6: Open URN Database
-|   |   |-- __init__.py
-|   |   |-- models.py               # SQLAlchemy ORM models: Ship, URNRecord, Submission, UserContribution
-|   |   |-- database.py             # Database engine setup, session factory, connection handling
-|   |   |-- crud.py                 # Create, read, update, delete operations for all database tables
-|   |   |-- submission_pipeline.py  # Validates, normalizes, and ingests community-submitted URN records
-|   |   |-- quality_control.py      # Checks submissions against ShipsEar/QiandaoEar22 baseline distributions
-|   |   |-- search.py               # Query functions: filter by vessel type, speed, frequency band, submission date
-|   |   |-- database_ui.py          # Streamlit UI: search interface, submission form, record detail view
-|   |   |-- migrations/             # Alembic migration scripts directory
-|   |       |-- env.py              # Alembic environment configuration
-|   |       |-- versions/           # Auto-generated migration version files go here
-|   |
-|   |-- shared/                     # Shared utilities used by more than one module
-|       |-- __init__.py
-|       |-- constants.py            # Physical constants, frequency band definitions, species group identifiers
-|       |-- logging_config.py       # Loguru logger configuration applied consistently across all modules
-|       |-- config.py               # Loads and exposes .env and config.yaml settings to all modules
-|       |-- file_utils.py           # Helpers for reading/writing WAV, CSV, JSON, and HDF5 files
-|       |-- plot_utils.py           # Shared Matplotlib/Plotly helper functions for consistent chart styling
-|
-|-- models/                         # Trained model weights and metadata (git-ignored for large files)
-|   |-- urn_predictor_v1.pt         # Saved PyTorch model checkpoint after initial training run
-|   |-- urn_predictor_v1_meta.json  # Training metadata: dataset split, hyperparameters, validation metrics
-|
-|-- data/                           # Local data storage (git-ignored except for structure and seed files)
-|   |-- raw/                        # Raw downloaded datasets, unmodified
-|   |   |-- shipsear/               # ShipsEar dataset audio files and metadata
-|   |   |-- qiandaoear22/           # QiandaoEar22 dataset audio files and metadata
-|   |   |-- audiograms/             # Published audiogram CSVs per species group
-|   |
-|   |-- processed/                  # Preprocessed features ready for model training
-|   |   |-- mfcc_features.h5        # Extracted MFCC feature matrix for all training samples
-|   |   |-- octave_spectra.h5       # 1/3-octave spectra computed from all training audio files
-|   |   |-- labels.csv              # Vessel type labels and metadata for each training sample
-|   |
-|   |-- seed/                       # Small seed data committed to the repository
-|       |-- imo_limits.json         # IMO MEPC.1/Circ.906 Rev.1 limit tables in machine-readable form
-|       |-- species_audiograms.json # Digitized audiogram data for all 5 functional hearing groups
-|       |-- species_calls.json      # Published vocalization frequency ranges per species group
-|
-|-- notebooks/                      # Research and development notebooks
-|   |-- 01_dataset_exploration.ipynb       # Initial exploration of ShipsEar and QiandaoEar22 distributions
-|   |-- 02_feature_engineering.ipynb       # MFCC pipeline development and 1/3-octave band analysis
-|   |-- 03_model_training.ipynb            # URN prediction model training experiments and loss curves
-|   |-- 04_compliance_validation.ipynb     # Verification of compliance checker against known test cases
-|   |-- 05_bioacoustic_analysis.ipynb      # BIS scoring development and masking model calibration
-|   |-- 06_mitigation_experiments.ipynb    # Speed-noise relationship analysis for mitigation module
-|   |-- 07_database_schema_design.ipynb    # URN database schema development and query prototyping
-|
-|-- scripts/                        # Standalone scripts for data preparation and model management
-|   |-- download_shipsear.py        # Downloads ShipsEar dataset from source and places it in data/raw/shipsear/
-|   |-- download_qiandaoear.py      # Downloads QiandaoEar22 dataset and places it in data/raw/qiandaoear22/
-|   |-- preprocess_audio.py         # Runs full audio-to-features pipeline and writes to data/processed/
-|   |-- train_model.py              # CLI wrapper around module2_urn/train.py for scheduled training runs
-|   |-- export_model.py             # Exports trained model to ONNX format for deployment environments
-|   |-- init_database.py            # Creates database schema and loads seed data on first setup
-|   |-- seed_database.py            # Populates URN database with curated example records for demonstration
-|
-|-- tests/                          # Test suite
-|   |-- __init__.py
-|   |-- conftest.py                 # Shared pytest fixtures: sample vessel parameters, synthetic spectra, db session
-|   |
-|   |-- test_module1/
-|   |   |-- test_input_schema.py    # Tests that valid and invalid vessel parameter inputs are handled correctly
-|   |   |-- test_validators.py      # Tests for all cross-parameter validation rules
-|   |
-|   |-- test_module2/
-|   |   |-- test_feature_engineering.py   # Tests MFCC output shape, 1/3-octave band count, and numerical stability
-|   |   |-- test_model_architecture.py    # Tests model forward pass shape and output range
-|   |   |-- test_spectrum_utils.py        # Tests dB conversion, band aggregation, and frequency array generation
-|   |
-|   |-- test_module3/
-|   |   |-- test_checker.py         # Tests compliance verdicts against known pass and fail spectra
-|   |   |-- test_report_generator.py  # Tests PDF generation and checks that required sections are present
-|   |
-|   |-- test_module4/
-|   |   |-- test_masking_model.py   # Tests masking threshold outputs against published psychoacoustic reference values
-|   |   |-- test_bis_scoring.py     # Tests BIS edge cases: zero noise, full masking, single frequency input
-|   |
-|   |-- test_module5/
-|   |   |-- test_recommender.py     # Tests that recommendations are ranked and non-empty for all compliance scenarios
-|   |   |-- test_speed_optimizer.py # Tests speed-to-noise reduction curve against known ship data
-|   |
-|   |-- test_module6/
-|       |-- test_crud.py            # Tests all database read and write operations against an in-memory SQLite instance
-|       |-- test_quality_control.py # Tests rejection of out-of-distribution and malformed URN submissions
-|
-|-- config/
-    |-- config.yaml                 # Default configuration: model paths, database URL, logging level, band definitions
-    |-- logging.yaml                # Loguru handler configuration for file and console output
+SONARIS/
+├── app.py
+├── requirements.txt
+├── README.md
+├── CONTRIBUTING.md
+├── CODE_OF_CONDUCT.md
+├── CHANGELOG.md
+├── .env.example
+├── .gitignore
+├── config/
+│   └── settings.py
+├── data/
+│   ├── raw/
+│   ├── processed/
+│   └── databases/
+├── modules/
+│   ├── __init__.py
+│   ├── input_engine/
+│   │   ├── __init__.py
+│   │   └── design_input.py
+│   ├── urn_prediction/
+│   │   ├── __init__.py
+│   │   ├── physics_layer.py
+│   │   └── ai_layer.py
+│   ├── imo_compliance/
+│   │   ├── __init__.py
+│   │   └── compliance_checker.py
+│   ├── bioacoustic/
+│   │   ├── __init__.py
+│   │   ├── audiogram_data.py
+│   │   └── bis_calculator.py
+│   ├── mitigation/
+│   │   ├── __init__.py
+│   │   └── recommender.py
+│   └── urn_database/
+│       ├── __init__.py
+│       └── db_manager.py
+├── models/
+│   ├── trained/
+│   └── architectures/
+├── notebooks/
+│   └── 01_ShipsEar_EDA.ipynb
+├── tests/
+│   ├── __init__.py
+│   └── test_modules.py
+├── docs/
+│   ├── architecture.md
+│   ├── api_reference.md
+│   └── research_notes.md
+├── ui/
+│   ├── pages/
+│   └── components/
+└── .github/
+    ├── pull_request_template.md
+    ├── workflows/
+    │   └── tests.yml
+    └── ISSUE_TEMPLATE/
+        ├── bug_report.md
+        ├── feature_request.md
+        └── data_contribution.md
 ```
 
 ---
 
-## File Count Summary
-
-| Directory | Files |
-|---|---|
-| Root | 8 |
-| docs/ | 6 |
-| sonaris/ (package) | 52 |
-| models/ | 2 |
-| data/ | 9 |
-| notebooks/ | 7 |
-| scripts/ | 8 |
-| tests/ | 17 |
-| config/ | 2 |
-| **Total** | **111** |
+## Per-File Descriptions
+
+### Root
+
+**app.py:** Entry point for the Streamlit application. Initialises the UI, routes
+user interactions to the appropriate module calls, and renders output visualizations.
+
+**requirements.txt:** Pinned list of all Python dependencies for the project.
+Used by both local development setup and CI.
+
+**README.md:** Public-facing project overview covering installation, usage, module
+descriptions, and contribution instructions.
+
+**CONTRIBUTING.md:** Contribution guide covering branch naming, commit conventions,
+code style requirements, and the PR review process.
+
+**CODE_OF_CONDUCT.md:** Contributor Covenant code of conduct for the SONARIS
+open-source community.
+
+**CHANGELOG.md:** Versioned log of all changes to the project, following Keep a
+Changelog format.
+
+**.env.example:** Template of all required environment variables with placeholder
+values. Actual `.env` file is never committed.
+
+**.gitignore:** Specifies files and directories excluded from version control,
+including `.env`, trained model weights, raw datasets, and Python cache files.
+
+### config/
+
+**settings.py:** Central configuration for the application: database paths, model
+paths, default operational parameters, and environment variable loading.
+
+### data/
+
+**raw/:** Storage directory for unprocessed source datasets (ShipsEar,
+QiandaoEar22). Not committed to version control.
+
+**processed/:** Storage directory for cleaned and feature-extracted datasets
+ready for model training or evaluation.
+
+**databases/:** Storage directory for the SQLite development database file.
+
+### modules/
+
+**modules/\_\_init\_\_.py:** Top-level package initialiser for the modules namespace.
+Does not execute computation on import.
+
+#### modules/input_engine/
+
+**\_\_init\_\_.py:** Package initialiser for the Design Input Engine module.
+
+**design_input.py:** Validates and structures all user-supplied vessel parameters
+(hull coefficients, propeller geometry, engine type, speed) into a standardised
+`VesselParameters` dataclass passed downstream.
+
+#### modules/urn_prediction/
+
+**\_\_init\_\_.py:** Package initialiser for the URN Prediction Core module.
+
+**physics_layer.py:** Interfaces with OpenFOAM and libAcoustics to run
+propeller cavitation simulations and extract the physics-based component of the
+noise spectrum.
+
+**ai_layer.py:** Loads the trained PyTorch neural network, runs inference on
+the structured vessel parameters, and returns a predicted 1/3-octave band
+spectrum in dB re 1 μPa at 1 m.
+
+#### modules/imo_compliance/
+
+**\_\_init\_\_.py:** Package initialiser for the IMO Compliance Checker module.
+
+**compliance_checker.py:** Compares the predicted URN spectrum against the
+vessel-type-specific limit tables from IMO MEPC.1/Circ.906 Rev.1 (2024) and
+returns a structured `ComplianceResult` with per-band pass/fail flags.
+
+#### modules/bioacoustic/
+
+**\_\_init\_\_.py:** Package initialiser for the Marine Bioacoustic Impact Module.
+
+**audiogram_data.py:** Contains the published audiogram sensitivity curves for
+five marine mammal functional hearing groups: low-frequency cetaceans, mid-frequency
+cetaceans, high-frequency cetaceans, phocid pinnipeds in water, and otariid pinnipeds
+in water.
+
+**bis_calculator.py:** Applies MFCC decomposition and spectral masking analysis
+to quantify the overlap between the ship noise spectrum and each species group's
+hearing sensitivity range, producing a Biological Interference Score per group.
+
+#### modules/mitigation/
+
+**\_\_init\_\_.py:** Package initialiser for the Mitigation Recommendation Engine.
+
+**recommender.py:** Receives upstream outputs (URN spectrum, compliance result,
+BIS scores) and generates ranked mitigation recommendations with estimated noise
+reduction in dB for each option.
+
+#### modules/urn_database/
+
+**\_\_init\_\_.py:** Package initialiser for the Open URN Database module.
+
+**db_manager.py:** Handles all database operations: schema initialisation, record
+insertion, querying by vessel type or frequency band, and export to JSON or CSV.
+
+### models/
+
+**trained/:** Storage directory for serialised trained model weights (`.pt` files).
+Not committed to version control.
+
+**architectures/:** Python files defining the PyTorch neural network architectures
+used in Module 2.
+
+### notebooks/
+
+**01_ShipsEar_EDA.ipynb:** Exploratory data analysis notebook for the ShipsEar
+dataset. Covers class distribution, spectrogram inspection, signal-to-noise
+assessment, and feature extraction prototyping.
+
+### tests/
+
+**tests/\_\_init\_\_.py:** Makes the tests directory a Python package.
+
+**test_modules.py:** pytest test suite covering unit tests for all six modules.
+Integration tests covering the full pipeline are added here as modules mature.
+
+### docs/
+
+**architecture.md:** This file. Technical reference for the repository structure,
+data flow, module interfaces, and design decisions.
+
+**api_reference.md:** Auto-generated or manually maintained documentation of all
+public functions and classes across the six modules.
+
+**research_notes.md:** Running scientific journal for the project. Logs dataset
+assessments, methodology decisions, and literature references that feed into the
+eventual SONARIS research paper.
+
+### ui/
+
+**pages/:** Streamlit multi-page app files, one per major UI view.
+
+**components/:** Reusable Streamlit UI components shared across pages.
+
+### .github/
+
+**pull_request_template.md:** Template automatically loaded when a contributor
+opens a pull request, including the pre-merge checklist and scientific basis
+section.
+
+**workflows/tests.yml:** GitHub Actions workflow that runs the pytest test suite
+on every push and every pull request targeting main.
+
+**ISSUE_TEMPLATE/bug_report.md:** Structured template for reporting bugs.
+
+**ISSUE_TEMPLATE/feature_request.md:** Structured template for proposing new
+features.
+
+**ISSUE_TEMPLATE/data_contribution.md:** Structured template for contributing
+URN measurement records to the Open URN Database.
+
+---
+
+## Data Flow
+
+1. The user supplies vessel parameters through the Streamlit UI or directly via
+   the Python API. Inputs include hull form coefficients (Cb, Cp, L/B ratio),
+   propeller geometry (blade count, pitch ratio, diameter), engine type, rated
+   RPM, and operational speed in knots.
+
+2. **Module 1 (Design Input Engine)** validates all inputs, applies physical
+   plausibility checks, and packages them into a `VesselParameters` dataclass.
+   This object is the sole input passed to Module 2.
+
+3. **Module 2 (URN Prediction Core)** receives the `VesselParameters` object.
+   The physics layer optionally runs an OpenFOAM simulation to produce a
+   physics-derived partial spectrum. The AI layer runs the trained PyTorch
+   model to produce a data-driven full spectrum. The two layers are fused into
+   a single `URNSpectrum` object: a dict mapping each 1/3-octave band center
+   frequency (Hz) to a level in dB re 1 μPa at 1 m.
+
+4. **Module 3 (IMO Compliance Checker)** receives the `URNSpectrum` and the
+   vessel type string from `VesselParameters`. It returns a `ComplianceResult`
+   object containing a per-band pass/fail dict, an overall compliance flag, and
+   the reference limit values used for comparison.
+
+5. **Module 4 (Marine Bioacoustic Impact Module)** receives the `URNSpectrum`.
+   It applies MFCC decomposition across the spectrum and computes spectral overlap
+   against each of the five audiogram curves. It returns a `BISResult` object:
+   a dict mapping each marine mammal group name to its Biological Interference
+   Score (0 to 100) and the frequency bands driving the interference.
+
+6. **Module 5 (Mitigation Recommendation Engine)** receives the `URNSpectrum`,
+   the `ComplianceResult`, and the `BISResult`. It returns a ranked list of
+   `MitigationRecommendation` objects, each containing a description, the
+   expected noise reduction in dB, and the applicable species groups or
+   frequency bands.
+
+7. All outputs can optionally be written to **Module 6 (Open URN Database)** as
+   a structured record containing vessel metadata, measurement conditions, and
+   the full `URNSpectrum`. Records are also queryable from the database to
+   populate the community dataset.
 
 ---
 
-## Module to Directory Mapping
+## Module Interfaces
+
+**Module 1: Design Input Engine**
+Input: Raw user-supplied values via form or dict. Hull coefficients, propeller
+geometry, engine type, RPM, speed in knots.
+Output: `VesselParameters` dataclass with validated and typed fields.
+Key dependencies: `pydantic` or `dataclasses`, `scipy` for range validation.
+
+**Module 2: URN Prediction Core**
+Input: `VesselParameters` dataclass.
+Output: `URNSpectrum` — dict mapping 1/3-octave band center frequencies (Hz)
+to levels in dB re 1 μPa at 1 m, covering 20 Hz to 20 kHz.
+Key dependencies: `torch`, `numpy`, `scipy`, OpenFOAM CLI (optional physics layer).
+
+**Module 3: IMO Compliance Checker**
+Input: `URNSpectrum`, vessel type string.
+Output: `ComplianceResult` — overall pass/fail flag, per-band results, limit
+values from IMO MEPC.1/Circ.906 Rev.1 (2024).
+Key dependencies: Internal lookup tables encoding IMO limit values by vessel type.
+
+**Module 4: Marine Bioacoustic Impact Module**
+Input: `URNSpectrum`.
+Output: `BISResult` — per-species-group Biological Interference Score and
+contributing frequency band list. Spectrogram overlay data for visualization.
+Key dependencies: `librosa`, `scipy.signal`, `numpy`, `matplotlib`.
+
+**Module 5: Mitigation Recommendation Engine**
+Input: `URNSpectrum`, `ComplianceResult`, `BISResult`.
+Output: List of `MitigationRecommendation` objects ranked by expected dB
+reduction.
+Key dependencies: Internal rule engine and lookup tables. No external ML.
 
-| Module | Directory |
-|---|---|
-| Module 1: Design Input Engine | `sonaris/module1_input/` |
-| Module 2: URN Prediction Core | `sonaris/module2_urn/` |
-| Module 3: IMO Compliance Checker | `sonaris/module3_compliance/` |
-| Module 4: Marine Bioacoustic Impact | `sonaris/module4_bioacoustics/` |
-| Module 5: Mitigation Recommendation Engine | `sonaris/module5_mitigation/` |
-| Module 6: Open URN Database | `sonaris/module6_database/` |
-| Shared Utilities | `sonaris/shared/` |
+**Module 6: Open URN Database**
+Input (write): Vessel metadata dict + `URNSpectrum` + measurement conditions dict.
+Input (read): Query parameters (vessel type, IMO number, frequency range, date range).
+Output (read): List of matching database records as dicts or Pandas DataFrames.
+Key dependencies: `sqlite3` (development), `psycopg2` (production), `pandas`.
 
 ---
 
-## Key Design Decisions
+## Design Decisions
 
-**Single package, modular internals.** All six modules live inside the `sonaris/` package. This means the Python API (`from sonaris import URNPredictor`) works without any knowledge of the internal module structure, while the internals remain cleanly separated.
+**1. mSOUND removed from pip, manual source integration planned for Phase 3.**
+mSOUND is not available as a pip-installable package compatible with the project's
+Python environment. Rather than vendor an untested integration in Phase 0, the
+physics simulation layer is scoped to OpenFOAM plus libAcoustics for Phases 1 and 2.
+mSOUND will be integrated manually from source in Phase 3 once the core pipeline
+is stable.
 
-**Seed data is version-controlled; raw audio is not.** The `data/seed/` directory (IMO limits, audiograms, species call ranges) is committed to the repository so the tool works out of the box. Raw audio datasets are large and externally hosted; the download scripts in `scripts/` handle retrieval.
+**2. pyaudio and spectrum removed due to Python 3.14 wheel unavailability.**
+Neither `pyaudio` nor `spectrum` publish binary wheels for Python 3.14 on Windows
+as of Phase 0. Both would require a local C++ build toolchain. All audio processing
+and spectral estimation needed for the MFCC pipeline is available through `librosa`
+and `scipy.signal`, which do provide 3.14-compatible wheels. The two packages were
+removed from `requirements.txt` with no loss of required functionality.
 
-**Model weights are not committed.** Trained `.pt` files live in `models/` which is git-ignored. The `scripts/train_model.py` script reproduces them from the processed dataset. A pre-trained checkpoint will be hosted separately on Hugging Face Hub.
+**3. MFCC pipeline uses librosa and scipy only.**
+The bioacoustic masking and MFCC analysis in Module 4 are implemented entirely
+with `librosa` for feature extraction and `scipy.signal` for spectral processing.
+This keeps the dependency count low, avoids binary-only packages, and gives full
+access to the intermediate signal representations needed for the BIS calculation.
 
-**Migrations directory is tracked.** The `sonaris/module6_database/migrations/` directory and its `env.py` are committed. Individual migration version files are generated by Alembic as the schema evolves and should also be committed.
+**4. CI uses Python 3.11 while local development uses Python 3.14.**
+GitHub Actions Ubuntu runners have stable binary wheel availability for all SONARIS
+dependencies on Python 3.11. Python 3.14 is used locally on Windows because it is
+the active development environment, but forcing 3.14 in CI would require compiling
+several packages from source and would make CI fragile. The API surface used by
+SONARIS does not differ between 3.11 and 3.14 for any dependency in scope.
 
-**One UI file per module.** Each module has a `_ui.py` file that defines its Streamlit component as a callable function. `app.py` imports and assembles these into a single multi-page application. This keeps UI logic out of the scientific core.
+**5. SQLite used for development, PostgreSQL targeted for production.**
+SQLite requires no server process and works identically across all developer
+machines. The `db_manager.py` abstraction layer uses SQLAlchemy-compatible
+connection strings so that switching to PostgreSQL in production requires changing
+one configuration value, not the query logic.

docs/research_notes.md

@@ -0,0 +1,130 @@
+# SONARIS Research Notes
+
+This file is a running scientific journal for the SONARIS project. Every
+significant research finding, dataset assessment, methodology decision, and
+literature reference is logged here during development. Entries feed directly
+into the methodology and literature review sections of the SONARIS research paper.
+
+**Usage rules:**
+- New entries go at the top of the file, below this header.
+- Each entry must carry a date in ISO format (YYYY-MM-DD).
+- If an entry is based on published literature, include the full reference at the
+  bottom of that entry.
+- Write for a technical reader who is encountering this topic for the first time
+  in this project's context.
+
+---
+
+## 2026-03-03 — IMO MEPC.1/Circ.906 Rev.1 (2024): Regulatory Gap and Project Motivation
+
+### What the guidelines require
+
+IMO MEPC.1/Circ.906 Rev.1 (2024) is the current iteration of the IMO's voluntary
+guidelines for the reduction of underwater noise from commercial shipping. The
+circular applies to all new-build vessels and requests that shipowners and operators
+monitor, manage, and where practicable reduce underwater radiated noise (URN) across
+the ship's operational speed range. The guidelines specify that URN should be
+characterized using 1/3-octave band measurements and reported in dB re 1 μPa at 1 m,
+covering the frequency range relevant to marine mammal hearing (approximately 10 Hz
+to 20 kHz depending on species). Vessels are categorised by type (bulk carrier,
+container ship, tanker, passenger vessel, and others), and the guidelines provide
+recommended management practices for each category. Crucially, the 2024 revision
+sharpened the language from the 2014 original: shipyards and operators are now
+explicitly encouraged to apply URN prediction tools at the design stage, not only
+during sea trials.
+
+### The gap: no open-source design-phase tool exists
+
+The IMO GloNoise Partnership Programme conducted a structured gap analysis in October
+2025. Its finding was direct: while IMO mandates URN management and design-stage
+assessment, no open-source prediction or compliance-checking tool exists for
+shipyards and researchers to use during the design phase. The only tools capable
+of performing full-spectrum URN prediction (dBSea, ANSYS Fluent with acoustic
+modules, GL ShipNoise) are commercial, proprietary, and priced out of reach for
+most of the world's shipyards. A small shipyard in Southeast Asia, a research
+institution in West Africa, or a student designing a vessel for a class project
+cannot access these tools. This is not a niche gap: the IMO GloNoise report
+notes that the majority of the global shipbuilding output by vessel count comes
+from yards in developing economies where no licensed acoustic software is in use.
+
+The consequence of this gap is that URN compliance is assessed, when it is assessed
+at all, only at the sea trial stage. By that point the hull form is fixed, the
+propeller is installed, and the engine mounts are set. Retrofitting for noise
+reduction at sea trial is expensive and typically limited to operational adjustments
+(speed reduction, routing) rather than design-level changes. The entire value of
+design-stage prediction is lost.
+
+### The frequency bands that matter
+
+The IMO guidelines and the underlying marine bioacoustics literature converge on
+three frequency bands of primary concern:
+
+**Low frequency: 10 Hz to 1000 Hz.** This is the primary hearing range of baleen
+whales (mysticetes), including blue, fin, sei, minke, and humpback whales.
+Commercial shipping noise is dominated in this band by engine tonal components,
+propeller shaft harmonics, and hull flow noise. The overlap is severe: fin whale
+20 Hz calls sit directly in the band occupied by machinery noise from large
+slow-speed diesel engines. This band is the primary driver of the chronic acoustic
+masking problem for large whales in shipping lanes.
+
+**Mid frequency: 1 kHz to 10 kHz.** This is the primary communication and
+echolocation range of dolphins, porpoises, and toothed whales (odontocetes).
+Propeller cavitation noise, which typically peaks between 1 kHz and 5 kHz
+depending on ship speed and propeller design, falls directly in this band.
+Bottlenose dolphin signature whistles, which are critical for individual
+identification and group cohesion, occupy 3 kHz to 20 kHz. The interference
+in this band is intermittent (tied to cavitation onset at specific speeds) but
+acoustically intense.
+
+**The blade-pass overlap zone: 50 Hz to 500 Hz.** The propeller blade-pass
+frequency (BPF) is calculated as RPM/60 × blade count. For a typical
+large commercial vessel running at 100 RPM with a 5-blade propeller, BPF is
+approximately 8.3 Hz, with harmonics at 16.6 Hz, 25 Hz, and so on. At higher
+shaft speeds typical of medium vessels, these harmonics fall squarely in the
+50 Hz to 500 Hz range where both baleen whale low-frequency calls and toothed
+whale social calls are concentrated. This harmonic overlap is what makes the
+SONARIS Module 4 BIS calculation non-trivial: it is not sufficient to compare
+broadband levels. Tonal interference at specific harmonics must be resolved.
+This is precisely where the audio-engineering concept of spectral masking, as
+used in perceptual audio codecs and MFCC-based speech analysis, applies directly
+to the bioacoustic problem.
+
+### Industry confirmation of demand
+
+In October 2024, BIMCO (Baltic and International Maritime Council) and ICS
+(International Chamber of Shipping), the two largest shipping industry bodies by
+member tonnage, published a joint URN Management Guide. The guide explicitly
+recommends that all member operators implement URN monitoring and compliance
+workflows and calls on the industry to develop accessible tools for design-stage
+prediction. This is the clearest statement from industry itself that demand for
+a tool like SONARIS exists and that the current commercial tool landscape does not
+meet it.
+
+### Connection to SONARIS modules
+
+Module 2 (URN Prediction Core) closes the prediction gap identified by the IMO
+GloNoise analysis by producing a full 1/3-octave band spectrum at design stage
+from vessel geometry and operational parameters alone, without requiring a physical
+prototype or sea trial.
+
+Module 3 (IMO Compliance Checker) closes the compliance assessment gap by
+directly mapping the Module 2 output against the MEPC.1/Circ.906 Rev.1 (2024)
+limit tables and issuing a structured pass/fail report, formatted for inclusion
+in a ship's technical documentation package.
+
+Module 4 (Marine Bioacoustic Impact Module) goes beyond what IMO currently
+requires. The BIS metric provides a species-specific, frequency-resolved measure
+of biological harm that the IMO guidelines acknowledge in principle but do not
+operationalize. This positions SONARIS as a tool not just for compliance but for
+genuine environmental assessment.
+
+### References
+
+- IMO MEPC.1/Circ.906 Rev.1 (2024). *2024 Guidelines for the Reduction of
+  Underwater Noise from Commercial Shipping to Address Adverse Impacts on Marine
+  Life.* International Maritime Organization, London.
+- IMO GloNoise Partnership Programme (October 2025). *Gap Analysis: Underwater
+  Radiated Noise Management Tools for Design-Phase Application.* International
+  Maritime Organization, London.
+- BIMCO and ICS (October 2024). *URN Management Guide for Shipping Operators.*
+  Baltic and International Maritime Council / International Chamber of Shipping.

modules/__init__.py

@@ -0,0 +1,15 @@
+"""
+SONARIS top-level modules package.
+
+This package contains the six core processing modules that form the SONARIS
+pipeline: Design Input Engine, URN Prediction Core, IMO Compliance Checker,
+Marine Bioacoustic Impact Module, Mitigation Recommendation Engine, and Open
+URN Database. Importing this package makes the module namespace available but
+executes no computation. Each sub-module must be imported explicitly by the
+caller.
+
+Libraries: None at this level. Dependencies are declared within each sub-module.
+
+Pipeline position: This is the root of the processing pipeline. Nothing feeds
+into this package; it exposes the six modules to app.py and to the test suite.
+"""

modules/bioacoustic/__init__.py

@@ -0,0 +1,37 @@
+"""
+Module 4: Marine Bioacoustic Impact Module.
+
+Maps the predicted ship noise spectrum against the published audiogram
+sensitivity curves of five marine mammal functional hearing groups and
+quantifies the biological interference caused by the ship at each frequency band.
+The five groups follow the NOAA/NMFS (2018) marine mammal acoustic weighting
+function classification: low-frequency cetaceans (baleen whales), mid-frequency
+cetaceans (dolphins and most toothed whales), high-frequency cetaceans (porpoises
+and some small odontocetes), phocid pinnipeds in water, and otariid pinnipeds in
+water.
+
+The core method borrows two techniques from audio signal processing. First,
+Mel-Frequency Cepstral Coefficient (MFCC) decomposition is applied to the ship
+noise spectrum to extract a perceptually weighted frequency representation aligned
+with the non-linear frequency sensitivity of the mammal ear. Second, spectral
+masking analysis quantifies how much of the ship noise spectrum overlaps with and
+energetically masks the frequency bands where each species group communicates and
+echolocates. The combination of these two analyses produces the Biological
+Interference Score (BIS), a value from 0 to 100 for each species group, where
+100 represents complete masking of the group's functional hearing range. The BIS
+is not a standardised regulatory metric; it is a SONARIS-defined index intended
+to rank relative biological harm across design alternatives and routing scenarios.
+
+Libraries: ``librosa`` for MFCC extraction, ``scipy.signal`` for spectral
+masking computation, ``numpy``, ``matplotlib`` and ``plotly`` for spectrogram
+overlay visualization.
+
+Pipeline position: Fourth stage, running in parallel with Module 3. Receives
+``URNSpectrum`` from Module 2. Outputs a ``BISResult`` object consumed by
+Module 5.
+"""
+
+from modules.bioacoustic.audiogram_data import AUDIOGRAM_CURVES
+from modules.bioacoustic.bis_calculator import calculate_bis, BISResult
+
+__all__ = ["AUDIOGRAM_CURVES", "calculate_bis", "BISResult"]

modules/imo_compliance/__init__.py

@@ -0,0 +1,28 @@
+"""
+Module 3: IMO Compliance Checker.
+
+Receives the predicted URN spectrum from Module 2 and the vessel type string
+from the ``VesselParameters`` object produced by Module 1. Checks each 1/3-octave
+band level against the vessel-type-specific limit values defined in IMO
+MEPC.1/Circ.906 Rev.1 (2024) and returns a structured compliance result. The
+result includes a per-band pass/fail flag, the limit value applied at each band,
+the measured (predicted) level, and the exceedance in dB where a band fails.
+An overall compliance flag aggregates the per-band results. The module can also
+generate a formatted compliance report suitable for inclusion in a vessel's
+technical documentation package.
+
+The limit tables are encoded directly in this module as Python dicts keyed by
+vessel type and center frequency. When IMO updates its guidelines, these tables
+are the only code that requires updating.
+
+Libraries: Internal lookup tables only. ``fpdf2`` or ``reportlab`` for PDF
+report generation (added in Phase 2).
+
+Pipeline position: Third stage. Receives ``URNSpectrum`` from Module 2 and
+vessel type from Module 1. Outputs a ``ComplianceResult`` object consumed by
+Module 5 and optionally written to Module 6.
+"""
+
+from modules.imo_compliance.compliance_checker import check_compliance, ComplianceResult
+
+__all__ = ["check_compliance", "ComplianceResult"]

modules/input_engine/__init__.py

@@ -0,0 +1,26 @@
+"""
+Module 1: Design Input Engine.
+
+Accepts all user-supplied vessel parameters required for URN prediction and
+validates them against physical plausibility bounds before passing them
+downstream. Inputs include hull form coefficients (block coefficient Cb,
+prismatic coefficient Cp, length-to-beam ratio L/B), propeller geometry (blade
+count, pitch ratio P/D, diameter in meters), engine type (slow-speed diesel,
+medium-speed diesel, gas turbine), rated shaft RPM, and operational speed in
+knots. All inputs are validated and packaged into a ``VesselParameters``
+dataclass. If any input falls outside physically meaningful bounds, this module
+raises a descriptive ``ValidationError`` before any computation reaches Module 2.
+No acoustic prediction logic lives here; the sole responsibility of this module
+is input integrity.
+
+Libraries: ``dataclasses`` (stdlib), ``typing`` (stdlib). Optional use of
+``pydantic`` for schema validation if added in a later phase.
+
+Pipeline position: First stage. Receives raw user input from the Streamlit UI
+or from a direct Python API call. Outputs a ``VesselParameters`` object consumed
+by the URN Prediction Core (Module 2).
+"""
+
+from modules.input_engine.design_input import VesselParameters, validate_inputs
+
+__all__ = ["VesselParameters", "validate_inputs"]

modules/mitigation/__init__.py

@@ -0,0 +1,34 @@
+"""
+Module 5: Mitigation Recommendation Engine.
+
+Generates ranked mitigation recommendations based on the upstream outputs of
+Modules 2, 3, and 4. Each recommendation addresses either a compliance failure
+identified by Module 3 or a high Biological Interference Score identified by
+Module 4, or both. Recommendations span two categories: operational (speed
+reduction targets expressed in knots and the corresponding predicted dB
+reduction, geographic routing avoidance zones keyed to known cetacean habitat
+polygons) and design-level (hull coating options with published noise reduction
+coefficients, propeller geometry modifications including skew angle adjustments
+and blade count changes with expected BPF harmonic shifts). Each recommendation
+is returned as a ``MitigationRecommendation`` object carrying a description,
+the expected noise reduction in dB across affected frequency bands, the
+species groups that benefit, and a confidence level based on how well the
+recommendation type is supported by the available literature.
+
+Recommendations are ranked by total expected noise reduction weighted by the
+BIS scores of the affected species groups, so recommendations that reduce noise
+in the most biologically sensitive frequency bands rank above those that reduce
+broadband levels without addressing critical masking zones.
+
+Libraries: ``numpy`` for ranking arithmetic. No external ML dependencies; the
+recommendation logic is a rule-based system operating on structured inputs.
+
+Pipeline position: Fifth and final computation stage. Receives ``URNSpectrum``
+from Module 2, ``ComplianceResult`` from Module 3, and ``BISResult`` from
+Module 4. Outputs a ranked list of ``MitigationRecommendation`` objects
+rendered by the Streamlit UI and optionally stored in Module 6.
+"""
+
+from modules.mitigation.recommender import generate_recommendations, MitigationRecommendation
+
+__all__ = ["generate_recommendations", "MitigationRecommendation"]

modules/urn_database/__init__.py

@@ -0,0 +1,34 @@
+"""
+Module 6: Open URN Database.
+
+Manages the Open URN Database, the first open-source community-contributed
+database of ship underwater radiated noise signatures. Each record stores vessel
+metadata (IMO number, vessel type, length overall, beam, draft, propeller blade
+count, engine type), measurement or prediction conditions (ship speed, loading
+condition, water depth, measurement method), and the full 1/3-octave band
+spectrum from 20 Hz to 20 kHz in dB re 1 μPa at 1 m. Records contributed by
+the community are flagged with a provenance field indicating whether the spectrum
+was measured at sea trial, predicted by SONARIS, or sourced from a published
+dataset.
+
+The development database is SQLite, stored locally under ``data/databases/``.
+The production database targets PostgreSQL. The abstraction layer in
+``db_manager.py`` uses connection strings compatible with both backends so that
+the transition requires a single configuration change. All write operations
+include input validation to enforce the schema before insertion. Query operations
+support filtering by vessel type, IMO number, frequency band range, and date of
+contribution, and return results as either Python dicts or Pandas DataFrames
+depending on the caller's request.
+
+Libraries: ``sqlite3`` (stdlib) for development, ``psycopg2`` for production,
+``sqlalchemy`` for the abstraction layer, ``pandas`` for DataFrame output.
+
+Pipeline position: Optional terminal stage that runs alongside or after Module 5.
+Receives any combination of ``VesselParameters``, ``URNSpectrum``,
+``ComplianceResult``, and ``BISResult`` objects for storage. Also serves as an
+input source when Module 2 queries historical records for training data augmentation.
+"""
+
+from modules.urn_database.db_manager import DatabaseManager
+
+__all__ = ["DatabaseManager"]

modules/urn_prediction/__init__.py

@@ -0,0 +1,29 @@
+"""
+Module 2: URN Prediction Core.
+
+Predicts a ship's underwater radiated noise spectrum from the vessel parameters
+produced by Module 1. The prediction is hybrid: a physics layer and an AI layer
+run in sequence, and their outputs are fused into a single spectrum.
+
+The physics layer interfaces with OpenFOAM and libAcoustics to simulate propeller
+cavitation and hull-induced turbulence noise. This layer is computationally
+intensive and optional during development; it can be bypassed to run the AI layer
+alone. The AI layer is a deep neural network implemented in PyTorch, trained on
+the ShipsEar dataset (Santos-Dominguez et al., 2016) and the QiandaoEar22 dataset.
+The network takes the structured ``VesselParameters`` object as input features
+and returns a predicted noise level for each 1/3-octave band from 20 Hz to 20 kHz.
+Output levels are in dB re 1 μPa at 1 m, the standard reference for underwater
+source levels used in IMO MEPC.1/Circ.906 Rev.1 (2024).
+
+Libraries: ``torch``, ``numpy``, ``scipy.signal``. OpenFOAM is invoked as a
+subprocess via the physics layer; it is not a Python dependency.
+
+Pipeline position: Second stage. Receives ``VesselParameters`` from Module 1.
+Outputs a ``URNSpectrum`` object (a dict mapping Hz to dB re 1 μPa at 1 m)
+consumed by Module 3 and Module 4.
+"""
+
+from modules.urn_prediction.physics_layer import run_physics_prediction
+from modules.urn_prediction.ai_layer import run_ai_prediction, fuse_spectra
+
+__all__ = ["run_physics_prediction", "run_ai_prediction", "fuse_spectra"]