Project Info

VASCTRACE AI

Inspiration

Medical imaging research has a chicken-and-egg problem: you cannot train or fairly evaluate a detector for a rare vascular finding without labeled examples, but the labeled examples barely exist. So we flipped the question. Instead of chasing scarce disease labels, we asked a bounded, honestly-answerable one: Under controlled image-domain conditions, when can a compact PET/CT model localize a simulated vascular-like FDG source in a healthy scan, and what can deterministic code actually measure about it? VascuTrace is our answer — a reproducible method-development prototype, not a diagnostic system. It is a research prototype trained and evaluated on simulated vascular-like sources, and no result here establishes clinical sensitivity, specificity, or patient benefit. The second inspiration was about how rigorous research gets built. We wanted to see whether an AI agent could own the parts of research that usually bottleneck a small team — planning, architecture, scientific review, and report writing — while keeping a hard line: generated language must never be able to change a measured number. That "Work, Life and Productivity" angle — using Codex and GPT-5.6 as a disciplined research engine — is as much the project as the model is.

What it does

VascuTrace is an end-to-end PET/CT research pipeline on the public QUADRA healthy test/retest cohort (Zenodo 16686025: 48 subjects, 96 sessions, 960 NIfTI files): Physical-coordinate geometry — PET and CT live on different grids, so every multimodal op uses patient RAS coordinates and named transforms, never matching array indices. Controlled synthetic-source engine — inserts a parameterized vascular-like FDG source (radius, uptake multiplier, blur) into raw SUV, giving ground truth by construction. A 2.5-D shared-weight Siamese U-Net ("B2", deep supervision) that reads five adjacent PET and CT slices per bilateral branch and emits an uncalibrated abnormality_score map. Deterministic 3-D quantification that returns SUV statistics — or structured nulls with explicit QC reasons, never silent zeros. A product layer with an auditable tool trace, an executable evaluation suite, and a verifier that rejects any generated report whose numbers or claims drift. On a freshly rebuilt, leakage-verified held-out validation cache (90 positive slices), the trained model reproduced the reported behavior: We report the misses too — the honest spread matters more than one aggregate.

How we built it

The division of labor was deliberate: Codex, powered by GPT-5.6 (gpt-5.6-sol), owned every non-coding role: planning and architecture, primary technical decisions, scientific and critical review, report writing, and Git/release handling. It converted the research goal into bounded plans with explicit acceptance checks. Claude implemented code only from those Codex-authored plans. The team kept final authority over every scientific, licensing, and submission decision. The sanitized public receipt covers 11 Codex sessions on GPT-5.6 — 5,654 tool calls, 654 code patches, 629 bounded reviews, over 28,000 structured source records and 123.76 observed hours. The core engineering principle is that measurement code is physically separate from generated prose. Numbers come from pure, side-effect-free functions; the language model may write interpretation, but a deterministic verifier compares every reported value against the source within tolerance and rejects prohibited claims. For example, laterality asymmetry is a fixed formula, not a model opinion: $ \text{asymmetry_index} = \dfrac{\bar{S}{\text{target}} - \bar{S}{\text{contra}}}{\bar{S}_{\text{contra}} + \varepsilon} $ and physical volume comes straight from the affine determinant, never a hardcoded spacing: $$ V_{\text{mL}} = \frac{N_{\text{vox}} \,\lvert \det(A_{3\times3}) \rvert}{1000}. $$ Stack: Python 3.13, PyTorch + MONAI, NumPy/SciPy, nibabel/SimpleITK, Streamlit, Pydantic, the Model Context Protocol, uv/ruff/pytest — 735 offline tests pass deterministically on CPU with no data or weights required.

Challenges we ran into

A 14 GB memory wall. Cropping one whole-body session peaked at ~14 GB and OOM-killed our machine, blocking the entire real-data path. The culprit was the RAS canonicalization: an exact signed-permutation remap that was materializing dense whole-volume float64 coordinate grids. We replaced it with a transpose + per-axis flip — provably bit-identical (verified against the old path) — cutting the peak to ~3.6 GB and unblocking everything. A data-leakage trap. The dataset split uses seed 20260713, but the training seed is 20260716. Naively reusing the training seed would have put training subjects into the "held-out" evaluation. We caught it and verified every evaluated subject was genuinely held out. Honest reproduction, not cherry-picking. Our independently rebuilt cache lands close to the reported numbers but not identical — and we show exactly why (a 15-vs-13-bundle cache and a known legacy-reflection gap) rather than papering over it. Keeping the scientific boundary intact end-to-end — every artifact carries the "simulated, not clinical" warning, and invalid measurements stay as structured nulls.

What we learned

Determinism is a feature, not a constraint. Making measurement code incapable of being rewritten by an LLM — rather than merely instructing it not to — is what makes the pipeline trustworthy. AI can own the research scaffolding. Codex/GPT-5.6 tracing requirements, catching a statistical defect, and assembling an evidence-classed report genuinely accelerated the work — while a human kept final authority. Read the seeds. In imaging ML, a one-line seed mismatch is the difference between a held-out result and accidental leakage. Efficiency is correctness-adjacent. A ~14× memory blow-up hid inside an "obviously cheap" axis permutation.

What's next

The report is explicit about what would be needed before any promotion claim: native-space 3-D mask stitching, 26-connected component matching, a subject-clustered bootstrap on a sealed test split, a promotion-compliant threshold baseline, and wiring the standalone 3-D quantifier into the product path. Until then, VascuTrace is what it says it is: a disciplined, reproducible research prototype on simulated sources — not a diagnosis.

VascuTrace AI

Research prototype. Trained and evaluated using simulated vascular-like abnormalities, not confirmed human post-angioplasty lesions.

VascuTrace is a reproducible PET/CT method-development prototype. It studies whether controlled vascular-like synthetic sources can be detected and quantified in healthy PET/CT backgrounds. It is not a diagnostic system and no reported result establishes clinical sensitivity, clinical specificity, or patient benefit.

The detailed technical report is available at docs/report/VascuTrace_Technical_Report_2026-07-20.pdf. It includes aggregate EDA, method schematics, actual generated product views, the verified five-tool runtime trace, all six product checks, corrected development-collaboration evidence, and a sanitized analysis of 11 root Codex sessions. No patient image or model weight is used in the report evidence build.

Current implementation

The repository contains:

PET/CT geometry utilities that use physical patient coordinates and named transforms
subject-grouped data contracts and deterministic bilateral crop generation
a parameterized image-domain synthetic-source engine
a transparent threshold baseline
deterministic 3D quantification with structured null and QC results
a 2.5D shared-weight Siamese U-Net training and evaluation path
a research-demonstrator application with deterministic tools, MCP exposure, optional local evidence retrieval, report generation, and numeric-fidelity verification

The product workflow keeps measurement code separate from generated prose. Language generation cannot create or replace quantitative values. The default report backend is a deterministic template, and the default detection backend is a synthetic-reference path intended for integration testing. The trained Siamese backend is opt-in and currently processes a selected cached 2D validation sample rather than a complete scan.

The current exploratory B2 result was measured on 208 validation center slices, including 78 positive and 130 negative slices, drawn from seven subject clusters. At the frozen operating point, positive-slice mean IoU was 0.614895, 75 of 78 positive slices had a target-overlapping prediction, and 37 of 130 negative slices contained activation. These are validation-only 2D observations, not held-out test, scan-level, 3D, or clinical performance estimates.

Setup

The project targets Python 3.13 and uses uv for dependency management.

uv sync --locked
uv run ruff check --no-cache .
uv run ruff format --check --no-cache .
uv run pytest -q -m "not local_data and not gpu" \
  -k "not test_dataloader_with_multiple_workers"

CPU and offline tests use generated fixtures. Dataset files, medical volumes, model weights, caches, credentials, and run outputs are not versioned.

The multiprocessing DataLoader node is verified separately because restricted containers may not allow worker processes to complete. During release review, it reached a 90-second cap without pytest failure output. On a host that permits multiprocessing, run:

uv run pytest -q \
  tests/test_ml_dataset.py::TestPicklingAndDataLoader::test_dataloader_with_multiple_workers

Research demonstrator

Run the deterministic local dashboard:

uv run streamlit run app.py

Run the product evaluation and complete synthetic case paths:

uv run python -m scripts.run_product_evaluation
uv run python -m scripts.run_complete_case

Rebuild the generated-only product receipt and report figures 09 through 11:

uv run python docs/report/scripts/build_product_evidence.py

Run the MCP server over standard input and output:

uv run python -m vascutrace.mcp_server

Generated artifacts are written under the configured output root and remain untracked.

Optional product backends

Every optional backend is explicitly selected. Offline deterministic behavior is the default.

Setting	Default	Optional value
`VASCUTRACE_DETECTION_BACKEND`	`reference`	`siamese`
`VASCUTRACE_REPORT_BACKEND`	`template`	`llm`
`VASCUTRACE_EVIDENCE_BACKEND`	`keyword`	`rag`

The optional report path uses an OpenAI reasoning model for interpretation and local Qwen models for embedding and reranking. Deterministic code owns all measurements and laterality fields. The public retrieval corpus must be rebuilt locally before enabling RAG because generated indices are not versioned.

Collaboration with Codex

Codex with GPT-5.6 performed every non-coding workflow role in the VascuTrace development process. This included planning and architecture, primary technical decisions, scientific review, report writing, delivery review, Git and release handling, and humanizer and editorial review. Codex also authored the plans and instructions used for code implementation. Claude was used only to implement that planned code. The project owner retained final authority over all product, scientific, publication, licensing, repository, category, video, and submission decisions.

The public evidence projection covers 11 root Codex sessions through 2026-07-21T14:56:53.784Z. Their metadata records gpt-5.6-sol in all 11 sessions. The projection contains 87 user turns, 725 assistant updates, 69 started tasks, 60 completed tasks, 5,654 tool-call events, 654 patch events, 629 bounded review activities, 77 web searches, and 38 context compactions. These are structural event counts, not measures of quality, labor time, or scientific performance.

VascuTrace product GenAI prompts are shipped application code. Private development-agent artifacts are excluded from the public release. The session-based collaboration record documents the public decision and evidence trail, links the sanitized session receipt, and shows the collaboration, timeline, and activity figures. The hackathon submission guide collects the description, demonstration, testing, and owner-completed submission fields. The selected competition category is Work, Life and Productivity.

Scientific status and limitations

The implemented components are not yet a fully integrated scientific pipeline. Important open work includes:

replacing the legacy bilateral-reflection crop method with the frozen iliac-only physical-coordinate method
completing a promotion-compliant threshold baseline
stitching model outputs into native-space 3D masks
running subject-clustered evaluation on a sealed test split
integrating the standalone 3D quantifier into the product path
rebuilding and reevaluating the sanitized public retrieval corpus

Invalid or unavailable scientific measurements should be represented as structured nulls with explicit QC reasons, never silently converted to zeros.

Branches

main is the release branch.
dev is the active development branch.

CI runs lockfile, lint, formatting, and test checks for pushes and pull requests.

Analysis

Compare with all teams

View

Metric

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

OpenAIIn code
PythonIn code
PyTorchIn code
StreamlitIn code

4 of 4 appear in the indexed code.

AI coding agents

Claude CodeCommits

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

1.8 MB

Source files

114

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.