NetworkSim - Provider Network Intelligence & Analytics

Overview

NetworkSim provides provider network intelligence using real NPPES provider data (8.9M records), CMS facility data (60K+ facilities), and quality metrics integrated with PopulationSim demographics. Unlike synthetic generation, NetworkSim queries actual registered providers to enable:

1. Provider Discovery: Search providers by specialty, location, credentials, quality
2. Network Analysis: Assess adequacy against regulatory standards (CMS MA, NCQA, Medicaid)
3. Healthcare Access: Identify deserts combining access gaps, health needs, and vulnerability
4. Cross-Product Integration: Provide authentic providers for PatientSim, MemberSim, TrialSim

Key Differentiator: NetworkSim uses real NPPES registry data, not synthetic generation. Every NPI returned is a real, registered healthcare provider.

Quick Reference

Trigger Phrases

Provider Search

• "Find [specialty] in [location]"
• "Search for primary care providers in [county]"
• "Show me cardiologists within 10 miles of [zip]"
• "List all orthopedic surgeons in Texas"
• "Find providers with NPI starting with [prefix]"

Facility Search

• "Find hospitals in [county/state]"
• "Show me 4-star hospitals in California"
• "List nursing homes in [city]"
• "Find trauma centers near [location]"
• "Search for ambulatory surgery centers"

Validation & Roster

• "Is NPI 1234567890 valid?"
• "Validate this NPI: [number]"
• "Create a network roster for [specialty] in [geography]"
• "Export provider list to CSV"
• "Generate directory of PCPs for [county]"

Density & Coverage

• "What's the provider density in [county]?"
• "Providers per 100K population in Texas"
• "Compare density to HRSA benchmarks"
• "Which specialties have gaps in [region]?"
• "Assess geographic coverage for [state]"

Quality Filtering

• "Show only 5-star hospitals"
• "Find MD/DO providers only"
• "Filter by board certification"
• "High-quality providers in [area]"
• "Premium tier hospitals"

Network Adequacy

• "Assess PCP adequacy for California"
• "Does this network meet CMS standards?"
• "NCQA specialty coverage check"
• "Provider-to-enrollee ratio analysis"
• "Time/distance access assessment"

Healthcare Deserts

• "Identify healthcare deserts in Texas"
• "Show underserved counties"
• "Find areas with low access + high disease burden"
• "Critical shortage areas for primary care"
• "Equity analysis for vulnerable populations"

Skill Inventory

Query Skills (9 skills)

Analytics Skills (2 skills)

Synthetic Skills (6 skills)

Integration Skills (5 skills)

Reference Skills (7 skills)

Pattern Skills (5 skills)

Output Types

ProviderSearchResult

Provider records from NPPES database:

{
  "npi": "1234567890",
  "entity_type": "individual",
  "name": {
    "last": "Johnson",
    "first": "Sarah",
    "credential": "MD, FACC"
  },
  "taxonomy": {
    "code": "207RC0000X",
    "classification": "Internal Medicine",
    "specialization": "Cardiovascular Disease"
  },
  "practice_location": {
    "address": "123 Medical Center Dr",
    "city": "Houston",
    "state": "TX",
    "zip": "77030",
    "county_fips": "48201"
  },
  "enumeration_date": "2015-03-15",
  "last_update": "2024-11-01"
}

AdequacyAssessment

Network adequacy evaluation against standards:

{
  "geography": {
    "type": "state",
    "code": "CA",
    "name": "California"
  },
  "standard": "CMS_MA",
  "assessment_date": "2025-01-15",
  "metrics": {
    "pcp_ratio": {
      "actual": 85.3,
      "required": 83.3,
      "adequacy_pct": 102.4,
      "status": "ADEQUATE"
    },
    "specialist_coverage": {
      "ncqa_13_specialties": 13,
      "covered": 13,
      "status": "COMPLETE"
    }
  },
  "overall_status": "COMPLIANT"
}

HealthcareDesert

Desert identification with severity scoring:

{
  "geography": {
    "fips": "48001",
    "county": "Anderson County",
    "state": "Texas"
  },
  "desert_type": "primary_care",
  "severity": "critical",
  "scores": {
    "access_gap": 0.85,
    "health_burden": 0.72,
    "social_vulnerability": 0.68,
    "quality_gap": 0.45,
    "composite": 0.73
  },
  "indicators": {
    "providers_per_100k": 12.3,
    "hrsa_benchmark": 60.0,
    "diabetes_prevalence": 0.142,
    "svi_percentile": 0.78
  },
  "intervention_priority": 1
}

NetworkRoster

Exportable provider roster:

{
  "roster_id": "ROSTER-CA-PCP-2025-001",
  "generated_at": "2025-01-15T10:30:00Z",
  "criteria": {
    "specialty": "Primary Care",
    "geography": "San Diego County, CA",
    "quality_filter": "MD/DO only"
  },
  "summary": {
    "total_providers": 2847,
    "by_taxonomy": {
      "207Q00000X": 1523,
      "207R00000X": 892,
      "363L00000X": 432
    }
  },
  "export_formats": ["csv", "json", "xlsx"]
}

Data Sources

Provider Data (network.providers)

Key Columns: npi, entity_type_code, last_name, first_name, credential, taxonomy_1-4, practice_state, practice_city, practice_zip, county_fips

Facility Data (network.facilities)

Hospital Quality (network.hospital_quality)

Physician Quality (network.physician_quality)

AHRF County Data (network.ahrf_county)

Regulatory Standards

CMS Medicare Advantage

Provider-to-Enrollee Ratios:

Time/Distance Standards:

NCQA 13 Essential Specialties

Must have at least one contracted provider in each:

1. Primary Care
2. Cardiology
3. Dermatology
4. Endocrinology
5. Gastroenterology
6. General Surgery
7. Neurology
8. OB/GYN
9. Ophthalmology
10. Orthopedic Surgery
11. Otolaryngology (ENT)
12. Psychiatry
13. Urology

HRSA Benchmarks

Performance Benchmarks

Database: healthsim.duckdb (1.7 GB) Indexes: county_fips, taxonomy_1, practice_state

Cross-Product Integration

NetworkSim → PatientSim

Assign providers to clinical encounters:

-- Find cardiologist for heart failure patient
SELECT npi, first_name, last_name, credential
FROM network.providers
WHERE taxonomy_1 LIKE '207RC%'  -- Cardiovascular
  AND practice_state = 'TX'
  AND county_fips = '48201'     -- Harris County
LIMIT 1;

NetworkSim → MemberSim

Determine network status for claims:

-- Check if provider is in network
SELECT 
  CASE WHEN p.npi IS NOT NULL THEN 'IN_NETWORK' 
       ELSE 'OUT_OF_NETWORK' END as network_status
FROM network.providers p
WHERE p.npi = '1234567890';

NetworkSim + PopulationSim

Equity analysis combining provider access with vulnerability:

-- Provider access in vulnerable communities
SELECT 
    sv.county,
    sv.rpl_themes as svi_percentile,
    COUNT(DISTINCT p.npi) as provider_count,
    sv.e_totpop as population,
    ROUND(COUNT(DISTINCT p.npi) * 100000.0 / sv.e_totpop, 1) as per_100k
FROM population.svi_county sv
LEFT JOIN network.providers p ON sv.stcnty = p.county_fips
WHERE sv.rpl_themes > 0.75  -- Most vulnerable quartile
GROUP BY sv.county, sv.rpl_themes, sv.e_totpop
ORDER BY per_100k ASC;

Development Status

Phase 1: Data Infrastructure ✅

• NPPES data import (8.9M providers)
• Geographic enrichment (97.77% county FIPS)
• Quality metrics integration (CMS Hospital Compare)
• Test framework (18 tests passing)

Phase 2: Query Skills ✅

• 9 query skills (provider, facility, pharmacy, NPI, roster, density, coverage, quality)
• 4,069 lines documentation

Phase 3: Advanced Analytics 🎯 (Current)

• Network adequacy analysis
• Healthcare deserts identification
• Specialty distribution analysis
• Provider demographics analysis

Progress: 8 of 12 sessions complete (66%)

Validation Rules

NPI Validation

• 10 digits exactly
• Luhn algorithm checksum
• Prefix 1 or 2 (individual vs organization)
• Active status in NPPES

Taxonomy Validation

• Valid NUCC taxonomy codes
• Matches provider specialty claim
• Primary taxonomy switch indicator

Geographic Validation

• Valid state abbreviation (2 letters)
• Valid county FIPS (5 digits)
• ZIP code format (5 or 9 digits)

Related Documentation

• Examples: hello-healthsim/examples/networksim-examples.md
• Developer Guide: developer-guide.md
• Prompt Guide: prompt-guide.md
• Data Architecture: docs/healthsim-duckdb-schema.md
• Master SKILL.md: SKILL.md

Last Updated: December 28, 2025 Version: 2.0.0 Status: Active (Phase 3)