mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/search.py

@@ -0,0 +1,230 @@
+"""Verified catalog search service shared by the public CLI and API consumers.
+
+Three public stores exist, and dispatch between them is by exact name and exact schema rather than
+by discovery: a v1 sealed catalog, a v2 retrieval manifest, and a range-local packed head. The two
+legacy paths below are byte-for-byte what they were -- ``search_catalog`` is the shipped
+``mr-data catalog-search`` entry point and its payload is a published shape -- and the packed path
+is a separate capture that never touches them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.sources.catalog.embedding import EmbeddingBackend
+from mostlyright.data_harness.sources.catalog.entry_v2 import CatalogEntryV2, CatalogFactFilter
+from mostlyright.data_harness.sources.catalog.gating import CatalogRequirement
+from mostlyright.data_harness.sources.catalog.packed_retrieval import (
+    CatalogSearchWorkLimits,
+    detect_public_store_kind,
+)
+from mostlyright.data_harness.sources.catalog.query_trace import (
+    PackedCatalogAnswer,
+    query_catalog_snapshot,
+    query_packed_catalog_with_trace,
+)
+from mostlyright.data_harness.sources.contracts import SourceContractError
+
+PACKED_CATALOG_SEARCH_SCHEMA = "mr-data-catalog-search.packed.v1"
+
+#: The one store-kind dispatcher. It is the packed reader's own, so there is exactly one answer to
+#: "what is installed at this root" and no second copy of it to drift.
+public_store_kind = detect_public_store_kind
+
+
+def _cadence(seconds: int) -> str:
+    names = {
+        86_400: "daily",
+        604_800: "weekly",
+        2_592_000: "monthly",
+        31_536_000: "annual",
+    }
+    return names.get(seconds, f"every-{seconds}-seconds")
+
+
+@dataclass(frozen=True)
+class VerifiedCatalogSearch:
+    payload: dict[str, Any]
+    catalog_bytes: bytes
+    vector_members: tuple[tuple[str, bytes], ...]
+
+
+def capture_catalog_search(
+    *,
+    catalog_root: Path,
+    catalog_manifest_sha256: str,
+    question: str,
+    requirement: CatalogRequirement,
+    limit: int = 5,
+) -> VerifiedCatalogSearch:
+    """Return one machine payload after verified, model-free catalog ranking and facts gating."""
+
+    snapshot = query_catalog_snapshot(
+        directory=catalog_root,
+        expected_catalog_manifest_sha256=catalog_manifest_sha256,
+        question=question,
+        requirement=requirement,
+        limit=limit,
+    )
+    recommendation = snapshot.recommendation
+    trace = snapshot.trace
+    selected_coordinate = next(
+        (item.entry_coordinate for item in trace.candidates if item.disposition == "admitted"),
+        None,
+    )
+    if selected_coordinate is None:
+        raise SourceContractError(
+            "CATALOG_NO_ADMITTED_SOURCE",
+            "catalog",
+            "the verified catalog has no admitted source for this question and requirement",
+        )
+    selected = next(
+        (item for item in snapshot.index.entries if item.coordinate == selected_coordinate), None
+    )
+    traced = next(item for item in trace.candidates if item.entry_coordinate == selected_coordinate)
+    if (
+        selected is None
+        or selected.digest != traced.entry_digest
+        or snapshot.index.backend.descriptor.coordinate != trace.backend_coordinate
+    ):
+        raise SourceContractError(
+            "CATALOG_SNAPSHOT_MISMATCH",
+            "catalog",
+            "the verified snapshot disagrees with its query trace",
+        )
+    entry = selected.to_dict()
+    source_facts = {
+        "format": selected.data_formats[0].upper(),
+        "rights": selected.rights.lawful_basis,
+        "update_cadence": _cadence(selected.observation.update_frequency_seconds),
+    }
+    payload = {
+        "catalog_manifest_sha256": catalog_manifest_sha256,
+        "catalog_root": str(catalog_root),
+        "recommendation": recommendation.to_dict(),
+        "schema_version": "mr-data-catalog-search.v1",
+        "source_facts": source_facts,
+        "selected_entry": entry,
+        "selected_entry_coordinate": selected.coordinate,
+        "selected_entry_digest": selected.digest,
+        "status": "catalog_searched",
+        "trace": trace.to_dict(),
+    }
+    return VerifiedCatalogSearch(payload, snapshot.catalog_bytes, snapshot.vector_members)
+
+
+def search_catalog(
+    *,
+    catalog_root: Path,
+    catalog_manifest_sha256: str,
+    question: str,
+    requirement: CatalogRequirement,
+    limit: int = 5,
+) -> dict[str, Any]:
+    return capture_catalog_search(
+        catalog_root=catalog_root,
+        catalog_manifest_sha256=catalog_manifest_sha256,
+        question=question,
+        requirement=requirement,
+        limit=limit,
+    ).payload
+
+
+@dataclass(frozen=True)
+class VerifiedPackedCatalogSearch:
+    """One packed answer and the bounded evidence that produced it."""
+
+    payload: dict[str, Any]
+    answer: PackedCatalogAnswer
+
+
+def _known(fact: Any) -> Any | None:
+    return fact.value if fact.state == "known" else None
+
+
+def _packed_source_facts(entry: CatalogEntryV2) -> dict[str, Any]:
+    """Only facts this entry actually states. An unknown fact is absent, never guessed."""
+
+    formats = _known(entry.data_formats)
+    facts: dict[str, Any] = {}
+    if formats is not None:
+        facts["format"] = [value.upper() for value in formats]
+    for name in ("rights", "access_kind"):
+        value = _known(getattr(entry, name))
+        if value is not None:
+            facts[name] = value
+    authentication = _known(entry.authentication_required)
+    if authentication is not None:
+        facts["authentication_required"] = authentication
+    return facts
+
+
+def capture_packed_catalog_search(
+    *,
+    catalog_root: Path,
+    expected_head_sha256: str,
+    receipt: Mapping[str, Any],
+    question: str,
+    requirement: CatalogRequirement,
+    backend: EmbeddingBackend,
+    work_limits: CatalogSearchWorkLimits,
+    fact_filters: tuple[CatalogFactFilter, ...] = (),
+    limit: int = 5,
+) -> VerifiedPackedCatalogSearch:
+    """Answer one question from one authenticated packed generation under a stated work budget.
+
+    Three outcomes, and they are told apart rather than collapsed: the search ran out of budget
+    before every unpruned range closed (``catalog_search_incomplete``, and no candidate at all); it
+    completed and the facts admitted nothing (``catalog_no_admitted_source``); or it completed and
+    the first admitted identity is the answer (``catalog_searched``).
+    """
+
+    answer = query_packed_catalog_with_trace(
+        directory=catalog_root,
+        expected_head_sha256=expected_head_sha256,
+        receipt=receipt,
+        backend=backend,
+        question=question,
+        requirement=requirement,
+        work_limits=work_limits,
+        fact_filters=fact_filters,
+        limit=limit,
+    )
+    trace = answer.trace
+    payload: dict[str, Any] = {
+        "catalog_root": str(catalog_root),
+        "head_sha256": trace.head_sha256,
+        "receipt_coordinate_sha256": trace.receipt_coordinate_sha256,
+        "schema_version": PACKED_CATALOG_SEARCH_SCHEMA,
+        "trace": trace.to_dict(),
+    }
+    if answer.status == "incomplete":
+        payload["status"] = "catalog_search_incomplete"
+        payload["incomplete_code"] = answer.incomplete_code
+        return VerifiedPackedCatalogSearch(payload, answer)
+    if not trace.admitted:
+        payload["status"] = "catalog_no_admitted_source"
+        return VerifiedPackedCatalogSearch(payload, answer)
+    coordinate = trace.admitted[0]
+    selected = next(entry for entry in answer.entries if entry.coordinate == coordinate)
+    traced = next(item for item in trace.candidates if item.entry_coordinate == coordinate)
+    if selected.digest != traced.entry_digest:  # pragma: no cover - the trace is built from these
+        raise SourceContractError(
+            "CATALOG_SNAPSHOT_MISMATCH",
+            "catalog",
+            "the packed answer disagrees with its own query trace",
+        )
+    payload["status"] = "catalog_searched"
+    payload["recommendation"] = {
+        "kind": "use_source",
+        "entry_coordinate": coordinate,
+        "entry_digest": selected.digest,
+        "semantic_facts_digest": traced.semantic_facts_digest,
+    }
+    payload["selected_entry_coordinate"] = coordinate
+    payload["selected_entry_digest"] = selected.digest
+    payload["source_facts"] = _packed_source_facts(selected)
+    return VerifiedPackedCatalogSearch(payload, answer)