Hormonal Health Research Assistant

An evidence-aware, multi-agent endocrine reasoning system that separates scientific literature from patient-specific biology using causal graph projection.

Comment

Inspiration

Endocrine and metabolic disorders—such as PCOS and adrenal dysfunction—present complex, overlapping symptom profiles and conflicting lab patterns. Existing AI tools often fall into two traps: generic LLMs produce authoritative-sounding hallucinated diagnoses, while classic Retrieval-Augmented Generation (RAG) systems dump overwhelming, contextually irrelevant literature hubs (e.g., forcing "obesity" or "male reproductive pathways" into a young, lean female patient's analysis).

We were inspired to build a system that acts as an evidence-aware reasoning assistant, not an AI doctor. Our goal was to bridge the gap between vast PubMed literature and individual patient context using structured, uncertainty-aware multi-agent workflows.

How We Built It

Our system separates global scientific knowledge from patient-specific interpretation using a 15-agent orchestration framework and a graph-based reasoning pipeline:

  1. Deterministic Intake & Biomarker Analysis: Extracts structured values (age, menstrual cycle day, numerical and qualitative biomarkers, symptoms) into validated Pydantic schemas.
  2. Scientific Retrieval & Knowledge Extraction: Retrieves PubMed/Semantic Scholar studies and extracts claims into structured entities, mechanisms, evidence directions, and confidence scores.
  3. Persistent Evidence Graph: Stores paper-supported relationships in a SQLite database, accumulating citation support, study quality, and recency over time.
  4. Patient-Specific Graph Projection & Biological Relevance Scoring: Generates a dynamic, temporary projection for the current query. Pathways are scored by biomarker proximity, evidence strength, and context fit.
    • Strict Pruning (drop state): Unconfirmed modifier conditions (e.g., obesity) or sex-incompatible pathways are algorithmically suppressed from the patient view, keeping the visual UI clean and biologically precise.
  5. Mechanistic Explanation & Safety Layer: Produces free-form Markdown explanations highlighting plausible mechanisms (e.g., adrenal $DHEA\text{-}S$ overproduction vs. ovarian hyperandrogenism), uncertainties, and high-yield missing tests (e.g., $17\text{-OHP}$). A final Safety Agent enforces non-diagnostic, uncertainty-aware boundaries.

Challenges We Faced

  • The "General Literature Hub" Noise: Literature graphs are naturally dominated by high-degree nodes like Obesity or Insulin Resistance. In isolated adrenal androgen excess, these nodes pollute the user's graph view. We solved this by developing a deterministic Biological Relevance Scoring engine that enforces a strict drop state for contextually unsupported nodes.
  • JSON Parsing Bottlenecks with Complex Schemas: Enforcing complex JSON schemas across multiple agents frequently triggered validation errors due to markdown wrapping or LLM Unicode glitches. We migrated our final user-facing agent to native Markdown and implemented Python-level JSON repair logic (extract_and_clean_json) using Pydantic validation boundaries.
  • State Persistence Across UI Views: Ensuring smooth navigation between the Chat view and Knowledge Graph view without duplicating historical error logs required implementing state filtering for API retry errors.

What We Learned

  • Uncertainty is a Feature, Not a Bug: In clinical reasoning, knowing what is missing (e.g., unmeasured $17\text{-OHP}$ or cortisol rhythms) is as critical as analyzing measured labs.
  • Graph Projection > Naive RAG: Filtering global scientific graphs through patient-specific constraints delivers far higher clinical clarity than dumping top vector search results.
  • Agent Architecture Design: Separating structured internal JSON data contracts from unstructured Markdown end-user explanations significantly improves system reliability and reduces execution failures.

OpenAI Codex & GPT-5.6 Usage

OpenAI’s cutting-edge developer tools were foundational to our engineering workflow:

  • OpenAI Codex: Acted as our primary pair programmer. Codex accelerated backend development by generating complex Pydantic data contracts (LabAnalysisRequest, PatientProjection), writing deterministic graph-pruning algorithms in Python, handling state persistence, and refactoring API error-handling logic.
  • GPT-5.6: Served as our architectural reasoning partner and debugging engine. GPT-5.6 helped us evaluate multi-agent trade-offs, analyze multi-agent execution traces, resolve complex Pydantic validation failures, and optimize system prompts for non-diagnostic, uncertainty-aware clinical safety.

Built With

Share this project:

Updates