Cohorts & Estimators API

Cohort similarity

POST /api/v1/projects/{projectId}/lattice/cohort

Find subjects whose behavior looks like the target’s — top-K nearest neighbors ranked by a blended score (RFM + entity Jaccard + pattern-kind Jaccard).

{
  "subject": { "kind": "customer", "externalId": "acct-42" },
  "k": 10,
  "minSimilarity": 0.3
}

Response members carry similarity, the member’s rfmSegment, and the patternKinds active on them — enough to annotate “Mike has the same recurring_event + entity_preference as Sarah” without a second round-trip. k is clamped to [1, 50].

Cohort-aware prediction

POST /api/v1/projects/{projectId}/lattice/cohort/predict

Aggregate predictions across the target’s cohort, so “people like Sarah also ordered pizza on Fridays” surfaces even when Sarah’s own signal is weak.

{
  "subject": { "kind": "customer", "externalId": "acct-42" },
  "cohortK": 10,
  "predictionLimit": 10,
  "minSimilarity": 0.3
}

Each CohortPrediction carries full provenance — supportingSubjects (which cohort members contributed) and sourceMemoryIds (which patterns).

Estimators

POST /api/v1/projects/{projectId}/lattice/estimate

Run a deterministic estimator over a subject’s signal memories. The first estimator is phenoage (biological / “health” age from lab signals).

{
  "subject": { "kind": "patient", "externalId": "pt-9" },
  "estimatorId": "phenoage",
  "persist": false
}

Response:

{
  "subject": { "kind": "patient", "externalId": "pt-9" },
  "estimatorId": "phenoage",
  "ok": true,
  "value": 41.2,
  "unit": "years",
  "contributors": [ { "signal": "crp", "contribution": 1.4 } ],
  "confidence": 0.8,
  "provenance": ["mem_…"],
  "framing": "estimate",
  "disclaimer": "Not a diagnosis…",
  "missingSignals": []
}

When ok is false, missingSignals lists the required signals that had no reading. Set persist: true to save the score as a kind=estimate memory so it builds a trajectory and feeds calibration.

Health vertical

The healthcare surfaces require the @thinkfleet/pack-healthcare pack (gated on the health entitlement).

POST /api/v1/projects/{projectId}/lattice/health/profile — biological age (PhenoAge core + composite adjustments) plus predicted conditions (biomarkers trending toward or above clinical thresholds), from recorded biomarkers, demographics, and ICD-10 diagnoses.

POST /api/v1/projects/{projectId}/lattice/health/cohort-risk — condition prevalence among the patients most similar by baseline features (age, sex, BMI, biomarkers). Aggregate / de-identified base rates; opted-out subjects excluded.