Add patient_cohort_recruitment template (CSP, Graph + Rules + Prescriptive, multi-axis cohort coverage)

[chriscoey]

What this template adds

A clinical-research cohort-selection template that composes three reasoners over a patient knowledge graph:

• Graph reasoner — closes a kinase-pathway sub-ontology in one reachable(full=True) call, materializing every pathway gene as a KinaseGene extends Gene sub-concept.
• Rules — pure-relational lifting from the closure to per-patient eligibility (KinaseMutationCarrier, QualifyingPairPatient, EligiblePatient) and per-axis coverage facts (Patient.covers_kinase_gene, Patient.covers_therapy, Patient.covers_ae).
• Prescriptive (CSP) — picks K patients whose joint coverage spans at least MIN_GENES_COVERED distinct kinase genes, MIN_THERAPIES_COVERED distinct therapies, and MIN_AES_COVERED distinct adverse events. MiniZinc / Chuffed backend.

Modeling patterns this surfaces

• Sub-concept predicate markers, not Boolean indicator properties. EligiblePatient extends Patient and CoverableGene extends Gene make membership the predicate; downstream rules and the CSP just check Sub(Parent).
• solve_for scoped to sub-concepts. Decisions are created only on rows the rules established as meaningful — ineligible patients and never-covered Ys never get a decision, and the upper-bound ICs cleanly bind on the rows that do.
• Eligible-coverage scoping for Coverable*. A Y covered only by ineligible patients would otherwise sit in Coverable* with no upper-bound IC binding and the solver could mark it covered for free. Scoping to EligiblePatient.covers_* closes that gap structurally.
• 3-arity Patient.qualifying_pair relationship over (Patient, TherapyEvent, AdverseEventOcc) triples single-sources the AE-window predicate. QualifyingPairPatient, Patient.covers_therapy, and Patient.covers_ae are one-line projections.
• Per-pair coverage saturation. Upper bound Y.is_covered <= sum(in_cohort).per(Y) plus per-pair lower bound Y.is_covered >= EligiblePatient.is_in_cohort pin is_covered to the actual coverage truth-value, so the floor IC sum(is_covered) >= MIN_* constrains true coverage and the inspect() output cannot underreport.

Verification

• Pre-solve invariants — Python helpers raise focused ValueError for null/duplicate keys, dangling foreign keys, missing kinase root, and negative timestamps. Foreign-key edges declared in a single declarative table.
• Post-solve problem.verify() — re-evaluates all 10 ICs (cohort size + 3 upper + 3 lower + 3 floor) in the returned solution. Every IC is pure relational arithmetic.
• termination_status() == "OPTIMAL" assertion via model.require.
• Bundled fixture: 15 patients, 26 mutations, 12 AEs, 7 kinase-pathway genes (root + 2 internal + 4 leaves). 8 patients are eligible; the solver returns one of several feasible cohorts that hit the (MIN_GENES=3, MIN_THERAPIES=2, MIN_AES=2) floors.

References

The "How it works" section walks through each pillar with code excerpts. The Customize section covers swap-your-own-data, alternative cohort objectives (max coverage, min average age), tightening the qualifying window, additional eligibility conjuncts, and per-stratum fairness constraints. Troubleshooting covers INFEASIBLE, multi-cohort non-determinism, and the two encoding pitfalls (sub-concept target + eligible-coverage scoping) that produce the "is_covered=1 with no covering patient" symptom.

[github-actions]

The docs preview for this pull request has been deployed to Vercel!

✅ Preview:	https://relationalai-docs-7t12wfiov-relationalai.vercel.app/build/templates
🔍 Inspect:	https://vercel.com/relationalai/relationalai-docs/DLU37RTjWcNgsRhMmbRHkY7iYMRC

[cafzal]

Ship with nits. Sub-concept-as-predicate is genuinely novel in v1 — telco_network_recovery uses is_critical_restore as a Boolean Relationship marker, this template uses EligiblePatient extends Patient with solve_for(Sub.prop) keying decisions only to rows the rules established as meaningful (patient_cohort_recruitment.py:470-489). Eligible-coverage scoping verified by reproduction (lines 444-449, 505-518): BRAF mutated by ineligibles 10/14 but stays coverable because eligibles 1/4/7 also carry it. Per-pair coverage saturation LB (:528-541) genuinely pins is_covered so inspect() cannot underreport. Pre-solve invariants reusable (driven by an _FK_EDGES table). Closure exactly {1..7}; floors (3,2,2) non-trivially feasible; MAX(4,3,3) correctly unreachable. Distinct lesson vs. telco — both are Graph + Rules + CSP, no overlap in encoding lessons.

Issues (all NITs)

• README.md:50-51 — "10 genes ... 26 mutation events" missing a "bundled sample" / "illustrative" qualifier. Combined with P_Alpha...P_Oscar patient names, the demo-ness is implicit but should be explicit (per global no-PII / Demo-framing rule). Add one sentence in "What's included" or front-matter description.
• README.md:25 — "a EligiblePatient" should be "an" (vowel-sound rule). Article slip recurs in "How it works".
• README.md:159 — "fail at least one of: kinase-mutation, qualifying-pair within the 90-day window" reads like a 3-item list but is 2 items. Drop "at least one of" or reword to "fail either the kinase-mutation test or the qualifying-pair test".
• patient_cohort_recruitment.py:421 — dropped word: "...demonstrate a qualifying response pattern for are counted." Suggest "Only therapies and AEs with a within-window qualifying pair are counted."
• README.md:264 — section name "Customize this template" drifts from sample-template's "Customize".
• README.md:269 — gold parenthetical about the parent/sub-concept aggregation TypeError is buried at the end of a long bullet. Lift to its own bullet or move to Troubleshooting.
• README.md:23 — long opening sentence buries the lede; split for pacing.

py_compile and ruff check clean.