SeekStorm Pure Python REST Client

Pure Python REST client, using httpx (sync and async), for the SeekStorm vector & lexical search server.

seekstorm_client_pure_py is open source licensed under the Apache License 2.0

SeekStorm REST client (Pure Python)

SeekStorm REST client (Python wrapper via PyO3/Maturin)

SeekStorm REST client (Rust)

SeekStorm multi-tenancy search server

SeekStorm in-process search library

Website | Benchmark | Demo | Repository for SeekStorm Python client | Repository for SeekStorm library, server, Rust client | Roadmap | Blog | X

Install

pip install seekstorm-client-pure-py

Quick Start (Sync)

from seekstorm_client import (
  SeekStorm,
  CreateIndexRequest,
  SearchRequestObject,
)

BASE_URL = "http://127.0.0.1:80"
DEMO_API_KEY = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="

client = SeekStorm(base_url=BASE_URL, apikey_base64=DEMO_API_KEY)

schema = [
  {"field": "title", "field_type": "Text", "store": True, "index_lexical": True},
  {"field": "body", "field_type": "Text", "store": True, "index_lexical": True, "longest": True},
  {"field": "url", "field_type": "Text", "store": True, "index_lexical": False},
]

create_request = CreateIndexRequest(
  index_name="demo_index",
  schema=schema,
  similarity="Bm25f",
  tokenizer="UnicodeAlphanumeric",
  stemmer="None",
  document_compression="Snappy",
  ngram_indexing=0,
)

index_id = client.create_index(create_request).index_id

client.index_document(index_id, {"title": "title1", "body": "hello seekstorm", "url": "https://example.org"})
client.commit_index(index_id)

query = SearchRequestObject(query_string="+hello +seekstorm", offset=0, length=10)
result = client.query_index(index_id, query)

print(result.count_total)
client.delete_index(index_id)
client.close()

Quick Start (Async)

import asyncio

from seekstorm_client import AsyncSeekStorm, CreateIndexRequest, SearchRequestObject


async def main() -> None:
  client = AsyncSeekStorm(base_url="http://127.0.0.1:80", apikey_base64="AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")

  request = CreateIndexRequest(
    index_name="demo_async_index",
    schema=[
      {"field": "title", "field_type": "Text", "store": True, "index_lexical": True},
      {"field": "body", "field_type": "Text", "store": True, "index_lexical": True},
    ],
  )

  index_id = (await client.create_index(request)).index_id

  await client.index_document(index_id, {"title": "async", "body": "hello"})
  await client.commit_index(index_id)

  result = await client.query_index(index_id, SearchRequestObject(query_string="+hello"))
  print(result.count_total)

  await client.delete_index(index_id)
  await client.close()


asyncio.run(main())

Dataclasses

The client exposes typed dataclasses for common request/response objects.

Request dataclasses:

• ApikeyQuotaObject
• CreateIndexRequest
• DeleteApikeyRequest
• GetDocumentRequest
• GetIteratorRequest
• SearchRequestObject
• UpdateDocumentRequest
• UpdateDocumentsRequest

Response dataclasses:

• LiveResponse
• ApiKeyResponse
• RemainingApiKeysResponse
• ApikeyInfoResponse
• CreateIndexResponse
• RemainingIndicesResponse
• IndexedDocumentCountResponse
• IndexResponseObject
• IteratorResultItem
• IteratorResult
• DocumentResponse
• PdfResponse
• SearchResultObject

Error type:

• SeekStormApiError (contains status_code and body)

API Key Endpoints

The client supports API key lifecycle endpoints, including create_apikey.

REST routes:

• POST /api/v1/apikey -> create_apikey(...)
• GET /api/v1/apikey -> get_apikey_info(...)
• DELETE /api/v1/apikey -> delete_apikey(...)

Sync example:

from seekstorm_client import SeekStorm, ApikeyQuotaObject

client = SeekStorm(base_url="http://127.0.0.1:80")
master_key = "/iWStCpyfpd/BVlHOFtwnMgrFrmof4jGq/OQDWXQzcM="

quota = ApikeyQuotaObject(
  indices_max=10,
  indices_size_max=100_000_000_000,
  documents_max=100_000_000,
  operations_max=1_000_000_000,
  rate_limit=None,
  demo=True,
)

created = client.create_apikey(master_key, quota)
print(created.api_key_base64)

info = client.get_apikey_info(apikey_base64=created.api_key_base64)
print(len(info.indices))

remaining = client.delete_apikey(created.api_key_base64, master_key)
print(remaining.remaining_api_keys)

client.close()

Method Signatures

Sync client: SeekStorm

SeekStorm(base_url: str, apikey_base64: str | None = None, timeout: float = 30.0)

All endpoint methods accept an optional base_url: str | None = None parameter to override the client default host for that single request.

API key endpoints:

• live() -> LiveResponse
• create_apikey(master_apikey: str, api_key_quota_object: ApikeyQuotaObject) -> ApiKeyResponse
• delete_apikey(apikey_base64: str, master_apikey_base64: str) -> RemainingApiKeysResponse
• get_apikey_info(apikey_base64: str | None = None) -> ApikeyInfoResponse

Index endpoints:

• create_index(request: CreateIndexRequest, apikey_base64: str | None = None) -> CreateIndexResponse
• delete_index(index_id: int, apikey_base64: str | None = None) -> RemainingIndicesResponse
• clear_index(index_id: int, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• commit_index(index_id: int, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• get_index_info(index_id: int, apikey_base64: str | None = None) -> IndexResponseObject

Document endpoints:

• index_document(index_id: int, document: dict, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• index_documents(index_id: int, documents: Sequence[dict], apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• index_pdf(index_id: int, file_path: str | Path, file_date: int, document: bytes, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• get_pdf(index_id: int, doc_id: int, apikey_base64: str | None = None) -> PdfResponse
• get_document(index_id: int, doc_id: int, request: GetDocumentRequest, apikey_base64: str | None = None) -> DocumentResponse
• update_document(index_id: int, request: UpdateDocumentRequest, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• update_documents(index_id: int, request: UpdateDocumentsRequest, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• delete_document_by_docid(index_id: int, doc_id: int, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• delete_documents_by_docid(index_id: int, doc_id_vec: Sequence[int], apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• delete_documents_by_query(index_id: int, query: SearchRequestObject, apikey_base64: str | None = None) -> IndexedDocumentCountResponse
• document_iterator(index_id: int, request: GetIteratorRequest, apikey_base64: str | None = None) -> IteratorResult
• query_index(index_id: int, request: SearchRequestObject, apikey_base64: str | None = None) -> SearchResultObject

Async client: AsyncSeekStorm

AsyncSeekStorm exposes the same endpoint methods as SeekStorm, but all methods are async and must be awaited.

Tests

Make sure the SeekStorm server is running before running tests.

Optional environment variables:

• SEEKSTORM_BASE_URL (default: http://127.0.0.1:80)
• SEEKSTORM_API_KEY (default: demo key)
• SEEKSTORM_MASTER_API_KEY (default in tests is set to the known local dev master key)

Run sync tests:

python -m unittest -v test_client.py

Run async tests:

python -m unittest -v test_async_client.py

Run both suites in one command:

python -m unittest -v test_client.py test_async_client.py