XREPORT: A Local-First Lab for Draft Radiology Reports

What it is, why it exists, and the design choices that make it a cautious tool instead of an ambitious one.

The job that hides inside the scan

If you have ever watched a radiologist work a stack of chest X-rays, the first thing you notice is how much of the job is not diagnosis. A lot of it is dictation. The lungs, the cardiac silhouette, the mediastinum, the bones. Normal, unremarkable, no acute findings. The kind of report that makes up most of a working day and takes very little of a radiologist's brain to produce correctly, but still has to be written, in the right format, with the right words, every single time.

That is the problem XREPORT is aimed at, and the honest way to state it is also the narrow way. Doing radiology reporting well is exhausting, and fatigue is the last thing you want anywhere near a diagnostic decision. Automation cannot fix that fatigue, but it can carry some of the routine load so the human review happens on a less tired brain.

This is not a tool that reads a scan and tells you what is wrong. It is a tool that produces a structured first draft of the report, which a qualified clinician then reads, corrects, and signs. The difference between those two jobs is the whole design. XREPORT is built to be a laboratory for making drafts, with the review step kept firmly human.

Local first, because the data decides

The most important sentence in the whole project is in the repository's opening note: generated drafts are not clinically approved and require qualified independent review. The second most important is the privacy boundary. XREPORT is local-first, and for medical imaging that is not a packaging preference, it is the entire point.

X-ray images are patient data under legal and ethical constraints. A tool that sends chest scans to a cloud service is a non-starter for most hospitals regardless of how accurate the model is, because the institution cannot control where the data goes or who can look at it. XREPORT never phones home. Models are downloaded once, cached in a project-local resource directory, verified, and reused offline. Training, validation, and generation all run on the machine the user controls. For clinical settings this is not a feature that needs to be argued for; it is the price of entry.

That single decision shapes everything downstream. Because there is no cloud backend, there is also no silent model update, no surprise behavior change between Tuesday and Wednesday. What the user validated last month is what runs next month, unless they choose to change it.

Not one report engine, but a choice with provenance

XREPORT avoids locking the user into a single black box. It ships with a fixed catalogue of five pinned public Hugging Face report-generation models, and it also accepts locally trained checkpoints through its own training workflow. The pinned models are chosen because each is a known, verifiable starting point. The custom checkpoints exist because a research lab or a hospital with its own data should not be forced onto a generic model when it has spent months building one on a domain-specific set.

Every generated report carries its provenance with it. The output comes back as editable Findings and Impression fields with the model, provider, and revision metadata attached, so anyone reading the draft can see where the text came from. That traceability matters in a domain where the reader needs to know whether the suggestion was produced by the model the team validated or by something else. It is the difference between a reproducible artifact and an output you cannot explain a month later.

What the custom model actually is

The in-house training path treats report generation as an image-to-text problem, the same framing you would use for image captioning, but with medical language and a strict output shape. It is not a chat model asked nicely to describe an X-ray. It is a purpose-built encoder-decoder that maps an image to a token-by-token sequence of report language.

The image side starts with a BEiT image encoder, a vision transformer pretrained on image patches, which turns a 224 by 224 chest X-ray into a set of visual feature vectors. Those features are projected into the shared embedding space. On the text side, a positional embedding encodes the report tokens as they are produced, and a stack of transformer encoder and decoder layers learns to attend from the image to that sequence. The default shape is four encoder layers and four decoder layers with eight attention heads and a 256-dimensional embedding, though the sizes are configuration options rather than hard constants. A softmax classifier over the vocabulary produces the next token at each step.

Training uses a masked cross-entropy loss that only scores the report tokens, with a masked-accuracy metric tracking how often the model predicts the right next token at the right position. The optimizer is AdamW with an optional warmup learning-rate schedule. The important practical detail is the checkpoint lifecycle. A run can be paused, resumed from any saved state, and evaluated against held-out examples, so a team is never forced to finish a model in one sitting or trust a single untested run. The evaluation view shows loss and accuracy for a saved checkpoint before that model is allowed anywhere near real generation.

The five public models, and what they trade off

Because not everyone wants to train their own model, XREPORT also ships a pinned catalogue of five public chest imaging models, each with its capabilities spelled out in the config rather than assumed. The catalogue is deliberately small and explicitly pinned to exact revisions, so a model that works today still works six months from now.

At the lightweight end is CXRMate Multi TF, a 0.1B parameter model that is the recommended default. It is designed for multi-view chest X-rays and its output is structured, with separate Findings and Impression sections. On modest hardware it is usable locally, which makes it the sensible first choice for most runs. Its sibling CXRMate-ED is a similar small model that additionally accepts a clinical indication or history from the user and maps it into the model's context input. Same family, one richer input.

Further up the scale sit two larger, more demanding models. CheXOne, a 4B parameter vision-language model from Stanford, is capable not only of drafting reports but of reasoning and of output that can be localized back to regions of the image, so it is the entry point if grounding matters. CXRMate-2 is a 3B parameter specialist with structured output and clinical-context support, at the cost of much heavier local storage and memory. Both are far more capable than the lightweight pair, and both are far more demanding on hardware, which is exactly the trade-off a local-first tool has to surface rather than hide.

Rounding out the set is MedGemma 1.5 4B, a broader medical-imaging model that, unlike the chest specialists, is not validated only on radiographs. It produces a single raw report rather than separate structured sections, and it is the one model that also supports prior images as context. It is also gated: downloading it requires accepting Google's model terms and configuring a local token, which XREPORT notes up front rather than pretending the download is automatic.

The picture that emerges is not "here is the one best model." It is a ladder of choices from a small fast default up to heavyweight research models, with their parameter sizes, licence restrictions, hardware demands, and structured-versus-raw output all visible in one place. A small radiology group on a workstation and a research lab with a GPU server look at the same screen and pick different entries on the same list.

The workflow is the concept

XREPORT is a loop, not a single inference button. The loop is the point:

1. Dataset preparation. Import an image folder plus CSV or XLSX report metadata, review how images and reports match, inspect paired records, then clean, tokenize, split, and build training-ready datasets. MIMIC-CXR is supported as a starting validation dataset, alongside custom image-report pair formats. The review step matters, because a training set built without checking that each scan is paired with the right report is quietly teaching the model wrong associations.

1. Training. Configure CPU or GPU training, watch live metrics and logs, save checkpoints, resume, and evaluate. Model readiness and provenance warnings stay visible throughout.
2. Generation. Add up to sixteen study images, pick a generation profile, and submit a background job against the chosen model or checkpoint.
3. Review. The result returns as editable Findings and Impression text with its metadata attached, ready to be copied or exported for qualified review. The screen is built around the edit, not the acceptance. Nothing is published straight from the model; the draft is handed to a person.

Two parts of this deserve emphasis. One is that the user can generate from up to sixteen images in a single case, which matters because a real radiological study is rarely a single view. The other is that validation is a first-class step, not an afterthought. A tool that shows a confident report with no indication of whether the model behind it was ever validated is a tool that has quietly handed the judgment to the machine. XREPORT keeps the validation state in front of the user instead of hiding it.

Why the tool deliberately does less

The temptation in a project like this is to keep pushing toward the interesting part: the idea that a model might one day make a clinical call. XREPORT is explicitly built to stop well short of that line. The value it claims is a coherent first draft that flags what a reader should look for, which is most useful on the routine cases where the findings are unremarkable. For rare or critical findings, an automated draft is only as useful as the clinician's judgment in catching what the model missed. That is why the human-in-the-loop is not a concession but the designed center of the system, and why the output is labeled a research-use draft rather than a diagnosis.

Getting from local promise to usable software took real work on the delivery side too. On Windows the app runs through a single launcher that manages the portable runtimes and dependencies. A Tauri 2 desktop shell packages it as CPU and CUDA installers, so a user who needs the version built for their graphics setup has a normal installer rather than a pile of manual steps. The binaries are currently unsigned, and MSI installs are per-machine, so this is a tool that assumes a technically literate operator, which is honest about the audience.

The restless part under the surface

Underneath, the application is a FastAPI backend with an Angular 22 frontend, with settings kept local and machine-specific, never committed, and the SQLite database managed through explicit migrations. None of that is the story a reader needs to remember. The reason to mention the stack at all is that it was chosen to stay boring and auditable: a report you can trace, a schema you can reason about, dependencies you can pin. In a tool that produces medical text, boring and auditable is a feature.

The design stance

Most report-generation tools are pitched on how much they can automate. XREPORT is more honest than that, and I think that is its best quality. Its automation effort is aimed squarely at the routine load, it keeps the data local, it attaches provenance to every output, and it never pretends to own the diagnostic step. Whether you train a checkpoint or pick a pinned public model, you can see what produced the draft and how validated it was, and the final sign-off stays human.

If a radiologist wants to spend less of their day on unremarkable dictations and more on the cases that actually need them, that is the version of XREPORT that exists. The first run is a research-use tool, not a clinical product, and the source is open under an MIT licence, so any team that disagrees with a design decision can take the code and change it.

If that sounds like your problem, the repository is the place to start: github.com/CTCycle/XREPORT-radiological-reports-generator.

Part of the CTCycle open-source portfolio. Models and generated drafts are not clinically approved and require qualified independent review.