FEATURE: Add retriever for Outline (#13889)

- **Description:** Added a retriever for the Outline API to ask
questions on knowledge base
  - **Issue:** resolves #11814
  - **Dependencies:** None
  - **Tag maintainer:** @baskaryan

libs/langchain/langchain/retrievers/__init__.py

@@ -50,6 +50,7 @@ from langchain.retrievers.metal import MetalRetriever
 from langchain.retrievers.milvus import MilvusRetriever
 from langchain.retrievers.multi_query import MultiQueryRetriever
 from langchain.retrievers.multi_vector import MultiVectorRetriever
+from langchain.retrievers.outline import OutlineRetriever
 from langchain.retrievers.parent_document_retriever import ParentDocumentRetriever
 from langchain.retrievers.pinecone_hybrid_search import PineconeHybridSearchRetriever
 from langchain.retrievers.pubmed import PubMedRetriever
@@ -92,6 +93,7 @@ __all__ = [
     "MetalRetriever",
     "MilvusRetriever",
     "MultiQueryRetriever",
+    "OutlineRetriever",
     "PineconeHybridSearchRetriever",
     "PubMedRetriever",
     "RemoteLangChainRetriever",

libs/langchain/langchain/retrievers/outline.py

@@ -0,0 +1,20 @@
+from typing import List
+
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+
+from langchain.callbacks.manager import CallbackManagerForRetrieverRun
+from langchain.utilities.outline import OutlineAPIWrapper
+
+
+class OutlineRetriever(BaseRetriever, OutlineAPIWrapper):
+    """Retriever for Outline API.
+
+    It wraps run() to get_relevant_documents().
+    It uses all OutlineAPIWrapper arguments without any change.
+    """
+
+    def _get_relevant_documents(
+        self, query: str, *, run_manager: CallbackManagerForRetrieverRun
+    ) -> List[Document]:
+        return self.run(query=query)

libs/langchain/langchain/utilities/__init__.py

@@ -122,6 +122,12 @@ def _import_openweathermap() -> Any:
     return OpenWeatherMapAPIWrapper
 
 
+def _import_outline() -> Any:
+    from langchain.utilities.outline import OutlineAPIWrapper
+
+    return OutlineAPIWrapper
+
+
 def _import_portkey() -> Any:
     from langchain.utilities.portkey import Portkey
 
@@ -251,6 +257,8 @@ def __getattr__(name: str) -> Any:
         return _import_metaphor_search()
     elif name == "OpenWeatherMapAPIWrapper":
         return _import_openweathermap()
+    elif name == "OutlineAPIWrapper":
+        return _import_outline()
     elif name == "Portkey":
         return _import_portkey()
     elif name == "PowerBIDataset":
@@ -305,6 +313,7 @@ __all__ = [
     "MaxComputeAPIWrapper",
     "MetaphorSearchAPIWrapper",
     "OpenWeatherMapAPIWrapper",
+    "OutlineAPIWrapper",
     "Portkey",
     "PowerBIDataset",
     "PubMedAPIWrapper",

libs/langchain/langchain/utilities/outline.py

@@ -0,0 +1,96 @@
+"""Util that calls Outline."""
+import logging
+from typing import Any, Dict, List, Optional
+
+import requests
+from langchain_core.documents import Document
+from langchain_core.pydantic_v1 import BaseModel, root_validator
+
+from langchain.utils import get_from_dict_or_env
+
+logger = logging.getLogger(__name__)
+
+OUTLINE_MAX_QUERY_LENGTH = 300
+
+
+class OutlineAPIWrapper(BaseModel):
+    """Wrapper around OutlineAPI.
+
+    This wrapper will use the Outline API to query the documents of your instance.
+    By default it will return the document content of the top-k results.
+    It limits the document content by doc_content_chars_max.
+    """
+
+    top_k_results: int = 3
+    load_all_available_meta: bool = False
+    doc_content_chars_max: int = 4000
+    outline_instance_url: Optional[str] = None
+    outline_api_key: Optional[str] = None
+    outline_search_endpoint: str = "/api/documents.search"
+
+    @root_validator()
+    def validate_environment(cls, values: Dict) -> Dict:
+        """Validate that instance url and api key exists in environment."""
+        outline_instance_url = get_from_dict_or_env(
+            values, "outline_instance_url", "OUTLINE_INSTANCE_URL"
+        )
+        values["outline_instance_url"] = outline_instance_url
+
+        outline_api_key = get_from_dict_or_env(
+            values, "outline_api_key", "OUTLINE_API_KEY"
+        )
+        values["outline_api_key"] = outline_api_key
+
+        return values
+
+    def _result_to_document(self, outline_res: Any) -> Document:
+        main_meta = {
+            "title": outline_res["document"]["title"],
+            "source": self.outline_instance_url + outline_res["document"]["url"],
+        }
+        add_meta = (
+            {
+                "id": outline_res["document"]["id"],
+                "ranking": outline_res["ranking"],
+                "collection_id": outline_res["document"]["collectionId"],
+                "parent_document_id": outline_res["document"]["parentDocumentId"],
+                "revision": outline_res["document"]["revision"],
+                "created_by": outline_res["document"]["createdBy"]["name"],
+            }
+            if self.load_all_available_meta
+            else {}
+        )
+        doc = Document(
+            page_content=outline_res["document"]["text"][: self.doc_content_chars_max],
+            metadata={
+                **main_meta,
+                **add_meta,
+            },
+        )
+        return doc
+
+    def _outline_api_query(self, query: str) -> List:
+        raw_result = requests.post(
+            f"{self.outline_instance_url}{self.outline_search_endpoint}",
+            data={"query": query, "limit": self.top_k_results},
+            headers={"Authorization": f"Bearer {self.outline_api_key}"},
+        )
+
+        if not raw_result.ok:
+            raise ValueError("Outline API returned an error: ", raw_result.text)
+
+        return raw_result.json()["data"]
+
+    def run(self, query: str) -> List[Document]:
+        """
+        Run Outline search and get the document content plus the meta information.
+
+        Returns: a list of documents.
+
+        """
+        results = self._outline_api_query(query[:OUTLINE_MAX_QUERY_LENGTH])
+        docs = []
+        for result in results[: self.top_k_results]:
+            if doc := self._result_to_document(result):
+                docs.append(doc)
+        return docs

libs/langchain/tests/integration_tests/utilities/test_outline.py

@@ -0,0 +1,116 @@
+"""Integration test for Outline API Wrapper."""
+from typing import List
+
+import pytest
+import responses
+from langchain_core.documents import Document
+
+from langchain.utilities import OutlineAPIWrapper
+
+OUTLINE_INSTANCE_TEST_URL = "https://app.getoutline.com"
+OUTLINE_SUCCESS_RESPONSE = {
+    "data": [
+        {
+            "ranking": 0.3911583,
+            "context": "Testing Context",
+            "document": {
+                "id": "abb2bf15-a597-4255-8b19-b742e3d037bf",
+                "url": "/doc/quick-start-jGuGGGOTuL",
+                "title": "Test Title",
+                "text": "Testing Content",
+                "createdBy": {"name": "John Doe"},
+                "revision": 3,
+                "collectionId": "93f182a4-a591-4d47-83f0-752e7bb2065c",
+                "parentDocumentId": None,
+            },
+        },
+    ],
+    "status": 200,
+    "ok": True,
+}
+
+OUTLINE_EMPTY_RESPONSE = {
+    "data": [],
+    "status": 200,
+    "ok": True,
+}
+
+OUTLINE_ERROR_RESPONSE = {
+    "ok": False,
+    "error": "authentication_required",
+    "status": 401,
+    "message": "Authentication error",
+}
+
+
+@pytest.fixture
+def api_client() -> OutlineAPIWrapper:
+    return OutlineAPIWrapper(
+        outline_api_key="api_key", outline_instance_url=OUTLINE_INSTANCE_TEST_URL
+    )
+
+
+def assert_docs(docs: List[Document], all_meta: bool = False) -> None:
+    for doc in docs:
+        assert doc.page_content
+        assert doc.metadata
+        main_meta = {"title", "source"}
+        assert set(doc.metadata).issuperset(main_meta)
+        if all_meta:
+            assert len(set(doc.metadata)) > len(main_meta)
+        else:
+            assert len(set(doc.metadata)) == len(main_meta)
+
+
+@responses.activate
+def test_run_success(api_client: OutlineAPIWrapper) -> None:
+    responses.add(
+        responses.POST,
+        api_client.outline_instance_url + api_client.outline_search_endpoint,
+        json=OUTLINE_SUCCESS_RESPONSE,
+        status=200,
+    )
+
+    docs = api_client.run("Testing")
+    assert_docs(docs, all_meta=False)
+
+
+@responses.activate
+def test_run_success_all_meta(api_client: OutlineAPIWrapper) -> None:
+    api_client.load_all_available_meta = True
+    responses.add(
+        responses.POST,
+        api_client.outline_instance_url + api_client.outline_search_endpoint,
+        json=OUTLINE_SUCCESS_RESPONSE,
+        status=200,
+    )
+
+    docs = api_client.run("Testing")
+    assert_docs(docs, all_meta=True)
+
+
+@responses.activate
+def test_run_no_result(api_client: OutlineAPIWrapper) -> None:
+    responses.add(
+        responses.POST,
+        api_client.outline_instance_url + api_client.outline_search_endpoint,
+        json=OUTLINE_EMPTY_RESPONSE,
+        status=200,
+    )
+
+    docs = api_client.run("No Result Test")
+    assert not docs
+
+
+@responses.activate
+def test_run_error(api_client: OutlineAPIWrapper) -> None:
+    responses.add(
+        responses.POST,
+        api_client.outline_instance_url + api_client.outline_search_endpoint,
+        json=OUTLINE_ERROR_RESPONSE,
+        status=401,
+    )
+    try:
+        api_client.run("Testing")
+    except Exception as e:
+        assert "Outline API returned an error:" in str(e)

libs/langchain/tests/unit_tests/retrievers/test_imports.py

@@ -23,6 +23,7 @@ EXPECTED_ALL = [
     "MetalRetriever",
     "MilvusRetriever",
     "MultiQueryRetriever",
+    "OutlineRetriever",
     "PineconeHybridSearchRetriever",
     "PubMedRetriever",
     "RemoteLangChainRetriever",

libs/langchain/tests/unit_tests/utilities/test_imports.py

@@ -20,6 +20,7 @@ EXPECTED_ALL = [
     "MaxComputeAPIWrapper",
     "MetaphorSearchAPIWrapper",
     "OpenWeatherMapAPIWrapper",
+    "OutlineAPIWrapper",
     "Portkey",
     "PowerBIDataset",
     "PubMedAPIWrapper",