Sovereign 8s.is mirror of standardgalactic/WiseMind-DDx-Psyc
  • Jupyter Notebook 45.8%
  • HTML 23%
  • Roff 21.4%
  • Python 9.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Yuqi Wu (Research) 4e1ed40627 Review Ready
2025-11-24 01:19:19 -07:00
.conda clean up 2025-11-16 01:43:20 -07:00
data Review Ready 2025-11-24 01:19:19 -07:00
src Review Ready 2025-11-24 01:19:19 -07:00
.DS_Store clean up 2025-11-16 01:43:20 -07:00
LICENSE Initial commit 2025-11-13 06:07:15 +08:00
README.md Review Ready 2025-11-24 01:19:19 -07:00

WiseMind: Virtual Standard Patients & Differential Diagnosis System

This repository contains the WiseMind prototype system, including:

  • A web-based psychiatric diagnostic conversation agent
  • A Virtual Standard Patient (VSP) generation pipeline
  • DSM-inspired decision trees for differential diagnosis
  • Example simulated interviews illustrating the full reasoning workflow

The system is intended for research, demonstration, and reviewer evaluation purposes only.


🚀 1. Running the WiseMind Web App

You can run WiseMind through our hosted demo URL. The original code was not released due to the confidentiality.


Hosted Demo (For Reviewers Only)

A temporary, rate-limited demonstration endpoint is available at:

👉 http://140.206.187.2/wisemind/

This instance uses an author-provided API key for testing and review only. It is not intended for production or clinical use.


🧪 2. Generating Virtual Standard Patients (VSPs)

We provide src/generate_vsp.py to construct VSP scripts—consistent, DSM-grounded, first-person patient profiles.

VSPs are generated from DSM-style diagnostic decision trees and include:

  • A binary met/not-met vector over all DSM decision nodes
  • A full, coherent first-person symptom narrative generated by an LLM
  • One CSV per VSP with fields: Node, Met_Criteria, Description, Patient_Story

Usage

From src/:

python generate_vsp.py --disorder mdd --vsp-id MDD_0

Command-line Options

Argument Description
--disorder {mdd, anx, bp} Choose which decision tree to use.
mdd — Depressed mood tree
anx — Anxious mood tree
bp — Elevated mood / bipolar tree
--vsp-id <ID> File identifier for the generated VSP (e.g., MDD_0)
--diagnosis-name <LABEL> (Optional) Select leaf diagnosis by label (e.g., "MDD")
--leaf-path <PATH> (Optional) Use an exact tree path (advanced)
--data-dir Where tree CSVs are stored (default: ../data)
--out-dir Where to save generated VSP CSVs (default: ../data/vsp_scripts)

Where VSP Files Are Saved

Generated VSP profiles are stored under:

data/vsp_scripts/<vsp_id>.csv

We also provide example pre-generated VSPs:

data/Medical/example_vsp_<disorder>/

🎭 3. Example Simulated Interviews

In:

data/Medical/Example Simulated Interview/

you will find three example simulated WiseMind–VSP diagnostic sessions.

Each example JSON includes:

  • Ground-truth disorder (gt_disorder)
  • WiseMind's prediction (pred_disorder)
  • Final and intermediate diagnostic accuracy
  • The complete node-by-node reasoning path
  • Node-level RA summaries and decisions
  • Full multi-turn conversation transcript
  • Reasoning logs for each question and action
  • Inference time and number of rounds

These examples illustrate:

  • How WiseMind interacts with VSPs
  • How the Structured Knowledge Graph (SKG) drives decision-making
  • How reasoning and empathy are combined
  • How final diagnoses are produced

🌳 4. Decision Trees & Structured Knowledge Graph (SKG)

4.1. Interactive Tree Notebook

The notebook:

src/differential_diagnosis_tree.ipynb

demonstrates how we construct and manipulate the DSM-inspired binary decision trees used as the SKG.

It includes:

  • Example tree construction
  • DFS traversal and path extraction
  • Visualization utilities
  • Exporting trees to CSV for VSP generation

4.2. DSM Decision Tree CSV Files

Each disorder category has a detailed decision-tree CSV:

mdd_tree_dfs_detailed.csv   # depressed mood
anx_tree_dfs_detailed.csv   # anxious mood
bp_tree_dfs_detailed.csv    # elevated mood / bipolar

Each row contains:

  • path: hierarchical identifier (used to reconstruct parent-child relations)
  • name: node label
  • Description: clinical meaning of the decision node

These files are consumed by:

  • generate_vsp.py (for VSP creation)
  • WiseMind (for structured diagnostic reasoning)
  • SKG visualisation scripts

🧭 5. Disorder Code Interpretation

Throughout the repository:

  • mdd → depressed mood / major depressive pathway
  • anx → anxious mood / anxiety decision tree
  • bp → elevated mood / bipolar spectrum decision tree

These codes appear in file names, CLI arguments, and analysis scripts.


📂 6. Repository Structure (Simplified)

src/
  app.py                         # FastAPI application
  generate_vsp.py                # Generate Virtual Standard Patients
  differential_diagnosis_tree.ipynb

data/
  
  Medical/
  mdd_tree_dfs_detailed.csv
  anx_tree_dfs_detailed.csv
  bp_tree_dfs_detailed.csv
  example_vsp_mdd/             # example VSP scripts
  example_vsp_anx/
  example_vsp_bp/
  Example Simulated Interview/ 
  vsp_scripts/                   # auto-generated VSPs
    

README.md                        # this file

📝 Citation

If you use this code in academic work, please cite the associated manuscript:

WiseMind: Recontextualizing AI with a Knowledge-Guided, Theory-Informed Multi-Agent Framework for Instrumental and Humanistic Benefits (2025).


⚠️ Disclaimer

This system is a research prototype and is not approved for clinical use. It is intended solely for:

  • Academic research and evaluation
  • Demonstration of multi-agent AI diagnostic frameworks
  • Virtual standard patient methodology development

Do not use this system for actual patient diagnosis or treatment decisions.


📧 Contact

For questions, issues, or collaboration inquiries, please contact:


🔒 License

Apache 2.0


🙏 Acknowledgments

This work was supported by [funding sources]. We thank:

  • The developers of the KangNing dataset
  • Clinical collaborators at University of Alberta
  • Research participants who contributed to user evaluations