sse_lib

Thin Python client for the Semantic Search Engine (SSE) REST API (src/sse_api/ in this repository).

sse_lib is a client-side layer only: it maps Python calls onto the HTTP endpoints of a running SSE backend and turns the JSON answers into small dataclasses. It does not import Django, torch, pymilvus or any other server dependency — the single runtime requirement is requests.

from sse_lib import SSEClient, SearchOptions, GenerativeOptions

client = SSEClient("http://localhost:8271", token="...")

client.create_collection(
    "my_docs",
    "My Documents",
    "Test collection",
    embedder="radlab/polish-bi-encoder-mean",
    reranker="radlab/polish-cross-encoder",
    index_type="HNSW",
    chunking={"max_tokens_in_chunk": 128, "number_of_overlap_tokens": 0},
)
client.upload_files("my_docs", ["invoice.pdf", "regulations.zip"])
client.index_documents("my_docs", ["Some text to index."], category="Notes")

found = client.search("my_docs", "policy on data retention",
                      SearchOptions(max_results=20, rerank_results=True))
answer = client.generate_answer(
    found.query_response_id,
    GenerativeOptions(
        generative_model="radlab/pLLama-3-8B-DPO-L",
        percentage_rank_mass=40,
    ),
)
print(answer.answer)

Chunking belongs to the collection, not to a single call: declare it with create_collection(..., chunking={...}) (or strict_chunking=True to forbid any deviation) and the indexing calls above may leave both keys out — the server takes the settings of the collection. client.embedders_info() returns max_model_length of every embedder, the largest chunk its model can take in (client.rerankers_info() the pair budget of the rerankers). Passing max_tokens_in_chunk / number_of_overlap_tokens per call, or once per client with SSEClient(..., default_indexing_options={...}), still works; a split which cannot exist (overlap >= chunk) raises SSEValueError before the request goes out. percentage_rank_mass of generate_answer is required by the backend and has no library-wide default on purpose.

Installation

From a checkout:

pip install ./sse_lib            # or: pip install -e ./sse_lib  (development)

Once published to a registry, pip install sse-lib is all that is needed — the package is standalone and versioned independently (sse_lib.__version__).

Python 3.9+, requests as the only runtime dependency.

Authentication

Configuration

SSEClient is a context manager; leaving the block closes the HTTP session.

API coverage

Collections may be passed as a name, a Collection returned by create_collection() / list_collections(), or any mapping with a name key. A Collection also carries the settings of the collection: metadata_json, chunking ({} when none was declared) and strict_chunking.

GET documents has two views. The default one lists the names of the documents which take part in the search (list_documents()); with with_disabled=True — and always in list_document_details() — the server adds the deactivated documents together with their id and use_in_search flag. Those identifiers are what document_ids[] of delete_documents and set_documents_use_in_search expects.

send_chat_message(..., collection="my_docs") requires an explicit collection, even if the chat was created with one: the current server resolves the collection from each message request. Omitting it raises SSEValueError before sending.

Set api_prefix="" for deployments without an API path prefix; an explicitly provided empty prefix overrides SSE_API_PREFIX.

Options objects

Single options may also be passed as keyword arguments — the two calls below are equivalent:

client.search("my_docs", "query", SearchOptions(max_results=20, hybrid_search=True))
client.search("my_docs", "query", max_results=20, hybrid_search=True)

Unknown keys in search and generation dictionaries are preserved in extra; unknown indexing keys raise SSEValueError. Per-call dictionaries override only the supplied client defaults, while IndexingOptions instances supply a complete configuration (including their dataclass defaults). Keyword arguments win over both.

Wire-format quirks handled by the client

The backend is not uniform, and these traps are the reason the wrapper exists:

• options of search_with_options, query_options of generative_answer and indexing_options of upload_and_index_files are read with json.loads(), so they are sent as JSON strings;
• indexing_options of add_and_index_texts and options/search_options of the chat endpoints are read as objects, so they are sent as JSON objects;
• uploaded files use the field name files[] and input texts texts[];
• endpoint paths have no trailing slash (that is how Django registers them);
• business errors come back as HTTP 200 with {"status": false, "errors": [...]}.

Return values

Methods return dataclasses (sse_lib.models): Collection, SearchResponse (with .hits of SearchHit), Answer, UploadResult, IndexingResult, DocumentRef, Chat, ChatReply, ChatMessage, ChatHistory. Every one of them keeps the untouched server payload in .raw, and client.request("GET", "some_endpoint") returns the unwrapped body of any endpoint for fields that are not modelled yet.

Errors

All of them derive from SSEError, so a single except SSEError is enough for a coarse handler. Idempotent GET calls are retried on connection errors and on 429/502/503/504; POST is never replayed, because indexing twice is a real side effect.

Development

cd sse_lib
PYTHONPATH=src python -m unittest discover -s tests -v   # no installation needed
python -m pytest .                                        # pytest, if available
black --check . && flake8 .

The tests never open a socket: tests/support.py replaces the HTTP session with a recording double, which pins the exact payloads sent to the API.