LLMReasoningFailsClinical

Research code for evaluating explicit reasoning in large language models on clinical natural language processing tasks.

Background

This project compares matched direct-answer and explicit-reasoning (ER) prompting across diverse clinical text tasks, languages, and model families. Both conditions use the same task instruction, input, and final-answer format; only the ER condition requests an externalized reasoning trace. Task performance is calculated from the extracted final answer.

The repository supports local and provider-backed inference, paired prompt comparisons, task-specific evaluation, and reasoning-trace analyses. In configuration files, direct denotes direct-answer prompting and cot denotes CoT-style ER prompting.

Study overview

Figure 1. Study workflow

Figure 2. Overall performance across tasks and models

Quick start

Install the Python dependencies:

pip install -r requirements.txt

Create local configuration files from the committed templates:

cp inference/configs/API.key.example.yaml inference/configs/API.key.yaml
cp inference/configs/dict_model_path.example.json inference/configs/dict_model_path.json

Configure tasks and runtime options in inference/configs/inference.yaml, then run an experiment:

python -m inference.main \
  --model_name gpt-oss-20b \
  --gpus 0,1 \
  --engine vllm \
  --config inference/configs/inference.yaml \
  --model_file inference/configs/dict_model_path.json

Evaluate generated results with the separate evaluation configuration:

python -m inference.evaluation.runner
python -m inference.evaluation.runner --config inference/evaluation/config.yaml

For a public, fully synthetic pipeline check, use the task files and configs in inference/dataset_example. These fixtures cover classification, extraction, and generation without including clinical records.

Documentation

Detailed instructions are organized under Instructions for use/:

• Usage guide: inference, evaluation, experiments, analyses, and file layout.
• Reproduction instructions: tested environment, core settings, and a concise reproduction sequence.

Experiment workflows

Reproducible experiment recipes are provided for:

• paired prompt variants;
• Direct and ER few-shot prompting;
• five-sample self-consistency;
• large-scale overall performance.

Analysis modules

The maintained secondary analyses are separated by purpose:

• overall performance, including a converter from paired evaluation JSON files;
• language and task-type subgroups;
• reasoning-trace length;
• medical concept alignment;
• correct-versus-incorrect lexical patterns.

Every analysis includes a public example and a command-line entry point. Overall, subgroup, and valid-response examples use aggregate reported results; trace-level fixtures contain synthetic text.

Repository layout

• inference/: model execution and task evaluation, including configs/, dataset/, model/, metric/, prompt/, evaluation/, util/, and the public dataset_example/.
• analysis/: secondary analyses grouped by overall_performance/, subgroup/, length/, medical_concept/, and lexical_pattern/.
• experiment/: reproducible workflows for prompt_variants/, cot_few_shot/, cot_self_consistency/, and overall_performance/.
• scripts/: experiment launch helpers.
• Instructions for use/: usage and reproduction documentation.
• tests/: regression tests for the maintained runtime.
• fig/: public workflow and result figures.

Data and credentials

Benchmark datasets, model checkpoints, credentials, generated outputs, and performance artifacts are intentionally excluded from version control. The small inference/dataset_example/ fixtures are synthetic and intended for public release. Do not commit protected health information or regulated clinical data.

Development

Run the lightweight regression suite before committing changes:

pytest -q

License

This repository is distributed under the terms in LICENSE.