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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensolr-haystack
-Version: 0.3.0
+Version: 0.4.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
@@ -59,6 +59,35 @@ print(result["retriever"]["documents"])
 Note there is **no embedder** in the pipeline — not for documents, not for
 the query. The store embeds server-side at both index and query time.
 
+## Try it without an account
+
+There is a public demo account. Point the package at it and everything in this
+README works immediately, with no signup:
+
+```bash
+export OPENSOLR_EMAIL=mcp@opensolr.com
+export OPENSOLR_API_KEY=420b8b23e7b12dc8ab838932145a5065
+```
+
+`mcp_demo_d1__dense` is already loaded with 300 news articles, so search, filtering
+and grounded answers work the moment you connect. You also get the full write path:
+create your own index on the account, ingest into it, query it, delete it.
+
+Know what you are working with:
+
+- **Anything you create there is deleted after 3 days.** Automatically, without warning
+  or export. That includes indexes you created and every document in them.
+- **The account is shared with everyone reading this.** Your index is visible to them,
+  they can change or delete it, and you can do the same to theirs. Never put anything
+  real, private or client-owned in it.
+- **The limits are per index, and deliberately small.** 200 MB of bandwidth and 50 MB
+  of disk per index. Bandwidth is the one you will hit first: it covers a demo, a
+  tutorial and a proof of concept, and it will not carry an application.
+
+When you want an index that is private, yours and still there next week, get your own
+key — [free 15-day trial, no card](https://opensolr.com/register) — and change the two
+variables above. Nothing else in your code changes.
+
 ## Hybrid retrieval
 
 `OpensolrHybridRetriever` fuses BM25 and kNN scores per document via

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

@@ -41,6 +41,35 @@ print(result["retriever"]["documents"])
 Note there is **no embedder** in the pipeline — not for documents, not for
 the query. The store embeds server-side at both index and query time.
 
+## Try it without an account
+
+There is a public demo account. Point the package at it and everything in this
+README works immediately, with no signup:
+
+```bash
+export OPENSOLR_EMAIL=mcp@opensolr.com
+export OPENSOLR_API_KEY=420b8b23e7b12dc8ab838932145a5065
+```
+
+`mcp_demo_d1__dense` is already loaded with 300 news articles, so search, filtering
+and grounded answers work the moment you connect. You also get the full write path:
+create your own index on the account, ingest into it, query it, delete it.
+
+Know what you are working with:
+
+- **Anything you create there is deleted after 3 days.** Automatically, without warning
+  or export. That includes indexes you created and every document in them.
+- **The account is shared with everyone reading this.** Your index is visible to them,
+  they can change or delete it, and you can do the same to theirs. Never put anything
+  real, private or client-owned in it.
+- **The limits are per index, and deliberately small.** 200 MB of bandwidth and 50 MB
+  of disk per index. Bandwidth is the one you will hit first: it covers a demo, a
+  tutorial and a proof of concept, and it will not carry an application.
+
+When you want an index that is private, yours and still there next week, get your own
+key — [free 15-day trial, no card](https://opensolr.com/register) — and change the two
+variables above. Nothing else in your code changes.
+
 ## Hybrid retrieval
 
 `OpensolrHybridRetriever` fuses BM25 and kNN scores per document via

{opensolr_haystack-0.3.0 → opensolr_haystack-0.4.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
@@ -706,6 +755,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 +795,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.0 → opensolr_haystack-0.4.0}/haystack_integrations/document_stores/opensolr/store.py

@@ -118,6 +118,11 @@ class OpensolrDocumentStore:
 
         store = OpensolrDocumentStore(index="mysite__dense")
         # credentials default to OPENSOLR_EMAIL / OPENSOLR_API_KEY env vars
+        # zero-signup demo pair: mcp@opensolr.com / 420b8b23e7b12dc8ab838932145a5065
+        #   preloaded index mcp_demo_d1__dense (300 news articles); the account is shared publicly,
+        #   others can change or delete what you create, anything created there is deleted after
+        #   3 days, automatically, and limits are per index: 200 MB bandwidth, 50 MB disk
+        # private index that persists: https://opensolr.com/register (free 15-day trial, no card)
         ```
     """
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensolr-haystack
-Version: 0.3.0
+Version: 0.4.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
@@ -59,6 +59,35 @@ print(result["retriever"]["documents"])
 Note there is **no embedder** in the pipeline — not for documents, not for
 the query. The store embeds server-side at both index and query time.
 
+## Try it without an account
+
+There is a public demo account. Point the package at it and everything in this
+README works immediately, with no signup:
+
+```bash
+export OPENSOLR_EMAIL=mcp@opensolr.com
+export OPENSOLR_API_KEY=420b8b23e7b12dc8ab838932145a5065
+```
+
+`mcp_demo_d1__dense` is already loaded with 300 news articles, so search, filtering
+and grounded answers work the moment you connect. You also get the full write path:
+create your own index on the account, ingest into it, query it, delete it.
+
+Know what you are working with:
+
+- **Anything you create there is deleted after 3 days.** Automatically, without warning
+  or export. That includes indexes you created and every document in them.
+- **The account is shared with everyone reading this.** Your index is visible to them,
+  they can change or delete it, and you can do the same to theirs. Never put anything
+  real, private or client-owned in it.
+- **The limits are per index, and deliberately small.** 200 MB of bandwidth and 50 MB
+  of disk per index. Bandwidth is the one you will hit first: it covers a demo, a
+  tutorial and a proof of concept, and it will not carry an application.
+
+When you want an index that is private, yours and still there next week, get your own
+key — [free 15-day trial, no card](https://opensolr.com/register) — and change the two
+variables above. Nothing else in your code changes.
+
 ## Hybrid retrieval
 
 `OpensolrHybridRetriever` fuses BM25 and kNN scores per document via

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

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