feat: Centralised filtering API of OMOP Queries

[nicoloesch]

Query Filtering Framework for OMOP_Alchemy

Summary

Introduces a composable, extensible query filtering system (ConceptFilter and BaseConceptFilter)
that eliminates code duplication and provides a unified interface for OMOP concept filtering.

Problem

Both omop-emb and omop-graph independently implement identical filtering classes to filter Concept table queries by domain, vocabulary, concept ID, and standardization status:

• omop-emb: EmbeddingConceptFilter
• omop-graph: SearchConstraintConcept

This duplication creates maintenance burden and inhibits circular-import-free sharing of this common pattern.

Solution

New module: omop_alchemy.cdm.query

• BaseConceptFilter: Abstract protocol enforcing consistent apply(query: Select) -> Select interface
• ConceptFilter: Frozen dataclass implementing unified concept filtering
  • Filter by: concept_ids, domains, vocabularies, require_standard
  • Identical behaviour to existing implementations in downstream projects
  • Type-safe and immutable

Benefits

Single Source of Truth — Eliminates ~70 lines of duplicated code
No Circular Imports — Shared library is stable and can be imported by all projects
Extensible Protocol — BaseConceptFilter enables future filter types (measurements, relationships, temporal, etc.)
Backward Compatible — Downstream projects can re-export as aliases for gradual migration

Migration Opportunities

omop-emb: Replace EmbeddingConceptFilter with from omop_alchemy.cdm.query import ConceptFilter
omop-graph: Replace SearchConstraintConcept with from omop_alchemy.cdm.query import ConceptFilter

See docs/api/query-filtering.md for full API documentation and extension guide.

Changes

• Created omop_alchemy/cdm/query/filters.py with BaseConceptFilter protocol and ConceptFilter implementation
• Created omop_alchemy/cdm/query/__init__.py with public exports
• Updated omop_alchemy/cdm/__init__.py to re-export filters
• Added docs/api/query-filtering.md with usage, composition, and extensibility guide