opensolr-haystack 0.1.0__tar.gz

opensolr_haystack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opensolr SRL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opensolr_haystack-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: opensolr-haystack
+Version: 0.1.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
+Project-URL: Homepage, https://opensolr.com/langchain
+Project-URL: Repository, https://github.com/phpcip/opensolr-haystack
+Keywords: haystack,opensolr,solr,vector,hybrid-search,rag,document-store
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: haystack-ai>=2.0.0
+Requires-Dist: httpx>=0.25.0
+Dynamic: license-file
+
+# opensolr-haystack
+
+[Haystack](https://haystack.deepset.ai) integration for
+[Opensolr](https://opensolr.com) — managed Apache Solr as a DocumentStore,
+with **server-side embeddings** and native **hybrid (BM25 + kNN) retrieval**.
+
+No embedder components needed in your pipeline — texts and queries are
+embedded on Opensolr's GPU infrastructure (multilingual E5-large-instruct,
+1024 dimensions, cosine).
+
+**Product page:** [opensolr.com/langchain](https://opensolr.com/langchain) ·
+free 15-day trial, no card, at [opensolr.com](https://opensolr.com)
+
+```bash
+pip install opensolr-haystack
+```
+
+## Quickstart
+
+```python
+from haystack import Document, Pipeline
+from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore
+from haystack_integrations.components.retrievers.opensolr import OpensolrHybridRetriever
+
+# credentials default to OPENSOLR_EMAIL / OPENSOLR_API_KEY env vars
+store = OpensolrDocumentStore(index="mysite__dense", create_if_missing=True)
+
+store.write_documents([
+    Document(content="Hybrid search fuses BM25 with vector similarity"),
+    Document(content="Cats sleep sixteen hours a day"),
+])
+
+pipe = Pipeline()
+pipe.add_component("retriever", OpensolrHybridRetriever(document_store=store))
+result = pipe.run({"retriever": {"query": "how do keyword and semantic search combine?"}})
+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.
+
+## Hybrid retrieval
+
+`OpensolrHybridRetriever` fuses BM25 and kNN scores per document via
+Opensolr's native `{!hybrid}` Solr query parser:
+
+```python
+OpensolrHybridRetriever(
+    document_store=store,
+    top_k=10,
+    hybrid=True,     # False = pure semantic kNN
+    alpha=0.5,       # 0 = all semantic … 1 = all lexical
+)
+```
+
+Standard Haystack filters are supported and map to Solr `fq`:
+
+```python
+pipe.run({"retriever": {
+    "query": "search engines",
+    "filters": {"field": "meta.category", "operator": "==", "value": "docs"},
+}})
+```
+
+## Notes
+
+- Vector-enabled indexes run on Opensolr's Solr 9.x environments — currently
+  `us` (Chicago), `de` (Germany), `fi` (Finland). **Additional dedicated
+  regions can be deployed on request** (paid add-on):
+  [support@opensolr.com](mailto:support@opensolr.com).
+- Every index is also plain Apache Solr with the native `/select` API —
+  facets, highlighting, spellcheck included.
+- Siblings: [`langchain-opensolr`](https://pypi.org/project/langchain-opensolr/) ·
+  [`llama-index-opensolr`](https://pypi.org/project/llama-index-opensolr/) ·
+  [`opensolr-mcp`](https://pypi.org/project/opensolr-mcp/)
+
+MIT license.

opensolr_haystack-0.1.0/README.md

@@ -0,0 +1,77 @@
+# opensolr-haystack
+
+[Haystack](https://haystack.deepset.ai) integration for
+[Opensolr](https://opensolr.com) — managed Apache Solr as a DocumentStore,
+with **server-side embeddings** and native **hybrid (BM25 + kNN) retrieval**.
+
+No embedder components needed in your pipeline — texts and queries are
+embedded on Opensolr's GPU infrastructure (multilingual E5-large-instruct,
+1024 dimensions, cosine).
+
+**Product page:** [opensolr.com/langchain](https://opensolr.com/langchain) ·
+free 15-day trial, no card, at [opensolr.com](https://opensolr.com)
+
+```bash
+pip install opensolr-haystack
+```
+
+## Quickstart
+
+```python
+from haystack import Document, Pipeline
+from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore
+from haystack_integrations.components.retrievers.opensolr import OpensolrHybridRetriever
+
+# credentials default to OPENSOLR_EMAIL / OPENSOLR_API_KEY env vars
+store = OpensolrDocumentStore(index="mysite__dense", create_if_missing=True)
+
+store.write_documents([
+    Document(content="Hybrid search fuses BM25 with vector similarity"),
+    Document(content="Cats sleep sixteen hours a day"),
+])
+
+pipe = Pipeline()
+pipe.add_component("retriever", OpensolrHybridRetriever(document_store=store))
+result = pipe.run({"retriever": {"query": "how do keyword and semantic search combine?"}})
+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.
+
+## Hybrid retrieval
+
+`OpensolrHybridRetriever` fuses BM25 and kNN scores per document via
+Opensolr's native `{!hybrid}` Solr query parser:
+
+```python
+OpensolrHybridRetriever(
+    document_store=store,
+    top_k=10,
+    hybrid=True,     # False = pure semantic kNN
+    alpha=0.5,       # 0 = all semantic … 1 = all lexical
+)
+```
+
+Standard Haystack filters are supported and map to Solr `fq`:
+
+```python
+pipe.run({"retriever": {
+    "query": "search engines",
+    "filters": {"field": "meta.category", "operator": "==", "value": "docs"},
+}})
+```
+
+## Notes
+
+- Vector-enabled indexes run on Opensolr's Solr 9.x environments — currently
+  `us` (Chicago), `de` (Germany), `fi` (Finland). **Additional dedicated
+  regions can be deployed on request** (paid add-on):
+  [support@opensolr.com](mailto:support@opensolr.com).
+- Every index is also plain Apache Solr with the native `/select` API —
+  facets, highlighting, spellcheck included.
+- Siblings: [`langchain-opensolr`](https://pypi.org/project/langchain-opensolr/) ·
+  [`llama-index-opensolr`](https://pypi.org/project/llama-index-opensolr/) ·
+  [`opensolr-mcp`](https://pypi.org/project/opensolr-mcp/)
+
+MIT license.

opensolr_haystack-0.1.0/haystack_integrations/components/retrievers/opensolr/__init__.py

@@ -0,0 +1,7 @@
+"""Opensolr retriever component for Haystack pipelines."""
+
+from haystack_integrations.components.retrievers.opensolr.retriever import (
+    OpensolrHybridRetriever,
+)
+
+__all__ = ["OpensolrHybridRetriever"]

opensolr_haystack-0.1.0/haystack_integrations/components/retrievers/opensolr/retriever.py

@@ -0,0 +1,81 @@
+"""Hybrid retriever component over :class:`OpensolrDocumentStore`.
+
+Takes a plain-text query — embedding happens server-side on Opensolr's GPU
+infrastructure, so no query-embedder component is needed in the pipeline.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from haystack import Document, component, default_from_dict, default_to_dict
+
+from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore
+
+
+@component
+class OpensolrHybridRetriever:
+    """Retrieve documents from Opensolr with hybrid BM25 + kNN scoring.
+
+    Example:
+        ```python
+        from haystack import Pipeline
+        from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore
+        from haystack_integrations.components.retrievers.opensolr import OpensolrHybridRetriever
+
+        store = OpensolrDocumentStore(index="mysite__dense")
+        pipe = Pipeline()
+        pipe.add_component("retriever", OpensolrHybridRetriever(document_store=store))
+        result = pipe.run({"retriever": {"query": "affordable restaurants"}})
+        ```
+    """
+
+    def __init__(
+        self,
+        document_store: OpensolrDocumentStore,
+        top_k: int = 10,
+        hybrid: bool = True,
+        alpha: float = 0.5,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.document_store = document_store
+        self.top_k = top_k
+        self.hybrid = hybrid
+        self.alpha = alpha
+        self.filters = filters
+
+    @component.output_types(documents=List[Document])
+    def run(
+        self,
+        query: str,
+        top_k: Optional[int] = None,
+        hybrid: Optional[bool] = None,
+        alpha: Optional[float] = None,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, List[Document]]:
+        """Run the retriever. ``alpha``: 0 = all semantic, 1 = all lexical."""
+        docs = self.document_store.search(
+            query=query,
+            top_k=top_k if top_k is not None else self.top_k,
+            hybrid=hybrid if hybrid is not None else self.hybrid,
+            alpha=alpha if alpha is not None else self.alpha,
+            filters=filters if filters is not None else self.filters,
+        )
+        return {"documents": docs}
+
+    def to_dict(self) -> Dict[str, Any]:
+        return default_to_dict(
+            self,
+            document_store=self.document_store.to_dict(),
+            top_k=self.top_k,
+            hybrid=self.hybrid,
+            alpha=self.alpha,
+            filters=self.filters,
+        )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "OpensolrHybridRetriever":
+        data["init_parameters"]["document_store"] = OpensolrDocumentStore.from_dict(
+            data["init_parameters"]["document_store"]
+        )
+        return default_from_dict(cls, data)

opensolr_haystack-0.1.0/haystack_integrations/document_stores/opensolr/__init__.py

@@ -0,0 +1,6 @@
+"""Opensolr DocumentStore for Haystack — managed Apache Solr with server-side
+embeddings and native hybrid (BM25 + kNN) search."""
+
+from haystack_integrations.document_stores.opensolr.store import OpensolrDocumentStore
+
+__all__ = ["OpensolrDocumentStore"]

opensolr_haystack-0.1.0/haystack_integrations/document_stores/opensolr/client.py

@@ -0,0 +1,227 @@
+"""Thin REST client for the Opensolr platform APIs.
+
+Two base URLs, by platform design:
+- Management API (index list/info/create): https://opensolr.com/solr_manager/api
+- AI API (embed, batch_embed, embed_and_search, ai_summary): https://api.opensolr.com/solr_manager/api
+
+Direct Solr access (select/update) goes to the index's own host, resolved via
+``get_core_info`` (``connection_url`` + HTTP basic auth).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+MGMT_BASE = "https://opensolr.com/solr_manager/api"
+AI_BASE = "https://api.opensolr.com/solr_manager/api"
+
+#: Convenience aliases for Opensolr's vector-enabled environments. The
+#: authoritative list is served live by the platform (``vector_regions``
+#: endpoint) — new regions become valid automatically, and additional
+#: dedicated regions can be deployed on request (paid): support@opensolr.com.
+VECTOR_LOCATIONS: Dict[str, str] = {
+    "us": "CHICAGO-96",
+    "de": "DE-SOLR-9",
+    "fi": "FINLAND9",
+}
+
+
+def resolve_location(location: str) -> str:
+    """Map a friendly alias ("us"/"de"/"fi") to its environment identifier.
+
+    Unknown values pass through unchanged — validity is decided against the
+    live ``vector_regions`` list (or, ultimately, by the server), so newly
+    deployed vector regions work without a package upgrade.
+    """
+    return VECTOR_LOCATIONS.get(location.strip().lower(), location.strip())
+
+#: Server-side limit for one batch_embed call.
+BATCH_EMBED_MAX = 50
+
+
+class OpensolrError(RuntimeError):
+    """Raised when an Opensolr API call fails."""
+
+
+class OpensolrClient:
+    """Authenticated client for Opensolr management + AI endpoints.
+
+    Args:
+        email: Opensolr account email.
+        api_key: Opensolr API key (Account > API in the control panel).
+        timeout: Per-request timeout in seconds. Embedding calls run on GPU
+            infrastructure and are usually fast, but cold starts happen.
+    """
+
+    def __init__(self, email: str, api_key: str, timeout: float = 120.0) -> None:
+        self.email = email
+        self.api_key = api_key
+        self._http = httpx.Client(timeout=timeout, follow_redirects=True)
+        self._core_info_cache: Dict[str, Dict[str, Any]] = {}
+
+    # ------------------------------------------------------------------ #
+    # low level                                                          #
+    # ------------------------------------------------------------------ #
+
+    def _auth_params(self) -> Dict[str, str]:
+        return {"email": self.email, "api_key": self.api_key}
+
+    def _request(self, base: str, method: str, params: Dict[str, Any]) -> Any:
+        url = f"{base}/{method}"
+        data = {**self._auth_params(), **params}
+        resp = self._http.post(url, data=data)
+        if resp.status_code >= 500:
+            raise OpensolrError(f"{method}: HTTP {resp.status_code}: {resp.text[:200]}")
+        try:
+            body = resp.json()
+        except json.JSONDecodeError as exc:
+            raise OpensolrError(f"{method}: non-JSON response: {resp.text[:200]}") from exc
+        if isinstance(body, dict) and body.get("status") is False:
+            raise OpensolrError(f"{method}: {body.get('msg', body)}")
+        return body
+
+    def mgmt(self, method: str, **params: Any) -> Any:
+        return self._request(MGMT_BASE, method, params)
+
+    def ai(self, method: str, **params: Any) -> Any:
+        return self._request(AI_BASE, method, params)
+
+    # ------------------------------------------------------------------ #
+    # management                                                         #
+    # ------------------------------------------------------------------ #
+
+    def get_index_list(self) -> List[Dict[str, str]]:
+        return self.mgmt("get_index_list")
+
+    def get_core_info(self, index: str, refresh: bool = False) -> Dict[str, Any]:
+        """Resolve an index's Solr endpoint + HTTP auth. Cached per client."""
+        if not refresh and index in self._core_info_cache:
+            return self._core_info_cache[index]
+        body = self.mgmt("get_core_info", core_name=index)
+        msg = body.get("msg") if isinstance(body, dict) else None
+        if not isinstance(msg, dict) or "info" not in msg:
+            raise OpensolrError(f"get_core_info({index}): unexpected response: {str(body)[:200]}")
+        info = msg["info"]
+        self._core_info_cache[index] = info
+        return info
+
+    def vector_regions(self) -> List[Dict[str, str]]:
+        """Live list of vector-enabled environments (Solr 9.x + knn_vector +
+        hybrid parser): ``[{environment, country, solr_version}, ...]``.
+
+        Cached per client. Additional dedicated regions can be deployed on
+        request (paid) — contact support@opensolr.com.
+        """
+        if not hasattr(self, "_vector_regions_cache"):
+            body = self.mgmt("vector_regions")
+            self._vector_regions_cache = body if isinstance(body, list) else []
+        return self._vector_regions_cache
+
+    def create_index(self, index: str, location: str = "us") -> Dict[str, Any]:
+        """Create a vector-enabled index in a vector location.
+
+        ``location`` is an alias ("us", "de", "fi") or a raw Opensolr
+        environment identifier. Validated against the live ``vector_regions``
+        list when reachable; otherwise the server has the final word.
+        """
+        env = resolve_location(location)
+        try:
+            live = {r["environment"] for r in self.vector_regions()}
+        except OpensolrError:
+            live = set(VECTOR_LOCATIONS.values())  # offline fallback
+        if live and env not in live:
+            raise ValueError(
+                f"{location!r} is not a vector-enabled Opensolr location. "
+                f"Currently available: {sorted(live)}. Additional regions can "
+                f"be deployed on request — contact support@opensolr.com."
+            )
+        return self.mgmt(
+            "create_index", index_name=index, core_type="generic", server_country=env
+        )
+
+    # ------------------------------------------------------------------ #
+    # AI                                                                 #
+    # ------------------------------------------------------------------ #
+
+    def embed(self, index: str, text: str, is_query: bool = False) -> List[float]:
+        body = self.ai(
+            "embed", index_name=index, payload=text, is_query="1" if is_query else "0"
+        )
+        if not isinstance(body, list) or not body:
+            raise OpensolrError(f"embed: unexpected response: {str(body)[:200]}")
+        return body
+
+    def batch_embed(self, index: str, texts: List[str]) -> List[List[float]]:
+        """Embed many texts. Chunks transparently at the server's batch limit."""
+        out: List[List[float]] = []
+        for i in range(0, len(texts), BATCH_EMBED_MAX):
+            chunk = texts[i : i + BATCH_EMBED_MAX]
+            resp = self._http.post(
+                f"{AI_BASE}/batch_embed",
+                json={
+                    **self._auth_params(),
+                    "index_name": index,
+                    "payloads": chunk,
+                },
+            )
+            try:
+                body = resp.json()
+            except json.JSONDecodeError as exc:
+                raise OpensolrError(f"batch_embed: non-JSON response: {resp.text[:200]}") from exc
+            if isinstance(body, dict) and body.get("status") is False:
+                raise OpensolrError(f"batch_embed: {body.get('msg', body)}")
+            embeddings = body.get("embeddings") if isinstance(body, dict) else None
+            if not isinstance(embeddings, list) or len(embeddings) != len(chunk):
+                raise OpensolrError(f"batch_embed: unexpected response: {str(body)[:200]}")
+            out.extend(embeddings)
+        return out
+
+    def embed_and_search(self, index: str, query: str, rows: int = 10, **params: Any) -> Dict[str, Any]:
+        """Server-side one-shot: embed the query, run hybrid search, return docs."""
+        body = self.ai(
+            "embed_and_search",
+            index_name=index,
+            q=query,
+            rows=rows,
+            **{"in": "all", "fresh": "no", **params},
+        )
+        return body
+
+    # ------------------------------------------------------------------ #
+    # direct Solr                                                        #
+    # ------------------------------------------------------------------ #
+
+    def solr_endpoint(self, index: str) -> Tuple[str, Optional[Tuple[str, str]]]:
+        """Return (base_url, basic_auth) for the index's native Solr API."""
+        info = self.get_core_info(index)
+        url = info.get("connection_url")
+        if not url:
+            raise OpensolrError(f"No connection_url for index {index!r}")
+        auth = None
+        if info.get("auth_username"):
+            auth = (info["auth_username"], info.get("auth_password") or "")
+        return url, auth
+
+    def solr_select(self, index: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        base, auth = self.solr_endpoint(index)
+        resp = self._http.post(f"{base}/select", data={"wt": "json", **params}, auth=auth)
+        resp.raise_for_status()
+        return resp.json()
+
+    def solr_update(self, index: str, payload: Any, commit: bool = True) -> Dict[str, Any]:
+        base, auth = self.solr_endpoint(index)
+        params = {"commit": "true"} if commit else {"commitWithin": "10000"}
+        resp = self._http.post(
+            f"{base}/update",
+            params=params,
+            json=payload,
+            auth=auth,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self) -> None:
+        self._http.close()

opensolr_haystack-0.1.0/haystack_integrations/document_stores/opensolr/store.py

@@ -0,0 +1,287 @@
+"""Opensolr DocumentStore for Haystack.
+
+Managed, vector-enabled Apache Solr 9.x (knn_vector 1024-dim, cosine) with
+embeddings computed **server-side** on Opensolr's GPU infrastructure — no
+local embedder component needed at indexing time.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+from haystack import Document, default_from_dict, default_to_dict
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+from haystack_integrations.document_stores.opensolr.client import (
+    OpensolrClient,
+    OpensolrError,
+)
+
+_META_KEY_RE = re.compile(r"[^a-z0-9_]+")
+
+
+def _meta_field(key: str) -> str:
+    return f"meta_{_META_KEY_RE.sub('_', key.lower()).strip('_')}"
+
+
+def _escape(value: Any) -> str:
+    return str(value).replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _filters_to_fq(filters: Optional[Dict[str, Any]]) -> List[str]:
+    """Translate Haystack's standard filter dict into Solr fq clauses.
+
+    Supports field conditions with operators ==, !=, in, not in, and logical
+    AND groups (the common cases). OR groups become a single fq with OR.
+    """
+    if not filters:
+        return []
+
+    def _cond(f: Dict[str, Any]) -> str:
+        field = f["field"].split("meta.", 1)[-1]
+        solr_field = _meta_field(field)
+        op = f["operator"]
+        value = f.get("value")
+        if op == "==":
+            return f'{solr_field}:"{_escape(value)}"'
+        if op == "!=":
+            return f'-{solr_field}:"{_escape(value)}"'
+        if op == "in":
+            joined = " OR ".join(f'"{_escape(v)}"' for v in value)
+            return f"{solr_field}:({joined})"
+        if op == "not in":
+            joined = " OR ".join(f'"{_escape(v)}"' for v in value)
+            return f"-{solr_field}:({joined})"
+        if op in (">", ">="):
+            return f'{solr_field}:{"{" if op == ">" else "["}"{_escape(value)}" TO *]'
+        if op in ("<", "<="):
+            return f'{solr_field}:[* TO "{_escape(value)}"{"}" if op == "<" else "]"}'
+        raise ValueError(f"Unsupported filter operator: {op}")
+
+    if "operator" in filters and "conditions" in filters:
+        parts = []
+        for c in filters["conditions"]:
+            if "conditions" in c:
+                sub = _filters_to_fq(c)
+                parts.append("(" + " AND ".join(sub) + ")")
+            else:
+                parts.append(_cond(c))
+        if filters["operator"] == "AND":
+            return parts
+        if filters["operator"] == "OR":
+            return ["(" + " OR ".join(parts) + ")"]
+        raise ValueError(f"Unsupported logical operator: {filters['operator']}")
+    return [_cond(filters)]
+
+
+class OpensolrDocumentStore:
+    """Haystack DocumentStore backed by a managed Opensolr vector index.
+
+    Example:
+        ```python
+        from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore
+
+        store = OpensolrDocumentStore(index="mysite__dense")
+        # credentials default to OPENSOLR_EMAIL / OPENSOLR_API_KEY env vars
+        ```
+    """
+
+    def __init__(
+        self,
+        index: str,
+        email: Secret = Secret.from_env_var("OPENSOLR_EMAIL"),
+        api_key: Secret = Secret.from_env_var("OPENSOLR_API_KEY"),
+        create_if_missing: bool = False,
+        location: str = "us",
+    ) -> None:
+        self.index = index
+        self.email = email
+        self.api_key = api_key
+        self.create_if_missing = create_if_missing
+        self.location = location
+        self._client: Optional[OpensolrClient] = None
+        self._checked = False
+
+    # ------------------------------------------------------------------ #
+
+    @property
+    def client(self) -> OpensolrClient:
+        if self._client is None:
+            self._client = OpensolrClient(
+                self.email.resolve_value(), self.api_key.resolve_value()
+            )
+        return self._client
+
+    def _ensure_index(self) -> None:
+        if self._checked:
+            return
+        try:
+            self.client.get_core_info(self.index)
+        except OpensolrError:
+            if not self.create_if_missing:
+                raise
+            self.client.create_index(self.index, self.location)
+            import time
+
+            for _ in range(5):
+                time.sleep(2)
+                try:
+                    self.client.get_core_info(self.index, refresh=True)
+                    break
+                except OpensolrError:
+                    continue
+        self._checked = True
+
+    def _doc_from_solr(self, solr_doc: Dict[str, Any]) -> Document:
+        def _flat(v: Any) -> Any:
+            return v[0] if isinstance(v, list) and len(v) == 1 else v
+
+        meta: Dict[str, Any] = {}
+        raw = _flat(solr_doc.get("meta_lc_json"))
+        if raw:
+            try:
+                meta = json.loads(raw)
+            except (TypeError, json.JSONDecodeError):
+                meta = {}
+        content = _flat(solr_doc.get("text", "")) or ""
+        if isinstance(content, list):
+            content = " ".join(str(c) for c in content)
+        score = solr_doc.get("score")
+        return Document(
+            id=str(_flat(solr_doc.get("id", ""))),
+            content=str(content),
+            meta=meta,
+            score=float(_flat(score)) if score is not None else None,
+        )
+
+    # ------------------------------------------------------------------ #
+    # DocumentStore protocol                                             #
+    # ------------------------------------------------------------------ #
+
+    def count_documents(self) -> int:
+        self._ensure_index()
+        body = self.client.solr_select(self.index, {"q": "*:*", "rows": 0})
+        return int(body["response"]["numFound"])
+
+    def filter_documents(self, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+        self._ensure_index()
+        params: Dict[str, Any] = {"q": "*:*", "rows": 1000, "fl": "*"}
+        fq = _filters_to_fq(filters)
+        if fq:
+            params["fq"] = fq
+        body = self.client.solr_select(self.index, params)
+        return [self._doc_from_solr(d) for d in body["response"]["docs"]]
+
+    def write_documents(
+        self, documents: List[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+    ) -> int:
+        if not documents:
+            return 0
+        self._ensure_index()
+
+        if policy in (DuplicatePolicy.SKIP, DuplicatePolicy.FAIL):
+            ids = [d.id for d in documents]
+            joined = " OR ".join(f'"{_escape(i)}"' for i in ids)
+            body = self.client.solr_select(
+                self.index, {"q": f"id:({joined})", "rows": len(ids), "fl": "id"}
+            )
+            existing = {
+                str(d["id"][0] if isinstance(d["id"], list) else d["id"])
+                for d in body["response"]["docs"]
+            }
+            if existing and policy == DuplicatePolicy.FAIL:
+                from haystack.document_stores.errors import DuplicateDocumentError
+
+                raise DuplicateDocumentError(f"IDs already in the store: {sorted(existing)}")
+            documents = [d for d in documents if d.id not in existing]
+            if not documents:
+                return 0
+
+        texts = [d.content or " " for d in documents]
+        embeddings: List[Optional[List[float]]] = [d.embedding for d in documents]
+        missing = [i for i, e in enumerate(embeddings) if e is None]
+        if missing:
+            computed = self.client.batch_embed(self.index, [texts[i] for i in missing])
+            for i, vec in zip(missing, computed):
+                embeddings[i] = vec
+
+        docs = []
+        for doc, text, vector in zip(documents, texts, embeddings):
+            meta = dict(doc.meta or {})
+            solr_doc: Dict[str, Any] = {
+                "id": doc.id,
+                "text": text,
+                "embeddings": vector,
+                "meta_lc_json": json.dumps(meta, ensure_ascii=False),
+                "title": str(meta.get("title") or text[:100]),
+            }
+            for key, value in meta.items():
+                if isinstance(value, (str, int, float, bool)):
+                    solr_doc[_meta_field(str(key))] = str(value)
+            docs.append(solr_doc)
+
+        self.client.solr_update(self.index, docs)
+        return len(docs)
+
+    def delete_documents(self, document_ids: List[str]) -> None:
+        if not document_ids:
+            return
+        self._ensure_index()
+        self.client.solr_update(self.index, {"delete": list(document_ids)})
+
+    # ------------------------------------------------------------------ #
+    # search (used by the retriever component)                           #
+    # ------------------------------------------------------------------ #
+
+    def search(
+        self,
+        query: str,
+        top_k: int = 10,
+        hybrid: bool = True,
+        alpha: float = 0.5,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> List[Document]:
+        self._ensure_index()
+        vector = self.client.embed(self.index, query, is_query=True)
+        compact = json.dumps(vector, separators=(",", ":"))
+        knn = f"{{!knn f=embeddings topK={max(top_k, 10)}}}{compact}"
+
+        params: Dict[str, Any] = {"rows": top_k, "fl": "*,score"}
+        if hybrid:
+            clean = query.replace("{", " ").replace("}", " ").replace('"', " ")
+            params["q"] = (
+                f"{{!hybrid lexical=$lexicalRaw vector=$vectorQuery "
+                f"mode=union alpha={alpha} topN={max(top_k, 10)}}}"
+            )
+            params["lexicalRaw"] = f'{{!edismax qf="title^100 text^1"}}{clean}'
+            params["vectorQuery"] = knn
+        else:
+            params["q"] = knn
+        fq = _filters_to_fq(filters)
+        if fq:
+            params["fq"] = fq
+
+        body = self.client.solr_select(self.index, params)
+        return [self._doc_from_solr(d) for d in body["response"]["docs"]]
+
+    # ------------------------------------------------------------------ #
+    # serialization                                                      #
+    # ------------------------------------------------------------------ #
+
+    def to_dict(self) -> Dict[str, Any]:
+        return default_to_dict(
+            self,
+            index=self.index,
+            email=self.email.to_dict(),
+            api_key=self.api_key.to_dict(),
+            create_if_missing=self.create_if_missing,
+            location=self.location,
+        )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "OpensolrDocumentStore":
+        deserialize_secrets_inplace(data["init_parameters"], keys=["email", "api_key"])
+        return default_from_dict(cls, data)

opensolr_haystack-0.1.0/opensolr_haystack.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: opensolr-haystack
+Version: 0.1.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
+Project-URL: Homepage, https://opensolr.com/langchain
+Project-URL: Repository, https://github.com/phpcip/opensolr-haystack
+Keywords: haystack,opensolr,solr,vector,hybrid-search,rag,document-store
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: haystack-ai>=2.0.0
+Requires-Dist: httpx>=0.25.0
+Dynamic: license-file
+
+# opensolr-haystack
+
+[Haystack](https://haystack.deepset.ai) integration for
+[Opensolr](https://opensolr.com) — managed Apache Solr as a DocumentStore,
+with **server-side embeddings** and native **hybrid (BM25 + kNN) retrieval**.
+
+No embedder components needed in your pipeline — texts and queries are
+embedded on Opensolr's GPU infrastructure (multilingual E5-large-instruct,
+1024 dimensions, cosine).
+
+**Product page:** [opensolr.com/langchain](https://opensolr.com/langchain) ·
+free 15-day trial, no card, at [opensolr.com](https://opensolr.com)
+
+```bash
+pip install opensolr-haystack
+```
+
+## Quickstart
+
+```python
+from haystack import Document, Pipeline
+from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore
+from haystack_integrations.components.retrievers.opensolr import OpensolrHybridRetriever
+
+# credentials default to OPENSOLR_EMAIL / OPENSOLR_API_KEY env vars
+store = OpensolrDocumentStore(index="mysite__dense", create_if_missing=True)
+
+store.write_documents([
+    Document(content="Hybrid search fuses BM25 with vector similarity"),
+    Document(content="Cats sleep sixteen hours a day"),
+])
+
+pipe = Pipeline()
+pipe.add_component("retriever", OpensolrHybridRetriever(document_store=store))
+result = pipe.run({"retriever": {"query": "how do keyword and semantic search combine?"}})
+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.
+
+## Hybrid retrieval
+
+`OpensolrHybridRetriever` fuses BM25 and kNN scores per document via
+Opensolr's native `{!hybrid}` Solr query parser:
+
+```python
+OpensolrHybridRetriever(
+    document_store=store,
+    top_k=10,
+    hybrid=True,     # False = pure semantic kNN
+    alpha=0.5,       # 0 = all semantic … 1 = all lexical
+)
+```
+
+Standard Haystack filters are supported and map to Solr `fq`:
+
+```python
+pipe.run({"retriever": {
+    "query": "search engines",
+    "filters": {"field": "meta.category", "operator": "==", "value": "docs"},
+}})
+```
+
+## Notes
+
+- Vector-enabled indexes run on Opensolr's Solr 9.x environments — currently
+  `us` (Chicago), `de` (Germany), `fi` (Finland). **Additional dedicated
+  regions can be deployed on request** (paid add-on):
+  [support@opensolr.com](mailto:support@opensolr.com).
+- Every index is also plain Apache Solr with the native `/select` API —
+  facets, highlighting, spellcheck included.
+- Siblings: [`langchain-opensolr`](https://pypi.org/project/langchain-opensolr/) ·
+  [`llama-index-opensolr`](https://pypi.org/project/llama-index-opensolr/) ·
+  [`opensolr-mcp`](https://pypi.org/project/opensolr-mcp/)
+
+MIT license.

opensolr_haystack-0.1.0/opensolr_haystack.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+haystack_integrations/components/retrievers/opensolr/__init__.py
+haystack_integrations/components/retrievers/opensolr/retriever.py
+haystack_integrations/document_stores/opensolr/__init__.py
+haystack_integrations/document_stores/opensolr/client.py
+haystack_integrations/document_stores/opensolr/store.py
+opensolr_haystack.egg-info/PKG-INFO
+opensolr_haystack.egg-info/SOURCES.txt
+opensolr_haystack.egg-info/dependency_links.txt
+opensolr_haystack.egg-info/requires.txt
+opensolr_haystack.egg-info/top_level.txt

opensolr_haystack-0.1.0/opensolr_haystack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opensolr_haystack-0.1.0/opensolr_haystack.egg-info/requires.txt

@@ -0,0 +1,2 @@
+haystack-ai>=2.0.0
+httpx>=0.25.0

opensolr_haystack-0.1.0/opensolr_haystack.egg-info/top_level.txt

@@ -0,0 +1 @@
+haystack_integrations

opensolr_haystack-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opensolr-haystack"
+version = "0.1.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" }
+requires-python = ">=3.9"
+authors = [{ name = "Opensolr", email = "support@opensolr.com" }]
+dependencies = [
+    "haystack-ai>=2.0.0",
+    "httpx>=0.25.0",
+]
+keywords = ["haystack", "opensolr", "solr", "vector", "hybrid-search", "rag", "document-store"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://opensolr.com/langchain"
+Repository = "https://github.com/phpcip/opensolr-haystack"
+
+[tool.setuptools.packages.find]
+include = ["haystack_integrations.*"]

opensolr_haystack-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+