updates

README.md

@@ -1,138 +1,15 @@
 ---
 title: Sokrates
-colorFrom: blue
-colorTo: indigo
+emoji: 🐨
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 4.44.0
-python_version: "3.11"
+sdk_version: 6.18.0
+python_version: '3.13'
 app_file: app.py
 pinned: false
 license: mit
-short_description: AI-assisted clinical intake assistant
+short_description: listens, structures the form, suggests follow-up questions
 ---
 
-# Sokrates
-
-🔗 **Social Media Post + Video:** https://x.com/guidoputignano/status/2065494688501506353
-
-AI-assisted **clinical intake** for a medical visit. Sokrates listens to a
-doctor–patient conversation, transcribes it, automatically fills in a structured
-clinical intake form, and suggests the questions the doctor still needs to ask.
-
-Two sources of suggested questions:
-1. **Gaps** — mandatory form fields that are still empty (deterministic engine).
-2. **Clinical follow-ups** — coherent next questions generated by the LLM.
-
-> **Sokrates does not make diagnoses.** It prepares and structures data collection.
-
-## Architecture
-
-```
-audio -> ASR (+ optional diarization) -> orchestration loop ->
-  [structured extraction + gap engine + question generation] -> three-panel UI
-```
-
-- **UI**: Gradio Blocks, three columns — live transcript, the intake form filling
-  in (green = filled, grey = missing), and a suggested-questions panel.
-- **ASR**: `faster-whisper` (large-v3), `language="en"`. Uploaded audio file
-  (priority) and live microphone. Optional diarization via `pyannote` behind a flag.
-- **LLM**: any OpenAI-compatible endpoint (e.g. a vLLM server on Modal running
-  **Qwen3-14B**, ≤ 32B params). Configured purely through environment variables.
-- **Schema**: oncology intake form as a Pydantic model (`sokrates/schema.py`).
-
-## How to use
-
-1. Provide a transcript one of three ways:
-   - **Sample dialogue** — pick one and click *Load sample* (no audio needed).
-   - **Upload / record a file** — click *Transcribe audio* to run ASR.
-   - **Live microphone** — switch to the *Live microphone* tab and speak;
-     Sokrates transcribes and updates the form automatically on pauses.
-2. Click **Analyze transcript → update** (for the upload/sample paths).
-3. Watch the **clinical form** fill in (green = filled, grey = optional missing,
-   red-tinted = mandatory still missing) and the **suggested questions** appear
-   (missing mandatory fields first, then coherent follow-ups). *Reset* clears the
-   session.
-
-## Modules
-
-| File                        | Role                                                        |
-| --------------------------- | ----------------------------------------------------------- |
-| `sokrates/schema.py`        | Oncology intake form (Pydantic) + field metadata + merge.   |
-| `sokrates/asr.py`           | faster-whisper transcription (file + live mic), diarization.|
-| `sokrates/llm.py`           | OpenAI-compatible client: extraction + question generation. |
-| `sokrates/gaps.py`          | Deterministic gap engine (no LLM).                          |
-| `sokrates/orchestrator.py`  | The loop: extract → gaps → questions.                       |
-| `app.py`                    | Gradio three-panel UI.                                       |
-
-## Local run
-
-```bash
-python -m venv .venv && source .venv/bin/activate
-pip install -r requirements.txt
-python app.py
-```
-
-Open the local URL Gradio prints (default http://127.0.0.1:7860).
-
-## Configuration (environment variables)
-
-No credentials live in the code. The LLM client is configured at runtime:
-
-| Variable            | Purpose                                         | Example                                  |
-| ------------------- | ----------------------------------------------- | ---------------------------------------- |
-| `MODEL_BASE_URL`    | OpenAI-compatible base URL                       | `https://your-modal-app.modal.run/v1`    |
-| `MODEL_API_KEY`     | API key / token for the endpoint                 | `sk-...` (or any token your server wants)|
-| `MODEL_NAME`        | Model identifier served by the endpoint          | `Qwen/Qwen3-14B`                         |
-| `ENABLE_DIARIZATION`| `1` to enable pyannote diarization (optional)    | `0`                                      |
-| `WHISPER_MODEL`     | faster-whisper model size                        | `large-v3`                               |
-| `HF_TOKEN`          | Hugging Face token (only if using pyannote)      | `hf_...`                                 |
-| `SOKRATES_GUIDED_JSON` | `1` to use vLLM `guided_json` instead of `response_format` | `0`                  |
-| `SOKRATES_NO_THINK` | `1` to disable Qwen3 thinking (faster, terser)   | `0`                                      |
-| `MODEL_TEMPERATURE` | sampling temperature (extraction uses `0.0`)     | `0.0`                                    |
-
-### Pointing at a Modal vLLM endpoint
-
-This repo ships a ready-to-deploy Modal script (`modal_vllm.py`) that serves
-**Qwen3-14B** as an OpenAI-compatible vLLM endpoint.
-
-```bash
-# 1. One-time setup
-pip install modal
-modal token new
-# Choose the API key the endpoint will require (reuse it as MODEL_API_KEY):
-modal secret create sokrates-llm MODEL_API_KEY=sk-sokrates-demo-123
-
-# 2. Deploy (prints a https://...-serve.modal.run URL)
-modal deploy modal_vllm.py
-
-# 3. Point the app at it (note the trailing /v1)
-export MODEL_BASE_URL="https://<your-workspace>--sokrates-qwen3-14b-serve.modal.run/v1"
-export MODEL_API_KEY="sk-sokrates-demo-123"   # must match the secret
-export MODEL_NAME="Qwen/Qwen3-14B"
-export SOKRATES_GUIDED_JSON=1                 # vLLM enforces the JSON schema
-python app.py
-```
-
-Smoke-test the endpoint before launching the app:
-
-```bash
-curl $MODEL_BASE_URL/models -H "Authorization: Bearer $MODEL_API_KEY"
-```
-
-No code changes are required to switch endpoints — only these variables.
-
-## Deploy to a Hugging Face Space
-
-1. Create a new **Gradio** Space.
-2. Push this repo to the Space (or connect the GitHub repo).
-3. In **Settings → Variables and secrets**, add `MODEL_BASE_URL`, `MODEL_API_KEY`,
-   `MODEL_NAME` (and `HF_TOKEN` if using diarization) as **secrets**.
-4. The Space runs `app.py` automatically.
-
-## Sample dialogues
-
-Synthetic, English-only doctor–patient conversations live in `data/`:
-- `data/sample_dialogue_1.txt` — lung mass intake.
-- `data/sample_dialogue_2.txt` — breast lump intake.
-
-No real patient data is used anywhere in this project.
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -1,587 +0,0 @@
-"""Sokrates — Gradio entrypoint.
-
-Three-column clinical UI:
-  1. Live transcript (uploaded audio, live microphone, or a sample dialogue)
-  2. Clinical intake form filling in (green = filled, grey = missing)
-  3. Suggested questions for the doctor (missing mandatory fields + follow-ups)
-
-The flow is: audio -> ASR -> orchestration loop
-(structured extraction + gap engine + question generation) -> this UI.
-Sokrates does NOT make diagnoses; it structures data collection.
-"""
-
-from __future__ import annotations
-
-import glob
-import os
-
-import gradio as gr
-
-# Work around a gradio_client 1.3.0 bug: building the API schema crashes with
-# "argument of type 'bool' is not iterable" when a JSON schema contains boolean
-# values (e.g. additionalProperties: true). That crash makes Gradio's launch
-# health check think localhost is unreachable and abort. Tolerate bool schemas.
-import gradio_client.utils as _gcu
-
-_orig_json_to_pytype = _gcu._json_schema_to_python_type
-_orig_get_type = _gcu.get_type
-
-
-def _safe_json_to_pytype(schema, defs=None):
-    if isinstance(schema, bool):
-        return "Any"
-    return _orig_json_to_pytype(schema, defs)
-
-
-def _safe_get_type(schema):
-    if not isinstance(schema, dict):
-        return "Any"
-    return _orig_get_type(schema)
-
-
-_gcu._json_schema_to_python_type = _safe_json_to_pytype
-_gcu.get_type = _safe_get_type
-
-from sokrates import asr
-from sokrates.orchestrator import process_transcript
-from sokrates.schema import (
-    FIELD_META,
-    IntakeForm,
-    coerce_form,
-    format_value,
-    is_empty,
-)
-
-DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
-
-CUSTOM_CSS = """
-:root {
-    --sok-primary: #0e7490; --sok-primary-dark: #0b5566;
-    --sok-accent: #2563eb; --sok-green: #16a34a; --sok-red: #dc2626;
-    --sok-bg: #eef2f6; --sok-card: #ffffff; --sok-border: #e2e8f0;
-    --sok-text: #1e293b; --sok-muted: #64748b;
-}
-.gradio-container { background: var(--sok-bg) !important; max-width: 1400px !important; }
-footer { display: none !important; }
-
-/* Header banner */
-.sok-banner {
-    background: linear-gradient(120deg, #0e7490 0%, #0891b2 50%, #2563eb 100%);
-    border-radius: 16px; padding: 1.1rem 1.4rem; margin-bottom: 0.4rem;
-    color: #fff; box-shadow: 0 6px 20px rgba(8,89,110,0.25);
-    display: flex; align-items: center; gap: 1rem;
-}
-.sok-logo {
-    width: 52px; height: 52px; border-radius: 14px; flex: 0 0 auto;
-    background: rgba(255,255,255,0.18); display: flex; align-items: center;
-    justify-content: center; font-size: 1.7rem;
-}
-.sok-banner h1 { margin: 0; font-size: 1.7rem; font-weight: 800; letter-spacing: 0.3px; }
-.sok-banner .sub { opacity: 0.92; font-size: 0.92rem; margin-top: 0.15rem; }
-.sok-badge {
-    margin-left: auto; background: rgba(255,255,255,0.16);
-    border: 1px solid rgba(255,255,255,0.3); border-radius: 999px;
-    padding: 0.35rem 0.85rem; font-size: 0.78rem; font-weight: 600; white-space: nowrap;
-}
-.sok-steps { display: flex; gap: 0.5rem; margin: 0.5rem 0 0.2rem 0; }
-.sok-step {
-    flex: 1; background: var(--sok-card); border: 1px solid var(--sok-border);
-    border-radius: 10px; padding: 0.45rem 0.7rem; font-size: 0.8rem; color: var(--sok-muted);
-}
-.sok-step b { color: var(--sok-primary); }
-
-/* Cards */
-.panel-card {
-    background: var(--sok-card); border: 1px solid var(--sok-border); border-radius: 16px;
-    padding: 1rem 1.1rem; box-shadow: 0 2px 10px rgba(16,40,70,0.06); min-height: 480px;
-}
-.panel-title {
-    font-weight: 700; color: var(--sok-text); margin-bottom: 0.7rem; font-size: 1.02rem;
-    display: flex; align-items: center; gap: 0.5rem;
-}
-.panel-title .chip {
-    width: 30px; height: 30px; border-radius: 9px; display: inline-flex;
-    align-items: center; justify-content: center; font-size: 1rem;
-    background: #ecfeff; color: var(--sok-primary);
-}
-
-/* Progress */
-.progress-wrap { margin: 0.1rem 0 0.9rem 0; }
-.progress-bar { height: 9px; border-radius: 999px; background: #eef2f6; overflow: hidden; }
-.progress-fill {
-    height: 100%; border-radius: 999px;
-    background: linear-gradient(90deg, #22c55e, #16a34a); transition: width 0.5s ease;
-}
-.progress-label {
-    font-size: 0.78rem; color: var(--sok-muted); margin-top: 0.3rem;
-    display: flex; justify-content: space-between;
-}
-.progress-label b { color: var(--sok-text); }
-
-/* Form rows */
-.form-row {
-    display: flex; align-items: center; gap: 0.6rem;
-    padding: 0.45rem 0.55rem; border-radius: 10px; margin-bottom: 0.32rem;
-    border: 1px solid transparent; transition: transform 0.12s ease, box-shadow 0.12s ease;
-}
-.form-row:hover { transform: translateX(2px); }
-.form-row .ic {
-    width: 20px; height: 20px; border-radius: 50%; flex: 0 0 auto; color: #fff;
-    display: inline-flex; align-items: center; justify-content: center; font-size: 0.7rem;
-}
-.form-row .label { flex: 1; color: var(--sok-text); font-size: 0.9rem; font-weight: 500; }
-.form-row .value {
-    color: var(--sok-text); font-size: 0.85rem; font-weight: 600;
-    background: #f1f5f9; border-radius: 999px; padding: 0.15rem 0.6rem; max-width: 55%;
-    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
-}
-.form-row.filled  { background: #f0fdf4; border-color: #dcfce7; }
-.form-row.filled  .ic { background: var(--sok-green); }
-.form-row.filled  .value { background: #dcfce7; color: #166534; }
-.form-row.missing { background: #f8fafc; }
-.form-row.missing .ic { background: #cbd5e1; }
-.form-row.missing.req-missing { background: #fef2f2; border-color: #fee2e2; }
-.form-row.missing.req-missing .ic { background: var(--sok-red); }
-.form-row .req { color: var(--sok-red); font-size: 0.7rem; margin-left: 3px; font-weight: 700; }
-
-/* Questions */
-.q-item {
-    background: #f8fbff; border: 1px solid #e3edfb; border-left: 4px solid var(--sok-accent);
-    border-radius: 10px; padding: 0.65rem 0.8rem; margin-bottom: 0.55rem; color: #1e3a5f;
-    font-size: 0.92rem; display: flex; align-items: flex-start; gap: 0.6rem;
-    box-shadow: 0 1px 4px rgba(37,99,235,0.06); transition: transform 0.12s ease;
-}
-.q-item:hover { transform: translateY(-1px); box-shadow: 0 3px 10px rgba(37,99,235,0.12); }
-.q-num {
-    flex: 0 0 auto; min-width: 1.5rem; height: 1.5rem; line-height: 1.5rem; text-align: center;
-    background: var(--sok-accent); color: #fff; border-radius: 50%; font-size: 0.78rem; font-weight: 700;
-}
-.gaps-note {
-    background: #fffbeb; border: 1px solid #fde68a; color: #92400e; font-size: 0.8rem;
-    border-radius: 9px; padding: 0.45rem 0.65rem; margin-bottom: 0.7rem;
-}
-.gaps-note b { color: #b45309; }
-.empty-state { color: var(--sok-muted); font-size: 0.88rem; text-align: center; padding: 1.5rem 0.5rem; }
-.disclaimer {
-    color: #94a3b8; font-size: 0.76rem; margin-top: 0.7rem; font-style: italic;
-    border-top: 1px dashed var(--sok-border); padding-top: 0.5rem;
-}
-/* Status pill — always clearly visible */
-.sok-status {
-    background: #ecfeff; border: 1px solid #a5f3fc; border-radius: 10px;
-    padding: 0.55rem 0.85rem; margin-top: 0.55rem;
-}
-.sok-status p, .sok-status span, .sok-status {
-    margin: 0 !important; color: #0b5566 !important;
-    font-weight: 600 !important; font-size: 0.92rem !important;
-}
-
-/* Transcript box — force readable light styling even in OS dark mode */
-.sok-transcript textarea {
-    background: #ffffff !important; color: #1e293b !important;
-    border: 1px solid var(--sok-border) !important; border-radius: 10px !important;
-    font-size: 0.9rem !important; line-height: 1.4 !important;
-}
-.sok-transcript textarea::placeholder { color: #94a3b8 !important; }
-"""
-
-
-def render_form_html(form: IntakeForm) -> str:
-    """Render the intake form: green = filled, grey = optional-missing,
-    red-tinted = mandatory-missing. Includes a mandatory-completeness bar."""
-    rows = []
-    filled_mand = total_mand = 0
-    for meta in FIELD_META:
-        value = getattr(form, meta.name)
-        filled = not is_empty(value)
-        if meta.mandatory:
-            total_mand += 1
-            filled_mand += int(filled)
-        css = "filled" if filled else "missing"
-        if not filled and meta.mandatory:
-            css += " req-missing"
-        req = '<span class="req">*</span>' if meta.mandatory else ""
-        icon = "✓" if filled else ("!" if meta.mandatory else "")
-        value_html = (
-            f'<span class="value">{format_value(value)}</span>' if filled else ""
-        )
-        rows.append(
-            f'<div class="form-row {css}">'
-            f'<span class="ic">{icon}</span>'
-            f'<span class="label">{meta.label}{req}</span>'
-            f"{value_html}"
-            f"</div>"
-        )
-    pct = int(100 * filled_mand / total_mand) if total_mand else 0
-    progress = (
-        '<div class="progress-wrap">'
-        f'<div class="progress-bar"><div class="progress-fill" '
-        f'style="width:{pct}%"></div></div>'
-        f'<div class="progress-label"><span>Mandatory fields</span>'
-        f"<b>{filled_mand}/{total_mand} complete</b></div></div>"
-    )
-    return (
-        '<div class="panel-card">'
-        '<div class="panel-title"><span class="chip">🩺</span>'
-        "Clinical intake form</div>"
-        + progress
-        + "".join(rows)
-        + '<div class="disclaimer">* mandatory field. '
-        "Sokrates structures data collection — it does not make diagnoses.</div>"
-        "</div>"
-    )
-
-
-def render_questions_html(questions: list[str], missing: list[str] | None = None) -> str:
-    """Render the suggested-questions panel with optional missing-field note."""
-    missing = missing or []
-    note = ""
-    if missing:
-        note = (
-            '<div class="gaps-note">📋 <b>Still missing (mandatory):</b> '
-            + ", ".join(missing)
-            + "</div>"
-        )
-    if not questions:
-        items = (
-            '<div class="empty-state">💬 No suggested questions yet.<br>'
-            "Analyze the transcript to generate them.</div>"
-        )
-    else:
-        items = "".join(
-            f'<div class="q-item"><span class="q-num">{i}</span>'
-            f"<span>{q}</span></div>"
-            for i, q in enumerate(questions, start=1)
-        )
-    return (
-        '<div class="panel-card">'
-        '<div class="panel-title"><span class="chip">💡</span>'
-        "Suggested questions</div>"
-        + note
-        + items
-        + "</div>"
-    )
-
-
-# --- Sample dialogues (synthetic, English) -------------------------------
-
-def list_sample_dialogues() -> dict[str, str]:
-    """Map a friendly label -> file path for each sample dialogue in data/."""
-    samples: dict[str, str] = {}
-    for path in sorted(glob.glob(os.path.join(DATA_DIR, "sample_dialogue_*.txt"))):
-        label = (
-            os.path.splitext(os.path.basename(path))[0]
-            .replace("sample_dialogue_", "Sample dialogue ")
-            .replace("_", " ")
-        )
-        samples[label] = path
-    return samples
-
-
-SAMPLE_DIALOGUES = list_sample_dialogues()
-
-
-def load_sample_dialogue(label: str) -> str:
-    """Return the text of a sample dialogue (used in place of ASR for the demo)."""
-    path = SAMPLE_DIALOGUES.get(label)
-    if not path or not os.path.exists(path):
-        return ""
-    with open(path, "r", encoding="utf-8") as fh:
-        return fh.read().strip()
-
-
-def transcribe_audio(audio_path: str | None) -> str:
-    """Run ASR on an uploaded/recorded audio file and return the transcript."""
-    if not audio_path:
-        return ""
-    try:
-        return asr.transcribe_file(audio_path)
-    except Exception as exc:  # surface ASR/setup errors in the UI, don't crash
-        return f"[ASR error] {exc}"
-
-
-# --- Orchestration (Step 5) ----------------------------------------------
-
-def analyze_transcript(transcript: str, form: IntakeForm):
-    """Run the full loop on the current transcript and repaint all panels.
-
-    Implemented as a generator so the UI shows instant "Analyzing…" feedback
-    before the (slower) model round-trip completes. Yields tuples of
-    (form_state, form_html, questions_html, status_markdown).
-    """
-    form = coerce_form(form)  # Gradio State may hand back a dict
-    if not transcript or not transcript.strip():
-        yield (
-            form,
-            render_form_html(form),
-            render_questions_html([]),
-            "⚠️ Transcript is empty — load a sample or transcribe audio first.",
-        )
-        return
-    # Immediate feedback while the model runs.
-    yield (
-        form,
-        render_form_html(form),
-        render_questions_html([]),
-        "⏳ Analyzing transcript with the model… (first call may be slower)",
-    )
-    try:
-        result = process_transcript(transcript, form)
-    except Exception as exc:  # never surface a raw 'Error' badge to the user
-        import traceback
-
-        traceback.print_exc()  # full detail in the terminal
-        yield (
-            form,
-            render_form_html(form),
-            render_questions_html([]),
-            f"⚠️ Error: {exc}",
-        )
-        return
-    yield (
-        result.form,
-        render_form_html(result.form),
-        render_questions_html(result.questions, result.missing_mandatory),
-        "✅ " + result.status,
-    )
-
-
-def reset_session():
-    """Clear the form, questions and transcript to start a fresh visit."""
-    empty = IntakeForm()
-    return (
-        empty,
-        render_form_html(empty),
-        render_questions_html([]),
-        "",
-        "Session reset.",
-    )
-
-
-# --- Live microphone: record a segment, transcribe + analyze on stop ---
-#
-# Gradio 4.x's streaming-microphone (`gr.Audio(streaming=True)` + `.stream()`)
-# is unreliable — chunks are often never delivered to the callback, so live
-# streaming silently captures nothing. We instead record a clip and process it
-# on `stop_recording`, reusing the same file-transcription path that the
-# Upload/sample tab already relies on. The user records a segment, pauses, and
-# Sokrates transcribes it and updates the form; recording again appends more.
-
-def record_and_analyze(audio_path: str | None, transcript: str, form: IntakeForm):
-    """Transcribe a recorded mic clip, append it, and run the full loop.
-
-    Implemented as a generator so the UI shows instant feedback before the
-    (slower) ASR + model round-trip completes. Yields tuples of
-    (transcript, form_html, questions_html, status_markdown, form_state).
-    """
-    form = coerce_form(form)  # Gradio State may hand back a dict
-    if not audio_path:
-        yield (
-            transcript,
-            render_form_html(form),
-            render_questions_html([]),
-            "🎙️ No audio captured — click record, speak, then stop.",
-            form,
-        )
-        return
-    yield (
-        transcript,
-        render_form_html(form),
-        render_questions_html([]),
-        "⏳ Transcribing the recording…",
-        form,
-    )
-    try:
-        text = asr.transcribe_file(audio_path)
-    except Exception as exc:
-        import traceback
-
-        traceback.print_exc()
-        yield (
-            transcript,
-            render_form_html(form),
-            render_questions_html([]),
-            f"⚠️ ASR error: {exc}",
-            form,
-        )
-        return
-    if not text:
-        yield (
-            transcript,
-            render_form_html(form),
-            render_questions_html([]),
-            "🎙️ No speech detected in that recording — try again.",
-            form,
-        )
-        return
-    new_transcript = (transcript + "\n" + text).strip() if transcript else text
-    try:
-        result = process_transcript(new_transcript, form)
-    except Exception as exc:
-        import traceback
-
-        traceback.print_exc()
-        yield (
-            new_transcript,
-            render_form_html(form),
-            render_questions_html([]),
-            f"⚠️ Error: {exc}",
-            form,
-        )
-        return
-    yield (
-        new_transcript,
-        render_form_html(result.form),
-        render_questions_html(result.questions, result.missing_mandatory),
-        "✅ " + result.status,
-        result.form,
-    )
-
-
-DEFAULT_TRANSCRIPT = (
-    "Load a sample dialogue, upload an audio file, or use the microphone, "
-    "then click “Analyze transcript”."
-)
-
-# Force light mode regardless of the OS/browser theme, so the clinical look is
-# consistent and every component stays readable (reloads once with __theme=light).
-FORCE_LIGHT_JS = """
-() => {
-  const url = new URL(window.location.href);
-  if (url.searchParams.get('__theme') !== 'light') {
-    url.searchParams.set('__theme', 'light');
-    window.location.replace(url.href);
-  }
-}
-"""
-
-
-def build_demo() -> gr.Blocks:
-    theme = gr.themes.Soft(
-        primary_hue=gr.themes.colors.cyan,
-        secondary_hue=gr.themes.colors.blue,
-        font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
-    )
-    with gr.Blocks(
-        css=CUSTOM_CSS, title="Sokrates", theme=theme, js=FORCE_LIGHT_JS
-    ) as demo:
-        gr.HTML(
-            '<div class="sok-banner">'
-            '<div class="sok-logo">⚕️</div>'
-            "<div><h1>Sokrates</h1>"
-            '<div class="sub">AI-assisted clinical intake — listens, structures '
-            "the form, and suggests follow-up questions.</div></div>"
-            '<div class="sok-badge">🔒 No diagnoses · data collection only</div>'
-            "</div>"
-            '<div class="sok-steps">'
-            '<div class="sok-step"><b>1 · Listen</b> — transcribe the visit</div>'
-            '<div class="sok-step"><b>2 · Structure</b> — fill the intake form</div>'
-            '<div class="sok-step"><b>3 · Ask</b> — suggest the next questions</div>'
-            "</div>"
-        )
-
-        form_state = gr.State(IntakeForm())
-
-        with gr.Row(equal_height=False):
-            # --- Column 1: transcript & input ---
-            with gr.Column(scale=1):
-                gr.HTML('<div class="panel-title">🎙️ Live transcript</div>')
-                with gr.Tab("Upload / sample"):
-                    audio_in = gr.Audio(
-                        sources=["upload", "microphone"],
-                        type="filepath",
-                        label="Upload an audio file (or record)",
-                    )
-                    transcribe_btn = gr.Button(
-                        "Transcribe audio", variant="secondary"
-                    )
-                    with gr.Row():
-                        sample_dd = gr.Dropdown(
-                            choices=list(SAMPLE_DIALOGUES.keys()),
-                            label="Or load a sample dialogue",
-                            scale=3,
-                        )
-                        sample_btn = gr.Button("Load sample", scale=1)
-                with gr.Tab("Live microphone"):
-                    mic_in = gr.Audio(
-                        sources=["microphone"],
-                        type="filepath",
-                        label="Record the visit — transcribes when you stop",
-                    )
-                    gr.Markdown(
-                        "Click record and speak; click stop when you pause. "
-                        "Sokrates transcribes the clip and updates the form. "
-                        "Record again to add more to the same visit."
-                    )
-
-                transcript_box = gr.Textbox(
-                    value="",
-                    placeholder=DEFAULT_TRANSCRIPT,
-                    lines=12,
-                    show_label=False,
-                    interactive=True,
-                    container=False,
-                    elem_classes="sok-transcript",
-                )
-                with gr.Row():
-                    analyze_btn = gr.Button(
-                        "Analyze transcript → update", variant="primary", scale=3
-                    )
-                    reset_btn = gr.Button("Reset", scale=1)
-                status_box = gr.Markdown(
-                    "Ready — load a transcript and click **Analyze**.",
-                    elem_classes="sok-status",
-                )
-
-            # --- Column 2: clinical form ---
-            with gr.Column(scale=1):
-                form_html = gr.HTML(render_form_html(IntakeForm()))
-
-            # --- Column 3: suggested questions ---
-            with gr.Column(scale=1):
-                questions_html = gr.HTML(render_questions_html([]))
-
-        # --- Wiring ---
-        transcribe_btn.click(
-            fn=transcribe_audio, inputs=audio_in, outputs=transcript_box
-        )
-        sample_btn.click(
-            fn=load_sample_dialogue, inputs=sample_dd, outputs=transcript_box
-        )
-        analyze_btn.click(
-            fn=analyze_transcript,
-            inputs=[transcript_box, form_state],
-            outputs=[form_state, form_html, questions_html, status_box],
-        )
-        reset_btn.click(
-            fn=reset_session,
-            inputs=None,
-            outputs=[
-                form_state,
-                form_html,
-                questions_html,
-                transcript_box,
-                status_box,
-            ],
-        )
-        mic_in.stop_recording(
-            fn=record_and_analyze,
-            inputs=[mic_in, transcript_box, form_state],
-            outputs=[
-                transcript_box,
-                form_html,
-                questions_html,
-                status_box,
-                form_state,
-            ],
-        )
-
-    return demo
-
-
-if __name__ == "__main__":
-    # Ensure localhost isn't routed through an HTTP proxy, which can otherwise
-    # make Gradio's post-launch health check fail ("localhost not accessible").
-    for _var in ("no_proxy", "NO_PROXY"):
-        os.environ[_var] = "localhost,127.0.0.1,0.0.0.0," + os.environ.get(_var, "")
-    build_demo().launch(server_name="0.0.0.0", server_port=7860)

data/sample_dialogue_1.txt

@@ -1,19 +0,0 @@
-Doctor: Good morning, please have a seat. What brings you in today?
-Patient: Good morning, doctor. I've had a persistent cough for about three weeks now, and lately I've been losing weight without trying.
-Doctor: I'm sorry to hear that. Can I confirm a few details first — how old are you?
-Patient: I'm 62 years old.
-Doctor: And you're a man, correct?
-Patient: Yes, that's right.
-Doctor: Besides the cough and the weight loss, any other symptoms? Shortness of breath, chest pain, coughing up blood?
-Patient: I do get a bit short of breath when I climb stairs, and once or twice there was a little blood when I coughed.
-Doctor: Thank you. Have you had any imaging done recently, like a chest X-ray or CT scan?
-Patient: Yes, my GP ordered a chest CT last week. They said there was a mass in my right lung.
-Doctor: I see. Has anyone performed a biopsy of that mass yet?
-Patient: No, not yet. They told me I'd need one but it hasn't been scheduled.
-Doctor: Understood. Do you have any other medical conditions — diabetes, high blood pressure, heart problems?
-Patient: I have high blood pressure, and I was told I have mild type 2 diabetes.
-Doctor: Are you currently taking any medications for those?
-Patient: Yes, I take metformin for the diabetes and ramipril for the blood pressure.
-Doctor: Any allergies to medications that you know of?
-Patient: I'm allergic to penicillin — it gives me a rash.
-Doctor: That's very helpful, thank you. Let's talk about the next steps for getting that biopsy arranged.

data/sample_dialogue_2.txt

@@ -1,21 +0,0 @@
-Doctor: Hello, thanks for coming in today. How can I help you?
-Patient: Hi doctor. I found a lump in my left breast about a month ago and it hasn't gone away.
-Doctor: Thank you for coming in about it. May I ask your age?
-Patient: I'm 47.
-Doctor: And have you noticed any other changes — pain, skin changes, nipple discharge?
-Patient: The lump isn't really painful, but the skin over it looks a bit dimpled now.
-Doctor: How long would you say you've noticed the lump and the skin changes?
-Patient: The lump for about four weeks, and the dimpling started maybe two weeks ago.
-Doctor: Have you had a mammogram or an ultrasound of the breast?
-Patient: Yes, I had a mammogram and an ultrasound last week. They saw a suspicious area and recommended a biopsy.
-Doctor: Did you go ahead with the biopsy?
-Patient: Yes, I had a core needle biopsy two days ago. I'm waiting for the results.
-Doctor: Thank you. Do you know if the cancer has been staged yet?
-Patient: No, nothing has been confirmed yet. We're still waiting on the biopsy.
-Doctor: Are you currently taking any medications or undergoing any treatments?
-Patient: I take levothyroxine for an underactive thyroid, nothing else.
-Doctor: Any other medical conditions I should know about?
-Patient: Just the thyroid issue — hypothyroidism. Otherwise I'm generally healthy.
-Doctor: And any allergies to medications?
-Patient: No known allergies.
-Doctor: Thank you, that's all very useful. Once the biopsy results are back, we'll discuss the findings and plan from there.

modal_vllm.py

@@ -1,118 +0,0 @@
-"""Serve Qwen3-14B on Modal as an OpenAI-compatible vLLM endpoint.
-
-This stands up exactly the kind of endpoint Sokrates' `MODEL_BASE_URL` expects:
-an OpenAI-compatible `/v1` server (chat completions + structured output) backed
-by vLLM, running Qwen3-14B (<= 32B params) on a Modal GPU.
-
---------------------------------------------------------------------------------
-One-time setup
---------------------------------------------------------------------------------
-  pip install modal
-  modal token new                      # authenticate the CLI
-
-  # Pick the API key the endpoint will require, and store it as a secret.
-  # Use the SAME value for the app's MODEL_API_KEY.
-  modal secret create sokrates-llm MODEL_API_KEY=sk-sokrates-demo-123
-
---------------------------------------------------------------------------------
-Deploy
---------------------------------------------------------------------------------
-  modal deploy modal_vllm.py
-
-Modal prints a URL like:
-  https://<your-workspace>--sokrates-qwen3-14b-serve.modal.run
-
-Point the Gradio app at it (note the trailing /v1):
-  export MODEL_BASE_URL="https://<...>-serve.modal.run/v1"
-  export MODEL_API_KEY="sk-sokrates-demo-123"   # must match the secret
-  export MODEL_NAME="Qwen/Qwen3-14B"
-  # vLLM is happiest enforcing the schema via guided_json:
-  export SOKRATES_GUIDED_JSON=1
-  python app.py
-
---------------------------------------------------------------------------------
-Quick smoke test (after deploy)
---------------------------------------------------------------------------------
-  curl $MODEL_BASE_URL/models -H "Authorization: Bearer $MODEL_API_KEY"
-"""
-
-import os
-import subprocess
-
-import modal
-
-# --- Configuration -----------------------------------------------------------
-
-MODEL_NAME = "Qwen/Qwen3-14B"  # <= 32B params, as required
-# A100-80GB comfortably fits the 14B weights (~28 GB bf16) plus KV cache.
-# Use "H100" for more headroom/speed, or "L40S" (48 GB) to cut cost.
-GPU_CONFIG = os.environ.get("SOKRATES_MODAL_GPU", "A100-80GB")
-VLLM_PORT = 8000
-MAX_MODEL_LEN = 16384
-
-# vLLM build with Qwen3 support. Pin to keep deploys reproducible.
-vllm_image = (
-    modal.Image.debian_slim(python_version="3.12")
-    .pip_install(
-        "vllm==0.9.1",
-        # Pin transformers: vllm 0.9.1 conflicts with transformers >= 4.54
-        # ("'aimv2' is already used by a Transformers config" crash on startup).
-        "transformers==4.52.4",
-        # Let vLLM pull a compatible huggingface_hub (>=0.32); just add the
-        # hf_transfer extra for fast weight downloads.
-        "hf_transfer",
-    )
-    # Faster weight downloads from the Hugging Face Hub.
-    .env({"HF_HUB_ENABLE_HF_TRANSFER": "1", "VLLM_USE_V1": "1"})
-)
-
-app = modal.App("sokrates-qwen3-14b")
-
-# Persist downloaded weights across cold starts so we only pull them once.
-hf_cache = modal.Volume.from_name("huggingface-cache", create_if_missing=True)
-vllm_cache = modal.Volume.from_name("vllm-cache", create_if_missing=True)
-
-
-@app.function(
-    image=vllm_image,
-    gpu=GPU_CONFIG,
-    # The secret provides MODEL_API_KEY, which vLLM enforces on every request.
-    secrets=[modal.Secret.from_name("sokrates-llm")],
-    volumes={
-        "/root/.cache/huggingface": hf_cache,
-        "/root/.cache/vllm": vllm_cache,
-    },
-    timeout=60 * 60,  # allow long-running server invocations
-    scaledown_window=15 * 60,  # keep warm 15 min after the last request
-    # During a live demo set SOKRATES_KEEP_WARM=1 before `modal deploy` to keep
-    # one replica always running (no cold starts). Costs GPU while idle, so set
-    # it back to 0 afterwards.
-    min_containers=int(os.environ.get("SOKRATES_KEEP_WARM", "0")),
-)
-@modal.concurrent(max_inputs=100)  # one replica handles many concurrent requests
-@modal.web_server(port=VLLM_PORT, startup_timeout=15 * 60)
-def serve():
-    """Launch the vLLM OpenAI-compatible API server."""
-    api_key = os.environ["MODEL_API_KEY"]
-    cmd = [
-        "vllm",
-        "serve",
-        MODEL_NAME,
-        "--host",
-        "0.0.0.0",
-        "--port",
-        str(VLLM_PORT),
-        "--api-key",
-        api_key,
-        "--served-model-name",
-        MODEL_NAME,
-        "--max-model-len",
-        str(MAX_MODEL_LEN),
-        "--gpu-memory-utilization",
-        "0.92",
-        # Structured-output backend used by response_format / guided_json.
-        "--guided-decoding-backend",
-        "xgrammar",
-    ]
-    # Run vLLM in the foreground process group of this container.
-    subprocess.Popen(" ".join(cmd), shell=True)

requirements.txt

@@ -1,19 +0,0 @@
-# --- Core UI ---
-gradio>=4.44,<5
-# Gradio 4.x imports HfFolder, removed in huggingface_hub >= 0.26
-huggingface_hub>=0.23,<0.26
-# Gradio 4.44's templating breaks on fastapi/starlette >= 1.x; pin known-good.
-fastapi==0.114.2
-starlette==0.38.6
-
-# --- Schema / validation ---
-pydantic>=2.6
-
-# --- LLM client (OpenAI-compatible: vLLM, Modal, etc.) ---
-openai>=1.30
-
-# --- ASR (added/used from Step 2 onward) ---
-faster-whisper>=1.0.3
-
-# --- Optional diarization (Step 2, behind ENABLE_DIARIZATION flag) ---
-# pyannote.audio>=3.1

run.sh

@@ -1,24 +0,0 @@
-#!/usr/bin/env bash
-# Launch Sokrates with environment variables loaded from a local .env file.
-#
-# Usage:
-#   cp .env.example .env        # once: fill in your endpoint + key
-#   source <your-venv>/bin/activate
-#   ./run.sh                    # starts the Gradio app
-#   ./run.sh test               # runs the endpoint diagnostic instead
-set -euo pipefail
-cd "$(dirname "$0")"
-
-if [ -f .env ]; then
-    set -a            # export everything we source
-    . ./.env
-    set +a
-else
-    echo "No .env found. Run: cp .env.example .env  (then edit it)"; exit 1
-fi
-
-if [ "${1:-}" = "test" ]; then
-    exec python test_endpoint.py
-else
-    exec python app.py
-fi

sokrates/__init__.py

@@ -1,8 +0,0 @@
-"""Sokrates: AI-assisted clinical intake during a medical visit.
-
-Sokrates listens to a doctor-patient conversation, transcribes it, fills in a
-structured clinical intake form, and suggests follow-up questions. It does NOT
-make diagnoses: it only prepares and structures data collection.
-"""
-
-__version__ = "0.1.0"

sokrates/asr.py

@@ -1,186 +0,0 @@
-"""Automatic speech recognition for Sokrates.
-
-Transcribes an uploaded audio file (priority for the demo video) or a live
-microphone recording using ``faster-whisper`` (large-v3, English).
-
-Design notes:
-  - The Whisper model is heavy, so it is loaded lazily and cached as a module
-    singleton. Importing this module does NOT load the model, so ``app.py`` can
-    start instantly and ASR dependencies stay optional until first use.
-  - Diarization (who is speaking) is OPTIONAL, enabled with ENABLE_DIARIZATION=1
-    and a valid HF_TOKEN. If pyannote is unavailable or fails, we transcribe
-    without speaker labels instead of crashing.
-
-Configuration via environment variables:
-  WHISPER_MODEL       faster-whisper model size (default "large-v3")
-  WHISPER_DEVICE      "cpu", "cuda", or "auto" (default "auto")
-  WHISPER_COMPUTE     compute type, e.g. "int8", "float16" (default "auto")
-  ENABLE_DIARIZATION  "1" to enable pyannote diarization (default off)
-  HF_TOKEN            Hugging Face token, required for pyannote
-"""
-
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-from typing import List, Optional
-
-def _language():
-    """Transcription language from WHISPER_LANGUAGE (default 'en').
-
-    Set WHISPER_LANGUAGE=it for Italian, or 'auto' to let Whisper detect it.
-    """
-    lang = os.getenv("WHISPER_LANGUAGE", "en").strip().lower()
-    return None if lang in ("auto", "detect", "") else lang
-
-_model = None  # cached faster-whisper WhisperModel
-_diarizer = None  # cached pyannote pipeline (or False if unavailable)
-
-
-@dataclass
-class TranscriptSegment:
-    """A single transcribed chunk with timing and optional speaker label."""
-
-    start: float
-    end: float
-    text: str
-    speaker: Optional[str] = None
-
-    def render(self) -> str:
-        prefix = f"{self.speaker}: " if self.speaker else ""
-        return f"{prefix}{self.text.strip()}"
-
-
-def _resolve_device() -> tuple[str, str]:
-    """Pick (device, compute_type), honoring env overrides and GPU availability."""
-    device = os.getenv("WHISPER_DEVICE", "auto")
-    compute = os.getenv("WHISPER_COMPUTE", "auto")
-    if device == "auto":
-        try:
-            import torch  # noqa: WPS433 (optional dependency)
-
-            device = "cuda" if torch.cuda.is_available() else "cpu"
-        except Exception:
-            device = "cpu"
-    if compute == "auto":
-        compute = "float16" if device == "cuda" else "int8"
-    return device, compute
-
-
-def get_model():
-    """Lazily build and cache the faster-whisper model."""
-    global _model
-    if _model is None:
-        from faster_whisper import WhisperModel  # local import: optional dep
-
-        model_size = os.getenv("WHISPER_MODEL", "large-v3")
-        device, compute = _resolve_device()
-        _model = WhisperModel(model_size, device=device, compute_type=compute)
-    return _model
-
-
-def diarization_enabled() -> bool:
-    return os.getenv("ENABLE_DIARIZATION", "0") == "1"
-
-
-def _get_diarizer():
-    """Lazily load the pyannote diarization pipeline, or None if unavailable."""
-    global _diarizer
-    if _diarizer is not None:
-        return _diarizer or None
-    token = os.getenv("HF_TOKEN")
-    if not token:
-        _diarizer = False
-        return None
-    try:
-        from pyannote.audio import Pipeline  # local import: optional dep
-
-        _diarizer = Pipeline.from_pretrained(
-            "pyannote/speaker-diarization-3.1", use_auth_token=token
-        )
-    except Exception:
-        # pyannote missing, model not accessible, or token invalid -> skip.
-        _diarizer = False
-    return _diarizer or None
-
-
-def _assign_speakers(
-    segments: List[TranscriptSegment], audio_path: str
-) -> List[TranscriptSegment]:
-    """Best-effort speaker labelling. Returns segments unchanged on any failure."""
-    diarizer = _get_diarizer()
-    if diarizer is None:
-        return segments
-    try:
-        diarization = diarizer(audio_path)
-        for seg in segments:
-            mid = (seg.start + seg.end) / 2.0
-            for turn, _, speaker in diarization.itertracks(yield_label=True):
-                if turn.start <= mid <= turn.end:
-                    seg.speaker = speaker.replace("SPEAKER_", "Speaker ")
-                    break
-    except Exception:
-        return segments
-    return segments
-
-
-def transcribe_segments(audio_path: str) -> List[TranscriptSegment]:
-    """Transcribe an audio file into timed segments (with optional speakers)."""
-    model = get_model()
-    segments_iter, _info = model.transcribe(
-        audio_path,
-        language=_language(),
-        vad_filter=True,
-    )
-    segments = [
-        TranscriptSegment(start=s.start, end=s.end, text=s.text)
-        for s in segments_iter
-    ]
-    if diarization_enabled():
-        segments = _assign_speakers(segments, audio_path)
-    return segments
-
-
-def transcribe_file(audio_path: str) -> str:
-    """Transcribe an audio file and return a plain-text transcript."""
-    if not audio_path:
-        return ""
-    segments = transcribe_segments(audio_path)
-    return "\n".join(seg.render() for seg in segments).strip()
-
-
-SAMPLE_RATE = 16000
-
-
-def _to_mono_float32_16k(sample_rate: int, samples) -> "object":
-    """Convert an arbitrary audio chunk to mono float32 at 16 kHz for Whisper."""
-    import numpy as np
-
-    audio = np.asarray(samples)
-    if audio.ndim > 1:  # stereo -> mono
-        audio = audio.mean(axis=1)
-    if np.issubdtype(audio.dtype, np.integer):  # int16 -> [-1, 1] float
-        audio = audio.astype(np.float32) / np.iinfo(audio.dtype).max
-    else:
-        audio = audio.astype(np.float32)
-    if sample_rate != SAMPLE_RATE and audio.size > 0:  # linear resample to 16k
-        duration = audio.shape[0] / float(sample_rate)
-        target_len = int(round(duration * SAMPLE_RATE))
-        if target_len > 0:
-            src_idx = np.linspace(0, audio.shape[0] - 1, num=target_len)
-            audio = np.interp(src_idx, np.arange(audio.shape[0]), audio).astype(
-                np.float32
-            )
-    return audio
-
-
-def transcribe_array(sample_rate: int, samples) -> str:
-    """Transcribe an in-memory audio buffer (used by the live-microphone path)."""
-    audio = _to_mono_float32_16k(sample_rate, samples)
-    if getattr(audio, "size", 0) == 0:
-        return ""
-    model = get_model()
-    segments_iter, _info = model.transcribe(
-        audio, language=_language(), vad_filter=True
-    )
-    return " ".join(s.text.strip() for s in segments_iter).strip()

sokrates/gaps.py

@@ -1,56 +0,0 @@
-"""Gap engine: a deterministic (no-LLM) view of what the form still needs.
-
-Given the current intake form, this module reports which mandatory fields are
-still empty. The UI surfaces these directly, and the question generator uses
-them to prioritize what the doctor should ask next.
-
-This is intentionally pure Python with no model calls, so the "what is missing"
-signal is fully deterministic and auditable.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import List
-
-from sokrates.schema import FIELD_META, IntakeForm, is_empty
-
-
-@dataclass(frozen=True)
-class Gap:
-    """A single missing field."""
-
-    name: str
-    label: str
-    mandatory: bool
-
-
-def find_gaps(form: IntakeForm, mandatory_only: bool = True) -> List[Gap]:
-    """Return the fields that are still empty.
-
-    With ``mandatory_only=True`` (default) only required fields are returned,
-    which is what drives the "questions still to ask" priority.
-    """
-    gaps: List[Gap] = []
-    for meta in FIELD_META:
-        if mandatory_only and not meta.mandatory:
-            continue
-        if is_empty(getattr(form, meta.name)):
-            gaps.append(Gap(meta.name, meta.label, meta.mandatory))
-    return gaps
-
-
-def missing_mandatory_labels(form: IntakeForm) -> List[str]:
-    """Convenience: human-readable labels of the missing mandatory fields."""
-    return [g.label for g in find_gaps(form, mandatory_only=True)]
-
-
-def completeness(form: IntakeForm) -> tuple[int, int]:
-    """Return (filled_mandatory, total_mandatory) for a progress indicator."""
-    total = sum(1 for m in FIELD_META if m.mandatory)
-    filled = sum(
-        1
-        for m in FIELD_META
-        if m.mandatory and not is_empty(getattr(form, m.name))
-    )
-    return filled, total

sokrates/llm.py

@@ -1,336 +0,0 @@
-"""LLM access: OpenAI-compatible client + structured extraction.
-
-The model runs behind any OpenAI-compatible endpoint (e.g. a vLLM server on
-Modal serving Qwen3-14B). Nothing about the provider is hardcoded — base URL,
-API key and model name come from environment variables, so the same code can
-point at vLLM, OpenAI, or any compatible server without edits.
-
-Environment variables:
-  MODEL_BASE_URL   OpenAI-compatible base URL (e.g. https://.../v1)
-  MODEL_API_KEY    API key / token for the endpoint
-  MODEL_NAME       model identifier served by the endpoint (e.g. Qwen/Qwen3-14B)
-
-Optional:
-  SOKRATES_GUIDED_JSON   "1" to send the schema via vLLM's `guided_json`
-                         (extra_body) instead of OpenAI `response_format`.
-  SOKRATES_NO_THINK      "1" to disable Qwen3 thinking via chat_template_kwargs.
-  MODEL_TEMPERATURE      sampling temperature (default 0.0 for extraction).
-
-This module only handles structured extraction (Step 3). Question generation is
-added in Step 4.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-from typing import Any, Optional
-
-from sokrates.schema import IntakeForm, merge_forms
-
-_client = None
-
-
-class LLMConfigError(RuntimeError):
-    """Raised when the LLM endpoint is not configured via env vars."""
-
-
-def get_config() -> tuple[str, str, str]:
-    """Return (base_url, api_key, model_name) from the environment."""
-    base_url = os.getenv("MODEL_BASE_URL")
-    api_key = os.getenv("MODEL_API_KEY")
-    model_name = os.getenv("MODEL_NAME")
-    missing = [
-        name
-        for name, val in (
-            ("MODEL_BASE_URL", base_url),
-            ("MODEL_API_KEY", api_key),
-            ("MODEL_NAME", model_name),
-        )
-        if not val
-    ]
-    if missing:
-        raise LLMConfigError(
-            "Missing environment variable(s): "
-            + ", ".join(missing)
-            + ". Set MODEL_BASE_URL, MODEL_API_KEY and MODEL_NAME to point at "
-            "your vLLM/OpenAI-compatible endpoint."
-        )
-    return base_url, api_key, model_name  # type: ignore[return-value]
-
-
-def get_client():
-    """Lazily build and cache the OpenAI-compatible client."""
-    global _client
-    if _client is None:
-        from openai import OpenAI  # local import: optional dep
-
-        base_url, api_key, _ = get_config()
-        # Bound the wait so a stuck request surfaces as an error instead of
-        # hanging the UI. Generous default to tolerate a cold start.
-        timeout = float(os.getenv("MODEL_TIMEOUT", "180"))
-        _client = OpenAI(
-            base_url=base_url, api_key=api_key, timeout=timeout, max_retries=1
-        )
-    return _client
-
-
-def _temperature() -> float:
-    try:
-        return float(os.getenv("MODEL_TEMPERATURE", "0.0"))
-    except ValueError:
-        return 0.0
-
-
-def _extra_body(schema: Optional[dict] = None) -> dict[str, Any]:
-    """Assemble vLLM-specific extra_body options based on env flags."""
-    body: dict[str, Any] = {}
-    if schema is not None and os.getenv("SOKRATES_GUIDED_JSON", "0") == "1":
-        body["guided_json"] = schema
-    if os.getenv("SOKRATES_NO_THINK", "0") == "1":
-        body["chat_template_kwargs"] = {"enable_thinking": False}
-    return body
-
-
-def _parse_json_object(content: str) -> dict:
-    """Parse a JSON object from model output, tolerating stray text/markdown."""
-    content = content.strip()
-    # Strip Qwen3-style <think>...</think> blocks if present.
-    content = re.sub(r"<think>.*?</think>", "", content, flags=re.DOTALL).strip()
-    try:
-        return json.loads(content)
-    except json.JSONDecodeError:
-        pass
-    # Fall back to the first balanced {...} block.
-    start = content.find("{")
-    if start != -1:
-        depth = 0
-        for i in range(start, len(content)):
-            if content[i] == "{":
-                depth += 1
-            elif content[i] == "}":
-                depth -= 1
-                if depth == 0:
-                    return json.loads(content[start : i + 1])
-    raise ValueError(f"Could not parse JSON from model output: {content[:200]!r}")
-
-
-EXTRACTION_SYSTEM_PROMPT = (
-    "You are a clinical intake assistant. From a doctor-patient conversation, "
-    "output a SINGLE JSON object with exactly these keys, filling EVERY field the "
-    "transcript supports:\n"
-    '- "age": integer, patient age in years. "I\'m 71" / "Ho 71 anni" -> 71\n'
-    '- "sex": one of "male", "female", "other" (ENGLISH). '
-    '"sesso maschile" / "I\'m a man" -> "male"\n'
-    '- "tumor_site": string, body location of the tumor/mass/lesion. '
-    '"massa vicino alla prostata" / "mass near the prostate" -> "prostate"\n'
-    '- "main_symptoms": array of strings — every reported symptom/complaint.\n'
-    '- "symptom_duration": string, how long symptoms lasted. '
-    '"da circa quattro mesi" -> "about four months"\n'
-    '- "biopsy_done": boolean — true if a biopsy was performed/done.\n'
-    '- "stage_known": boolean — true if the cancer stage is mentioned/known.\n'
-    '- "cancer_stage": string, the stage value if mentioned, e.g. "T3", "II".\n'
-    '- "current_therapies": array of strings — current medications/treatments.\n'
-    '- "comorbidities": array of strings — other chronic conditions.\n'
-    '- "allergies": array of strings — drug or other allergies.\n'
-    "Rules:\n"
-    "- Fill a field whenever the information appears ANYWHERE in the transcript, "
-    "in ANY language. Translate enum values (sex) to English; keep symptom and "
-    "condition wording as the patient said it.\n"
-    "- Use null ONLY when the field is truly not mentioned.\n"
-    "- Always capture age and sex when stated, even in a short reply.\n"
-    "- Do NOT diagnose or invent. Output ONLY the JSON object."
-)
-
-# A worked example (few-shot) that teaches the model to fill scalars too.
-_EXAMPLE_USER = (
-    "Conversation transcript:\n"
-    "Good morning. How old are you? I'm 68, and I'm a woman. I found a lump in my "
-    "left breast. They did a biopsy; it's not staged yet. I take levothyroxine.\n\n"
-    "Extract the clinical intake fields as a JSON object."
-)
-_EXAMPLE_ASSISTANT = (
-    '{"age": 68, "sex": "female", "tumor_site": "left breast", '
-    '"main_symptoms": ["lump in the left breast"], "symptom_duration": null, '
-    '"biopsy_done": true, "stage_known": false, "cancer_stage": null, '
-    '"current_therapies": ["levothyroxine"], "comorbidities": null, '
-    '"allergies": null}'
-)
-
-
-def _extraction_attempt(
-    transcript: str, model_name: str, client, schema: dict, guided: bool
-) -> dict:
-    """One extraction round-trip. Returns a dict of non-null fields.
-
-    Thinking is ALWAYS disabled here (structured output; a chain-of-thought
-    doesn't help and, under guided decoding, can't be emitted at all).
-    """
-    user_prompt = (
-        "Conversation transcript:\n"
-        f"{transcript}\n\n"
-        "Extract the clinical intake fields as a JSON object."
-    )
-    kwargs: dict[str, Any] = dict(
-        model=model_name,
-        messages=[
-            {"role": "system", "content": EXTRACTION_SYSTEM_PROMPT},
-            {"role": "user", "content": _EXAMPLE_USER},
-            {"role": "assistant", "content": _EXAMPLE_ASSISTANT},
-            {"role": "user", "content": user_prompt},
-        ],
-        temperature=_temperature(),
-        max_tokens=int(os.getenv("SOKRATES_EXTRACT_MAX_TOKENS", "1024")),
-    )
-    extra: dict[str, Any] = {"chat_template_kwargs": {"enable_thinking": False}}
-    if guided:
-        extra["guided_json"] = schema
-    else:
-        kwargs["response_format"] = {"type": "json_object"}
-    kwargs["extra_body"] = extra
-
-    resp = client.chat.completions.create(**kwargs)
-    content = resp.choices[0].message.content or "{}"
-    data = _parse_json_object(content)
-    return {k: v for k, v in data.items() if v is not None}
-
-
-def _normalize_value(key: str, value: Any) -> Any:
-    """Light normalization so common multilingual values still validate.
-
-    Mainly maps sex words (any language / short forms) to the English enum.
-    """
-    if key == "sex" and isinstance(value, str):
-        v = value.strip().lower()
-        male = {"male", "m", "man", "maschile", "maschio", "uomo", "männlich", "homme"}
-        female = {"female", "f", "woman", "femminile", "femmina", "donna", "femme"}
-        if v in male:
-            return "male"
-        if v in female:
-            return "female"
-    return value
-
-
-def _build_form(data: dict) -> IntakeForm:
-    """Validate field by field, dropping any value that doesn't fit the schema.
-
-    This keeps good fields even if one value is malformed (e.g. an unmapped sex
-    value), instead of rejecting the whole object.
-    """
-    clean: dict[str, Any] = {}
-    for key, value in data.items():
-        if value is None or key not in IntakeForm.model_fields:
-            continue
-        value = _normalize_value(key, value)
-        try:
-            IntakeForm.model_validate({key: value})
-        except Exception:
-            continue
-        clean[key] = value
-    return IntakeForm.model_validate(clean)
-
-
-def extract_form(transcript: str, current: Optional[IntakeForm] = None) -> IntakeForm:
-    """Extract an IntakeForm from the transcript and merge into ``current``.
-
-    Uses a free-form JSON call by default (the model fills every field it can,
-    guided by the prompt + example). Guided decoding tended to fill only the
-    list fields and null the scalars, so it's now only a fallback. The new JSON
-    is merged WITHOUT overwriting fields already filled (schema.merge_forms).
-    """
-    current = current or IntakeForm()
-    if not transcript or not transcript.strip():
-        return current
-
-    _, _, model_name = get_config()  # validate env first (clear error if missing)
-    client = get_client()
-    schema = IntakeForm.model_json_schema()
-
-    try:
-        data = _extraction_attempt(
-            transcript, model_name, client, schema, guided=False
-        )
-    except Exception:
-        # Endpoint rejected json_object �� fall back to guided decoding.
-        data = _extraction_attempt(
-            transcript, model_name, client, schema, guided=True
-        )
-
-    # If nothing came back, try the other strategy once more.
-    if not data:
-        try:
-            data = _extraction_attempt(
-                transcript, model_name, client, schema, guided=True
-            )
-        except Exception:
-            pass
-
-    extracted = _build_form(data)
-    return merge_forms(current, extracted)
-    extracted = IntakeForm.model_validate(data)
-    return merge_forms(current, extracted)
-
-
-QUESTION_SYSTEM_PROMPT = (
-    "You are Sokrates, an assistant that helps a doctor run a clinical intake "
-    "during a visit. You suggest the next questions the doctor should ask the "
-    "patient to complete the intake.\n"
-    "Strict rules:\n"
-    "- DO NOT make diagnoses, do not suggest treatments, do not interpret "
-    "findings. You only help COLLECT and STRUCTURE information.\n"
-    "- Prioritize the listed missing mandatory fields first, then coherent "
-    "clinical follow-ups based on what was already said.\n"
-    "- Return AT MOST 3 questions, ordered by priority (most important first).\n"
-    "- Each question must be short, in plain English, and directly askable to "
-    "the patient.\n"
-    "- Return ONLY a JSON object of the form "
-    '{"questions": ["...", "..."]} with no extra text.'
-)
-
-
-def generate_questions(
-    transcript: str,
-    missing_fields: list[str],
-    max_questions: int = 3,
-) -> list[str]:
-    """Generate up to ``max_questions`` prioritized follow-up questions.
-
-    Combines the deterministic gaps (missing mandatory fields) with the
-    conversation so far. Never diagnoses — see QUESTION_SYSTEM_PROMPT.
-    """
-    if not transcript or not transcript.strip():
-        return []
-
-    _, _, model_name = get_config()
-    client = get_client()
-
-    missing_str = ", ".join(missing_fields) if missing_fields else "(none)"
-    user_prompt = (
-        f"Missing mandatory intake fields: {missing_str}\n\n"
-        "Conversation transcript so far:\n"
-        f"{transcript}\n\n"
-        f"Suggest at most {max_questions} prioritized questions the doctor "
-        "should ask next to complete the intake. Do not diagnose."
-    )
-
-    kwargs: dict[str, Any] = dict(
-        model=model_name,
-        messages=[
-            {"role": "system", "content": QUESTION_SYSTEM_PROMPT},
-            {"role": "user", "content": user_prompt},
-        ],
-        temperature=max(_temperature(), 0.2),
-        response_format={"type": "json_object"},
-        max_tokens=int(os.getenv("SOKRATES_QUESTIONS_MAX_TOKENS", "400")),
-    )
-    extra = _extra_body()
-    if extra:
-        kwargs["extra_body"] = extra
-
-    resp = client.chat.completions.create(**kwargs)
-    content = resp.choices[0].message.content or "{}"
-    data = _parse_json_object(content)
-    questions = data.get("questions", []) if isinstance(data, dict) else []
-    cleaned = [str(q).strip() for q in questions if str(q).strip()]
-    return cleaned[:max_questions]

sokrates/orchestrator.py

@@ -1,78 +0,0 @@
-"""Orchestration loop: transcript -> extraction -> gaps -> questions.
-
-This is the single entry point the UI calls after each transcript update. It:
-  1. extracts structured fields and merges them into the running form,
-  2. computes the still-missing mandatory fields (deterministic gap engine),
-  3. asks the LLM for up to 3 prioritized follow-up questions.
-
-It never diagnoses; it only structures data collection and suggests questions.
-The function is defensive: extraction and question generation can each fail
-independently (e.g. transient endpoint errors) without losing the form state.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import List
-
-from sokrates.gaps import completeness, find_gaps, missing_mandatory_labels
-from sokrates.llm import extract_form, generate_questions
-from sokrates.schema import IntakeForm
-
-
-@dataclass
-class TurnResult:
-    """Everything the UI needs to repaint after processing a transcript."""
-
-    form: IntakeForm
-    missing_mandatory: List[str] = field(default_factory=list)
-    questions: List[str] = field(default_factory=list)
-    filled_mandatory: int = 0
-    total_mandatory: int = 0
-    notes: List[str] = field(default_factory=list)
-
-    @property
-    def status(self) -> str:
-        msg = (
-            f"{self.filled_mandatory}/{self.total_mandatory} mandatory fields "
-            "filled."
-        )
-        if self.notes:
-            msg += " " + " ".join(self.notes)
-        return msg
-
-
-def process_transcript(
-    transcript: str,
-    form: IntakeForm | None = None,
-    max_questions: int = 3,
-) -> TurnResult:
-    """Run one full orchestration turn over the current transcript."""
-    form = form or IntakeForm()
-    notes: List[str] = []
-
-    # 1) Structured extraction (merges, never overwrites filled fields).
-    try:
-        form = extract_form(transcript, form)
-    except Exception as exc:
-        notes.append(f"⚠️ Extraction failed: {exc}")
-
-    # 2) Deterministic gap engine.
-    missing = missing_mandatory_labels(form)
-    filled, total = completeness(form)
-
-    # 3) Question generation (best-effort; uses gaps + transcript).
-    questions: List[str] = []
-    try:
-        questions = generate_questions(transcript, missing, max_questions)
-    except Exception as exc:
-        notes.append(f"⚠️ Question generation failed: {exc}")
-
-    return TurnResult(
-        form=form,
-        missing_mandatory=missing,
-        questions=questions,
-        filled_mandatory=filled,
-        total_mandatory=total,
-        notes=notes,
-    )

sokrates/schema.py

@@ -1,148 +0,0 @@
-"""Clinical intake form schema (oncology) as a Pydantic model.
-
-This module is the single source of truth for:
-  - the fields of the intake form (`IntakeForm`),
-  - per-field display metadata and whether a field is mandatory (`FIELD_META`),
-  - helpers to merge partial extractions without overwriting filled fields.
-
-Both the gap engine (`sokrates/gaps.py`) and the Gradio UI (`app.py`) read
-`FIELD_META`, so labels and "mandatory" status are defined in exactly one place.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import List, Literal, Optional
-
-from pydantic import BaseModel, Field
-
-
-Sex = Literal["male", "female", "other"]
-
-
-class IntakeForm(BaseModel):
-    """Oncology clinical intake form.
-
-    Every field is optional and starts as ``None`` (empty). The orchestration
-    loop fills fields incrementally as the conversation progresses. List fields
-    default to ``None`` (not ``[]``) so we can distinguish "not asked yet" from
-    "asked, none reported".
-    """
-
-    age: Optional[int] = Field(default=None, description="Patient age in years.")
-    sex: Optional[Sex] = Field(default=None, description="Patient biological sex.")
-    tumor_site: Optional[str] = Field(
-        default=None,
-        description="Anatomical site of the tumor, e.g. 'left breast', 'lung'.",
-    )
-    main_symptoms: Optional[List[str]] = Field(
-        default=None,
-        description="Main presenting symptoms, e.g. ['cough', 'weight loss'].",
-    )
-    symptom_duration: Optional[str] = Field(
-        default=None,
-        description="How long symptoms have been present, e.g. '3 weeks'.",
-    )
-    biopsy_done: Optional[bool] = Field(
-        default=None, description="Whether a biopsy has already been performed."
-    )
-    stage_known: Optional[bool] = Field(
-        default=None, description="Whether the cancer stage is known."
-    )
-    cancer_stage: Optional[str] = Field(
-        default=None,
-        description="Cancer stage if known, e.g. 'T2N1M0' or 'II'.",
-    )
-    current_therapies: Optional[List[str]] = Field(
-        default=None,
-        description="Ongoing or current treatments/medications.",
-    )
-    comorbidities: Optional[List[str]] = Field(
-        default=None,
-        description="Pre-existing conditions, e.g. ['diabetes', 'hypertension'].",
-    )
-    allergies: Optional[List[str]] = Field(
-        default=None,
-        description="Known drug or other allergies.",
-    )
-
-
-@dataclass(frozen=True)
-class FieldMeta:
-    """Display + policy metadata for a single intake field."""
-
-    name: str
-    label: str
-    mandatory: bool
-
-
-# Ordered metadata for every field in IntakeForm. The UI renders fields in this
-# order; the gap engine uses `mandatory` to decide what is still required.
-FIELD_META: List[FieldMeta] = [
-    FieldMeta("age", "Age", True),
-    FieldMeta("sex", "Sex", True),
-    FieldMeta("tumor_site", "Tumor site", True),
-    FieldMeta("main_symptoms", "Main symptoms", True),
-    FieldMeta("symptom_duration", "Symptom duration", False),
-    FieldMeta("biopsy_done", "Biopsy done", True),
-    FieldMeta("stage_known", "Stage known", True),
-    FieldMeta("cancer_stage", "Cancer stage", False),
-    FieldMeta("current_therapies", "Current therapies", False),
-    FieldMeta("comorbidities", "Comorbidities", False),
-    FieldMeta("allergies", "Allergies", False),
-]
-
-MANDATORY_FIELDS: List[str] = [m.name for m in FIELD_META if m.mandatory]
-
-
-def is_empty(value: object) -> bool:
-    """Return True if a field value counts as 'not filled yet'."""
-    if value is None:
-        return True
-    if isinstance(value, str) and value.strip() == "":
-        return True
-    if isinstance(value, list) and len(value) == 0:
-        return True
-    return False
-
-
-def coerce_form(value: object) -> IntakeForm:
-    """Return an IntakeForm from None, a dict, or an IntakeForm.
-
-    Gradio's ``State`` can hand back a plain dict instead of the model instance,
-    so callers normalize through this before using the form.
-    """
-    if isinstance(value, IntakeForm):
-        return value
-    if isinstance(value, dict):
-        return IntakeForm(**value)
-    return IntakeForm()
-
-
-def merge_forms(base: IntakeForm, update: IntakeForm) -> IntakeForm:
-    """Merge ``update`` into ``base`` without overwriting already-filled fields.
-
-    A field in ``base`` is only replaced when it is currently empty AND the
-    corresponding field in ``update`` is non-empty. This implements the
-    "do not overwrite fields that are already filled" rule.
-    """
-    merged = base.model_copy(deep=True)
-    for meta in FIELD_META:
-        current = getattr(merged, meta.name)
-        if not is_empty(current):
-            continue
-        incoming = getattr(update, meta.name)
-        if not is_empty(incoming):
-            setattr(merged, meta.name, incoming)
-    return merged
-
-
-def format_value(value: object) -> str:
-    """Human-readable rendering of a field value for the UI."""
-    if is_empty(value):
-        return ""
-    if isinstance(value, bool):
-        return "Yes" if value else "No"
-    if isinstance(value, list):
-        return ", ".join(str(v) for v in value)
-    return str(value)

test_endpoint.py

@@ -1,68 +0,0 @@
-"""Diagnostic: confirm the LLM endpoint works and measure latency.
-
-Run it with the same environment variables as the app:
-
-    export MODEL_BASE_URL="https://....modal.run/v1"
-    export MODEL_API_KEY="sk-sokrates-demo-123"
-    export MODEL_NAME="Qwen/Qwen3-14B"
-    export SOKRATES_GUIDED_JSON=1
-    export SOKRATES_NO_THINK=1
-    python test_endpoint.py
-
-It prints, step by step:
-  - the resolved config,
-  - whether the server lists the model,
-  - the extraction call + how long it took,
-  - the question-generation call + how long it took.
-
-If the first call is slow (tens of seconds to minutes) but the second is fast,
-that's a cold start — the model is loading on the GPU. Keep one replica warm:
-    SOKRATES_KEEP_WARM=1 modal deploy modal_vllm.py
-"""
-
-import time
-
-from sokrates.gaps import missing_mandatory_labels
-from sokrates.llm import generate_questions, get_client, get_config, extract_form
-
-TRANSCRIPT = (
-    "Doctor: Good morning, how old are you?\n"
-    "Patient: I'm 62, and I'm a man.\n"
-    "Doctor: What brings you in?\n"
-    "Patient: I've had a cough for three weeks and lost some weight. "
-    "I had a chest CT that showed a mass in my right lung, but no biopsy yet."
-)
-
-
-def main() -> None:
-    base_url, _key, model = get_config()
-    print(f"• Endpoint : {base_url}")
-    print(f"• Model    : {model}\n")
-
-    print("→ Checking the server lists the model …")
-    t0 = time.time()
-    models = get_client().models.list()
-    served = [m.id for m in models.data]
-    print(f"  OK in {time.time() - t0:.1f}s — served models: {served}\n")
-
-    print("→ Extraction call (fills the form) …")
-    t0 = time.time()
-    form = extract_form(TRANSCRIPT)
-    print(f"  Done in {time.time() - t0:.1f}s")
-    print(f"  Extracted: {form.model_dump(exclude_none=True)}\n")
-
-    missing = missing_mandatory_labels(form)
-    print(f"  Still-missing mandatory fields: {missing}\n")
-
-    print("→ Question-generation call …")
-    t0 = time.time()
-    questions = generate_questions(TRANSCRIPT, missing)
-    print(f"  Done in {time.time() - t0:.1f}s")
-    for i, q in enumerate(questions, 1):
-        print(f"   {i}. {q}")
-
-    print("\n✅ Endpoint works end to end.")
-
-
-if __name__ == "__main__":
-    main()