{"schema_version":"1","site":"https://decosa.ai","id":"medical-chronology","num":"73","name":"Medical chronology with page cites","tool_name":"Build a medical chronology","short":"Medical chronology","blurb":"For personal-injury and med-mal attorneys, life and disability insurers and APS reviewers. Give it a packet of medical records: typed notes, scanned and faxed forms, handwriting, lab tables. The document reader reads every page with boxes, the pages go into a retrieval index as chunks that keep their page and box, and an open model lists the encounters, diagnoses, procedures, imaging, labs and medications on each page. Code keeps only events whose words are on the page and whose date is written there. Copies from different providers are merged, conflicting dates for the same procedure are flagged, and so are gaps in treatment and conditions documented before the injury. Every line cites the file, page and box. A paralegal and reviewer aid, not medical or legal advice.","status":"live","labels":{"industry":["legal","healthcare"],"job":["review","attest"],"input":["files"],"deploy":["selfhost"],"status":"live","output":["data","record"],"data":["phi"],"hardware":"gpu-96","licence":"permissive"},"industries":["legal","healthcare"],"runs_in":["selfhost"],"part_of":[],"built_from":["document-reader","evidence-retrieval","typed-judgment","signed-record"],"models":"Qwen3.8-27B (events per page with the page image, typed judgments) · document reader (Docling layout + PaddleOCR-VL) · Qwen3-Embedding + Qwen3-Reranker (retrieval over the page boxes)","where":"Self-host for real records (PHI); the hosted demo takes synthetic records only","hardware":"1x RTX PRO 6000 (96 GB) for Qwen3.8-27B, plus about 6 GB for the document reader and 10 GB for the embedder and reranker; the checks, merging and record run on CPU","final_artifact":"A dated chronology in Markdown where every line cites file, page and box, with copies merged, conflicting dates, gaps and pre-existing conditions flagged, and a signed decosa.record.v1.","self_host_first":true,"verification":{"receipt_coverage":"full","summary":"Receipt per model call; a signed document-reader receipt per file; retrieval index and layout hashes with signed search receipts; every quote found on its page; signed hash-chained record","manual_qa":{"hosted":{"date":"2026-09-27","result":"pass","p50_ms":25306,"p95_ms":null,"runs":null,"receipts_per_run":8,"cost_per_run_usd":0.004391},"selfhost":{"date":"2026-09-27","result":"pass","method":"fresh clone into a clean directory, api image from docker/api/Dockerfile, compose api with a named volume, direct route to the local Qwen3.8-27B and the running document reader and retrieval services, local signing; torn down after","notes":"The rehearsal bundle passed 12/12 in 68 s (the 16-page packet uploaded as files: conflict, gap, pre-existing, copies, cites in the index, reader receipts, record verified and failed when changed; every receipt attested) and the smoke module passed in 17.9 s. The reader and retrieval services were not built from the compose file here: the running ones were used."},"known_limits":["Hosted verification ran on the pre-release server (decosa-api the pre-release branch on our server, gateway route): the smoke test on one 4-page file, and the full 16-page sample from the console. The production API gets this tool when the branch merges.","Measured on synthetic packets written by the same author as the prompts, one template family; not on real records or against a nurse reviewer's chronology.","When the reader skips a line on a scan, the event on it is missed: 9 of 198 planted events were missed, mostly this way.","Hosted runs are capped at 40 pages; a page takes about 5 s on the shared gateway.","Billing records and charges are not extracted."],"nightly_covers":null},"nightly":"https://api.decosa.ai/verify/status"},"eval_summary":{"metrics":[{"name":"Planted events found","value":"189 / 198","unit":null,"n":198,"split":"test","note":"6 held-out synthetic packets, 96 pages; prompts and thresholds frozen after the dev split"},{"name":"Date right, of events found","value":"189 / 189","unit":null,"n":189,"split":"test","note":null},{"name":"Cite on the right page and box, of events found","value":"189 / 189","unit":null,"n":189,"split":"test","note":"the cited box overlaps the planted line by at least half its height"},{"name":"Lines that are not planted events","value":"2 / 224","unit":null,"n":224,"split":"test","note":"both were therapy techniques in a PT plan listed as procedures"},{"name":"Planted date conflicts flagged","value":"6 / 6","unit":null,"n":6,"split":"test","note":"0 false conflicts"},{"name":"Planted gaps in treatment found","value":"6 / 6","unit":null,"n":6,"split":"test","note":"0 false gaps"},{"name":"Pre-existing conditions flagged (related or not said right)","value":"12 / 12 (12 / 12)","unit":null,"n":12,"split":"test","note":"0 false flags"},{"name":"Events on faxed copies cited on the copy too","value":"57 / 66","unit":null,"n":66,"split":"test","note":null},{"name":"Seconds per 100 pages","value":"537.7","unit":"s","n":96,"split":"test","note":"end to end on the shared hosted gateway, one packet at a time"},{"name":"Planted events found, dev","value":"98 / 99","unit":null,"n":99,"split":"dev","note":"3 packets used while building; 1 of 114 lines not a planted event"}],"dataset":"Nine synthetic record packets for fictional patients (3 dev, 6 held-out test), 16 pages each from five providers: typed PDFs with a text layer, scans with rotation, speckle and JPEG noise, handwritten forms and flow sheets, and faxed copies, with planted events, copies, one date conflict, one gap and two pre-existing conditions each (decosa_api/verticals/chronology/synth.py).","held_out":true,"caveats":["Same author wrote the generator, the answer key and the prompts; one template family, tidier than real records.","Matching an entry to a planted event uses its type and key words; a few defensible extra lines (an operative note listed as a visit, orders as referrals) are counted as neither right nor wrong.","No real records and no nurse reviewer's chronology to compare with.","Timing is on a gateway shared with other workloads; a private GPU runs faster."],"date":"2026-09-27","doc_url":"https://decosa.ai/metrics/evals/medical-chronology"},"stack":{"summary":"For personal-injury and med-mal attorneys, life and disability insurers and APS reviewers. Give it the records as PDFs or images: typed notes, scanned and faxed forms, handwriting, lab tables. The document reader reads every page into elements with their boxes (and signs a receipt per file); the evidence retrieval block indexes each page's elements as chunks that keep page and box. Qwen3.8-27B reads each page, with the page image for scans, and lists encounters, diagnoses, procedures, imaging, labs, medications and referrals in a fixed schema. Code keeps an event only if its words are on the page and its date is written there (the dates block), turns ordered studies into referrals, merges copies of the same page from different providers, and a search per procedure finds other pages that give a different date; typed judgments settle the unclear pairs and say whether a condition documented before the injury is related to it. You get a Markdown chronology with conflicts, gaps in treatment and pre-existing conditions flagged, and a signed record of hashes. A paralegal and reviewer aid, not medical or legal advice.","tagline":"A packet of medical records in, a dated chronology out: every line cites the file, page and box it came from.","deployment":"self-host-first","regulatory_note":"Written 27 Sep 2026. Medical records held by HIPAA covered entities (providers, health plans) and their business associates are protected health information; 45 CFR 160.103 names legal and consulting services among the services that make a vendor a business associate (https://www.law.cornell.edu/cfr/text/45/160.103, read 27 Sep 2026), and 45 CFR Part 164 Subpart E sets the privacy rules (https://www.hhs.gov/hipaa/for-professionals/privacy/index.html). A plaintiff's firm that gets records with the patient's authorization is usually not a business associate, and life and disability income insurance are excepted benefits outside HIPAA's 'health plan' (PHS Act 2791(c)(1), cited by 160.103; the list itself was not re-read today, unverified here), but state medical-privacy laws, protective orders and professional duties still apply to the same records. That is why real records are self-host only and the hosted demo refuses anything not marked synthetic. The tool lists what the records say with their page and box; it does not give medical opinions (causation, standard of care, prognosis) or legal advice, and a paralegal, nurse reviewer or attorney checks each line. Model licences: Apache-2.0 (Qwen3.8-27B, PaddleOCR-VL-1.6, Qwen3-Embedding, Qwen3-Reranker), MIT and Apache-2.0 (Docling and its layout weights).","components":[{"id":"chronology","role":"The event schema and page checks, copies, merging, conflicts, gaps, pre-existing, cites to chunks and bytes, the Markdown chronology and the signed record (no model; CPU)","name":"decosa-api medical chronology (decosa_api/verticals/chronology), importing the document reader, evidence retrieval (scans into retrieval), typed judgment and dates blocks","hf_repo":null,"license":"AGPL-3.0-or-later","params":null,"quant":null,"vram_gb":0,"memory_gb_estimate":null,"engine":"Python 3.12; quote-on-page check (exact, or the reader's fuzzy locate at 0.85 for OCR slips); dates parsed and located by decosa_api.verticals.claims.dates; page copies by word 3-gram overlap plus a shared date; decosa.record.v1 hash chain","receipt_coverage":"partial","in_hosted_demo":null,"tiers":["lite","standard"],"alternative_to":null},{"id":"model","role":"One call per page (the page's elements, plus the page image for a scan) listing typed events with quote and date; typed judgments for duplicate and conflict pairs and for pre-existing conditions; re-reads of regions the parser was unsure of","name":"Qwen3.8-27B (NVFP4)","hf_repo":"nvidia/Qwen3.8-27B-NVFP4","license":"Apache-2.0","params":"27.8B","quant":"NVFP4 (MLP NVFP4, GDN/attention FP8) + FP8 KV cache; MTP head, 3 draft tokens","vram_gb":20,"memory_gb_estimate":null,"engine":"vLLM 0.29.0, temperature 0, thinking off, JSON answers, image input for scanned pages","receipt_coverage":"strong","in_hosted_demo":true,"tiers":["lite","standard"],"alternative_to":null},{"id":"layout","role":"Finds and orders the regions of every page (text, headings, tables, checkboxes) with their boxes","name":"Docling 2.130 with the Heron layout model (document reader block)","hf_repo":"docling-project/docling-layout-heron","license":"MIT (Docling) + Apache-2.0 (weights)","params":null,"quant":"FP32","vram_gb":1,"memory_gb_estimate":null,"engine":"docling-ibm-models on CUDA in the docreader service (services/docreader), our server's GPU0","receipt_coverage":"partial","in_hosted_demo":true,"tiers":["lite","standard"],"alternative_to":null},{"id":"parser","role":"Reads each region of a scanned page (text, handwriting, tables as cells)","name":"PaddleOCR-VL-1.6 (0.9B, document reader block)","hf_repo":"PaddlePaddle/PaddleOCR-VL-1.6","license":"Apache-2.0","params":"0.9B","quant":"BF16","vram_gb":4.4,"memory_gb_estimate":null,"engine":"vLLM 0.29.0 behind the docreader service (production on our server's GPU0 since 27 Sep; 4.4 GB peak measured)","receipt_coverage":"partial","in_hosted_demo":true,"tiers":["lite","standard"],"alternative_to":null},{"id":"retrieval","role":"Scans into retrieval: each page's elements as chunks with page and box, the index and layout hashes, every cite located to a chunk and byte span, and a reranked search per procedure for other pages that give another date","name":"Evidence retrieval block: Qwen3-Embedding-0.6B + Qwen3-Reranker-4B (decosa-retrieval service)","hf_repo":"Qwen/Qwen3-Reranker-4B","license":"Apache-2.0","params":"0.6B + 4B","quant":"BF16","vram_gb":9,"memory_gb_estimate":null,"engine":"services/retrieval (transformers, loaded once); decosa_api.retrieval.scans in the API","receipt_coverage":"partial","in_hosted_demo":true,"tiers":["standard"],"alternative_to":null}],"tiers":[{"id":"lite","label":"Lite · document reader and the model, no retrieval service","summary":"DECOSA_CHRONO_RETRIEVAL=bm25: the same reading, extraction, checks, merging and record; cites are located in a keyword index and the conflict search uses BM25 without the reranker, so about 10 GB less GPU memory.","components":["chronology","model","layout","parser"],"hardware":"1x GPU with about 26 GB free for Qwen3.8-27B and the reader","quality_evidence":[{"metric":"Planted events found, conflicts, gaps with BM25 only","value":"not measured yet","source":"the eval runner supports it (scripts/chronology_eval.py --bm25); not run on the test split"}],"latency_note":"not measured separately; the reranked search is about a third of the merge step on the hosted run","in_hosted_demo":false,"receipt_coverage":"strong","receipt_note":"Every model call is receipted; the searches are BM25 in code, so there are no embed or rerank attestations.","hosting":null},{"id":"standard","label":"Standard · reader, retrieval service and the model (hosted demo)","summary":"The document reader, scans into retrieval with Qwen3-Embedding and Qwen3-Reranker, and Qwen3.8-27B per page with the page image. This is what the hosted demo runs, on synthetic records only.","components":["chronology","model","layout","parser","retrieval"],"hardware":"1x RTX PRO 6000 96 GB (measured on shared cards)","quality_evidence":[{"metric":"Planted events found (held-out, 6 packets, 96 pages)","value":"189 / 198 (95.5%)","source":"decosa-api docs/evals/medical-chronology.md, test split, 27 Sep 2026"},{"metric":"Date right / cite on the right page and box, of those found","value":"dates 189 / 189, cites 189 / 189","source":"decosa-api docs/evals/medical-chronology.md, test split"},{"metric":"Lines that are not planted events","value":"2 / 224 (0.9%)","source":"decosa-api docs/evals/medical-chronology.md, test split"},{"metric":"Planted date conflicts / gaps / pre-existing flagged","value":"6 / 6, 6 / 6, 12 / 12; 0 false flags of each kind","source":"decosa-api docs/evals/medical-chronology.md, test split"},{"metric":"Events on faxed copies carrying the copy's cite","value":"57 / 66","source":"decosa-api docs/evals/medical-chronology.md, test split"}],"latency_note":"measured: several minutes per hundred pages on the shared gateway route (held-out eval); a couple of minutes for the sample.","in_hosted_demo":true,"receipt_coverage":"strong","receipt_note":"Every Qwen3.8 call is a separate gateway call with a gateway-signed receipt; each file has a signed document-reader receipt; each search has a signed search receipt with the index hash; the record lists them all.","hosting":null}],"alternates":[],"services":[{"name":"decosa-api","port":8445,"image":"${DECOSA_REGISTRY}/decosa-api:<tag>","purpose":"GET /chronology/info, /chronology/samples; POST /chronology/run (SSE or JSON); POST /retrieval/index-scans; POST /record/verify. Keeps no record text."},{"name":"decosa-docreader (+ PaddleOCR-VL on vLLM)","port":8497,"image":"built from services/docreader; parser on vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1","purpose":"Page image in, regions with boxes out; nothing leaves the box."},{"name":"decosa-retrieval","port":8499,"image":"built from services/retrieval (no published image yet)","purpose":"Embedder and reranker for the evidence retrieval block, on the same GPU box."},{"name":"vLLM (model)","port":8114,"image":"vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1","purpose":"Qwen3.8-27B NVFP4 behind our gateway (hosted) or called directly (self-host)."}],"tools":[{"name":"45 CFR 160.103 (HIPAA definitions)","url":"https://www.law.cornell.edu/cfr/text/45/160.103","license":"US government work","purpose":"Business associate and health plan definitions, cited in the regulatory note (read 27 Sep 2026)."},{"name":"Kalam and Patrick Hand fonts","url":"https://fonts.google.com/specimen/Kalam","license":"SIL Open Font License 1.1","purpose":"The handwriting on the synthetic PT forms and flow sheets (eval and sample only)."}],"hardware":[{"tier":"1x RTX PRO 6000 Blackwell 96 GB","fits":true,"notes":"Measured on our server: the model through the shared gateway on one card; the document reader (about 5.7 GB) and the retrieval service (about 10 GB) on another shared card."},{"tier":"1x 48 GB card","fits":true,"notes":"Estimate: Qwen3.8-27B NVFP4 (about 20 GB with a small KV cache) plus about 16 GB for the reader and retrieval models. Not measured."},{"tier":"CPU only","fits":false,"notes":"The model and the page parser need a GPU. The checks, merging and record run on CPU."}],"latency":[{"lane":"the 16-page sample packet, hosted gateway route, streamed","typical_ms":144410,"source":"measured on our server 2026-09-27 (pre-release server): reading 51.6 s, extraction 43.0 s, merging, judgments and the conflict search 49.8 s; gateway shared with other workloads"},{"lane":"per 100 pages, held-out eval (6 packets of 16 pages, one at a time)","typical_ms":537700,"source":"measured on our server 2026-09-27: 537.7 s per 100 pages end to end (64 to 141 s a packet), shared gateway, 4 page calls at a time"},{"lane":"smoke test: one 4-page file","typical_ms":25306,"source":"measured on our server 2026-09-27, hosted gateway route"}],"benchmark":null,"notes":["On six held-out synthetic packets (96 pages: typed, scanned, faxed and handwritten) it found 189 of 198 planted events; every found event had the right date and a cite on the right page and box.","It flagged all 6 planted date conflicts, all 6 gaps in treatment and all 12 conditions documented before the injury (related or not said right 12 of 12), with no false conflict, gap or pre-existing flag; 2 of 224 lines were not planted events.","Misses come mostly from the reader skipping a line on a scan (an ED diagnosis, an X-ray on a fax) and from the model leaving out the visit itself on a page.","The packets were written by the same author as the prompts, in one template family; real records are messier and have not been measured."]},"buyer_facts":[{"label":"Data retention","value":"Nothing stored: files and page images live in memory for the request (the sample packet's reader output is cached in memory by file hash). The signed record holds hashes and receipt ids, never record text or the patient's name; logs carry counts only."},{"label":"What leaves the box","value":"Self-hosted on the direct route: nothing. The reader, the retrieval service, the model and the checks run on the same machine. Hosted: page text and page images go through the Decosa API, and only synthetic records are accepted."},{"label":"What every line carries","value":"Date, type, label, the quote, and a cite to file, page and box (plus the chunk and byte span in the index). Click-through to the box on the sample packet."},{"label":"What it is not","value":"Medical or legal advice. It does not judge causation, standard of care or damages; a paralegal, nurse reviewer or attorney checks each line at its box."}],"hosted_now":{"needs":["document-reader","evidence-retrieval","qwen3.8-27b"],"off":["document-reader","evidence-retrieval"],"live_by_default":false,"live_status":"https://api.decosa.ai/status"},"data_handling":{"page":"/data#medical-chronology","self_host":{"level":"confidential","leaves":"nothing","summary":"Runs on your machine; nothing is sent to Decosa or a third party by default."},"hosted":{"level":"operator-processed","demo_only":true,"summary":"Hosted demo on sample or public data only; self-host for real data.","gpus":"operator-contracted","third_parties":[],"retention":"Nothing stored: files and page images live in memory for the request (the sample packet's reader output is cached in memory by file hash). The signed record holds hashes and receipt ids, never record text or the patient's name; logs carry counts only.","used_for_training":false,"encrypted_while_processed":false},"sealed_tier":{"applies":false,"note":"The sealed tier (raw chat only, never use-case pipelines) is paused at launch (/docs/sealed-tier)."},"external_calls":[]},"console":{"href":"/legal/medical-chronology","input":"chronology","lanes":[{"id":"read","title":"Pages read","kind":"list"},{"id":"entries","title":"Chronology","kind":"list"},{"id":"flags","title":"Flags","kind":"list"},{"id":"record","title":"Chronology and signed record","kind":"json"}],"samples":[{"n":1,"id":"whitlock","title":"Whitlock","deep_link":"/legal/medical-chronology?sample=1&autorun=0"}],"deep_link_params":{"sample":"1-based index into samples, or a sample id","autorun":"1 = start the run once the sample is loaded; 0 (default) = only preselect","reduce-motion":"1 = turn off animations"}},"api":{"base":"https://api.decosa.ai","contract":"/api/contract.json","contract_markdown":"/api/contract.md","reference":"/docs/api","keys":"/account/keys"},"prompts":{"hosted":"/prompts/medical-chronology-hosted.md","selfhost":"/prompts/medical-chronology-selfhost.md","assemble":"/prompts/medical-chronology-assemble.md","mac":null},"rehearsal":{"bundle":"/samples/medical-chronology.zip","bundle_url":"https://decosa.ai/samples/medical-chronology.zip","folder":"/samples/medical-chronology/","expected":"/samples/medical-chronology/expected.json","files":["/samples/medical-chronology/expected.json","/samples/medical-chronology/inputs/F1.pdf","/samples/medical-chronology/inputs/F2.pdf","/samples/medical-chronology/inputs/F3.pdf","/samples/medical-chronology/inputs/F4.pdf","/samples/medical-chronology/inputs/F5.pdf"],"bytes":965716,"checks":["every page was read and gave an answer","the rotator cuff repair is listed and its conflicting date is flagged","the 138-day gap in treatment is found","the 2022 low back pain is flagged before the injury and judged related","the faxed ED note inside the PCP's file is merged as a copy","at least 25 entries, each located in the retrieval index","every cite's quote is located in an index chunk","each file has a signed document-reader receipt","the chronology says it is not medical or legal advice","the signed record verifies","the record fails once its entry count is changed","every model call has a signed receipt"],"licence":"Synthetic: the patient, providers, dates and records are invented (decosa_api/verticals/chronology/synth.py; handwriting in the OFL fonts Kalam and Patrick Hand). Part of decosa-api, which will be released under AGPL-3.0-or-later; until then the source is on request.","about":"Dana Whitlock is fictional. After a rear-end collision on 8 March 2024, five providers send records: typed PCP notes (born-digital PDF), a scanned ED note and lab table, a handwritten physical-therapy evaluation and flow sheet, two MRI reports, and an orthopedic file with a scanned operative note. The ED note also arrives as a fax inside the PCP's file, and the lumbar MRI report as a fax inside the orthopedic file. Planted: the rotator cuff repair's date is given differently in the post-procedure note, therapy stops for 138 days, and a 2022 low-back visit comes before the injury. The run must list the events with a page and box on every line, flag the conflict, the gap and the pre-existing low-back condition (as related), merge the faxed copies, and sign a record that verifies and fails when changed. It takes a few minutes: every page is read by the document reader and one model call is made per page.","run":{"containers":"docker compose exec api python scripts/rehearse.py medical-chronology","checkout":"python scripts/rehearse.py medical-chronology --bundle medical-chronology.zip --base-url http://127.0.0.1:8445","mac":".venv/bin/python scripts/rehearse.py medical-chronology"},"guidance":"Set up with a coding agent (we recommend Claude Code with Claude Opus 5.5; any capable coding agent works) on mock data only, run the rehearsal until every check passes, then run your own data locally yourself. Never give the agent real data during setup."},"hardware_fit":{"check":"/self-host/hardware?use=medical-chronology","data":"/api/hardware.json","tiers":[{"id":"lite","gpu_gb":63,"basis":"stack","unknown":[]},{"id":"standard","gpu_gb":72,"basis":"stack","unknown":[]}],"mac":null},"links":{"page":"/legal/medical-chronology","json":"/use-cases/medical-chronology.json","metrics":"/metrics/medical-chronology","console":"/legal/medical-chronology","console_sample":"/legal/medical-chronology?sample=1&autorun=0","stack":"/legal/medical-chronology#stack","try_live":"/legal/medical-chronology","watch":"/legal/medical-chronology","build":"/legal/medical-chronology#build","self_host":"/legal/medical-chronology#self-host","prompts":{"hosted":"/prompts/medical-chronology-hosted.md","selfhost":"/prompts/medical-chronology-selfhost.md","assemble":"/prompts/medical-chronology-assemble.md","mac":null}}}