HF Readmit Agent

• 

  HF Readmit Agent

Inspiration

Heart-failure follow-up after discharge is full of small, longitudinal signals: weight changes, oxygenation, symptoms, medication adherence, and patient-reported concerns. A single alert is not enough to support a rigorous review.

We were inspired by a simple question: how can AI support evaluation without hiding the evidence, replacing clinical judgment, or making untested claims? HF Readmit Agent explores an answer through a synthetic-data research workflow where every escalation can be inspected, challenged, and measured.

What it does

HF Readmit Agent is an evidence-first, human-in-the-loop workstation for evaluating post-discharge heart-failure follow-up triage on a cohort of 18 synthetic cases.

A reviewer can:

• Open a reviewer-specific case queue and inspect a compact patient snapshot.
• Review a daily timeline of symptoms, vitals, adherence, and trends.
• See the deterministic L0–L3 triage tier, named rule, source day, and source value behind each escalation.
• Record an independent final tier and explain agreement, modification, or disagreement.
• Explore analytics and Safety Lab results that compare deterministic rules, an optional LLM second reader, and human reviewers.

The project is strictly a research prototype. It does not use real patient data and is not a medical device, diagnostic tool, or clinical decision-support system.

How we built it

We built HF Readmit Agent as a runnable full-stack prototype:

• React + Vite + TypeScript for the reviewer workspace, Safety Lab, bilingual interface, theme settings, browser-local logo preferences, and clinician-oriented information hierarchy.
• Go for the REST API, deterministic rules engine, reviewer queues, server-side review timing, exports, analytics, and LLM safety controls.
• PostgreSQL for reviewer-scoped decisions and measured review duration.
• Docker Compose for a reproducible local web, API, and database stack.
• A deterministic rules-v1.0 engine that evaluates each synthetic follow-up day and returns L0–L3 results with named, evidence-producing rules.
• An optional GPT-5.6 second-reader path, designed as a constrained research assistant rather than an autonomous scorer. Its output follows a strict JSON structure; citations are restricted to real case fields and days, then verified and resolved server-side before being shown.
• A Safety Lab that makes disagreements visible through coverage, exact-match, L3 sensitivity, low-risk specificity, critical-miss, and citation-coverage views.

We also used ui-ux-pro-max skill during development to guide visual hierarchy, typography, dashboard layout, SVG icon usage, light/dark mode polish, and clinician-friendly review workflows. It was a development-time design aid, not a runtime dependency.

Codex accelerated implementation and validation across the stack: translating the reader-study concept into a working Go/React/PostgreSQL/Docker system, implementing tests, iterating on the UI, and helping audit the public repository for reproducibility and privacy boundaries. The key product decisions remained human-led: synthetic-only data, evidence before automation, optional model use, and clinician final authority.

Challenges we ran into

The hardest challenge was balancing useful AI assistance with safe boundaries.

First, we needed a triage experience that was informative without pretending to be clinical truth. We solved this by making deterministic rules inspectable and labeling the designed cohort answers as prototype evaluation references, not medical ground truth.

Second, an LLM can produce fluent but unsupported output. Rather than treating it as another opaque risk score, we constrained the optional GPT-5.6 second reader with structured output, source-data citation checks, canonical value resolution, and a human final-decision boundary.

Third, clinical review screens can become too dense. We iterated on the workspace so the patient snapshot, trend, daily trail, triggering evidence, and reviewer action are understandable without forcing the user to hunt through disconnected panels.

Finally, we wanted judges to test the project immediately. The core review experience, deterministic rules, analytics, and baseline Safety Lab run locally without an API key or test account.

Accomplishments that we're proud of

• Built a complete, runnable research workflow around 18 synthetic heart-failure follow-up cases.
• Made every deterministic escalation traceable to a named rule, day, and source value.
• Preserved independent human review through reviewer-specific queues, server-measured timing, decision notes, and exports.
• Created a Safety Lab that treats disagreement and critical misses as visible evaluation signals.
• Added an optional GPT-5.6 integration with server-side safety controls instead of exposing an unrestricted browser-side prompt.
• Delivered a polished bilingual interface with light/dark modes, local logo customization, privacy-oriented display settings, collapsible navigation, and SVG-based icons.
• Packaged the full stack with Docker Compose so it can be tested without rebuilding the project from scratch.

What we learned

We learned that “AI-assisted” is not enough in a high-stakes evaluation workflow. The system must show its evidence, preserve the reviewer’s ability to disagree, and make its own failures measurable.

We also learned that model safety is a product and engineering problem together. Strict schemas, citation verification, server-side secrets, ephemeral benchmark memory, and clear interface language all matter—not just the prompt.

Most importantly, we learned that a strong prototype does not need to claim clinical efficacy to be meaningful. A transparent research environment can help teams ask better questions before AI is ever placed near real-world care.

What's next for HF Readmit Agent

• Conduct structured usability studies with clinicians using synthetic scenarios.
• Add richer study configuration, reviewer management, and more detailed disagreement analysis.
• Evaluate multiple compatible LLMs and model versions under the same constrained, evidence-cited benchmark.
• Improve reproducibility with versioned benchmark runs and exportable evaluation reports.
• Explore enterprise research-readiness features such as role-based access control, audit trails, governance workflows, and institutional data-handling requirements.

HF Readmit Agent will remain synthetic-data and research-only unless future work establishes the clinical, regulatory, security, and governance foundations required for any broader use.

Built With

• codex
• csv
• data-visualization
• docker
• docker-compose
• explainable-ai
• generative-ai
• go
• gpt-5.6
• healthcare
• healthtech
• human-in-the-loop
• i18n
• json-schema
• llm
• openai
• postgresql
• react
• rest-api
• svg
• synthetic-data
• typescript
• ui/ux-pro-max
• vite