# 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",
)

from lib.biomarker_analysis.execution import resume_analysis

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

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)

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

.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

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

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

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, ...)

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

# 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...
"