NetworkSim - Provider Network Intelligence & Analytics

Overview

NetworkSim queries real NPPES provider data (8.9M records), CMS facility data (60K+ facilities), and quality metrics. Unlike synthetic generation, it uses actual registered providers to enable:

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

Quick Reference

Trigger Phrases

• Provider/Facility: "find [specialty] in [location]", "hospitals in [state]", "nursing homes near", "pharmacies in"
• Validation/Roster: "validate NPI", "is NPI valid", "create roster", "export providers"
• Density/Coverage: "providers per 100K", "density in [county]", "HRSA benchmark"
• Quality: "4-star hospitals", "MD/DO only", "board certified"
• Adequacy: "CMS adequacy standards", "NCQA coverage", "provider ratio", "time/distance"
• Deserts/Access: "healthcare deserts", "underserved counties", "access gaps", "shortage areas"

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

Key fields: geography (type, code, name), standard (CMS_MA/NCQA), metrics.pcp_ratio (actual, required, status), metrics.specialist_coverage (13 specialties), overall_status (COMPLIANT/NON_COMPLIANT).

HealthcareDesert

Key fields: geography (fips, county, state), desert_type, severity (critical/high/moderate), scores (access_gap, health_burden, social_vulnerability, composite 0-1), intervention_priority (1=highest).

NetworkRoster

Key fields: roster_id, criteria (specialty, geography, quality_filter), summary (total_providers, by_taxonomy), 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

Additional Tables

Regulatory Standards

See reference/network-adequacy.md for full CMS MA ratios, time/distance tables, NCQA 13 essential specialties, ECP requirements, and HPSA/MUA definitions.

Quick reference:

• CMS MA PCP ratio: 1:1,200 enrollees
• HRSA HPSA threshold: <60 PCPs per 100K
• NCQA requires coverage across 13 specialties
• Time/distance varies by urban/suburban/rural designation

Database: network schema of the HealthSim reference data (~/.healthsim/reference.duckdb for the plugin, healthsim.duckdb in a checkout), indexed on 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;

Safety Guardrails

Real Data Disclaimer

NetworkSim queries real NPPES registry data (public CMS data, non-PHI). Every NPI is a real registered provider. Results reflect registry status only -- not accepting-patients, insurance participation, or clinical competence.

What NetworkSim Does NOT Do

• No clinical advice: Never suggest a provider is "best" for a condition
• No insurance verification: Network status is simulated, not real-time eligibility
• No appointment scheduling: Registry data is not a booking system
• No synthetic NPIs in real queries: Use synthetic/ skills only for test data

Code System References

Cross-product code systems (via PatientSim/MemberSim/RxMemberSim integration): ICD-10 (diagnoses), CPT (procedures), LOINC (labs), SNOMED (clinical terms), RxNorm/NDC (medications). These are real standard codes -- linked patient data is synthetic/fictional.

Edge Cases

• Missing county_fips: ~2.2% of records lack county FIPS; filter with WHERE county_fips IS NOT NULL for geographic queries
• Deactivated NPIs: Check npi_deactivation_date IS NULL for active providers
• Multi-taxonomy providers: Up to 15 taxonomies; taxonomy_1 is primary but check taxonomy_2-taxonomy_4 for dual-specialty searches
• Organization vs Individual: entity_type_code = 1 (individual) vs 2 (organization); filter appropriately

Negative Examples (What NOT to Do)

Never give clinical advice based on provider data:

• WRONG: "I recommend Dr. Smith for your heart condition" or "The patient needs a cardiologist"
• RIGHT: "Here are cardiologists registered in Harris County per NPPES data. This is simulated test data for analytics, not a referral."

Always distinguish real reference data from synthetic/fictional entities:

• WRONG: "Here is the patient's real provider" (implies real clinical relationship)
• RIGHT: "NPI data is from the real NPPES registry (public CMS data). Patient/encounter data is synthetic/fictional -- not real patient information."

Never mix synthetic and real data without labeling:

• WRONG: Return synthetic NPIs alongside real NPPES query results
• RIGHT: Label synthetic providers (from synthetic/ skills) vs real providers (from network.providers)

Validation Rules

NPI: 10 digits, Luhn checksum, prefix 1 (individual) or 2 (organization), active in NPPES

Taxonomy: Valid NUCC codes, primary taxonomy switch indicator

Geography: 2-letter state, 5-digit county FIPS, 5- or 9-digit ZIP

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)