Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
11.0 KB
Raw Blame
"""
Unit tests for how services/search_service.py applies the score threshold.

OpenSearch DLS adds its role query to every user-scoped search as a
constant-score clause, so a top-level min_score is met by every visible hit.
The threshold must therefore sit inside the query, on the hybrid score.

Verifies:
- a positive threshold wraps the hybrid query in function_score.min_score
- no top-level min_score is sent
- threshold 0 and wildcard queries are not wrapped
- the num_candidates retry still strips num_candidates inside the wrapper
"""

from types import SimpleNamespace

import pytest
from opensearchpy.exceptions import RequestError

from auth_context import (
    set_auth_context,
    set_score_threshold,
    set_search_filters,
    set_search_limit,
    set_search_result_mode,
)
from services.search_service import SearchService


class _OpenSearch:
    """Minimal OpenSearch stub that records every non-agg search body."""

    def __init__(self, reject_num_candidates: bool = False, vector_field: dict | None = None):
        """Initialize request recording and optional rejection of the first search."""
        self.bodies: list[dict] = []
        self._reject_num_candidates = reject_num_candidates
        if vector_field is not None:
            properties = {"chunk_embedding_openai_text_embedding_3_small": vector_field}
            self.indices = SimpleNamespace(get_mapping=self._get_mapping)
            self._mapping = {"documents": {"mappings": {"properties": properties}}}

    async def _get_mapping(self, *, index):
        """Return the configured vector-field mapping."""
        return self._mapping

    async def search(self, *, index, body, params):
        """Return empty results, recording searches and optionally simulating a retry error."""
        # Agg-only probes (embedding space detection, wildcard facets)
        if body.get("size") == 0:
            return {
                "aggregations": {
                    "embedding_spaces": {"buckets": []},
                    "legacy_embedding_models": {"buckets": []},
                }
            }
        self.bodies.append(body)
        if self._reject_num_candidates and len(self.bodies) == 1:
            raise RequestError(
                400,
                "x_content_parse_exception",
                {"error": {"root_cause": [{"reason": "[knn] unknown field [num_candidates]"}]}},
            )
        return {"hits": {"hits": []}, "aggregations": {}}


def _make_service(opensearch: _OpenSearch, monkeypatch) -> SearchService:
    """Build a search service with the supplied client and deterministic embedding stubs."""
    service = object.__new__(SearchService)
    service.session_manager = SimpleNamespace(
        get_user_opensearch_client=lambda user_id, jwt_token: opensearch
    )
    service.models_service = None

    async def _no_embed(body, **_kwargs):
        """Return a fixed query embedding without contacting an embedding provider."""
        return {"data": [{"embedding": [0.1, 0.2]}]}

    monkeypatch.setattr("services.search_service.gateway_embeddings", _no_embed)
    monkeypatch.setattr("services.search_service.get_index_name", lambda: "documents")
    monkeypatch.setattr(
        "services.search_service.get_embedding_model", lambda: "text-embedding-3-small"
    )
    monkeypatch.setattr(
        "services.search_service.get_openrag_config",
        lambda: SimpleNamespace(
            knowledge=SimpleNamespace(embedding_provider="openai"),
            providers=SimpleNamespace(ollama=SimpleNamespace(endpoint=None)),
        ),
    )
    monkeypatch.setattr(
        "services.search_service.get_declared_default_embedding_model",
        lambda _: "text-embedding-3-small",
    )
    return service


def _set_context(score_threshold: float) -> None:
    """Set a test user's search context with the requested score threshold."""
    set_auth_context("user-1", None)
    set_search_filters({})
    set_search_limit(100)
    set_score_threshold(score_threshold)
    set_search_result_mode("chunks")


def _knn_params(query: dict) -> list[dict]:
    """Extract kNN parameters from a hybrid query with or without a score wrapper."""
    hybrid = query.get("function_score", {}).get("query", query)
    knn_queries = hybrid["bool"]["should"][0]["dis_max"]["queries"]
    return [params for knn in knn_queries if "knn" in knn for params in knn["knn"].values()]


@pytest.mark.asyncio
async def test_positive_threshold_applies_inside_the_query(monkeypatch):
    """Verify a positive threshold filters the hybrid score inside function_score."""
    os_client = _OpenSearch()
    service = _make_service(os_client, monkeypatch)
    _set_context(1.0)

    await service.search_tool("MCP")

    body = os_client.bodies[-1]
    assert "min_score" not in body
    function_score = body["query"]["function_score"]
    assert function_score["min_score"] == 1.0
    assert "functions" not in function_score
    assert function_score["query"]["bool"]["minimum_should_match"] == 1


@pytest.mark.asyncio
async def test_zero_threshold_leaves_the_query_unwrapped(monkeypatch):
    """Verify a zero threshold leaves the hybrid query unwrapped and without min_score."""
    os_client = _OpenSearch()
    service = _make_service(os_client, monkeypatch)
    _set_context(0)

    await service.search_tool("MCP")

    body = os_client.bodies[-1]
    assert "min_score" not in body
    assert "function_score" not in body["query"]
    assert "bool" in body["query"]


@pytest.mark.asyncio
async def test_wildcard_query_ignores_the_threshold(monkeypatch):
    """Verify wildcard searches use match_all even when the score threshold is positive."""
    os_client = _OpenSearch()
    service = _make_service(os_client, monkeypatch)
    _set_context(1.0)

    await service.search_tool("*")

    body = os_client.bodies[-1]
    assert "min_score" not in body
    assert body["query"]["bool"]["filter"] == [
        {"bool": {"must_not": [{"terms": {"record_kind": ["web_page_manifest", "web_source"]}}]}}
    ]


@pytest.mark.asyncio
async def test_num_candidates_retry_keeps_the_threshold(monkeypatch):
    """Verify a retry removes unsupported num_candidates while preserving the threshold."""
    os_client = _OpenSearch(reject_num_candidates=True)
    service = _make_service(os_client, monkeypatch)
    _set_context(1.0)

    await service.search_tool("MCP")

    first, retry = os_client.bodies
    assert all("num_candidates" in params for params in _knn_params(first["query"]))
    assert all("num_candidates" not in params for params in _knn_params(retry["query"]))
    assert retry["query"]["function_score"]["min_score"] == 1.0
    assert "min_score" not in retry


@pytest.mark.asyncio
async def test_filters_are_pushed_into_each_knn_clause(monkeypatch):
    """Filters must constrain kNN neighbor selection, not only post-filter the top-k."""
    os_client = _OpenSearch()
    service = _make_service(os_client, monkeypatch)
    _set_context(0)
    set_search_filters({"created_after": "2024-01-01T00:00:00Z"})

    await service.search_tool("MCP")

    params = _knn_params(os_client.bodies[-1]["query"])
    assert params
    date_clause = {"range": {"indexed_time": {"gte": "2024-01-01T00:00:00.000000Z"}}}
    for knn in params:
        # The date range sits beside the chunk-mode exclusion of website manifests.
        assert date_clause in knn["filter"]["bool"]["filter"]


@pytest.mark.asyncio
async def test_knowledge_source_search_keeps_website_page_chunks_for_parent_aggregation(
    monkeypatch,
):
    """The API folds page hits into their source after SearchService ranks them."""
    os_client = _OpenSearch()
    service = _make_service(os_client, monkeypatch)
    _set_context(0)
    set_search_result_mode("knowledge_sources")

    await service.search_tool("baseball")

    filters = os_client.bodies[-1]["query"]["bool"].get("filter", [])
    assert not any(
        clause.get("bool", {}).get("must_not") == [{"exists": {"field": "web_page_id"}}]
        for clause in filters
    )


@pytest.mark.asyncio
async def test_chunk_search_excludes_website_manifests_but_not_page_chunks(monkeypatch):
    """RAG/chunk searches must not retrieve metadata-only website records."""
    os_client = _OpenSearch()
    service = _make_service(os_client, monkeypatch)
    _set_context(0)

    await service.search_tool("baseball")

    filters = os_client.bodies[-1]["query"]["bool"]["filter"]
    assert {"terms": {"record_kind": ["web_page_manifest", "web_source"]}} in [
        clause["bool"]["must_not"][0]
        for clause in filters
        if clause.get("bool", {}).get("must_not")
    ]


_DATE = {"created_after": "2024-01-01T00:00:00Z"}


@pytest.mark.asyncio
@pytest.mark.parametrize("engine", ["jvector", "lucene", "faiss"])
async def test_engines_with_native_filtering_get_the_inner_knn_filter(monkeypatch, engine):
    os_client = _OpenSearch(
        vector_field={"type": "knn_vector", "method": {"engine": engine, "space_type": "l2"}}
    )
    service = _make_service(os_client, monkeypatch)
    _set_context(0)
    set_search_filters(_DATE)

    await service.search_tool("MCP")

    params = _knn_params(os_client.bodies[-1]["query"])
    assert params and all("filter" in knn for knn in params)


@pytest.mark.asyncio
async def test_nmslib_scores_the_filtered_documents_exactly(monkeypatch):
    os_client = _OpenSearch(
        vector_field={
            "type": "knn_vector",
            "method": {"engine": "nmslib", "space_type": "cosinesimil"},
        }
    )
    service = _make_service(os_client, monkeypatch)
    _set_context(0)
    set_search_filters(_DATE)

    await service.search_tool("MCP")

    query = os_client.bodies[-1]["query"]
    assert _knn_params(query) == []  # no native kNN clause for nmslib
    hybrid = query.get("function_score", {}).get("query", query)
    (clause,) = hybrid["bool"]["should"][0]["dis_max"]["queries"]
    script = clause["script_score"]["script"]
    assert script["lang"] == "knn"
    assert script["params"]["space_type"] == "cosinesimil"
    date_clause = {"range": {"indexed_time": {"gte": "2024-01-01T00:00:00.000000Z"}}}
    assert date_clause in clause["script_score"]["query"]["bool"]["filter"]
    assert date_clause in hybrid["bool"]["filter"]  # the outer filter is kept


@pytest.mark.asyncio
async def test_nmslib_chunk_search_without_dates_still_avoids_the_inner_filter(monkeypatch):
    """The chunk-mode record-kind exclusion alone is a filter, so nmslib must not get it inline."""
    os_client = _OpenSearch(vector_field={"type": "knn_vector", "method": {"engine": "nmslib"}})
    service = _make_service(os_client, monkeypatch)
    _set_context(0)

    await service.search_tool("MCP")

    assert _knn_params(os_client.bodies[-1]["query"]) == []


@pytest.mark.asyncio
async def test_unreadable_mapping_keeps_the_native_knn_filter(monkeypatch):
    os_client = _OpenSearch()  # no `indices`: the mapping cannot be read
    service = _make_service(os_client, monkeypatch)
    _set_context(0)
    set_search_filters(_DATE)

    await service.search_tool("MCP")

    params = _knn_params(os_client.bodies[-1]["query"])
    assert params and all("filter" in knn for knn in params)