# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Radiacode 103 is a gamma-ray spectrometer isotope identification pipeline. It captures spectra from a Radiacode 103 USB detector, subtracts background radiation, and identifies isotopes using a CNN-FCNN multi-task PyTorch model (VegaModel, 34.5M params, 82 isotopes). The project runs as Docker containers orchestrated by docker-compose.

## Architecture

Three Docker containers, each with its own Dockerfile:

- **train/** — Generates 50k synthetic spectra and trains VegaModel on GPU. Entrypoint runs generation then training sequentially. Code lives in `train/vega_ml/` (synthetic_spectra, training/vega).
- **detect/** — Production monitor. Connects to Radiacode 103 via USB, samples every 60s, accumulates spectrum, subtracts background, runs inference, writes JSON state and daily reports. Two scripts: `radiacode_monitor.py` (main loop) and `capture_background.py` (24h background capture).
- **web/** — FastAPI dashboard on port 8080. Serves a single-page HTML/JS frontend with tabs for spectrum, background, CPS timeline, and history. Reads monitor state from JSON files written by the detect container.

Data flow: `detect` writes `monitor_state.json` + `cps_log.jsonl` + daily reports to `/data/` and `/logs/` → `web` reads them (read-only volume mounts). The `train` container reads/writes `/data/synthetic/` and `/models/`.

### Web API Routes

- `/api/status` — monitor status (connected, CPS, staleness)
- `/api/spectrum/current` — accumulated spectrum (1023 channels, overflow channel excluded)
- `/api/spectrum/difference` — background-subtracted spectrum
- `/api/background`, `/api/background/spectrum`, `/api/background/reference`, `/api/background/theoretical` — background data (live, 24h reference, theoretical CsI(Tl) model)
- `/api/cps/timeline` — CPS time series
- `/api/history`, `/api/history/{date}` — daily detection reports

### Key Physics Constants

Energy calibration: `E(keV) = 0.33 + 2.97 * channel_index` (env vars `ENERGY_CALIBRATION_OFFSET` and `ENERGY_CALIBRATION_SLOPE`). The detector has 1024 raw channels but channel 1023 is an overflow bin — only the first 1023 channels (20–3036 keV) are used for display and inference. CsI(Tl) crystal with 8.4% FWHM at 662 keV.

## Commands

```bash
# Build all images
docker compose build

# Train model (GPU required, ~45 min on RTX 5060 Ti)
docker compose run --rm train

# Capture 24h background (leave running, no radioactive source nearby)
docker compose run --rm -d --name radiacode-bg detect python capture_background.py

# Start continuous detection monitor
docker compose up detect

# Start web dashboard
docker compose up web

# Run both detect and web
docker compose up detect web
```

No test suite exists in this project. No linter is configured.

## VegaModel

Defined in `train/vega_ml/training/vega/model.py`. Input: 1D spectrum (1023 channels, normalized to max). Output: classification logits (82 isotopes, apply sigmoid for probabilities) + activity predictions (Bq, scaled by max_activity_bq=1000). Loss: `VegaLoss = BCE(logits) + 0.1 * Huber(activities * mask)` — regression only penalizes present isotopes.

The model checkpoint (`models/vega_best.pt`) stores `model_config` and `model_state_dict`. At inference, the detect container dynamically imports `VegaModel` and `IsotopeIndex` from the mounted `vega_ml` volume.

## Synthetic Background Model

The training background uses a realistic CsI(Tl) continuum shape (not a simple exponential):

- **Continuum**: Asymmetric hump at ~110 keV (sigma_left=55, sigma_right=50 keV) + Compton tail (`0.45*exp(-E/240) + 0.04*exp(-E/700)`) + noise floor. Calibrated against real Radiacode 103 measurements. Implemented in `spectrum_physics.py::generate_realistic_continuum()`.
- **Isotope peaks**: K-40 (1460 keV), Pb-214 (295, 352 keV), Bi-214 (609, 1120, 1764 keV), Ac-228 (911 keV), Pb-212 (239 keV), Tl-208 (583, 2614 keV) — with stochastic activity variation per sample.
- **Hybrid training**: If `MEASURED_BACKGROUND_PATH` points to a valid `.npy` file, 70% measured + 30% synthetic continuum is used. This is controlled by `SpectrumConfig.measured_background_path` and the `--measured_background` CLI argument.

## Configuration

All config is via environment variables in `docker-compose.yml`. Key variables:
- `MODEL_PATH`, `ISOTOPE_INDEX_PATH`, `BACKGROUND_PATH` — file paths (container-mounted volumes)
- `VEGA_DEVICE` — `cpu` or `cuda`
- `THRESHOLD` — detection probability threshold (default 0.5)
- `SAMPLE_INTERVAL` — seconds between samples (default 60)
- `ENERGY_CALIBRATION_OFFSET/SLOPE` — energy calibration constants
- `MEASURED_BACKGROUND_PATH` — path to measured background `.npy` for hybrid training (default: `/data/background_24h.npy`)