opensolr-haystack 0.4.0__tar.gz → 0.5.0__tar.gz

{opensolr_haystack-0.4.0 → opensolr_haystack-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensolr-haystack
-Version: 0.4.0
+Version: 0.5.0
 Summary: Haystack integration for Opensolr — managed Apache Solr DocumentStore with server-side embeddings and hybrid BM25+kNN retrieval
 Author-email: Opensolr <support@opensolr.com>
 License: MIT
@@ -145,10 +145,37 @@ Don't need vectors? Pure keyword search skips the embedding call entirely —
 zero AI quota, and it works on **any** Opensolr index, including non-vector
 ones and older Solr versions.
 
+## Search by image
+
+Search your index with a **photo** instead of a text query. Opensolr reads the
+picture three ways — visual labels (what it depicts), OCR text (words printed on
+it), and any barcode / QR code — and turns that into an ordinary search. Nothing
+new is stored in Solr; the picture simply becomes words.
+
+```python
+# What the picture reads as (labels, OCR text, barcodes) — no search yet:
+read = store.image_to_words("photo.jpg")   # path, bytes, or base64
+# {'text': 'red running shoe', 'mode': 'clip',
+#  'labels': ['running shoe', 'sneaker'], 'codes': ['0123456789012']}
+
+# Search the index with the picture:
+docs = store.search_by_image("photo.jpg", top_k=4)          # engine picks the best reading
+docs = store.search_by_image("photo.jpg", using="meaning")  # visual labels
+docs = store.search_by_image("photo.jpg", using="text")     # only OCR text
+docs = store.search_by_image("photo.jpg", using="code")     # exact barcode / QR match
+docs = store.search_by_image("photo.jpg", using="all")      # labels + OCR + codes
+```
+
+`search_by_image` forwards the same tuning as `search` — `hybrid`, `lexical`,
+`alpha`, `fresh_bias`, `filters` — so an image query runs through the exact
+hybrid pipeline a text query does.
+
 ## Your index schema
 
 Documents follow the Opensolr document model (`title`, `description`, `text`,
-`meta_*` custom fields). To see the full schema: **Control Panel → click your
+`meta_*` custom fields). The whole schema, every field and every type suffix,
+is explained in the [Index Schema Reference](https://opensolr.com/opensolr-platform-user-documentation/schema-reference).
+To see your own copy: **Control Panel → click your
 index → Configuration → Edit File → schema.xml**. Prefer zero-effort data
 entry? Configure the **Web Crawler** in the Control Panel (Index Tools →
 WebCrawler): add your site URL, validate it, and Opensolr indexes the whole

{opensolr_haystack-0.4.0 → opensolr_haystack-0.5.0}/README.md

@@ -127,10 +127,37 @@ Don't need vectors? Pure keyword search skips the embedding call entirely —
 zero AI quota, and it works on **any** Opensolr index, including non-vector
 ones and older Solr versions.
 
+## Search by image
+
+Search your index with a **photo** instead of a text query. Opensolr reads the
+picture three ways — visual labels (what it depicts), OCR text (words printed on
+it), and any barcode / QR code — and turns that into an ordinary search. Nothing
+new is stored in Solr; the picture simply becomes words.
+
+```python
+# What the picture reads as (labels, OCR text, barcodes) — no search yet:
+read = store.image_to_words("photo.jpg")   # path, bytes, or base64
+# {'text': 'red running shoe', 'mode': 'clip',
+#  'labels': ['running shoe', 'sneaker'], 'codes': ['0123456789012']}
+
+# Search the index with the picture:
+docs = store.search_by_image("photo.jpg", top_k=4)          # engine picks the best reading
+docs = store.search_by_image("photo.jpg", using="meaning")  # visual labels
+docs = store.search_by_image("photo.jpg", using="text")     # only OCR text
+docs = store.search_by_image("photo.jpg", using="code")     # exact barcode / QR match
+docs = store.search_by_image("photo.jpg", using="all")      # labels + OCR + codes
+```
+
+`search_by_image` forwards the same tuning as `search` — `hybrid`, `lexical`,
+`alpha`, `fresh_bias`, `filters` — so an image query runs through the exact
+hybrid pipeline a text query does.
+
 ## Your index schema
 
 Documents follow the Opensolr document model (`title`, `description`, `text`,
-`meta_*` custom fields). To see the full schema: **Control Panel → click your
+`meta_*` custom fields). The whole schema, every field and every type suffix,
+is explained in the [Index Schema Reference](https://opensolr.com/opensolr-platform-user-documentation/schema-reference).
+To see your own copy: **Control Panel → click your
 index → Configuration → Edit File → schema.xml**. Prefer zero-effort data
 entry? Configure the **Web Crawler** in the Control Panel (Index Tools →
 WebCrawler): add your site URL, validate it, and Opensolr indexes the whole

{opensolr_haystack-0.4.0 → opensolr_haystack-0.5.0}/haystack_integrations/document_stores/opensolr/client.py

@@ -540,6 +540,15 @@ class OpensolrClient:
     def ai(self, method: str, **params: Any) -> Any:
         return self._request(AI_BASE, method, params)
 
+    def image_to_text(self, index: str, image_b64: str, top_k: int = 8) -> Dict[str, Any]:
+        """Turn an image into search words via the Opensolr image_to_text API.
+
+        The answer carries ``text`` (the words to search with), ``mode`` ("clip"/"ocr"),
+        ``labels`` (CLIP visual labels, present even in OCR mode) and ``codes``
+        (barcodes / QR codes). No image vector is stored: the picture becomes words.
+        """
+        return self.ai("image_to_text", index_name=index, image=image_b64, top_k=top_k)
+
     # ------------------------------------------------------------------ #
     # management                                                         #
     # ------------------------------------------------------------------ #

{opensolr_haystack-0.4.0 → opensolr_haystack-0.5.0}/haystack_integrations/document_stores/opensolr/store.py

@@ -7,6 +7,8 @@ local embedder component needed at indexing time.
 
 from __future__ import annotations
 
+import base64
+from pathlib import Path
 import json
 import re
 from typing import Any, Dict, List, Optional
@@ -376,6 +378,66 @@ class OpensolrDocumentStore:
     # serialization                                                      #
     # ------------------------------------------------------------------ #
 
+    def image_to_words(self, image, top_k: int = 8) -> Dict[str, Any]:
+        """Read an image and return what it was turned into, without searching yet.
+
+        Returns ``{"text", "mode", "labels", "codes"}``: the best words to search
+        with, whether it was read as visual labels ("clip") or OCR text ("ocr"),
+        the CLIP visual labels (present even in OCR mode), and any barcodes / QR codes.
+        ``image`` is a file path (str/Path) or raw image bytes.
+        """
+        raw = bytes(image) if isinstance(image, (bytes, bytearray)) else Path(image).read_bytes()
+        b64 = base64.b64encode(raw).decode("ascii")
+        ans = self.client.image_to_text(self._index, b64, top_k=top_k)
+        labels = [l["label"] for l in (ans.get("labels") or []) if isinstance(l, dict) and l.get("label")]
+        codes = []
+        for c in (ans.get("codes") or []):
+            text = c.get("text") if isinstance(c, dict) else (c if isinstance(c, str) else None)
+            if text:
+                codes.append(text)
+        return {"text": (ans.get("text") or "").strip(), "mode": ans.get("mode") or "clip", "labels": labels, "codes": codes}
+
+    def search_by_image(
+        self,
+        image,
+        top_k: int = 10,
+        using: str = "auto",
+        filters: Optional[Dict[str, Any]] = None,
+        image_top_k: int = 8,
+        **search_kwargs,
+    ) -> List[Document]:
+        """Search the index with a photo instead of a text query.
+
+        The image is turned into words by :meth:`image_to_words`, then those words
+        run through the normal :meth:`search`, so ``hybrid``, ``lexical``, ``alpha``
+        and ``fresh_bias`` apply via ``search_kwargs``. No image vector is stored.
+
+        ``using``: which reading to search with — ``"auto"`` (the engine's chosen
+        text), ``"meaning"`` (CLIP visual labels), ``"text"`` (OCR text only), or
+        ``"code"`` (the first barcode / QR code), or ``"all"`` (labels + OCR text + barcodes combined).
+        """
+        read = self.image_to_words(image, top_k=image_top_k)
+        if using == "meaning":
+            query = ", ".join(read["labels"])
+        elif using == "text":
+            query = read["text"] if read["mode"] == "ocr" else ""
+        elif using == "code":
+            query = read["codes"][0] if read["codes"] else ""
+            search_kwargs.setdefault("lexical", True)
+        elif using == "all":
+            parts = list(read["labels"])
+            if read["mode"] == "ocr" and read["text"]:
+                parts.append(read["text"])
+            parts.extend(read["codes"])
+            query = ", ".join(p for p in parts if p)
+        elif using == "auto":
+            query = read["text"]
+        else:
+            raise ValueError("using must be one of 'auto', 'meaning', 'text', 'code', 'all'")
+        if not query:
+            return []
+        return self.search(query, top_k=top_k, filters=filters, **search_kwargs)
+
     def to_dict(self) -> Dict[str, Any]:
         return default_to_dict(
             self,

{opensolr_haystack-0.4.0 → opensolr_haystack-0.5.0}/opensolr_haystack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensolr-haystack
-Version: 0.4.0
+Version: 0.5.0
 Summary: Haystack integration for Opensolr — managed Apache Solr DocumentStore with server-side embeddings and hybrid BM25+kNN retrieval
 Author-email: Opensolr <support@opensolr.com>
 License: MIT
@@ -145,10 +145,37 @@ Don't need vectors? Pure keyword search skips the embedding call entirely —
 zero AI quota, and it works on **any** Opensolr index, including non-vector
 ones and older Solr versions.
 
+## Search by image
+
+Search your index with a **photo** instead of a text query. Opensolr reads the
+picture three ways — visual labels (what it depicts), OCR text (words printed on
+it), and any barcode / QR code — and turns that into an ordinary search. Nothing
+new is stored in Solr; the picture simply becomes words.
+
+```python
+# What the picture reads as (labels, OCR text, barcodes) — no search yet:
+read = store.image_to_words("photo.jpg")   # path, bytes, or base64
+# {'text': 'red running shoe', 'mode': 'clip',
+#  'labels': ['running shoe', 'sneaker'], 'codes': ['0123456789012']}
+
+# Search the index with the picture:
+docs = store.search_by_image("photo.jpg", top_k=4)          # engine picks the best reading
+docs = store.search_by_image("photo.jpg", using="meaning")  # visual labels
+docs = store.search_by_image("photo.jpg", using="text")     # only OCR text
+docs = store.search_by_image("photo.jpg", using="code")     # exact barcode / QR match
+docs = store.search_by_image("photo.jpg", using="all")      # labels + OCR + codes
+```
+
+`search_by_image` forwards the same tuning as `search` — `hybrid`, `lexical`,
+`alpha`, `fresh_bias`, `filters` — so an image query runs through the exact
+hybrid pipeline a text query does.
+
 ## Your index schema
 
 Documents follow the Opensolr document model (`title`, `description`, `text`,
-`meta_*` custom fields). To see the full schema: **Control Panel → click your
+`meta_*` custom fields). The whole schema, every field and every type suffix,
+is explained in the [Index Schema Reference](https://opensolr.com/opensolr-platform-user-documentation/schema-reference).
+To see your own copy: **Control Panel → click your
 index → Configuration → Edit File → schema.xml**. Prefer zero-effort data
 entry? Configure the **Web Crawler** in the Control Panel (Index Tools →
 WebCrawler): add your site URL, validate it, and Opensolr indexes the whole

{opensolr_haystack-0.4.0 → opensolr_haystack-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensolr-haystack"
-version = "0.4.0"
+version = "0.5.0"
 description = "Haystack integration for Opensolr — managed Apache Solr DocumentStore with server-side embeddings and hybrid BM25+kNN retrieval"
 readme = "README.md"
 license = { text = "MIT" }