orchestrator-core 4.5.1a1__py3-none-any.whl → 4.5.3__py3-none-any.whl

orchestrator/search/retrieval/retrievers/hybrid.py

@@ -0,0 +1,277 @@
+# Copyright 2019-2025 SURF, GÉANT.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import TypedDict
+
+from sqlalchemy import BindParameter, Select, and_, bindparam, case, cast, func, literal, or_, select
+from sqlalchemy.sql.expression import ColumnElement, Label
+from sqlalchemy.types import TypeEngine
+
+from orchestrator.db.models import AiSearchIndex
+from orchestrator.search.core.types import SearchMetadata
+
+from ..pagination import PaginationParams
+from .base import Retriever
+
+
+class RrfScoreSqlComponents(TypedDict):
+    """SQL expression components of the RRF hybrid score calculation."""
+
+    rrf_num: ColumnElement
+    perfect: Label
+    beta: ColumnElement
+    rrf_max: ColumnElement
+    fused_num: ColumnElement
+    normalized_score: ColumnElement
+
+
+def compute_rrf_hybrid_score_sql(
+    sem_rank_col: ColumnElement,
+    fuzzy_rank_col: ColumnElement,
+    avg_fuzzy_score_col: ColumnElement,
+    k: int,
+    perfect_threshold: float,
+    n_sources: int = 2,
+    margin_factor: float = 0.05,
+    score_numeric_type: TypeEngine | None = None,
+) -> RrfScoreSqlComponents:
+    """Compute RRF (Reciprocal Rank Fusion) hybrid score as SQL expressions for database execution.
+
+    This function implements the core scoring logic for hybrid search combining semantic
+    and fuzzy ranking. It computes:
+    1. Base RRF score from both ranks
+    2. Perfect match detection and boosting
+    3. Dynamic beta parameter based on k and n_sources
+    4. Normalized final score in [0, 1] range
+
+    Args:
+        sem_rank_col: SQLAlchemy column expression for semantic rank
+        fuzzy_rank_col: SQLAlchemy column expression for fuzzy rank
+        avg_fuzzy_score_col: SQLAlchemy column expression for average fuzzy score
+        k: RRF constant controlling rank influence (typically 60)
+        perfect_threshold: Threshold for perfect match boost (typically 0.9)
+        n_sources: Number of ranking sources being fused (default: 2 for semantic + fuzzy)
+        margin_factor: Margin above rrf_max as fraction (default: 0.05 = 5%)
+        score_numeric_type: SQLAlchemy numeric type for casting scores
+
+    Returns:
+        RrfScoreSqlComponents: Dictionary of SQL expressions for score components
+            - rrf_num: Raw RRF score (cast to numeric type if provided)
+            - perfect: Perfect match flag (1 if avg_fuzzy_score >= threshold, else 0)
+            - beta: Boost amount for perfect matches
+            - rrf_max: Maximum possible RRF score
+            - fused_num: RRF + perfect boost
+            - normalized_score: Final score normalized to [0, 1]
+
+    Note:
+        -   Keep margin_factor small to avoid compressing perfects near 1 after normalization.
+
+        -   The `beta` boost is calculated to be greater than the maximum possible standard
+            RRF score (`rrf_max`). This guarantees that any item flagged as a "perfect" match
+            will always rank above any non-perfect match.
+
+        -   This function assumes that rank columns do not
+            contain `NULL` values. A `NULL` in any rank column will result in a `NULL` final score
+            for that item.
+    """
+    # RRF (rank-based): sum of 1/(k + rank_i) for each ranking source
+    rrf_raw = (1.0 / (k + sem_rank_col)) + (1.0 / (k + fuzzy_rank_col))
+    rrf_num = cast(rrf_raw, score_numeric_type) if score_numeric_type else rrf_raw
+
+    # Perfect flag to boost near perfect fuzzy matches
+    perfect = case((avg_fuzzy_score_col >= perfect_threshold, 1), else_=0).label("perfect_match")
+
+    # Dynamic beta based on k and number of sources
+    # rrf_max = n_sources / (k + 1)
+    k_num = literal(float(k), type_=score_numeric_type) if score_numeric_type else literal(float(k))
+    n_sources_lit = (
+        literal(float(n_sources), type_=score_numeric_type) if score_numeric_type else literal(float(n_sources))
+    )
+    rrf_max = n_sources_lit / (k_num + literal(1.0, type_=score_numeric_type if score_numeric_type else None))
+
+    margin = rrf_max * literal(margin_factor, type_=score_numeric_type if score_numeric_type else None)
+    beta = rrf_max + margin
+
+    # Fused score: RRF + perfect match boost
+    perfect_casted = cast(perfect, score_numeric_type) if score_numeric_type else perfect
+    fused_num = rrf_num + beta * perfect_casted
+
+    # Normalize to [0,1] via the theoretical max (beta + rrf_max)
+    norm_den = beta + rrf_max
+    normalized_score = fused_num / norm_den
+
+    return RrfScoreSqlComponents(
+        rrf_num=rrf_num,
+        perfect=perfect,
+        beta=beta,
+        rrf_max=rrf_max,
+        fused_num=fused_num,
+        normalized_score=normalized_score,
+    )
+
+
+class RrfHybridRetriever(Retriever):
+    """Reciprocal Rank Fusion of semantic and fuzzy ranking with parent-child retrieval."""
+
+    def __init__(
+        self,
+        q_vec: list[float],
+        fuzzy_term: str,
+        pagination_params: PaginationParams,
+        k: int = 60,
+        field_candidates_limit: int = 100,
+    ) -> None:
+        self.q_vec = q_vec
+        self.fuzzy_term = fuzzy_term
+        self.page_after_score = pagination_params.page_after_score
+        self.page_after_id = pagination_params.page_after_id
+        self.k = k
+        self.field_candidates_limit = field_candidates_limit
+
+    def apply(self, candidate_query: Select) -> Select:
+        cand = candidate_query.subquery()
+        q_param: BindParameter[list[float]] = bindparam("q_vec", self.q_vec, type_=AiSearchIndex.embedding.type)
+
+        best_similarity = func.word_similarity(self.fuzzy_term, AiSearchIndex.value)
+        sem_expr = case(
+            (AiSearchIndex.embedding.is_(None), None),
+            else_=AiSearchIndex.embedding.op("<->")(q_param),
+        )
+        sem_val = func.coalesce(sem_expr, literal(1.0)).label("semantic_distance")
+
+        filter_condition = literal(self.fuzzy_term).op("<%")(AiSearchIndex.value)
+
+        field_candidates = (
+            select(
+                AiSearchIndex.entity_id,
+                AiSearchIndex.path,
+                AiSearchIndex.value,
+                sem_val,
+                best_similarity.label("fuzzy_score"),
+            )
+            .select_from(AiSearchIndex)
+            .join(cand, cand.c.entity_id == AiSearchIndex.entity_id)
+            .where(
+                and_(
+                    AiSearchIndex.value_type.in_(self.SEARCHABLE_FIELD_TYPES),
+                    filter_condition,
+                )
+            )
+            .order_by(
+                best_similarity.desc().nulls_last(),
+                sem_expr.asc().nulls_last(),
+                AiSearchIndex.entity_id.asc(),
+            )
+            .limit(self.field_candidates_limit)
+        ).cte("field_candidates")
+
+        entity_scores = (
+            select(
+                field_candidates.c.entity_id,
+                func.avg(field_candidates.c.semantic_distance).label("avg_semantic_distance"),
+                func.avg(field_candidates.c.fuzzy_score).label("avg_fuzzy_score"),
+            ).group_by(field_candidates.c.entity_id)
+        ).cte("entity_scores")
+
+        entity_highlights = (
+            select(
+                field_candidates.c.entity_id,
+                func.first_value(field_candidates.c.value)
+                .over(
+                    partition_by=field_candidates.c.entity_id,
+                    order_by=[field_candidates.c.fuzzy_score.desc(), field_candidates.c.path.asc()],
+                )
+                .label(self.HIGHLIGHT_TEXT_LABEL),
+                func.first_value(field_candidates.c.path)
+                .over(
+                    partition_by=field_candidates.c.entity_id,
+                    order_by=[field_candidates.c.fuzzy_score.desc(), field_candidates.c.path.asc()],
+                )
+                .label(self.HIGHLIGHT_PATH_LABEL),
+            ).distinct(field_candidates.c.entity_id)
+        ).cte("entity_highlights")
+
+        ranked = (
+            select(
+                entity_scores.c.entity_id,
+                entity_scores.c.avg_semantic_distance,
+                entity_scores.c.avg_fuzzy_score,
+                entity_highlights.c.highlight_text,
+                entity_highlights.c.highlight_path,
+                func.dense_rank()
+                .over(
+                    order_by=[entity_scores.c.avg_semantic_distance.asc().nulls_last(), entity_scores.c.entity_id.asc()]
+                )
+                .label("sem_rank"),
+                func.dense_rank()
+                .over(order_by=[entity_scores.c.avg_fuzzy_score.desc().nulls_last(), entity_scores.c.entity_id.asc()])
+                .label("fuzzy_rank"),
+            ).select_from(
+                entity_scores.join(entity_highlights, entity_scores.c.entity_id == entity_highlights.c.entity_id)
+            )
+        ).cte("ranked_results")
+
+        # Compute RRF hybrid score
+        score_components = compute_rrf_hybrid_score_sql(
+            sem_rank_col=ranked.c.sem_rank,
+            fuzzy_rank_col=ranked.c.fuzzy_rank,
+            avg_fuzzy_score_col=ranked.c.avg_fuzzy_score,
+            k=self.k,
+            perfect_threshold=0.9,
+            score_numeric_type=self.SCORE_NUMERIC_TYPE,
+        )
+
+        perfect = score_components["perfect"]
+        normalized_score = score_components["normalized_score"]
+
+        # Round to configured precision
+        score = cast(
+            func.round(cast(normalized_score, self.SCORE_NUMERIC_TYPE), self.SCORE_PRECISION),
+            self.SCORE_NUMERIC_TYPE,
+        ).label(self.SCORE_LABEL)
+
+        stmt = select(
+            ranked.c.entity_id,
+            score,
+            ranked.c.highlight_text,
+            ranked.c.highlight_path,
+            perfect.label("perfect_match"),
+        ).select_from(ranked)
+
+        stmt = self._apply_fused_pagination(stmt, score, ranked.c.entity_id)
+
+        return stmt.order_by(
+            score.desc().nulls_last(),
+            ranked.c.entity_id.asc(),
+        ).params(q_vec=self.q_vec)
+
+    def _apply_fused_pagination(
+        self,
+        stmt: Select,
+        score_column: ColumnElement,
+        entity_id_column: ColumnElement,
+    ) -> Select:
+        """Keyset paginate by fused score + id."""
+        if self.page_after_score is not None and self.page_after_id is not None:
+            score_param = self._quantize_score_for_pagination(self.page_after_score)
+            stmt = stmt.where(
+                or_(
+                    score_column < score_param,
+                    and_(score_column == score_param, entity_id_column > self.page_after_id),
+                )
+            )
+        return stmt
+
+    @property
+    def metadata(self) -> SearchMetadata:
+        return SearchMetadata.hybrid()

orchestrator/search/retrieval/retrievers/semantic.py

@@ -0,0 +1,94 @@
+# Copyright 2019-2025 SURF, GÉANT.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from sqlalchemy import Select, and_, cast, func, literal, or_, select
+from sqlalchemy.sql.expression import ColumnElement
+
+from orchestrator.db.models import AiSearchIndex
+from orchestrator.search.core.types import SearchMetadata
+
+from ..pagination import PaginationParams
+from .base import Retriever
+
+
+class SemanticRetriever(Retriever):
+    """Ranks results based on the minimum semantic vector distance."""
+
+    def __init__(self, vector_query: list[float], pagination_params: PaginationParams) -> None:
+        self.vector_query = vector_query
+        self.page_after_score = pagination_params.page_after_score
+        self.page_after_id = pagination_params.page_after_id
+
+    def apply(self, candidate_query: Select) -> Select:
+        cand = candidate_query.subquery()
+
+        dist = AiSearchIndex.embedding.l2_distance(self.vector_query)
+
+        raw_min = func.min(dist).over(partition_by=AiSearchIndex.entity_id)
+
+        # Normalize score to preserve ordering in accordance with other retrievers:
+        # smaller distance = higher score
+        similarity = literal(1.0, type_=self.SCORE_NUMERIC_TYPE) / (
+            literal(1.0, type_=self.SCORE_NUMERIC_TYPE) + cast(raw_min, self.SCORE_NUMERIC_TYPE)
+        )
+
+        score = cast(
+            func.round(cast(similarity, self.SCORE_NUMERIC_TYPE), self.SCORE_PRECISION), self.SCORE_NUMERIC_TYPE
+        ).label(self.SCORE_LABEL)
+
+        combined_query = (
+            select(
+                AiSearchIndex.entity_id,
+                score,
+                func.first_value(AiSearchIndex.value)
+                .over(partition_by=AiSearchIndex.entity_id, order_by=[dist.asc(), AiSearchIndex.path.asc()])
+                .label(self.HIGHLIGHT_TEXT_LABEL),
+                func.first_value(AiSearchIndex.path)
+                .over(partition_by=AiSearchIndex.entity_id, order_by=[dist.asc(), AiSearchIndex.path.asc()])
+                .label(self.HIGHLIGHT_PATH_LABEL),
+            )
+            .select_from(AiSearchIndex)
+            .join(cand, cand.c.entity_id == AiSearchIndex.entity_id)
+            .where(AiSearchIndex.embedding.isnot(None))
+            .distinct(AiSearchIndex.entity_id)
+        )
+        final_query = combined_query.subquery("ranked_semantic")
+
+        stmt = select(
+            final_query.c.entity_id,
+            final_query.c.score,
+            final_query.c.highlight_text,
+            final_query.c.highlight_path,
+        ).select_from(final_query)
+
+        stmt = self._apply_semantic_pagination(stmt, final_query.c.score, final_query.c.entity_id)
+
+        return stmt.order_by(final_query.c.score.desc().nulls_last(), final_query.c.entity_id.asc())
+
+    @property
+    def metadata(self) -> SearchMetadata:
+        return SearchMetadata.semantic()
+
+    def _apply_semantic_pagination(
+        self, stmt: Select, score_column: ColumnElement, entity_id_column: ColumnElement
+    ) -> Select:
+        """Apply semantic score pagination with precise Decimal handling."""
+        if self.page_after_score is not None and self.page_after_id is not None:
+            score_param = self._quantize_score_for_pagination(self.page_after_score)
+            stmt = stmt.where(
+                or_(
+                    score_column < score_param,
+                    and_(score_column == score_param, entity_id_column > self.page_after_id),
+                )
+            )
+        return stmt

orchestrator/search/retrieval/retrievers/structured.py

@@ -0,0 +1,39 @@
+# Copyright 2019-2025 SURF, GÉANT.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from sqlalchemy import Select, literal, select
+
+from orchestrator.search.core.types import SearchMetadata
+
+from ..pagination import PaginationParams
+from .base import Retriever
+
+
+class StructuredRetriever(Retriever):
+    """Applies a dummy score for purely structured searches with no text query."""
+
+    def __init__(self, pagination_params: PaginationParams) -> None:
+        self.page_after_id = pagination_params.page_after_id
+
+    def apply(self, candidate_query: Select) -> Select:
+        cand = candidate_query.subquery()
+        stmt = select(cand.c.entity_id, literal(1.0).label("score")).select_from(cand)
+
+        if self.page_after_id:
+            stmt = stmt.where(cand.c.entity_id > self.page_after_id)
+
+        return stmt.order_by(cand.c.entity_id.asc())
+
+    @property
+    def metadata(self) -> SearchMetadata:
+        return SearchMetadata.structured()

orchestrator/search/retrieval/utils.py

@@ -1,3 +1,16 @@
+# Copyright 2019-2025 SURF, GÉANT.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 import json
 import re
 
@@ -16,7 +29,7 @@ logger = structlog.get_logger(__name__)
 
 
 def generate_highlight_indices(text: str, term: str) -> list[tuple[int, int]]:
-    """Finds all occurrences of individual words from the term with word boundary matching case-insensitively."""
+    """Finds all occurrences of individual words from the term, including both word boundary and substring matches."""
     if not text or not term:
         return []
 
@@ -24,14 +37,15 @@ def generate_highlight_indices(text: str, term: str) -> list[tuple[int, int]]:
     words = [w.strip() for w in term.split() if w.strip()]
 
     for word in words:
+        # First find word boundary matches
         word_boundary_pattern = rf"\b{re.escape(word)}\b"
-        matches = list(re.finditer(word_boundary_pattern, text, re.IGNORECASE))
-
-        if not matches:
-            substring_pattern = re.escape(word)
-            matches = list(re.finditer(substring_pattern, text, re.IGNORECASE))
+        word_matches = list(re.finditer(word_boundary_pattern, text, re.IGNORECASE))
+        all_matches.extend([(m.start(), m.end()) for m in word_matches])
 
-        all_matches.extend([(m.start(), m.end()) for m in matches])
+        # Then find all substring matches
+        substring_pattern = re.escape(word)
+        substring_matches = list(re.finditer(substring_pattern, text, re.IGNORECASE))
+        all_matches.extend([(m.start(), m.end()) for m in substring_matches])
 
     return sorted(set(all_matches))
 

orchestrator/search/retrieval/validation.py

@@ -1,4 +1,15 @@
-from typing import assert_never
+# Copyright 2019-2025 SURF, GÉANT.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
 from sqlalchemy import select, text
 from sqlalchemy.exc import ProgrammingError
@@ -8,72 +19,48 @@ from orchestrator.db import db
 from orchestrator.db.database import WrappedSession
 from orchestrator.db.models import AiSearchIndex
 from orchestrator.search.core.types import EntityType, FieldType
-from orchestrator.search.filters import (
-    DateRangeFilter,
-    DateValueFilter,
-    EqualityFilter,
-    FilterCondition,
-    FilterTree,
-    LtreeFilter,
-    NumericRangeFilter,
-    NumericValueFilter,
-    PathFilter,
-    StringFilter,
+from orchestrator.search.filters import FilterCondition, FilterTree, LtreeFilter, PathFilter
+from orchestrator.search.filters.definitions import operators_for
+from orchestrator.search.retrieval.exceptions import (
+    EmptyFilterPathError,
+    IncompatibleFilterTypeError,
+    InvalidEntityPrefixError,
+    InvalidLtreePatternError,
+    PathNotFoundError,
 )
 
 
 def is_filter_compatible_with_field_type(filter_condition: FilterCondition, field_type: FieldType) -> bool:
     """Check whether a filter condition is compatible with a given field type.
 
-    Parameters
-    ----------
-    filter_condition : FilterCondition
-        The filter condition instance to check.
-    field_type : FieldType
-        The type of field from the index schema.
+    Args:
+        filter_condition (FilterCondition): The filter condition instance to check.
+        field_type (FieldType): The type of field from the index schema.
 
     Returns:
-    -------
-    bool
-        True if the filter condition is valid for the given field type, False otherwise.
+        bool: True if the filter condition is valid for the given field type, False otherwise.
     """
 
-    match filter_condition:
-        case LtreeFilter():
-            return True  # Filters for path only
-        case DateRangeFilter() | DateValueFilter():
-            return field_type == FieldType.DATETIME
-        case NumericRangeFilter() | NumericValueFilter():
-            return field_type in {FieldType.INTEGER, FieldType.FLOAT}
-        case StringFilter():
-            return field_type == FieldType.STRING
-        case EqualityFilter():
-            return field_type in {
-                FieldType.BOOLEAN,
-                FieldType.UUID,
-                FieldType.BLOCK,
-                FieldType.RESOURCE_TYPE,
-                FieldType.STRING,
-            }
-        case _:
-            assert_never(filter_condition)
+    # LtreeFilter is for path filtering only and is thus compatible with all field types.
+    if isinstance(filter_condition, LtreeFilter):
+        return True
+
+    # Get valid operators for this field type and check if the filter's operator is valid.
+    valid_operators = operators_for(field_type)
+    return filter_condition.op in valid_operators
 
 
 def is_lquery_syntactically_valid(pattern: str, db_session: WrappedSession) -> bool:
     """Validate whether a string is a syntactically correct `lquery` pattern.
 
-    Parameters
-    ----------
-    pattern : str
-        The LTree lquery pattern string to validate.
-    db_session : WrappedSession
-        The database session used to test casting.
+    Args:
+        pattern (str): The LTree lquery pattern string to validate.
+        db_session (WrappedSession): The database session used to test casting.
 
     Returns:
-    -------
-    bool
-        True if the pattern is valid, False if it fails to cast in PostgreSQL.
+        bool: True if the pattern is valid, False if it fails to cast in PostgreSQL.
     """
+
     try:
         with db_session.begin_nested():
             db_session.execute(text("SELECT CAST(:pattern AS lquery)"), {"pattern": pattern})
@@ -86,10 +73,9 @@ def get_structured_filter_schema() -> dict[str, str]:
     """Retrieve all distinct filterable paths and their field types from the index.
 
     Returns:
-    -------
-    Dict[str, str]
-        Mapping of path strings to their corresponding field type values.
+        Dict[str, str]: Mapping of path strings to their corresponding field type values.
     """
+
     stmt = select(AiSearchIndex.path, AiSearchIndex.value_type).distinct().order_by(AiSearchIndex.path)
     result = db.session.execute(stmt)
     return {str(path): value_type.value for path, value_type in result}
@@ -98,16 +84,13 @@ def get_structured_filter_schema() -> dict[str, str]:
 def validate_filter_path(path: str) -> str | None:
     """Check if a given path exists in the index and return its field type.
 
-    Parameters
-    ----------
-    path : str
-        The fully qualified LTree path.
+    Args:
+        path (str): The fully qualified LTree path.
 
     Returns:
-    -------
-    Optional[str]
-        The value type of the field if found, otherwise None.
+        Optional[str]: The value type of the field if found, otherwise None.
     """
+
     stmt = select(AiSearchIndex.value_type).where(AiSearchIndex.path == Ltree(path)).limit(1)
     result = db.session.execute(stmt).scalar_one_or_none()
     return result.value if result else None
@@ -123,47 +106,42 @@ async def complete_filter_validation(filter: PathFilter, entity_type: EntityType
     4. Filter type matches the field's value_type
     5. Path starts with the correct entity type prefix (unless wildcard)
 
-    Parameters
-    ----------
-    filter : PathFilter
-        The filter to validate.
-    entity_type : EntityType
-        The entity type being searched.
+    Args:
+        filter (PathFilter): The filter to validate.
+        entity_type (EntityType): The entity type being searched.
 
     Raises:
-    ------
-    ValueError
-        If any of the validation checks fail.
+        ValueError: If any of the validation checks fail.
     """
+
     # Ltree is a special case
     if isinstance(filter.condition, LtreeFilter):
         lquery_pattern = filter.condition.value
         if not is_lquery_syntactically_valid(lquery_pattern, db.session):
-            raise ValueError(f"Ltree pattern '{lquery_pattern}' has invalid syntax.")
+            raise InvalidLtreePatternError(lquery_pattern)
         return
 
     if not filter.path or not filter.path.strip():
-        raise ValueError("Filter path cannot be empty")
+        raise EmptyFilterPathError()
 
     # 1. Check if path exists in database
     db_field_type_str = validate_filter_path(filter.path)
     if db_field_type_str is None:
-        raise ValueError(f"Path '{filter.path}' does not exist in database schema")
+        raise PathNotFoundError(filter.path)
 
     db_field_type = FieldType(db_field_type_str)
 
     # 2. Check filter compatibility with field type
     if not is_filter_compatible_with_field_type(filter.condition, db_field_type):
-        raise ValueError(
-            f"Filter '{type(filter.condition).__name__}' not compatible with field type '{db_field_type.value}'"
+        expected_operators = operators_for(db_field_type)
+        raise IncompatibleFilterTypeError(
+            filter.condition.op.value, db_field_type.value, filter.path, expected_operators
         )
 
     # 3. Check entity type prefix requirements (unless it's a wildcard path)
     expected_prefix = f"{entity_type.value.lower()}."
     if not filter.path.startswith(expected_prefix) and not filter.path.startswith("*"):
-        raise ValueError(
-            f"Filter path '{filter.path}' must start with '{expected_prefix}' for {entity_type.value} searches."
-        )
+        raise InvalidEntityPrefixError(filter.path, expected_prefix, entity_type.value)
 
 
 async def validate_filter_tree(filters: FilterTree | None, entity_type: EntityType) -> None:

orchestrator/search/schemas/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2019-2025 SURF, GÉANT.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.