Metadata-Version: 2.4
Name: synthmind
Version: 0.1.0
Summary: Synthetic patients and psychotherapy-protocol simulation for clinical psychology research and teaching.
Author-email: Buğra Ayan <bugraayan.com@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bugraayancom/synthmind
Project-URL: Documentation, https://github.com/bugraayancom/synthmind/tree/main/docs
Project-URL: Issues, https://github.com/bugraayancom/synthmind/issues
Project-URL: Author, https://bugraayan.com
Keywords: clinical-psychology,psychotherapy,synthetic-patients,simulation,rct,causal-inference,mental-health,education
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Provides-Extra: causal
Requires-Dist: networkx>=3.0; extra == "causal"
Provides-Extra: app
Requires-Dist: streamlit>=1.32; extra == "app"
Requires-Dist: plotly>=5.18; extra == "app"
Requires-Dist: matplotlib>=3.7; extra == "app"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo>=2024.01.29; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Dynamic: license-file

# synthmind

[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-97%20passing-brightgreen.svg)](tests)
[![Code style: ruff](https://img.shields.io/badge/lint-ruff-46aef7.svg)](https://github.com/astral-sh/ruff)
[![Built with synthdiet blueprint](https://img.shields.io/badge/blueprint-synthdiet-0EA5E9.svg)](https://github.com/bugraayancom/synthdiet)

> **Languages:**
> **English** ·
> [Türkçe](README.tr.md) ·
> [Español](README.es.md) ·
> [Français](README.fr.md) ·
> [Deutsch](README.de.md) ·
> [Português](README.pt.md) ·
> [Italiano](README.it.md) ·
> [中文](README.zh.md) ·
> [日本語](README.ja.md)

![synthmind hero](assets/hero.png)

**synthmind** is a Python library for clinical-psychology research and
teaching. It generates clinically realistic synthetic patients with
DSM-5 -- style mental-health conditions and simulates eight evidence-
based psychotherapy protocols (CBT, DBT, PE, EMDR, IPT, ACT, MBCT and
short-term psychodynamic therapy). On top of those primitives it
provides RCT engines, causal-inference utilities, OSCE-style teaching
cases, validation against five landmark trials, and a Streamlit
interface.

> **Disclaimer.** synthmind is a research and teaching tool. The
> patients generated in this interface are **not real**; the numbers
> shown **cannot be used as clinical recommendations**. For patient
> care always consult a qualified registered specialist.

## Author

**Buğra Ayan** — Ankara, Türkiye · [bugraayan.com](https://bugraayan.com)

## Features

* **27 mental-health disorders** across ten DSM-5 categories with
  parametric response curves calibrated to published meta-analyses.
* **31 psychometric instruments** (PHQ-9, GAD-7, HAMD-17, MADRS,
  BDI-II, PCL-5, CAPS-5, Y-BOCS, PANSS, CGI, WHOQoL-BREF, SDS,
  WAI-SR, AUDIT, DAST-10, ISI, PSQI, WHO-5, ORS, IIP-32 and more)
  with severity cut-offs and reliable-change values.
* **Eight evidence-based psychotherapy presets** that share a uniform
  `InterventionPlan` interface.
* **Two simulation engines** — a generic `Simulator` and the
  domain-specific `SymptomTrajectoryEngine` (exponential decay +
  alliance moderator + dose response).
* **Five generators** (`Random`, `Distribution`, `Copula`,
  `CohortSpec`, `Markov`).
* **Five behaviour models** (constant, decaying, stochastic-skip,
  perceived-burden, Weibull dropout).
* **Three RCT engines** (parallel, crossover, factorial) with
  ITT/PP/AT and ANCOVA on baseline-adjusted change.
* **Causal-inference toolkit** — counterfactual simulation, naive +
  IPTW + g-formula ATE estimators, conditional ATE, an E-value
  sensitivity sweep, and a hand-rolled `CausalDAG`.
* **Reliable-change & clinically-significant-change indices**
  (Jacobson-Truax), Cohen's *d*, Hedges' *g*, response and remission
  helpers.
* **Statistical helpers** — power, sample-size, bootstrap CI,
  permutation, Benjamini-Hochberg, ANCOVA.
* **Measurement-error & missingness injection** (CV%, MCAR, MAR, MNAR).
* **15 OSCE-style teaching cases** with a weighted rubric grader.
* **Validation against five landmark trials** (STAR\*D, TADS-equivalent,
  CALM, CATIE-equivalent, PROSPECT-equivalent).
* **Streamlit web app** with a clinical-clean theme, Plotly trajectory
  animations and a custom CONSORT diagram.
* **Documentation in nine languages** (en, tr, es, fr, de, pt, it,
  zh, ja).

## Installation

```bash
pip install -e ".[viz,causal,app,dev]"
```

For the Streamlit app you only need the `app` extra:

```bash
pip install -e ".[app]"
streamlit run app/streamlit_app.py
```

## 60-second tour

```python
import synthmind as sm

cohort = sm.DistributionGenerator(
    primary_diagnosis="major_depressive_disorder", seed=42,
).sample(80)

trial = sm.ParallelTrial(
    cohort=cohort,
    arms={
        "waitlist": sm.cbt_intervention(
            sessions_total=4, sessions_per_week=0.25,
            homework_minutes_per_week=0,
            expected_adherence=0.95, name="Waitlist (sham)",
        ),
        "active": sm.cbt_intervention(),
    },
    simulator=sm.Simulator(
        adherence=sm.WeibullDropout(),
        engine=sm.SymptomTrajectoryEngine(),
    ),
    duration_weeks=12,
    primary_biomarker="phq9",
)
result = trial.run(seed=7)
print(result.intention_to_treat())   # ANCOVA on PHQ-9 change
print(result.consort_diagram())
```

![Mean PHQ-9 trajectory](assets/rct_trajectory.png)

## Project layout

```
synthmind/
├── app/                     # Streamlit (5 pages + components + theme)
├── docs/                    # 9 languages (en + tr + es + fr + de + pt + it + zh + ja)
├── examples/                # 4 end-to-end Python scripts
├── paper/                   # JOSS draft
├── scripts/                 # build_translations + capture_screenshots + build_hero
├── src/synthmind/
│   ├── behavior/            # adherence + dropout
│   ├── causal/              # counterfactual + ATE + DAG + sensitivity
│   ├── diseases/            # 27-disorder registry
│   ├── education/           # 15 cases + OSCE
│   ├── evaluation/          # outcome reporting
│   ├── generators/          # 5 strategies
│   ├── indices/             # RCI + Jacobson-Truax + d / g
│   ├── interactions/        # ≥12 drug-biomarker interactions
│   ├── interventions/       # 8 psychotherapy presets
│   ├── noise/               # measurement-error + missingness
│   ├── patients/            # Patient + sub-records
│   ├── psychometrics/       # 31 instruments
│   ├── simulation/          # Simple + SymptomTrajectory engines
│   ├── stats/               # power + bootstrap + permutation + FDR + ANCOVA
│   ├── trials/              # parallel + crossover + factorial
│   ├── utils/               # constants + RNG + validators
│   ├── validation/          # 5 landmark-trial validators
│   └── viz/                 # optional matplotlib plots
└── tests/                   # 97 tests (92 fast + 5 slow validation)
```

## Extending

Register a new disease:

```python
from synthmind.diseases import (
    Disease, DiseaseCategory, PsychConstraints, register,
)

def my_response(patient, intervention, weeks):
    return {"phq9": -2.0 * weeks / 12}

register(Disease(
    name="my_new_diagnosis",
    label="My new diagnosis",
    icd10="F99",
    mesh="Mental Disorders",
    category=DiseaseCategory.MOOD,
    primary_biomarker="phq9",
    psych_constraints=PsychConstraints(citations=("Smith 2025",)),
    response_to_intervention=my_response,
))
```

## Citation

```bibtex
@software{ayan2026synthmind,
  author  = {Ayan, Buğra},
  title   = {synthmind: synthetic patients and psychotherapy
             simulation for clinical psychology},
  version = {0.1.0},
  year    = {2026},
  url     = {https://github.com/bugraayancom/synthmind},
}
```

## License

MIT — see `LICENSE`.
