A virtual consentbot that facilitates virtual conversations with patients.

MIA is designed to be deployed in a variaty of environments. If configurd properly it should work with any external application that presents properly formatted API requests with appropirate authentication credentials.

This repository is composed of two serivce applications. The server application is a Django API DB and the client application is a Redux/React UI.

This project is licensed under the Creative Commons Attribution–NonCommercial 4.0 International License (CC BY-NC 4.0).

You may share and adapt the material for noncommercial purposes, provided that you give appropriate credit.
See the full license or the Creative Commons page.

• Local deployment
  • For develpment or internal use only
• Production deployment
  • For deployment that is exposed to the internet
• Docker deployment
  • WIP: coming soon

• Contribution Guide lines
• FAQ and trouble shooting
• .secretes configuration
• Testing

The MIA Consent Chat Engine is a graph-driven, stateful conversation system designed to guide users through personalized consent flows for research studies. It combines structured metadata, dynamic branching, and real-time user interactions to deliver a responsive and compliant experience.

• The chat script is structured as a Directed Acyclic Graph (DAG).
• Each node represents either a bot message or a user input.
• Nodes contain:
  • type: "bot" or "user"
  • messages: List of strings (bot dialog or button labels)
  • child_ids: IDs of next nodes
  • render_type: "button", "form", "image", "video", etc.
  • render_content: optional image/video/form JSON
  • metadata: includes flags like workflow, end_sequence, etc.

{
  "type": "bot",
  "messages": ["Welcome to the study!"],
  "child_ids": ["abc123"],
  "render_type": "button",
  "metadata": {
    "workflow": "start_consent",
    "end_sequence": false
  }
}

• Chat starts at a designated node (start_consent) defined in the script.
• The conversation graph is loaded from a ConsentScript JSON blob.
• An invite link (invite_id) associates each session with a user.

• The engine uses process_consent_sequence() to collect all bot messages until a user response is needed.
• Bot messages are delivered with a typing delay for realism.
• Responses are rendered as Ant Design buttons or forms.

• Clicking a button or submitting a form dispatches a Redux thunk (submitConsentResponse).
• Backend handles form logic via custom processors like:
  • handle_family_enrollment_form
  • handle_phi_use
  • handle_result_return
• After form processing, the next node is determined and the process repeats.

• Nodes can belong to named workflows (e.g., "family_enrollment") via metadata.workflow.
• Dynamic workflows can be generated at runtime using generate_workflow().

• Form rendering from JSON (render_type: form)
• Typing indicator (“Mia is typing...”)
• Session timeout modal after inactivity
• Feedback, PHI, and result return forms handled as modular processors
• Dynamic sub-workflows depending on user inputs (e.g., enrolling child vs self)

Bot: Welcome to the PMGRC study
User: [👋 Hi Mia!]
Bot: Let me walk you through it...
Bot: Here’s what we’ll cover...
User: [Sounds good]
Bot: [Video or Image Rendered]
User: [Submit feedback form]