# PRISM — Polysubstance Risk & Interaction Surveillance for Mental-health prescribing

**Phase 3 of the [PRISM platform](https://github.com/SCharithaKodumagulla/PRISM-Platform).**

Clinical decision support checks *drug–drug* interactions. It largely ignores
*drug–substance* and *substance–substance* risk — which is where overdose mortality
actually comes from (opioid + benzodiazepine, opioid + alcohol).

PRISM is a reasoning layer that closes that gap and grounds an LLM in retrieved evidence
rather than recall. It ships as an **MCP server with 47 tools** and a web platform, both
driven by the same validated cascade.

> **Not a medical device.** PRISM surfaces evidence with its provenance. It does not give
> clinical advice, and the validation harness asserts that it never crosses that line.

---

## The 7-level evidence cascade

| Level | Source | Offline? |
|---|---|---|
| 1 | Curated interaction knowledge base | yes |
| 2 | OpenFDA drug labeling | live |
| 3 | CYP450 / transporter kinetics | yes |
| 4 | Pharmacodynamic stacking (e.g. CNS depression) | yes |
| 5 | Drug-class combinations | yes |
| 6 | **FAERS disproportionality signals** (Phase 2) | yes |
| 7 | External interaction sources | live |

Severity is the maximum across levels; **confidence scales with the number of *independent*
levels that fire** (1 → low, 4+ → very_high). The model cannot invent an interaction — it
can only report what a level returned, tagged with that level's source.

On top of the per-pair checks sits compound-risk synthesis: triple CNS-depressant stacks,
naloxone candidacy, cocaethylene formation, Beers criteria, teratogenicity — plus automatic
screening triggers (AUDIT, DAST-10, CUDIT-R, GAD-7, PHQ-9).

Proxy matching means street terms resolve to pharmacology: heroin → opioid class, street
benzos → benzodiazepine class.

## Population prior

Phase 1's NSDUH model is imported as a national baseline, so the system can answer "how
risky is this patient's profile relative to the population?" rather than only "do these two
drugs interact?" — 1,188 risk profiles, 60 annual trend rows, and the logistic coefficients
for real-time scoring.

## Validation

14 clinical scenarios run end-to-end through the live server and PostgreSQL:

- 2 cases flagged `life_threatening`; **0 instances of overstepping into advice**
- **Case 14 regression** (benzodiazepine + opioid) returns `life_threatening` across levels
  1, 4, 5, 6, 7 with `fda_black_box=True` — it returned *nothing* before the cascade was
  built, and it is the reason the cascade exists
- Audit rows persist to `cascade_results`, `compound_risk_alerts`, and `screening_queue`

The public repo ships a **synthetic** 14-case set that reproduces identical severities for
all 14 cases. See [`scenarios/README.md`](scenarios/README.md).

## Layout

```
src/
  server.py         FastMCP server, 47 registered tools
  cascade.py        the 7-level engine (DB-optional, unit-testable)
  cascade_tools.py  DB-backed cascade tools
  extra_tools.py    remaining registry tools
  live_apis.py      OpenFDA (L2) + RxNorm (L1) hooks
  api/app.py        FastAPI bridge for the web UI
  db/
    schema.sql              24 base tables
    migrations_path3.sql    +5 cascade tables (29 total)
    seed.py                 curated KB (+ private case loader)
    load_scenarios.py       scenario loader (synthetic or private)
    import_path3_data.py    imports Phase 1 + Phase 2 exports
web/                Next.js 14 app (8 pages, Tailwind, Recharts)
scenarios/          synthetic validation cases
validate_scenarios.py
```

## Setup

```bash
python -m venv venv && ./venv/bin/pip install -r requirements.txt
createdb prism_db
psql prism_db -f src/db/schema.sql
psql prism_db -f src/db/migrations_path3.sql

python -m src.db.seed --reference-only      # curated KB, no patient data
python -m src.db.load_scenarios --replace   # 14 synthetic cases
python src/db/import_path3_data.py          # Phase 1 + Phase 2 exports
python validate_scenarios.py
```

`import_path3_data.py` reads the sibling `NSDUH/` and `FAERS/` checkouts by default;
override with `NSDUH_RESULTS` and `FAERS_RESULTS` environment variables.

## Running the server

```bash
python -m src.server           # stdio  (Claude Desktop, Claude Code)
python -m src.server --http    # HTTP   on :8000
```

Register with an MCP host:

```json
{ "mcpServers": {
    "prism": {
      "command": "/path/PRISM/venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/PRISM",
      "env": { "DATABASE_URL": "postgresql://localhost/prism_db" }
}}}
```

## License

MIT (code). Clinical scenario source material is not distributed. Not a medical device; not
reviewed by any regulatory authority; must not be used to direct patient care.