Shared, per-component settings dataclasses used by processing classes.
Top-level config classes (Config, ConfigDrugMapping) are composed of these
settings so the same structures are reused across different workflows.
Each processing class accepts only the settings it actually needs.
AndOrRewriteSettings
dataclass
Data driving the ICD 'and' → 'and/or' rewrite (logic lives in TermCleaner).
Source code in src/ariadne/utils/settings.py
113
114
115
116
117
118
119
120
121 | @dataclass
class AndOrRewriteSettings:
"""Data driving the ICD 'and' → 'and/or' rewrite (logic lives in TermCleaner)."""
vocabulary_ids: List[str] = field(default_factory=list)
excluded_codes: List[str] = field(default_factory=list)
excluded_prefixes: List[str] = field(default_factory=list)
excluded_name_patterns: List[str] = field(default_factory=list)
both_combined_exception_prefixes: List[str] = field(default_factory=list)
|
AttributeConfig
dataclass
Link between a pipeline attribute key and its SNOMED CT attribute concept.
Source code in src/ariadne/utils/settings.py
| @dataclass
class AttributeConfig:
"""Link between a pipeline attribute key and its SNOMED CT attribute concept."""
attribute_id: int = 0
ohdsi_relationship: str = ""
|
ConceptContextSettings
dataclass
Controls which context columns :func:add_concept_context adds.
Source code in src/ariadne/utils/settings.py
194
195
196
197
198
199
200
201
202
203
204
205 | @dataclass
class ConceptContextSettings:
"""Controls which context columns :func:`add_concept_context` adds."""
include_target_parents: bool = True
include_target_children: bool = True
include_target_synonyms: bool = True
include_target_domain: bool = True
include_target_class: bool = True
include_target_vocabulary: bool = True
include_target_clinical_drug_form_child_count: bool = False
re_insert_source_target_details: bool = True
|
ConceptFilterSettings
dataclass
Shared concept filters used by vocabulary download and vector search.
Source code in src/ariadne/utils/settings.py
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107 | @dataclass
class ConceptFilterSettings:
"""Shared concept filters used by vocabulary download and vector search."""
standard_concept: List[str] = field(default_factory=lambda: ["S"])
domain_ids: Optional[List[str]] = None
concept_class_ids: Optional[List[str]] = None
vocabulary_ids: Optional[List[str]] = None
exclude_concept_class_ids: Optional[List[str]] = None
exclude_vocabulary_ids: List[str] = field(default_factory=list)
def __post_init__(self) -> None:
allowed_values = {"S", "C", "None"}
if not self.standard_concept:
raise ValueError("filter.standard_concept must contain at least one value.")
invalid_values = [value for value in self.standard_concept if value not in allowed_values]
if invalid_values:
raise ValueError(
"Invalid filter.standard_concept values: "
f"{invalid_values}. Allowed values are {sorted(allowed_values)}."
)
|
DrugStructuringSettings
dataclass
Everything :class:LlmDrugStructurer needs.
Source code in src/ariadne/utils/settings.py
220
221
222
223
224
225
226
227
228
229
230
231 | @dataclass
class DrugStructuringSettings:
"""Everything :class:`LlmDrugStructurer` needs."""
llm_mapper_responses_folder: str = "data/llm_drug_mapper_responses"
drug_device_system_prompt: str = ""
ingredient_system_prompt: str = ""
drug_system_prompt: str = ""
device_system_prompt: str = ""
def __post_init__(self) -> None:
self.llm_mapper_responses_folder = resolve_path(self.llm_mapper_responses_folder)
|
EvaluationConfig
dataclass
Output for hierarchy evaluation.
Source code in src/ariadne/utils/settings.py
310
311
312
313
314
315
316
317
318
319 | @dataclass
class EvaluationConfig:
"""Output for hierarchy evaluation."""
output_dir: str = "data/notebook_results"
llm_response_folder: str = "data/hierarchy_attribute_responses"
max_workers: int = 4
def __post_init__(self) -> None:
self.llm_response_folder = resolve_path(self.llm_response_folder)
|
HecateSearchSettings
dataclass
Bases: VectorSearchSettings
Settings used by :class:HecateConceptSearcher.
Source code in src/ariadne/utils/settings.py
| @dataclass
class HecateSearchSettings(VectorSearchSettings):
"""Settings used by :class:`HecateConceptSearcher`."""
substrings_to_remove: List[str] = field(default_factory=list)
|
HierarchySettings
dataclass
Settings block loaded from the optional top-level hierarchy config key.
Source code in src/ariadne/utils/settings.py
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442 | @dataclass
class HierarchySettings:
"""Settings block loaded from the optional top-level ``hierarchy`` config key."""
index_build: IndexBuildConfig = field(default_factory=IndexBuildConfig)
retrieval: RetrievalConfig = field(default_factory=RetrievalConfig)
parent_selection: ParentSelectionConfig = field(default_factory=ParentSelectionConfig)
evaluation: EvaluationConfig = field(default_factory=EvaluationConfig)
prompts: PromptsConfig = field(default_factory=PromptsConfig)
# The SNOMED attributes of the pipeline, keyed by pipeline attribute key (``hierarchy.attributes``).
attributes: Dict[str, AttributeConfig] = field(default_factory=dict)
mrcm: MrcmSettings = field(default_factory=MrcmSettings)
def __post_init__(self) -> None:
self.attributes = {
key: value if isinstance(value, AttributeConfig) else AttributeConfig(**(value or {}))
for key, value in (self.attributes or {}).items()
}
@property
def snomed_relationships(self) -> List[str]:
"""OHDSI ``relationship_id`` of every configured attribute.
Used to fetch reference-example attributes and to build the ``snomed_attribute`` table.
"""
return list(self.relationship_by_attribute().values())
def relationship_type_ids(self) -> Dict[str, int]:
"""OHDSI ``relationship_id`` (e.g. ``"Has finding site"``) → SNOMED attribute concept ID (RF2 ``typeId``)."""
return {
attribute.ohdsi_relationship: attribute.attribute_id
for attribute in self.attributes.values()
if attribute.ohdsi_relationship and attribute.attribute_id
}
def relationship_by_attribute(self) -> Dict[str, str]:
"""Pipeline attribute key (e.g. ``"finding_site"``) → OHDSI ``relationship_id``."""
return {key: attribute.ohdsi_relationship for key, attribute in self.attributes.items() if attribute.ohdsi_relationship}
def attribute_by_relationship(self) -> Dict[str, str]:
"""OHDSI ``relationship_id`` → pipeline attribute key."""
return {relationship: key for key, relationship in self.relationship_by_attribute().items()}
|
snomed_relationships
property
OHDSI relationship_id of every configured attribute.
Used to fetch reference-example attributes and to build the snomed_attribute table.
attribute_by_relationship()
OHDSI relationship_id → pipeline attribute key.
Source code in src/ariadne/utils/settings.py
| def attribute_by_relationship(self) -> Dict[str, str]:
"""OHDSI ``relationship_id`` → pipeline attribute key."""
return {relationship: key for key, relationship in self.relationship_by_attribute().items()}
|
relationship_by_attribute()
Pipeline attribute key (e.g. "finding_site") → OHDSI relationship_id.
Source code in src/ariadne/utils/settings.py
| def relationship_by_attribute(self) -> Dict[str, str]:
"""Pipeline attribute key (e.g. ``"finding_site"``) → OHDSI ``relationship_id``."""
return {key: attribute.ohdsi_relationship for key, attribute in self.attributes.items() if attribute.ohdsi_relationship}
|
relationship_type_ids()
OHDSI relationship_id (e.g. "Has finding site") → SNOMED attribute concept ID (RF2 typeId).
Source code in src/ariadne/utils/settings.py
428
429
430
431
432
433
434 | def relationship_type_ids(self) -> Dict[str, int]:
"""OHDSI ``relationship_id`` (e.g. ``"Has finding site"``) → SNOMED attribute concept ID (RF2 ``typeId``)."""
return {
attribute.ohdsi_relationship: attribute.attribute_id
for attribute in self.attributes.values()
if attribute.ohdsi_relationship and attribute.attribute_id
}
|
IndexBuildConfig
dataclass
Batch/index build settings used by the hierarchy pgvector builder.
Source code in src/ariadne/utils/settings.py
330
331
332
333
334
335
336
337
338 | @dataclass
class IndexBuildConfig:
"""Batch/index build settings used by the hierarchy pgvector builder."""
embedding_batch_size: int = 500
embedding_cache_folder: str = "data/hierarchy_embedding_cache"
def __post_init__(self) -> None:
self.embedding_cache_folder = resolve_path(self.embedding_cache_folder)
|
LlmMapperSettings
dataclass
Everything :class:LlmMapper needs.
Source code in src/ariadne/utils/settings.py
208
209
210
211
212
213
214
215
216
217 | @dataclass
class LlmMapperSettings:
"""Everything :class:`LlmMapper` needs."""
llm_mapper_responses_folder: str = "data/llm_mapper_responses"
context: ConceptContextSettings = field(default_factory=ConceptContextSettings)
system_prompts: List[str] = field(default_factory=list)
def __post_init__(self) -> None:
self.llm_mapper_responses_folder = resolve_path(self.llm_mapper_responses_folder)
|
MappingPerConceptClassSettings
dataclass
Per-concept-class settings used by the drug-mapping pipeline.
Source code in src/ariadne/utils/settings.py
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259 | @dataclass
class MappingPerConceptClassSettings:
"""Per-concept-class settings used by the drug-mapping pipeline."""
verbatim_mapping: VerbatimMappingSettings = field(default_factory=VerbatimMappingSettings)
hecate_search: Optional[HecateSearchSettings] = None
pgvector_search: Optional[PgvectorSearchSettings] = None
tfidf_search: Optional[TfidfSearchSettings] = None
llm_mapping: LlmMapperSettings = field(default_factory=LlmMapperSettings)
def __post_init__(self) -> None:
configured_searchers = [
name
for name, value in (
("hecate_search", self.hecate_search),
("pgvector_search", self.pgvector_search),
("tfidf_search", self.tfidf_search),
)
if value is not None
]
if len(configured_searchers) != 1:
raise ValueError(
"Exactly one vector search block must be configured per concept class: "
"hecate_search, pgvector_search, or tfidf_search. "
f"Configured: {configured_searchers or 'none'}."
)
|
MrcmSettings
dataclass
SNOMED CT MRCM rules used for role grouping and validation.
Rules are read from the RF2 MRCM refset snapshot files in folder, limited
to the configured domains (and the sub-domains listed there) and
content_types (pre-coordinated only by default).
Source code in src/ariadne/utils/settings.py
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398 | @dataclass
class MrcmSettings:
"""SNOMED CT MRCM rules used for role grouping and validation.
Rules are read from the RF2 MRCM refset snapshot files in ``folder``, limited
to the configured ``domains`` (and the sub-domains listed there) and
``content_types`` (pre-coordinated only by default).
"""
folder: str = "data/mrcm"
content_types: List[int] = field(default_factory=lambda: [723596005, 723594008])
domains: Dict[str, int] = field(default_factory=dict)
default_domain: str = ""
grouping: RoleGroupingConfig = field(default_factory=RoleGroupingConfig)
def __post_init__(self) -> None:
self.folder = resolve_path(self.folder)
|
ParentSelectionConfig
dataclass
Stated-parent selection by primitive-ancestor consensus of nearest SNOMED neighbours.
Candidate parents are the primitive descendants of root_concept_id. The root itself is the
fallback parent.
Source code in src/ariadne/utils/settings.py
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307 | @dataclass
class ParentSelectionConfig:
"""Stated-parent selection by primitive-ancestor consensus of nearest SNOMED neighbours.
Candidate parents are the primitive descendants of ``root_concept_id``. The root itself is the
fallback parent.
"""
# Nearest standard SNOMED concepts that vote on the parent.
num_neighbours: int = 10
# Concepts retrieved per term before exclusions; at least num_neighbours.
candidate_pool_size: int = 40
min_similarity: float = 0.6
# Minimum similarity-weighted share of neighbours that must sit under a candidate parent.
min_support: float = 0.5
max_parents: int = 2
# OMOP concept_id of the root of the allowed parent set (441840 = Clinical finding).
root_concept_id: int = 441840
# OMOP concept_id of the "Primitive" definition status (900000000000074008).
primitive_status_concept_id: int = 40642538
# Evaluation guard: drop the source concept and its descendants from neighbours and parents.
exclude_source_descendants: bool = True
# Concurrent neighbour searches (one database connection each).
max_workers: int = 4
neighbour_cache_file: str = "data/notebook_results/hierarchy_parent_selection_neighbours.json"
def __post_init__(self) -> None:
if self.num_neighbours < 1:
raise ValueError("parent_selection.num_neighbours must be >= 1.")
if self.candidate_pool_size < self.num_neighbours:
raise ValueError("parent_selection.candidate_pool_size must be >= num_neighbours.")
if not 0.0 < self.min_support <= 1.0:
raise ValueError("parent_selection.min_support must be in (0, 1].")
if self.max_parents < 1:
raise ValueError("parent_selection.max_parents must be >= 1.")
if self.neighbour_cache_file:
self.neighbour_cache_file = resolve_path(self.neighbour_cache_file)
|
PgvectorSearchSettings
dataclass
Bases: VectorSearchSettings
Settings used by :class:PgvectorConceptSearcher.
Source code in src/ariadne/utils/settings.py
168
169
170
171
172
173
174 | @dataclass
class PgvectorSearchSettings(VectorSearchSettings):
"""Settings used by :class:`PgvectorConceptSearcher`."""
substrings_to_remove: List[str] = field(default_factory=list)
include_synonyms: bool = True
include_mapped_terms: bool = True
|
PromptsConfig
dataclass
Prompt templates for hierarchy extraction and candidate selection.
Source code in src/ariadne/utils/settings.py
| @dataclass
class PromptsConfig:
"""Prompt templates for hierarchy extraction and candidate selection."""
extraction: str = ""
selection: str = ""
|
RetrievalConfig
dataclass
Retrieval-stage hyper-parameters for hierarchy extraction.
Source code in src/ariadne/utils/settings.py
262
263
264
265
266
267
268 | @dataclass
class RetrievalConfig:
"""Retrieval-stage hyper-parameters for hierarchy extraction."""
num_reference_examples: int = 5
top_k_per_category: int = 20
hnsw_ef_search: int = 200
|
RoleGroupingConfig
dataclass
Role-group composition rules (SNOMED CT Editorial Guide; not encoded in the MRCM refsets).
Attributes:
| Name |
Type |
Description |
self_grouped |
List[str]
|
Attribute keys that must be alone in their role group.
|
clusters |
Dict[str, List[str]]
|
Named sets of attribute keys that may share a role group.
Attributes from different clusters never share a group.
|
llm_grouped_clusters |
List[str]
|
Clusters whose role groups the LLM proposes
explicitly (role_groups in the extraction/selection output).
|
requires |
Dict[str, str]
|
{attribute: partner} — an attribute that is only valid
in a group that also contains partner.
|
Source code in src/ariadne/utils/settings.py
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379 | @dataclass
class RoleGroupingConfig:
"""Role-group composition rules (SNOMED CT Editorial Guide; not encoded in the MRCM refsets).
Attributes:
self_grouped: Attribute keys that must be alone in their role group.
clusters: Named sets of attribute keys that may share a role group.
Attributes from different clusters never share a group.
llm_grouped_clusters: Clusters whose role groups the LLM proposes
explicitly (``role_groups`` in the extraction/selection output).
requires: ``{attribute: partner}`` — an attribute that is only valid
in a group that also contains *partner*.
"""
self_grouped: List[str] = field(default_factory=list)
clusters: Dict[str, List[str]] = field(default_factory=dict)
llm_grouped_clusters: List[str] = field(default_factory=list)
requires: Dict[str, str] = field(default_factory=dict)
@property
def enabled(self) -> bool:
return bool(self.self_grouped or self.clusters)
def cluster_of(self, attribute_key: str) -> str | None:
for name, members in self.clusters.items():
if attribute_key in members:
return name
return None
def llm_grouped_keys(self) -> list[str]:
return [k for name in self.llm_grouped_clusters for k in self.clusters.get(name, [])]
|
TermCleanerSettings
dataclass
Everything :class:TermCleaner needs.
Source code in src/ariadne/utils/settings.py
124
125
126
127
128
129
130 | @dataclass
class TermCleanerSettings:
"""Everything :class:`TermCleaner` needs."""
system_prompt: str = ""
and_or_rewrite: AndOrRewriteSettings = field(default_factory=AndOrRewriteSettings)
max_workers: int = 4
|
TfidfSearchSettings
dataclass
Bases: VectorSearchSettings
Settings used by :class:TfidfConceptSearcher.
Source code in src/ariadne/utils/settings.py
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191 | @dataclass
class TfidfSearchSettings(VectorSearchSettings):
"""Settings used by :class:`TfidfConceptSearcher`."""
terms_folder: str = "data/terms_tfidf"
tfidf_index_file: str = "data/tfidf_index.pkl"
download_batch_size: int = 100_000
log_folder: str = "logs"
include_synonyms: bool = True
substrings_to_remove: List[str] = field(default_factory=list)
def __post_init__(self) -> None:
self.terms_folder = resolve_path(self.terms_folder)
self.tfidf_index_file = resolve_path(self.tfidf_index_file)
self.log_folder = resolve_path(self.log_folder)
|
VectorSearchSettings
dataclass
Base settings shared by all concept searchers.
Source code in src/ariadne/utils/settings.py
| @dataclass
class VectorSearchSettings:
"""Base settings shared by all concept searchers."""
max_candidates: int = 25
filter: ConceptFilterSettings = field(default_factory=ConceptFilterSettings)
|
VerbatimMappingSettings
dataclass
Everything :func:download_terms, :class:VocabVerbatimTermMapper, and
:class:TermNormalizer need.
Source code in src/ariadne/utils/settings.py
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150 | @dataclass
class VerbatimMappingSettings:
"""Everything :func:`download_terms`, :class:`VocabVerbatimTermMapper`, and
:class:`TermNormalizer` need."""
terms_folder: str = "data/terms"
verbatim_mapping_index_file: str = "data/verbatim_mapping_index.pkl"
download_batch_size: int = 100_000
log_folder: str = "logs"
substrings_to_remove: List[str] = field(default_factory=list)
include_synonyms: bool = True
preferred_vocabulary_ids: List[str] = field(default_factory=list)
filter: ConceptFilterSettings = field(default_factory=ConceptFilterSettings)
def __post_init__(self) -> None:
self.terms_folder = resolve_path(self.terms_folder)
self.verbatim_mapping_index_file = resolve_path(self.verbatim_mapping_index_file)
self.log_folder = resolve_path(self.log_folder)
|
build_dataclass(cls, data)
Recursively build a dataclass instance from a plain dict.
Source code in src/ariadne/utils/settings.py
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65 | def build_dataclass(cls: Type[Any], data: Dict[str, Any] | None) -> Any:
"""Recursively build a dataclass instance from a plain dict."""
if data is None:
data = {}
if not is_dataclass(cls):
return data
kw: dict[str, Any] = {}
# Resolve string annotations to actual types
try:
resolved_hints = get_type_hints(cls)
except Exception:
resolved_hints = {}
for f in fields(cls):
if f.name not in data:
continue
value = data[f.name]
# Use resolved type hint if available, else fall back to f.type
raw_type = resolved_hints.get(f.name, f.type)
# Unwrap Optional[X] / X | None to get the inner type
origin = getattr(raw_type, "__origin__", None)
if origin is not None:
args = getattr(raw_type, "__args__", ())
# For Optional[X], args is (X, NoneType); pick the non-None arg
non_none = [a for a in args if a is not type(None)]
raw_type = non_none[0] if non_none else raw_type
if is_dataclass(raw_type) and isinstance(value, dict):
kw[f.name] = build_dataclass(raw_type, value)
else:
kw[f.name] = value
return cls(**kw)
|
serialize_dataclass(obj)
Recursively serialize a dataclass (or list/dict of dataclasses) to plain dicts.
Source code in src/ariadne/utils/settings.py
68
69
70
71
72
73
74
75
76
77
78
79
80
81 | def serialize_dataclass(obj: Any) -> Any:
"""Recursively serialize a dataclass (or list/dict of dataclasses) to plain dicts."""
if is_dataclass(obj):
result = {}
for f in fields(obj):
value = getattr(obj, f.name)
result[f.name] = serialize_dataclass(value)
return result
elif isinstance(obj, dict):
return {k: serialize_dataclass(v) for k, v in obj.items()}
elif isinstance(obj, list):
return [serialize_dataclass(item) for item in obj]
else:
return obj
|