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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensolr-haystack
-Version: 0.3.1
+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.3.1 → 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.3.1 → opensolr_haystack-0.5.0}/haystack_integrations/document_stores/opensolr/client.py

@@ -66,6 +66,41 @@ BATCH_EMBED_MAX = 50
 # so it is applied at full strength with no hedging.
 FRESH_BIAS_FUNCTION = "recip(max(0,ms(NOW,creation_date)),3.16e-11,1,1)"
 
+#: Default Fresh Results Bias strength when a caller does not pass one.
+FRESH_BIAS_WEIGHT_DEFAULT = 0.5
+
+
+def fresh_bias_function(weight: Optional[float] = None) -> str:
+    """Build the recency function for a 0.0-1.0 ``weight``.
+
+    Mirrors ``Hybrid_search::fresh_bias_function()`` on opensolr.com, the Drupal module and
+    the WordPress plugin. ``recip(ms, c, 1, 1)`` halves at ``ms = 1/c``, so the weight is a
+    HALF-LIFE on a geometric scale between 365 days at 0.0 and 6 hours at 1.0:
+
+    ==========  ===========================================================
+    weight      meaning
+    ==========  ===========================================================
+    0.0         365-day half-life: technically on, barely visible
+    0.3         41 days
+    0.5         9.6 days (the default)
+    0.7         2.2 days
+    1.0         6 hours: date all but replaces relevance
+    ==========  ===========================================================
+
+    The fixed constant this replaces behaved like 0.0, which is why Fresh looked broken on a
+    news index: a 10-day-old article kept 97% of its multiplier, nowhere near enough to
+    outrank a better-matching older one.
+    """
+    w = FRESH_BIAS_WEIGHT_DEFAULT if weight is None else float(weight)
+    w = max(0.0, min(1.0, w))
+    half_life_days = 365.0 * (0.25 / 365.0) ** w
+    # PHP's %g writes "1.212e-9" where Python's writes "1.212e-09". Numerically identical,
+    # textually not — and this string is compared byte for byte against the platform, the
+    # Drupal module and the WordPress plugin by the prompt/query parity harness. Strip the
+    # padding zero so all five implementations emit the same characters.
+    c = ("%.4g" % (1.0 / (half_life_days * 86400000.0))).replace("e-0", "e-").replace("e+0", "e+")
+    return "recip(max(0,ms(NOW,creation_date))," + c + ",1,1)"
+
 #: The four candidate-selection modes the {!hybrid} parser understands.
 #:
 #: Validated rather than trusted, because the failure is silent: `mode` is interpolated into
@@ -77,7 +112,7 @@ FRESH_BIAS_FUNCTION = "recip(max(0,ms(NOW,creation_date)),3.16e-11,1,1)"
 HYBRID_MODES = ("union", "keywords_required", "meaning_required", "intersection")
 
 
-def apply_fresh_bias(params: Dict[str, Any]) -> Dict[str, Any]:
+def apply_fresh_bias(params: Dict[str, Any], weight: Optional[float] = None) -> Dict[str, Any]:
     """Wrap an already-built ``params["q"]`` so the recency curve multiplies the
     FINAL score. Mutates ``params`` in place and returns it.
 
@@ -99,7 +134,21 @@ def apply_fresh_bias(params: Dict[str, Any]) -> Dict[str, Any]:
     rather than being inlined, so a ``}`` in the user's text cannot close the
     ``{!boost}`` block and leave the remainder to be parsed as query syntax.
     """
-    params["freshBias"] = FRESH_BIAS_FUNCTION
+    # A document with no creation_date evaluates recip() at its MAXIMUM, 1.0 — Solr's
+    # ms(NOW, <missing>) is 0 — so an undated document is scored as if published this
+    # instant and floats to the top of a "newest first" ranking. Require a date instead
+    # of silently promoting the ones that have none.
+    fq = params.get("fq")
+    date_fq = "+creation_date:[* TO *]"
+    if fq is None:
+        params["fq"] = date_fq
+    elif isinstance(fq, list):
+        if date_fq not in fq:
+            params["fq"] = fq + [date_fq]
+    elif fq != date_fq:
+        params["fq"] = [fq, date_fq]
+
+    params["freshBias"] = fresh_bias_function(weight)
     params["freshBiasInner"] = params["q"]
     params["q"] = "{!boost b=$freshBias v=$freshBiasInner}"
     return params
@@ -491,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                                                         #
     # ------------------------------------------------------------------ #
@@ -706,6 +764,7 @@ class OpensolrClient:
         fl: str = "*,score",
         fq: Optional[str] = None,
         fresh_bias: bool = False,
+        fresh_bias_weight: Optional[float] = None,
     ) -> Dict[str, Any]:
         """Hybrid (BM25 + kNN) search via the native ``{!hybrid}`` parser.
 
@@ -745,7 +804,7 @@ class OpensolrClient:
         if fq:
             params["fq"] = fq
         if fresh_bias:
-            apply_fresh_bias(params)
+            apply_fresh_bias(params, fresh_bias_weight)
         return self.solr_select(index, params)
 
     #: RAG context defaults — how many hybrid hits feed the LLM, and how many

{opensolr_haystack-0.3.1 → 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.3.1 → opensolr_haystack-0.5.0}/opensolr_haystack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensolr-haystack
-Version: 0.3.1
+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.3.1 → opensolr_haystack-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensolr-haystack"
-version = "0.3.1"
+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" }