feat: Full Qdrant Recommend API support

Add OFFSET, SCORE THRESHOLD, WITH clause, LOOKUP FROM, and USING
to RECOMMEND statements, closing the gap with the Qdrant query_points
recommend surface.

Parser:
- Parse LOOKUP FROM <collection> [VECTOR '<name>'] for cross-collection
  recommendation
- Parse USING '<vector_name>' to target a specific named vector
- Parse OFFSET <n> for pagination
- Parse SCORE THRESHOLD <f> for minimum score filtering
- Parse WITH { exact: true, hnsw_ef: <n> } for query-time search params

Executor:
- Wire offset, score_threshold, search_params, using, and lookup_from
  to Qdrant query_points()
- Use LookupLocation for cross-collection ID lookups

Tests:
- Parser coverage for all new clauses and combined forms
- Executor coverage verifying forwarding to the Qdrant client

Docs:
- Update README with full RECOMMEND syntax reference
- Update sample_v2.qql with OFFSET, SCORE THRESHOLD, WITH, and USING
  examples

Author: srimon12

README.md

@@ -392,10 +392,16 @@ This is useful when you already know which stored points represent the kind of r
 
 **Syntax:**
 ```sql
-RECOMMEND FROM <collection_name> POSITIVE IDS (1001, 1002) LIMIT <n>
-RECOMMEND FROM <collection_name> POSITIVE IDS (1001, 1002) NEGATIVE IDS (1003) LIMIT <n>
-RECOMMEND FROM <collection_name> POSITIVE IDS (1001) STRATEGY 'best_score' LIMIT <n>
-RECOMMEND FROM <collection_name> POSITIVE IDS (1001) LIMIT <n> WHERE <filter>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) NEGATIVE IDS (<id>, ...) LIMIT <n>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) STRATEGY '<strategy>' LIMIT <n>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n> WHERE <filter>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n> OFFSET <n>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n> SCORE THRESHOLD <f>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n> WITH { exact: true, hnsw_ef: <n> }
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n> LOOKUP FROM <collection>
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n> LOOKUP FROM <collection> VECTOR '<name>'
+RECOMMEND FROM <collection_name> POSITIVE IDS (<id>, ...) LIMIT <n> USING '<vector_name>'
 ```
 
 **Examples:**
@@ -420,12 +426,60 @@ Recommend only within a filtered subset:
 RECOMMEND FROM articles POSITIVE IDS (1001) LIMIT 5 WHERE year >= 2020 AND status = 'published'
 ```
 
+Paginate recommendations (skip first 5, return next 10):
+```sql
+RECOMMEND FROM articles POSITIVE IDS (1001) LIMIT 10 OFFSET 5
+```
+
+Filter out low-confidence recommendations:
+```sql
+RECOMMEND FROM articles POSITIVE IDS (1001) LIMIT 10 SCORE THRESHOLD 0.5
+```
+
+Exact KNN baseline for recommendations:
+```sql
+RECOMMEND FROM articles POSITIVE IDS (1001) LIMIT 5 WITH { exact: true }
+```
+
+Cross-collection recommend (look up example IDs from another collection):
+```sql
+RECOMMEND FROM target_collection
+  POSITIVE IDS ('a')
+  LOOKUP FROM source_collection VECTOR 'dense'
+  LIMIT 5
+```
+
+Recommend using a specific named vector in the target collection:
+```sql
+RECOMMEND FROM articles
+  POSITIVE IDS (1001)
+  USING 'sparse'
+  LIMIT 5
+```
+
+Full-featured recommend:
+```sql
+RECOMMEND FROM articles
+  POSITIVE IDS (1001, 1002)
+  NEGATIVE IDS (1009)
+  STRATEGY 'best_score'
+  LOOKUP FROM other_collection VECTOR 'dense'
+  USING 'dense'
+  LIMIT 10
+  OFFSET 5
+  SCORE THRESHOLD 0.5
+  WHERE year >= 2020
+  WITH { exact: true }
+```
+
 **Supported strategies:**
 
 - `average_vector`
 - `best_score`
 - `sum_scores`
 
+**Clause order:** `POSITIVE IDS` → `NEGATIVE IDS` → `STRATEGY` → `LOOKUP FROM` → `USING` → `LIMIT` → `OFFSET` → `SCORE THRESHOLD` → `WHERE` → `WITH`
+
 ---
 
 ### Query-Time Search Params (`EXACT`, `WITH`)

resources/sample_v2.qql

@@ -74,6 +74,25 @@ RECOMMEND FROM qql_sample_v2
   LIMIT 3
   WHERE department = 'neurology'
 
+-- Recommend with pagination and score threshold
+RECOMMEND FROM qql_sample_v2
+  POSITIVE IDS (2001)
+  LIMIT 5
+  OFFSET 2
+  SCORE THRESHOLD 0.3
+
+-- Recommend with exact KNN baseline
+RECOMMEND FROM qql_sample_v2
+  POSITIVE IDS (2001)
+  LIMIT 3
+  WITH { exact: true }
+
+-- Recommend using sparse vector instead of dense
+RECOMMEND FROM qql_sample_v2_hybrid
+  POSITIVE IDS (4001)
+  LIMIT 3
+  USING 'sparse'
+
 -- Hybrid collection
 CREATE COLLECTION qql_sample_v2_hybrid HYBRID
 

src/qql/ast_nodes.py

@@ -178,6 +178,11 @@ class RecommendStmt:
     limit: int = 10
     strategy: str | None = None
     query_filter: FilterExpr | None = None
+    offset: int = 0
+    score_threshold: float | None = None
+    with_clause: SearchWith | None = None
+    lookup_from: tuple[str, str | None] | None = None
+    using: str | None = None
 
 
 @dataclass(frozen=True)

src/qql/executor.py

@@ -17,6 +17,7 @@
     HasIdCondition,
     IsEmptyCondition,
     IsNullCondition,
+    LookupLocation,
     MatchAny,
     MatchExcept,
     MatchPhrase,
@@ -509,12 +510,26 @@ def _execute_recommend(self, node: RecommendStmt) -> ExecutionResult:
             strategy=self._parse_recommend_strategy(node.strategy),
         )
 
+        search_params = self._build_search_params(node.with_clause)
+
+        lookup_from: LookupLocation | None = None
+        if node.lookup_from is not None:
+            lookup_from = LookupLocation(
+                collection=node.lookup_from[0],
+                vector=node.lookup_from[1],
+            )
+
         try:
             response = self._client.query_points(
                 collection_name=node.collection,
                 query=RecommendQuery(recommend=recommend_input),
                 limit=node.limit,
+                offset=node.offset or None,
                 query_filter=qdrant_filter,
+                search_params=search_params,
+                score_threshold=node.score_threshold,
+                using=node.using,
+                lookup_from=lookup_from,
             )
         except UnexpectedResponse as e:
             raise QQLRuntimeError(f"Qdrant error during RECOMMEND: {e}") from e

src/qql/lexer.py

@@ -33,6 +33,11 @@ class TokenKind(Enum):
     SIMILAR = auto()
     TO = auto()
     LIMIT = auto()
+    OFFSET = auto()
+    SCORE = auto()
+    THRESHOLD = auto()
+    LOOKUP = auto()
+    VECTOR = auto()
     DELETE = auto()
     FROM = auto()
     WHERE = auto()
@@ -103,6 +108,11 @@ class TokenKind(Enum):
     "SIMILAR": TokenKind.SIMILAR,
     "TO": TokenKind.TO,
     "LIMIT": TokenKind.LIMIT,
+    "OFFSET": TokenKind.OFFSET,
+    "SCORE": TokenKind.SCORE,
+    "THRESHOLD": TokenKind.THRESHOLD,
+    "LOOKUP": TokenKind.LOOKUP,
+    "VECTOR": TokenKind.VECTOR,
     "DELETE": TokenKind.DELETE,
     "FROM": TokenKind.FROM,
     "WHERE": TokenKind.WHERE,

src/qql/parser.py

@@ -297,21 +297,58 @@ def _parse_recommend(self) -> RecommendStmt:
             self._advance()
             strategy = self._expect(TokenKind.STRING).value
 
+        lookup_from: tuple[str, str | None] | None = None
+        if self._peek().kind == TokenKind.LOOKUP:
+            self._advance()
+            self._expect(TokenKind.FROM)
+            lookup_collection = self._parse_identifier()
+            lookup_vector: str | None = None
+            if self._peek().kind == TokenKind.VECTOR:
+                self._advance()
+                lookup_vector = self._expect(TokenKind.STRING).value
+            lookup_from = (lookup_collection, lookup_vector)
+
+        using: str | None = None
+        if self._peek().kind == TokenKind.USING:
+            self._advance()
+            using = self._expect(TokenKind.STRING).value
+
         self._expect(TokenKind.LIMIT)
         limit = int(self._expect(TokenKind.INTEGER).value)
 
+        offset: int = 0
+        if self._peek().kind == TokenKind.OFFSET:
+            self._advance()
+            offset = int(self._expect(TokenKind.INTEGER).value)
+
+        score_threshold: float | None = None
+        if self._peek().kind == TokenKind.SCORE:
+            self._advance()
+            self._expect(TokenKind.THRESHOLD)
+            score_threshold = float(self._expect(TokenKind.FLOAT).value)
+
         query_filter: FilterExpr | None = None
         if self._peek().kind == TokenKind.WHERE:
             self._advance()
             query_filter = self._parse_filter_expr()
 
+        with_clause: SearchWith | None = None
+        if self._peek().kind == TokenKind.WITH:
+            self._advance()
+            with_clause = self._parse_with_clause()
+
         return RecommendStmt(
             collection=collection,
             positive_ids=positive_ids,
             negative_ids=negative_ids,
             limit=limit,
             strategy=strategy,
             query_filter=query_filter,
+            offset=offset,
+            score_threshold=score_threshold,
+            with_clause=with_clause,
+            lookup_from=lookup_from,
+            using=using,
         )
 
     def _parse_delete(self) -> DeleteStmt:
@@ -456,12 +493,29 @@ def _parse_predicate(self) -> FilterExpr:
     def _parse_field_path(self) -> str:
         """Dot-notation paths are already single IDENTIFIER tokens from the lexer."""
         tok = self._peek()
-        if tok.kind != TokenKind.IDENTIFIER:
-            raise QQLSyntaxError(
-                f"Expected a field name, got '{tok.value}'", tok.pos
-            )
-        self._advance()
-        return tok.value
+        if tok.kind == TokenKind.IDENTIFIER:
+            self._advance()
+            return tok.value
+        # Allow bare keywords to serve as field names (e.g. score, limit),
+        # but not filter operator keywords or literal tokens.
+        if tok.kind not in {
+            TokenKind.AND, TokenKind.OR, TokenKind.NOT,
+            TokenKind.IN, TokenKind.BETWEEN, TokenKind.IS,
+            TokenKind.NULL, TokenKind.EMPTY, TokenKind.MATCH,
+            TokenKind.ANY, TokenKind.PHRASE,
+            TokenKind.STRING, TokenKind.INTEGER, TokenKind.FLOAT,
+            TokenKind.LPAREN, TokenKind.RPAREN,
+            TokenKind.LBRACE, TokenKind.RBRACE,
+            TokenKind.LBRACKET, TokenKind.RBRACKET,
+            TokenKind.COMMA, TokenKind.COLON, TokenKind.EQUALS,
+            TokenKind.NOT_EQUALS, TokenKind.GT, TokenKind.GTE,
+            TokenKind.LT, TokenKind.LTE, TokenKind.EOF,
+        }:
+            self._advance()
+            return tok.value
+        raise QQLSyntaxError(
+            f"Expected a field name, got '{tok.value}'", tok.pos
+        )
 
     def _parse_literal(self) -> str | int | float:
         """STRING | INTEGER | FLOAT"""

tests/test_executor.py

@@ -516,6 +516,111 @@ def test_recommend_nonexistent_collection_raises(self, executor, mock_client):
         with pytest.raises(QQLRuntimeError, match="does not exist"):
             executor.execute(node)
 
+    def test_recommend_forwards_offset(self, executor, mock_client, mocker):
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes", positive_ids=("a",), limit=5, offset=10
+        )
+        executor.execute(node)
+        assert mock_client.query_points.call_args.kwargs["offset"] == 10
+
+    def test_recommend_forwards_score_threshold(self, executor, mock_client, mocker):
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes", positive_ids=("a",), limit=5, score_threshold=0.5
+        )
+        executor.execute(node)
+        assert mock_client.query_points.call_args.kwargs["score_threshold"] == pytest.approx(0.5)
+
+    def test_recommend_forwards_using(self, executor, mock_client, mocker):
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes", positive_ids=("a",), limit=5, using="sparse"
+        )
+        executor.execute(node)
+        assert mock_client.query_points.call_args.kwargs["using"] == "sparse"
+
+    def test_recommend_forwards_lookup_from(self, executor, mock_client, mocker):
+        from qdrant_client.models import LookupLocation
+
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes",
+            positive_ids=("a",),
+            limit=5,
+            lookup_from=("source", "dense"),
+        )
+        executor.execute(node)
+        lookup = mock_client.query_points.call_args.kwargs["lookup_from"]
+        assert isinstance(lookup, LookupLocation)
+        assert lookup.collection == "source"
+        assert lookup.vector == "dense"
+
+    def test_recommend_forwards_lookup_from_without_vector(self, executor, mock_client, mocker):
+        from qdrant_client.models import LookupLocation
+
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes",
+            positive_ids=("a",),
+            limit=5,
+            lookup_from=("source", None),
+        )
+        executor.execute(node)
+        lookup = mock_client.query_points.call_args.kwargs["lookup_from"]
+        assert isinstance(lookup, LookupLocation)
+        assert lookup.collection == "source"
+        assert lookup.vector is None
+
+    def test_recommend_forwards_search_params(self, executor, mock_client, mocker):
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes",
+            positive_ids=("a",),
+            limit=5,
+            with_clause=SearchWith(exact=True, hnsw_ef=128),
+        )
+        executor.execute(node)
+        search_params = mock_client.query_points.call_args.kwargs["search_params"]
+        assert search_params.exact is True
+        assert search_params.hnsw_ef == 128
+
+    def test_recommend_offset_zero_passes_none(self, executor, mock_client, mocker):
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes", positive_ids=("a",), limit=5, offset=0
+        )
+        executor.execute(node)
+        assert mock_client.query_points.call_args.kwargs["offset"] is None
+
 
 class TestDelete:
     def test_delete_calls_qdrant_delete(self, executor, mock_client):