feat(langgraph): optional LangGraph search pipeline (Sprint 1+2)

README.md

@@ -196,6 +196,61 @@ Enable `DELTA_INDEXING: True` to skip objects that haven’t changed since last
 | `redis` | `OPTIONS.alias` | Production |
 | `db` | `OPTIONS.alias` | Simple setup |
 
+## LangGraph-powered search pipeline (optional)
+
+Starting with this version, `django-graph-search` ships with an **optional**
+orchestration layer built on top of [LangGraph](https://langchain-ai.github.io/langgraph/).
+It is disabled by default; the public API (`Searcher.search`,
+`Searcher.find_similar`, REST endpoints) is fully backwards-compatible.
+
+When enabled, the pipeline runs as a small graph:
+
+```
+analyze_query → [expand_query] → vector_search → [rerank] → postprocess
+```
+
+Steps in `[brackets]` are toggled via settings, and each one degrades
+gracefully: if the LLM backend fails or is not configured, the pipeline keeps
+working using the deterministic vector search.
+
+```python
+GRAPH_SEARCH = {
+    # ... your existing config ...
+    "LANGGRAPH": {
+        "ENABLED": True,                # Master switch.
+        "QUERY_EXPANSION": True,        # Generate semantic reformulations.
+        "RERANKING": True,              # Rerank top-K candidates.
+        "MAX_EXPANDED_QUERIES": 3,
+        "RERANK_TOP_K": 20,
+        "TIMEOUT_SECONDS": 15,
+        "MAX_QUERY_LENGTH": 1024,
+        "FALLBACK_ON_ERROR": True,      # Fall back to legacy search on graph errors.
+        "USE_FOR_SIMILAR": False,       # Route find_similar through the graph.
+        "LLM": {
+            # Leave BACKEND=None to use the deterministic dummy backend.
+            "BACKEND": None,
+            "MODEL": None,
+            "OPTIONS": {},
+        },
+    },
+}
+```
+
+### Bring your own LLM backend
+
+Implement `django_graph_search.llm.BaseLLMBackend` and point
+`LANGGRAPH.LLM.BACKEND` at the dotted path. The contract is intentionally
+tiny — `expand_query(query, models, max_variants)` and
+`rerank(query, candidates, top_k)` — so you can wrap any provider
+(OpenAI, Ollama, vLLM, your in-house service) in a few lines.
+
+### Why optional?
+
+The library refuses to add hard dependencies on `langgraph` or any LLM SDK.
+If `langgraph` is not installed, the pipeline transparently uses an in-tree
+sequential runner with the same node structure, so behaviour and tests stay
+identical.
+
 ## Comparison
 
 | Feature | django-graph-search | Haystack | django-elasticsearch-dsl |

setup.cfg

@@ -40,8 +40,12 @@ qdrant =
     qdrant-client>=1.6.0
 test =
     pytest>=9.0.0
+    pytest-django>=4.0
+langgraph =
+    langgraph>=0.2.0
 all =
     chromadb>=0.5.0
     faiss-cpu>=1.7.4
     qdrant-client>=1.6.0
+    langgraph>=0.2.0