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 (CMSMA/NCQA), metrics.pcp_ratio (actual, required, status), metrics.specialist_coverage (13 specialties), overall_status (COMPLIANT/NONCOMPLIANT).

HealthcareDesert

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

NetworkRoster

Key fields: roster_id, criteria (specialty, geography, qualityfilter), summary (totalproviders, 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, entitytypecode, lastname, firstname, credential, taxonomy1-4, practicestate, practicecity, practicezip, 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: 0.75 -- Most vulnerable quartile

GROUP BY sv.county, sv.rplthemes, sv.etotpop 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](../../hello-healthsim/examples/networksim-examples.md)
- **Developer Guide**: [developer-guide.md](developer-guide.md)
- **Prompt Guide**: [prompt-guide.md](prompt-guide.md)
- **Data Architecture**: [docs/healthsim-duckdb-schema.md](../../docs/healthsim-duckdb-schema.md)
- **Master SKILL.md**: [SKILL.md](../../SKILL.md)

---

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mark64oswald](https://github.com/mark64oswald)
- **Source:** [mark64oswald/healthsim-workspace](https://github.com/mark64oswald/healthsim-workspace)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.