Registry Runtime

This page documents the core runtime classes used to compile and apply OMOP semantic templates in ETL pipelines.

OmopSemanticEngine

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 intended to be the main object used by ETL pipelines, query builders, 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] = ()) -> 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 and merged into a single symbolic profile namespace for documentation and inspection.

Parameters:

Name	Type	Description	Default
registry_paths	Iterable[Path]	Paths to registry fragment YAML files.	required
profile_paths	Iterable[Path]	Optional paths to profile/symbol YAML files.	()

Returns:

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

OmopRegistryRuntime

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.

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.

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.

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.

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.

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")

RuntimeTemplate

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.

OmopTemplateRuntime

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.

OmopSemanticResolver

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

This library is not database-backed so the resolved group hierarchies need to be resolved in downstream logic.

TODO: allow this class to extended with full resolution logic without introducing dependencies on database connections or external services.

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.

SemanticProfileRuntime

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.