Fuente: ddx-documentation/adr/0023-dx-assistant.md
- **Status:** Accepted (plan `osprey-ibis-parity`, reconciled 2026-11-12). - **Refines:** [ADR 0021](/es/docs/adr/0021-diagnosis-engine) (diagnosis engine) and [ADR 0022](/es/docs/adr/0022-ibis-pack-reuse) (IBIS pack reuse). Neither is rewritten. - **Plan:** `plans/osprey-ibis-parity/` (`specs/ASSISTANT.md`, `RAG.md`, `SCORING.md`, `CARDS.md`). - **Docs:** [features.md](/es/docs/features) §5g, `ddx-osprey-engine/CLAUDE.md` (CLI, routes, tables, suites). ## Context ADR 0021 gave Osprey a model-free scoring core and a form-driven run. Doctors also want a chat assistant ("Dudoxx Dx") that takes a case in free text, explains the differential, answers "what if" questions and writes a long case dossier. A chat model can write any number it likes. In a clinical product that is the failure to prevent. ## Decision 1. **The model talks, the core decides.** Every probability, odds, rank, grade, safety verdict and treatment order comes from `packages/ddx-diagnosis-core`. The chat agent proposes, asks, explains and cites. It cannot state a number the core did not return. 2. **Chat tools, persona and skills; no new lane, no new event type.** The catalogue holds the `dx_*` tools (case extract, run start / status / answer, what-if, explain, compare, treatment plan, knowledge search, literature search, deep dossier, card propose). Tools return handles and short summaries, never full cards. A persona "Dudoxx Dx" (SQL 008 / 023) carries the tool ids. At most two skills load per turn (SQL 023). The prompt is generic and never shaped by a test topic. 3. **Grounding guard on dx turns only.** A deterministic output processor checks each number in the assistant text against the tool results of the same turn (±0.5 pt rounding). A number that does not match is replaced by a block reference. Other personas are not touched. Suite `dx-assistant-grounding`. 4. **Pattern cards.** A pattern card is a curated set of 2-5 disease cards with joint relation strengths and shared findings. It adds a multimorbidity score. Relations need evidence; a miner may draft members only. 5. **Knowledge plane, Qdrant v2.** `osprey_dx_knowledge` gets named `dense` and `sparse` vectors (IDF modifier, deterministic hashed tokens) fused by RRF. `osprey_dx_entities` holds one point per entity (disease, pattern, finding, drug, treatment). Entity text is a deterministic template, never model prose. The dimension always comes from `DUDOXX_EMBEDDING_DIMENSION`. Rerank is `mmr`, `none` or an explicit router alias; a missing alias fails loudly (Cardinal #26). 6. **3D map with exact cosine.** `GET /diagnosis/runs/:runId/vector-map` and `GET /diagnosis/map` project vectors with a seeded PCA (deterministic). Layout is approximate; the shown cosine is exact and for display only. It never enters the Bayesian log-odds. 7. **Deep reasoning and dossier.** A supervisor with sub-agents (challenger, pattern-seeker, pharmacology, evidence-auditor) returns structured proposals only. The core rescore is the only effect. The dossier forks the deep-content runtime and passes run results and card ids, never the draft text. **Egress is de-identified**: a search guard (`assertDeidentifiedQuery`) rejects any query with a draft span, number-and-unit pair or date, and a source-registry URL gate limits fetches to registered sources. A `numbers-match` judge checks every dossier number against the stored run value. 8. **MCP server `/osprey/mcp/dx`.** `src/mcp/dx-server.ts` exposes `dx_knowledge_search`, `dx_card_get`, `dx_score_case` (de-identified concept states only) and `dx_drug_check` to other DDX products. It is mounted behind ddx-api (user or service key, tenant scoped). The engine stays on 127.0.0.1. 9. **Self-curation: producers file PENDING proposals only.** Producers are the curator, feedback, gap miner, estimate replacer, calibration watcher, pattern miner and the doctor. None can publish. Reviewer is never the proposer (checked in `decide()`), and the gold-set gate still decides. Scheduler jobs (`index/reconcile`, `eval/tick`, `curator/miners`) need `diagnosis:system` and claim `<job>:<windowKey>` in `dx_curator_job`, so two nodes never run one window twice. 10. **Must-not-miss `critical_lift`.** A critical card also pins when its own odds lift is high, so a rare critical diagnosis is not hidden by a low prior. Safety wins over ranking. 11. **In-pack EIG for questions.** Next-best questions come from expected information gain over the pack's own findings, weighted by cost class and must-not-miss mass. No model picks a question. 12. **Guidance section aliases.** Guidance reads IBIS card section names through an alias map, so imported cards fill the same guidance sections as seed cards. ## Consequences - A wrong number in chat is blocked by code, not by prompt wording. - The doctor can always trace a number to a core run, a card fact or a chunk id. - Search egress carries labels only; patient data stays on the Dudoxx router (no PHI off-host). - Scanned PDFs without text are marked `needs_text`; OCR is out of scope. - A new port is not needed: [ports.md](/es/docs/ports) is unchanged.
osprey-ibis-parity, reconciled 2026-11-12).plans/osprey-ibis-parity/ (specs/ASSISTANT.md, RAG.md, SCORING.md, CARDS.md).ddx-osprey-engine/CLAUDE.md (CLI, routes, tables, suites).ADR 0021 gave Osprey a model-free scoring core and a form-driven run. Doctors also want a chat assistant ("Dudoxx Dx") that takes a case in free text, explains the differential, answers "what if" questions and writes a long case dossier. A chat model can write any number it likes. In a clinical product that is the failure to prevent.
packages/ddx-diagnosis-core. The chat agent proposes, asks, explains
and cites. It cannot state a number the core did not return.dx_* tools (case extract, run start / status / answer, what-if, explain, compare, treatment plan,
knowledge search, literature search, deep dossier, card propose). Tools return handles and short
summaries, never full cards. A persona "Dudoxx Dx" (SQL 008 / 023) carries the tool ids. At most two
skills load per turn (SQL 023). The prompt is generic and never shaped by a test topic.dx-assistant-grounding.osprey_dx_knowledge gets named dense and sparse vectors (IDF
modifier, deterministic hashed tokens) fused by RRF. osprey_dx_entities holds one point per entity
(disease, pattern, finding, drug, treatment). Entity text is a deterministic template, never model
prose. The dimension always comes from DUDOXX_EMBEDDING_DIMENSION. Rerank is mmr, none or an
explicit router alias; a missing alias fails loudly (Cardinal #26).GET /diagnosis/runs/:runId/vector-map and GET /diagnosis/map
project vectors with a seeded PCA (deterministic). Layout is approximate; the shown cosine is exact
and for display only. It never enters the Bayesian log-odds.assertDeidentifiedQuery) rejects any query
with a draft span, number-and-unit pair or date, and a source-registry URL gate limits fetches to
registered sources. A numbers-match judge checks every dossier number against the stored run value./osprey/mcp/dx. src/mcp/dx-server.ts exposes dx_knowledge_search, dx_card_get,
dx_score_case (de-identified concept states only) and dx_drug_check to other DDX products. It is
mounted behind ddx-api (user or service key, tenant scoped). The engine stays on 127.0.0.1.decide()), and the gold-set gate still decides.
Scheduler jobs (index/reconcile, eval/tick, curator/miners) need diagnosis:system and claim
<job>:<windowKey> in dx_curator_job, so two nodes never run one window twice.critical_lift. A critical card also pins when its own odds lift is high, so a
rare critical diagnosis is not hidden by a low prior. Safety wins over ranking.needs_text; OCR is out of scope.adr/
deploy/
research/