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

omop_semantics-0.2.2/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.3
+Name: omop-semantics
+Version: 0.2.2
+Summary: Define, validate, and use schema-backed semantic conventions for OMOP CDM
+Author: gkennos
+Author-email: gkennos <georgina.kennedy@unsw.edu.au>
+Requires-Dist: ipykernel>=7.2.0
+Requires-Dist: linkml>=1.11.1
+Requires-Dist: linkml-runtime>=1.11.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: ruamel-yaml>=0.18.17
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Dist: urllib3>=2.7.0
+Requires-Dist: ipython>=8.0 ; extra == 'dev'
+Requires-Dist: pytest>=9.0.3 ; extra == 'dev'
+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: pygments>=2.20.0 ; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.7.6 ; extra == 'docs'
+Requires-Dist: mkdocstrings-python>=2.0.1 ; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.1 ; extra == 'docs'
+Requires-Dist: mkdocs-mermaid2-plugin>=1.2.3 ; extra == 'docs'
+Requires-Dist: pygments>=2.20.0 ; extra == 'docs'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://australiancancerdatanetwork.github.io/omop-semantics/
+Project-URL: Repository, https://github.com/AustralianCancerDataNetwork/omop-semantics
+Project-URL: Issues, https://github.com/AustralianCancerDataNetwork/omop-semantics/issues
+Provides-Extra: dev
+Provides-Extra: docs
+Description-Content-Type: text/markdown
+
+# omop-semantics
+
+**omop-semantics** is a Python library for defining and managing **semantic conventions on top of OMOP CDM**.
+
+It gives you a structured, versioned, portable layer for describing which OMOP concepts are valid in a given context, how they map to CDM row shapes, and what fallback concepts to use when a mapping cannot be completed. Conventions are authored in YAML, validated against schemas, and exposed as typed Python objects — not scattered across ETL code, SQL, or documentation.
+
+---
+
+## Three runtime surfaces
+
+- **Value-set runtime**  
+  Stable named concept ids for application logic:  
+  `from omop_semantics.runtime.default_valuesets import runtime`
+
+- **Template/profile runtime**  
+  Compiled semantic templates and CDM profiles via `OmopSemanticEngine`.
+
+- **Fallback concepts**  
+  Canonical unknown and default concepts with reason codes:  
+  `from omop_semantics.unknowns import UNKNOWN`
+
+---
+
+## Key properties
+
+- **Portable** — no database or vocabulary graph required
+- **Versionable** — conventions are tracked in git alongside code
+- **Extensible** — add project-specific definitions on top of the shipped ones
+- **Integrates with pipelines** — drives ETL logic, validation, and documentation from a single source
+
+---
+
+## When to use this
+
+Use **omop-semantics** if you:
+
+- have project-specific rules about which OMOP concepts are valid,
+- need consistent concept groupings across ETL and analytics,
+- want semantic conventions to be explicit, testable, and versioned,
+- are working in domains like oncology where OMOP alone is too permissive.
+
+---
+
+## Docs
+
+- [Usage](docs/usage.md) — loading paths and code patterns
+- [Data Model](docs/data-model.md) — profiles, templates, and semantic objects
+- [Schema & Instances](docs/schema-and-instances.md) — authoring assets and file organisation
+- [Fallback Concepts](docs/unknowns.md) — the shipped unknown and default concepts
+- [Internals](docs/internals.md) — package structure and load-time behaviour

omop_semantics-0.2.2/README.md

@@ -0,0 +1,50 @@
+# omop-semantics
+
+**omop-semantics** is a Python library for defining and managing **semantic conventions on top of OMOP CDM**.
+
+It gives you a structured, versioned, portable layer for describing which OMOP concepts are valid in a given context, how they map to CDM row shapes, and what fallback concepts to use when a mapping cannot be completed. Conventions are authored in YAML, validated against schemas, and exposed as typed Python objects — not scattered across ETL code, SQL, or documentation.
+
+---
+
+## Three runtime surfaces
+
+- **Value-set runtime**  
+  Stable named concept ids for application logic:  
+  `from omop_semantics.runtime.default_valuesets import runtime`
+
+- **Template/profile runtime**  
+  Compiled semantic templates and CDM profiles via `OmopSemanticEngine`.
+
+- **Fallback concepts**  
+  Canonical unknown and default concepts with reason codes:  
+  `from omop_semantics.unknowns import UNKNOWN`
+
+---
+
+## Key properties
+
+- **Portable** — no database or vocabulary graph required
+- **Versionable** — conventions are tracked in git alongside code
+- **Extensible** — add project-specific definitions on top of the shipped ones
+- **Integrates with pipelines** — drives ETL logic, validation, and documentation from a single source
+
+---
+
+## When to use this
+
+Use **omop-semantics** if you:
+
+- have project-specific rules about which OMOP concepts are valid,
+- need consistent concept groupings across ETL and analytics,
+- want semantic conventions to be explicit, testable, and versioned,
+- are working in domains like oncology where OMOP alone is too permissive.
+
+---
+
+## Docs
+
+- [Usage](docs/usage.md) — loading paths and code patterns
+- [Data Model](docs/data-model.md) — profiles, templates, and semantic objects
+- [Schema & Instances](docs/schema-and-instances.md) — authoring assets and file organisation
+- [Fallback Concepts](docs/unknowns.md) — the shipped unknown and default concepts
+- [Internals](docs/internals.md) — package structure and load-time behaviour

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

@@ -1,6 +1,6 @@
 [project]
 name = "omop-semantics"
-version = "0.2.1"
+version = "0.2.2"
 description = "Define, validate, and use schema-backed semantic conventions for OMOP CDM"
 readme = "README.md"
 authors = [
@@ -23,7 +23,7 @@ omop-semantics = "omop_semantics:main"
 [project.optional-dependencies]
 dev = [
   "ipython>=8.0",
-  "pytest>=7.0",
+  "pytest>=9.0.3",
   "pytest-cov>=4.0",
   "mypy>=1.8",
   "ruff>=0.4",
@@ -45,6 +45,9 @@ build-backend = "uv_build"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+[tool.pyright]
+ignore = ["src/omop_semantics/schema/generated_models"]
+
 [project.urls]
 Homepage = "https://australiancancerdatanetwork.github.io/omop-semantics/"
 Repository = "https://github.com/AustralianCancerDataNetwork/omop-semantics"

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

@@ -80,6 +80,18 @@ def merge_instance_files(
         "groups": merged_groups
     }
 
+def needs_profile_interpolation(path: Path) -> bool:
+    """Return True if any registry member in the file uses a string cdm_profile reference."""
+    data = yaml_loader.load_as_dict(str(path))
+    if not isinstance(data, dict):
+        return False
+    for group in data.get("groups", []) or []:
+        for member in (group.get("registry_members") or []):
+            if isinstance(member.get("cdm_profile"), str):
+                return True
+    return False
+
+
 def merge_registry_fragments(fragments: Sequence[RegistryFragment]) -> RegistryFragment:
     groups: list[RegistryGroup] = []
 

{omop_semantics-0.2.1 → omop_semantics-0.2.2}/src/omop_semantics/runtime/renderers.py

@@ -243,11 +243,11 @@ def render_registry_group(group: RegistryGroup) -> Html:
         ],
     )
 
+    notes = f"<p><em>{h(group.notes)}</em></p>" if group.notes else ""
     return Html(
         f"<h3>{h(group.name)} ({h(group.role)})</h3>"
         f"{html}"
-        f"<p><em>{h(group.notes)}</em></p>" if group.notes else
-        f"<h3>{h(group.name)} ({h(group.role)})</h3>{html}"
+        f"{notes}"
     )
 
 def render_registry_fragment(fragment: RegistryFragment) -> Html:

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

@@ -12,7 +12,6 @@ from omop_semantics.schema.generated_models.omop_semantic_registry import (
 from pathlib import Path
 from dataclasses import dataclass
 from typing import Iterable, TypedDict, Optional, Set
-from pydantic import ValidationError
 from .renderers import render_semantic_object, render_profile_object, Html, tr, h, table, as_list, render_compiled_templates
 from .instance_loader import (
     load_profiles,
@@ -20,6 +19,7 @@ from .instance_loader import (
     merge_instance_files,
     merge_registry_fragments,
     load_symbol_module,
+    needs_profile_interpolation,
 )
 from omop_semantics.utils.paths import INSTANCE_DIR
 
@@ -368,8 +368,6 @@ class OmopRegistryRuntime:
         """
         if self._compiled_by_name is None:
             self.compile_index()
-        if self._compiled_by_name is None:
-            raise RuntimeError("No compiled templates available")
         return self._compiled_by_name[name]
     
     def get_runtime(self, name: str) -> RuntimeTemplate:
@@ -413,8 +411,6 @@ class OmopRegistryRuntime:
         """
         if self._compiled_by_role is None:
             self.compile_index()
-        if self._compiled_by_role is None:
-            raise RuntimeError("No compiled templates available")
         return self._compiled_by_role.get(role, [])
 
     def compile_all(self, role: str | None = None) -> list[CompiledTemplate]:
@@ -433,9 +429,7 @@ class OmopRegistryRuntime:
         """
         if self._compiled_by_name is None:
             self.compile_index()
-        if self._compiled_by_name is None:
-            raise RuntimeError("Template compilation failed")
-        if role is None or self._compiled_by_role is None:
+        if role is None:
             return list(self._compiled_by_name.values())
         return self._compiled_by_role.get(role, [])
     
@@ -1053,6 +1047,8 @@ class OmopSemanticEngine:
         cls,
         registry_paths: Iterable[Path],
         profile_paths: Iterable[Path] = (),
+        *,
+        profiles_path: Path | None = None,
     ) -> "OmopSemanticEngine":
         """
         Construct a semantic engine from YAML registry and profile files.
@@ -1061,10 +1057,9 @@ class OmopSemanticEngine:
         Profile YAML files are loaded into a symbolic profile namespace for
         documentation and inspection.
 
-        The shipped registry instance files often store `cdm_profile` as a
-        string such as `observation_simple`. This method resolves those names
-        against the built-in `profiles.yaml` catalogue before validating and
-        compiling the registry fragment.
+        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
         ----------
@@ -1072,7 +1067,10 @@ class OmopSemanticEngine:
             Paths to registry fragment YAML files.
         profile_paths
             Optional paths to symbolic profile/group YAML files that should be
-            exposed through `profile_runtime`.
+            exposed through ``profile_runtime``.
+        profiles_path
+            Path to the CDM profile catalogue YAML. Defaults to the shipped
+            ``profiles.yaml`` when not provided.
 
         Returns
         -------
@@ -1081,17 +1079,16 @@ class OmopSemanticEngine:
         """
         fragments: list[RegistryFragment] = []
         profile_objects: dict[str, dict] = {}
-        cdm_profiles = load_profiles(INSTANCE_DIR / "profiles.yaml")
+        cdm_profiles = load_profiles(profiles_path or INSTANCE_DIR / "profiles.yaml")
 
         for p in registry_paths:
-            try:
-                fragments.append(load_registry_fragment(p))
-            except ValidationError:
-                # Shipped registry instance files often refer to cdm_profile by
-                # name and need interpolation against the profile catalogue
-                # before they conform to RegistryFragment.
+            if needs_profile_interpolation(p):
+                # File uses string-named cdm_profile references; expand them
+                # against the catalogue before validating as RegistryFragment.
                 interpolated = merge_instance_files([p], cdm_profiles)
                 fragments.append(RegistryFragment.model_validate(interpolated))
+            else:
+                fragments.append(load_registry_fragment(p))
 
         for p in profile_paths:
             profile_objects.update(load_symbol_module(p))

{omop_semantics-0.2.1 → omop_semantics-0.2.2}/src/omop_semantics/runtime/value_sets.py

@@ -1,16 +1,3 @@
-from dataclasses import dataclass
-from omop_semantics.schema.generated_models.omop_named_sets import (
-    OmopConcept, 
-    OmopGroup, 
-    OmopEnum, 
-    OmopSemanticObject, 
-    CDMSemanticUnits,
-    CDMValueSet,
-    CDMValueSets
-)
-from abc import ABC
-from .renderers import tr, table, h, Html
-
 """
 Runtime accessors for OMOP semantic value sets.
 
@@ -40,8 +27,20 @@ as a pure read-only semantic access layer.
 """
 
 from abc import ABC
+from dataclasses import dataclass
 from typing import Mapping
 
+from omop_semantics.schema.generated_models.omop_named_sets import (
+    OmopConcept,
+    OmopGroup,
+    OmopEnum,
+    OmopSemanticObject,
+    CDMSemanticUnits,
+    CDMValueSet,
+    CDMValueSets,
+)
+from .renderers import tr, table, h, Html
+
 class _RuntimeLabelledConcepts(ABC):
     """
     Thin shared base for runtime objects that expose a label -> concept_id mapping.
@@ -67,7 +66,10 @@ class _RuntimeLabelledConcepts(ABC):
     def __getattr__(self, label: str) -> int:
         if label.startswith("_"):
             raise AttributeError(label)
-        return self._by_label[label]
+        try:
+            return self._by_label[label]
+        except KeyError:
+            raise AttributeError(label) from None
 
     def __repr__(self) -> str:
         labels = ", ".join(self.labels)
@@ -234,10 +236,10 @@ class RuntimeSemanticUnit:
             for value in labelled_item.values():
                 try:
                     return getattr(value, name)
-                except AttributeError:
+                except KeyError:
                     pass
 
-        raise AttributeError(name)
+        raise KeyError(name)
 
     def __repr__(self) -> str:
         parts = []
@@ -404,7 +406,7 @@ def compile_valuesets(defs: CDMValueSets) -> RuntimeValueSets:
     for vs in defs.valuesets:
         members = {
             (unit.name or "[unlabelled]"): RuntimeSemanticUnit(unit)
-            for unit in vs.members
+            for unit in vs.semantic_units
         }
 
         compiled[vs.valueset_name] = RuntimeValueSet(
@@ -485,7 +487,7 @@ def interpolate_valuesets(
     for vs in raw["valuesets"]:
         resolved_members: list[CDMSemanticUnits] = []
 
-        for name in vs["members"]:
+        for name in vs["semantic_units"]:
             if name not in semantic_index:
                 raise KeyError(f"Unknown semantic unit referenced in valuesets.yaml: {name}")
 
@@ -516,7 +518,7 @@ def interpolate_valuesets(
         valuesets.append(
             CDMValueSet(
                 valueset_name=vs["name"],
-                members=resolved_members,
+                semantic_units=resolved_members,
             )
         )
 

{omop_semantics-0.2.1 → omop_semantics-0.2.2}/src/omop_semantics/schema/configuration/core/omop_named_sets.yaml

@@ -12,7 +12,7 @@ classes:
   CDMValueSet:
     slots:
       - valueset_name
-      - members
+      - semantic_units
   CDMSemanticUnits:
     slots:
       - name
@@ -41,7 +41,7 @@ slots:
     required: true
   name:
     range: string
-  members:
+  semantic_units:
     range: CDMSemanticUnits
     multivalued: true
     required: true

{omop_semantics-0.2.1 → omop_semantics-0.2.2}/src/omop_semantics/schema/generated_models/omop_named_sets.py

@@ -135,7 +135,7 @@ class OmopValueSet(OmopSemanticObject):
          'slot_usage': {'class_uri': {'equals_string': 'OmopValueSet',
                                       'name': 'class_uri'}}})
 
-    members: list[CDMSemanticUnits] = Field(default=..., json_schema_extra = { "linkml_meta": {'domain_of': ['OmopValueSet', 'CDMValueSet']} })
+    members: Optional[list[OmopSemanticObject]] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopValueSet']} })
     class_uri: Literal["OmopValueSet"] = Field(default=..., json_schema_extra = { "linkml_meta": {'domain_of': ['OmopSemanticObject'], 'equals_string': 'OmopValueSet'} })
     name: Optional[str] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopSemanticObject', 'CDMSemanticUnits']} })
     notes: Optional[str] = Field(default=None, json_schema_extra = { "linkml_meta": {'domain_of': ['OmopSemanticObject']} })
@@ -163,7 +163,7 @@ class CDMValueSet(ConfiguredBaseModel):
     linkml_meta: ClassVar[LinkMLMeta] = LinkMLMeta({'from_schema': 'https://example.org/omop_semantics/cdm_value_sets'})
 
     valueset_name: str = Field(default=..., json_schema_extra = { "linkml_meta": {'domain_of': ['CDMValueSet']} })
-    members: list[CDMSemanticUnits] = Field(default=..., json_schema_extra = { "linkml_meta": {'domain_of': ['OmopValueSet', 'CDMValueSet']} })
+    semantic_units: list[CDMSemanticUnits] = Field(default=..., json_schema_extra = { "linkml_meta": {'domain_of': ['CDMValueSet']} })
 
 
 class CDMSemanticUnits(ConfiguredBaseModel):

{omop_semantics-0.2.1 → omop_semantics-0.2.2}/src/omop_semantics/schema/instances/valuesets.yaml

@@ -1,41 +1,41 @@
 valuesets:
   - name: genomic
-    members:
+    semantic_units:
       - genomic_value_group
       - genomic_mapped_types
   - name: modifiers
-    members:
+    semantic_units:
       - modifier_fields
       - modifier_tables
   - name: types
-    members: 
+    semantic_units: 
       - treatment_episode_types
       - disease_episode_types
       - source_types
   - name: treatment_modifiers
-    members: 
+    semantic_units: 
       - treatment_intent
       - treatment_modality
       - treatment_modifier_values
   - name: condition_modifiers
-    members: 
+    semantic_units: 
       - condition_modifier_values
       - tumor_grade
       - numeric_condition_modifiers
       - condition_status
   - name: nlp
-    members:
+    semantic_units:
       - document_type
       - document_encoding
       - document_language
   - name: cancer_procedures
-    members: 
+    semantic_units: 
       - cancer_consult_types
       - encounter_provider_specialty
       - cancer_procedure_types
       - procedures_by_location
   - name: measurements_numeric
-    members:
+    semantic_units:
       - body_size_units
       - body_size_measurements
       - lab_measurements
@@ -43,19 +43,19 @@ valuesets:
       - proms_numeric
       - performance_status_measurements
   - name: staging
-    members:
+    semantic_units:
       - t_stage_concepts
       - n_stage_concepts
       - m_stage_concepts
       - group_stage_concepts
       - stage_edition
   - name: visits
-    members:
+    semantic_units:
       - visit_modalities
   - name: observations
-    members:
+    semantic_units:
       - demography_concepts
       - sact_concepts
   - name: unknowns
-    members:
+    semantic_units:
       - unknowns

{omop_semantics-0.2.1 → omop_semantics-0.2.2}/src/omop_semantics/unknowns.py

@@ -20,7 +20,9 @@ This is a stable public surface. External consumers should import from
     'mapping_failed'
 """
 
+from collections.abc import Mapping
 from dataclasses import dataclass
+from types import MappingProxyType
 from typing import Literal
 
 
@@ -55,7 +57,7 @@ class UnknownValue:
     reason: UnknownReason | None = None
 
 
-UNKNOWN: dict[str, UnknownValue] = {
+UNKNOWN: Mapping[str, UnknownValue] = MappingProxyType({
     "generic":             UnknownValue(4129922,  "Unknown",                                        "missing"),
     "gender":              UnknownValue(4214687,  "Gender Unknown",                                 "missing"),
     "condition":           UnknownValue(44790729, "Unknown problem",                                "mapping_failed"),
@@ -66,6 +68,6 @@ UNKNOWN: dict[str, UnknownValue] = {
     "stage_edition":       UnknownValue(1634449,  "8th",                                            "default_value"),
     "therapeutic_regimen": UnknownValue(4207655,  "prescription of therapeutic regimen",            "mapping_failed"),
     "drug_trial":          UnknownValue(4207655,  "clinical drug trial",                            "ambiguous"),
-}
+})
 
 __all__ = ["UnknownReason", "UnknownValue", "UNKNOWN"]

omop_semantics-0.2.1/PKG-INFO

@@ -1,139 +0,0 @@
-Metadata-Version: 2.3
-Name: omop-semantics
-Version: 0.2.1
-Summary: Define, validate, and use schema-backed semantic conventions for OMOP CDM
-Author: gkennos
-Author-email: gkennos <georgina.kennedy@unsw.edu.au>
-Requires-Dist: ipykernel>=7.2.0
-Requires-Dist: linkml>=1.11.1
-Requires-Dist: linkml-runtime>=1.11.1
-Requires-Dist: python-dotenv>=1.2.2
-Requires-Dist: ruamel-yaml>=0.18.17
-Requires-Dist: typing-extensions>=4.15.0
-Requires-Dist: urllib3>=2.7.0
-Requires-Dist: ipython>=8.0 ; extra == 'dev'
-Requires-Dist: pytest>=7.0 ; extra == 'dev'
-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: pygments>=2.20.0 ; extra == 'dev'
-Requires-Dist: mkdocs-material>=9.7.6 ; extra == 'docs'
-Requires-Dist: mkdocstrings-python>=2.0.1 ; extra == 'docs'
-Requires-Dist: mkdocs>=1.6.1 ; extra == 'docs'
-Requires-Dist: mkdocs-mermaid2-plugin>=1.2.3 ; extra == 'docs'
-Requires-Dist: pygments>=2.20.0 ; extra == 'docs'
-Requires-Python: >=3.12
-Project-URL: Homepage, https://australiancancerdatanetwork.github.io/omop-semantics/
-Project-URL: Repository, https://github.com/AustralianCancerDataNetwork/omop-semantics
-Project-URL: Issues, https://github.com/AustralianCancerDataNetwork/omop-semantics/issues
-Provides-Extra: dev
-Provides-Extra: docs
-Description-Content-Type: text/markdown
-
-# omop_semantics
-
-**omop_semantics** is a Python library for defining and managing **semantic conventions on top of OMOP CDM**.
-
-It lets you describe conventions in code
-
-- which OMOP concepts you want to have on hand as named key concepts to improve ergonomics in analytic code,
-- how they are grouped,
-- what roles they play 
-- and provide profiles to render these targets uniformly into CDM tables.
-
-The goal is to make these conventions **explicit, versioned, and reusable**, instead of being buried in code, SQL, or documentation. They are also extensible so that you can add opinionated layers on top of default specifications that may be relevant in a domain-specific context only.
-
----
-
-## Current structure
-
-The library has three user-facing surfaces:
-
-- **Value-set runtime**
-  For stable named ids and ergonomic downstream access such as
-  `from omop_semantics.runtime.default_valuesets import runtime`.
-
-- **Template/profile runtime**
-  For working with semantic templates, compiled template views, and CDM row
-  shapes via `OmopSemanticEngine`.
-
-- **Fallback concepts**
-  For canonical "unknown", "not recorded", and default concepts via
-  `from omop_semantics.unknowns import UNKNOWN`.
-
-If you are starting new downstream code today:
-
-1. use `runtime.default_valuesets` when you need stable named concept ids,
-2. use `OmopSemanticEngine` when you need templates, profiles, or profile
-   groups,
-3. use `omop_semantics.unknowns` when you need standard fallback concepts and
-   their reason codes.
-
----
-
-## Key ideas
-
-- **Human-authored**  
-  Semantic rules and concept groups are written in YAML and validated with schemas.
-
-- **Portable**  
-  No database or graph store required.
-
-- **Versionable**  
-  Conventions can evolve over time and be tracked in git.
-
-- **Integrates with pipelines**  
-  Can drive ETL logic, validation, and documentation so they stay in sync.
-
----
-
-## Typical workflow
-
-1. **Define a schema**  
-   Describes what kinds of semantic objects and roles exist (e.g. staging,
-   modifiers).
-
-2. **Write YAML instances**  
-   Lists actual OMOP concepts, profiles, and templates used in your project.
-
-3. **Load the runtime surface you need**  
-   Use value sets for named ids, or the semantic engine for template/profile
-   work.
-
-4. **Use it in code**  
-   For validation, cohort logic, ETL constraints, or documentation.
-
----
-
-## When should you use this?
-
-Use **omop_semantics** if you:
-
-- have project-specific rules about which OMOP concepts are valid,  
-- need consistent concept groupings across ETL and analytics,  
-- want semantic conventions to be explicit, testable, and versioned,  
-- are working in domains like oncology where OMOP alone is too permissive.
-
----
-
-## Docs map
-
-- `docs/usage.md`
-  Recommended loading paths for value sets, templates/profiles, fallback
-  concepts, and lower-level helpers.
-
-- `docs/data-model.md`
-  The conceptual distinction between profiles, profile groups, templates, and
-  semantic objects.
-
-- `docs/schema-and-instances.md`
-  Canonical authoring assets and how the shipped schema/instance files are
-  organized.
-
-- `docs/internals.md`
-  Repo structure, public runtime surfaces, and load-time behavior.
-
-- `docs/unknowns.md`
-  Canonical fallback concepts and how to use their reason codes.

omop_semantics-0.2.1/README.md

@@ -1,105 +0,0 @@
-# omop_semantics
-
-**omop_semantics** is a Python library for defining and managing **semantic conventions on top of OMOP CDM**.
-
-It lets you describe conventions in code
-
-- which OMOP concepts you want to have on hand as named key concepts to improve ergonomics in analytic code,
-- how they are grouped,
-- what roles they play 
-- and provide profiles to render these targets uniformly into CDM tables.
-
-The goal is to make these conventions **explicit, versioned, and reusable**, instead of being buried in code, SQL, or documentation. They are also extensible so that you can add opinionated layers on top of default specifications that may be relevant in a domain-specific context only.
-
----
-
-## Current structure
-
-The library has three user-facing surfaces:
-
-- **Value-set runtime**
-  For stable named ids and ergonomic downstream access such as
-  `from omop_semantics.runtime.default_valuesets import runtime`.
-
-- **Template/profile runtime**
-  For working with semantic templates, compiled template views, and CDM row
-  shapes via `OmopSemanticEngine`.
-
-- **Fallback concepts**
-  For canonical "unknown", "not recorded", and default concepts via
-  `from omop_semantics.unknowns import UNKNOWN`.
-
-If you are starting new downstream code today:
-
-1. use `runtime.default_valuesets` when you need stable named concept ids,
-2. use `OmopSemanticEngine` when you need templates, profiles, or profile
-   groups,
-3. use `omop_semantics.unknowns` when you need standard fallback concepts and
-   their reason codes.
-
----
-
-## Key ideas
-
-- **Human-authored**  
-  Semantic rules and concept groups are written in YAML and validated with schemas.
-
-- **Portable**  
-  No database or graph store required.
-
-- **Versionable**  
-  Conventions can evolve over time and be tracked in git.
-
-- **Integrates with pipelines**  
-  Can drive ETL logic, validation, and documentation so they stay in sync.
-
----
-
-## Typical workflow
-
-1. **Define a schema**  
-   Describes what kinds of semantic objects and roles exist (e.g. staging,
-   modifiers).
-
-2. **Write YAML instances**  
-   Lists actual OMOP concepts, profiles, and templates used in your project.
-
-3. **Load the runtime surface you need**  
-   Use value sets for named ids, or the semantic engine for template/profile
-   work.
-
-4. **Use it in code**  
-   For validation, cohort logic, ETL constraints, or documentation.
-
----
-
-## When should you use this?
-
-Use **omop_semantics** if you:
-
-- have project-specific rules about which OMOP concepts are valid,  
-- need consistent concept groupings across ETL and analytics,  
-- want semantic conventions to be explicit, testable, and versioned,  
-- are working in domains like oncology where OMOP alone is too permissive.
-
----
-
-## Docs map
-
-- `docs/usage.md`
-  Recommended loading paths for value sets, templates/profiles, fallback
-  concepts, and lower-level helpers.
-
-- `docs/data-model.md`
-  The conceptual distinction between profiles, profile groups, templates, and
-  semantic objects.
-
-- `docs/schema-and-instances.md`
-  Canonical authoring assets and how the shipped schema/instance files are
-  organized.
-
-- `docs/internals.md`
-  Repo structure, public runtime surfaces, and load-time behavior.
-
-- `docs/unknowns.md`
-  Canonical fallback concepts and how to use their reason codes.