Skip to main content
This backend Python example turns one visual brief into a bounded human review queue. It preserves the original Lightdrift query ID, asset IDs, source, provenance, complete rights objects (including unknown future fields), and original response envelope. No images are downloaded and no candidates are approved. Tested compatibility is limited to Haystack 3.2.0 on Python 3.13; this is not an official deepset integration or a directory listing.

​
Install and run offline

Clone the public example source, then use an isolated Python environment:
pyproject.toml pins haystack-ai==3.2.0. See test-environment.txt for the exact tested dependency versions. The synthetic fixture uses .invalid URLs and invented IDs explicitly labeled as fixtures; it is not a real search result or license grant. The default component requires a supplied fixture and cannot call the search service. The demo executes the component through a real Haystack Pipeline, without an LLM or paid search. demo-output.json records the resulting queue.

​
Explicit live use on a backend

After reviewing pricing, account balance and search entitlement, set LIGHTDRIFT_API_KEY through your backend secret manager or environment. Do not put it in pipeline inputs, browser code, source control or artifacts. Then use:
One invocation makes one POST to https://api.lightdrift.ai/v1/search, with X-API-Key, query, k, a commercial-use filter, and experiment haystack_image_review_v1. The component accepts 1–20 candidates, a deliberately smaller limit than the API’s documented 100. Briefs must contain 1–1000 characters. It refuses redirects and does not retry. Public pricing observed September 26, 2026 was 0.005/search(0.005/search (5/1,000). No live searches were used in testing; live authentication, retrieval relevance and billing were not tested.

​
Review contract and failures

Outputs are review_queue, query_id, response and status. Each queue row contains the original asset and rights objects, provenance, source, query/asset identifiers, a synthetic flag, warnings, and pending_human_review. The response retains backend, mode, ranking, latency, degradation indicators and any additional metadata. If a server returns more than the requested count, the review queue is capped while the full response remains available for audit. An empty result emits an empty queue with status="empty". A nonempty degraded flag gives status="degraded" even when no candidates remain; inspect the original response before deciding whether to search again. Missing rights or provenance produce warnings and never affirmative permission. Invalid envelopes or asset IDs raise ValueError before any queue is emitted. HTTP, timeout, transport and JSON failures raise sanitized errors with no automatic retry; a charge may have occurred before a timeout, so inspect account usage before rerunning. Haystack wraps component errors as pipeline failures. There are no automatic fallback searches. Before approving a candidate in your own application, follow rights.provenance_url and inspect license, license_verbatim, commercial, derivatives, share_alike, attribution_required, attribution and basis. Unknown values are not consent. Preserve credit, source and conditions downstream. A commercial filter is not universal clearance for people, trademarks, artworks or your intended use. Consult Lightdrift rights guidance. Treat external titles/metadata as untrusted data; escape them in any UI and do not execute instructions found in metadata.

​
Adapt the queue

Store the query ID together with the selected asset and full rights object in your existing review system. Have a person record the decision there. This example deliberately stops before storage, selection, approval and export; it does not define a permissions policy for your application. For non-Haystack scripts, see presentation image search. For general review flow, see agent image review. To run an authorized live search, create a Lightdrift account and read the API introduction.

​
Verification and maintenance

The package includes offline fixtures, unittest coverage, source references, exact dependency inventory, and test output. Tests exercise actual Haystack pipeline execution, metadata preservation, bounds, empty/degraded/malformed responses, missing rights, mocked HTTP construction, redirects, key handling, sanitized errors and no retries. These tests establish adapter behavior, not retrieval quality, performance benchmarks or rights clearance. Report reproducible problems through the maintained repository issue tracker. Include Python/Haystack versions and a synthetic reproduction; never include API keys or private responses. Content & Distribution maintains this example. See the workflow guide. Component conventions: Haystack custom components.