Skip to content

v0.4.0 - Source-Disciplined Health-System Metrics

Latest
Latest

Choose a tag to compare

View all tags
@ajhcs ajhcs released this 15 Jun 16:26
v0.4.0
f40ca2d
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v0.4.0 - Source-Disciplined Health-System Metrics

Released: 2026-06-15

This minor release adds a national health-system metrics surface to
health-system-profiler using the AHRQ Compendium 2023 health-system universe as
the canonical public snapshot.

Health-System Metrics

  • Added health-system-profiler.list_health_system_metrics for cursor-paginated
    national metrics browsing with state filters, deterministic snapshot IDs, and
    bounded page sizes.
  • Added health-system-profiler.get_health_system_metrics for exact system ID
    lookup and conservative system-name resolution that returns candidates for
    ambiguous or low-confidence names.
  • Returns AHRQ snapshot hospital counts, nonfederal general acute hospital
    counts, linked hospital row counts, nonfederal general acute bed counts,
    hospital-level hos_beds values, and AHRQ Compendium physician counts.
  • Includes facility details with hospital address/type candidates, conflicts,
    CCN identity caveats, leading-zero preservation, and shared-CCN warnings.

Source Discipline

  • Every metrics response declares the AHRQ Compendium 2023 universe, snapshot
    year, source release, data mode, and snapshot ID.
  • Defaults to compendium_snapshot mode so AHRQ 2023 values are not silently
    replaced by current CMS data.
  • Adds latest_public_overlay mode for explicitly labeled CMS HGI/POS/HCRIS/state
    candidates while preserving the AHRQ snapshot values.
  • Adds concrete coverage summaries for system counts, hospital linkage rows,
    linked nonfederal general acute hospitals, count completeness, bed coverage,
    and overlay match counts.

Compatibility And QA

  • Preserves nullable AHRQ metric semantics for the new API while keeping legacy
    profile fields tolerant of pd.NA and missing numeric values.
  • Maintains legacy AHRQ aliases for existing profiler/discovery consumers.
  • Hardens cursor validation so mismatched sort, filters, state scope, or data
    mode return recoverable cursor_filter_mismatch responses.
  • Adds regression coverage for nullable parsing, fuzzy-name ambiguity, cursor
    mismatch handling, snapshot ID stability, source-vintage rules, and Medicare
    public clinician roster NPI deduplication.

Verification

  • python3 -m pytest tests/servers/health_system_profiler -q
  • python3 -m pytest tests/shared/test_bed_resolver.py -q
  • python3 -m pytest tests/shared/utils/test_cms_client.py tests/test_workflows.py tests/test_mcp_tool_contracts.py -q
  • python3 -m pytest tests/servers/test_smoke_servers.py -q -k health_system_profiler
  • hc-mcp doctor --check
Assets 2
Loading