---
title: "2026-09-18 NanoVirDx sample API design"
description: "Designed the breaking migration from parallel-list batch dataclasses to scalar samples and list-in/list-out predictors."
image: "https://docs.virdx.dev/img/virdx-social-card.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.virdx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-09-18 NanoVirDx sample API design

## Work Done

Inspected all NanoVirDx Python source and its README in the mono repository. Designed a file-by-file migration from `*Batch` struct-of-lists types to scalar `*Sample` dataclasses. Defined list-in/list-out predictor contracts, the nested histology preprocessing result, the derived single-domain directory invariant, vxData adapter boundaries, README corrections, and a deliberate no-compatibility policy. No mono working-tree files were edited because vxData adapter work was in progress concurrently.

## Lessons Learned: Pitfalls

The product workstream was initially inferred, but NanoVirDx spans Histo, DiffSim, and inverse pipelines and fits the inverse workstream better for this cross-domain API design. The inverse workstream has no SOP index. The README currently advertises several empty or nonexistent predictors, so it is not a reliable inventory without checking source.

## Lessons Learned: Improvements

A short NanoVirDx API design note should record that predictors accept lists of scalar samples, preserve order and cardinality, and that preprocessing alone nests a variable component list per source WSI. It should also state that a domain representation's maps must share one directory because DiffSim discovers maps from that directory.

Source: https://docs.virdx.dev/knowledge/inbox/2026-09-18-inverse-nanovirdx-sample-api-design/index.mdx