{
  "engine": {
    "id": "cpe-006",
    "code": "CPE-006",
    "name": "Male Hypogonadism Pattern Engine",
    "version": "1.0.0",
    "url": "https://biod.ai/tools/testosterone",
    "status": "Executable specification v1.0.0, authored by Biod from the narrative CPE-006 specification and current guidelines. Reviewed by Dr. Vinicius Amaral, D.O. Not for clinical production use."
  },
  "notice": "Clinical decision support for licensed clinicians. Synthetic-data demonstration. Not FDA cleared. Physician adjudication required.",
  "rules": [
    {
      "id": "HG-SCOPE-01",
      "name": "Patient outside the adult male pathway",
      "group": "Scope and validity",
      "status": "active",
      "classification": "Priority 1",
      "summary": "Patient outside the adult male pathway. Evaluates age_years below 18.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "age_years < 18"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Routing: pediatric or adolescent endocrine pathway"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Adult male reference values and criteria do not apply."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-scope-01"
    },
    {
      "id": "HG-VAL-01",
      "name": "Sample timing or illness limits interpretation",
      "group": "Scope and validity",
      "status": "active",
      "classification": "Priority 2",
      "summary": "Sample timing or illness limits interpretation. Evaluates sample not drawn in the morning (7–10 am) OR acute illness OR recent high-dose biotin.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "sample not drawn in the morning (7–10 am) OR acute illness OR recent high-dose biotin"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Interpretation limited: testosterone varies with time of day and falls in acute illness"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Repeat a fasting morning total testosterone before drawing conclusions"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Does not discard the result; it labels it as provisional."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-AUA-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-val-01"
    },
    {
      "id": "HG-EXO-01",
      "name": "Exogenous androgen or testosterone therapy",
      "group": "Scope and validity",
      "status": "active",
      "classification": "Priority 2",
      "summary": "Exogenous androgen or testosterone therapy. Evaluates testosterone therapy OR anabolic-androgenic steroid use documented.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "testosterone therapy OR anabolic-androgenic steroid use documented"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Measured testosterone and gonadotropins reflect the exogenous exposure; baseline status cannot be classified"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Hypogonadism is not classified while exogenous androgens are being taken."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-exo-01"
    },
    {
      "id": "HG-01",
      "name": "Symptom pattern: testosterone not yet measured",
      "group": "Screening",
      "status": "active",
      "classification": "Priority 4",
      "summary": "Symptom pattern: testosterone not yet measured. Evaluates no total testosterone entered.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "no total testosterone entered",
            "at least one specific symptom (low libido, erectile dysfunction, loss of morning erections, infertility, gynecomastia, hot flushes, small testes, osteoporosis or fragility fracture) OR three or more symptoms of any kind"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Screening opportunity: measure a morning fasting total testosterone"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Order a fasting morning total testosterone (two samples to confirm a low value), with SHBG when it is borderline"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Symptoms are non-specific. They justify measuring, not a diagnosis."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-AUA-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-01"
    },
    {
      "id": "HG-02",
      "name": "One low testosterone result, not yet confirmed",
      "group": "Diagnosis",
      "status": "active",
      "classification": "Priority 3",
      "summary": "One low testosterone result, not yet confirmed. Evaluates first total testosterone below 300 ng/dL.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "first total testosterone < 300 ng/dL",
            "second sample not entered"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Low total testosterone on a single sample: confirmation is required before it is acted on"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Repeat a fasting morning total testosterone on a separate day"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Not a diagnosis."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-AUA-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-02"
    },
    {
      "id": "HG-03",
      "name": "Low testosterone confirmed on two samples",
      "group": "Diagnosis",
      "status": "active",
      "classification": "Priority 3",
      "summary": "Low testosterone confirmed on two samples. Evaluates two separate total testosterone results, both below 300 ng/dL.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "two separate total testosterone results, both < 300 ng/dL"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Biochemically low testosterone on two samples",
            "With compatible symptoms, the criteria for testosterone deficiency are met (Endocrine Society 2018, AUA 2018)"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Establishes the biochemical finding; the cause still has to be found."
          ]
        },
        {
          "heading": "Notes",
          "items": [
            "The Endocrine Society's harmonized lower limit for healthy young men is 264 ng/dL; the AUA uses 300 ng/dL. Values between 264 and 299 are flagged as low under the AUA cutoff only."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-AUA-2018",
        "EV-TRAVISON-2017"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-03"
    },
    {
      "id": "HG-04",
      "name": "Borderline total testosterone",
      "group": "Diagnosis",
      "status": "active",
      "classification": "Priority 5",
      "summary": "Borderline total testosterone. Evaluates total testosterone 300 to 350 ng/dL.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "total testosterone 300 to 350 ng/dL",
            "compatible symptoms"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Borderline: free testosterone may be informative when binding proteins are abnormal",
            "Calculated free testosterone (Vermeulen) is shown when SHBG is available"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Measure SHBG and consider a calculated or equilibrium-dialysis free testosterone",
            "Repeat the morning total testosterone"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "No free-testosterone threshold is applied: cutoffs are assay-specific."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-VERMEULEN-1999"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-04"
    },
    {
      "id": "HG-05",
      "name": "Primary (hypergonadotropic) pattern",
      "group": "Classification",
      "status": "active",
      "classification": "Priority 4",
      "summary": "Primary (hypergonadotropic) pattern. Evaluates low total testosterone.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "low total testosterone",
            "LH or FSH above the laboratory upper limit"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Pattern of primary testicular failure: testes are the likely site"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Consider the causes of primary hypogonadism (for example Klinefelter syndrome, prior orchitis, cryptorchidism, chemotherapy or radiation, trauma)"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "A pattern, not a cause."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-05"
    },
    {
      "id": "HG-06",
      "name": "Secondary (hypogonadotropic) pattern",
      "group": "Classification",
      "status": "active",
      "classification": "Priority 3",
      "summary": "Secondary (hypogonadotropic) pattern. Evaluates low total testosterone.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "low total testosterone",
            "LH low or inappropriately normal (not above the upper limit)"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Pattern of secondary hypogonadism: the problem is above the testes (hypothalamus or pituitary) or functional"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Measure prolactin and consider other pituitary hormones",
            "Review medications, obesity, sleep apnea and chronic illness"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Functional suppression and pituitary disease look alike here."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-06"
    },
    {
      "id": "HG-07",
      "name": "Hyperprolactinemia with low testosterone",
      "group": "Classification",
      "status": "active",
      "classification": "Priority 2",
      "summary": "Hyperprolactinemia with low testosterone. Evaluates prolactin above the laboratory upper limit.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "prolactin above the laboratory upper limit",
            "low total testosterone"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Priority: a raised prolactin can suppress testosterone and may reflect a pituitary lesion, medication or another cause"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Consider pituitary imaging when prolactin is clearly raised or there are mass-effect symptoms",
            "Review prolactin-raising drugs (antipsychotics, metoclopramide), hypothyroidism, renal failure and macroprolactinemia",
            "Address the cause before testosterone therapy is weighed"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Does not diagnose a prolactinoma."
          ]
        }
      ],
      "evidence": [
        "EV-ES-PRL-2011"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-07"
    },
    {
      "id": "HG-08",
      "name": "Reversible contributors present",
      "group": "Classification",
      "status": "active",
      "classification": "Priority 4",
      "summary": "Reversible contributors present. Evaluates low testosterone.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "low testosterone",
            "any of: obesity (BMI ≥30), diabetes or prediabetes, opioid use, chronic glucocorticoid use, untreated severe sleep apnea, heavy alcohol use, untreated hypothyroidism, severe weight loss, chronic illness"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Contributors that can lower testosterone are present and should be addressed"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Address the contributor and repeat testosterone, as the Endocrine Society advises"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Presence of a contributor does not prove it is the cause."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-08"
    },
    {
      "id": "HG-09",
      "name": "Possible chromosomal cause",
      "group": "Classification",
      "status": "active",
      "classification": "Priority 5",
      "summary": "Possible chromosomal cause. Evaluates primary pattern (HG-05).",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "primary pattern (HG-05)",
            "small testes OR tall stature OR gynecomastia OR learning difficulty"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Consider karyotype for Klinefelter syndrome"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "A prompt; the engine does not diagnose a syndrome."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-09"
    },
    {
      "id": "HG-10",
      "name": "Fertility desired",
      "group": "Safety",
      "status": "active",
      "classification": "Priority 2",
      "summary": "Fertility desired. Evaluates fertility desired.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "fertility desired",
            "low testosterone pattern OR testosterone therapy under consideration"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Caution: testosterone therapy suppresses spermatogenesis; evaluation and treatment differ when fertility is wanted"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Discuss fertility goals before any androgen therapy; consider referral to reproductive endocrinology or urology"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "The engine does not choose a therapy."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-AUA-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-10"
    },
    {
      "id": "HG-11",
      "name": "Testosterone-therapy cautions to review",
      "group": "Safety",
      "status": "active",
      "classification": "Priority 2",
      "summary": "Testosterone-therapy cautions to review. Evaluates testosterone therapy under consideration.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "testosterone therapy under consideration",
            "any of: prostate cancer, breast cancer, palpable prostate nodule or induration, PSA > 4 ng/mL, hematocrit > 50%, untreated severe sleep apnea, severe lower urinary tract symptoms, unstable heart failure, myocardial infarction or stroke in the last 6 months, thrombophilia"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Endocrine Society cautions or contraindications to testosterone therapy are present"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Resolve or evaluate each flag before any decision on therapy"
          ]
        },
        {
          "heading": "Never outputs",
          "items": [
            "a recommendation to start testosterone therapy"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "A screen of cautions. It is never an indication."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-TRAVERSE-2023"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-11"
    },
    {
      "id": "HG-12",
      "name": "Testosterone-therapy monitoring",
      "group": "Safety",
      "status": "active",
      "classification": "Priority 2",
      "summary": "Testosterone-therapy monitoring. Evaluates on testosterone therapy.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "on testosterone therapy",
            "hematocrit > 54% (priority) OR hematocrit not checked in the last 12 months OR PSA not checked in the last 12 months (age 40 and over)"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Hematocrit above 54% calls for evaluation and a pause in therapy per the Endocrine Society",
            "Interval prompts for hematocrit and PSA"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Monitoring prompts, not instructions to adjust therapy."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-AUA-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-12"
    },
    {
      "id": "HG-13",
      "name": "Bone health",
      "group": "Context triggers",
      "status": "active",
      "classification": "Priority 6",
      "summary": "Bone health. Evaluates low testosterone.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "low testosterone",
            "osteoporosis OR fragility fracture OR long-standing deficiency"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Bone density assessment should be considered"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "A prompt."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-13"
    },
    {
      "id": "HG-14",
      "name": "PSA elevation",
      "group": "Safety",
      "status": "active",
      "classification": "Priority 3",
      "summary": "PSA elevation. Evaluates PSA above 4 ng/mL.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "PSA > 4 ng/mL"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Elevated PSA needs urologic evaluation, and bears on any androgen therapy"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Does not diagnose prostate disease."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018",
        "EV-AUA-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-14"
    },
    {
      "id": "HG-15",
      "name": "Testosterone not low despite symptoms",
      "group": "Classification",
      "status": "active",
      "classification": "Priority 5",
      "summary": "Testosterone not low despite symptoms. Evaluates total testosterone above 350 ng/dL.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "total testosterone > 350 ng/dL",
            "symptoms documented"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "No biochemical testosterone deficiency from the value entered: non-specific symptoms have other causes"
          ]
        },
        {
          "heading": "Recommended next steps (for physician review)",
          "items": [
            "Consider other causes of the symptoms (depression, sleep disorders, thyroid disease, anemia, medications)"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "A normal value in one sample does not rule out all androgen problems."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-15"
    },
    {
      "id": "HG-SAFE-01",
      "name": "Possible pituitary mass effect",
      "group": "Safety",
      "status": "active",
      "classification": "Priority 1",
      "summary": "Possible pituitary mass effect. Evaluates severe or new headache OR visual field loss.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "severe or new headache OR visual field loss",
            "low testosterone OR raised prolactin"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Urgent assessment: possible pituitary mass effect"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Routine outpatient pathway is not appropriate."
          ]
        }
      ],
      "evidence": [
        "EV-ES-PRL-2011"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-safe-01"
    },
    {
      "id": "HG-MISS-01",
      "name": "Information needed to classify",
      "group": "Missing data",
      "status": "active",
      "classification": "Priority 8",
      "summary": "Information needed to classify. Evaluates low testosterone confirmed or single.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "low testosterone confirmed or single",
            "LH, FSH, prolactin or SHBG missing"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "The type of hypogonadism cannot be classified without gonadotropins and prolactin"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "Names what is needed."
          ]
        }
      ],
      "evidence": [
        "EV-ES-TRT-2018"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-miss-01"
    },
    {
      "id": "HG-CALC-01",
      "name": "Calculated free testosterone",
      "group": "Calculations",
      "status": "module",
      "classification": "Context",
      "summary": "Calculated free testosterone. Evaluates total testosterone and SHBG available.",
      "sections": [
        {
          "heading": "Condition",
          "items": [
            "total testosterone and SHBG available"
          ]
        },
        {
          "heading": "What it reports",
          "items": [
            "Free testosterone by the Vermeulen equation (albumin 4.3 g/dL assumed unless entered)"
          ]
        },
        {
          "heading": "Diagnostic boundary",
          "items": [
            "No threshold is applied."
          ]
        }
      ],
      "evidence": [
        "EV-VERMEULEN-1999"
      ],
      "url": "https://biod.ai/tools/testosterone/rules/hg-calc-01"
    }
  ],
  "evidence": [
    {
      "id": "EV-ES-TRT-2018",
      "citation": "Bhasin S, Brito JP, Cunningham GR, et al. Testosterone Therapy in Men With Hypogonadism: An Endocrine Society Clinical Practice Guideline. J Clin Endocrinol Metab. 2018;103(5):1715-1744.",
      "supports": [
        "Diagnose with symptoms plus unequivocally low testosterone on two morning fasting samples",
        "Contraindications and cautions to therapy; monitoring of hematocrit and PSA",
        "Evaluation of the type of hypogonadism with LH and FSH"
      ]
    },
    {
      "id": "EV-AUA-2018",
      "citation": "Mulhall JP, Trost LW, Brannigan RE, et al. Evaluation and Management of Testosterone Deficiency: AUA Guideline. J Urol. 2018;200(2):423-432.",
      "supports": [
        "Total testosterone below 300 ng/dL as the threshold; repeat and confirm; fertility counselling before therapy"
      ]
    },
    {
      "id": "EV-TRAVISON-2017",
      "citation": "Travison TG, Vesper HW, Orwoll E, et al. Harmonized reference ranges for circulating testosterone levels in men of four cohort studies in the United States and Europe. J Clin Endocrinol Metab. 2017;102(4):1161-1173.",
      "supports": [
        "Lower limit of 264 ng/dL in healthy young men"
      ]
    },
    {
      "id": "EV-VERMEULEN-1999",
      "citation": "Vermeulen A, Verdonck L, Kaufman JM. A critical evaluation of simple methods for the estimation of free testosterone in serum. J Clin Endocrinol Metab. 1999;84(10):3666-3672.",
      "supports": [
        "Calculated free testosterone from total testosterone, SHBG and albumin"
      ]
    },
    {
      "id": "EV-ES-PRL-2011",
      "citation": "Melmed S, Casanueva FF, Hoffman AR, et al. Diagnosis and treatment of hyperprolactinemia: an Endocrine Society Clinical Practice Guideline. J Clin Endocrinol Metab. 2011;96(2):273-288.",
      "supports": [
        "Causes of raised prolactin, including drugs and macroprolactin; when to image the pituitary"
      ]
    },
    {
      "id": "EV-TRAVERSE-2023",
      "citation": "Lincoff AM, Bhasin S, Flevaris P, et al. Cardiovascular Safety of Testosterone-Replacement Therapy. N Engl J Med. 2023;389(2):107-117.",
      "supports": [
        "Cardiovascular safety data in hypogonadal men at increased cardiovascular risk, with higher rates of atrial fibrillation, pulmonary embolism and acute kidney injury"
      ]
    }
  ]
}