opensolr-haystack 0.2.8__tar.gz → 0.3.0__tar.gz

{opensolr_haystack-0.2.8 → opensolr_haystack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensolr-haystack
-Version: 0.2.8
+Version: 0.3.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
@@ -157,6 +157,33 @@ tuning={"search_mode": "keywords_required", "fw_title": 0.2,
 Defaults match the platform's PHP configuration exactly — customize in the
 Control Panel once, or per call from code.
 
+#### Fresh Results Bias
+
+Rank newer documents higher without hiding anything older. Every score is
+multiplied by a recency curve on `creation_date` — full weight for a document
+published today, about half after a year:
+
+```python
+store.similarity_search_with_score("solar inverter warranty", fresh_bias=True)
+client.hybrid_search(index, query, fresh_bias=True)
+client.ai_answer(index, question, tuning={"fresh_bias": 1})
+```
+
+It **re-orders and never filters**: the hit count is identical either way,
+nothing old becomes unreachable, and a document with no `creation_date` simply
+keeps its place instead of being pushed to the bottom. It applies to all three
+retrieval shapes — vector-only, keyword-only and the fused hybrid ranking —
+because the boost wraps the final score rather than one half of it. Off by
+default.
+
+This is the same control visitors get as the **Fresh** toggle beside the sort
+options on the hosted Opensolr search page, so a query behaves identically here
+and there.
+
+> `fresh_bias` and `freshness_boost` are two different knobs and the names
+> invite confusion. `freshness_boost` is a hard window in **days** — anything
+> older is filtered out and the hit count drops. `fresh_bias` filters nothing.
+
 ## How it's tested
 
 Every release is validated against **live Opensolr infrastructure** — no mocks:

{opensolr_haystack-0.2.8 → opensolr_haystack-0.3.0}/README.md

@@ -139,6 +139,33 @@ tuning={"search_mode": "keywords_required", "fw_title": 0.2,
 Defaults match the platform's PHP configuration exactly — customize in the
 Control Panel once, or per call from code.
 
+#### Fresh Results Bias
+
+Rank newer documents higher without hiding anything older. Every score is
+multiplied by a recency curve on `creation_date` — full weight for a document
+published today, about half after a year:
+
+```python
+store.similarity_search_with_score("solar inverter warranty", fresh_bias=True)
+client.hybrid_search(index, query, fresh_bias=True)
+client.ai_answer(index, question, tuning={"fresh_bias": 1})
+```
+
+It **re-orders and never filters**: the hit count is identical either way,
+nothing old becomes unreachable, and a document with no `creation_date` simply
+keeps its place instead of being pushed to the bottom. It applies to all three
+retrieval shapes — vector-only, keyword-only and the fused hybrid ranking —
+because the boost wraps the final score rather than one half of it. Off by
+default.
+
+This is the same control visitors get as the **Fresh** toggle beside the sort
+options on the hosted Opensolr search page, so a query behaves identically here
+and there.
+
+> `fresh_bias` and `freshness_boost` are two different knobs and the names
+> invite confusion. `freshness_boost` is a hard window in **days** — anything
+> older is filtered out and the hit count drops. `fresh_bias` filters nothing.
+
 ## How it's tested
 
 Every release is validated against **live Opensolr infrastructure** — no mocks:

{opensolr_haystack-0.2.8 → opensolr_haystack-0.3.0}/haystack_integrations/components/retrievers/opensolr/retriever.py

@@ -38,6 +38,7 @@ class OpensolrHybridRetriever:
         alpha: float = 0.5,
         filters: Optional[Dict[str, Any]] = None,
         lexical: bool = False,
+        fresh_bias: bool = False,
     ) -> None:
         self.document_store = document_store
         self.top_k = top_k
@@ -45,6 +46,11 @@ class OpensolrHybridRetriever:
         self.alpha = alpha
         self.filters = filters
         self.lexical = lexical
+        # Threaded through the component because a pipeline never touches the store
+        # directly — run() below is the only door onto OpensolrDocumentStore.search()
+        # for a Haystack user, so an option the component does not carry is an option
+        # that does not exist in a pipeline.
+        self.fresh_bias = fresh_bias
 
     @component.output_types(documents=List[Document])
     def run(
@@ -55,9 +61,14 @@ class OpensolrHybridRetriever:
         alpha: Optional[float] = None,
         filters: Optional[Dict[str, Any]] = None,
         lexical: Optional[bool] = None,
+        fresh_bias: Optional[bool] = None,
     ) -> Dict[str, List[Document]]:
         """Run the retriever. ``alpha``: 0 = all semantic, 1 = all lexical.
-        ``lexical=True`` = pure keyword search, no embedding call."""
+        ``lexical=True`` = pure keyword search, no embedding call.
+        ``fresh_bias=True`` biases the ranking toward recent documents by
+        multiplying each score by a recency curve on ``creation_date``; it
+        re-orders and never filters, so the hit count is unchanged and nothing
+        old becomes unreachable. Off by default."""
         docs = self.document_store.search(
             query=query,
             top_k=top_k if top_k is not None else self.top_k,
@@ -65,6 +76,7 @@ class OpensolrHybridRetriever:
             alpha=alpha if alpha is not None else self.alpha,
             filters=filters if filters is not None else self.filters,
             lexical=lexical if lexical is not None else self.lexical,
+            fresh_bias=fresh_bias if fresh_bias is not None else self.fresh_bias,
         )
         return {"documents": docs}
 
@@ -77,6 +89,10 @@ class OpensolrHybridRetriever:
             alpha=self.alpha,
             filters=self.filters,
             lexical=self.lexical,
+            # Serialized alongside the other search options so a pipeline saved with
+            # the bias on comes back with it on. from_dict() tolerates its absence in
+            # dicts written before this option existed — the constructor defaults it.
+            fresh_bias=self.fresh_bias,
         )
 
     @classmethod