xtrace_sdk.x_vec.retrievers.retriever¶

Attributes¶

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

_decode_item(homomorphic_client, ciphertext)

Top-level helper for multiprocessing — must be picklable.

xtrace_sdk.x_vec.retrievers.retriever._decode_item(homomorphic_client, ciphertext)¶

Top-level helper for multiprocessing — must be picklable.

Parameters:

homomorphic_client (xtrace_sdk.x_vec.crypto.hamming_client_base.HammingClientBase)
ciphertext (list[int | bytes])

Return type:

int

class xtrace_sdk.x_vec.retrievers.retriever.Retriever(execution_context, integration, parallel=False)¶

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

Parameters:

execution_context (xtrace_sdk.x_vec.utils.execution_context.ExecutionContext) – Holds AES + homomorphic clients and context ID.
integration (xtrace_sdk.integrations.xtrace.XTraceIntegration) – XTrace API integration instance.
parallel (bool) – If True, decode hamming distances in parallel using multiprocessing.

async nn_search_for_ids(query_vector, k=3, kb_id='', meta_filter=None, range_filter=None, include_scores=False)¶

Find the k nearest neighbors by encrypted hamming distance.

Parameters:

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

Returns:

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

Return type:

list[int] | tuple[list[int], list[int]]

async retrieve_and_decrypt(chunk_ids, kb_id, projection=None)¶

Fetch chunks by ID and AES-decrypt their content.

Parameters:

chunk_ids (list[int]) – List of chunk IDs to retrieve.
kb_id (str) – Knowledge-base ID the chunks belong to.
projection (list[str] | None) – Fields to return; defaults to all standard fields.

Returns:

List of dicts with decrypted chunk_content and meta_data.

Return type:

list[dict]

static format_context(contexts)¶

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