Registry Runtime

The registry runtime compiles declarative semantic templates into execution-ready objects. It is the layer between YAML authoring and ETL/analytics code.

The primary entrypoint is OmopSemanticEngine. Everything else on this page is accessible through it.

Quick example

from omop_semantics.runtime import OmopSemanticEngine
from omop_semantics import INSTANCE_DIR, SCHEMA_DIR

engine = OmopSemanticEngine.from_yaml_paths(
    registry_paths=[INSTANCE_DIR / "demographic.yaml"],
    profile_paths=[INSTANCE_DIR / "profile_groups.yaml"],
)

# Compiled template access
tpl = engine.registry_runtime.get_runtime("Language spoken")
tpl.cdm_profile.cdm_table     # → "observation"
tpl.cdm_profile.value_slot    # → "value_as_concept_id"
tpl.entity_concept_ids        # → {4052785}
tpl.value_concept_ids         # → {4182347}

# Membership tests
engine.registry_runtime.allows_concept("Language spoken", 4052785)  # → True
engine.registry_runtime.allows_value("Language spoken", 4182347)    # → True

# Iterate by role
for tpl in engine.registry_runtime.by_role_runtime("demographic"):
    print(tpl.name, tpl.cdm_profile.cdm_table)

Class responsibilities

OmopSemanticEngine is the entry point. It owns the resolver, compiler, and registry runtime as attributes. Use from_yaml_paths() for shipped YAML files or from_instances() for programmatic fragment construction.

OmopRegistryRuntime provides indexed, compiled access to a RegistryFragment. It compiles on first access and caches the result. Also provides diff() and merge() for comparing and combining registries.

OmopSemanticResolver turns a semantic object (OmopConcept, OmopGroup, OmopEnum, OmopValueSet) into a set[int]. Each type has a specific resolution: - OmopConcept → {concept_id} - OmopEnum → set of all member concept_ids - OmopGroup → set of all anchor (parent_concepts) concept_ids - OmopValueSet → union of its members' resolved sets

OmopTemplateRuntime compiles a single OmopTemplate into a CompiledTemplate (TypedDict) by invoking the resolver on its entity_concept and value_concept.

RuntimeTemplate is an attribute-based view over a CompiledTemplate. Access tpl.name, tpl.role, tpl.cdm_profile, tpl.entity_concept_ids, tpl.value_concept_ids directly.

SemanticProfileRuntime provides read-only access to raw profile object dictionaries loaded from symbolic YAML files. Used for documentation and inspection, not for ETL execution. Available via engine.profile_runtime when profile_paths are provided.

API reference

High-level entry point for working with OMOP semantic registries and profiles.

This class wires together: - the semantic resolver (concept/group/enum → OMOP concept_ids), - the template compiler runtime, - the registry runtime (indexed, compiled templates), - and the optional semantic profile runtime (symbolic/profile view).

It is the main high-level entrypoint for shipped registry instance files, ETL routing, and documentation/rendering layers.

Construct a semantic engine from an already-loaded registry fragment.

Parameters:

Name	Type	Description	Default
registry_fragment	RegistryFragment	Declarative registry fragment defining OMOP semantic templates and groups.	required
profile_objects	dict[str, dict] | None	Optional mapping of symbolic profile objects (e.g. OmopTemplate, OmopGroup, OmopConcept definitions) used for documentation and inspection.	None

docs_html

docs_html() -> Html

Render combined HTML documentation for the registry and profiles.

Returns:

Type	Description
Html	HTML block containing registry tables and (if available) profile documentation.

from_instances classmethod

from_instances(fragment: RegistryFragment) -> OmopSemanticEngine

Construct a semantic engine directly from an in-memory RegistryFragment.

This is useful in tests or programmatic composition of registry fragments.

Parameters:

Name	Type	Description	Default
fragment	RegistryFragment	Registry fragment containing semantic templates.	required

Returns:

Type	Description
OmopSemanticEngine	Initialised semantic engine.

from_yaml_paths classmethod

from_yaml_paths(registry_paths: Iterable[Path], profile_paths: Iterable[Path] = (), *, profiles_path: Path | None = None) -> OmopSemanticEngine

Construct a semantic engine from YAML registry and profile files.

Multiple registry fragments are merged into a single runtime registry. Profile YAML files are loaded into a symbolic profile namespace for documentation and inspection.

Registry files that store cdm_profile as a string name (e.g. observation_simple) are automatically expanded against the CDM profile catalogue before validation.

Parameters:

Name	Type	Description	Default
registry_paths	Iterable[Path]	Paths to registry fragment YAML files.	required
profile_paths	Iterable[Path]	Optional paths to symbolic profile/group YAML files that should be exposed through profile_runtime.	()
profiles_path	Path | None	Path to the CDM profile catalogue YAML. Defaults to the shipped profiles.yaml when not provided.	None

Returns:

Type	Description
OmopSemanticEngine	Initialised semantic engine with merged registry and profiles.

Runtime interface over a registry of OMOP semantic templates.

This class provides indexed, compiled access to a RegistryFragment, allowing templates to be retrieved by name, grouped by role, or iterated over in compiled form for use in ETL pipelines and semantic execution layers.

Compilation is cached to avoid repeated semantic resolution and to provide stable runtime objects during pipeline execution.

Initialise the registry runtime for a semantic registry fragment.

Parameters:

Name	Type	Description	Default
fragment	RegistryFragment	Registry fragment containing declarative OMOP semantic templates.	required
template_runtime	OmopTemplateRuntime	Compiler used to convert templates into execution-ready form.	required

roles property

roles: Set[str]

Get the set of all semantic roles defined in the registry.

Returns:

Type	Description
Set[str]	Unique set of semantic roles (e.g. 'demographic', 'staging') present in the registry.

template_names property

template_names: Set[str]

Get the set of all template names defined in the registry.

Returns:

Type	Description
Set[str]	Unique set of template names present in the registry.

allows_concept

allows_concept(template_name: str, concept_id: int) -> bool

Return True if concept_id is allowed in the template's entity slot.

allows_value

allows_value(template_name: str, concept_id: int) -> bool

Return True if concept_id is allowed in the template's value slot.

by_label

by_label(label: str) -> RuntimeTemplate

Retrieve a compiled template by case-insensitive name.

This is the case-insensitive counterpart to get(), useful when template names come from user input or external sources where casing may not be known precisely.

Parameters:

Name	Type	Description	Default
label	str	Template name to look up (case-insensitive).	required

Returns:

Type	Description
RuntimeTemplate	Compiled runtime view of the matching template.

Raises:

Type	Description
KeyError	If no template with the given name exists.

by_role

by_role(role: str) -> list[CompiledTemplate]

Retrieve all compiled templates for a given semantic role.

Parameters:

Name	Type	Description	Default
role	str	Semantic role to filter by (e.g. 'demographic', 'staging').	required

Returns:

Type	Description
list[CompiledTemplate]	List of compiled templates associated with the given role.

by_role_runtime

by_role_runtime(role: str) -> list[RuntimeTemplate]

Return all compiled templates for a role as RuntimeTemplate objects.

compile_all

compile_all(role: str | None = None) -> list[CompiledTemplate]

Retrieve all compiled templates, optionally filtered by role.

Parameters:

Name	Type	Description	Default
role	str | None	Optional semantic role to filter templates.	None

Returns:

Type	Description
list[CompiledTemplate]	List of compiled templates in the registry.

compile_index

compile_index() -> None

Compile and index all templates in the registry.

This method resolves all semantic objects and caches the compiled templates for fast lookup by name or role during runtime execution.

diff

diff(other: OmopRegistryRuntime) -> RegistryRuntimeDiff

Compute the difference between this registry and another.

Compares compiled output — changes in the underlying YAML that do not affect resolved concept IDs, profiles, or roles will not appear here.

Parameters:

Name	Type	Description	Default
other	OmopRegistryRuntime	Registry to compare against.	required

Returns:

Type	Description
RegistryRuntimeDiff	Summary of added, removed, and changed templates.

get

get(name: str) -> CompiledTemplate

Retrieve a compiled template by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the semantic template.	required

Returns:

Type	Description
CompiledTemplate	Compiled representation of the named template.

Raises:

Type	Description
KeyError	If no template with the given name exists.
RuntimeError	If compilation has failed.

get_runtime

get_runtime(name: str) -> RuntimeTemplate

Retrieve a compiled template and wrap it as a RuntimeTemplate.

This is the most ergonomic lookup when you want attribute access such as tpl.cdm_profile or tpl.entity_concept_ids.

iter_templates

iter_templates(role: str | None = None)

Iterate over declarative templates in the registry.

Parameters:

Name	Type	Description	Default
role	str | None	Optional semantic role to filter templates (e.g. 'demographic').	None

Yields:

Type	Description
OmopTemplate	Declarative semantic templates from the registry.

merge

merge(other: OmopRegistryRuntime, *, strategy: str = 'prefer_self') -> OmopRegistryRuntime

Merge another registry into this one and return the combined result.

Template name conflicts are resolved by strategy:

• "prefer_self" — keep this registry's template on conflict (default)
• "prefer_other" — use the other registry's template on conflict
• "error" — raise ValueError on any name conflict

The returned registry contains all templates from both, flattened into a single organisational group. Group structure from the originals is not preserved in the merged result.

Parameters:

Name	Type	Description	Default
other	OmopRegistryRuntime	Registry to merge with.	required
strategy	str	Conflict resolution strategy.	'prefer_self'

Returns:

Type	Description
OmopRegistryRuntime	New registry containing templates from both, with conflicts resolved.

Raises:

Type	Description
ValueError	If strategy is "error" and conflicting template names exist.

to_compiled_html

to_compiled_html(role: str | None = None) -> Html

Render the compiled registry as an HTML table.

This view displays the execution-ready form of semantic templates, where semantic objects have been resolved to concrete OMOP concept IDs. It is useful for inspecting the concrete OMOP mappings that will be used by ETL pipelines or query builders.

Parameters:

Name	Type	Description	Default
role	str | None	Optional semantic role to filter compiled templates. If provided, only compiled templates with this role are rendered.	None

Returns:

Type	Description
Html	HTML representation of the compiled templates suitable for display in Jupyter or documentation.

Examples:

Inspect the compiled demographic mappings:

>>> engine.registry_runtime.to_compiled_html(role="demographic")

Compare declarative vs compiled views:

>>> engine.registry_runtime.to_html()
>>> engine.registry_runtime.to_compiled_html()

to_html

to_html(role: str | None = None) -> Html

Render the declarative registry fragment as an HTML table.

This view displays the semantic templates grouped by registry group, showing their role, CDM profile, and associated semantic objects (entity and value concepts). It is intended for documentation, debugging, and interactive exploration in notebooks.

Parameters:

Name	Type	Description	Default
role	str | None	Optional semantic role to filter templates (e.g. 'demographic', 'staging'). If provided, only templates with this role are rendered.	None

Returns:

Type	Description
Html	HTML representation of the registry suitable for display in Jupyter.

Examples:

Render the full registry in a notebook:

>>> engine.registry_runtime.to_html()

Render only demographic templates:

>>> engine.registry_runtime.to_html(role="demographic")

validate

validate() -> None

Validate the registry for internal consistency.

Checks performed: - no duplicate template names within the registry - every template declares an entity_concept

Raises:

Type	Description
ValueError	If any issues are found, with all problems listed together.

Attribute-based runtime view over a compiled OMOP template.

This is a thin wrapper around CompiledTemplate to provide ergonomic access in ETL pipelines and execution code.

Runtime compiler for OMOP semantic templates.

This class transforms declarative OmopTemplate instances into compiled, execution-ready representations by resolving semantic objects into concrete OMOP concept identifiers using an OmopSemanticResolver.

The output of this layer is intended to be consumed directly by ETL pipelines, query builders, or analytics workflows.

Create a runtime compiler bound to a semantic resolver.

Parameters:

Name	Type	Description	Default
resolver	OmopSemanticResolver	Resolver used to ground semantic objects into OMOP concept IDs.	required

compile

compile(tpl: OmopTemplate) -> CompiledTemplate

Compile a declarative OMOP template into a runtime representation.

Parameters:

Name	Type	Description	Default
tpl	OmopTemplate	Declarative semantic template describing how concepts map to OMOP CDM slots.	required

Returns:

Type	Description
CompiledTemplate	Execution-ready representation of the template, with resolved concept IDs.

Raises:

Type	Description
ValueError	If the template is missing required semantic components.

Resolves OMOP semantic objects into concrete OMOP concept identifiers.

This class provides the semantic grounding layer between declarative semantic objects (e.g. OmopConcept, OmopGroup, OmopEnum) and the executable representation required by OMOP-based ETL and query logic.

The resolver is intentionally minimal and explainable: - OmopConcept resolves to its single concept_id - OmopEnum resolves to the set of concept_ids of its members - OmopGroup resolves to the anchor (parent) concept_ids of the group - OmopValueSet resolves to the union of its members' resolved concept_ids

This library is not database-backed, so descendant expansion and vocabulary graph traversal belong in downstream logic rather than in this resolver.

resolve

resolve(obj: OmopSemanticObject) -> set[int]

Resolve a semantic object into a set of OMOP concept identifiers.

Parameters:

Name	Type	Description	Default
obj	OmopSemanticObject	A semantic object describing permissible OMOP concepts.	required

Returns:

Type	Description
set[int]	A set of OMOP concept_ids derived from the semantic object.

Raises:

Type	Description
ValueError	If a required concept_id is missing.
TypeError	If the semantic object type is unsupported.

Runtime interface over semantic profile objects.

This class provides lightweight, read-only access to profile-layer semantic objects (e.g. RegistryGroup, OmopTemplate, OmopGroup, OmopConcept) loaded from profile YAML files. It is primarily intended for documentation, inspection, and UI / notebook exploration rather than execution-time ETL logic.

Initialise the profile runtime.

Parameters:

Name	Type	Description	Default
objects	dict[str, dict] | list[dict[str, dict]]	Mapping of profile object names to raw profile dictionaries, or a list of such mappings (which will be merged). Later entries take precedence when merging.	required

explain

explain(name: str) -> str

Return a short human-readable explanation for a profile object.

This is typically sourced from the notes field in the profile definition and is intended for UI / documentation display.

Parameters:

Name	Type	Description	Default
name	str	Name of the profile object.	required

Returns:

Type	Description
str	Notes or description associated with the object, or a fallback message if none is provided.

Raises:

Type	Description
KeyError	If no profile object with the given name exists.

explain_html

explain_html(name: str) -> Html

Render a single profile object as a simple key/value HTML table.

Parameters:

Name	Type	Description	Default
name	str	Name of the profile object to explain.	required

Returns:

Type	Description
Html	Rendered HTML block showing all fields on the object.

get

get(name: str) -> dict

Retrieve a profile object by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the profile object.	required

Returns:

Type	Description
dict	Raw profile object dictionary.

Raises:

Type	Description
KeyError	If no profile object with the given name exists.

list_groups

list_groups() -> dict[str, dict]

List all RegistryGroup objects defined in the profiles.

Returns:

Type	Description
dict[str, dict]	Mapping of group name to raw RegistryGroup profile dictionaries.

list_semantic_objects

list_semantic_objects() -> dict[str, dict]

List all semantic objects (OmopGroup, OmopConcept, OmopEnum) defined in the profiles.

Returns:

Type	Description
dict[str, dict]	Mapping of object name to raw profile dictionaries for semantic objects.

list_templates

list_templates() -> dict[str, dict]

List all OmopTemplate objects defined in the profiles.

Returns:

Type	Description
dict[str, dict]	Mapping of template name to raw OmopTemplate profile dictionaries.

to_html

to_html() -> Html

Render all loaded semantic profile objects as HTML documentation.

This produces a lightweight, human-readable overview of: - Registry groups - Templates - Semantic objects (groups, concepts, enums)

Returns:

Type	Description
Html	Rendered HTML block suitable for notebook display.