Medical Query Chat

Medical Query Chat is a modular Python application for collecting spoken or typed health queries, translating them, and sending them to a configured local language-model provider. It is a prototype workflow, not a diagnostic or emergency medical service.

Read the Setup Guide to install and run the app, and Contribution Guidelines before contributing changes.

Quick start

On macOS or Linux, run the complete local setup and UI launcher from a fresh clone:

./launch

It installs uv and Ollama if needed, starts Ollama, downloads the default model once, syncs dependencies, and opens the UI. To use another model, set MEDICAL_QUERY_MODEL, for example MEDICAL_QUERY_MODEL=gemma3:4b ./launch.

For development, install uv and create the lightweight environment:

uv sync --group dev
uv run pytest
uv run medical-query --help

Enable only the features you need:

uv sync --group dev --extra speech --extra translation
uv sync --extra ui
uv sync --extra local-llm

The default backend calls a local Ollama qwen3:4b-instruct model directly; it does not require the external llm command or its plugins. Start Ollama and pull that model before prompting. Qwen reasoning is disabled and responses are capped at 512 tokens so multilingual requests return promptly. Browser and CLI recording use WAV by default, so ffmpeg is needed only when you explicitly request MP3 output or upload a non-WAV audio file.

Commands

# Ask the configured LLM and print its response
uv run medical-query ask "What are common flu symptoms?"

# Read a prompt from a file and save the response
uv run medical-query ask --input-file data/sample_prompt.txt --output-file runtime/output.txt

# Record, transcribe, translate to English, and save runtime/input.txt
uv run medical-query listen --duration 5 --source-language auto --target-language en

# Translate text without calling a model
uv run medical-query translate "नमस्ते" --source-language hi --target-language en

# Start the modern local browser interface
uv run medical-query-ui

The browser UI supports typed conversations, a local-model selector, response-language selection, quick prompts, and microphone/upload transcription. The selector lists practical model sizes and marks models not yet downloaded. Selecting one disables chat until you use Download selected model, which runs the needed ollama pull command for you. It opens locally only and does not create a public URL. uv sync --extra ui installs its audio dependencies. Use --model, --temperature, and --top-p with ask to change model settings. Add --backend llm-cli only when intentionally using a compatible external llm installation. Set MEDICAL_QUERY_MODEL to change the default for both CLI and UI.

Architecture

medical_query_chat/ contains the maintained application. services/ coordinates workflows, adapters/ contains integrations with microphones, speech recognition, translation, and models, and protocols.py defines their replaceable contracts. cli.py and ui/ are thin entry points. The maintained UI is a Gradio browser application.

data/ holds tracked sample prompts and datasets; runtime/ is for ignored generated recordings and responses. legacy/ contains preserved experiments and standalone scripts, including the old local Llama runner. It is not part of the primary package.

To add a provider, implement the relevant protocol and inject it into MedicalQueryService or ListeningService; no CLI or UI business logic should depend on a provider package directly.

Development

uv run ruff format --check .
uv run ruff check .
uv run mypy medical_query_chat
uv run pytest

Tests must not require microphone hardware, network access, ffmpeg, or a model download. See flow.md for data flow and changes.md for the maintained migration record.