Look up a single ICD-10-CM concept by its exact billing code.

Use this when the caller already has a specific code, e.g. "E11.21", and wants its name and OMOP metadata. Not a search tool — for free-text clinical terms use search_concepts instead.

:param concept_code: An exact ICD-10-CM code, e.g. "E11.21". :returns: The matching concept, or None if no ICD-10-CM concept has that code. :rtype: Concept | None

Expand an ICD-10-CM code to every code beneath it in the billing hierarchy.

For example, expanding "E11" (Type 2 diabetes mellitus) returns all of its more specific subtypes, such as "E11.21" (with diabetic nephropathy). Every returned concept is tagged generated provenance: it is a structural consequence of the vocabulary hierarchy, not a clinically validated inclusion, and should be treated as ungrounded until a human confirms it belongs in the target population.

:param seed_code: An exact ICD-10-CM code to expand from, e.g. "E11". :returns: All descendant concepts, or an empty set if seed_code does not exist or has no descendants. :rtype: ConceptSet

Search ICD-10-CM concept names for a free-text clinical term or phrase.

Combines lexical (BM25) and semantic (embedding) matching, fused by reciprocal rank, so paraphrased or loosely-worded descriptions (e.g. "sugar disease" for diabetes) are found even without shared exact wording — always prefer this over guessing at exact terminology yourself. Every returned concept is tagged generated provenance and should be treated as ungrounded until a human confirms it.

:param query: Free-text search string, e.g. "diabetic nephropathy". :param k: Maximum number of results to return. :returns: Fused, deduplicated results ordered by combined relevance. If nothing matches, concepts is empty and unmappable explains why. :rtype: ConceptSet

Search the OHDSI Phenotype Library for a validated cohort definition.

Use this FIRST for any population description that plausibly matches a peer-reviewed phenotype (e.g. "type 2 diabetes", "diabetic ketoacidosis") — a match here is curated provenance, safe to use as-is citing the cohort id. Only fall back to search_concepts/expand_hierarchy if nothing matches; those return generated provenance requiring human confirmation. This demo bundles a small, hand-picked set of diabetes/kidney-related cohorts, not the full library — a miss here does not mean no curated definition exists.

:param query: Free-text population description. :returns: The best-matching cohort's resolved ICD-10-CM concepts tagged curated, or an empty set with an explanatory unmappable entry if nothing in the bundled set matches or the library has not been fetched yet. :rtype: ConceptSet