EHR & Transcript Consolidation Service

What it does

During a medical encounter, a lot of clinically relevant information is spoken but never makes it into the patient’s record — and sometimes what is said directly contradicts what the record already holds. EHR & Transcript Consolidation Service watches a clinical conversation as it streams in and, chunk by chunk, compares what is being said against the patient’s existing Electronic Health Record (EHR).

Whenever the transcript and the record disagree, or the transcript adds something the record is missing, the service emits a notification. Each notification carries a type (information_missing or information_conflict), a human-readable message, and, where appropriate, a concrete edit suggestion — an add, replace, or remove operation against a specific field in the EHR — so the record can be brought back in line with what was actually discussed.

How it works

The system is built as two application services backed by Redis and MySQL:

• API (FastAPI, Python 3.12) — the core inference service. It runs an LLM agent that compares each transcript chunk against the EHR and produces the notifications and edit suggestions. Agent behavior — model, instructions, prompt templates, and the structured output schema — is defined declaratively in a YAML config and loaded per request, which keeps prompt engineering out of the application code.
• Frontend (Next.js 15) — the user interface and a server-side proxy to the API. The browser only ever talks to the frontend; prediction calls are forwarded server-side, which keeps the API URL out of the client bundle and sidesteps CORS.
• Redis — stores per-conversation session memory so repeat calls only need to send the newest transcript chunk.
• MySQL — stores agent traces and spans for observability, written through a custom tracing exporter batched behind the OpenAI Agents SDK.

Streaming predictions

The API exposes a single POST /v1/predict endpoint designed to be called repeatedly as a conversation unfolds:

1. First call — the client sends session_id: null, the full ehr_data, and the first transcript chunk. The API creates a Redis-backed session, runs the agent, and returns a session_id alongside any notifications.
2. Subsequent calls — the client passes the returned session_id and only the next transcript chunk. The EHR context and prior turns live in the Redis session, so every follow-up request stays small.

This design keeps the per-call payload minimal while preserving the full conversational context on the server.

Tech stack

Layer	Technology
Inference API	FastAPI · Python 3.12 · uv · OpenAI Agents SDK
Frontend	Next.js 15 (App Router) · Node 22
Session store	Redis
Observability	MySQL 8.4 (traces & spans)
Packaging	Docker · multi-stage builds
Orchestration	Kubernetes (local via minikube) · HPA autoscaling

Deployment

The whole stack runs two ways from the same images. For local development, Docker Compose brings everything up with hot reload:

docker compose -f compose.yaml -f compose.dev.yaml up --build

For a cluster, the repository ships Kubernetes manifests for every component — Deployments, Services, a HorizontalPodAutoscaler on the API (1–5 replicas), a wait-for-mysql init container, health probes on /health, and a persistent volume for MySQL — deployable locally on minikube.

A short demo of the system reconciling a fictional encounter against a patient’s EHR summary is available in the demo video, and the full source, manifests, and documentation live in the GitHub repository.