langchain-vectoramp 0.1.0__py3-none-any.whl

langchain_vectoramp/__init__.py

@@ -0,0 +1,7 @@
+"""LangChain integration for VectorAmp."""
+
+from .intelligence import VectorAmpIntelligence
+from .loaders import VectorAmpLoader
+from .vectorstores import VectorAmpVectorStore
+
+__all__ = ["VectorAmpIntelligence", "VectorAmpLoader", "VectorAmpVectorStore"]

langchain_vectoramp/client.py

@@ -0,0 +1,333 @@
+"""Small internal VectorAmp HTTP client used by the LangChain adapter."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from collections.abc import Mapping, Sequence
+from typing import Any, Optional, Union
+
+import httpx
+
+JSON = dict[str, Any]
+FilterValue = Union[str, int, float, bool, None]
+Filters = Mapping[str, FilterValue]
+
+# A vector record id may be a string or an integer. Integer ids must round-trip
+# to the API as JSON numbers (not strings), otherwise the server rewrites them.
+VectorId = Union[str, int]
+
+
+class VectorAmpClientError(RuntimeError):
+    """Raised when the VectorAmp API returns an error."""
+
+
+class VectorAmpHTTPClient:
+    """Minimal client for dataset text insertion and text search endpoints."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.vectoramp.com",
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+        async_http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("VECTORAMP_API_KEY") or ""
+        if not self.api_key:
+            raise ValueError("api_key is required or VECTORAMP_API_KEY must be set.")
+        self.base_url = base_url.rstrip("/")
+        self._owns_client = http_client is None
+        self._owns_async_client = async_http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._async_client = async_http_client or httpx.AsyncClient(timeout=timeout)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    async def aclose(self) -> None:
+        if self._owns_async_client:
+            await self._async_client.aclose()
+
+    def get_dataset_id(self, *, dataset_id: Optional[str], dataset_name: Optional[str]) -> str:
+        if dataset_id:
+            return dataset_id
+        if not dataset_name:
+            raise ValueError("dataset_id or dataset_name is required.")
+        page = self._request("GET", "/datasets", params={"limit": 100, "offset": 0})
+        for dataset in page.get("datasets", []):
+            if dataset.get("name") == dataset_name:
+                value = dataset.get("id") or dataset.get("dataset_id")
+                if value is not None:
+                    return str(value)
+        raise ValueError(f"Dataset named {dataset_name!r} was not found.")
+
+    async def aget_dataset_id(
+        self, *, dataset_id: Optional[str], dataset_name: Optional[str]
+    ) -> str:
+        if dataset_id:
+            return dataset_id
+        if not dataset_name:
+            raise ValueError("dataset_id or dataset_name is required.")
+        page = await self._arequest("GET", "/datasets", params={"limit": 100, "offset": 0})
+        for dataset in page.get("datasets", []):
+            if dataset.get("name") == dataset_name:
+                value = dataset.get("id") or dataset.get("dataset_id")
+                if value is not None:
+                    return str(value)
+        raise ValueError(f"Dataset named {dataset_name!r} was not found.")
+
+    def add_texts(
+        self,
+        dataset_id: str,
+        texts: Sequence[str],
+        *,
+        ids: Optional[Sequence[VectorId]] = None,
+        metadatas: Optional[Sequence[Mapping[str, Any]]] = None,
+    ) -> list[VectorId]:
+        embeddings = self._embed(dataset_id, texts)
+        vector_ids = self._build_ids(texts, ids)
+        self._insert_vectors(dataset_id, texts, embeddings, vector_ids, metadatas)
+        return vector_ids
+
+    async def aadd_texts(
+        self,
+        dataset_id: str,
+        texts: Sequence[str],
+        *,
+        ids: Optional[Sequence[VectorId]] = None,
+        metadatas: Optional[Sequence[Mapping[str, Any]]] = None,
+    ) -> list[VectorId]:
+        embeddings = await self._aembed(dataset_id, texts)
+        vector_ids = self._build_ids(texts, ids)
+        await self._ainsert_vectors(dataset_id, texts, embeddings, vector_ids, metadatas)
+        return vector_ids
+
+    def search(self, dataset_id: str, query: str, *, k: int, **kwargs: Any) -> JSON:
+        return self._request(
+            "POST", f"/datasets/{dataset_id}/search", json=self._search_body(query, k, kwargs)
+        )
+
+    def intelligence_query(self, body: Mapping[str, Any]) -> JSON:
+        """POST an Intelligence/RAG query and return the JSON answer."""
+        return self._request("POST", "/intelligence/query", json=dict(body))
+
+    async def aintelligence_query(self, body: Mapping[str, Any]) -> JSON:
+        """Async variant of :meth:`intelligence_query`."""
+        return await self._arequest("POST", "/intelligence/query", json=dict(body))
+
+    def list_documents(
+        self,
+        dataset_id: str,
+        *,
+        limit: int = 50,
+        cursor: Optional[str] = None,
+        status: Optional[str] = None,
+    ) -> JSON:
+        return self._request(
+            "GET",
+            f"/datasets/{dataset_id}/documents",
+            params={"limit": limit, "cursor": cursor, "status": status},
+        )
+
+    def retry_job(self, job_id: str) -> JSON:
+        """Queue a fresh full-rerun job from an eligible failed or cancelled job."""
+        return self._request("POST", f"/ingestion/jobs/{job_id}/retry")
+
+    async def aretry_job(self, job_id: str) -> JSON:
+        """Async variant of :meth:`retry_job`."""
+        return await self._arequest("POST", f"/ingestion/jobs/{job_id}/retry")
+
+    def download_document(self, dataset_id: str, document_id: str) -> bytes:
+        response = self._client.request(
+            "GET",
+            f"{self.base_url}/datasets/{dataset_id}/documents/{document_id}/download",
+            headers=self._headers(),
+            follow_redirects=True,
+        )
+        if response.status_code >= 300:
+            raise VectorAmpClientError(
+                f"VectorAmp API error {response.status_code}: {response.text}"
+            )
+        return response.content
+
+    async def asearch(self, dataset_id: str, query: str, *, k: int, **kwargs: Any) -> JSON:
+        return await self._arequest(
+            "POST", f"/datasets/{dataset_id}/search", json=self._search_body(query, k, kwargs)
+        )
+
+    def _embed(self, dataset_id: str, texts: Sequence[str]) -> list[Sequence[float]]:
+        response = self._request(
+            "POST", f"/datasets/{dataset_id}/embed", json={"texts": list(texts)}
+        )
+        return self._extract_embeddings(response, len(texts))
+
+    async def _aembed(self, dataset_id: str, texts: Sequence[str]) -> list[Sequence[float]]:
+        response = await self._arequest(
+            "POST", f"/datasets/{dataset_id}/embed", json={"texts": list(texts)}
+        )
+        return self._extract_embeddings(response, len(texts))
+
+    def _insert_vectors(
+        self,
+        dataset_id: str,
+        texts: Sequence[str],
+        embeddings: Sequence[Sequence[float]],
+        ids: Sequence[VectorId],
+        metadatas: Optional[Sequence[Mapping[str, Any]]],
+    ) -> JSON:
+        return self._request(
+            "POST",
+            f"/datasets/{dataset_id}/insert",
+            json={"vectors": self._vectors(texts, embeddings, ids, metadatas)},
+        )
+
+    async def _ainsert_vectors(
+        self,
+        dataset_id: str,
+        texts: Sequence[str],
+        embeddings: Sequence[Sequence[float]],
+        ids: Sequence[VectorId],
+        metadatas: Optional[Sequence[Mapping[str, Any]]],
+    ) -> JSON:
+        return await self._arequest(
+            "POST",
+            f"/datasets/{dataset_id}/insert",
+            json={"vectors": self._vectors(texts, embeddings, ids, metadatas)},
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Mapping[str, Any]] = None,
+    ) -> JSON:
+        response = self._client.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            params=params,
+            json=json,
+        )
+        return self._decode_response(response)
+
+    async def _arequest(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Mapping[str, Any]] = None,
+    ) -> JSON:
+        response = await self._async_client.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            params=params,
+            json=json,
+        )
+        return self._decode_response(response)
+
+    def _headers(self) -> dict[str, str]:
+        return {"x-api-key": self.api_key, "authorization": f"Bearer {self.api_key}"}
+
+    @staticmethod
+    def _decode_response(response: httpx.Response) -> JSON:
+        if response.status_code >= 400:
+            raise VectorAmpClientError(
+                f"VectorAmp API error {response.status_code}: {response.text}"
+            )
+        if response.status_code == 204 or not response.content:
+            return {}
+        data = response.json()
+        if not isinstance(data, dict):
+            raise VectorAmpClientError("VectorAmp API returned a non-object JSON response.")
+        return data
+
+    @staticmethod
+    def _extract_embeddings(response: Mapping[str, Any], count: int) -> list[Sequence[float]]:
+        embeddings = response.get("embeddings")
+        if not isinstance(embeddings, list) or len(embeddings) != count:
+            raise VectorAmpClientError("Embedding response length did not match input texts.")
+        return embeddings
+
+    @staticmethod
+    def _build_ids(texts: Sequence[str], ids: Optional[Sequence[VectorId]]) -> list[VectorId]:
+        if ids is not None:
+            if len(ids) != len(texts):
+                raise ValueError("ids length must match texts length.")
+            # Preserve the caller's id types. Integer ids stay integers so they
+            # serialize as JSON numbers; everything else is coerced to a string.
+            # (bool is a subclass of int but is not a valid id, so it is excluded.)
+            return [
+                value if isinstance(value, int) and not isinstance(value, bool) else str(value)
+                for value in ids
+            ]
+        return [str(uuid.uuid4()) for _ in texts]
+
+    @staticmethod
+    def _vectors(
+        texts: Sequence[str],
+        embeddings: Sequence[Sequence[float]],
+        ids: Sequence[VectorId],
+        metadatas: Optional[Sequence[Mapping[str, Any]]],
+    ) -> list[JSON]:
+        if metadatas is not None and len(metadatas) != len(texts):
+            raise ValueError("metadatas length must match texts length.")
+        vectors: list[JSON] = []
+        for index, (text, values) in enumerate(zip(texts, embeddings, strict=True)):
+            metadata = dict(metadatas[index]) if metadatas is not None else {}
+            metadata.setdefault("text", text)
+            # ``ids[index]`` keeps its original type (int stays int -> JSON number,
+            # str stays str) so the API never rewrites integer ids.
+            vectors.append({"id": ids[index], "values": list(values), "metadata": metadata})
+        return vectors
+
+    @staticmethod
+    def _search_body(query: str, k: int, kwargs: Mapping[str, Any]) -> JSON:
+        # Metadata filters accept ``filter`` (preferred, LangChain convention) or
+        # ``filters`` (SDK parity). Both map to the API's ``filters`` field; pass
+        # only one.
+        search_text = kwargs.get("search_text")
+        if search_text is not None and search_text != query:
+            raise ValueError(
+                "Use the LangChain query argument for search text, "
+                "not a separate search_text value."
+            )
+        body: JSON = {"query_text": query, "top_k": k, "include_documents": True}
+        filter_value = kwargs.get("filter")
+        filters_value = kwargs.get("filters")
+        if filter_value is not None and filters_value is not None:
+            raise ValueError("Use only one of filter or filters.")
+        filters = filter_value if filter_value is not None else filters_value
+        if filters is not None:
+            body["filters"] = dict(filters)
+        passthrough = {
+            "advanced_filters",
+            "embedding_provider",
+            "embedding_model",
+            "nprobe_override",
+            "rerank_depth_override",
+            "hybrid",
+            "sparse_query",
+            "alpha",
+            "include_embeddings",
+            "include_documents",
+            "include_metadata",
+            "rerank",
+        }
+        for key in passthrough:
+            if key in kwargs and kwargs[key] is not None:
+                body[key] = kwargs[key]
+        # Ergonomic: ``rerank=True`` expands to the full VectorAmp rerank object.
+        if body.get("rerank") is True:
+            body["rerank"] = {
+                "enabled": True,
+                "provider": "vectoramp",
+                "model": "VectorAmp-Rerank-v1",
+            }
+        return body

langchain_vectoramp/intelligence.py

@@ -0,0 +1,196 @@
+"""LangChain Intelligence (RAG) interface for VectorAmp.
+
+Designed for minimal-friction usage: a one-liner answers a question, queries run
+across all datasets by default, and multi-turn conversations "just work" because
+LangChain message history is mapped to the API's ``conversation_history``
+automatically. The caller decides how many prior messages to include simply by
+how many they pass.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Optional, Union
+
+from langchain_core.messages import BaseMessage
+from langchain_core.runnables import Runnable, RunnableConfig
+
+from .client import VectorAmpHTTPClient
+
+JSON = dict[str, Any]
+Turn = dict[str, str]
+Message = Union[BaseMessage, dict[str, Any], str]
+
+# LangChain message ``type`` -> Intelligence ``role``.
+_ROLE_BY_TYPE = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}
+
+
+def _content_to_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):  # LangChain content blocks
+        parts = [
+            block.get("text", "") if isinstance(block, dict) else str(block)
+            for block in content
+        ]
+        return "".join(parts)
+    return str(content)
+
+
+def _to_turn(message: Message) -> Turn:
+    if isinstance(message, BaseMessage):
+        return {
+            "role": _ROLE_BY_TYPE.get(message.type, "user"),
+            "content": _content_to_text(message.content),
+        }
+    if isinstance(message, dict):
+        role = message.get("role") or _ROLE_BY_TYPE.get(str(message.get("type", "")), "user")
+        return {"role": role, "content": _content_to_text(message.get("content", ""))}
+    return {"role": "user", "content": str(message)}
+
+
+class VectorAmpIntelligence(Runnable[Any, str]):
+    """Ask VectorAmp Intelligence (RAG) from LangChain.
+
+    The simplest usage needs only a question::
+
+        intel = VectorAmpIntelligence()          # uses VECTORAMP_API_KEY, all datasets
+        print(intel.ask("What changed in Q4 planning?"))
+
+    Multi-turn follow-ups: pass prior LangChain messages (or plain dicts); they
+    are forwarded as ``conversation_history`` automatically::
+
+        from langchain_core.messages import HumanMessage, AIMessage
+        history = [HumanMessage("What is VectorAmp?"), AIMessage("A vector DB platform.")]
+        intel.ask("Does it support hybrid search?", history=history)
+
+    As a LangChain ``Runnable`` it composes in chains and works with
+    ``RunnableWithMessageHistory`` (pass a list of messages; the last human
+    message is the question and the rest become conversation history)::
+
+        intel.invoke("Summarize the docs")
+        intel.invoke([HumanMessage("hi"), AIMessage("hello"), HumanMessage("and bye?")])
+    """
+
+    def __init__(
+        self,
+        *,
+        dataset_id: Optional[str] = None,
+        dataset_name: Optional[str] = None,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.vectoramp.com",
+        client: Optional[VectorAmpHTTPClient] = None,
+        top_k: Optional[int] = None,
+        include_sources: bool = True,
+    ) -> None:
+        self._client = client or VectorAmpHTTPClient(api_key=api_key, base_url=base_url)
+        self._dataset_id = dataset_id
+        self._dataset_name = dataset_name
+        self._top_k = top_k
+        self._include_sources = include_sources
+
+    def _dataset(self) -> str:
+        # Default to every accessible dataset; only resolve a name/id when given.
+        if self._dataset_id or self._dataset_name:
+            return self._client.get_dataset_id(
+                dataset_id=self._dataset_id, dataset_name=self._dataset_name
+            )
+        return "all"
+
+    def _body(
+        self,
+        query: str,
+        history: Optional[Sequence[Message]],
+        overrides: dict[str, Any],
+    ) -> JSON:
+        body: JSON = {
+            "query": query,
+            "dataset_id": overrides.get("dataset_id") or self._dataset(),
+            "include_sources": overrides.get("include_sources", self._include_sources),
+            "stream": False,
+        }
+        top_k = overrides.get("top_k", self._top_k)
+        if top_k is not None:
+            body["top_k"] = top_k
+        turns = [_to_turn(message) for message in (history or [])]
+        if turns:
+            body["conversation_history"] = turns
+        return body
+
+    def ask(
+        self,
+        query: str,
+        *,
+        history: Optional[Sequence[Message]] = None,
+        **overrides: Any,
+    ) -> str:
+        """Ask a question and return the answer text."""
+        response = self._client.intelligence_query(self._body(query, history, overrides))
+        return str(response.get("answer", ""))
+
+    async def aask(
+        self,
+        query: str,
+        *,
+        history: Optional[Sequence[Message]] = None,
+        **overrides: Any,
+    ) -> str:
+        """Async variant of :meth:`ask`."""
+        data = await self._client.aintelligence_query(self._body(query, history, overrides))
+        return str(data.get("answer", ""))
+
+    def ask_with_sources(
+        self,
+        query: str,
+        *,
+        history: Optional[Sequence[Message]] = None,
+        **overrides: Any,
+    ) -> JSON:
+        """Return the full Intelligence response (answer, sources, metadata)."""
+        return self._client.intelligence_query(self._body(query, history, overrides))
+
+    # --- Runnable interface -------------------------------------------------
+    def invoke(
+        self,
+        input: Any,
+        config: Optional[RunnableConfig] = None,
+        **kwargs: Any,
+    ) -> str:
+        query, history = self._split(input)
+        return self.ask(query, history=history)
+
+    async def ainvoke(
+        self,
+        input: Any,
+        config: Optional[RunnableConfig] = None,
+        **kwargs: Any,
+    ) -> str:
+        query, history = self._split(input)
+        return await self.aask(query, history=history)
+
+    @staticmethod
+    def _split(input: Any) -> tuple[str, list[Message]]:
+        """Normalize Runnable input into (query, history).
+
+        Accepts a plain string, a dict
+        ({query|question|input, history|chat_history|messages}), or a sequence of
+        messages where the last one is the question.
+        """
+        if isinstance(input, str):
+            return input, []
+        if isinstance(input, dict):
+            query = input.get("query") or input.get("question") or input.get("input") or ""
+            history = list(
+                input.get("history") or input.get("chat_history") or input.get("messages") or []
+            )
+            if not query and history:
+                last = history.pop()
+                return _to_turn(last)["content"], history
+            return str(query), history
+        if isinstance(input, Sequence):
+            messages = list(input)
+            if not messages:
+                return "", []
+            last = messages[-1]
+            return _to_turn(last)["content"], messages[:-1]
+        return str(input), []

langchain_vectoramp/loaders.py

@@ -0,0 +1,128 @@
+"""LangChain document loader for VectorAmp dataset documents or search results."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import Any, Optional
+
+from langchain_core.document_loaders import BaseLoader
+from langchain_core.documents import Document
+
+from .client import VectorAmpHTTPClient
+from .vectorstores import VectorAmpVectorStore
+
+
+class VectorAmpLoader(BaseLoader):
+    """Load LangChain documents from VectorAmp retained documents or search results.
+
+    When ``query`` is omitted, the loader uses VectorAmp's public
+    ``/datasets/{id}/documents`` endpoint to iterate retained source documents.
+    When ``query`` is provided, it remains semantic-search-backed and returns the
+    top ``k`` matching documents.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.vectoramp.com",
+        dataset_id: str,
+        client: Optional[Any] = None,
+        query: Optional[str] = None,
+        filter: Optional[Mapping[str, Any]] = None,
+        k: int = 10,
+        metadata: Optional[Mapping[str, Any]] = None,
+        timeout: float = 30.0,
+        **search_kwargs: Any,
+    ) -> None:
+        self.dataset_id = dataset_id
+        self.query = query
+        self.filter = dict(filter) if filter is not None else None
+        self.k = k
+        self.metadata = dict(metadata) if metadata is not None else {}
+        self.search_kwargs = dict(search_kwargs)
+        self._external_client = client
+        self._client = client or VectorAmpHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    def lazy_load(self) -> Iterator[Document]:
+        """Yield retained dataset documents or semantic-search matches."""
+        if not self.query:
+            yield from self._lazy_load_documents()
+            return
+
+        kwargs = dict(self.search_kwargs)
+        if self.filter is not None:
+            kwargs["filter"] = self.filter
+        kwargs.setdefault("include_documents", True)
+        kwargs.setdefault("include_metadata", True)
+        store = VectorAmpVectorStore(client=self._client, dataset_id=self.dataset_id)
+        for document in store.similarity_search(self.query, k=self.k, **kwargs):
+            if self.metadata:
+                document.metadata = {**self.metadata, **document.metadata}
+            yield document
+
+    def _lazy_load_documents(self) -> Iterator[Document]:
+        if not hasattr(self._client, "list_documents"):
+            raise ValueError(
+                "VectorAmpLoader requires query when the client cannot list documents."
+            )
+
+        cursor: Optional[str] = None
+        while True:
+            page = self._client.list_documents(
+                self.dataset_id, limit=self.k, cursor=cursor, status="ready"
+            )
+            documents = page.get("documents") or page.get("data") or page.get("items") or []
+            if not documents:
+                break
+            for item in documents:
+                if not isinstance(item, Mapping):
+                    continue
+                content = self._document_content(item)
+                if content is None:
+                    if not hasattr(self._client, "download_document"):
+                        continue
+                    document_id = item.get("id") or item.get("document_id")
+                    if document_id is None:
+                        continue
+                    content = self._client.download_document(
+                        self.dataset_id, str(document_id)
+                    ).decode("utf-8", errors="replace")
+                metadata = {
+                    key: value
+                    for key, value in item.items()
+                    if key not in {"text", "content", "page_content", "doc_value"}
+                }
+                if self.metadata:
+                    metadata = {**self.metadata, **metadata}
+                doc_id = item.get("id") or item.get("document_id")
+                yield Document(
+                    page_content=str(content),
+                    metadata=metadata,
+                    id=str(doc_id) if doc_id is not None else None,
+                )
+
+            cursor = page.get("next_cursor") or page.get("nextCursor")
+            if not cursor:
+                break
+
+    @staticmethod
+    def _document_content(item: Mapping[str, Any]) -> Any:
+        for key in ("text", "content", "page_content", "doc_value"):
+            value = item.get(key)
+            if value is not None:
+                return value
+        return None
+
+    def load(self) -> list[Document]:
+        """Return all documents from :meth:`lazy_load`."""
+        return list(self.lazy_load())
+
+    def close(self) -> None:
+        """Close owned HTTP resources."""
+        if self._external_client is None and hasattr(self._client, "close"):
+            self._client.close()