tests: harden unit tests (randomize order, add third doc); chore: ignore caches; docs: refine retriever docstrings and README; add examples under docs/

Author: fm1320

.gitignore

@@ -1,5 +1,6 @@
 # Byte-compiled / optimized / DLL files
 __pycache__/
+**/__pycache__/
 *.py[cod]
 *$py.class
 
@@ -36,6 +37,8 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.mypy_cache/
+.ruff_cache/
 htmlcov/
 
 # Type checkers / linters

langchain_superlinked/__pycache__/__init__.cpython-312.pyc

@@ -1,4 +1,9 @@
-"""Retriever for Superlinked."""
+"""LangChain retriever backed by Superlinked.
+
+This module adapts Superlinked query execution to LangChain's retriever
+interface. Provide a Superlinked App instance and a `QueryDescriptor`,
+and map a result field to `Document.page_content`.
+"""
 
 from __future__ import annotations
 
@@ -188,16 +193,16 @@ def validate_superlinked_packages(cls, values: Dict[str, Any]) -> Dict[str, Any]
     def _get_relevant_documents(
         self, query: str, *, run_manager: CallbackManagerForRetrieverRun, **kwargs: Any
     ) -> List[Document]:
-        """
-        Retrieve relevant documents from Superlinked.
+        """Retrieve relevant documents from Superlinked.
 
         Args:
-            query: The user's text query.
-            run_manager: The callback manager for the retriever run.
-            **kwargs: Additional parameters to pass to the Superlinked query at runtime.
+            query: User query text.
+            run_manager: Callback manager for this retriever run.
+            **kwargs: Extra parameters forwarded to Superlinked
+                (for example, weights, filters, `k`).
 
         Returns:
-            A list of relevant LangChain Documents.
+            List of `Document` mapped from Superlinked results.
         """
         # Extract k parameter before building query_params
         k = kwargs.pop("k", self.k)

langchain_superlinked/__pycache__/retrievers.cpython-312.pyc

@@ -1,5 +1,6 @@
 """Unit tests for SuperlinkedRetriever."""
 
+import random
 from unittest.mock import Mock
 
 from langchain_core.callbacks import CallbackManagerForRetrieverRun
@@ -40,8 +41,19 @@ def test_get_relevant_documents_success(self) -> None:
             "category": "landmark",
         }
 
+        mock_entry3 = Mock()
+        mock_entry3.id = "3"
+        mock_entry3.fields = {
+            "text": "Machine learning enables predictive analytics.",
+            "category": "technology",
+        }
+
+        # Randomize entry order to enforce order-independence
+        entries = [mock_entry1, mock_entry2, mock_entry3]
+        random.shuffle(entries)
+
         mock_result = Mock()
-        mock_result.entries = [mock_entry1, mock_entry2]
+        mock_result.entries = entries
         retriever.sl_client.query.return_value = mock_result
 
         # Test the actual method implementation
@@ -50,13 +62,18 @@ def test_get_relevant_documents_success(self) -> None:
             retriever, "landmarks", run_manager=run_manager
         )
 
-        # Verify results
-        assert len(docs) == 2
-        assert isinstance(docs[0], Document)
-        assert docs[0].page_content == "The Eiffel Tower is in Paris."
-        assert docs[0].metadata == {"id": "1", "category": "landmark"}
-        assert docs[1].page_content == "The Colosseum is in Rome."
-        assert docs[1].metadata == {"id": "2", "category": "landmark"}
+        # Verify results (order-independent)
+        assert len(docs) == 3
+        assert all(isinstance(d, Document) for d in docs)
+        expected = {
+            ("The Eiffel Tower is in Paris.", ("1", "landmark")),
+            ("The Colosseum is in Rome.", ("2", "landmark")),
+            ("Machine learning enables predictive analytics.", ("3", "technology")),
+        }
+        got = {
+            (d.page_content, (d.metadata["id"], d.metadata["category"])) for d in docs
+        }
+        assert got == expected
 
     def test_get_relevant_documents_with_k_parameter(self) -> None:
         """Test retrieval with k parameter limiting results."""