xtrace_sdk.x_vec.retrievers.retriever
=====================================

.. py:module:: xtrace_sdk.x_vec.retrievers.retriever


Attributes
----------

.. autoapisummary::

   xtrace_sdk.x_vec.retrievers.retriever._log


Classes
-------

.. autoapisummary::

   xtrace_sdk.x_vec.retrievers.retriever.Retriever


Functions
---------

.. autoapisummary::

   xtrace_sdk.x_vec.retrievers.retriever._decode_item


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

.. py:data:: _log

.. py:function:: _decode_item(homomorphic_client, ciphertext)

   Top-level helper for multiprocessing — must be picklable.


.. py:class:: Retriever(execution_context, integration, parallel = False)

   Retrieves and decrypts chunks from XTrace using encrypted hamming distance search.

   :param execution_context: Holds AES + homomorphic clients and context ID.
   :param integration: XTrace API integration instance.
   :param parallel: If True, decode hamming distances in parallel using multiprocessing.


   .. py:attribute:: execution_context


   .. py:attribute:: integration


   .. py:attribute:: parallel
      :value: False



   .. py:method:: nn_search_for_ids(query_vector, k = 3, kb_id = '', meta_filter = None, range_filter = None, include_scores = False)
      :async:


      Find the k nearest neighbors by encrypted hamming distance.

      :param query_vector: Float embedding vector to search with.
      :param k: Number of nearest neighbors to return.
      :param kb_id: Knowledge-base ID to search.
      :param meta_filter: Optional metadata filter dict (MongoDB-style operators).
      :param range_filter: Optional ``[min, max]`` range to restrict which chunks are searched.
      :param include_scores: If True, also return the plain hamming distances.

      :returns: List of chunk IDs, or (chunk_ids, scores) if include_scores=True.



   .. py:method:: retrieve_and_decrypt(chunk_ids, kb_id, projection = None)
      :async:


      Fetch chunks by ID and AES-decrypt their content.

      :param chunk_ids: List of chunk IDs to retrieve.
      :param kb_id: Knowledge-base ID the chunks belong to.
      :param projection: Fields to return; defaults to all standard fields.

      :returns: List of dicts with decrypted chunk_content and meta_data.



   .. py:method:: format_context(contexts)
      :staticmethod:


      Format a list of context strings for use in an LLM prompt.