Usage Guide

A start-to-finish walkthrough: onboard a clinical trial, put Carmen in front of patients, and review what happened. Written for study coordinators and clinical staff; no programming required.

Getting started

How it works

MediMentor runs patient consultations through Carmen, a virtual health advocate with a video avatar (that is how Carmen introduces herself to patients). The whole pipeline looks like this:

1. Onboard a trial. Staff creates the trial, uploads its documents, extracts and verifies the structured record, and activates it.
2. Invite a patient. Staff sends the patient a one-time link tied to that trial.
3. The consultation. The patient talks to Carmen, who answers from the trial's reviewed content.
4. Review. Staff reads each conversation on the dashboard, including the full transcript.

The rest of this guide follows that exact order.

Signing in

All staff pages are protected with a shared password. When you open any admin page your browser shows a sign-in prompt:

• Username: admin (always)
• Password: ask your administrator (it is configured per deployment)

Patients never sign in. They use a one-time invite link (see Invite a patient).

Onboarding a trial

Draft vs. active

Every trial is in one of two states:

• Draft: visible only to staff. Carmen does not know about it and patients cannot be invited to it.
• Active: Carmen answers questions about it, and you can create patient invites for it.

A new trial starts as a draft and becomes active in five steps: create, upload documents, extract, review, activate. Each step is described below in order.

Step 1: Create the trial

On /admin, choose New trial. You only need a trial ID: a short, permanent identifier such as acadabra-her2-nsclc (letters, digits, dots, dashes, underscores; it cannot be changed later). The ID must be unique: if it is already taken, the form warns "Trial ID already exists" and nothing is created. Then pick one of the two buttons:

• Create & Extract Documents (recommended): opens the onboarding wizard, which walks you through steps 2 to 5.
• Create & Enter Manually: takes you straight to the trial detail page to type everything yourself (skip to step 4).

Step 2: Upload documents

On the trial's onboarding or detail page, upload the source documents (protocol synopsis, prescribing information, consent forms, and so on).

Each document row shows a colored status label:

You can download the original file or delete a document at any time. You can also add documents later, after the trial is already set up or live: open the trial's Documents tab, upload the file, and click Index & Activate so the new document is indexed. Any document change puts the trial back into draft until you do.

Step 3: Extract trial information

Extract reads the uploaded documents with an AI model and pre-fills the trial's structured sections: general info, study details, dosing, visit schedule, inclusion/exclusion criteria, prohibited medications, and side effects.

• Extraction overwrites the sections it manages with what it found, so run it before manual corrections, not after.
• Values that don't pass validation are reported as warnings next to the affected section and skipped, so one bad value never blocks the rest.
• Extraction never activates anything: the result is a draft for you to review.

Step 4: Review and edit the record

The trial detail page shows the record in tabs: General (trial and study information), Criteria (inclusion and exclusion), Treatment (dosing and prohibited medications), Visit Schedule, Side Effects, and Documents. Edit any tab and save. Each save checks the values (for example, visit days must be positive whole numbers and criterion IDs must not repeat). If something is invalid, a warning appears at the top of that section naming the exact field.

Step 5: Activate

Activate does two things in one step: it indexes every uploaded document so Carmen can search them, then flips the trial to active. If any document fails to index, the trial stays in draft and the error is shown. Nothing goes half-live.

Once active, the trial appears in the invite page's trial list and Carmen starts using its content. You're ready to invite a patient.

Running consultations

Invite a patient

Patients access Carmen through one-time invite links created on /admin/invites:

1. Pick the (active) trial the patient belongs to.
2. Optionally add a label for your own bookkeeping, e.g. "Pt. 0142 (Dr. Weber's clinic)". The patient never sees it.
3. Copy the generated link and send it to the patient through your usual channel.

Invite links are:

• Single-use: the first person to start the consultation consumes the link.
• Time-limited: they expire 7 days after creation.

Test it yourself

To experience exactly what the patient will, use the test session button on the admin pages: it opens the consultation console for a chosen trial without consuming an invite. Test conversations show up on the dashboard like real ones, so end them properly (or note the time) to keep them easy to tell apart.

The patient experience

What the patient experiences after opening their invite link:

1. A welcome page introduces the trial; they press start.
2. Carmen appears as a video avatar and greets them with a short introduction.
3. They talk naturally (or type). Carmen answers from the trial's curated record and documents: side effects, visit schedule, dosing, eligibility questions, practical concerns.
4. The patient can interrupt Carmen mid-sentence (barge-in) just like a phone call; Carmen stops and listens.
5. Ending the consultation finalizes it (see Reviewing) and their link cannot be used again.

• Sessions stay valid for 7 days: a patient can close the tab and come back with the same link on the same device.
• Carmen is instructed to stay within the trial's reviewed content and to defer medical judgment to the care team.

Reviewing

Conversations

/dashboard lists every conversation that has stored history, including ones still in progress. Each row shows the trial, the start time, and the message count. Open a conversation to read its full transcript.

The top of the page shows four totals across all conversations: how many there are, the average number of messages, how many started today, and the average duration. You can filter the list by minimum message count, or search by trial or conversation ID.

Upkeep

Updating a live trial

Any change to an active trial (editing a section, uploading or deleting a document) automatically puts it back into draft. This is a safety feature: staff must explicitly re-activate (and thereby re-index) before patients see the changed content.

• Deactivate immediately returns an active trial to draft, for example while making corrections. Patients with open sessions stop getting that trial's content on their next question.
• Delete removes the trial together with its documents and search index. Conversations are kept.

Resets

Two administrative reset operations exist for recovery scenarios. Both are irreversible, so read carefully:

Troubleshooting