MLT rebase

Author: ankitml

README.md

@@ -64,12 +64,12 @@ Product.objects.filter(description=ParadeDB('shoes'))
 
 Check out some examples:
 
-- [Quick Start](examples/quickstart.py)
-- [Faceted Search](examples/faceted_search.py)
-- [Autocomplete](examples/autocomplete.py)
-- [More Like This](examples/more_like_this.py)
-- [Hybrid Search (RRF)](examples/hybrid_rrf.py)
-- [RAG](examples/rag.py)
+- [Quick Start](examples/quickstart/quickstart.py)
+- [Faceted Search](examples/faceted_search/faceted_search.py)
+- [Autocomplete](examples/autocomplete/autocomplete.py)
+- [More Like This](examples/more_like_this/more_like_this.py)
+- [Hybrid Search (RRF)](examples/hybrid_rrf/hybrid_rrf.py)
+- [RAG](examples/rag/rag.py)
 
 ## BM25 Index
 
@@ -224,6 +224,11 @@ Product.objects.filter(MoreLikeThis(product_id=42))
 # Similar to multiple documents
 Product.objects.filter(MoreLikeThis(product_ids=[1, 2, 3]))
 
+# Similar to a custom document
+Product.objects.filter(
+    MoreLikeThis(document={"description": "comfortable running shoes"})
+)
+
 # With tuning parameters
 Product.objects.filter(
     MoreLikeThis(

examples/README.md

@@ -188,15 +188,12 @@ Product.objects.filter(
     MoreLikeThis(product_ids=[5, 12, 23], fields=["description"])
 )
 
-# Similar to text (user describes what they want)
+# Similar to a custom document (user describes what they want)
 Product.objects.filter(
-    MoreLikeThis(text='{"description": "comfortable running shoes"}')
+    MoreLikeThis(document={"description": "comfortable running shoes"})
 )
 ```
 
-> **Note:** `MoreLikeThis` is used directly in `.filter()`, not wrapped in `ParadeDB()`.
-> This is because it's a table-level similarity query, not a field-targeted search.
-
 **Tuning Parameters:**
 
 | Parameter | Description | Default |
@@ -207,7 +204,6 @@ Product.objects.filter(
 | `max_doc_freq` | Maximum docs term can appear in | unlimited |
 
 ```python
-# Tuned for precision
 Product.objects.filter(
     MoreLikeThis(
         product_id=5,

examples/more_like_this/more_like_this.py

@@ -2,19 +2,21 @@
 """MoreLikeThis example: find similar documents without vectors.
 
 This example demonstrates ParadeDB's MoreLikeThis feature, which finds similar
-documents based on term frequency analysis (TF-IDF), not vector embeddings.
-
-NOTE: MoreLikeThis is used directly in .filter(), not wrapped in ParadeDB().
-This is because it's a table-level similarity query that uses the primary key
-internally, rather than a field-targeted search expression.
+documents based BM25 provided by ParadeDB, not vector embeddings.
 
 Use cases:
 - "Related products" on product pages
 - "Similar articles" recommendations
 - Content discovery and exploration
 """
 
-from _common import MockItem, setup_mock_items
+import sys
+from pathlib import Path
+
+# Add parent directory to path for importing common utilities
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from common import MockItem, setup_mock_items
 
 from paradedb.functions import Score
 from paradedb.search import MoreLikeThis
@@ -83,8 +85,8 @@ def demo_similar_to_multiple_products() -> None:
         print(f"  {item.id}: {item.description[:50]}... [{item.category}]")
 
 
-def demo_similar_by_text() -> None:
-    """Find products similar to a text description.
+def demo_similar_by_document() -> None:
+    """Find products similar to a custom document.
 
     Use case: User describes what they want, find matching products.
     This is different from regular search - it uses MLT's term analysis.
@@ -97,11 +99,10 @@ def demo_similar_by_text() -> None:
     user_description = "comfortable wireless audio for running"
     print(f"\nUser wants: '{user_description}'")
 
-    # MoreLikeThis with text requires fields parameter
     print("\nMatching products:")
     similar = (
         MockItem.objects.filter(
-            MoreLikeThis(text=user_description, fields=["description"])
+            MoreLikeThis(document={"description": user_description})
         )
         .annotate(score=Score())
         .order_by("-score")[:5]
@@ -235,7 +236,7 @@ def demo_multifield_similarity() -> None:
 
     demo_similar_to_single_product()
     demo_similar_to_multiple_products()
-    demo_similar_by_text()
+    demo_similar_by_document()
     demo_tuning_parameters()
     demo_combined_with_filters()
     demo_multifield_similarity()