Skip to content

llm_attribute_extractor

Four-step SNOMED CT attribute extraction pipeline.

Public API

extract_attributes(source_term, attribute_searcher, ...) → dict

Helpers handle individual steps

infer_attributes — Step 2 (LLM infers attribute mentions) _retrieve_candidates — Step 3 (embed mentions, retrieve SNOMED candidates) _build_selection_prompt — Step 4 (build LLM selection prompt)

ContentFilterError

Bases: Exception

Raised when the LLM content filter blocks a response.

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
65
66
class ContentFilterError(Exception):
    """Raised when the LLM content filter blocks a response."""

assign_role_groups(result, hierarchy_settings)

Group the selected attributes with the cached MRCM rules (in place); no-op when grouping is disabled.

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
588
589
590
591
592
593
def assign_role_groups(result: dict, hierarchy_settings) -> None:
    """Group the selected attributes with the cached MRCM rules (in place); no-op when grouping is disabled."""
    mrcm_settings = _mrcm_settings(hierarchy_settings)
    if mrcm_settings is None or not mrcm_settings.grouping.enabled:
        return
    group_result(result, mrcm_settings, _load_mrcm_rules(hierarchy_settings))

call_llm(system_prompt, user_prompt)

Call the LLM and return LlmResult(content, cost_usd).

Parameters:

Name Type Description Default
system_prompt str

System-level prompt text.

required
user_prompt str

User-level prompt text.

required

Returns:

Type Description
LlmResult

LlmResult(content, cost).

Raises:

Type Description
ContentFilterError

If the content filter blocks the response.

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def call_llm(system_prompt: str, user_prompt: str) -> LlmResult:
    """Call the LLM and return ``LlmResult(content, cost_usd)``.

    Args:
        system_prompt: System-level prompt text.
        user_prompt: User-level prompt text.

    Returns:
        LlmResult(content, cost).

    Raises:
        ContentFilterError: If the content filter blocks the response.
    """
    result = get_llm_response(user_prompt, system_prompt=system_prompt)
    if result["content"] is None:
        raise ContentFilterError(
            f"Content filter triggered for prompt: {user_prompt[:100]}..."
        )
    return LlmResult(result["content"], result["usage"]["total_cost_usd"])

drop_non_candidate_values(result, candidates)

Remove selected concepts that were not offered as candidates for their attribute (in place).

The selection prompt only allows candidates, but the LLM can copy a concept from the reference examples instead. Such values are removed from attributes, llm_role_groups and role_groups, and recorded in result["dropped_selections"].

Parameters:

Name Type Description Default
result dict

Pipeline result with the selected concepts.

required
candidates DataFrame | list[dict]

The retrieved candidates (candidates_df or result["retrieved_candidates"]).

required

Returns:

Type Description
list[dict]

The dropped values as {"attribute", "concept_id", "concept_name"} dicts.

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
def drop_non_candidate_values(result: dict, candidates: pd.DataFrame | list[dict]) -> list[dict]:
    """Remove selected concepts that were not offered as candidates for their attribute (in place).

    The selection prompt only allows candidates, but the LLM can copy a concept from the reference
    examples instead. Such values are removed from ``attributes``, ``llm_role_groups`` and
    ``role_groups``, and recorded in ``result["dropped_selections"]``.

    Args:
        result: Pipeline result with the selected concepts.
        candidates: The retrieved candidates (``candidates_df`` or ``result["retrieved_candidates"]``).

    Returns:
        The dropped values as ``{"attribute", "concept_id", "concept_name"}`` dicts.
    """
    rows = candidates.to_dict("records") if isinstance(candidates, pd.DataFrame) else list(candidates or [])
    allowed: dict[str, set[str]] = {}
    for row in rows:
        allowed.setdefault(str(row.get("attribute_key")), set()).add(str(row.get("concept_id")))

    dropped: dict[tuple[str, str], dict] = {}

    def keep(key: str, concept) -> bool:
        if not isinstance(concept, dict) or concept.get("concept_id") in (None, ""):
            return True
        concept_id = str(concept["concept_id"])
        if concept_id in allowed.get(EXTRACTION_KEY_ALIASES.get(key, key), set()):
            return True
        entry = dropped.setdefault(
            (key, concept_id), {"attribute": key, "concept_id": concept_id, "concept_name": None}
        )
        entry["concept_name"] = entry["concept_name"] or concept.get("concept_name")
        return False

    attributes = result.get("attributes")
    if isinstance(attributes, dict):
        for key, value in list(attributes.items()):
            if value is None:
                continue
            if key == INTERPRETS_PAIR_KEY and isinstance(value, list):
                attributes[key] = [
                    pair for pair in value
                    if not isinstance(pair, dict) or all([keep(k, v) for k, v in pair.items()])
                ]
            elif isinstance(value, list):
                attributes[key] = [concept for concept in value if keep(key, concept)]
            elif not keep(key, value):
                attributes[key] = None

    if "llm_role_groups" in result:
        groups = []
        for group in result.get("llm_role_groups") or []:
            if not isinstance(group, dict):
                groups.append(group)
                continue
            kept = {}
            for key, value in group.items():
                if isinstance(value, list):
                    kept[key] = [concept for concept in value if keep(key, concept)]
                elif keep(key, value):
                    kept[key] = value
            if any(kept.values()):
                groups.append(kept)
        if groups:
            result["llm_role_groups"] = groups
        else:
            result.pop("llm_role_groups")

    if "role_groups" in result:
        role_groups = []
        for group in result.get("role_groups") or []:
            members = [m for m in group.get("members", []) if keep(str(m.get("attribute")), m)]
            if members:
                role_groups.append({**group, "members": members})
        result["role_groups"] = role_groups

    if dropped:
        result["dropped_selections"] = result.get("dropped_selections", []) + list(dropped.values())
    return list(dropped.values())

extract_attributes(source_term, attribute_searcher, reference_searcher, hierarchy_settings=None)

Run the 4-step SNOMED CT attribute extraction pipeline.

Steps
  1. Retrieve reference examples (similar SNOMED concepts and their attributes).
  2. LLM infers applicable attributes.
  3. Retrieve SNOMED candidate values per attribute.
  4. LLM selects exact SNOMED concepts from candidates.

Parameters:

Name Type Description Default
source_term str

The clinical term to decompose.

required
attribute_searcher AttributeSearcher

SnomedAttributeSearcher over the snomed_attribute table.

required
reference_searcher ReferenceSearcher

SnomedReferenceConceptVectorSearcher supplying few-shot reference examples.

required
hierarchy_settings HierarchySettings | None

Pipeline configuration.

None

Returns:

Type Description
dict

Dict with keys attributes, role_groups, grouping_method,

dict

extracted_components, retrieved_candidates, reference_examples,

dict

cost (plus llm_role_groups/mrcm_domain when available).

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
def extract_attributes(
    source_term: str,
    attribute_searcher: AttributeSearcher,
    reference_searcher: ReferenceSearcher,
    hierarchy_settings: HierarchySettings | None = None
) -> dict:
    """Run the 4-step SNOMED CT attribute extraction pipeline.

    Steps:
        1. Retrieve reference examples (similar SNOMED concepts and their attributes).
        2. LLM infers applicable attributes.
        3. Retrieve SNOMED candidate values per attribute.
        4. LLM selects exact SNOMED concepts from candidates.

    Args:
        source_term: The clinical term to decompose.
        attribute_searcher: ``SnomedAttributeSearcher`` over the ``snomed_attribute`` table.
        reference_searcher: ``SnomedReferenceConceptVectorSearcher`` supplying few-shot
            reference examples.
        hierarchy_settings: Pipeline configuration.

    Returns:
        Dict with keys ``attributes``, ``role_groups``, ``grouping_method``,
        ``extracted_components``, ``retrieved_candidates``, ``reference_examples``,
        ``cost`` (plus ``llm_role_groups``/``mrcm_domain`` when available).
    """

    # Step 1
    logger.debug("Step 1: Finding reference examples")
    reference_examples, ref_cost = reference_searcher.search(source_term,
                                                             top_k=hierarchy_settings.retrieval.num_reference_examples)

    # Step 2
    logger.debug("Step 2: Inferring attributes")
    components, extraction_cost = infer_attributes(source_term,
                                                   reference_examples=reference_examples,
                                                   hierarchy_settings=hierarchy_settings)

    # Step 3
    logger.debug("Step 3: Retrieving candidates...")
    candidates_df, embedding_cost = _retrieve_candidates(
        components, attribute_searcher,
        hierarchy_settings=hierarchy_settings
    )

    # Step 4
    logger.debug("Step 4: Selecting best matches")
    candidates_text = _build_selection_prompt(candidates_df)
    selection_cost = 0.0
    if candidates_text.strip():
        reference_text = format_reference_examples(reference_examples, hierarchy_settings, include_concept_ids=True)
        system_prompt = _fill_prompt(hierarchy_settings.prompts.selection, reference_text, hierarchy_settings)
        user_prompt = f"Medical term: {source_term}\n\nCandidate concepts:\n{candidates_text}"
        extracted_groups_text = _format_extracted_role_groups(components)
        if extracted_groups_text:
            user_prompt += f"\n\n{extracted_groups_text}"
        response, selection_cost = call_llm(system_prompt, user_prompt)
        result = parse_json_response(response)
    else:
        logger.debug("Step 4 skipped: no candidates available for selection.")
        result = {"attributes": {}}

    total_cost = ref_cost + extraction_cost + embedding_cost + selection_cost

    llm_role_groups = _merge_role_groups_into_attributes(result)
    if llm_role_groups:
        result["llm_role_groups"] = llm_role_groups

    dropped = drop_non_candidate_values(result, candidates_df)
    if dropped:
        logger.warning(
            "%s: dropped selected value(s) not among the candidates: %s",
            source_term,
            "; ".join(f"{d['attribute']}={d['concept_name']} ({d['concept_id']})" for d in dropped),
        )

    # --- Enforce interprets ↔ interpretation pairing ---
    if "attributes" in result:
        _enforce_interprets_pairing(result["attributes"])

    _inject_selected_concept_codes(result, candidates_df)

    assign_role_groups(result, hierarchy_settings)
    _attach_pipeline_metadata(
        result,
        extracted_components=components,
        candidates_df=candidates_df,
        reference_examples=reference_examples,
        extraction_cost=extraction_cost,
        embedding_cost=embedding_cost,
        selection_cost=selection_cost,
        total_cost=total_cost,
    )
    logger.debug("Total cost: $%.4f", total_cost)
    return result

format_reference_examples(similar_terms, hierarchy_settings, include_concept_ids=False)

Format reference examples into a human-readable block for the prompt.

Parameters:

Name Type Description Default
similar_terms list[dict]

List of reference dicts from the reference searcher.

required
hierarchy_settings HierarchySettings

Pipeline configuration; hierarchy.attributes names each relationship by its pipeline attribute key (e.g. "Has pathology" → pathological_process). Relationships it doesn't list are shown by their OHDSI name.

required
include_concept_ids

Append concept IDs to terms and attribute values.

False

Returns:

Type Description
str

Formatted string, or empty string if no terms.

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
def format_reference_examples(
    similar_terms: list[dict], hierarchy_settings: HierarchySettings, include_concept_ids=False
) -> str:
    """Format reference examples into a human-readable block for the prompt.

    Args:
        similar_terms: List of reference dicts from the reference searcher.
        hierarchy_settings: Pipeline configuration; ``hierarchy.attributes`` names each relationship
            by its pipeline attribute key (e.g. ``"Has pathology"`` → ``pathological_process``).
            Relationships it doesn't list are shown by their OHDSI name.
        include_concept_ids: Append concept IDs to terms and attribute values.

    Returns:
        Formatted string, or empty string if no terms.
    """
    if not similar_terms:
        return ""
    attribute_key = hierarchy_settings.attribute_by_relationship()
    examples = []
    for term in similar_terms:
        attrs_text = []
        for a in term["attributes"]:
            line = f"  - {attribute_key.get(a['attribute_category'], a['attribute_category'])}: {a['target_concept_name']}"
            attrs_text.append(f"{line} ({a['target_concept_id']})" if include_concept_ids else line)
        attrs_str = "\n".join(attrs_text) if attrs_text else "  (no attributes)"
        if include_concept_ids:
            examples.append(f"Term: {term['concept_name']} ({term['concept_id']})\nAttributes:\n{attrs_str}")
        else:
            examples.append(f"Term: {term['concept_name']}\nAttributes:\n{attrs_str}")
    if not examples:
        return ""
    else:
        return "=== SIMILAR EXAMPLES ===\n" + "\n\n".join(examples)

infer_attributes(source_term, reference_examples, hierarchy_settings)

Step 2: Use the LLM to infer applicable SNOMED attributes.

Parameters:

Name Type Description Default
source_term str

Term to decompose.

required
reference_examples List

Reference examples.

required
hierarchy_settings HierarchySettings

Pipeline configuration.

required

Returns:

Type Description
Tuple[Dict, float]

ExtractionResult(components, cost).

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
def infer_attributes(
    source_term: str,
    reference_examples: List,
    hierarchy_settings: HierarchySettings,
) -> Tuple[Dict, float]:
    """Step 2: Use the LLM to infer applicable SNOMED attributes.

    Args:
        source_term: Term to decompose.
        reference_examples: Reference examples.
        hierarchy_settings: Pipeline configuration.

    Returns:
        ExtractionResult(components, cost).
    """
    reference_text = format_reference_examples(reference_examples, hierarchy_settings, include_concept_ids=False)
    system_prompt = _fill_prompt(hierarchy_settings.prompts.extraction, reference_text, hierarchy_settings)
    user_prompt = f'Determine the attributes for: "{source_term}"'
    response, cost = call_llm(system_prompt, user_prompt)
    return parse_json_response(response), cost

parse_json_response(response)

Parse a JSON response from an LLM, stripping markdown fences if present.

Parameters:

Name Type Description Default
response str

Raw LLM response string.

required

Returns:

Type Description
dict

Parsed dict.

Raises:

Type Description
ValueError

If the response cannot be parsed as JSON.

Source code in src/ariadne/hierarchy/llm_attribute_extractor.py
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def parse_json_response(response: str) -> dict:
    """Parse a JSON response from an LLM, stripping markdown fences if present.

    Args:
        response: Raw LLM response string.

    Returns:
        Parsed dict.

    Raises:
        ValueError: If the response cannot be parsed as JSON.
    """
    raw = response  # keep original for diagnostics
    response = response.strip()
    if response.startswith("```"):
        response = response.split("```")[1]
        if response.startswith("json"):
            response = response[4:]
    try:
        return json.loads(response)
    except json.JSONDecodeError as exc:
        logger.error(
            "Failed to parse LLM response as JSON. Raw response:\n%s", raw
        )
        raise ValueError(
            f"LLM returned malformed JSON: {exc}. "
            f"First 200 chars of response: {raw[:200]!r}"
        ) from exc