langchain-opensolr 0.1.0__tar.gz

langchain_opensolr-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.

langchain_opensolr-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: langchain-opensolr
+Version: 0.1.0
+Summary: LangChain integration for Opensolr — managed Apache Solr with server-side embeddings and hybrid (BM25 + kNN) search
+Author-email: Opensolr <support@opensolr.com>
+License: MIT
+Project-URL: Homepage, https://opensolr.com
+Project-URL: Documentation, https://opensolr.com/opensolr-platform-user-documentation/ai-vector
+Project-URL: Repository, https://github.com/opensolr/langchain-opensolr
+Keywords: langchain,opensolr,solr,vector,hybrid-search,rag,embeddings
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: httpx>=0.25.0
+Dynamic: license-file
+
+# langchain-opensolr
+
+LangChain integration for [Opensolr](https://opensolr.com) — managed Apache Solr
+with **server-side embeddings** and native **hybrid (BM25 + kNN) search**.
+
+No local embedding model. No third-party embedding API key. One set of
+credentials, and the vectors are computed on Opensolr's GPU infrastructure
+(multilingual E5-large-instruct, 1024 dimensions, cosine).
+
+```bash
+pip install langchain-opensolr
+```
+
+## The whole tutorial
+
+```python
+from langchain_opensolr import OpensolrVectorStore
+
+vs = OpensolrVectorStore(
+    index="mysite__dense",          # vector-enabled Opensolr index
+    email="you@example.com",
+    api_key="YOUR_OPENSOLR_API_KEY",
+    create_if_missing=True,          # provisions the index on first use
+)
+
+vs.add_texts(
+    ["Hybrid search fuses BM25 with vector similarity",
+     "Cats sleep sixteen hours a day"],
+    metadatas=[{"category": "search"}, {"category": "animals"}],
+)
+
+docs = vs.similarity_search("how do lexical and semantic search combine?", k=1)
+print(docs[0].page_content)
+```
+
+That's it — no embedding model was configured, because embedding happens on
+the server at both index and query time.
+
+## Hybrid search
+
+Pure vector search fails on exact identifiers; pure BM25 fails on meaning.
+Opensolr's `{!hybrid}` query parser fuses both scores **per document**:
+
+```python
+docs = vs.similarity_search(
+    "affordable restaurants",
+    k=5,
+    hybrid=True,
+    mode="union",     # union | keywords_required | meaning_required | intersection
+    alpha=0.5,        # 0 = all semantic … 1 = all lexical
+)
+```
+
+## Metadata filters
+
+```python
+vs.similarity_search("search engines", k=5, filter={"category": "search"})
+vs.similarity_search("anything", k=5, filter='meta_rank:[2 TO *]')   # raw Solr fq
+```
+
+Metadata round-trips losslessly (stored as JSON alongside filterable
+`meta_*` fields).
+
+## As a retriever, in any chain
+
+```python
+retriever = vs.as_retriever(search_kwargs={"k": 5, "hybrid": True})
+```
+
+## Standalone embeddings
+
+Use Opensolr's embedding endpoint with any other LangChain component:
+
+```python
+from langchain_opensolr import OpensolrEmbeddings
+
+emb = OpensolrEmbeddings(email="you@example.com", api_key="...", index="mysite__dense")
+emb.embed_query("budget-friendly dining")   # -> 1024 floats
+```
+
+## Notes
+
+- Vector-enabled indexes run on Opensolr's Solr 9.x environments — locations
+  `us` (Chicago), `de` (Germany), `fi` (Finland). Pass `location=` to choose.
+- A free Opensolr account (15-day trial, no card) includes an AI quota that
+  comfortably covers this README end to end:
+  [opensolr.com](https://opensolr.com).
+- Full platform docs: [AI & Vector Search](https://opensolr.com/opensolr-platform-user-documentation/ai-vector).
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest tests/unit_tests
+OPENSOLR_EMAIL=... OPENSOLR_API_KEY=... OPENSOLR_INDEX=... pytest tests/integration_tests
+```
+
+MIT license.

langchain_opensolr-0.1.0/README.md

@@ -0,0 +1,98 @@
+# langchain-opensolr
+
+LangChain integration for [Opensolr](https://opensolr.com) — managed Apache Solr
+with **server-side embeddings** and native **hybrid (BM25 + kNN) search**.
+
+No local embedding model. No third-party embedding API key. One set of
+credentials, and the vectors are computed on Opensolr's GPU infrastructure
+(multilingual E5-large-instruct, 1024 dimensions, cosine).
+
+```bash
+pip install langchain-opensolr
+```
+
+## The whole tutorial
+
+```python
+from langchain_opensolr import OpensolrVectorStore
+
+vs = OpensolrVectorStore(
+    index="mysite__dense",          # vector-enabled Opensolr index
+    email="you@example.com",
+    api_key="YOUR_OPENSOLR_API_KEY",
+    create_if_missing=True,          # provisions the index on first use
+)
+
+vs.add_texts(
+    ["Hybrid search fuses BM25 with vector similarity",
+     "Cats sleep sixteen hours a day"],
+    metadatas=[{"category": "search"}, {"category": "animals"}],
+)
+
+docs = vs.similarity_search("how do lexical and semantic search combine?", k=1)
+print(docs[0].page_content)
+```
+
+That's it — no embedding model was configured, because embedding happens on
+the server at both index and query time.
+
+## Hybrid search
+
+Pure vector search fails on exact identifiers; pure BM25 fails on meaning.
+Opensolr's `{!hybrid}` query parser fuses both scores **per document**:
+
+```python
+docs = vs.similarity_search(
+    "affordable restaurants",
+    k=5,
+    hybrid=True,
+    mode="union",     # union | keywords_required | meaning_required | intersection
+    alpha=0.5,        # 0 = all semantic … 1 = all lexical
+)
+```
+
+## Metadata filters
+
+```python
+vs.similarity_search("search engines", k=5, filter={"category": "search"})
+vs.similarity_search("anything", k=5, filter='meta_rank:[2 TO *]')   # raw Solr fq
+```
+
+Metadata round-trips losslessly (stored as JSON alongside filterable
+`meta_*` fields).
+
+## As a retriever, in any chain
+
+```python
+retriever = vs.as_retriever(search_kwargs={"k": 5, "hybrid": True})
+```
+
+## Standalone embeddings
+
+Use Opensolr's embedding endpoint with any other LangChain component:
+
+```python
+from langchain_opensolr import OpensolrEmbeddings
+
+emb = OpensolrEmbeddings(email="you@example.com", api_key="...", index="mysite__dense")
+emb.embed_query("budget-friendly dining")   # -> 1024 floats
+```
+
+## Notes
+
+- Vector-enabled indexes run on Opensolr's Solr 9.x environments — locations
+  `us` (Chicago), `de` (Germany), `fi` (Finland). Pass `location=` to choose.
+- A free Opensolr account (15-day trial, no card) includes an AI quota that
+  comfortably covers this README end to end:
+  [opensolr.com](https://opensolr.com).
+- Full platform docs: [AI & Vector Search](https://opensolr.com/opensolr-platform-user-documentation/ai-vector).
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest tests/unit_tests
+OPENSOLR_EMAIL=... OPENSOLR_API_KEY=... OPENSOLR_INDEX=... pytest tests/integration_tests
+```
+
+MIT license.

langchain_opensolr-0.1.0/langchain_opensolr/__init__.py

@@ -0,0 +1,13 @@
+"""LangChain integration for Opensolr — managed Apache Solr with server-side
+embeddings and native hybrid (BM25 + kNN) search."""
+
+from langchain_opensolr._client import OpensolrClient, OpensolrError
+from langchain_opensolr.embeddings import OpensolrEmbeddings
+from langchain_opensolr.vectorstores import OpensolrVectorStore
+
+__all__ = [
+    "OpensolrClient",
+    "OpensolrError",
+    "OpensolrEmbeddings",
+    "OpensolrVectorStore",
+]

langchain_opensolr-0.1.0/langchain_opensolr/_client.py

@@ -0,0 +1,197 @@
+"""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"
+
+#: Only these Opensolr environments run vector-enabled (Solr 9.x + knn_vector
+#: schema) servers. ``create_index`` for a vector index must target one of them.
+VECTOR_LOCATIONS: Dict[str, str] = {
+    "us": "CHICAGO-96",
+    "de": "DE-SOLR-9",
+    "fi": "FINLAND9",
+}
+
+#: 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 create_index(self, index: str, location: str = "us") -> Dict[str, Any]:
+        """Create a vector-enabled index on one of the vector locations.
+
+        ``location`` is one of :data:`VECTOR_LOCATIONS` keys ("us", "de", "fi")
+        or a raw Opensolr environment identifier.
+        """
+        env = VECTOR_LOCATIONS.get(location.lower(), location)
+        if env not in VECTOR_LOCATIONS.values():
+            raise ValueError(
+                f"Vector-enabled indexes are only available in these locations: "
+                f"{sorted(VECTOR_LOCATIONS)} (got {location!r})"
+            )
+        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()

langchain_opensolr-0.1.0/langchain_opensolr/embeddings.py

@@ -0,0 +1,63 @@
+"""Opensolr server-side embeddings for LangChain.
+
+Texts are embedded by Opensolr's GPU-backed multilingual model
+(E5-large-instruct, 1024 dimensions). No local model, no extra API keys —
+the same credentials as your Opensolr account.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from langchain_core.embeddings import Embeddings
+
+from ._client import OpensolrClient
+
+
+class OpensolrEmbeddings(Embeddings):
+    """Embeddings backed by the Opensolr AI API.
+
+    Example:
+        .. code-block:: python
+
+            from langchain_opensolr import OpensolrEmbeddings
+
+            embeddings = OpensolrEmbeddings(
+                email="you@example.com",
+                api_key="...",
+                index="mysite__dense",
+            )
+            vec = embeddings.embed_query("budget-friendly dining")
+
+    Args:
+        email: Opensolr account email.
+        api_key: Opensolr API key.
+        index: A vector-enabled Opensolr index name. Embedding requests are
+            accounted against this index's plan.
+        client: Optional pre-configured :class:`OpensolrClient` to reuse
+            (e.g. shared with an :class:`OpensolrVectorStore`).
+    """
+
+    def __init__(
+        self,
+        email: str = "",
+        api_key: str = "",
+        index: str = "",
+        client: Optional[OpensolrClient] = None,
+    ) -> None:
+        if client is None:
+            if not (email and api_key):
+                raise ValueError("Provide either a client or email + api_key")
+            client = OpensolrClient(email, api_key)
+        if not index:
+            raise ValueError("index is required (embedding is accounted per index)")
+        self._client = client
+        self._index = index
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        if not texts:
+            return []
+        return self._client.batch_embed(self._index, texts)
+
+    def embed_query(self, text: str) -> List[float]:
+        return self._client.embed(self._index, text, is_query=True)

langchain_opensolr-0.1.0/langchain_opensolr/vectorstores.py

@@ -0,0 +1,402 @@
+"""Opensolr vector store for LangChain.
+
+A :class:`~langchain_core.vectorstores.VectorStore` backed by a managed,
+vector-enabled Opensolr index (Apache Solr 9.x, ``knn_vector`` 1024-dim,
+cosine). Embedding happens **server-side** on Opensolr's GPU infrastructure —
+no local embedding model or third-party API key is needed.
+
+Highlights:
+
+- Zero-config constructor: ``OpensolrVectorStore(index=..., email=..., api_key=...)``.
+  Host, port and HTTP auth of the underlying Solr core are resolved
+  automatically through the Opensolr management API.
+- ``hybrid=True`` search uses Opensolr's native ``{!hybrid}`` query parser,
+  fusing BM25 and kNN per document with a tunable ``alpha`` balance and four
+  modes: ``union``, ``keywords_required``, ``meaning_required``, ``intersection``.
+- Metadata round-trips losslessly (stored as JSON alongside filterable
+  ``meta_*`` string fields).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+import uuid
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from langchain_core.documents import Document
+from langchain_core.embeddings import Embeddings
+from langchain_core.vectorstores import VectorStore
+
+from ._client import VECTOR_LOCATIONS, OpensolrClient, OpensolrError
+from .embeddings import OpensolrEmbeddings
+
+_HYBRID_MODES = ("union", "keywords_required", "meaning_required", "intersection")
+
+#: Solr fields managed by this integration or by the Opensolr schema that
+#: should not leak into Document.metadata.
+_INTERNAL_FIELDS = {
+    "_version_",
+    "_root_",
+    "score",
+    "embeddings",
+    "meta_lc_json",
+}
+
+_META_KEY_RE = re.compile(r"[^a-z0-9_]+")
+
+
+def _sanitize_meta_key(key: str) -> str:
+    return _META_KEY_RE.sub("_", key.lower()).strip("_")
+
+
+def _escape_fq_value(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _scalar(value: Any) -> bool:
+    return isinstance(value, (str, int, float, bool))
+
+
+class OpensolrVectorStore(VectorStore):
+    """Managed hybrid vector store on Opensolr.
+
+    Example:
+        .. code-block:: python
+
+            from langchain_opensolr import OpensolrVectorStore
+
+            vs = OpensolrVectorStore(
+                index="mysite__dense",
+                email="you@example.com",
+                api_key="...",
+            )
+            vs.add_texts(["Solr is a search platform", "Cats sleep a lot"])
+            docs = vs.similarity_search("search engines", k=2)
+
+            # hybrid BM25 + kNN with filters
+            docs = vs.similarity_search(
+                "search engines", k=2, hybrid=True, filter={"category": "docs"}
+            )
+
+    Args:
+        index: Name of the vector-enabled Opensolr index. Vector indexes live
+            on Opensolr's Solr 9.x environments (locations: ``us``, ``de``, ``fi``).
+        email: Opensolr account email.
+        api_key: Opensolr API key.
+        client: Optional pre-configured :class:`OpensolrClient` (overrides
+            email/api_key).
+        location: Where to create the index if ``create_if_missing`` is set:
+            ``us`` (Chicago), ``de`` (Germany) or ``fi`` (Finland) — the
+            Opensolr environments with vector-enabled servers.
+        create_if_missing: Create the index automatically on first use.
+        text_field: Solr field holding page content (default ``text``).
+        vector_field: Solr ``knn_vector`` field (default ``embeddings``).
+    """
+
+    def __init__(
+        self,
+        index: str,
+        email: str = "",
+        api_key: str = "",
+        client: Optional[OpensolrClient] = None,
+        location: str = "us",
+        create_if_missing: bool = False,
+        text_field: str = "text",
+        vector_field: str = "embeddings",
+    ) -> None:
+        if client is None:
+            if not (email and api_key):
+                raise ValueError("Provide either a client or email + api_key")
+            client = OpensolrClient(email, api_key)
+        if location.lower() not in VECTOR_LOCATIONS and location not in VECTOR_LOCATIONS.values():
+            raise ValueError(
+                f"Vector-enabled Opensolr locations are {sorted(VECTOR_LOCATIONS)}; got {location!r}"
+            )
+        self._client = client
+        self._index = index
+        self._location = location
+        self._create_if_missing = create_if_missing
+        self._text_field = text_field
+        self._vector_field = vector_field
+        self._checked = False
+
+    # ------------------------------------------------------------------ #
+    # plumbing                                                           #
+    # ------------------------------------------------------------------ #
+
+    @property
+    def embeddings(self) -> Embeddings:
+        """Server-side embeddings bound to this index."""
+        return OpensolrEmbeddings(client=self._client, index=self._index)
+
+    def _ensure_index(self) -> None:
+        if self._checked:
+            return
+        try:
+            info = self._client.get_core_info(self._index)
+        except OpensolrError:
+            if not self._create_if_missing:
+                raise
+            self._client.create_index(self._index, self._location)
+            info = None
+            for _ in range(5):
+                time.sleep(2)
+                try:
+                    info = self._client.get_core_info(self._index, refresh=True)
+                    break
+                except OpensolrError:
+                    continue
+            if info is None:
+                raise
+        version = str(info.get("solr_version", ""))
+        if version and not version.startswith("9"):
+            raise OpensolrError(
+                f"Index {self._index!r} runs Solr {version}, but vector search "
+                f"requires Solr 9.x. Create the index in one of the vector-enabled "
+                f"locations: {sorted(VECTOR_LOCATIONS)}."
+            )
+        self._checked = True
+
+    def _doc_from_solr(self, solr_doc: Dict[str, Any]) -> Document:
+        def _flat(v: Any) -> Any:
+            if isinstance(v, list):
+                return v[0] if len(v) == 1 else v
+            return v
+
+        content = _flat(solr_doc.get(self._text_field, "")) or ""
+        if isinstance(content, list):
+            content = " ".join(str(c) for c in content)
+
+        metadata: Dict[str, Any] = {}
+        raw_json = _flat(solr_doc.get("meta_lc_json"))
+        if raw_json:
+            try:
+                metadata = json.loads(raw_json)
+            except (TypeError, json.JSONDecodeError):
+                metadata = {}
+        if not metadata:
+            for key, value in solr_doc.items():
+                if key.startswith("meta_") and key not in _INTERNAL_FIELDS:
+                    metadata[key[5:]] = _flat(value)
+        return Document(
+            id=str(_flat(solr_doc.get("id", ""))),
+            page_content=str(content),
+            metadata=metadata,
+        )
+
+    def _filter_to_fq(self, filter: Any) -> List[str]:
+        if filter is None:
+            return []
+        if isinstance(filter, str):
+            return [filter]
+        if isinstance(filter, list):
+            return [str(f) for f in filter]
+        if isinstance(filter, dict):
+            fq = []
+            for key, value in filter.items():
+                field = f"meta_{_sanitize_meta_key(key)}"
+                if isinstance(value, list):
+                    joined = " OR ".join(f'"{_escape_fq_value(str(v))}"' for v in value)
+                    fq.append(f"{field}:({joined})")
+                else:
+                    fq.append(f'{field}:"{_escape_fq_value(str(value))}"')
+            return fq
+        raise ValueError(f"Unsupported filter type: {type(filter)}")
+
+    # ------------------------------------------------------------------ #
+    # write path                                                         #
+    # ------------------------------------------------------------------ #
+
+    def add_texts(
+        self,
+        texts: Iterable[str],
+        metadatas: Optional[List[dict]] = None,
+        ids: Optional[List[str]] = None,
+        **kwargs: Any,
+    ) -> List[str]:
+        texts = list(texts)
+        if not texts:
+            return []
+        self._ensure_index()
+        metadatas = metadatas or [{} for _ in texts]
+        ids = ids or [str(uuid.uuid4()) for _ in texts]
+        if not (len(texts) == len(metadatas) == len(ids)):
+            raise ValueError("texts, metadatas and ids must have the same length")
+
+        vectors = self._client.batch_embed(self._index, texts)
+
+        docs = []
+        for text, meta, doc_id, vector in zip(texts, metadatas, ids, vectors):
+            doc: Dict[str, Any] = {
+                "id": doc_id,
+                self._text_field: text,
+                self._vector_field: vector,
+                "meta_lc_json": json.dumps(meta, ensure_ascii=False),
+            }
+            title = meta.get("title") if isinstance(meta, dict) else None
+            doc["title"] = str(title) if title else text[:100]
+            for key, value in (meta or {}).items():
+                if _scalar(value):
+                    field = f"meta_{_sanitize_meta_key(key)}"
+                    if field not in ("meta_lc_json",):
+                        doc[field] = str(value)
+            docs.append(doc)
+
+        self._client.solr_update(self._index, docs)
+        return ids
+
+    def delete(self, ids: Optional[List[str]] = None, **kwargs: Any) -> Optional[bool]:
+        self._ensure_index()
+        if ids is None:
+            if kwargs.get("delete_all"):
+                self._client.solr_update(self._index, {"delete": {"query": "*:*"}})
+                return True
+            raise ValueError("Provide ids, or delete_all=True to clear the index")
+        self._client.solr_update(self._index, {"delete": list(ids)})
+        return True
+
+    def get_by_ids(self, ids: Sequence[str], /) -> List[Document]:
+        self._ensure_index()
+        joined = " OR ".join(f'"{_escape_fq_value(str(i))}"' for i in ids)
+        body = self._client.solr_select(
+            self._index, {"q": f"id:({joined})", "rows": len(ids), "fl": "*"}
+        )
+        found = {d.id: d for d in map(self._doc_from_solr, body["response"]["docs"])}
+        return [found[i] for i in ids if i in found]
+
+    # ------------------------------------------------------------------ #
+    # read path                                                          #
+    # ------------------------------------------------------------------ #
+
+    def _knn_query(self, vector: List[float], k: int) -> str:
+        compact = json.dumps(vector, separators=(",", ":"))
+        return f"{{!knn f={self._vector_field} topK={k}}}{compact}"
+
+    def similarity_search_with_score(
+        self,
+        query: str,
+        k: int = 4,
+        filter: Optional[Any] = None,
+        hybrid: bool = False,
+        mode: str = "union",
+        alpha: float = 0.5,
+        **kwargs: Any,
+    ) -> List[Tuple[Document, float]]:
+        """Return documents most similar to ``query`` with their scores.
+
+        Args:
+            query: Natural language query. Embedded server-side.
+            k: Number of documents to return.
+            filter: Metadata filter — a dict (``{"key": "value"}`` matches the
+                ``meta_key`` field), a raw Solr ``fq`` string, or a list of them.
+            hybrid: Fuse BM25 (lexical) and kNN (semantic) scores per document
+                using Opensolr's ``{!hybrid}`` query parser instead of pure kNN.
+            mode: Hybrid mode — ``union`` (default), ``keywords_required``,
+                ``meaning_required`` or ``intersection``.
+            alpha: Hybrid semantic↔lexical balance, 0 = all semantic,
+                1 = all lexical.
+        """
+        self._ensure_index()
+        vector = self._client.embed(self._index, query, is_query=True)
+        knn = self._knn_query(vector, max(k, 10))
+
+        params: Dict[str, Any] = {
+            "rows": k,
+            "fl": "*,score",
+        }
+        if hybrid:
+            if mode not in _HYBRID_MODES:
+                raise ValueError(f"mode must be one of {_HYBRID_MODES}, got {mode!r}")
+            clean = query.replace("{", " ").replace("}", " ").replace('"', " ")
+            params["q"] = (
+                f"{{!hybrid lexical=$lexicalRaw vector=$vectorQuery "
+                f"mode={mode} alpha={alpha} topN={max(k, 10)}}}"
+            )
+            params["lexicalRaw"] = (
+                f'{{!edismax qf="title^100 {self._text_field}^1"}}{clean}'
+            )
+            params["vectorQuery"] = knn
+        else:
+            params["q"] = knn
+
+        for i, fq in enumerate(self._filter_to_fq(filter)):
+            params.setdefault("fq", [])
+            params["fq"].append(fq)
+
+        body = self._client.solr_select(self._index, params)
+        docs = body["response"]["docs"]
+        return [
+            (self._doc_from_solr(d), float(d.get("score", 0.0)))
+            for d in docs
+        ]
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 4,
+        filter: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> List[Document]:
+        return [
+            doc
+            for doc, _ in self.similarity_search_with_score(
+                query, k=k, filter=filter, **kwargs
+            )
+        ]
+
+    def similarity_search_by_vector(
+        self,
+        embedding: List[float],
+        k: int = 4,
+        filter: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> List[Document]:
+        self._ensure_index()
+        params: Dict[str, Any] = {
+            "q": self._knn_query(embedding, max(k, 10)),
+            "rows": k,
+            "fl": "*,score",
+        }
+        fq = self._filter_to_fq(filter)
+        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"]]
+
+    # ------------------------------------------------------------------ #
+    # constructors                                                       #
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def from_texts(
+        cls,
+        texts: List[str],
+        embedding: Optional[Embeddings] = None,
+        metadatas: Optional[List[dict]] = None,
+        *,
+        index: str = "",
+        email: str = "",
+        api_key: str = "",
+        location: str = "us",
+        ids: Optional[List[str]] = None,
+        **kwargs: Any,
+    ) -> "OpensolrVectorStore":
+        """Build a store from texts.
+
+        ``embedding`` is accepted for interface compatibility but ignored —
+        Opensolr embeds server-side with its own multilingual model.
+        """
+        if not index:
+            raise ValueError("index is required")
+        store = cls(
+            index=index,
+            email=email,
+            api_key=api_key,
+            location=location,
+            create_if_missing=True,
+            **kwargs,
+        )
+        store.add_texts(texts, metadatas=metadatas, ids=ids)
+        return store

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

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: langchain-opensolr
+Version: 0.1.0
+Summary: LangChain integration for Opensolr — managed Apache Solr with server-side embeddings and hybrid (BM25 + kNN) search
+Author-email: Opensolr <support@opensolr.com>
+License: MIT
+Project-URL: Homepage, https://opensolr.com
+Project-URL: Documentation, https://opensolr.com/opensolr-platform-user-documentation/ai-vector
+Project-URL: Repository, https://github.com/opensolr/langchain-opensolr
+Keywords: langchain,opensolr,solr,vector,hybrid-search,rag,embeddings
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: httpx>=0.25.0
+Dynamic: license-file
+
+# langchain-opensolr
+
+LangChain integration for [Opensolr](https://opensolr.com) — managed Apache Solr
+with **server-side embeddings** and native **hybrid (BM25 + kNN) search**.
+
+No local embedding model. No third-party embedding API key. One set of
+credentials, and the vectors are computed on Opensolr's GPU infrastructure
+(multilingual E5-large-instruct, 1024 dimensions, cosine).
+
+```bash
+pip install langchain-opensolr
+```
+
+## The whole tutorial
+
+```python
+from langchain_opensolr import OpensolrVectorStore
+
+vs = OpensolrVectorStore(
+    index="mysite__dense",          # vector-enabled Opensolr index
+    email="you@example.com",
+    api_key="YOUR_OPENSOLR_API_KEY",
+    create_if_missing=True,          # provisions the index on first use
+)
+
+vs.add_texts(
+    ["Hybrid search fuses BM25 with vector similarity",
+     "Cats sleep sixteen hours a day"],
+    metadatas=[{"category": "search"}, {"category": "animals"}],
+)
+
+docs = vs.similarity_search("how do lexical and semantic search combine?", k=1)
+print(docs[0].page_content)
+```
+
+That's it — no embedding model was configured, because embedding happens on
+the server at both index and query time.
+
+## Hybrid search
+
+Pure vector search fails on exact identifiers; pure BM25 fails on meaning.
+Opensolr's `{!hybrid}` query parser fuses both scores **per document**:
+
+```python
+docs = vs.similarity_search(
+    "affordable restaurants",
+    k=5,
+    hybrid=True,
+    mode="union",     # union | keywords_required | meaning_required | intersection
+    alpha=0.5,        # 0 = all semantic … 1 = all lexical
+)
+```
+
+## Metadata filters
+
+```python
+vs.similarity_search("search engines", k=5, filter={"category": "search"})
+vs.similarity_search("anything", k=5, filter='meta_rank:[2 TO *]')   # raw Solr fq
+```
+
+Metadata round-trips losslessly (stored as JSON alongside filterable
+`meta_*` fields).
+
+## As a retriever, in any chain
+
+```python
+retriever = vs.as_retriever(search_kwargs={"k": 5, "hybrid": True})
+```
+
+## Standalone embeddings
+
+Use Opensolr's embedding endpoint with any other LangChain component:
+
+```python
+from langchain_opensolr import OpensolrEmbeddings
+
+emb = OpensolrEmbeddings(email="you@example.com", api_key="...", index="mysite__dense")
+emb.embed_query("budget-friendly dining")   # -> 1024 floats
+```
+
+## Notes
+
+- Vector-enabled indexes run on Opensolr's Solr 9.x environments — locations
+  `us` (Chicago), `de` (Germany), `fi` (Finland). Pass `location=` to choose.
+- A free Opensolr account (15-day trial, no card) includes an AI quota that
+  comfortably covers this README end to end:
+  [opensolr.com](https://opensolr.com).
+- Full platform docs: [AI & Vector Search](https://opensolr.com/opensolr-platform-user-documentation/ai-vector).
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest tests/unit_tests
+OPENSOLR_EMAIL=... OPENSOLR_API_KEY=... OPENSOLR_INDEX=... pytest tests/integration_tests
+```
+
+MIT license.

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

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+langchain_opensolr/__init__.py
+langchain_opensolr/_client.py
+langchain_opensolr/embeddings.py
+langchain_opensolr/vectorstores.py
+langchain_opensolr.egg-info/PKG-INFO
+langchain_opensolr.egg-info/SOURCES.txt
+langchain_opensolr.egg-info/dependency_links.txt
+langchain_opensolr.egg-info/requires.txt
+langchain_opensolr.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+langchain-core>=0.3.0
+httpx>=0.25.0

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

@@ -0,0 +1 @@
+langchain_opensolr

langchain_opensolr-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-opensolr"
+version = "0.1.0"
+description = "LangChain integration for Opensolr — managed Apache Solr with server-side embeddings and hybrid (BM25 + kNN) search"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Opensolr", email = "support@opensolr.com" }]
+dependencies = [
+    "langchain-core>=0.3.0",
+    "httpx>=0.25.0",
+]
+keywords = ["langchain", "opensolr", "solr", "vector", "hybrid-search", "rag", "embeddings"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://opensolr.com"
+Documentation = "https://opensolr.com/opensolr-platform-user-documentation/ai-vector"
+Repository = "https://github.com/opensolr/langchain-opensolr"
+
+[tool.setuptools]
+packages = ["langchain_opensolr"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

langchain_opensolr-0.1.0/setup.cfg

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