ICUlater / MediKaki

ICUlater is a hackathon prototype for MediKaki, a Singapore-focused medication adherence companion for elderly chronic disease patients and their caregivers. The bot runs through Telegram for the demo, mirrors a WhatsApp-first product flow, uses Gemini for bounded medication conversation routing, and generates a clinician-facing Clinic Card before visits.

The core idea is Behavioral Adherence Intelligence: when a dose is missed, the system tries to identify why it happened (forgetful, side-effect driven, access/logistics, intentional, or confusion-driven) and responds with the right follow-up instead of sending the same reminder again.

Repository Layout

Path	Purpose
iculater/	Main Python application code and agent/tool functions. Start here for backend behavior.
clinic_card/	Generated Clinic Card report template and related card documentation. This is not a full frontend app.
scripts/	Runnable utilities for validation, Clinic Card preview generation, and Telegram smoke testing.
notebooks/	Interactive Telegram bot runner used for the demo flow.
docs/	Planning, pitch, and demo documents. docs/PS1_PLAN.md is the main plan document.
data/	Demo patient profile, medication knowledge base, hawker food knowledge base, UID mapping, and runtime logs.
prompts/	Prompt material used by the BAI classifier.
output/	Generated local artifacts such as clinic_card_preview.html. This directory is ignored by git.

Main Workflows

Install dependencies:

pip install -e ".[dev]"

Run the full demo data/template validation:

python scripts/validate_all.py

Generate the Clinic Card preview:

python scripts/preview_clinic_card.py

Run the minimal Telegram /start smoke test:

export TELEGRAM_BOT_TOKEN="your-token"
python scripts/test_telegram_start.py

Run the full notebook demo from notebooks/tg_bot.ipynb. The notebook expects TELEGRAM_BOT_TOKEN and optionally GEMINI_API_KEY, GEMINI_MODEL, PATIENT_CHAT_ID, and CAREGIVER_CHAT_ID in the environment.

Important Files

• Main app functions: iculater/ai_functions.py
• Backward-compatible import shim: tg_bot_AI_functions.py
• Clinic Card template: clinic_card/templates/clinic_card.html.j2
• Product and pitch plan: docs/PS1_PLAN.md
• Demo conversation script: docs/demo_script.md
• Demo notebook: notebooks/tg_bot.ipynb

Notes

Do not commit live API tokens or chat IDs. Use environment variables or a local .env file for secrets.