omop-semantics 0.2.2__tar.gz → 0.3.0__tar.gz

{omop_semantics-0.2.2 → omop_semantics-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: omop-semantics
-Version: 0.2.2
+Version: 0.3.0
 Summary: Define, validate, and use schema-backed semantic conventions for OMOP CDM
 Author: gkennos
 Author-email: gkennos <georgina.kennedy@unsw.edu.au>
@@ -17,7 +17,7 @@ Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
 Requires-Dist: mypy>=1.8 ; extra == 'dev'
 Requires-Dist: ruff>=0.4 ; extra == 'dev'
 Requires-Dist: rich>=13.0 ; extra == 'dev'
-Requires-Dist: tornado>=6.5.5 ; extra == 'dev'
+Requires-Dist: tornado>=6.5.7 ; extra == 'dev'
 Requires-Dist: pygments>=2.20.0 ; extra == 'dev'
 Requires-Dist: mkdocs-material>=9.7.6 ; extra == 'docs'
 Requires-Dist: mkdocstrings-python>=2.0.1 ; extra == 'docs'

{omop_semantics-0.2.2 → omop_semantics-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omop-semantics"
-version = "0.2.2"
+version = "0.3.0"
 description = "Define, validate, and use schema-backed semantic conventions for OMOP CDM"
 readme = "README.md"
 authors = [
@@ -28,7 +28,7 @@ dev = [
   "mypy>=1.8",
   "ruff>=0.4",
   "rich>=13.0",
-  "tornado>=6.5.5",
+  "tornado>=6.5.7",
   "pygments>=2.20.0"
 ]
 docs = [

{omop_semantics-0.2.2 → omop_semantics-0.3.0}/src/omop_semantics/runtime/__init__.py

@@ -20,6 +20,26 @@ from .resolver import (
     OmopSemanticObject,
     SemanticProfileRuntime
 )
+from .projection import (
+    ProjectionProfileRuntime,
+    RuntimeProjectionProfile,
+    ProjectedOutputRow,
+    ProjectedOutputLink,
+    ProjectedOutputBundle,
+    SuppressedRow,
+)
+from .output_definitions import (
+    ContextFieldRef,
+    OutputRowProjection,
+    OutputLinkRule,
+    OutputDefinition,
+    CompiledOutputDefinition,
+    OutputDefinitionRuntime,
+    DerivationRule,
+    NO_DEFAULT,
+    SpecialValuePolicy,
+    SUPPRESSION_MODES,
+)
 from typing import TYPE_CHECKING
 
 
@@ -39,4 +59,20 @@ __all__ = [
     "render_registry_fragment",
     "render_profile_groups",
     "SemanticProfileRuntime",
+    "ProjectionProfileRuntime",
+    "RuntimeProjectionProfile",
+    "ProjectedOutputRow",
+    "ProjectedOutputLink",
+    "ProjectedOutputBundle",
+    "SuppressedRow",
+    "ContextFieldRef",
+    "OutputRowProjection",
+    "OutputLinkRule",
+    "OutputDefinition",
+    "CompiledOutputDefinition",
+    "OutputDefinitionRuntime",
+    "DerivationRule",
+    "NO_DEFAULT",
+    "SpecialValuePolicy",
+    "SUPPRESSION_MODES",
 ]

{omop_semantics-0.2.2 → omop_semantics-0.3.0}/src/omop_semantics/runtime/instance_loader.py

@@ -45,6 +45,13 @@ def interpolate_profiles(group: dict, profiles: dict[str, OmopCdmProfile]) -> No
             "cdm_table": profile.cdm_table,
             "concept_slot": profile.concept_slot,
             "value_slot": profile.value_slot,
+            "unit_slot": profile.unit_slot,
+            "operator_slot": profile.operator_slot,
+            "modifier_slot": profile.modifier_slot,
+            "extra_concept_slots": profile.extra_concept_slots,
+            "numeric_slots": profile.numeric_slots,
+            "string_slots": profile.string_slots,
+            "reference_slots": profile.reference_slots,
         }
 
         member.pop("concept_slot", None)

omop_semantics-0.3.0/src/omop_semantics/runtime/output_definitions.py

@@ -0,0 +1,469 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Mapping, Sequence
+
+from .projection import (
+    ProjectedOutputBundle,
+    ProjectedOutputLink,
+    ProjectedOutputRow,
+    ProjectionProfileRuntime,
+    RuntimeProjectionProfile,
+    SuppressedRow,
+)
+
+
+@dataclass(frozen=True)
+class ContextFieldRef:
+    """
+    Reference to a value in the projection context.
+
+    The path is dot-delimited, for example:
+
+    - `grounded.concept_id`
+    - `source.numeric_value`
+    - `modifiers.intent_concept_id`
+    """
+
+    path: str
+
+
+BindingValue = Any | ContextFieldRef
+
+
+class _NoDefault:
+    def __repr__(self) -> str:
+        return "NO_DEFAULT"
+
+
+NO_DEFAULT: Any = _NoDefault()
+"""Sentinel distinguishing "no default configured" from a configured default of `None`."""
+
+
+@dataclass(frozen=True)
+class DerivationRule:
+    """
+    Resolve one row's slot value from a source field other than the one that
+    grounded the row's entity concept, via a source-code lookup — with an
+    explicit escape hatch for codes that should suppress the row entirely.
+
+    This is the n:1 fan-in counterpart to `field_bindings` (which only ever
+    read from the same context a row's own entity concept was grounded from).
+    The canonical case is a diagnosis paired with a separately-collected
+    role/status field (e.g. Primary/Contributing/Non-contributing): the role
+    field is never grounded on its own, and its raw code either resolves
+    `condition_status_concept_id` via `code_map` or, for "Non-contributing",
+    drops the record entirely via `suppress_codes`.
+    """
+
+    target_row: str
+    target_slot: str
+    source_field: ContextFieldRef
+    code_map: Mapping[str, Any] = field(default_factory=dict)
+    suppress_codes: frozenset[str] = frozenset()
+    default: Any = NO_DEFAULT
+
+
+SUPPRESSION_MODES = frozenset({"drop", "fail", "keep_as_value", "keep_as_modifier"})
+"""Recognized `SpecialValuePolicy.suppression_mode` values.
+
+Only `drop` and `fail` have runtime behavior today — both are the degenerate,
+single-field case validated against real data (a "meets criteria for X" Yes/No
+item, where the negative answer carries no positive clinical content of its
+own). `keep_as_value` and `keep_as_modifier` are named here per the schema
+proposal so definitions can be authored against a stable enum, but they raise
+`NotImplementedError` if actually triggered — there is no validated use case
+yet for what they should bind.
+"""
+
+
+@dataclass(frozen=True)
+class SpecialValuePolicy:
+    """
+    Row-level suppression (or other handling) driven by the row's *own*
+    source value — the counterpart to `DerivationRule`, which reads a
+    different source field. Attach to `OutputRowProjection.special_value_policy`.
+
+    The canonical case is a Yes/No field phrased "meets criteria for X": Yes
+    grounds the row normally, No means nothing should be written for it. There
+    is no sibling field to consult, so no `DerivationRule` is involved — the
+    same value used to ground the row is checked against
+    `allowed_special_values`.
+    """
+
+    source_field: ContextFieldRef
+    allowed_special_values: frozenset[str] = frozenset()
+    suppression_mode: str = "drop"
+
+
+@dataclass(frozen=True)
+class OutputRowProjection:
+    """
+    Declarative row projection definition.
+    """
+
+    row_id: str
+    profile_name: str
+    field_bindings: Mapping[str, BindingValue] = field(default_factory=dict)
+    defaults: Mapping[str, Any] = field(default_factory=dict)
+    required: bool = True
+    special_value_policy: SpecialValuePolicy | None = None
+
+
+@dataclass(frozen=True)
+class OutputLinkRule:
+    """
+    Declarative relationship between projected rows.
+    """
+
+    source_row: str
+    target_row: str
+    relationship_type: str
+    source_field: str | None = None
+    target_field: str | None = None
+
+
+@dataclass(frozen=True)
+class OutputDefinition:
+    """
+    Minimal programmatic output definition.
+
+    This is intentionally additive and runtime-only for the first execution
+    slice. It provides enough structure to compile and deterministically
+    project rows before a dedicated YAML/schema authoring surface is added.
+    """
+
+    name: str
+    role: str
+    template_names: tuple[str, ...] = ()
+    row_projections: tuple[OutputRowProjection, ...] = ()
+    link_rules: tuple[OutputLinkRule, ...] = ()
+    derivation_rules: tuple[DerivationRule, ...] = ()
+    notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class CompiledRowProjection:
+    row_id: str
+    profile: RuntimeProjectionProfile
+    field_bindings: Mapping[str, BindingValue]
+    defaults: Mapping[str, Any]
+    required: bool = True
+    special_value_policy: SpecialValuePolicy | None = None
+
+
+@dataclass(frozen=True)
+class CompiledOutputDefinition:
+    name: str
+    role: str
+    template_names: tuple[str, ...]
+    row_projections: tuple[CompiledRowProjection, ...]
+    link_rules: tuple[OutputLinkRule, ...]
+    derivation_rules: tuple[DerivationRule, ...]
+    notes: tuple[str, ...]
+
+
+class OutputDefinitionRuntime:
+    """
+    Compiler and executor for programmatic output definitions.
+    """
+
+    def __init__(
+        self,
+        definitions: Iterable[OutputDefinition],
+        projection_profiles: ProjectionProfileRuntime,
+    ) -> None:
+        self.projection_profiles = projection_profiles
+        self._compiled_by_name: dict[str, CompiledOutputDefinition] = {}
+        self._compiled_by_template: dict[str, list[CompiledOutputDefinition]] = {}
+        for definition in definitions:
+            compiled = self._compile_definition(definition)
+            if compiled.name in self._compiled_by_name:
+                raise ValueError(f"Duplicate output definition name: '{compiled.name}'")
+            self._compiled_by_name[compiled.name] = compiled
+            for template_name in compiled.template_names:
+                self._compiled_by_template.setdefault(template_name, []).append(compiled)
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._compiled_by_name))
+
+    def get(self, name: str) -> CompiledOutputDefinition:
+        return self._compiled_by_name[name]
+
+    def for_template(self, template_name: str) -> list[CompiledOutputDefinition]:
+        return list(self._compiled_by_template.get(template_name, ()))
+
+    def project(self, definition_name: str, context: Mapping[str, Any]) -> ProjectedOutputBundle:
+        compiled = self.get(definition_name)
+        projected_rows: list[ProjectedOutputRow] = []
+        row_ids: set[str] = set()
+        unresolved_fields: list[dict[str, Any]] = []
+        suppressed_rows: list[SuppressedRow] = []
+        audit_notes = list(compiled.notes)
+
+        for row_projection in compiled.row_projections:
+            resolved_fields = dict(row_projection.defaults)
+            missing_fields: list[str] = []
+            row_suppressed = False
+
+            for slot, binding in row_projection.field_bindings.items():
+                found, value = _resolve_binding(binding, context)
+                if not found:
+                    missing_fields.append(slot)
+                    continue
+                resolved_fields[slot] = value
+
+            for rule in compiled.derivation_rules:
+                if rule.target_row != row_projection.row_id:
+                    continue
+
+                found, raw_value = _resolve_binding(rule.source_field, context)
+                if not found:
+                    missing_fields.append(rule.target_slot)
+                    continue
+
+                code = str(raw_value)
+                if code in rule.suppress_codes:
+                    suppressed_rows.append(
+                        SuppressedRow(
+                            row_id=row_projection.row_id,
+                            reason=(
+                                f"derivation rule for '{rule.target_slot}' matched a "
+                                f"suppress code on '{rule.source_field.path}'"
+                            ),
+                            source_field=rule.source_field.path,
+                            source_code=code,
+                        )
+                    )
+                    row_suppressed = True
+                    break
+
+                if code in rule.code_map:
+                    resolved_fields[rule.target_slot] = rule.code_map[code]
+                elif rule.default is not NO_DEFAULT:
+                    resolved_fields[rule.target_slot] = rule.default
+                else:
+                    missing_fields.append(rule.target_slot)
+
+            policy = row_projection.special_value_policy
+            if policy is not None:
+                found, raw_value = _resolve_binding(policy.source_field, context)
+                if found:
+                    code = str(raw_value)
+                    if code in policy.allowed_special_values:
+                        if policy.suppression_mode == "drop":
+                            suppressed_rows.append(
+                                SuppressedRow(
+                                    row_id=row_projection.row_id,
+                                    reason=(
+                                        "special_value_policy matched "
+                                        f"'{policy.source_field.path}' == '{code}'"
+                                    ),
+                                    source_field=policy.source_field.path,
+                                    source_code=code,
+                                )
+                            )
+                            row_suppressed = True
+                        elif policy.suppression_mode == "fail":
+                            raise ValueError(
+                                f"row '{row_projection.row_id}' hit special value '{code}' "
+                                f"on '{policy.source_field.path}', configured to fail"
+                            )
+                        else:
+                            raise NotImplementedError(
+                                f"suppression_mode '{policy.suppression_mode}' has no "
+                                "runtime behavior yet"
+                            )
+
+            if row_suppressed:
+                continue
+
+            if missing_fields:
+                unresolved_fields.append(
+                    {
+                        "row_id": row_projection.row_id,
+                        "missing_fields": missing_fields,
+                        "required": row_projection.required,
+                    }
+                )
+                if row_projection.required:
+                    continue
+
+            if row_projection.profile.concept_slot not in resolved_fields:
+                unresolved_fields.append(
+                    {
+                        "row_id": row_projection.row_id,
+                        "missing_fields": [row_projection.profile.concept_slot],
+                        "required": row_projection.required,
+                    }
+                )
+                if row_projection.required:
+                    continue
+
+            row = ProjectedOutputRow(
+                row_id=row_projection.row_id,
+                profile=row_projection.profile,
+                fields=resolved_fields,
+            )
+            projected_rows.append(row)
+            row_ids.add(row.row_id)
+
+        links: list[ProjectedOutputLink] = []
+        for link_rule in compiled.link_rules:
+            if link_rule.source_row in row_ids and link_rule.target_row in row_ids:
+                links.append(
+                    ProjectedOutputLink(
+                        source_row=link_rule.source_row,
+                        target_row=link_rule.target_row,
+                        relationship_type=link_rule.relationship_type,
+                        source_field=link_rule.source_field,
+                        target_field=link_rule.target_field,
+                    )
+                )
+            else:
+                unresolved_fields.append(
+                    {
+                        "link": {
+                            "source_row": link_rule.source_row,
+                            "target_row": link_rule.target_row,
+                            "relationship_type": link_rule.relationship_type,
+                        },
+                        "missing_rows": [
+                            row_id
+                            for row_id in (link_rule.source_row, link_rule.target_row)
+                            if row_id not in row_ids
+                        ],
+                    }
+                )
+
+        return ProjectedOutputBundle(
+            definition_name=compiled.name,
+            role=compiled.role,
+            rows=projected_rows,
+            links=links,
+            unresolved_fields=unresolved_fields,
+            suppressed_rows=suppressed_rows,
+            audit_notes=audit_notes,
+        )
+
+    def project_for_template(
+        self,
+        template_name: str,
+        context: Mapping[str, Any],
+        *,
+        definition_name: str | None = None,
+    ) -> ProjectedOutputBundle:
+        matches = self.for_template(template_name)
+        if definition_name is not None:
+            matches = [item for item in matches if item.name == definition_name]
+        if not matches:
+            raise KeyError(f"No output definition found for template '{template_name}'")
+        if len(matches) > 1:
+            names = ", ".join(sorted(item.name for item in matches))
+            raise ValueError(
+                f"Multiple output definitions match template '{template_name}': {names}"
+            )
+        return self.project(matches[0].name, context)
+
+    def _compile_definition(self, definition: OutputDefinition) -> CompiledOutputDefinition:
+        row_ids: set[str] = set()
+        compiled_rows: list[CompiledRowProjection] = []
+        profile_by_row: dict[str, RuntimeProjectionProfile] = {}
+        errors: list[str] = []
+
+        for row_projection in definition.row_projections:
+            if row_projection.row_id in row_ids:
+                errors.append(f"duplicate row_id '{row_projection.row_id}'")
+                continue
+            row_ids.add(row_projection.row_id)
+
+            profile = self.projection_profiles.get(row_projection.profile_name)
+            declared_slots = set(row_projection.defaults) | set(row_projection.field_bindings)
+            invalid_slots = sorted(slot for slot in declared_slots if not profile.allows_slot(slot))
+            if invalid_slots:
+                errors.append(
+                    f"row '{row_projection.row_id}' uses slots not present in profile "
+                    f"'{profile.name}': {invalid_slots}"
+                )
+                continue
+
+            policy = row_projection.special_value_policy
+            if policy is not None and policy.suppression_mode not in SUPPRESSION_MODES:
+                errors.append(
+                    f"row '{row_projection.row_id}' has special_value_policy with "
+                    f"unrecognized suppression_mode '{policy.suppression_mode}'; "
+                    f"expected one of {sorted(SUPPRESSION_MODES)}"
+                )
+                continue
+
+            profile_by_row[row_projection.row_id] = profile
+            compiled_rows.append(
+                CompiledRowProjection(
+                    row_id=row_projection.row_id,
+                    profile=profile,
+                    field_bindings=dict(row_projection.field_bindings),
+                    defaults=dict(row_projection.defaults),
+                    required=row_projection.required,
+                    special_value_policy=policy,
+                )
+            )
+
+        for link_rule in definition.link_rules:
+            if link_rule.source_row not in row_ids:
+                errors.append(
+                    f"link rule references unknown source_row '{link_rule.source_row}'"
+                )
+            if link_rule.target_row not in row_ids:
+                errors.append(
+                    f"link rule references unknown target_row '{link_rule.target_row}'"
+                )
+
+        for derivation_rule in definition.derivation_rules:
+            if derivation_rule.target_row not in row_ids:
+                errors.append(
+                    "derivation rule references unknown target_row "
+                    f"'{derivation_rule.target_row}'"
+                )
+                continue
+            profile = profile_by_row.get(derivation_rule.target_row)
+            if profile is not None and not profile.allows_slot(derivation_rule.target_slot):
+                errors.append(
+                    f"derivation rule for row '{derivation_rule.target_row}' targets slot "
+                    f"'{derivation_rule.target_slot}' not present in profile '{profile.name}'"
+                )
+
+        if errors:
+            raise ValueError(
+                f"Output definition '{definition.name}' failed validation:\n"
+                + "\n".join(f"  - {item}" for item in errors)
+            )
+
+        return CompiledOutputDefinition(
+            name=definition.name,
+            role=definition.role,
+            template_names=tuple(definition.template_names),
+            row_projections=tuple(compiled_rows),
+            link_rules=tuple(definition.link_rules),
+            derivation_rules=tuple(definition.derivation_rules),
+            notes=tuple(definition.notes),
+        )
+
+
+def _resolve_binding(binding: BindingValue, context: Mapping[str, Any]) -> tuple[bool, Any]:
+    if isinstance(binding, ContextFieldRef):
+        return _resolve_context_path(context, binding.path)
+    return True, binding
+
+
+def _resolve_context_path(context: Mapping[str, Any], path: str) -> tuple[bool, Any]:
+    current: Any = context
+    for part in path.split("."):
+        if isinstance(current, Mapping):
+            if part not in current:
+                return False, None
+            current = current[part]
+            continue
+        if not hasattr(current, part):
+            return False, None
+        current = getattr(current, part)
+    return True, current

omop_semantics-0.3.0/src/omop_semantics/runtime/projection.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+from omop_semantics.schema.generated_models.omop_semantic_registry import OmopCdmProfile
+
+
+@dataclass(frozen=True)
+class RuntimeProjectionProfile:
+    """
+    Attribute-based runtime view over an `OmopCdmProfile`.
+
+    This is the structural counterpart to `RuntimeTemplate`: it exposes
+    the CDM row-shape information in a stable, ergonomic form for
+    downstream execution layers that need to reason about units,
+    operators, inline modifiers, or other supported slots.
+    """
+
+    name: str
+    cdm_table: str
+    concept_slot: str
+    value_slot: str | None = None
+    unit_slot: str | None = None
+    operator_slot: str | None = None
+    modifier_slot: str | None = None
+    extra_concept_slots: tuple[str, ...] = ()
+    numeric_slots: tuple[str, ...] = ()
+    string_slots: tuple[str, ...] = ()
+    reference_slots: tuple[str, ...] = ()
+
+    @classmethod
+    def from_profile(cls, profile: OmopCdmProfile) -> "RuntimeProjectionProfile":
+        return cls(
+            name=profile.name,
+            cdm_table=profile.cdm_table,
+            concept_slot=profile.concept_slot,
+            value_slot=profile.value_slot,
+            unit_slot=profile.unit_slot,
+            operator_slot=profile.operator_slot,
+            modifier_slot=profile.modifier_slot,
+            extra_concept_slots=tuple(profile.extra_concept_slots or ()),
+            numeric_slots=tuple(profile.numeric_slots or ()),
+            string_slots=tuple(profile.string_slots or ()),
+            reference_slots=tuple(profile.reference_slots or ()),
+        )
+
+    def concept_slots(self) -> tuple[str, ...]:
+        slots: list[str] = [self.concept_slot]
+        if self.modifier_slot is not None:
+            slots.append(self.modifier_slot)
+        slots.extend(self.extra_concept_slots)
+        if self.unit_slot is not None:
+            slots.append(self.unit_slot)
+        if self.operator_slot is not None:
+            slots.append(self.operator_slot)
+        return tuple(slots)
+
+    def all_slots(self) -> tuple[str, ...]:
+        slots: list[str] = [self.concept_slot]
+        if self.value_slot is not None:
+            slots.append(self.value_slot)
+        if self.unit_slot is not None:
+            slots.append(self.unit_slot)
+        if self.operator_slot is not None:
+            slots.append(self.operator_slot)
+        if self.modifier_slot is not None:
+            slots.append(self.modifier_slot)
+        slots.extend(self.extra_concept_slots)
+        slots.extend(self.numeric_slots)
+        slots.extend(self.string_slots)
+        slots.extend(self.reference_slots)
+        return tuple(slots)
+
+    def allows_slot(self, slot: str) -> bool:
+        return slot in self.all_slots()
+
+
+class ProjectionProfileRuntime:
+    """
+    Indexed runtime access to compiled CDM projection profiles.
+
+    This keeps the structural profile catalogue available at runtime
+    even when execution is not yet using higher-level output definitions.
+    """
+
+    def __init__(self, profiles: Mapping[str, OmopCdmProfile]):
+        self._profiles = dict(profiles)
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._profiles))
+
+    def get(self, name: str) -> RuntimeProjectionProfile:
+        return RuntimeProjectionProfile.from_profile(self._profiles[name])
+
+    def by_table(self, cdm_table: str) -> list[RuntimeProjectionProfile]:
+        return [
+            RuntimeProjectionProfile.from_profile(profile)
+            for profile in self._profiles.values()
+            if profile.cdm_table == cdm_table
+        ]
+
+
+@dataclass(frozen=True)
+class ProjectedOutputRow:
+    """
+    One projected row produced by a deterministic semantic execution step.
+    """
+
+    row_id: str
+    profile: RuntimeProjectionProfile
+    fields: dict[str, Any]
+
+    def __post_init__(self) -> None:
+        unknown_slots = sorted(set(self.fields) - set(self.profile.all_slots()))
+        if unknown_slots:
+            raise ValueError(
+                f"Projected row '{self.row_id}' contains fields not allowed by "
+                f"profile '{self.profile.name}': {unknown_slots}"
+            )
+        if self.profile.concept_slot not in self.fields:
+            raise ValueError(
+                f"Projected row '{self.row_id}' is missing required concept slot "
+                f"'{self.profile.concept_slot}' for profile '{self.profile.name}'"
+            )
+
+
+@dataclass(frozen=True)
+class SuppressedRow:
+    """
+    A row a definition would have produced, dropped deterministically by a
+    `DerivationRule` or row-level suppression policy rather than fabricated
+    with a missing or null slot value.
+    """
+
+    row_id: str
+    reason: str
+    source_field: str
+    source_code: str
+
+
+@dataclass(frozen=True)
+class ProjectedOutputLink:
+    """
+    Relationship between projected rows.
+    """
+
+    source_row: str
+    target_row: str
+    relationship_type: str
+    source_field: str | None = None
+    target_field: str | None = None
+
+
+@dataclass(frozen=True)
+class ProjectedOutputBundle:
+    """
+    Transport-friendly deterministic projection result.
+    """
+
+    definition_name: str
+    role: str
+    rows: list[ProjectedOutputRow]
+    links: list[ProjectedOutputLink] = field(default_factory=list)
+    constraint_checks: list[dict[str, Any]] = field(default_factory=list)
+    unresolved_fields: list[dict[str, Any]] = field(default_factory=list)
+    suppressed_rows: list[SuppressedRow] = field(default_factory=list)
+    audit_notes: list[str] = field(default_factory=list)
+
+    def row(self, row_id: str) -> ProjectedOutputRow:
+        for row in self.rows:
+            if row.row_id == row_id:
+                return row
+        raise KeyError(f"No projected row with id '{row_id}'")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "definition_name": self.definition_name,
+            "role": self.role,
+            "rows": [
+                {
+                    "row_id": row.row_id,
+                    "profile": row.profile.name,
+                    "cdm_table": row.profile.cdm_table,
+                    "fields": dict(row.fields),
+                }
+                for row in self.rows
+            ],
+            "links": [
+                {
+                    "source_row": link.source_row,
+                    "target_row": link.target_row,
+                    "relationship_type": link.relationship_type,
+                    "source_field": link.source_field,
+                    "target_field": link.target_field,
+                }
+                for link in self.links
+            ],
+            "constraint_checks": [dict(item) for item in self.constraint_checks],
+            "unresolved_fields": [dict(item) for item in self.unresolved_fields],
+            "suppressed_rows": [
+                {
+                    "row_id": row.row_id,
+                    "reason": row.reason,
+                    "source_field": row.source_field,
+                    "source_code": row.source_code,
+                }
+                for row in self.suppressed_rows
+            ],
+            "audit_notes": list(self.audit_notes),
+        }

{omop_semantics-0.2.2 → omop_semantics-0.3.0}/src/omop_semantics/runtime/resolver.py

@@ -22,6 +22,8 @@ from .instance_loader import (
     needs_profile_interpolation,
 )
 from omop_semantics.utils.paths import INSTANCE_DIR
+from .projection import ProjectionProfileRuntime, RuntimeProjectionProfile
+from .output_definitions import OutputDefinition, OutputDefinitionRuntime
 
 
 class CompiledTemplate(TypedDict):
@@ -203,6 +205,13 @@ class RuntimeTemplate:
             value_concept_ids=c["value_concept_ids"],
         )
 
+    @property
+    def projection_profile(self) -> RuntimeProjectionProfile:
+        """
+        Structural runtime view of the underlying CDM profile.
+        """
+        return RuntimeProjectionProfile.from_profile(self.cdm_profile)
+
 
 @dataclass(frozen=True)
 class RegistryRuntimeDiff:
@@ -999,6 +1008,7 @@ class OmopSemanticEngine:
         self,
         registry_fragment: RegistryFragment,
         profile_objects: dict[str, dict] | None = None,
+        cdm_profiles: dict[str, OmopCdmProfile] | None = None,
     ):
         """
         Construct a semantic engine from an already-loaded registry fragment.
@@ -1022,6 +1032,11 @@ class OmopSemanticEngine:
             if profile_objects is not None
             else None
         )
+        self.projection_profiles = (
+            ProjectionProfileRuntime(cdm_profiles)
+            if cdm_profiles is not None
+            else None
+        )
 
     @classmethod
     def from_instances(cls, fragment: RegistryFragment) -> "OmopSemanticEngine":
@@ -1098,6 +1113,7 @@ class OmopSemanticEngine:
         return cls(
             registry_fragment=merged_fragment,
             profile_objects=profile_objects or None,
+            cdm_profiles=cdm_profiles,
         )
 
     def docs_html(self) -> Html:
@@ -1122,3 +1138,18 @@ class OmopSemanticEngine:
             ])
 
         return Html("".join(parts))
+
+    def build_output_definition_runtime(
+        self,
+        definitions: Iterable[OutputDefinition],
+    ) -> OutputDefinitionRuntime:
+        """
+        Compile programmatic output definitions against the loaded profile catalogue.
+
+        This is the additive bridge from structural CDM profiles to deterministic
+        output bundles. The first implementation slice is intentionally runtime-only
+        and does not require a dedicated YAML schema for output definitions.
+        """
+        if self.projection_profiles is None:
+            raise RuntimeError("Projection profiles are not available on this semantic engine")
+        return OutputDefinitionRuntime(definitions, self.projection_profiles)

omop_semantics-0.3.0/src/omop_semantics/schema/configuration/core/omop_profiles.yaml

@@ -0,0 +1,81 @@
+id: https://example.org/omop_semantics/cdm_profiles
+name: cdm_profiles
+
+imports:
+  - omop_base
+
+classes:
+  CDMProfiles:
+    slots:
+      - profiles
+    tree_root: true
+  OmopCdmProfile:
+    slots:
+      - name
+      - cdm_table
+      - concept_slot
+      - value_slot
+      - unit_slot
+      - operator_slot
+      - modifier_slot
+      - extra_concept_slots
+      - numeric_slots
+      - string_slots
+      - reference_slots
+slots:
+  profiles:
+    range: OmopCdmProfile
+    multivalued: true
+  name:
+    range: string
+    required: true
+  cdm_table:
+    range: CdmTable
+    required: true
+  concept_slot:
+    range: string
+    required: true
+  value_slot:
+    range: string
+    required: false
+  unit_slot:
+    range: string
+    required: false
+  operator_slot:
+    range: string
+    required: false
+  modifier_slot:
+    range: string
+    required: false
+  extra_concept_slots:
+    range: string
+    multivalued: true
+    required: false
+  numeric_slots:
+    range: string
+    multivalued: true
+    required: false
+  string_slots:
+    range: string
+    multivalued: true
+    required: false
+  reference_slots:
+    range: string
+    multivalued: true
+    required: false
+enums:
+  CdmTable:
+    description: OMOP CDM table to which a semantic template applies
+    permissible_values:
+      observation:
+      measurement:
+      drug_exposure:
+      procedure_occurrence:
+      condition_occurrence:
+      device_exposure:
+      visit_occurrence:
+      death:
+      specimen:
+      fact_relationship:
+      episode:
+      episode_event:

{omop_semantics-0.2.2 → omop_semantics-0.3.0}/src/omop_semantics/schema/generated_models/omop_semantic_registry.py

@@ -92,6 +92,12 @@ class CdmTable(str, Enum):
     procedure_occurrence = "procedure_occurrence"
     condition_occurrence = "condition_occurrence"
     device_exposure = "device_exposure"
+    visit_occurrence = "visit_occurrence"
+    death = "death"
+    specimen = "specimen"
+    fact_relationship = "fact_relationship"
+    episode = "episode"
+    episode_event = "episode_event"
 
 
 
@@ -212,6 +218,13 @@ class OmopCdmProfile(ConfiguredBaseModel):
     cdm_table: CdmTable = Field(default=..., json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
     concept_slot: str = Field(default=..., json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
     value_slot: Optional[str] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
+    unit_slot: Optional[str] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
+    operator_slot: Optional[str] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
+    modifier_slot: Optional[str] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
+    extra_concept_slots: Optional[list[str]] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
+    numeric_slots: Optional[list[str]] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
+    string_slots: Optional[list[str]] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
+    reference_slots: Optional[list[str]] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopCdmProfile']} })
 
 
 class OmopTemplate(ConfiguredBaseModel):

{omop_semantics-0.2.2 → omop_semantics-0.3.0}/src/omop_semantics/schema/instances/profile_groups.yaml

@@ -15,6 +15,9 @@ ObservationProfiles:
     - observation_simple
     - observation_coded
     - observation_string
+    - observation_numeric
+    - observation_numeric_with_unit
+    - observation_with_qualifier
   notes: Valid CDM projection profiles for the OMOP OBSERVATION table
 
 
@@ -24,7 +27,10 @@ MeasurementProfiles:
   role: cdm_profile_set
   members:
     - measurement_numeric
+    - measurement_numeric_with_unit
+    - measurement_numeric_with_operator
     - measurement_coded
+    - measurement_simple
   notes: Valid CDM projection profiles for the OMOP MEASUREMENT table
 
 
@@ -34,6 +40,7 @@ ProcedureProfiles:
   role: cdm_profile_set
   members:
     - procedure_simple
+    - procedure_with_inline_modifier
 
 
 ConditionProfiles:
@@ -42,6 +49,7 @@ ConditionProfiles:
   role: cdm_profile_set
   members:
     - condition_simple
+    - condition_with_status
 
 
 DrugExposureProfiles:
@@ -50,4 +58,39 @@ DrugExposureProfiles:
   role: cdm_profile_set
   members:
     - drug_exposure_simple
-    - drug_exposure_dose
+    - drug_exposure_dose
+    - drug_exposure_with_quantity_and_days_supply
+    - drug_exposure_with_route
+
+
+DeviceProfiles:
+  class_uri: RegistryGroup
+  name: DeviceProfiles
+  role: cdm_profile_set
+  members:
+    - device_simple
+
+
+VisitProfiles:
+  class_uri: RegistryGroup
+  name: VisitProfiles
+  role: cdm_profile_set
+  members:
+    - visit_simple
+
+
+DeathProfiles:
+  class_uri: RegistryGroup
+  name: DeathProfiles
+  role: cdm_profile_set
+  members:
+    - death_simple
+
+
+SpecimenProfiles:
+  class_uri: RegistryGroup
+  name: SpecimenProfiles
+  role: cdm_profile_set
+  members:
+    - specimen_simple
+    - specimen_with_site_status_quantity

omop_semantics-0.3.0/src/omop_semantics/schema/instances/profiles.yaml

@@ -0,0 +1,102 @@
+profiles:
+  - name: observation_simple
+    cdm_table: observation
+    concept_slot: observation_concept_id
+  - name: observation_coded
+    cdm_table: observation
+    concept_slot: observation_concept_id
+    value_slot: value_as_concept_id
+  - name: observation_string
+    cdm_table: observation
+    concept_slot: observation_concept_id
+    value_slot: value_as_string
+  - name: observation_numeric
+    cdm_table: observation
+    concept_slot: observation_concept_id
+    value_slot: value_as_number
+  - name: observation_numeric_with_unit
+    cdm_table: observation
+    concept_slot: observation_concept_id
+    value_slot: value_as_number
+    unit_slot: unit_concept_id
+  - name: observation_with_qualifier
+    cdm_table: observation
+    concept_slot: observation_concept_id
+    extra_concept_slots:
+      - qualifier_concept_id
+  - name: measurement_numeric
+    cdm_table: measurement
+    concept_slot: measurement_concept_id
+    value_slot: value_as_number
+  - name: measurement_numeric_with_unit
+    cdm_table: measurement
+    concept_slot: measurement_concept_id
+    value_slot: value_as_number
+    unit_slot: unit_concept_id
+  - name: measurement_numeric_with_operator
+    cdm_table: measurement
+    concept_slot: measurement_concept_id
+    value_slot: value_as_number
+    unit_slot: unit_concept_id
+    operator_slot: operator_concept_id
+  - name: measurement_coded
+    cdm_table: measurement
+    concept_slot: measurement_concept_id
+    value_slot: value_as_concept_id
+  - name: measurement_simple
+    cdm_table: measurement
+    concept_slot: measurement_concept_id
+  - name: procedure_simple
+    cdm_table: procedure_occurrence
+    concept_slot: procedure_concept_id
+  - name: procedure_with_inline_modifier
+    cdm_table: procedure_occurrence
+    concept_slot: procedure_concept_id
+    modifier_slot: modifier_concept_id
+  - name: condition_simple
+    cdm_table: condition_occurrence
+    concept_slot: condition_concept_id
+  - name: condition_with_status
+    cdm_table: condition_occurrence
+    concept_slot: condition_concept_id
+    extra_concept_slots:
+      - condition_status_concept_id
+  - name: drug_exposure_simple
+    cdm_table: drug_exposure
+    concept_slot: drug_concept_id
+  - name: drug_exposure_dose
+    cdm_table: drug_exposure
+    concept_slot: drug_concept_id
+    value_slot: dose_value
+  - name: drug_exposure_with_quantity_and_days_supply
+    cdm_table: drug_exposure
+    concept_slot: drug_concept_id
+    numeric_slots:
+      - quantity
+      - days_supply
+  - name: drug_exposure_with_route
+    cdm_table: drug_exposure
+    concept_slot: drug_concept_id
+    extra_concept_slots:
+      - route_concept_id
+  - name: device_simple
+    cdm_table: device_exposure
+    concept_slot: device_concept_id
+  - name: visit_simple
+    cdm_table: visit_occurrence
+    concept_slot: visit_concept_id
+  - name: death_simple
+    cdm_table: death
+    concept_slot: death_type_concept_id
+  - name: specimen_simple
+    cdm_table: specimen
+    concept_slot: specimen_concept_id
+  - name: specimen_with_site_status_quantity
+    cdm_table: specimen
+    concept_slot: specimen_concept_id
+    extra_concept_slots:
+      - anatomic_site_concept_id
+      - disease_status_concept_id
+    numeric_slots:
+      - quantity
+    unit_slot: unit_concept_id

omop_semantics-0.2.2/src/omop_semantics/schema/configuration/core/omop_profiles.yaml

@@ -1,43 +0,0 @@
-id: https://example.org/omop_semantics/cdm_profiles
-name: cdm_profiles
-
-imports:
-  - omop_base
-
-classes:
-  CDMProfiles:
-    slots:
-      - profiles
-    tree_root: true
-  OmopCdmProfile:
-    slots:
-      - name
-      - cdm_table
-      - concept_slot
-      - value_slot
-slots:
-  profiles:
-    range: OmopCdmProfile
-    multivalued: true
-  name:
-    range: string
-    required: true
-  cdm_table:
-    range: CdmTable
-    required: true
-  concept_slot:
-    range: string
-    required: true
-  value_slot:
-    range: string
-    required: false
-enums:
-  CdmTable:
-    description: OMOP CDM table to which a semantic template applies
-    permissible_values:
-      observation:
-      measurement:
-      drug_exposure:
-      procedure_occurrence:
-      condition_occurrence:
-      device_exposure:

omop_semantics-0.2.2/src/omop_semantics/schema/instances/profiles.yaml

@@ -1,39 +0,0 @@
-profiles:
-  - name: observation_simple
-    cdm_table: observation
-    concept_slot: observation_concept_id
-  - name: observation_coded
-    cdm_table: observation
-    concept_slot: observation_concept_id
-    value_slot: value_as_concept_id
-  - name: observation_string
-    cdm_table: observation
-    concept_slot: observation_concept_id
-    value_slot: value_as_string
-  - name: measurement_numeric
-    cdm_table: measurement
-    concept_slot: measurement_concept_id
-    value_slot: value_as_number
-  - name: measurement_coded
-    cdm_table: measurement
-    concept_slot: measurement_concept_id
-    value_slot: value_as_concept_id
-  - name: measurement_simple
-    cdm_table: measurement
-    concept_slot: measurement_concept_id
-  - name: procedure_simple
-    cdm_table: procedure_occurrence
-    concept_slot: procedure_concept_id
-  - name: condition_simple
-    cdm_table: condition_occurrence
-    concept_slot: condition_concept_id
-  - name: drug_exposure_simple
-    cdm_table: drug_exposure
-    concept_slot: drug_concept_id
-  - name: drug_exposure_dose
-    cdm_table: drug_exposure
-    concept_slot: drug_concept_id
-    value_slot: dose_value
-  - name: device_simple
-    cdm_table: device_exposure
-    concept_slot: device_concept_id