# Registry Quickstart: Fe_Pt_DN Example

This guide shows how to register and load reflectometry models via the VIPR registry.
It covers local package registration and HuggingFace-backed usage.

## Option A — Domain convenience command

Use this when a domain-specific bundle command exists (Reflectorch, Flow, PANPE).
It assembles the package directory and `manifest.yaml` automatically.

```bash
vipr reflectometry registry bundle-reflectorch \
  --config  /path/to/storage/reflectorch/configs/NR-2layers-basic-v1.yaml \
  --weights /path/to/storage/reflectorch/saved_models/model_NR-2layers-basic-v1.safetensors \
  --name    NR-2layers-basic \
  --version v1.0.0 \
  --description "Reflectorch baseline model for neutron reflectometry (NR, 2 layers)"
```

Output:

```text
Model package registered: vipr://local/reflectometry/NR-2layers-basic@v1.0.0
```

## Option B — Generic bundle with manifest.yaml

Use this when no domain-specific bundle command exists, or when you need full control over package layout.

### 1. Assemble the package directory

```text
my-package/
├── manifest.yaml
├── configs/
│   └── NR-2layers-basic-v1.yaml
└── saved_models/
    └── model_NR-2layers-basic-v1.safetensors
```

### 2. Compute SHA-256 checksums

```bash
sha256sum configs/NR-2layers-basic-v1.yaml
sha256sum saved_models/model_NR-2layers-basic-v1.safetensors
```

### 3. Write manifest.yaml

```yaml
format_version: 1
name: NR-2layers-basic
version: v1.0.0
domain: reflectometry
family: reflectorch
description: "Reflectorch baseline model for neutron reflectometry (NR, 2 layers)"

model_builder:
  handler: reflectorch_builder
  parameters:
    config_ref: configs/NR-2layers-basic-v1.yaml
    weights_ref: saved_models/model_NR-2layers-basic-v1.safetensors

default_predictor:
  handler: reflectorch_predictor
  parameters:
    calc_pred_curve: true
    polish_prediction: true

requires:
  preprocess_filters:
    - class: vipr_reflectometry.reflectorch.preprocess.interpolation_filter.InterpolationFilter
      method: preprocess_interpolate
      hook: INFERENCE_PREPROCESS_PRE_FILTER

artifacts:
  - role: config
    path: configs/NR-2layers-basic-v1.yaml
    sha256: 30560abf286990b789a9f136502c2314b3d6e68440feec442070459e67d63500
  - role: weights
    path: saved_models/model_NR-2layers-basic-v1.safetensors
    format: safetensors
    sha256: 27ec0e6d0d084e54106e38092a4028162aacb54802867e99bc387d8307a47743

metrics: {}
tags:
  source: bundle-command
  family: reflectorch
```

`artifacts.path` must be relative and must not escape the package directory (`../` traversal is forbidden).
SHA-256 checksums are verified before builder code runs.
Bundle commands do not emit `lineage` by default.
Use `--include-lineage` if you want absolute source paths in the manifest.

### 4. Register the package

```bash
vipr registry bundle --manifest my-package/manifest.yaml --source-dir my-package/
```

## Inspect and promote (local backend)

```bash
vipr registry list
vipr registry show vipr://local/reflectometry/NR-2layers-basic@v1.0.0
vipr registry promote vipr://local/reflectometry/NR-2layers-basic@v1.0.0 production
vipr registry show vipr://local/reflectometry/NR-2layers-basic@production
```

## Option C — Use HuggingFace-backed registry

### 1. Enable HF backend

```bash
export VIPR_HF_REPO=HW-SC/registry
```

### 2. Prefetch registry packages (optional but recommended)

```bash
vipr registry sync
vipr registry sync --domain reflectometry --name fxc34ran
```

### 3. Use HF URI in inference config

```yaml
load_model:
  handler: registry_loader
  parameters:
    model_uri: vipr://hf/reflectometry/fxc34ran@v1.0.0
```

HF backend notes:

- use pinned versions (`@v1.0.0`), not aliases
- `vipr registry promote` is local-only
- requested versions are validated against `index.yaml` before download
- packages are fetched from the repository `main` revision via versioned path
  `<domain>/<name>/<version>/...`
- if a requested version is missing from `index.yaml`, VIPR fails early with
  `Version not found in index`

## Device and builder overrides in `registry_loader`

You can override model-builder parameters from inference YAML without editing `manifest.yaml`:

```yaml
load_model:
  handler: registry_loader
  parameters:
    model_uri: vipr://hf/reflectometry/fxc34ran@v1.0.0
    device: cpu
    builder_parameters:
      some_extra: value
```

`builder_parameters` is merged into `model_builder.parameters` in memory only.

## Full inference examples

### A) Local registry

```yaml
vipr:
  inference:
    filters:
      INFERENCE_PREPROCESS_PRE_FILTER:
        - enabled: true
          weight: -10
          class: vipr_reflectometry.reflectorch.preprocess.error_bar_filter.ErrorBarFilter
          method: preprocess_error_bar_filter
          parameters:
            filter_threshold: 0.3
            filter_remove_singles: true
            filter_remove_consecutives: true
            filter_consecutive: 3
            filter_q_start_trunc: 0.1
        - enabled: true
          weight: 0
          class: vipr_reflectometry.flow_models.preprocess.flow_preprocessor.FlowPreprocessor
          method: preprocess_flow
          parameters: {}
    load_data:
      handler: csv_spectrareader
      parameters:
        data_path: '@vipr_reflectometry/examples/data/Fe_Pt_DN.dat'
        column_mapping:
          q: 0
          I: 1
    load_model:
      handler: registry_loader
      parameters:
        model_uri: vipr://local/reflectometry/fxc34ran@v1.0.0
        device: cpu
    prediction:
      parameters:
        num_samples: 4000
        q_resolution: 0.1
        seed: 42
    preprocess:
      handler: ''
      parameters: {}
    postprocess:
      handler: ''
      parameters: {}
  result_id: Fe_Pt_DN_registry_local
  config_name: Fe_Pt_DN_registry_local
```

### B) HuggingFace remote registry

```yaml
vipr:
  inference:
    filters:
      INFERENCE_PREPROCESS_PRE_FILTER:
        - enabled: true
          weight: -10
          class: vipr_reflectometry.reflectorch.preprocess.error_bar_filter.ErrorBarFilter
          method: preprocess_error_bar_filter
          parameters:
            filter_threshold: 0.3
            filter_remove_singles: true
            filter_remove_consecutives: true
            filter_consecutive: 3
            filter_q_start_trunc: 0.1
        - enabled: true
          weight: 0
          class: vipr_reflectometry.flow_models.preprocess.flow_preprocessor.FlowPreprocessor
          method: preprocess_flow
          parameters: {}
    load_data:
      handler: csv_spectrareader
      parameters:
        data_path: '@vipr_reflectometry/examples/data/Fe_Pt_DN.dat'
        column_mapping:
          q: 0
          I: 1
    load_model:
      handler: registry_loader
      parameters:
        model_uri: vipr://hf/reflectometry/fxc34ran@v1.0.0
        device: cpu
    prediction:
      parameters:
        num_samples: 4000
        q_resolution: 0.1
        seed: 42
    preprocess:
      handler: ''
      parameters: {}
    postprocess:
      handler: ''
      parameters: {}
  result_id: Fe_Pt_DN_registry_hf
  config_name: Fe_Pt_DN_registry_hf
```
