Treatment plan simulation

Most AI tools record a session and ask a chatbot whether it sounds like depression. Nyra is built so a clinician can draft a treatment plan, run it against the patient's graph, rehearse the hard moves, compare variants, and commit only the one that fits. This is the v2.5 clinician workbench. It ships after the clinician co-pilot. The constraints below are v2.5-blocking; if a design choice cannot satisfy them, the design choice does not ship.

The three modes

Forecast. The clinician drafts a TreatmentPlan. The agent writes a SimulationRun plus many PredictedOutcome nodes against the patient graph. Each prediction carries a confidence band (low / mid / high) and citations into the curated clinical evidence index. The UI never shows a single point estimate without its band.

Rehearse. A graph-grounded surrogate the clinician can converse with to refine wording, anticipate patient reactions, and stress-test the plan's hardest moves. RehearsalTurn nodes are captured for audit and review. They never appear on the patient surface. The surrogate is always clearly labeled as a simulation; it is never named with the patient's real name.

Compare. N PlanVariant children branched from one parent TreatmentPlan, each with its own SimulationRun, surfaced side by side. Differences highlight where the variants diverge: which intervention starts first, what the homework cadence looks like, where the scale checkpoints land.

The commit boundary

No SimulationRun mutates the live patient graph. The only path from simulation to live is the explicit commit boundary, gated by a licensed clinician. When the clinician commits a chosen variant, the variant's proposed Homework, Session, and Scale checkpoints are promoted into the live graph through committed_as edges. The commit screen names exactly what is about to be promoted and requires explicit confirmation.

The agent never commits a plan on its own.

The sandboxed subgraph

Every node a SimulationRun writes lives in a simulation subgraph keyed by simulationRunId, separate from the live patient graph. The two subgraphs share schema but never share storage. The clinician can query simulation history per patient; the patient never sees it. Unchosen variants stay in the simulation subgraph as history when one variant is committed.

Safety constraints (all v2.5-blocking)

1. No certainty. Every simulation output is a draft. Forecasts ship with confidence bands and the data they were generated from. The UI never displays a single point estimate without its band.
2. No patient impersonation. The rehearsal surrogate is never named with the patient's real name. Always clearly labeled as a simulation. Patients are told during the consent flow that the clinician may simulate plans against their data and that simulator outputs are clinician-only.
3. No simulation of crisis content. The surrogate refuses to roleplay suicidal ideation, self-harm, abuse disclosure, psychosis presentations, substance crisis, or eating-disorder-crisis material. Enforced in the system prompt and in a post-generation refusal filter.
4. No live-graph mutation. Sandboxed subgraph only. Commit boundary is the only crossing.
5. No autonomous plan commitment. A licensed clinician commits. Always.
6. Audit completeness. The append-only audit chain logs every SimulationRun, every variant generated, every RehearsalTurn, every comparison surface viewed, and the moment of commitment with the chosen variant id. Hash-linked. Queryable by the clinician but not deletable.

What the patient sees

Nothing about the simulator. The patient surface continues to be reflection + scale + crisis. The patient is told once, in the consent flow, that the clinician may use a simulator against their data; the patient does not see simulator outputs, rehearsal transcripts, or unchosen variants.

What the patient eventually sees is the committed plan, on the live graph, as Homework and Session and Scale checkpoints. That is also the moment the clinician's commit is confirmed.

Why this is here at all

Forecasting clinical trajectories is hard; getting it wrong with overconfidence is harmful. The reason simulation can be useful in the Nyra framing is exactly the reason most products skip it: the only honest version requires aggressive constraints on what the simulator is allowed to say and do. Drafts, not predictions. Variants, not recommendations. The clinician commits, not the agent.

The full simulation node and edge taxonomy, the data flow, and the modality-aware forecasting behavior are all defined in the internal docs (GRAPH-SCHEMA.md, ARCHITECTURE.md, MODALITIES.md, SAFETY.md inside this repo's docs/ directory). If you are building on top of this surface, those four documents must stay consistent with each other and with this public summary.