luplo.core.search
=================

.. py:module:: luplo.core.search

.. autoapi-nested-parse::

   Search pipeline — glossary expansion → tsquery → optional vector rerank.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /api/luplo/core/search/pipeline/index
   /api/luplo/core/search/tsquery/index


Functions
---------

.. autoapisummary::

   luplo.core.search.search


Package Contents
----------------

.. py:function:: search(conn: psycopg.AsyncConnection[Any], query: str, project_id: str, *, embedding_backend: luplo.core.embedding.EmbeddingBackend | None = None, item_types: list[str] | None = None, system_ids: list[str] | None = None, limit: int = 10, tsquery: str | None = None) -> list[luplo.core.models.SearchResult]
   :async:


   Run the full search pipeline.

   1. **Glossary expand** — ``"vendor"`` → ``"(vendor | shop | NPC벤더)"``.
   2. **tsquery retrieval** — GIN index scan, ``ts_rank`` scoring.
      Over-fetches ``limit * 3`` candidates for reranking headroom.
   3. **Vector rerank** (optional) — if *embedding_backend* is provided
      and is not ``NullEmbedding``, rerank candidates by cosine
      similarity.  Otherwise return tsquery results as-is.

   :param conn: Async psycopg connection.
   :param query: Raw user query string (simple-dialect: word, "phrase", OR,
                 -negation). Glossary expanded. Ignored when *tsquery* is set.
   :param project_id: Project scope.
   :param embedding_backend: Embedding backend for reranking (default null).
   :param item_types: Filter by item types (e.g. ``["decision", "knowledge"]``).
   :param system_ids: Filter by system membership.
   :param limit: Maximum results to return.
   :param tsquery: Optional escape hatch — a raw PostgreSQL ``to_tsquery``
                   expression (e.g. ``"(inventory | 인벤토리) & slot & !deprecated"``).
                   When set, *query* and glossary expansion are bypassed and the
                   string is passed directly to ``to_tsquery('simple', …)``.
                   Caller is responsible for synonym coverage and valid syntax.
                   A malformed expression raises ``InvalidTsquery``.

   :returns: Ranked list of ``SearchResult`` objects.