Biomarker Analysis

Biomarker Analysis Pipeline (RALF)

Ralph-Inspired Adaptive Learning Framework for iterative, quality-gated biomarker report analysis.

Overview

This skill runs comprehensive biomarker analysis using the RALF architecture:

• Iterative Processing: Each category processed independently with fresh context
• KB Enrichment: Per-category VectorShift KB queries inform analysis
• Dual Validation Gates: Structural completeness + clinical accuracy
• Retry with Feedback: Failed validations trigger specific revision prompts
• State Persistence: Resume from any point, track learnings

Usage

Basic Analysis

# Run from Python
from lib.biomarker_analysis.execution import run_analysis

biomarkers = [
    {"name": "A1c", "value": "5.8", "unit": "%", "ref_range": "<5.7"},
    {"name": "Fasting Glucose", "value": "98", "unit": "mg/dL", "ref_range": "70-99"},
    # ... more biomarkers
]

prd = run_analysis(
    biomarkers=biomarkers,
    user_preference_level=3,  # 1-5 scale
    patient_goals="Optimize metabolic health and longevity",
)

Resume Interrupted Analysis

from lib.biomarker_analysis.execution import resume_analysis

prd = resume_analysis(output_dir=".biomarker-analysis")

Generate Visual Report

from lib.biomarker_analysis.synthesis import synthesize_report
from lib.biomarker_analysis.visual import generate_visual_report
from lib.biomarker_analysis.state import StateManager

state = StateManager()
synthesis = synthesize_report(state)
html = generate_visual_report(synthesis)

Architecture

PHASE 1: INITIALIZATION
├── Parse biomarkers from lab report
├── Categorize into 5 core categories + dynamic modules
└── Generate PRD with segment definitions

PHASE 2: ITERATIVE ANALYSIS (per category)
├── Query VectorShift KB for research context
├── Generate category analysis (Claude Haiku 4.5)
├── Validate with dual gates
├── Retry with feedback if failed (max 2 retries)
└── Mark complete or blocked

PHASE 3: SYNTHESIS
├── Generate Goal Summary + Findings Summary
├── Merge all category analyses
├── Prioritize interventions
└── Generate visual HTML report

Categories

Core Categories (Always Present)

1. GENERAL HEALTH: CBC, CMP, liver/kidney function
2. METABOLIC FUNCTION: A1c, glucose, insulin, ApoB, triglycerides
3. INFLAMMATION: hs-CRP, homocysteine, GGT
4. HORMONES: Testosterone, thyroid, estrogen, AMH
5. NUTRIENTS: Vitamin D, ferritin, B12, magnesium

Dynamic Modules (Auto-detected)

• Organic acids
• Microbiome
• Genetics/Epigenetics
• Advanced lipid panels
• Urine/salivary hormones

User Preference Levels

Clinical Conventions

The pipeline enforces these clinic-specific conventions:

• Free Testosterone: Always labeled "suboptimal" per clinic protocol
• GLP-1 RAs: When recommending, add creatine monohydrate 5g daily
• NAD+: Consider 1000mg oral daily if A1c >5.4 AND CRP <1
• Vitamin D: Target 60-80 ng/mL (optimal longevity range)
• Lab Values: Report EXACTLY as provided (no rounding)

Output Files

State is persisted in .biomarker-analysis/:

.biomarker-analysis/
├── prd.json              # Segment definitions + status
├── progress.txt          # Iteration logs
├── context/              # Per-category KB research
├── outputs/              # Per-category analysis JSON
└── final/
    ├── synthesis.json    # Merged synthesis data
    ├── report.html       # Visual HTML report
    └── report.md         # Markdown report

Validation Gates

Gate 1: Structural Completeness

• Status paragraph ≥100 words
• Root causes paragraph ≥100 words
• Interventions paragraph ≥100 words
• All biomarkers referenced by name

Gate 2: Clinical Accuracy

• Biomarker values match source exactly
• Units are correct
• Status classifications accurate
• Recommendations align with preference level
• Clinical conventions followed

Cost Comparison

78% cost reduction with maintained or improved quality.

Module Structure

lib/biomarker_analysis/
├── __init__.py      # Module exports
├── types.py         # Pydantic models
├── state.py         # State persistence
├── kb_client.py     # VectorShift KB queries
├── parser.py        # Biomarker extraction
├── generation.py    # Category analysis generation
├── validation.py    # Dual quality gates
├── execution.py     # Main iteration loop
├── synthesis.py     # Cross-category synthesis
└── visual.py        # HTML report generation

API Reference

ExecutionEngine

class ExecutionEngine:
    def __init__(output_dir, config, callbacks...)
    def initialize_from_biomarkers(biomarkers, user_preference_level, patient_goals, ...)
    async def run() -> AnalysisPRD
    def run_sync() -> AnalysisPRD
    async def resume() -> AnalysisPRD
    def get_status() -> Dict
    def is_complete() -> bool

StateManager

class StateManager:
    def load_prd() -> Optional[AnalysisPRD]
    def save_prd(prd)
    def create_prd_from_biomarkers(biomarkers, ...) -> AnalysisPRD
    def get_segment(segment_id) -> CategorySegment
    def update_segment(segment)
    def mark_segment_completed(segment_id)
    def log_iteration(segment, status, ...)

KBClient

class KBClient:
    async def query(queries: List[str]) -> Dict
    def generate_category_queries(segment, user_preference_level) -> List[str]
    async def get_category_research_context(segment, ...) -> Dict

Error Handling

• Validation Failures: Automatically retry with specific feedback (up to 2 retries)
• KB Query Failures: Continue with empty research context
• Blocked Segments: Marked as blocked, analysis continues with other segments
• Resume: Full state persistence allows resuming from any point

Testing

# Run tests
pytest tests/test_biomarker_analysis.py

# Test single category
python -c "
from lib.biomarker_analysis.execution import ExecutionEngine
engine = ExecutionEngine()
# Initialize and run...
"