# Phoebe — Brain-Computer Interface, Neuroscience & Clinical Psychology

`libs/phoebe/*` is the workspace for the **Phoebe** domain: the science and
medicine of the brain and mind. See `DOMAINS/phoebe/` for architecture,
features, and specifications, and **TODO Phase 181** (`TODOS/phase-181.md`) for
the implementation roadmap.

Phoebe is a **standalone domain that depends on** existing assets via contracts
(Iris BCI device layer, Aphrodite biosignals, Psyche affective computing, the
Phase 178 autonomous-research substrate, Kalika research agents). It does not
move or absorb their code.

## Package map (planned — built incrementally per Phase 181)

| Package                      | Owns                                                                | Status   |
| ---------------------------- | ------------------------------------------------------------------- | -------- |
| `@phoebe/core`               | Domain primitives, RDoC/HiTOP dimensional model, state machines     | ✅ built |
| `@phoebe/neural-io`          | Multimodal acquisition + LSL/XDF sub-ms time-sync                   | planned  |
| `@phoebe/signal`             | Real-time DSP (ICA/CSP/xDAWN/Riemannian)                            | planned  |
| `@phoebe/decoding`           | Decoder runtime, neural foundation models, cross-subject adaptation | planned  |
| `@phoebe/neuromodulation`    | Closed-loop aDBS/RNS/tFUS/TI, read–write, safety governor           | planned  |
| `@phoebe/connectomics`       | FFN segmentation, CAVE proofreading, petascale graph serving        | planned  |
| `@phoebe/simulation`         | NEST/NEURON/Arbor/Brian2 over SONATA, multi-scale co-sim            | planned  |
| `@phoebe/brain-models`       | Brain foundation models + circuit/region digital twins              | planned  |
| `@phoebe/neuro-analysis`     | SpikeInterface/Kilosort, LFADS/CEBRA, manifolds                     | planned  |
| `@phoebe/assessment`         | PHQ-9/GAD-7/PCL-5/C-SSRS + DSM-5-TR/ICD-11 coding                   | planned  |
| `@phoebe/mbc`                | Measurement-based + collaborative care                              | planned  |
| `@phoebe/phenotyping`        | Passive sensing, EMA, voice biomarkers, JITAI                       | planned  |
| `@phoebe/comp-psychiatry`    | RDoC/HiTOP models, biotypes, treatment matching                     | planned  |
| `@phoebe/therapeutics`       | CBT/DBT/ACT/MI content, anti-sycophancy, clinician copilot          | planned  |
| `@phoebe/hypothesis`         | KG-grounded generate/debate/rank + novelty/feasibility              | planned  |
| `@phoebe/design`             | BOED/DAD/ADO, Bayesian adaptive trials, SMART/JITAI                 | planned  |
| `@phoebe/experiment-runtime` | Frame-precise authoring/runtime + closed-loop/robotic execution     | planned  |
| `@phoebe/subjects`           | Panel connectors, data-quality firewall, eligibility matching       | planned  |
| `@phoebe/analysis`           | BIDS-App/MNE pipelines, causal inference                            | planned  |
| `@phoebe/reproducibility`    | Auto-preregistration, multiverse, provenance ledger                 | planned  |
| `@phoebe/knowledge-graph`    | Biolink KG, ontology service, RDoC OWL + DSM↔ICD crosswalk          | planned  |
| `@phoebe/literature`         | PubMed/OpenAlex/S2 ingestion, SciFact claim extraction              | planned  |
| `@phoebe/evidence-synthesis` | Living systematic reviews, GraphRAG + KGARevion                     | planned  |
| `@phoebe/datasets`           | FAIR catalog, NWB/BIDS/DICOM I/O                                    | planned  |
| `@phoebe/governance`         | Neurorights/HIPAA/GDPR, defacing, federated + DP compute            | planned  |
| `@phoebe/regulatory`         | FDA SaMD + PCCP, bias/drift testing, RCT evidence                   | planned  |
| `@phoebe/safety`             | 988 crisis routing, age-gating, jurisdiction-aware HITL             | planned  |
| `@phoebe/ai`                 | Autonomous closed-loop neuroscientist + fail-closed AI-IRB          | planned  |
| `@phoebe/integration`        | Cross-domain hub                                                    | planned  |
| `@phoebe/contracts`          | Zod contracts + cross-domain DTOs                                   | planned  |

## Hard requirements (enforced across every package)

1. **Fail-loud uncertainty** — every inference/decode/prediction carries
   calibrated uncertainty; out-of-scope requests return an explicit refusal.
2. **Human-in-the-loop** — no autonomous diagnosis, prescribing, or unsupervised
   therapy.
3. **Append-only audit** — stimulation events, data access, and autonomous
   actions are immutably logged.
4. **Jurisdiction-aware compliance** — feature availability gated by the user's
   jurisdiction (AI-therapy law; neurorights).
5. **Standards-native data** — recordings are born NWB/BIDS/XDF-conformant with
   W3C-PROV provenance.
6. **Real-time safety** — the decode→stimulate loop has bounded deadlines, a
   thermal/charge governor, watchdogs, and a fail-safe stop.

## Local development

Because the monorepo runs many worktrees, prefer direct tooling over Nx:

```bash
cd libs/phoebe/core
npx tsc --noEmit          # type check
npx vitest run            # tests
npx tsc -p tsconfig.lib.json   # build
```
