An LLM-powered chatbot for hospital appointment scheduling. Patients and doctors interact through natural language (typed or spoken), and a two-stage LLM pipeline turns that into structured actions against a Postgres-backed scheduling system.
- Frontend capture — a Next.js UI collects a message via text (
chat.tsx) or voice (voice-capture.tsx, using OpenAI's Realtime API), and packages it withsession_id,timezone, andinput_modeinto a single payload sent to/chat/textor/chat/voice. For voice, the frontend first exchanges its auth token for a short-lived ephemeral Realtime session token via the backend (/realtime/session), so the permanent OpenAI key never reaches the browser. - Intent extraction — the FastAPI backend calls GPT-4 with function calling (
run_llm_extract_intent) to convert the message and recent conversation memory into a structured{action, arguments}object. - Action dispatch —
handle_action_dispatchroutes the structured intent to the matching handler: booking, cancelling, or rescheduling an appointment; showing appointments or a doctor's schedule; reactivating a time segment; creating or cancelling a doctor event. Slot bookings and event changes run as atomic Postgres stored procedures (via Supabase) to stay consistent under concurrent requests. - Natural-language reply — a second GPT-4 call turns the handler's structured result back into a plain-language response, which is logged (
conversationstable) and returned to the frontend.
Invalid input (e.g. an out-of-range slot number, a nonexistent appointment) falls back to a clarifying prompt instead of failing silently.
- Role-based flows for patients and doctors, with registration, login, and session auth via Supabase.
- Text and voice input through the same intent-extraction/dispatch pipeline.
- Per-session conversational memory, and a slot-index-to-time-segment mapping layer so the LLM only ever refers to "option 1 / 2 / 3" rather than raw database IDs.
- Appointment booking, cancellation, and rescheduling; doctor schedule viewing; doctor-created events.
- Voice sessions authenticate with a short-lived ephemeral token minted server-side (
POST /realtime/session), instead of shipping the permanent OpenAI API key to the browser.
Python · FastAPI · OpenAI API (GPT-4, function calling) · Supabase (Postgres + Auth) · Next.js 15 / React 19 · Tailwind CSS · OpenAI Realtime API (voice)
├── backend/
│ ├── chatbot_services.py # Intent extraction, reply generation, action handlers
│ ├── llm_client.py # OpenAI API wrapper (function calling + chat completion)
│ ├── main.py # FastAPI entry point, auth, chat routing, realtime session minting
│ └── supabase_utils.py # Supabase auth, appointments, schedules, conversation log
│
├── frontend/
│ └── src/
│ ├── components/
│ │ ├── chat/
│ │ │ ├── chat.tsx # Text-based chat interface
│ │ │ └── voice-capture.tsx # Realtime voice chat interface
│ │ └── login_ui/, icons/, etc. # UI components
│ └── app/, auth/, etc. # App routing and auth context
│
└── supabase/
└── schema.sql # Postgres schema: registration, appointments, time segments, audit log
This project isn't deployed publicly — the instructions below are for running it locally with your own Supabase project and OpenAI API key. Requires Python 3.12 and Node.js. Create backend/.env and frontend/.env.local — see backend/.env.example and frontend/.env.local.example for the required variables. Only the backend needs the real OPENAI_API_KEY; the frontend obtains a voice session token from the backend at runtime.
The backend runs on port 8000 and the frontend on port 3000; CORS is configured for http://localhost:3000 specifically, so use localhost rather than 127.0.0.1.
# Backend
cd backend
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn main:app --reload
# Frontend
cd frontend
npm install
npm run devOnce both services are running, open http://localhost:3000.
supabase/schema.sql defines the full schema (doctor/patient registration, shifts, available time segments, appointments and requests, conversation log, audit log) — run it against your own Supabase project to bootstrap the database. No seed data or credentials are included in this repo.
Team project for Intelligent Health Informatics (DTI 6302), University of Ottawa. Team members: Patrica Huang, Rang Zhang.