Knowledge bases

cms_icd.knowledge_base.ICD10KnowledgeBase

ICD10KnowledgeBase(provider: MaterialProvider)

A CMS ICD-10 release with independently lazy CM and PCS views.

Construction records how materials should be found but performs no network request, download, or parsing. Accessing a view is also cheap; material is acquired only when tabular, index, or guidelines is accessed.

Examples:

>>> kb = ICD10KnowledgeBase.from_directory(
...     ".", fiscal_year=2026, release_date=date(2025, 10, 1)
... )
>>> repr(kb)
'ICD10KnowledgeBase(...loaded=[])'

Source code in src/cms_icd/knowledge_base.py

def __init__(self, provider: MaterialProvider) -> None:
    self._provider = provider
    self._cm: ICD10CMKnowledgeBase | None = None
    self._pcs: ICD10PCSKnowledgeBase | None = None

release property

release: Release

Return requested release metadata.

cm property

cm: ICD10CMKnowledgeBase

Return the lazy ICD-10-CM view.

pcs property

pcs: ICD10PCSKnowledgeBase

Return the lazy ICD-10-PCS view.

from_cms classmethod

from_cms(fiscal_year: int | None = None, *, year: int | None = None, release_date: date | None = None, cache_dir: str | Path | None = None, fallback: str | None = None, offline: bool = False) -> Self

Create a lazy selector for an exact CMS fiscal-year snapshot.

year is accepted as a compatibility alias for fiscal_year. Materials unchanged in the requested revision are inherited from the latest earlier revision in the same fiscal year.

Parameters:

Name	Type	Description	Default
fiscal_year	int | None	CMS fiscal year.	None
year	int | None	Compatibility alias for fiscal_year.	None
release_date	date | None	Effective date of the requested revision. Defaults to October 1 preceding the fiscal year.	None
cache_dir	str | Path | None	Persistent artifact cache directory. None uses the platform default cache directory.	None
fallback	str | None	Set to "latest_for_fy" to permit an explicit fallback.	None
offline	bool	Require the catalog and artifacts to already be cached.	False

Source code in src/cms_icd/knowledge_base.py

@classmethod
def from_cms(
    cls,
    fiscal_year: int | None = None,
    *,
    year: int | None = None,
    release_date: date | None = None,
    cache_dir: str | Path | None = None,
    fallback: str | None = None,
    offline: bool = False,
) -> Self:
    """Create a lazy selector for an exact CMS fiscal-year snapshot.

    ``year`` is accepted as a compatibility alias for ``fiscal_year``.
    Materials unchanged in the requested revision are inherited from the
    latest earlier revision in the same fiscal year.

    Args:
        fiscal_year: CMS fiscal year.
        year: Compatibility alias for ``fiscal_year``.
        release_date: Effective date of the requested revision. Defaults to
            October 1 preceding the fiscal year.
        cache_dir: Persistent artifact cache directory. ``None`` uses the
            platform default cache directory.
        fallback: Set to ``"latest_for_fy"`` to permit an explicit fallback.
        offline: Require the catalog and artifacts to already be cached.
    """
    selected_year = fiscal_year if fiscal_year is not None else year
    if selected_year is None:
        raise TypeError("fiscal_year is required")
    if fiscal_year is not None and year is not None and fiscal_year != year:
        raise ValueError("fiscal_year and year disagree")
    selected_date = release_date or date(selected_year - 1, 10, 1)
    release = Release(selected_year, selected_date)
    return cls(
        CMSProvider(
            release,
            cache_dir=cache_dir,
            fallback=fallback,
            offline=offline,
        ),
    )

for_date classmethod

for_date(service_date: date, *, cache_dir: str | Path | None = None, fallback: str | None = None, offline: bool = False) -> Self

Create a lazy selector for materials applicable on a coding date.

Use the discharge date for inpatient ICD-10-CM and ICD-10-PCS. Use the encounter or date of service for other ICD-10-CM coding.

Parameters:

Name	Type	Description	Default
service_date	date	Date that controls coding for the record.	required
cache_dir	str | Path | None	Persistent artifact cache directory. None uses the platform default cache directory.	None
fallback	str | None	Set to "latest_for_fy" to permit an explicit fallback.	None
offline	bool	Require the catalog and artifacts to already be cached.	False

Source code in src/cms_icd/knowledge_base.py

@classmethod
def for_date(
    cls,
    service_date: date,
    *,
    cache_dir: str | Path | None = None,
    fallback: str | None = None,
    offline: bool = False,
) -> Self:
    """Create a lazy selector for materials applicable on a coding date.

    Use the discharge date for inpatient ICD-10-CM and ICD-10-PCS. Use the
    encounter or date of service for other ICD-10-CM coding.

    Args:
        service_date: Date that controls coding for the record.
        cache_dir: Persistent artifact cache directory. ``None`` uses the
            platform default cache directory.
        fallback: Set to ``"latest_for_fy"`` to permit an explicit fallback.
        offline: Require the catalog and artifacts to already be cached.
    """
    release = Release(fiscal_year_for(service_date), service_date)
    return cls(
        CMSProvider(
            release,
            service_date=service_date,
            cache_dir=cache_dir,
            fallback=fallback,
            offline=offline,
        )
    )

from_directory classmethod

from_directory(directory: str | Path, *, fiscal_year: int, release_date: date) -> Self

Create an offline knowledge base from CMS-format files.

Source code in src/cms_icd/knowledge_base.py

@classmethod
def from_directory(
    cls,
    directory: str | Path,
    *,
    fiscal_year: int,
    release_date: date,
) -> Self:
    """Create an offline knowledge base from CMS-format files."""
    return cls(DirectoryProvider(directory, Release(fiscal_year, release_date)))

load_all

load_all() -> None

Eagerly load every CM and PCS material.

Source code in src/cms_icd/knowledge_base.py

def load_all(self) -> None:
    """Eagerly load every CM and PCS material."""
    self.cm.load_all()
    self.pcs.load_all()

__repr__

__repr__() -> str

Return a representation without acquiring any material.

Source code in src/cms_icd/knowledge_base.py

def __repr__(self) -> str:
    """Return a representation without acquiring any material."""
    loaded = [
        name
        for name, view in (("cm", self._cm), ("pcs", self._pcs))
        if view is not None
    ]
    return f"ICD10KnowledgeBase(release={self.release!r}, loaded={loaded!r})"

cms_icd.knowledge_base.ICD10CMKnowledgeBase

ICD10CMKnowledgeBase(provider: MaterialProvider | None, *, tabular: TabularStore | None = None, index: IndexStore | None = None, guidelines: GuidelineStore | None = None)

Lazy structured access to ICD-10-CM materials.

Instances are normally obtained from :attr:ICD10KnowledgeBase.cm.

Examples:

>>> from cms_icd.models import Code, Node
>>> from cms_icd.stores import IndexStore, TabularStore
>>> root = Node("cm", "cm", children_ids=("I10",))
>>> code = Code("I10", "I10", "Essential hypertension", parent_id="cm")
>>> tabular = TabularStore({"cm": root, "I10": code}, {"I10": "I10"}, ("cm",))
>>> cm = ICD10CMKnowledgeBase.from_stores(tabular=tabular)
>>> cm["I10"].description
'Essential hypertension'
>>> cm.get_all_tabular_parents("I10")[0].id
'cm'

Source code in src/cms_icd/knowledge_base.py

def __init__(
    self,
    provider: MaterialProvider | None,
    *,
    tabular: TabularStore | None = None,
    index: IndexStore | None = None,
    guidelines: GuidelineStore | None = None,
) -> None:
    self._provider = provider
    self._tabular = tabular
    self._index = index
    self._guidelines = guidelines
    self._tabular_lock = Lock()
    self._index_lock = Lock()
    self._guidelines_lock = Lock()
    self._render_cache: dict[tuple[str, ...], Guideline] = {}

from_stores classmethod

from_stores(*, tabular: TabularStore | None = None, index: IndexStore | None = None, guidelines: GuidelineStore | None = None) -> Self

Construct a CM view from prebuilt stores for custom sources or tests.

Source code in src/cms_icd/knowledge_base.py

@classmethod
def from_stores(
    cls,
    *,
    tabular: TabularStore | None = None,
    index: IndexStore | None = None,
    guidelines: GuidelineStore | None = None,
) -> Self:
    """Construct a CM view from prebuilt stores for custom sources or tests."""
    return cls(None, tabular=tabular, index=index, guidelines=guidelines)

get_chapter_guidelines

get_chapter_guidelines(codes: list[str]) -> Guideline

Render chapter-specific CM guidelines for a list of codes.

Source code in src/cms_icd/knowledge_base.py

def get_chapter_guidelines(self, codes: list[str]) -> Guideline:
    """Render chapter-specific CM guidelines for a list of codes."""
    keys: set[str] = set()
    for code in codes:
        parents = [
            item
            for item in self.tabular.parents(code)
            if item.id not in self.tabular.roots
        ]
        if not parents:
            continue
        chapter = parents[-1]
        keys.add(f"I.C.{chapter.name}")
    return self.render_guidelines(keys)

cms_icd.knowledge_base.ICD10PCSKnowledgeBase

ICD10PCSKnowledgeBase(provider: MaterialProvider | None, *, tabular: TabularStore | None = None, index: IndexStore | None = None, guidelines: GuidelineStore | None = None)

Lazy structured access to ICD-10-PCS materials.

Source code in src/cms_icd/knowledge_base.py

def __init__(
    self,
    provider: MaterialProvider | None,
    *,
    tabular: TabularStore | None = None,
    index: IndexStore | None = None,
    guidelines: GuidelineStore | None = None,
) -> None:
    self._provider = provider
    self._tabular = tabular
    self._index = index
    self._guidelines = guidelines
    self._tabular_lock = Lock()
    self._index_lock = Lock()
    self._guidelines_lock = Lock()
    self._render_cache: dict[tuple[str, ...], Guideline] = {}

from_stores classmethod

from_stores(*, tabular: TabularStore | None = None, index: IndexStore | None = None, guidelines: GuidelineStore | None = None) -> Self

Construct a PCS view from prebuilt stores for custom sources or tests.

Source code in src/cms_icd/knowledge_base.py

@classmethod
def from_stores(
    cls,
    *,
    tabular: TabularStore | None = None,
    index: IndexStore | None = None,
    guidelines: GuidelineStore | None = None,
) -> Self:
    """Construct a PCS view from prebuilt stores for custom sources or tests."""
    return cls(None, tabular=tabular, index=index, guidelines=guidelines)