healthsim-networksim

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

I want to...	Use This Skill	Key Triggers
Provider Search
Find providers by specialty	query/provider-search.md	"find cardiologists", "search for PCPs", "providers in"
Search hospitals/facilities	query/facility-search.md	"hospitals in", "find nursing homes", "clinics near"
Find pharmacies	query/pharmacy-search.md	"pharmacies in", "retail pharmacy", "specialty pharmacy"
Validation & Roster
Validate an NPI	query/npi-validation.md	"is NPI valid", "validate NPI", "check NPI"
Generate network roster	query/network-roster.md	"create roster", "export providers", "network list"
Density & Coverage
Calculate provider density	query/provider-density.md	"providers per 100K", "density analysis", "HRSA benchmark"
Assess network coverage	query/coverage-analysis.md	"network coverage", "geographic coverage", "specialty gaps"
Quality Metrics
Filter by hospital quality	query/hospital-quality-search.md	"4-star hospitals", "high quality", "CMS ratings"
Filter by physician credentials	query/physician-quality-search.md	"MD only", "board certified", "credentials"
Advanced Analytics
Assess network adequacy	analytics/network-adequacy-analysis.md	"adequacy assessment", "CMS standards", "NCQA requirements"
Identify healthcare deserts	analytics/healthcare-deserts.md	"healthcare deserts", "underserved areas", "access gaps"
Synthetic Generation
Generate synthetic provider	synthetic/synthetic-provider.md	"generate a provider", "create physician"
Generate synthetic facility	synthetic/synthetic-facility.md	"generate hospital", "create facility"
Generate synthetic pharmacy	synthetic/synthetic-pharmacy.md	"generate pharmacy", "create pharmacy"
Generate synthetic network	synthetic/synthetic-network.md	"generate network", "create provider network"
Generate synthetic plan	synthetic/synthetic-plan.md	"generate plan", "create health plan"
Integration
Assign provider to encounter	integration/provider-for-encounter.md	"provider for patient", "attending physician"
Determine network status	integration/network-for-member.md	"in-network check", "network status"
Route prescription	integration/pharmacy-for-rx.md	"pharmacy for prescription", "dispense at"

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)

Skill	File	Lines	Purpose
Provider Search	query/provider-search.md	450	Search 8.9M providers by specialty, location
Facility Search	query/facility-search.md	380	Search hospitals, nursing homes, clinics
Pharmacy Search	query/pharmacy-search.md	320	Search retail, specialty, mail pharmacies
NPI Validation	query/npi-validation.md	280	Validate NPIs with Luhn checksums
Network Roster	query/network-roster.md	350	Generate rosters in CSV/JSON/Excel
Provider Density	query/provider-density.md	400	Calculate density vs HRSA benchmarks
Coverage Analysis	query/coverage-analysis.md	380	Assess geographic/specialty coverage
Hospital Quality	query/hospital-quality-search.md	320	Filter by CMS star ratings
Physician Quality	query/physician-quality-search.md	290	Filter by credentials (MD/DO/NP/PA)

Analytics Skills (2 skills)

Skill	File	Lines	Purpose
Network Adequacy	analytics/network-adequacy-analysis.md	653	CMS/NCQA regulatory compliance
Healthcare Deserts	analytics/healthcare-deserts.md	757	Access + health needs + vulnerability

Synthetic Skills (6 skills)

Skill	File	Lines	Purpose
Synthetic Provider	synthetic/synthetic-provider.md	400	Generate providers with valid NPI format
Synthetic Facility	synthetic/synthetic-facility.md	350	Generate hospitals, ASCs, clinics
Synthetic Pharmacy	synthetic/synthetic-pharmacy.md	320	Generate pharmacies with NCPDP IDs
Synthetic Network	synthetic/synthetic-network.md	450	Generate complete network configurations
Synthetic Plan	synthetic/synthetic-plan.md	380	Generate health plan structures
Synthetic Pharmacy Benefit	synthetic/synthetic-pharmacy-benefit.md	350	Generate PBM configurations

Integration Skills (5 skills)

Skill	File	Lines	Purpose
Provider for Encounter	integration/provider-for-encounter.md	280	Assign providers to PatientSim
Network for Member	integration/network-for-member.md	300	Network status for MemberSim
Pharmacy for Rx	integration/pharmacy-for-rx.md	260	Pharmacy routing for RxMemberSim
Formulary for Rx	integration/formulary-for-rx.md	290	Formulary checks for RxMemberSim
Benefit for Claim	integration/benefit-for-claim.md	270	Benefit lookup for MemberSim

Reference Skills (7 skills)

Skill	File	Purpose
Network Types	reference/network-types.md	HMO, PPO, EPO, POS structures
Plan Structures	reference/plan-structures.md	Cost sharing, benefit design
Pharmacy Benefits	reference/pharmacy-benefit-concepts.md	PBM, formulary, tiers
Network Adequacy	reference/network-adequacy.md	CMS/NCQA standards
PBM Operations	reference/pbm-operations.md	Claims processing, rebates
Specialty Pharmacy	reference/specialty-pharmacy.md	Limited distribution, hubs
Utilization Management	reference/utilization-management.md	PA, step therapy, QL

Pattern Skills (5 skills)

Skill	File	Purpose
HMO Network	patterns/hmo-network-pattern.md	Closed network, gatekeeper model
PPO Network	patterns/ppo-network-pattern.md	Open access, tiered cost sharing
Tiered Network	patterns/tiered-network-pattern.md	Quality-based tier assignment
Specialty Distribution	patterns/specialty-distribution-pattern.md	Specialty mix by geography
Pharmacy Benefit	patterns/pharmacy-benefit-patterns.md	PBM network configurations

---

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)

Attribute	Value
Source	NPPES (National Plan and Provider Enumeration System)
Records	8,925,672
Update Frequency	Monthly CMS releases
Coverage	All active US healthcare providers with NPIs
County FIPS	97.77% coverage (3,213 of 3,286 counties)

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

Additional Tables

Table	Source	Records	Key Content
network.facilities	CMS POS file	77,302	Hospitals (01), SNFs (05), HHAs (07), Hospice (13)
network.hospital_quality	CMS Hospital Compare	5,421	Star ratings (1-5), mortality, readmission, safety
network.physician_quality	CMS Physician Compare	1,478,309	Quality measures, Medicare participation
network.ahrf_county	HRSA AHRF	3,235	Provider counts, hospital beds, health workforce

---

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: healthsim.duckdb (1.7 GB), 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

System	Used For	Example
NUCC Taxonomy	Provider specialty classification	207RC0000X = Cardiovascular Disease
NPI	Provider identification (Luhn-validated)	1234567890
County FIPS	Geographic scoping	48201 = Harris County, TX
CMS Certification Number	Facility identification	POS file facility IDs
CBSA	Urban/rural classification	Metro, micro, rural designations
HCPCS	Provider service codes	Level I (CPT) and Level II codes

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)