CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Gradio web app: a Medical Assistant chat that runs a background spiritual-distress classifier on every patient message, plus a verification/review workflow so clinicians and chaplains can grade the classifier's output and export the results. Python 3.14, Gradio 6.1.0, LLM calls to Google Gemini and Anthropic Claude.

Commands

# Setup
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# .env must contain GEMINI_API_KEY and/or ANTHROPIC_API_KEY

# Run — full interface (Chat, Verification, Model Settings, Edit Prompts, Profiles, Help)
./run.sh                    # port 7861, activates .venv and sets PYTHONPATH
python app.py               # port 7860

# Run — simplified interface (Chat, Conversation Verification, Help only)
python run_simplified_interface.py

# Tests
python run_tests.py                       # all suites, one pytest subprocess per directory
python -m pytest tests/unit -q            # one suite
python -m pytest tests/unit/test_consent_manager.py::test_name -q   # one test

Tests import as src.*; pytest's rootdir insertion makes this work when run from the repo root. Run from anywhere else and you need PYTHONPATH=.. direnv (.envrc) does venv activation + PYTHONPATH + dotenv automatically.

Baseline as of this writing: tests/unit is 5 failed, 170 passed — the 5 failures in test_enhanced_results_display.py are pre-existing, not caused by your change. Verify against a clean checkout before assuming you broke something. Several older files under tests/unit and tests/integration are script-style (test_*() returning bool), so they pass in pytest regardless of what they print — don't trust them as regression gates.

Env vars that change behavior: LOG_PROMPTS=true (dump every system/user prompt and response to ai_interactions.log), PERF_TIMING (per-stage [PERF] timing in the message path, on by default), GRADIO_SERVER_PORT / GRADIO_SERVER_NAME / GRADIO_SHARE, GCP_SERVICE_ACCOUNT_B64 (base64 service-account JSON — enables Vertex AI instead of the Gemini API key).

Two interfaces, one core

src/interface/gradio_app.py (full) and src/interface/simplified_gradio_app.py (simplified, built for the testing team) are separate, largely parallel UI builders over the same SimplifiedMedicalApp core. A change to shared chat/verification behavior usually has to be made or checked in both. The full app delegates to the *_handlers.py modules; the simplified app uses simplified_chat_handlers.py and its own inline wiring.

Entry points disagree on purpose: app.py → gradio_app.main, run_simplified_interface.py → simplified_gradio_app.main, and the README front-matter (app_file:) points Hugging Face Spaces at simplified_gradio_app.py. If you change what the deployed Space runs, update the README front-matter too.

Message flow

SimplifiedMedicalApp.process_message (src/core/simplified_medical_app.py) is the single entry point for every patient turn. It is a state machine over SessionSpiritualState (spiritual_state.py), not a straight classify-then-answer:

1. Awaiting consent → _handle_consent_response (patient is deciding on a chaplain referral).
2. In triage → _handle_triage_response — continues the existing YELLOW triage; the classifier is not re-run mid-triage.
3. Otherwise → SpiritualMonitor.classify returns GREEN / YELLOW / RED:
   • GREEN → normal medical reply.
   • YELLOW → SoftTriageManager asks up to 2–3 gentle clarifying questions, then resolves to GREEN or escalates to RED (_resolve_to_green / _escalate_to_red; forced decision at the question limit).
   • RED → crisis response + consent request + ProviderSummaryGenerator handoff summary.

The response returned to Gradio is prefixed with a classification badge, and every exchange is written by ConversationLogger to conversation_logs/session_*.json. spiritual_state.last_assessment is the shared slot the display, the logger, and the verification tab all read — the triage/escalation helpers update it as a side effect.

Agent name keys

A small set of string keys threads through config, model overrides, prompt overrides, and the UI. They must stay in sync across four places:

• AGENT_CONFIGURATIONS in src/config/ai_providers_config.py — provider + model + temperature per agent.
• apply_model_settings in src/interface/model_handlers.py — the Model Settings tab writes session.custom_models under these keys.
• _prompt_name_to_agent in src/interface/prompt_handlers.py — maps emoji UI labels ("🔍 Spiritual Monitor (Classifier)") to agent keys.
• SimplifiedMedicalApp.set_model_overrides / set_prompt_overrides, which propagate onto AIClientManager.

get_agent_config silently falls back to Gemini 2.5 Flash for an unknown agent name — a typo'd key produces a working app that quietly uses the wrong model. Note that SoftSpiritualTriage and TriageResponseEvaluator are used by the UI but are not in AGENT_CONFIGURATIONS, so they currently hit that fallback.

Prompt system

Prompts are text files in src/config/prompts/, but resolution goes through PromptController (src/config/prompt_management/prompt_controller.py) with three tiers, highest first:

1. Session override — set from the Edit Prompts tab, scoped to one session_id, never touches disk.
2. Centralized file — src/config/prompts/*.txt, with shared components (indicators / rules / templates / categories from prompt_management/data/*.json) spliced into placeholders.
3. Hardcoded default — module-level SYSTEM_PROMPT_* constants in spiritual_monitor.py, soft_triage_manager.py, src/config/prompts.py.

"Promote to File" writes a session override to the real .txt and leaves a *.backup.<timestamp>.txt beside it (that's what the existing backup files in src/config/prompts/ are). PromptController caches per agent_type + session_id; if you edit a prompt file on disk while the app is running, the cache can serve the stale copy.

Verification subsystems

Two distinct workflows that share vocabulary but not code paths:

• Conversation Verification — replays the current chat session, exchange by exchange, for reviewer grading. Handlers in src/interface/verification_handlers.py (_generate_conv_verification*, _mark_conv_correct/_incorrect, _export_conv_records_to_{json,csv}). State lives in Gradio component state, not in a store. The Provider Summary is appended as the final exchange, and on that step the classification flag is hidden (see Gradio notes below).
• Enhanced Verification — batch testing via manual entry or CSV/XLSX upload (enhanced_verification_interface.py, manual_input_interface.py, file_upload_interface.py), persisted through JSONVerificationStore (src/core/verification_store.py) into verification_sessions/, exported to verification_exports/.

Feature toggles for both live in app_config.py (FEATURE_FLAGS, ENHANCED_VERIFICATION_CONFIG). Standard Verification is deliberately disabled there — its functionality was folded into Enhanced Verification; leave it off unless asked.

Gradio 6 gotchas this codebase has already been bitten by

• A gr.Radio handed "" raises (value not in choices) and fails the entire event response, painting "Error" across unrelated components. Normalize unselected radios to None.
• Handler return arity must match the outputs= list on every branch, including early returns and empty-session paths. Mismatches surface as unrelated UI breakage, not a clear traceback.

Conventions

• Everything imports absolute from the repo root (from src.core... import); scripts that may be run directly re-insert the project root into sys.path at the top.
• Property-based tests use Hypothesis and live in tests/verification_mode/test_properties_*.py and tests/chaplain_feedback/test_properties_*.py — these are the meaningful correctness gates. manual_tests/ holds scripts that hit real APIs and are run by hand, never in CI.
• Ignore src/interface/enhanced_verification_ui_backup.py — dead 1700-line copy kept around; don't edit it or use it as a reference.
• .gitignore excludes docs/, conversation_logs/, exports/, review/, verification_*/, and (oddly) src/core/verification_store.py — that last one is already tracked so edits commit normally, but git status will not surface new files in those paths.
• No PHI is persisted; API keys stay in .env.