Skip to content

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 llm_attribute_extractor.py and hierarchy_attribute_evaluator.py.

LlmResult

Bases: NamedTuple

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

Source code in src/ariadne/hierarchy/types.py
22
23
24
25
26
class LlmResult(NamedTuple):
    """Return type for :func:`~ariadne.hierarchy.pipeline.call_llm`."""

    content: str
    cost: float

ReferenceSearchResult

Bases: NamedTuple

Return type for reference search and find_similar_reference_terms.

Source code in src/ariadne/hierarchy/types.py
43
44
45
46
47
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
36
37
38
39
40
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
29
30
31
32
33
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
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
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