WonderSearch for Python

Upload files and retrieve relevant passages with matching synchronous and asynchronous clients. Install the SDK from PyPI with pip install wondersearch.

pip install wondersearch

Configure POLYGRES_API_KEY with a workspace API key from Console and POLYGRES_BASE_URL with your API origin. The SDK has no implicit staging or production destination. A read_write key can upload and change the workspace default; a search key retains its existing read/search permissions.

from wondersearch import WonderSearch

with WonderSearch() as client:
    batch = client.upload("handbook.pdf")
    results = client.ask("What is our refund policy?")
    for passage in results.results:
        print(passage.text, passage.document_id, passage.document_revision)

from wondersearch import AsyncWonderSearch


async def search_handbook():
    async with AsyncWonderSearch() as client:
        await client.upload(["handbook.pdf", "policies.docx"])
        return await client.ask("What is our refund policy?")

ask() returns ranked passages and citations, not a generated answer. Empty results is a successful search. Every effort returns at most ten results, or fewer when fewer eligible matches exist. It defaults to the medium effort. The deprecated limit argument remains accepted for compatibility, but is ignored and is not sent to the API. Advanced options include effort, folder_id, group_by_document, timeout_ms (server search budget), and timeout (whole SDK operation budget). The server enforces query length, quotas and enabled efforts.

The SDK has no model-selection argument. Both clients use the model selected by the service operator. The response's model field identifies the model actually used. group_by_document=False permits several matching passages from the same document.

Compare effort="small" and effort="medium" on representative questions from your collection.

Drives

New workspaces have a selected Default drive. Change it on the Storage page or through the SDK:

client.drives.list()
client.drives.get_default()
client.drives.set_default("DRIVE_UUID")
client.upload("handbook.pdf", drive_id="DRIVE_UUID")
client.ask("Refund policy?", drive_id="DRIVE_UUID")

Create a drive with either client:

drive = client.drives.create("Knowledge Base")
print(drive.id, drive.status)
# Async: drive = await client.drives.create("Knowledge Base")

create(name, *, timeout=30, idempotency_key=None) returns a typed Drive. Names are trimmed and must contain 1-120 characters. Creation requires content write permission. The index may still be provisioning when this call returns; creation does not change the shared default. Use drives.set_default(drive.id) to select it explicitly. Reuse an idempotency_key and the same name to retry a creation whose response was lost.

Selection order is the method's drive_id, the client's drive_id, then the shared workspace default. The default is resolved once per operation and remains pinned through retries and polling. Explicit invalid drives never fall back. Changing the shared default affects subsequent calls by all workspace users. You must choose another default before deleting the selected default drive.

Uploads and recovery

upload() accepts a path or a list of paths for PDF, DOCX, TXT and Markdown, each from 1 through 1,000,000,000 bytes. It hashes and streams original bytes, follows proxy or direct transfer instructions, then optionally waits for indexing. Transfer concurrency defaults to three and is configurable with concurrency=1..50. Processing polling starts after the transfer phase, so indexing never occupies a transfer slot. Directories are not traversed. wait=False returns after queuing processing; the transfer phase has a timeout budget of 600 seconds by default. The subsequent processing phase has a separate processing_timeout budget of 600 seconds. Each budget covers its whole batch, including waiting for a slot.

Uploads return an UploadBatch, including for one file. Each receipt includes upload, drive and workspace IDs. Searchable receipts also contain document, operation and snapshot IDs. A fresh document identity is generated by default. Use a stable external_id on single-file uploads to deliberately replace that document with a server-assigned revision.

from wondersearch import UploadBatchError

try:
    batch = client.upload("handbook.pdf", idempotency_key="handbook-update-42")
except UploadBatchError as exc:
    print(exc.batch.files)  # Successful files are preserved.
    print(exc.idempotency_key, exc.drive_id)  # Reuse these for a retry.
    for filename, failure in exc.failures.items():
        print(filename, failure)

Reuse the same paths in the same order, content, metadata, drive and idempotency_key to retry an interrupted upload. Do not change the workspace default between those retries without passing the original explicit drive. Unfinished transfers expire after 24 hours. Durably queued processing and its storage reservation survive that deadline. Creation idempotency still expires after 24 hours; retain receipts and use uploads.resume() for queued work instead of recreating an old batch. SDK recovery is not a persistent upload queue.

For an upload already queued for extraction/indexing:

receipt = client.uploads.resume("UPLOAD_UUID", drive_id="DRIVE_UUID")

If bytes have not been sealed, resume() raises upload_transfer_incomplete and instructs you to repeat upload() with the original operation key. It does not pretend that polling can finish transferring bytes. Cancellation stops local waiting; already accepted server work may continue. A synchronous network request already in flight may finish cleanup after its caller's deadline; outstanding transport work is bounded.

Errors and citations

All API errors derive from PolygresError and expose status, code, request_id, details and retry_after. Unknown server codes remain inspectable. Upload failures retain receipts when a session exists. UploadBatchError retains successes and per-file errors.

Search and mutation retries use the same payload and idempotency key, with at most two retries and bounded backoff. Upload admission receiving upload_limit instead honors Retry-After, adds jitter and waits until the transfer deadline. A search whose replay has expired is never silently re-executed. Supplying your own idempotency_key lets you identify a logical search across invocations.

Search results include passage text and citation identifiers directly. New search responses include the selected model; historical replay responses may omit it. Snapshot IDs, cache counts and timings remain internal. passages.get() requires a separately known snapshot ID, such as one retained from an upload receipt. A current drive snapshot may differ from the snapshot used by a concurrent search, so it is not a substitute for that exact snapshot.

An expired snapshot raises the server error instead of returning newer content. SearchResponse.raw preserves additive response fields, and usage amounts retain the server's exact decimal representation.

Versions

Package versions use semantic versioning and PEP 440 release candidates. 0.2.0 targets API /v1 and is prepared for release. During the 0.x series, minor releases may introduce breaking changes; patch releases contain compatible fixes. From stable v1 onward, removals receive at least 90 days' notice and a migration guide.

Earlier 1.0.0rc* versions were TestPyPI previews. Version 0.1.0 begins the production release series and sorts below those previews. When migrating, after publication explicitly install wondersearch==0.2.0 from PyPI and change imports from polygres_search to wondersearch. Version 0.1.1 corrects the client names to WonderSearch and AsyncWonderSearch. Update imports and constructors from PolygresSearch and AsyncPolygresSearch; the old names are not exported. This initial branding correction is an exception to the patch compatibility policy.

Version 0.2.0 uses the operator-selected model and does not send a model selector. Search returns at most ten results, and the legacy limit argument is ignored. The server enforces the active model's query limit. Retry an uncertain search with the same SDK version, request options, and idempotency key.

Version 0.1.2 makes an additional exception to the patch compatibility policy: upload(timeout=...) now covers transfers rather than the complete upload-and-processing operation. Set processing_timeout explicitly and allocate both budgets when enforcing an overall deadline.

The SDK sends its version on API requests and processes compatibility metadata from the API. Unsupported API majors or explicitly unsupported SDK versions raise SDKCompatibilityError. Supported older versions receive SDKUpgradeWarning; deprecations use SDKDeprecationWarning. Warnings occur at most once per notice per process and can be controlled with Python warning filters or version_warnings=False. Structured notices remain available at client.notices. There is no automatic upgrade or import-time PyPI request.

Development and release

Use a project virtual environment. Run pytest, ruff check, and mypy src, then python -m build --no-isolation. Build tooling includes Hatchling, build, pytest, Ruff and mypy. The wheel needs only HTTPX and packaging plus their transitive dependencies.

Do not publish until package ownership, public metadata and package contents are approved. The release manifest must leave latest_stable_sdk_version null until a corresponding stable release actually exists. Deployment and package publication are separate actions. Python 3.10+ is the target; report the actual tested platforms and interpreter versions for each release.

The supplied tox.ini exercises installed wheels on Python 3.10 through 3.14. Run this matrix on Linux, macOS and Windows before stable publication; missing interpreters are failures rather than silently skipped. Tox is optional release tooling.

License

Licensed under Apache-2.0, matching the Polygres CLI and SDK.

Bulk uploads in 0.1.2

Multi-file uploads automatically use bulk requests when the API advertises support. Reservation and processing-status requests contain at most 50 files; byte transfers still obey concurrency (default 3, maximum 50). Capacity is enforced per drive by the server. Extraction and indexing do not consume transfer slots. wait=False returns only after source bytes have been verified and durably queued.

Use a stable idempotency_key and the same ordered file list when retrying an interrupted call. Reordering the list changes the derived per-file identities. Keep returned receipts and UploadBatchError failures for recovery. This SDK does not persist a local recovery manifest. Explicit single-file replacements use the existing endpoint and replacement quota rules; bulk admission reserves each new file’s full source size.