starting handlers folder reorganisation

[gkennos]

Summary

Reorganisation of handlers folder

Checklist

• Applied exactly one label (breaking, feature, fix, dependencies, or chore)
• Tests pass locally (uv run pytest -q)
• Lint passes (uv run ruff check .)

[Copilot]

Pull request overview

This PR reorganizes “handlers” into a new omop_alchemy.toolkit package with explicit tiering (core → episodes → analytics → integrations), while also extending episode/event resolution (including diagnostics) and adding initial oncology + body-metrics analytics plus documentation and tests.

Changes:

• Introduces the omop_alchemy.toolkit tiered architecture (new packages, docs, import-layer contract, optional semantics extra).
• Refactors Episode_EventView.resolved_event resolution to use ModifierTargetMixin-declared targets (with caching) and adds ResolvedEpisodeEvent diagnostics utilities.
• Adds new analytics modules (body metrics, adverse events, oncology) with corresponding tests and documentation updates.

Reviewed changes

Copilot reviewed 65 out of 67 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_episodes_basic.py	Adds tests for episode-event resolution diagnostics and episode children relationship behavior.
tests/test_concept_validation.py	Adds regression tests for standard-concept validation behavior changes.
tests/test_body_metrics.py	Adds unit tests for body metric unit conversion, BMI/BSA, and weight trajectory computations.
tests/test_adverse_events.py	Adds unit tests for CTCAE/Martin weight loss grading helpers.
pyproject.toml	Adds semantics optional extra, dev dependency import-linter, updates classifier, fixes pytest section indentation.
omop_alchemy/toolkit/integrations/meds_standard/init.py	Adds placeholder integration package for MEDS export.
omop_alchemy/toolkit/integrations/init.py	Introduces integrations tier and documents dependency direction.
omop_alchemy/toolkit/episodes/handling/summaries.py	Adds generic drug exposure summarization helpers.
omop_alchemy/toolkit/episodes/handling/resolved_event.py	Adds ResolvedEpisodeEvent + diagnostics and mixin for episode traversal.
omop_alchemy/toolkit/episodes/handling/exposure_series.py	Adds drug exposure resolution from explicit links + optional window fallback.
omop_alchemy/toolkit/episodes/handling/event_windowing.py	Adds bounded episode attachment window logic (handles open-ended episodes).
omop_alchemy/toolkit/episodes/handling/drug_episode.py	Adds DrugEpisodeMixin for exposure retrieval + summaries.
omop_alchemy/toolkit/episodes/handling/dosing.py	Adds shared DoseEvaluability vocabulary.
omop_alchemy/toolkit/episodes/handling/init.py	Defines handling public API surface and exports.
omop_alchemy/toolkit/episodes/derivation/init.py	Adds placeholder derivation tier docs (not yet implemented).
omop_alchemy/toolkit/episodes/init.py	Introduces episodes tier package with stable import surface docs.
omop_alchemy/toolkit/core/units/body_units.py	Adds anthropometric unit concepts + conversion rules with semantics-backed defaults.
omop_alchemy/toolkit/core/units/init.py	Exposes unit conversion public API.
omop_alchemy/toolkit/core/timeline/event_timeline.py	Adjusts imports to the new cdm.model.* paths.
omop_alchemy/toolkit/core/timeline/init.py	Adds timeline tier package exports and docs.
omop_alchemy/toolkit/core/concepts/registry.py	Updates resolver import to new lookup module location.
omop_alchemy/toolkit/core/concepts/normalizers.py	Updates type-checking import to new lookup module location.
omop_alchemy/toolkit/core/concepts/lookup.py	Updates imports to new toolkit/core concepts layout and CDM model paths.
omop_alchemy/toolkit/core/concepts/init.py	Adds stable import surface + exports for concepts layer.
omop_alchemy/toolkit/core/_semantics.py	Adds lazy import helper for optional omop-semantics runtime with install guidance.
omop_alchemy/toolkit/core/init.py	Introduces core tier package docs.
omop_alchemy/toolkit/analytics/oncology/oncology_sact_dosing.py	Adds SACT dose summarization utilities + mixin.
omop_alchemy/toolkit/analytics/oncology/oncology_rt_dosing.py	Adds RT dose summarization utilities + mixin.
omop_alchemy/toolkit/analytics/oncology/oncology_procedure_occurrence.py	Adds oncology-aware procedure view with concept-set membership checks.
omop_alchemy/toolkit/analytics/oncology/oncology_event.py	Adds oncology-aware episode_event resolution targets + mixin.
omop_alchemy/toolkit/analytics/oncology/oncology_episodes.py	Adds OncologyEpisode view composing modality classification + dosing + adverse events.
omop_alchemy/toolkit/analytics/oncology/oncology_drug_exposure.py	Adds oncology-aware drug exposure view with SACT membership checks.
omop_alchemy/toolkit/analytics/oncology/oncology_critical_weight_loss.py	Adds oncology mixin composing body-metrics + adverse-event grading.
omop_alchemy/toolkit/analytics/oncology/concept_sets.py	Adds semantics-backed governed concept sets + caching and SQL membership expressions.
omop_alchemy/toolkit/analytics/oncology/init.py	Defines oncology public API exports.
omop_alchemy/toolkit/analytics/body_metrics/weight_trajectory.py	Adds normalized weight/height series + BMI/BSA + trajectory/change computations.
omop_alchemy/toolkit/analytics/body_metrics/measurement_series.py	Adds measurement resolution via explicit links + episode/person windows.
omop_alchemy/toolkit/analytics/body_metrics/concept_sets.py	Adds semantics-backed body size measurement concept IDs.
omop_alchemy/toolkit/analytics/body_metrics/calculators.py	Adds BodyMetricRules for conversions and BMI/BSA formulas.
omop_alchemy/toolkit/analytics/body_metrics/init.py	Defines body_metrics public API exports and module docs.
omop_alchemy/toolkit/analytics/adverse_events/weight_loss.py	Adds Martin + critical weight loss grading logic.
omop_alchemy/toolkit/analytics/adverse_events/ctcae.py	Adds CTCAE-style percent weight loss grading.
omop_alchemy/toolkit/analytics/adverse_events/init.py	Defines adverse_events public API exports and module docs.
omop_alchemy/toolkit/analytics/init.py	Introduces analytics tier package docs.
omop_alchemy/toolkit/init.py	Introduces top-level toolkit package docs and stable import guidance.
omop_alchemy/cdm/model/structural/episode.py	Adds children relationship to episode context (self-referential traversal).
omop_alchemy/cdm/model/structural/episode_event.py	Refactors event resolution to ModifierTargetMixin mapping + cache + invalidation.
omop_alchemy/cdm/model/structural/init.py	Re-exports clear_episode_event_target_class_cache.
omop_alchemy/cdm/model/clinical/procedure_occurrence.py	Makes procedure occurrences valid episode_event targets via ModifierTargetMixin.
omop_alchemy/cdm/handlers/vocabs_and_mappers/init.py	Removes legacy handlers exports (moved/replaced by toolkit packages).
omop_alchemy/cdm/handlers/timeline/init.py	Removes legacy timeline handlers exports (moved/replaced by toolkit packages).
omop_alchemy/cdm/handlers/init.py	Removes legacy handlers namespace (moved/replaced by toolkit packages).
omop_alchemy/cdm/base/typing.py	Removes unused Protocol and trims imports.
omop_alchemy/cdm/base/modifier_interface.py	Improves typing for modifier target mixin and hybrid expression declaration.
omop_alchemy/cdm/base/concept_validation.py	Fixes standard-concept detection by delegating to Concept.is_standard_expr().
omop_alchemy/cdm/base/init.py	Exports ConceptValidationMixin from cdm.base.
mkdocs.yml	Adds Toolkit section to docs navigation.
docs/toolkit/integrations.md	Adds integrations tier documentation page.
docs/toolkit/index.md	Adds toolkit overview page and tiering explanation.
docs/toolkit/episodes.md	Adds episodes tier documentation page.
docs/toolkit/core.md	Adds core tier documentation page.
docs/toolkit/analytics.md	Adds analytics tier documentation page.
docs/api/typing.md	Updates typing docs to point to new timeline module path; removes ConceptResolver section.
docs/advanced/timelines.md	Updates timeline docs to use new toolkit timeline module paths.
.importlinter	Adds import-linter contract enforcing toolkit tier layering.
.gitignore	Ignores tests/test_meds* artifacts and normalizes docker/ ignore line.

Suppressed comments (3)

omop_alchemy/toolkit/analytics/body_metrics/weight_trajectory.py:176

• pct_change_over divides by earliest_in_window.value without guarding against a zero/negative baseline reading, which can raise ZeroDivisionError for dirty data. Treat non-positive baselines as not evaluable.
  omop_alchemy/toolkit/analytics/body_metrics/weight_trajectory.py:188
• pct_change_trajectory divides by baseline.value for every point; a zero/negative baseline will raise ZeroDivisionError. Treat non-positive baselines as producing no trajectory.
  omop_alchemy/toolkit/analytics/body_metrics/weight_trajectory.py:214
• sustained_loss divides by baseline.value; a zero/negative baseline will raise ZeroDivisionError. For dirty data, return None (unknown) when the baseline is not strictly positive.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.