Improve lab knowledge graph from common labs PDF

Co-authored-by: Codex <chatgpt-codex-connector[bot]@users.noreply.github.com>

kb/cbc_knowledge_graph.json

@@ -266,7 +266,7 @@
       "category": "Liver",
       "unit": "U/L",
       "description": "ALT measures liver enzyme released when liver cells are stressed.",
-      "why_important": "ALT is fairly liver-specific; elevations can follow fatty liver, alcohol, medications, or viral hepatitis. A low ALT is not typically a concern.",
+      "why_important": "ALT is usually interpreted as a liver enzyme, but it can also rise with skeletal muscle injury; fatty liver, alcohol, medications, viral hepatitis, CK, AST, and GGT help provide context. A low ALT is not typically a concern.",
       "sex_significance": {
         "level": "low",
         "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
@@ -882,7 +882,7 @@
       "category": "Liver",
       "unit": "U/L",
       "description": "AST measures enzyme from liver and muscle cells.",
-      "why_important": "AST rises with liver stress but also comes from muscle; the AST/ALT pattern helps point to a cause. A low AST is not typically a concern.",
+      "why_important": "AST rises with liver stress but also comes from skeletal muscle; CK and GGT can help separate muscle from liver or bile-duct patterns. A low AST is not typically a concern.",
       "sex_significance": {
         "level": "low",
         "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
@@ -928,6 +928,65 @@
       "source_ids": [],
       "video_url": "https://www.youtube.com/watch?v=7_-ZtM0TieA"
     },
+    {
+      "id": "band_neutrophils_percent",
+      "display_name": "Band Neutrophils Percent",
+      "aliases": [
+        "Band Neutrophil %",
+        "Band Neutrophils",
+        "Band %",
+        "Bands",
+        "Stab Neutrophils"
+      ],
+      "category": "CBC",
+      "unit": "%",
+      "description": "Band Neutrophils Percent measures percentage of immature neutrophils in the white-cell differential.",
+      "why_important": "A high band neutrophil percentage may suggest a left shift, often seen when the marrow is releasing immature neutrophils during infection, inflammation, or physiologic stress. A low band neutrophil percentage is usually expected and not clinically significant on its own.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report provides a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": [
+          "Support healthy blood production with balanced protein, iron, B12, folate, and vitamin C from whole foods.",
+          "Stay well hydrated unless a clinician advises fluid restriction."
+        ],
+        "exercises": [
+          "Use moderate activity as tolerated when blood counts are stable.",
+          "Avoid intense training if anemia, infection, or bleeding symptoms are present until evaluated."
+        ],
+        "supplements": [
+          "Discuss iron, B12, or folate supplementation only when testing supports a deficiency.",
+          "Do not start blood-building supplements without clinician guidance."
+        ]
+      },
+      "statistics_per_group_age": {
+        "child": {
+          "minimal_value": 0,
+          "normal_value": 3.0,
+          "maximum_value": 6
+        },
+        "teenager": {
+          "minimal_value": 0,
+          "normal_value": 3.0,
+          "maximum_value": 6
+        },
+        "adult": {
+          "minimal_value": 0,
+          "normal_value": 3.0,
+          "maximum_value": 6
+        },
+        "elder": {
+          "minimal_value": 0,
+          "normal_value": 3.0,
+          "maximum_value": 6
+        }
+      },
+      "related_tests": [],
+      "source_ids": [],
+      "video_url": "https://www.youtube.com/watch?v=AvVnjqShhWE"
+    },
     {
       "id": "bas_absolute",
       "display_name": "Absolute Basophil Count",
@@ -1232,7 +1291,7 @@
       "category": "Metabolic",
       "unit": "mmol/L",
       "description": "Bicarbonate measures main blood buffer for acid-base balance.",
-      "why_important": "A high bicarbonate may reflect metabolic alkalosis or compensation for lung issues. A low bicarbonate may reflect metabolic acidosis or severe diarrhea.",
+      "why_important": "A high bicarbonate or total CO2 may reflect metabolic alkalosis or compensation for lung/respiratory issues. A low bicarbonate or total CO2 may reflect metabolic acidosis, severe diarrhea, or other acid-base stress.",
       "sex_significance": {
         "level": "low",
         "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
@@ -1893,6 +1952,66 @@
       "source_ids": [],
       "video_url": "https://www.youtube.com/watch?v=udVccTOnmrM"
     },
+    {
+      "id": "coenzyme_q10",
+      "display_name": "Coenzyme Q10",
+      "aliases": [
+        "CoQ10",
+        "Coenzyme Q 10",
+        "Total Coenzyme Q10",
+        "Total Coenzyme Q 10",
+        "CoQ10 Profile",
+        "Total CoQ10"
+      ],
+      "category": "Vitamin",
+      "unit": "mcg/L",
+      "description": "Coenzyme Q10 measures mitochondrial electron-transport cofactor and antioxidant.",
+      "why_important": "A high CoQ10 level is most often supplement-related and may also track with lipoprotein levels. A low CoQ10 level may reflect nutritional status, medication context such as statins, or mitochondrial/neuromuscular evaluation context.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report provides a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": [
+          "Correct deficiencies first with food sources such as fortified grains, dairy, eggs, fish, legumes, and leafy greens.",
+          "Pair nutrient-dense meals with safe sun exposure for vitamin D when appropriate."
+        ],
+        "exercises": [
+          "Use weight-bearing and muscle-strengthening activity to support bone and metabolic health.",
+          "Adjust activity if deficiency symptoms such as fatigue or neuropathy are present."
+        ],
+        "supplements": [
+          "Supplement only after testing confirms deficiency or insufficiency.",
+          "Use clinician-guided dosing, especially for iron, vitamin A, and fat-soluble vitamins."
+        ]
+      },
+      "statistics_per_group_age": {
+        "child": {
+          "minimal_value": 433,
+          "normal_value": 982.5,
+          "maximum_value": 1532
+        },
+        "teenager": {
+          "minimal_value": 433,
+          "normal_value": 982.5,
+          "maximum_value": 1532
+        },
+        "adult": {
+          "minimal_value": 433,
+          "normal_value": 982.5,
+          "maximum_value": 1532
+        },
+        "elder": {
+          "minimal_value": 433,
+          "normal_value": 982.5,
+          "maximum_value": 1532
+        }
+      },
+      "related_tests": [],
+      "source_ids": [],
+      "video_url": "https://www.youtube.com/watch?v=cy1LhxV6jHs"
+    },
     {
       "id": "complement_c3",
       "display_name": "Complement C3",
@@ -2125,7 +2244,7 @@
       "category": "Cardiac",
       "unit": "U/L",
       "description": "Creatine Kinase measures enzyme from muscle including heart and skeletal.",
-      "why_important": "A high CK may reflect muscle injury from exercise, trauma, statins, or heart muscle damage. A low CK is not typically significant.",
+      "why_important": "A high CK may reflect skeletal muscle injury from exercise, trauma, statins, or neuromuscular disease; it can also rise with heart muscle damage in the right context. A low CK is not typically significant.",
       "sex_significance": {
         "level": "low",
         "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
@@ -3207,6 +3326,62 @@
       "source_ids": [],
       "video_url": "https://www.youtube.com/watch?v=IHaH9mlCdVY"
     },
+    {
+      "id": "free_testosterone",
+      "display_name": "Free Testosterone",
+      "aliases": [
+        "Free T",
+        "Free Testosterone Level"
+      ],
+      "category": "Hormone",
+      "unit": "ng/dL",
+      "description": "Free Testosterone measures unbound testosterone available to tissues.",
+      "why_important": "A high free testosterone may reflect androgen exposure or increased androgen production; interpretation depends strongly on sex, age, symptoms, and SHBG. A low free testosterone may relate to hypogonadism, pituitary signaling, chronic illness, steroid exposure, or high SHBG.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report provides a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": [
+          "Support hormone health with adequate protein, healthy fats, fiber, and micronutrients.",
+          "Avoid extreme dieting or rapid weight changes unless medically supervised."
+        ],
+        "exercises": [
+          "Use resistance training and sleep regularity to support hormonal balance.",
+          "Adjust training load during symptomatic hormone disorders."
+        ],
+        "supplements": [
+          "Avoid unsupervised hormone-boosting products.",
+          "Use prescribed hormone therapies only under endocrine or reproductive specialist guidance."
+        ]
+      },
+      "statistics_per_group_age": {
+        "child": {
+          "minimal_value": 5.25,
+          "normal_value": 12.97,
+          "maximum_value": 20.7
+        },
+        "teenager": {
+          "minimal_value": 5.25,
+          "normal_value": 12.97,
+          "maximum_value": 20.7
+        },
+        "adult": {
+          "minimal_value": 5.25,
+          "normal_value": 12.97,
+          "maximum_value": 20.7
+        },
+        "elder": {
+          "minimal_value": 5.25,
+          "normal_value": 12.97,
+          "maximum_value": 20.7
+        }
+      },
+      "related_tests": [],
+      "source_ids": [],
+      "video_url": "https://www.youtube.com/watch?v=yLuB8X8d_8o"
+    },
     {
       "id": "fructosamine",
       "display_name": "Fructosamine",
@@ -3383,7 +3558,7 @@
       "category": "Liver",
       "unit": "U/L",
       "description": "GGT measures liver enzyme sensitive to bile and alcohol.",
-      "why_important": "GGT is sensitive to bile-duct issues and alcohol; it helps clarify whether a high ALP is from the liver. A low GGT is not a concern.",
+      "why_important": "GGT is sensitive to bile-duct issues and alcohol; it helps clarify whether a high ALP is liver-related, while a normal GGT with high ALP can point more toward bone or skeletal sources. A low GGT is not a concern.",
       "sex_significance": {
         "level": "low",
         "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
@@ -3493,12 +3668,15 @@
         "Blood Sugar",
         "FBS",
         "RBS",
-        "Fasting Blood Sugar"
+        "Fasting Blood Sugar",
+        "Random Glucose",
+        "Non-Fasting Glucose",
+        "Glucose Random Non-Fasting"
       ],
       "category": "Metabolic",
       "unit": "mg/dL",
       "description": "Glucose measures blood sugar level.",
-      "why_important": "An elevated fasting glucose can indicate prediabetes or diabetes, or simply that the sample was not fasting. A low glucose can cause shakiness or lightheadedness and may relate to fasting, medications, or how the sample was handled.",
+      "why_important": "An elevated fasting or random glucose can indicate prediabetes or diabetes, or simply that the sample timing and recent food intake matter. A low glucose can cause shakiness or lightheadedness and may relate to fasting, medications, or how the sample was handled.",
       "sex_significance": {
         "level": "low",
         "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
@@ -3675,7 +3853,8 @@
       "aliases": [
         "A1c",
         "Hemoglobin A1c",
-        "Glycated Hemoglobin"
+        "Glycated Hemoglobin",
+        "HgbA1C"
       ],
       "category": "Metabolic",
       "unit": "%",
@@ -4226,6 +4405,65 @@
       "source_ids": [],
       "video_url": "https://www.youtube.com/watch?v=_LKdNhF2WhI"
     },
+    {
+      "id": "igfbp_3",
+      "display_name": "IGF Binding Protein-3",
+      "aliases": [
+        "IGFBP-3",
+        "IGFBP3",
+        "IGFbp3",
+        "Insulin-Like Growth Factor Binding Protein 3",
+        "Insulin-like Growth Factor-binding Protein 3"
+      ],
+      "category": "Hormone",
+      "unit": "mcg/mL",
+      "description": "IGF Binding Protein-3 measures major carrier protein for IGF-1 and marker of growth-hormone activity.",
+      "why_important": "A high IGFBP-3 can accompany increased growth-hormone activity but must be interpreted with age, puberty stage, IGF-1, and lab method. A low IGFBP-3 may support reduced growth-hormone activity or malnutrition when it matches IGF-1 and growth history.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report provides a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": [
+          "Support hormone health with adequate protein, healthy fats, fiber, and micronutrients.",
+          "Avoid extreme dieting or rapid weight changes unless medically supervised."
+        ],
+        "exercises": [
+          "Use resistance training and sleep regularity to support hormonal balance.",
+          "Adjust training load during symptomatic hormone disorders."
+        ],
+        "supplements": [
+          "Avoid unsupervised hormone-boosting products.",
+          "Use prescribed hormone therapies only under endocrine or reproductive specialist guidance."
+        ]
+      },
+      "statistics_per_group_age": {
+        "child": {
+          "minimal_value": 3.1,
+          "normal_value": 5.5,
+          "maximum_value": 7.9
+        },
+        "teenager": {
+          "minimal_value": 3.1,
+          "normal_value": 5.5,
+          "maximum_value": 7.9
+        },
+        "adult": {
+          "minimal_value": 3.1,
+          "normal_value": 5.5,
+          "maximum_value": 7.9
+        },
+        "elder": {
+          "minimal_value": 3.1,
+          "normal_value": 5.5,
+          "maximum_value": 7.9
+        }
+      },
+      "related_tests": [],
+      "source_ids": [],
+      "video_url": "https://www.youtube.com/watch?v=qV2rkofqK1I"
+    },
     {
       "id": "immunoglobulin_a",
       "display_name": "Immunoglobulin A",
@@ -4505,7 +4743,11 @@
       "id": "insulin",
       "display_name": "Insulin",
       "aliases": [
-        "Fasting Insulin"
+        "Fasting Insulin",
+        "Free Insulin",
+        "Total Insulin",
+        "Insulin Free",
+        "Insulin Total"
       ],
       "category": "Hormone",
       "unit": "uIU/mL",
@@ -5852,7 +6094,8 @@
       "aliases": [
         "Phosphorus",
         "PO4",
-        "Inorganic Phosphate"
+        "Inorganic Phosphate",
+        "Phosphorous"
       ],
       "category": "Metabolic",
       "unit": "mg/dL",
@@ -6367,7 +6610,7 @@
       "category": "Hormone",
       "unit": "pg/mL",
       "description": "Parathyroid Hormone measures hormone that regulates blood calcium.",
-      "why_important": "A high PTH may drive calcium up in primary hyperparathyroidism or rise appropriately when calcium is low. A low PTH may appear after parathyroid surgery or with high calcium from other causes.",
+      "why_important": "A high PTH may drive calcium up in primary hyperparathyroidism or rise appropriately when calcium is low, phosphate is shifted, or vitamin D is low. A low PTH may appear after parathyroid surgery or with high calcium from other causes.",
       "sex_significance": {
         "level": "low",
         "summary": "This marker is usually interpreted with age and lab method rather than sex-specific reference intervals.",
@@ -6420,7 +6663,8 @@
         "RBC",
         "Erythrocyte count",
         "Red cell count",
-        "Erythrocytes"
+        "Erythrocytes",
+        "Total RBC Count"
       ],
       "category": "CBC",
       "unit": "10^6/uL",
@@ -7966,7 +8210,9 @@
       "aliases": [
         "25-OH Vitamin D",
         "25-Hydroxyvitamin D",
-        "Vit D"
+        "Vit D",
+        "25 OH Vit D",
+        "25 Hydroxyvitamin D"
       ],
       "category": "Vitamin",
       "unit": "ng/mL",
@@ -8083,7 +8329,8 @@
         "Leukocytes",
         "WBC Count",
         "TLC",
-        "Total Leucocyte Count"
+        "Total Leucocyte Count",
+        "Total WBC Count"
       ],
       "category": "CBC",
       "unit": "10^3/uL",
@@ -8212,18 +8459,22 @@
     "anti_ccp_antibodies": "Rheumatoid arthritis overview; anti-CCP is correlated through RA evaluation.",
     "anti_mullerian_hormone": "Fertility hormone-testing overview includes AMH and ovarian-reserve timing.",
     "ast": "AST/ALT lab-values video covers AST directly alongside ALT.",
+    "band_neutrophils_percent": "Direct video on segmented versus band neutrophils.",
     "beta_hcg": "Reproductive-cycle overview is a broad pregnancy/reproductive hormone context; beta-hCG is not the primary topic.",
     "beta_hydroxybutyrate": "Diabetes/DKA overview covers ketone production; beta-hydroxybutyrate is not the only focus.",
     "ca_125": "Tumor-marker overview covers CA-125 with other markers.",
     "ca_15_3": "Direct CA 15-3 blood-test video; marker is for monitoring context rather than diagnosis.",
     "cea": "Tumor-marker overview covers CEA with other markers.",
     "ceruloplasmin": "Trace-mineral/copper overview; ceruloplasmin is linked to copper interpretation.",
+    "coenzyme_q10": "CoQ10 overview; closest available educational video for the CoQ10 marker rather than a lab-result-only lecture.",
     "copper": "Trace-mineral lab overview covering copper among other minerals.",
     "free_t3": "Free T3/Free T4 video focuses on free thyroid hormones together.",
+    "free_testosterone": "Direct free-versus-total testosterone video; marker interpretation still depends on sex, age, SHBG, and symptoms.",
     "fructosamine": "Diabetes overview; fructosamine is a shorter-term glycemic marker and is not the primary topic.",
     "gra_absolute": "WBC differential overview; granulocyte absolute combines neutrophils, eosinophils, and basophils.",
     "hct": "Hemoglobin/Hematocrit lab-values video covers hematocrit directly alongside hemoglobin.",
     "hdl_cholesterol": "HDL/LDL cholesterol video focuses on HDL in direct lipid-marker context.",
+    "igfbp_3": "Direct IGFBP-3 blood-test video.",
     "immunoglobulin_m": "IgG/IgM antibody-testing video covers IgM directly alongside IgG.",
     "mcv": "Anemia interpretation video uses MCV directly; also discusses MCH context.",
     "mpv": "FBC/CBC guide covers platelets; MPV is not discussed in detail.",

kb/knowledge_base.py

@@ -110,6 +110,11 @@ KB: dict[str, MarkerKB] = {
         low="A low basophil count is usually not significant.",
         questions=("Is this a persistent finding worth rechecking?",),
     ),
+    "Band Neutrophils Percent": MarkerKB(
+        high="A high band neutrophil percentage may suggest a left shift, often seen when the marrow is releasing immature neutrophils during infection, inflammation, or physiologic stress.",
+        low="A low band neutrophil percentage is usually expected and not clinically significant on its own.",
+        questions=("Does this fit with my total WBC and absolute neutrophil count?",),
+    ),
     "Reticulocyte Count": MarkerKB(
         high="A high reticulocyte count means the marrow is making extra red cells, often after blood loss or hemolysis.",
         low="A low reticulocyte count in anemia suggests the marrow is not keeping up with red-cell need.",
@@ -132,7 +137,7 @@ KB: dict[str, MarkerKB] = {
     ),
     # --- Metabolic panel ---
     "Glucose": MarkerKB(
-        high="An elevated fasting glucose can indicate prediabetes or diabetes, or simply that the sample was not fasting.",
+        high="An elevated fasting or random glucose can indicate prediabetes or diabetes, or simply that the sample timing and recent food intake matter.",
         low="A low glucose can cause shakiness or lightheadedness and may relate to fasting, medications, or how the sample was handled.",
         questions=("Was this a fasting sample?", "Should we confirm with an HbA1c?"),
     ),
@@ -187,8 +192,8 @@ KB: dict[str, MarkerKB] = {
         questions=("Does the albumin/globulin ratio need follow-up?",),
     ),
     "Bicarbonate": MarkerKB(
-        high="A high bicarbonate may reflect metabolic alkalosis or compensation for lung issues.",
-        low="A low bicarbonate may reflect metabolic acidosis or severe diarrhea.",
+        high="A high bicarbonate or total CO2 may reflect metabolic alkalosis or compensation for lung/respiratory issues.",
+        low="A low bicarbonate or total CO2 may reflect metabolic acidosis, severe diarrhea, or other acid-base stress.",
         questions=("Does this fit with my other electrolytes and symptoms?",),
     ),
     "Anion Gap": MarkerKB(
@@ -204,7 +209,7 @@ KB: dict[str, MarkerKB] = {
     "Phosphate": MarkerKB(
         high="A high phosphate may relate to kidney disease, low parathyroid activity, or cell breakdown.",
         low="A low phosphate may relate to malnutrition, alcohol, or overcorrection of vitamin D.",
-        questions=("Does this fit with my calcium and kidney results?",),
+        questions=("Does this fit with my calcium, PTH, vitamin D, and kidney results?",),
     ),
     "Uric Acid": MarkerKB(
         high="A high uric acid is associated with gout and kidney stones and may rise with diet, alcohol, or kidney disease.",
@@ -293,22 +298,22 @@ KB: dict[str, MarkerKB] = {
     ),
     # --- Liver enzymes ---
     "ALT": MarkerKB(
-        high="ALT is fairly liver-specific; elevations can follow fatty liver, alcohol, medications, or viral hepatitis.",
+        high="ALT is usually interpreted as a liver enzyme, but it can also rise with skeletal muscle injury; fatty liver, alcohol, medications, viral hepatitis, CK, AST, and GGT help provide context.",
         low="A low ALT is not typically a concern.",
         questions=("Could a medication or fatty liver explain this?", "Should we recheck in a few weeks?"),
     ),
     "AST": MarkerKB(
-        high="AST rises with liver stress but also comes from muscle; the AST/ALT pattern helps point to a cause.",
+        high="AST rises with liver stress but also comes from skeletal muscle; CK and GGT can help separate muscle from liver or bile-duct patterns.",
         low="A low AST is not typically a concern.",
         questions=("Does the AST/ALT ratio suggest a specific cause?",),
     ),
     "ALP": MarkerKB(
         high="A high alkaline phosphatase can come from the liver/bile ducts or from bone; growth and pregnancy also raise it.",
         low="A low ALP is uncommon and rarely significant.",
-        questions=("Is this from my liver or my bones?",),
+        questions=("Is this from my liver or my bones, and does GGT help clarify it?",),
     ),
     "GGT": MarkerKB(
-        high="GGT is sensitive to bile-duct issues and alcohol; it helps clarify whether a high ALP is from the liver.",
+        high="GGT is sensitive to bile-duct issues and alcohol; it helps clarify whether a high ALP is liver-related, while a normal GGT with high ALP can point more toward bone or skeletal sources.",
         low="A low GGT is not a concern.",
         questions=("Does my GGT help explain my ALP?",),
     ),
@@ -455,6 +460,11 @@ KB: dict[str, MarkerKB] = {
         low="A low vitamin E level may occur with fat malabsorption and can affect nerves and red cells.",
         questions=("Could fat absorption or supplements explain this?",),
     ),
+    "Coenzyme Q10": MarkerKB(
+        high="A high CoQ10 level is most often supplement-related and may also track with lipoprotein levels.",
+        low="A low CoQ10 level may reflect nutritional status, medication context such as statins, or mitochondrial/neuromuscular evaluation context.",
+        questions=("Am I taking CoQ10 or statin therapy?", "Is this being monitored for a mitochondrial or neuromuscular reason?"),
+    ),
     "HbA1c": MarkerKB(
         high="A high HbA1c reflects higher average blood sugar over ~3 months and is used to screen for prediabetes and diabetes.",
         low="A low HbA1c is generally not a concern.",
@@ -564,9 +574,9 @@ KB: dict[str, MarkerKB] = {
         questions=("Was chest pain or pressure present when this was drawn?",),
     ),
     "Creatine Kinase": MarkerKB(
-        high="A high CK may reflect muscle injury from exercise, trauma, statins, or heart muscle damage.",
+        high="A high CK may reflect skeletal muscle injury from exercise, trauma, statins, or neuromuscular disease; it can also rise with heart muscle damage in the right context.",
         low="A low CK is not typically significant.",
-        questions=("Did I exercise heavily before the blood draw?", "Am I on a statin?"),
+        questions=("Did I exercise heavily before the blood draw?", "Am I on a statin?", "Is there known muscle disease or weakness?"),
     ),
     "CK-MB": MarkerKB(
         high="A high CK-MB raises concern for heart-muscle injury when troponin is also elevated.",
@@ -594,6 +604,11 @@ KB: dict[str, MarkerKB] = {
         low="A low testosterone may cause fatigue, low libido, or muscle loss in men.",
         questions=("Could symptoms match my testosterone level?",),
     ),
+    "Free Testosterone": MarkerKB(
+        high="A high free testosterone may reflect androgen exposure or increased androgen production; interpretation depends strongly on sex, age, symptoms, and SHBG.",
+        low="A low free testosterone may relate to hypogonadism, pituitary signaling, chronic illness, steroid exposure, or high SHBG.",
+        questions=("How does this compare with total testosterone, SHBG, LH, and FSH?",),
+    ),
     "Estradiol": MarkerKB(
         high="A high estradiol may relate to ovarian function, obesity, or hormone therapy.",
         low="A low estradiol may relate to menopause, ovarian failure, or low body weight.",
@@ -620,7 +635,7 @@ KB: dict[str, MarkerKB] = {
         questions=("What day of my cycle was this drawn?",),
     ),
     "Parathyroid Hormone": MarkerKB(
-        high="A high PTH may drive calcium up in primary hyperparathyroidism or rise appropriately when calcium is low.",
+        high="A high PTH may drive calcium up in primary hyperparathyroidism or rise appropriately when calcium is low, phosphate is shifted, or vitamin D is low.",
         low="A low PTH may appear after parathyroid surgery or with high calcium from other causes.",
         questions=("How does PTH fit with my calcium and vitamin D?",),
     ),
@@ -659,6 +674,11 @@ KB: dict[str, MarkerKB] = {
         low="A low IGF-1 may reflect growth-hormone deficiency or malnutrition.",
         questions=("Are height, hands, or jaw changes relevant?",),
     ),
+    "IGF Binding Protein-3": MarkerKB(
+        high="A high IGFBP-3 can accompany increased growth-hormone activity but must be interpreted with age, puberty stage, IGF-1, and lab method.",
+        low="A low IGFBP-3 may support reduced growth-hormone activity or malnutrition when it matches IGF-1 and growth history.",
+        questions=("Does this match IGF-1 and growth-pattern concerns?",),
+    ),
     # --- Oncology / screening ---
     "PSA": MarkerKB(
         high="A high PSA may come from prostate enlargement, infection, recent procedures, or less commonly cancer.",

kb/marker_videos.json

@@ -18,6 +18,7 @@
     "apolipoprotein_b": "https://www.youtube.com/watch?v=V7ywq_s7ATk",
     "aptt": "https://www.youtube.com/watch?v=uiFicYWMZL0",
     "ast": "https://www.youtube.com/watch?v=7_-ZtM0TieA",
+    "band_neutrophils_percent": "https://www.youtube.com/watch?v=AvVnjqShhWE",
     "bas_absolute": "https://www.youtube.com/watch?v=sRIjKEkjWmU",
     "bas_percent": "https://www.youtube.com/watch?v=VUAVvLkcN0M",
     "beta_2_microglobulin": "https://www.youtube.com/watch?v=i2-_4wk30po",
@@ -35,6 +36,7 @@
     "ceruloplasmin": "https://www.youtube.com/watch?v=42kduAhoYlw",
     "chloride": "https://www.youtube.com/watch?v=5Fuav99clbE",
     "ck_mb": "https://www.youtube.com/watch?v=udVccTOnmrM",
+    "coenzyme_q10": "https://www.youtube.com/watch?v=cy1LhxV6jHs",
     "complement_c3": "https://www.youtube.com/watch?v=r_f5cvxwS6w",
     "complement_c4": "https://www.youtube.com/watch?v=r_f5cvxwS6w",
     "copper": "https://www.youtube.com/watch?v=42kduAhoYlw",
@@ -57,6 +59,7 @@
     "folate": "https://www.youtube.com/watch?v=dO0aUSqZ_bs",
     "free_t3": "https://www.youtube.com/watch?v=oz8HFUqwDgw",
     "free_t4": "https://www.youtube.com/watch?v=IHaH9mlCdVY",
+    "free_testosterone": "https://www.youtube.com/watch?v=yLuB8X8d_8o",
     "fructosamine": "https://www.youtube.com/watch?v=tXW-qGeTNFk",
     "fsh": "https://www.youtube.com/watch?v=UL0PFu5fPKA",
     "g6pd": "https://www.youtube.com/watch?v=iTh-hUU5mxE",
@@ -72,6 +75,7 @@
     "homocysteine": "https://www.youtube.com/watch?v=XbX9K1OtFFs",
     "hs_crp": "https://www.youtube.com/watch?v=eRNFtwzyyCo",
     "igf_1": "https://www.youtube.com/watch?v=_LKdNhF2WhI",
+    "igfbp_3": "https://www.youtube.com/watch?v=qV2rkofqK1I",
     "immunoglobulin_a": "https://www.youtube.com/watch?v=pkn3qA7s-NI",
     "immunoglobulin_e": "https://www.youtube.com/watch?v=z95-fg7bzLA",
     "immunoglobulin_g": "https://www.youtube.com/watch?v=d_3VZ5vDiHI",
@@ -147,18 +151,22 @@
     "anti_ccp_antibodies": "Rheumatoid arthritis overview; anti-CCP is correlated through RA evaluation.",
     "anti_mullerian_hormone": "Fertility hormone-testing overview includes AMH and ovarian-reserve timing.",
     "ast": "AST/ALT lab-values video covers AST directly alongside ALT.",
+    "band_neutrophils_percent": "Direct video on segmented versus band neutrophils.",
     "beta_hcg": "Reproductive-cycle overview is a broad pregnancy/reproductive hormone context; beta-hCG is not the primary topic.",
     "beta_hydroxybutyrate": "Diabetes/DKA overview covers ketone production; beta-hydroxybutyrate is not the only focus.",
     "ca_125": "Tumor-marker overview covers CA-125 with other markers.",
     "ca_15_3": "Direct CA 15-3 blood-test video; marker is for monitoring context rather than diagnosis.",
     "cea": "Tumor-marker overview covers CEA with other markers.",
     "ceruloplasmin": "Trace-mineral/copper overview; ceruloplasmin is linked to copper interpretation.",
+    "coenzyme_q10": "CoQ10 overview; closest available educational video for the CoQ10 marker rather than a lab-result-only lecture.",
     "copper": "Trace-mineral lab overview covering copper among other minerals.",
     "free_t3": "Free T3/Free T4 video focuses on free thyroid hormones together.",
+    "free_testosterone": "Direct free-versus-total testosterone video; marker interpretation still depends on sex, age, SHBG, and symptoms.",
     "fructosamine": "Diabetes overview; fructosamine is a shorter-term glycemic marker and is not the primary topic.",
     "gra_absolute": "WBC differential overview; granulocyte absolute combines neutrophils, eosinophils, and basophils.",
     "hct": "Hemoglobin/Hematocrit lab-values video covers hematocrit directly alongside hemoglobin.",
     "hdl_cholesterol": "HDL/LDL cholesterol video focuses on HDL in direct lipid-marker context.",
+    "igfbp_3": "Direct IGFBP-3 blood-test video.",
     "immunoglobulin_m": "IgG/IgM antibody-testing video covers IgM directly alongside IgG.",
     "mcv": "Anemia interpretation video uses MCV directly; also discusses MCH context.",
     "mpv": "FBC/CBC guide covers platelets; MPV is not discussed in detail.",

scripts/expand_lab_knowledge_graph.py

@@ -29,6 +29,7 @@ MARKER_IDS: dict[str, str] = {
     "Absolute Monocyte Count": "mon_absolute",
     "Absolute Eosinophil Count": "eos_absolute",
     "Absolute Basophil Count": "bas_absolute",
+    "Band Neutrophils Percent": "band_neutrophils_percent",
     "Reticulocyte Count": "reticulocyte_count",
     "Haptoglobin": "haptoglobin",
     "G6PD": "g6pd",
@@ -98,6 +99,7 @@ MARKER_IDS: dict[str, str] = {
     "Ceruloplasmin": "ceruloplasmin",
     "Selenium": "selenium",
     "Vitamin E": "vitamin_e",
+    "Coenzyme Q10": "coenzyme_q10",
     "Prothrombin Time": "prothrombin_time",
     "INR": "inr",
     "aPTT": "aptt",
@@ -124,6 +126,7 @@ MARKER_IDS: dict[str, str] = {
     "Cortisol": "cortisol",
     "Insulin": "insulin",
     "Testosterone": "testosterone",
+    "Free Testosterone": "free_testosterone",
     "Estradiol": "estradiol",
     "Prolactin": "prolactin",
     "FSH": "fsh",
@@ -137,6 +140,7 @@ MARKER_IDS: dict[str, str] = {
     "Beta-hCG": "beta_hcg",
     "SHBG": "shbg",
     "IGF-1": "igf_1",
+    "IGF Binding Protein-3": "igfbp_3",
     "PSA": "psa",
     "CEA": "cea",
     "CA-125": "ca_125",
@@ -153,11 +157,12 @@ EXTRA_ALIAS_UPDATES: dict[str, list[str]] = {
     "mon_absolute": ["AMC", "Absolute Monocyte Count", "Abs Monocytes", "Monocytes Absolute"],
     "eos_absolute": ["AEC", "Absolute Eosinophil Count", "Abs Eosinophils", "Eosinophils Absolute"],
     "bas_absolute": ["ABC", "Absolute Basophil Count", "Abs Basophils", "Basophils Absolute"],
+    "band_neutrophils_percent": ["Band Neutrophil %", "Band Neutrophils", "Band %", "Bands", "Stab Neutrophils"],
     "mpv": ["Mean Platelet Volume"],
     "reticulocyte_count": ["Retic Count", "Retics"],
     "bun": ["BUN", "Urea Nitrogen", "Blood Urea Nitrogen"],
     "egfr": ["GFR", "Estimated GFR"],
-    "hba1c": ["A1c", "Hemoglobin A1c", "Glycated Hemoglobin"],
+    "hba1c": ["A1c", "HgbA1C", "Hemoglobin A1c", "Hemoglobin A1C", "Glycated Hemoglobin"],
     "aptt": ["PTT", "APTT", "Activated Partial Thromboplastin Time"],
     "pth": ["PTH", "Intact PTH", "Parathyroid Hormone"],
     "hs_crp": ["High-Sensitivity CRP", "High Sensitivity C-Reactive Protein"],

src/markers.py

@@ -55,9 +55,9 @@ MARKERS: tuple[Marker, ...] = (
     # --- Complete blood count ---
     Marker("Hemoglobin", "g/dL", 11.9, 17.7, "CBC", "oxygen-carrying protein in red blood cells", ("Hgb", "HGB", "Hb")),
     Marker("Hematocrit", "%", 35, 52, "CBC", "fraction of blood made up of red cells", ("Hct", "HCT", "PCV")),
-    Marker("White Blood Cell Count", "10^3/uL", 3.7, 10.5, "CBC", "immune cells that fight infection", ("WBC", "Leukocytes", "WBC Count", "TLC", "Total Leucocyte Count")),
+    Marker("White Blood Cell Count", "10^3/uL", 3.7, 10.5, "CBC", "immune cells that fight infection", ("WBC", "Leukocytes", "WBC Count", "Total WBC Count", "TLC", "Total Leucocyte Count")),
     Marker("Platelet Count", "10^3/uL", 150, 400, "CBC", "cell fragments that help blood clot", ("Platelets", "PLT")),
-    Marker("Red Blood Cell Count", "10^6/uL", 4.0, 6.2, "CBC", "number of oxygen-carrying red cells", ("RBC", "Erythrocytes")),
+    Marker("Red Blood Cell Count", "10^6/uL", 4.0, 6.2, "CBC", "number of oxygen-carrying red cells", ("RBC", "Total RBC Count", "Erythrocytes")),
     Marker("MCV", "fL", 82, 99, "CBC", "average size of red blood cells", ("Mean Corpuscular Volume",)),
     Marker("MCH", "pg", 25, 35, "CBC", "average hemoglobin per red blood cell", ("Mean Corpuscular Hemoglobin",)),
     Marker("MCHC", "g/dL", 32, 36, "CBC", "average hemoglobin concentration in red cells", ("Mean Corpuscular Hemoglobin Concentration",)),
@@ -68,12 +68,13 @@ MARKERS: tuple[Marker, ...] = (
     Marker("Absolute Monocyte Count", "10^3/uL", 0.2, 0.8, "CBC", "count of cleanup and immune white cells", ("AMC", "Monocytes Absolute", "Abs Monocytes")),
     Marker("Absolute Eosinophil Count", "10^3/uL", 0, 0.5, "CBC", "count of allergy and parasite-related white cells", ("AEC", "Eosinophils Absolute", "Abs Eosinophils")),
     Marker("Absolute Basophil Count", "10^3/uL", 0, 0.2, "CBC", "count of histamine-related white cells", ("ABC", "Basophils Absolute", "Abs Basophils")),
+    Marker("Band Neutrophils Percent", "%", 0, 6, "CBC", "percentage of immature neutrophils in the white-cell differential", ("Band Neutrophil %", "Band Neutrophils", "Band %", "Bands", "Stab Neutrophils")),
     Marker("Reticulocyte Count", "%", 0.5, 2.5, "CBC", "young red cells recently released from bone marrow", ("Retic Count", "Retics")),
     Marker("Haptoglobin", "mg/dL", 30, 200, "CBC", "protein that binds free hemoglobin after red-cell breakdown", ("HP",)),
     Marker("G6PD", "U/g Hb", 5.5, 20.5, "CBC", "red-cell enzyme that protects against oxidative stress", ("Glucose-6-Phosphate Dehydrogenase", "G6PDH")),
     Marker("Erythropoietin", "mIU/mL", 4, 27, "CBC", "kidney hormone that stimulates red-cell production", ("EPO",)),
     # --- Metabolic panel ---
-    Marker("Glucose", "mg/dL", 70, 99, "Metabolic", "blood sugar level", ("Fasting Glucose", "GLU", "Blood Sugar", "FBS", "RBS", "Fasting Blood Sugar")),
+    Marker("Glucose", "mg/dL", 70, 99, "Metabolic", "blood sugar level", ("Fasting Glucose", "Random Glucose", "Non-Fasting Glucose", "Glucose Random Non-Fasting", "GLU", "Blood Sugar", "FBS", "RBS", "Fasting Blood Sugar")),
     Marker("Creatinine", "mg/dL", 0.7, 1.3, "Metabolic", "kidney-function waste product", ("Cr", "Serum Creatinine")),
     Marker("eGFR", "mL/min/1.73m2", 90, None, "Metabolic", "estimated kidney filtration rate", ("GFR", "Estimated GFR")),
     Marker("Blood Urea Nitrogen", "mg/dL", 7, 20, "Metabolic", "kidney-function waste product", ("BUN", "Urea Nitrogen")),
@@ -87,7 +88,7 @@ MARKERS: tuple[Marker, ...] = (
     Marker("Bicarbonate", "mmol/L", 22, 28, "Metabolic", "main blood buffer for acid-base balance", ("CO2", "Bicarb", "Total CO2", "Carbon Dioxide")),
     Marker("Anion Gap", "mEq/L", 7, 13, "Metabolic", "calculated gap from electrolytes suggesting acid-base issues", ("AG",)),
     Marker("Magnesium", "mg/dL", 1.7, 2.2, "Metabolic", "electrolyte for nerves, muscle, and heart rhythm", ("Mg", "Mg++")),
-    Marker("Phosphate", "mg/dL", 2.5, 4.5, "Metabolic", "mineral for bones, energy, and cell membranes", ("Phosphorus", "PO4", "Inorganic Phosphate")),
+    Marker("Phosphate", "mg/dL", 2.5, 4.5, "Metabolic", "mineral for bones, energy, and cell membranes", ("Phosphorus", "Phosphorous", "PO4", "Inorganic Phosphate")),
     Marker("Uric Acid", "mg/dL", 3.5, 7.2, "Metabolic", "breakdown product of purines; linked to gout", ("UA", "Urate")),
     Marker("Serum Iron", "mcg/dL", 60, 170, "Metabolic", "circulating iron available for red-cell production", ("Iron", "Fe", "Iron, Serum")),
     Marker("TIBC", "mcg/dL", 250, 450, "Metabolic", "blood's capacity to bind and transport iron", ("Total Iron Binding Capacity", "Iron Binding Capacity")),
@@ -133,7 +134,7 @@ MARKERS: tuple[Marker, ...] = (
     Marker("TSH Receptor Antibodies", "IU/L", None, 1.75, "Thyroid", "antibodies that can stimulate or block the TSH receptor", ("TRAb", "TSH-R Ab")),
     Marker("Thyroglobulin Antibodies", "IU/mL", None, 4, "Thyroid", "antibodies against thyroglobulin", ("TgAb", "Anti-Thyroglobulin Antibodies")),
     # --- Vitamins / iron ---
-    Marker("Vitamin D", "ng/mL", 30, 100, "Vitamin", "vitamin for bone and immune health", ("25-OH Vitamin D", "25-Hydroxyvitamin D", "Vit D")),
+    Marker("Vitamin D", "ng/mL", 30, 100, "Vitamin", "vitamin for bone and immune health", ("25-OH Vitamin D", "25-Hydroxyvitamin D", "25 OH Vit D", "25 Hydroxyvitamin D", "Vit D")),
     Marker("Vitamin B12", "pg/mL", 200, 900, "Vitamin", "vitamin for nerves and red-cell production", ("B12", "Cobalamin")),
     Marker("Ferritin", "ng/mL", 30, 400, "Vitamin", "stored-iron protein", ("FERR",)),
     Marker("Zinc", "mcg/dL", 60, 130, "Vitamin", "trace mineral involved in immunity and wound healing", ("Zn",)),
@@ -141,7 +142,8 @@ MARKERS: tuple[Marker, ...] = (
     Marker("Ceruloplasmin", "mg/dL", 20, 35, "Vitamin", "copper-carrying protein made by the liver", ("CP",)),
     Marker("Selenium", "mcg/L", 70, 150, "Vitamin", "trace mineral used in antioxidant and thyroid-related enzymes", ("Se",)),
     Marker("Vitamin E", "mg/L", 5.5, 17, "Vitamin", "fat-soluble antioxidant vitamin", ("Alpha-Tocopherol", "Tocopherol")),
-    Marker("HbA1c", "%", 4.0, 5.6, "Metabolic", "average blood sugar over ~3 months", ("A1c", "Hemoglobin A1c", "Glycated Hemoglobin")),
+    Marker("Coenzyme Q10", "mcg/L", 433, 1532, "Vitamin", "mitochondrial electron-transport cofactor and antioxidant", ("CoQ10", "Coenzyme Q 10", "Total Coenzyme Q10", "Total Coenzyme Q 10", "CoQ10 Profile", "Total CoQ10")),
+    Marker("HbA1c", "%", 4.0, 5.6, "Metabolic", "average blood sugar over ~3 months", ("A1c", "HgbA1C", "Hemoglobin A1c", "Hemoglobin A1C", "Glycated Hemoglobin")),
     # --- Coagulation ---
     Marker("Prothrombin Time", "seconds", 11, 13.5, "Coagulation", "time for the clotting cascade to form fibrin", ("PT",)),
     Marker("INR", "ratio", 0.9, 1.1, "Coagulation", "standardized prothrombin time for warfarin monitoring", ("International Normalized Ratio",)),
@@ -170,8 +172,9 @@ MARKERS: tuple[Marker, ...] = (
     Marker("Myoglobin", "ng/mL", 25, 72, "Cardiac", "oxygen-binding muscle protein released with muscle injury", ("Mb",)),
     # --- Hormones ---
     Marker("Cortisol", "mcg/dL", 6, 18, "Hormone", "stress hormone from the adrenal glands", ("AM Cortisol", "Serum Cortisol")),
-    Marker("Insulin", "uIU/mL", 2.6, 24.9, "Hormone", "hormone that lowers blood sugar", ("Fasting Insulin",)),
+    Marker("Insulin", "uIU/mL", 2.6, 24.9, "Hormone", "hormone that lowers blood sugar", ("Fasting Insulin", "Free Insulin", "Total Insulin", "Insulin Free", "Insulin Total")),
     Marker("Testosterone", "ng/dL", 300, 1000, "Hormone", "androgen sex hormone", ("Total Testosterone",)),
+    Marker("Free Testosterone", "ng/dL", 5.25, 20.7, "Hormone", "unbound testosterone available to tissues", ("Free T", "Free Testosterone Level")),
     Marker("Estradiol", "pg/mL", 15, 350, "Hormone", "primary estrogen sex hormone", ("E2", "Estrogen")),
     Marker("Prolactin", "ng/mL", None, 20, "Hormone", "pituitary hormone for lactation and more", ("PRL",)),
     Marker("FSH", "mIU/mL", 1.5, 12.4, "Hormone", "pituitary signal for egg and sperm production", ("Follicle Stimulating Hormone",)),
@@ -185,6 +188,7 @@ MARKERS: tuple[Marker, ...] = (
     Marker("Beta-hCG", "mIU/mL", None, 5, "Hormone", "pregnancy-associated hormone also used in some tumor monitoring", ("β-hCG", "Human Chorionic Gonadotropin", "hCG")),
     Marker("SHBG", "nmol/L", 10, 80, "Hormone", "protein that binds sex hormones in the blood", ("Sex Hormone Binding Globulin",)),
     Marker("IGF-1", "ng/mL", 115, 355, "Hormone", "growth factor reflecting growth-hormone activity", ("Insulin-Like Growth Factor 1", "Somatomedin C")),
+    Marker("IGF Binding Protein-3", "mcg/mL", 3.1, 7.9, "Hormone", "major carrier protein for IGF-1 and marker of growth-hormone activity", ("IGFBP-3", "IGFBP3", "IGFbp3", "Insulin-Like Growth Factor Binding Protein 3", "Insulin-like Growth Factor-binding Protein 3")),
     # --- Oncology / screening ---
     Marker("PSA", "ng/mL", None, 4.0, "Oncology", "prostate-specific protein used in screening", ("Prostate Specific Antigen",)),
     Marker("CEA", "ng/mL", None, 3.0, "Oncology", "tumor marker often followed in colorectal and other cancers", ("Carcinoembryonic Antigen",)),