types

Shared types and helpers for the SNOMED CT hierarchy pipeline.

NamedTuple result types provide self-documenting returns while remaining backward-compatible with existing a, b = func() unpacking.

interprets ↔ interpretation helpers centralise the paired-attribute logic that was previously duplicated across pipeline.py and evaluator.py.

ExtractionResult

Bases: NamedTuple

Return type for :func:~ariadne.hierarchy.pipeline.extract_components.

Source code in src/ariadne/hierarchy/types.py

class ExtractionResult(NamedTuple):
    """Return type for :func:`~ariadne.hierarchy.pipeline.extract_components`."""

    components: dict
    cost: float

LlmResult

Bases: NamedTuple

Return type for :func:~ariadne.hierarchy.pipeline.call_llm.

Source code in src/ariadne/hierarchy/types.py

class LlmResult(NamedTuple):
    """Return type for :func:`~ariadne.hierarchy.pipeline.call_llm`."""

    content: str
    cost: float

ReferenceRetrievalResult

Bases: NamedTuple

Return type for _retrieve_reference_examples.

Source code in src/ariadne/hierarchy/types.py

class ReferenceRetrievalResult(NamedTuple):
    """Return type for ``_retrieve_reference_examples``."""

    examples: list
    prompt_text: str
    cost: float

ReferenceSearchResult

Bases: NamedTuple

Return type for reference search and find_similar_reference_terms.

Source code in src/ariadne/hierarchy/types.py

class ReferenceSearchResult(NamedTuple):
    """Return type for reference ``search`` and ``find_similar_reference_terms``."""

    examples: list
    cost: float

SearchBatchResult

Bases: NamedTuple

Return type for search_batch.

Source code in src/ariadne/hierarchy/types.py

class SearchBatchResult(NamedTuple):
    """Return type for ``search_batch``."""

    results: dict  # dict[str, pd.DataFrame]
    cost: float

SearchResult

Bases: NamedTuple

Return type for attribute search and _retrieve_candidates.

Source code in src/ariadne/hierarchy/types.py

class SearchResult(NamedTuple):
    """Return type for attribute ``search`` and ``_retrieve_candidates``."""

    dataframe: Any  # pd.DataFrame
    cost: float

merge_interprets_keys(interprets_list, interpretation_list, *, verbose=False)

Merge separate interprets / interpretation lists into paired dicts.

Handles the backward-compatibility case where the LLM returns separate top-level keys instead of the expected interprets_interpretation list of pairs.

Parameters:

Name	Type	Description	Default
interprets_list	list | None	Values for the interprets side (may be a single value).	required
interpretation_list	list | None	Values for the interpretation side.	required
verbose	bool	Log warnings for dropped orphans.	False

Returns:

Type	Description
list[dict] | None	List of {interprets: ..., interpretation: ...} dicts, or None.

Source code in src/ariadne/hierarchy/types.py

def merge_interprets_keys(
    interprets_list: list | None,
    interpretation_list: list | None,
    *,
    verbose: bool = False,
) -> list[dict] | None:
    """Merge separate ``interprets`` / ``interpretation`` lists into paired dicts.

    Handles the backward-compatibility case where the LLM returns separate top-level
    keys instead of the expected ``interprets_interpretation`` list of pairs.

    Args:
        interprets_list: Values for the interprets side (may be a single value).
        interpretation_list: Values for the interpretation side.
        verbose: Log warnings for dropped orphans.

    Returns:
        List of ``{interprets: ..., interpretation: ...}`` dicts, or ``None``.
    """
    if interprets_list and not isinstance(interprets_list, list):
        interprets_list = [interprets_list]
    if interpretation_list and not isinstance(interpretation_list, list):
        interpretation_list = [interpretation_list]

    if not interprets_list or not interpretation_list:
        if verbose and (interprets_list or interpretation_list):
            logger.warning("  Dropped orphaned interprets/interpretation (missing pair)")
        return None

    pairs: list[dict] = []
    for i in range(max(len(interprets_list), len(interpretation_list))):
        pair: dict = {}
        if i < len(interprets_list) and interprets_list[i]:
            pair["interprets"] = interprets_list[i]
        if i < len(interpretation_list) and interpretation_list[i]:
            pair["interpretation"] = interpretation_list[i]
        if pair:
            pairs.append(pair)

    return pairs if pairs else None

split_interprets_pairs(pairs)

Split interprets_interpretation pairs into (attr_key, value) items.

Works for both mention-string pairs (pipeline retrieval) and concept-dict pairs (evaluator prediction rows).

Parameters:

Name	Type	Description	Default
pairs	list	List of dicts with optional interprets and interpretation keys.	required

Returns:

Type	Description
list[tuple[str, Any]]	List of (attr_key, value) tuples (value is whatever the dict contained).

Source code in src/ariadne/hierarchy/types.py

def split_interprets_pairs(pairs: list) -> list[tuple[str, Any]]:
    """Split ``interprets_interpretation`` pairs into ``(attr_key, value)`` items.

    Works for both mention-string pairs (pipeline retrieval) and concept-dict
    pairs (evaluator prediction rows).

    Args:
        pairs: List of dicts with optional ``interprets`` and ``interpretation`` keys.

    Returns:
        List of ``(attr_key, value)`` tuples (value is whatever the dict contained).
    """
    items: list[tuple[str, Any]] = []
    for pair in pairs:
        if not isinstance(pair, dict):
            continue
        for key in ("interprets", "interpretation"):
            val = pair.get(key)
            if val is not None:
                items.append((key, val))
    return items

validate_interprets_pairs(pairs, *, verbose=False)

Drop interprets_interpretation pairs missing either side.

Parameters:

Name	Type	Description	Default
pairs	list	List of pair dicts to validate.	required
verbose	bool	Log warnings for dropped incomplete pairs.	False

Returns:

Type	Description
list[dict] | None	List of valid pairs, or None if all dropped.

Source code in src/ariadne/hierarchy/types.py

def validate_interprets_pairs(
    pairs: list,
    *,
    verbose: bool = False,
) -> list[dict] | None:
    """Drop ``interprets_interpretation`` pairs missing either side.

    Args:
        pairs: List of pair dicts to validate.
        verbose: Log warnings for dropped incomplete pairs.

    Returns:
        List of valid pairs, or ``None`` if all dropped.
    """
    valid: list[dict] = []
    for pair in pairs:
        if not isinstance(pair, dict):
            continue
        has_interp = pair.get("interprets") is not None
        has_interpr = pair.get("interpretation") is not None
        if has_interp and has_interpr:
            valid.append(pair)
        elif verbose:
            logger.warning("  Dropped incomplete pair: %s", pair)
    return valid if valid else None