DoseMirror

DoseMirror is a research workbench for finding in-vitro nanotoxicology studies that are experimentally comparable to a target experiment.

It combines structured evidence, hard scientific compatibility gates, a bounded delivered-dose model, calibrated abstention, and budget-aware information acquisition.

The repository includes a live React workbench, a FastAPI service, a Python command line interface, a deterministic 50-episode smoke benchmark, frozen synthetic fixtures, tests, CI, Docker support, and a publication package.

Research boundary

DoseMirror is research infrastructure.

It must not be used for patient care, occupational safety, regulatory decisions, environmental-risk conclusions, or individual exposure advice.

The current benchmark validates software mechanics only. It does not establish biological validity or support the scientific hypotheses in the claims ledger.

What works

• Edit a target experiment and rerank evidence immediately
• Separate direct, translated, incompatible, and unresolved candidates
• Block textually similar studies when material, cell system, or endpoint gates fail
• Estimate delivered mass for supported static well geometries
• Return bounded intervals instead of a fabricated point when uncertainty is material
• Refuse dose translation when hydrodynamic size, effective density, or geometry is missing
• Preserve observed, derived, imputed, missing, and conflicting field states
• Show signed score contributions and study-level exclusion reasons
• Select the next action by expected decision-risk reduction per unit cost
• Export an auditable evidence report as JSON
• Run an offline deterministic NanoCompareBench smoke split
• Serve the same core workflow through FastAPI and the command line

Quick start

Docker

docker compose up --build

Open the workbench at http://localhost:3000.

Open the API documentation at http://localhost:8000/docs.

Local development

Requirements:

• Node.js 22.13 or later
• Python 3.11 or later

Install the workbench:

npm ci
npm run dev

Install the research package:

python -m venv .venv
python -m pip install -e ".[dev]"
uvicorn dosemirror.api.main:app --reload

Command line

dosemirror ingest --fixture data/fixtures/mini
dosemirror benchmark --config configs/smoke.yaml
dosemirror compare --target examples/target.yaml
dosemirror reproduce --manifest runs/example/manifest.json

The default smoke benchmark runs offline and makes no external API calls.

System design

Target experiment
      |
      v
Candidate retrieval
      |
      v
Hard scientific gates
      |
      +---- incompatible
      |
      v
Dosimetry applicability
      |
      +---- not identifiable ----> active acquisition or abstention
      |
      v
Bounded dose translation
      |
      v
Signed comparability score
      |
      v
Evidence report and replay manifest

The modules use dependency inversion so retrieval, extraction, dosimetry, compatibility scoring, and acquisition policies can be replaced independently.

dosemirror/
  acquisition/     Value-per-cost action policy
  api/             FastAPI contracts
  benchmark/       Deterministic smoke benchmark
  compatibility/   Hard gates and signed assessment
  domain/          Immutable versioned scientific schemas
  dosimetry/       Reduced-order settling and diffusion
  ingestion/       Frozen fixture loader
  normalization/   Dimensional unit conversion
  retrieval/       BM25 baseline
app/               Live React workbench
configs/           Benchmark and source configuration
data/fixtures/     Legally redistributable synthetic records
docs/              Data, model, dosimetry, and reproducibility cards
paper/             Claims ledger and publication scaffolding
tests/             TypeScript and rendered application tests
tests_py/          Python unit, property, API, and safety tests

Scientific contracts

Every observed field requires an evidence span.

Every field carries one of these states:

• observed
• derived
• imputed
• missing
• conflicting

Missing and conflicting critical variables never become observed values.

Dimensionally invalid unit conversion fails with an error.

Material density never substitutes for effective agglomerate density.

Primary size never substitutes for hydrodynamic size.

Hard incompatibilities cannot be repaired by semantic similarity.

Reduced-order dosimetry

The deployed model combines Stokes settling and Brownian diffusion in a static uniform liquid column.

The absorbed boundary approximation is used at the cell-facing surface.

The model reports:

• Delivered fraction
• Delivered mass per well area
• Uncertainty bounds
• Settling velocity
• Diffusion coefficient
• Peclet number
• Applicability status

The interval varies hydrodynamic diameter, effective density, and liquid height around the supplied values.

This implementation is not a full ISDD model. It does not support convection, dissolution, nonuniform media, complex particle shapes, or dynamic agglomeration.

See docs/dosimetry_card.md for equations, assumptions, limiting cases, and refusal rules.

Comparability

Candidate assessment follows a strict order.

1. Material identity and surface chemistry
2. Biological system
3. Endpoint construct
4. Critical metadata completeness
5. Dosimetry applicability
6. Delivered-dose overlap
7. Signed contribution score

The label meanings are:

Label	Meaning
direct	Core design, geometry, and nominal exposure are aligned
translated	Comparison is supported after bounded dose translation
incompatible	A hard scientific gate failed
unresolved	Critical evidence is missing or conflicting

Active acquisition

The current policy ranks actions by expected decision-risk reduction divided by cost.

Supported actions include:

• Inspect a characterization table
• Search a supplement
• Request a hydrodynamic-size measurement
• Request an effective-density measurement
• Inspect plate geometry
• Retain uncertainty
• Stop or abstain

The policy stops when no permitted action has positive value within budget.

NanoCompareBench

configs/smoke.yaml defines a 50-episode deterministic smoke split.

The fixtures cover:

• A direct comparison
• A defensible dose translation
• A material mismatch
• A biological-system mismatch
• An endpoint mismatch
• Critical missingness
• Conflicting evidence
• A surface-chemistry mismatch

All included records are synthetic and released for software testing.

Smoke benchmark output must be described as engineering validation. It must not be presented as a biological result.

The larger expert-reviewed benchmark remains future work.

Reproducibility

Every publication run should record:

• Configuration
• Seed
• Code commit
• Environment lock
• Fixture snapshot
• Source registry version
• Model version
• Action costs
• Raw predictions
• Latency
• Statistical output

The expected run manifest is documented in docs/reproducibility.md.

The claims ledger is in paper/claims/ledger.md.

No result table is prefilled with scientific findings.

Tests

Run the complete web suite:

npm test

Run Python tests:

pytest

Run static checks:

npm run lint
ruff check dosemirror tests_py
mypy dosemirror
bandit -q -r dosemirror

The test suite covers:

• Immutable scientific schemas
• Evidence requirements
• Geometry validation
• Dimensional consistency
• Analytic transport limits
• Probability bounds
• Retrieval behavior
• Hard incompatibility gates
• Missing-data abstention
• Budget stopping
• API contracts
• Research-use boundaries
• Deterministic benchmark behavior
• Server-rendered application content

Data and external services

The default application uses frozen synthetic fixtures.

Live sources are optional adapters and require explicit confirmation before submission.

Access conditions, redistribution limits, fallback behavior, and snapshot rules are recorded in docs/source_registry.md and configs/sources.yaml.

No external paper, figure, table, dataset, or PDF is included in this repository.

Publication workflow

Before a scientific submission:

1. Register the hypotheses and statistical plan
2. Freeze the source registry and benchmark snapshot
3. Obtain expert pairwise labels
4. Measure inter-rater agreement
5. Run all baselines and ablations
6. Save raw per-episode predictions
7. Compute paired confidence intervals and effect sizes
8. Review failure strata
9. Update every claim as supported, unsupported, or inconclusive
10. Ask an independent domain collaborator to validate assumptions

Kill criteria are recorded in the claims ledger and must be applied before publication.

Security and privacy

Do not upload private, licensed, or personal documents to a public deployment.

The current hosted workbench uses synthetic fixtures and stores no uploaded documents.

See SECURITY.md for reporting and deployment guidance.

Contributing

Contributions should preserve refusal behavior, provenance, deterministic tests, and the research-use boundary.

See CONTRIBUTING.md.

License

Code is licensed under Apache License 2.0.

Synthetic fixtures are released under CC0 1.0.