tatlock/tests/agents/librarian/test_hybrid_contract.py

"""
Contract tests for HybridRAG parsing against a recorded live response.

The fixture in fixtures/hybrid_query_recorded.json is a real (recorded)
response from library-desk's POST /query/hybrid. These tests pin the
field mapping (source_type/sources, rrf_score, context, per-item
related_dossiers, keywords dict with nested synonyms) so a drift in
either side shows up as a test failure instead of every result
rendering as "unknown (score: 0.00)".
"""

import json
from pathlib import Path
from unittest.mock import AsyncMock, MagicMock

import httpx
import pytest

from src.agents.librarian.client import HybridRAGResponse, LibraryDeskClient
from src.agents.librarian.tools import SOURCE_ICONS, hybrid_search

FIXTURE_PATH = Path(__file__).parent / "fixtures" / "hybrid_query_recorded.json"


@pytest.fixture
def recorded_response() -> dict:
    """Load the recorded /query/hybrid response."""
    return json.loads(FIXTURE_PATH.read_text())


@pytest.fixture
def client_with_recorded_response(recorded_response):
    """LibraryDeskClient whose httpx client replays the recorded response."""
    mock_response = MagicMock()
    mock_response.json.return_value = recorded_response
    mock_response.raise_for_status = MagicMock()

    mock_httpx = AsyncMock(spec=httpx.AsyncClient)
    mock_httpx.post.return_value = mock_response

    client = LibraryDeskClient(base_url="http://test:8089", api_key="test-key")
    client._client = mock_httpx
    return client


@pytest.mark.unit
class TestHybridRAGContract:
    """Contract tests for parsing the live /query/hybrid response shape."""

    @pytest.mark.asyncio
    async def test_sources_are_not_unknown(self, client_with_recorded_response):
        """Every result maps source_type - nothing falls back to 'unknown'."""
        response = await client_with_recorded_response.hybrid_search(
            "home server infrastructure", user="testuser"
        )

        assert isinstance(response, HybridRAGResponse)
        assert response.results, "recorded fixture must contain results"
        for result in response.results:
            assert result.source != "unknown"
            assert result.source in {"wiki", "web", "volatile", "document"}

    @pytest.mark.asyncio
    async def test_scores_are_non_zero(self, client_with_recorded_response):
        """rrf_score maps to score - no silent 0.00 fallback."""
        response = await client_with_recorded_response.hybrid_search(
            "home server infrastructure", user="testuser"
        )

        for result in response.results:
            assert result.score > 0.0

    @pytest.mark.asyncio
    async def test_sources_list_and_icons(self, client_with_recorded_response):
        """Per-item sources list is parsed and every value has an icon."""
        response = await client_with_recorded_response.hybrid_search(
            "home server infrastructure", user="testuser"
        )

        for result in response.results:
            assert result.sources, f"result '{result.title}' has empty sources"
            for source in result.sources:
                assert source in SOURCE_ICONS, f"no icon for source '{source}'"

    @pytest.mark.asyncio
    async def test_context_maps_to_formatted_context(
        self, client_with_recorded_response
    ):
        """Top-level 'context' field maps to formatted_context."""
        response = await client_with_recorded_response.hybrid_search(
            "home server infrastructure", user="testuser"
        )

        assert response.formatted_context != ""

    @pytest.mark.asyncio
    async def test_keywords_and_synonyms_from_dict(
        self, client_with_recorded_response
    ):
        """keywords is a dict: core_keywords + nested synonyms map."""
        response = await client_with_recorded_response.hybrid_search(
            "home server infrastructure", user="testuser"
        )

        assert response.keywords, "core_keywords should be extracted"
        assert all(isinstance(k, str) for k in response.keywords)
        # synonyms map in the fixture is empty, but must parse to a list
        assert isinstance(response.synonyms, list)

    @pytest.mark.asyncio
    async def test_per_item_related_dossiers(self, client_with_recorded_response):
        """related_dossiers live per result and aggregate to unique titles."""
        response = await client_with_recorded_response.hybrid_search(
            "home server infrastructure", user="testuser"
        )

        per_item = [d for r in response.results for d in r.related_dossiers]
        assert per_item, "recorded fixture contains per-item related_dossiers"
        for dossier in per_item:
            assert "title" in dossier
            assert "tag" in dossier

        assert response.related_dossiers, "top-level titles are aggregated"
        assert len(response.related_dossiers) == len(set(response.related_dossiers))

    @pytest.mark.asyncio
    async def test_payload_never_sends_zero_limits(
        self, client_with_recorded_response
    ):
        """The live service 422s on limits < 1; disabled legs use enable_* flags."""
        await client_with_recorded_response.hybrid_search(
            "home server infrastructure",
            user="testuser",
            web_limit=0,
            document_limit=0,
            volatile_limit=0,
        )

        payload = client_with_recorded_response._client.post.call_args.kwargs["json"]
        config = payload["config"]
        for key in (
            "vector_limit",
            "graph_limit",
            "web_limit",
            "document_limit",
            "volatile_limit",
        ):
            assert config[key] >= 1
        assert config["enable_web"] is False
        assert config["enable_documents"] is False
        assert config["enable_volatile"] is False

    @pytest.mark.asyncio
    async def test_tool_renders_no_unknown_results(self, client_with_recorded_response, monkeypatch):
        """The hybrid_search tool renders real sources and non-zero scores."""

        class _Factory:
            def __call__(self):
                return self

            async def __aenter__(self):
                return client_with_recorded_response

            async def __aexit__(self, *args):
                return None

        monkeypatch.setattr(
            "src.agents.librarian.tools.LibraryDeskClient", _Factory()
        )

        output = await hybrid_search("home server infrastructure")

        assert "unknown" not in output
        assert "score: 0.00" not in output
        assert "•" not in output, "every source value should map to an icon"