ducpy.search.search_elements
============================

.. py:module:: ducpy.search.search_elements

.. autoapi-nested-parse::

   Element search helpers for ``.duc`` SQLite databases.

   This module uses a hybrid strategy:

   1. SQLite FTS5 narrows candidates quickly from the searchable DUC tables.
   2. Python applies a second ranking pass that combines:
       - FTS rank
       - exact / prefix / substring behavior
       - token coverage
       - string similarity

   The JSON output is shaped for downstream consumers that need:

   - the original query
   - total raw element hits
   - the ordered list of all matching element ids
   - result rows for individual elements or grouped file-backed elements



Attributes
----------

.. autoapisummary::

   ducpy.search.search_elements.DucSearchResult


Classes
-------

.. autoapisummary::

   ducpy.search.search_elements.DucSearchResult
   ducpy.search.search_elements.DucElementSearchResult
   ducpy.search.search_elements.DucFileSearchResult
   ducpy.search.search_elements.DucSearchResponse


Functions
---------

.. autoapisummary::

   ducpy.search.search_elements.search_duc_elements


Module Contents
---------------

.. py:class:: DucSearchResult

   Compatibility placeholder for exported result types.


.. py:class:: DucElementSearchResult

   One result row for a single element.


   .. py:attribute:: element_id
      :type:  str


   .. py:attribute:: element_type
      :type:  str


   .. py:attribute:: matches
      :type:  list[str]


   .. py:attribute:: score
      :type:  float


   .. py:method:: to_dict() -> dict[str, Any]


.. py:class:: DucFileSearchResult

   One grouped result row for repeated file-backed elements.


   .. py:attribute:: file_id
      :type:  str


   .. py:attribute:: element_type
      :type:  str


   .. py:attribute:: matches
      :type:  list[str]


   .. py:attribute:: score
      :type:  float


   .. py:attribute:: hits
      :type:  int


   .. py:attribute:: element_ids
      :type:  list[str]


   .. py:method:: to_dict() -> dict[str, Any]


.. py:data:: DucSearchResult

.. py:class:: DucSearchResponse

   Search response and JSON export metadata.


   .. py:attribute:: query
      :type:  str


   .. py:attribute:: results
      :type:  list[DucSearchResult]


   .. py:attribute:: total_hits
      :type:  int


   .. py:attribute:: all_element_ids
      :type:  list[str]


   .. py:attribute:: output_path
      :type:  str | None
      :value: None



   .. py:method:: to_dict() -> dict[str, Any]

      Convert the response to a JSON-friendly dictionary.



.. py:function:: search_duc_elements(duc_path: str | pathlib.Path, query: str, *, output_path: str | pathlib.Path | None = None, limit: int = 50) -> DucSearchResponse

   Search DUC elements and export ordered results to JSON.

   Args:
       duc_path: Path to the ``.duc`` SQLite database.
       query: Plain-text search query.
       output_path: Optional JSON output path. When omitted, a file is created
           next to the ``.duc`` file.
       limit: Maximum number of ranked element results to keep.