clinlat 0.3.0

A symbolic substrate for clinical decision-making based on refinable hypothesis lattices and sound deduction operators
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! # `clinlat` — Clinical Lattice Types
//!
//! A Rust substrate for symbolic clinical decision-making based on refinable hypothesis lattices
//! and sound deduction operators.
//!
//! ## Overview
//!
//! The `clinlat` crate provides:
//!
//! - [`Hyp`]: A partially ordered set (poset) of clinical hypotheses, ordered by refinement.
//! - [`Outcome<H, A>`]: A sum type for operator results (refined hypothesis or abstention).
//! - **Deduction operators**: Sound functions that refine hypotheses using clinical evidence
//!   (e.g., [`sofa::SofaRespOperator`] for respiratory dysfunction severity).
//!
//! ## Architecture
//!
//! ### Hypotheses and Refinement
//!
//! A [`Hyp`] represents a set of clinical atoms at some level of specificity.
//! Hypotheses are ordered by **refinement**: `h1 ⊑ h2` (h1 refines h2) means h1 is more specific.
//!
//! ```
//! # use clinlat::{Hyp, Atom, OntologySystem};
//! let unknown = Hyp::unknown();  // Top element: no information.
//! let atom = Atom {
//!     system: OntologySystem::SNOMED,
//!     code: "67822003".to_string(),
//!     preferred_term: "Hypoxemia".to_string(),
//!     version: "2026-01-31".to_string(),
//! };
//! let specific = Hyp::new(vec![atom]);  // More specific.
//! assert!(specific < unknown);  // Refinement ordering.
//! ```
//!
//! ### Operators
//!
//! An [`Operator`] takes a hypothesis and evidence, producing an [`Outcome`]:
//!
//! ```ignore
//! impl Operator for MyOperator {
//!     fn apply(&self, h: &Hyp, e: &Evidence) -> Outcome<Hyp, AbstainReason> {
//!         // Refine h using evidence e, or abstain with a reason.
//!     }
//! }
//! ```
//!
//! Operators are **sound** by construction: they satisfy three properties (DEF-PS-08):
//! 1. **Refinement monotonicity**: Hypothesis specificity never decreases.
//! 2. **No spurious refinement**: Output never exceeds evidence justification.
//! 3. **Abstention purity**: Abstention is structural, not error handling.
//!
//! ### SOFA-3 Respiratory Scoring
//!
//! The [`sofa`] module implements one operator: SOFA-3 respiratory severity (PaO₂/FiO₂ ratio).
//!
//! ```
//! # use clinlat::sofa::{SofaRespEvidence, score_from_ratio};
//! let evidence = SofaRespEvidence::new(350.0, 1.0, false);
//! let ratio = evidence.pao2_fio2_ratio().unwrap();
//! let score = score_from_ratio(ratio, false);  // Maps to SOFA score.
//! assert_eq!(score, Some(1));
//! ```
//!
//! ## v0.2.0-alpha Status
//!
//! Shipped (Phases 0–3 of the M1 milestone):
//!
//! - [`Atom`] replaces the v0.1.0 `&'static str` AtomId; resolved through four
//!   [`OntologyAdapter`] implementations (SNOMED CT, RxNorm, LOINC, ICD-11).
//! - [`operator::Evidence`] is a typed struct carrying [`Observation`]s and a
//!   [`Provenance`] carrier (DEF-PS-12, DEF-PS-13).
//! - [`Provenance`] is a typed carrier with origin, timestamp, operator version,
//!   metadata, and optional `derives_from` hashes (DEF-MP-14, OBL-PS-04).
//! - [`sofa::SofaRespOperator`] enforces the version-respecting derivation chain
//!   invariant (INV-PS-05) by abstaining on version mismatch rather than
//!   silently producing refined output.
//! - Galois connection: [`operator::abstract_evidence`] (α_PS) and
//!   [`operator::is_consistent_with`] (the γ_PS predicate) are property-tested
//!   for the adjunction laws, discharging OBL-PS-02.
//!
//! Deferred to later phases of the v0.2.0 cut:
//!
//! - `OperatorSet` formalization (Phase 4).
//! - KDIGO AKI, Wells/PE, CURB-65 operators (Phase 5).
//! - SOFA-respiratory property-test tier upgrade (Phase 6).
//!
//! ## References
//!
//! - **Position**: [Substrate-First Clinical AI](https://github.com/SHA888/SFClinAI)
//!   (NOTE.md § 4A–4D).
//! - **Formalization**: SPEC.md § 2 (patient-state substrate).
//! - **SOFA-3**: Vincent et al. (1996), Singer et al. (2016, Sepsis-3).

pub mod abstain;
pub mod curb65;
pub mod hyp;
pub mod kdigo_aki;
pub mod lattice_search;
pub mod llm_proposer;
pub mod llm_proposer_config;
pub mod ontology;
pub mod operator;
pub mod operator_set;
pub mod outcome;
pub mod proposer;
pub mod provenance;
pub mod sofa;
pub mod version;
pub mod wells_pe;

pub use abstain::AbstainReason;
pub use curb65::Curb65Operator;
pub use hyp::Hyp;
pub use kdigo_aki::KdigoAkiOperator;
pub use lattice_search::LatticeSearchProposer;
pub use llm_proposer::LlmProposer;
pub use llm_proposer_config::{LlmProposerConfig, LlmProvider};
pub use ontology::{
    Atom, CacheMode, Icd11Adapter, LoincAdapter, OntologyAdapter, OntologyError, OntologySystem,
    RxNormAdapter, SNOMEDAdapter,
};
pub use operator::{Evidence, Observation, Operator, abstract_evidence, is_consistent_with};
pub use operator_set::{OperatorMetadata, OperatorSet, SetOutcome};
pub use outcome::Outcome;
pub use proposer::{
    CandidateSet, ConstraintError, FilterResult, ProposerConstraint, RefinementProposer,
    VerifyResult, propose_and_filter, propose_verify,
};
pub use provenance::{Provenance, ProvenanceOrigin};
pub use sofa::{SofaRespEvidence, SofaRespHypothesis, SofaRespOperator};
pub use version::Ver;
pub use wells_pe::WellsPeOperator;