fixed the comments

Author: pavanjava

README.md

@@ -7,7 +7,7 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen)](tests/)
 
-Write `INSERT`, `SEARCH`, `RECOMMEND`, `DELETE`, and `CREATE COLLECTION` statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, binary, product), SQL-style `WHERE` filters, script execution, and collection dump/restore.
+Write `INSERT`, `SEARCH`, `RECOMMEND`, `DELETE`, and `CREATE COLLECTION` statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, turbo, binary, product), SQL-style `WHERE` filters, script execution, and collection dump/restore.
 
 ```
 qql> INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is a vector database', 'author': 'alice', 'year': 2024}
@@ -84,7 +84,7 @@ Full documentation lives in the [`docs/`](docs/) folder and at **[pavanjava.gith
 | [INSERT / INSERT BULK](docs/insert.md) | Adding documents, batch inserts, payload types |
 | [SEARCH / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, hybrid, reranking, recommendations |
 | [WHERE Filters](docs/filters.md) | Full SQL-style filter operators |
-| [Collections & Quantization](docs/collections.md) | CREATE, DROP, QUANTIZE (scalar/binary/product), CREATE INDEX |
+| [Collections & Quantization](docs/collections.md) | CREATE, DROP, QUANTIZE (scalar/turbo/binary/product), CREATE INDEX |
 | [Scripts: EXECUTE / DUMP](docs/scripts.md) | Script files, collection backup/restore |
 | [Programmatic Usage](docs/programmatic.md) | Use QQL as a Python library |
 | [Reference: Models / Config / Errors](docs/reference.md) | Embedding models, config file, error reference |

docs/collections.md

@@ -67,7 +67,7 @@ When `USING MODEL` is omitted, the collection uses the **default embedding model
 
 ## Quantization — QUANTIZE clause
 
-Quantization reduces the memory footprint of vector collections and speeds up search at the cost of a small, controllable accuracy loss. QQL supports all three Qdrant quantization strategies via an optional `QUANTIZE` clause appended to `CREATE COLLECTION`.
+Quantization reduces the memory footprint of vector collections and speeds up search at the cost of a small, controllable accuracy loss. QQL supports all four Qdrant quantization strategies via an optional `QUANTIZE` clause appended to `CREATE COLLECTION`.
 
 **Four strategies:**
 
@@ -87,15 +87,18 @@ CREATE COLLECTION <name> ... QUANTIZE PRODUCT [ALWAYS RAM]
 ```
 
 - **`QUANTILE <float>`** — (SCALAR only) calibration quantile for the INT8 conversion; defaults to Qdrant's built-in default (0.99) when omitted.
-- **`BITS <depth>`** — (TURBO only) bit depth controlling compression ratio:
-  - `4` — 4-bit, **8×** compression (default when `BITS` is omitted)
-  - `2` — 2-bit, **16×** compression
-  - `1.5` — 1.5-bit, **24×** compression
-  - `1` — 1-bit, **32×** compression (same ratio as BINARY, but better recall)
+- **`BITS <depth>`** — (TURBO only) bit depth passed to the Qdrant SDK:
+  - `4` — 4-bit (default when `BITS` is omitted; server applies its own default)
+  - `2` — 2-bit
+  - `1.5` — 1.5-bit
+  - `1` — 1-bit
+  > Compression ratios (8×, 16×, 24×, 32×) and recall characteristics are
+  > Qdrant server-side behaviors. QQL maps the `BITS` value to the SDK model and
+  > passes it to Qdrant; actual results depend on your Qdrant server version.
 - **`ALWAYS RAM`** — keep the **quantized** vectors in RAM at all times, regardless of the collection's `on_disk` setting. Improves search throughput at the cost of higher RAM usage for the compressed index. The original full-precision vectors are stored and managed independently of this flag. Supported by all four quantization types.
 - **`QUANTIZE`** always appears **after** all other clauses (`HYBRID`, `USING MODEL`, etc.).
 - For `PRODUCT`, the compression ratio is fixed at **4×** in this version.
-- For `TURBO`, all distance metrics are supported; `TURBO` fully supports Cosine, Dot, and Euclidean with SIMD-accelerated scoring.
+- For `TURBO`, Cosine, Dot, and Euclidean distance are supported by the Qdrant server when TurboQuant is enabled.
 - When used with `HYBRID` collections, quantization applies only to the **dense** vector.
 
 **Examples:**

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "qql-cli"
 version = "2.0.0"
-description = "QQL is a SQL-like query language and CLI for Qdrant vector database. Write INSERT, SEARCH, RECOMMEND, DELETE, and CREATE COLLECTION statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, binary, product), WHERE clause filters, script execution, and collection dump/restore."
+description = "QQL is a SQL-like query language and CLI for Qdrant vector database. Write INSERT, SEARCH, RECOMMEND, DELETE, and CREATE COLLECTION statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, turbo, binary, product), WHERE clause filters, script execution, and collection dump/restore."
 readme = "README.md"
 license = { file = "LICENSE" }
 requires-python = ">=3.12"

src/qql/executor.py

@@ -877,7 +877,15 @@ def _build_quantization_config(
                 1.5: TurboQuantBitSize.BITS1_5,
                 1.0: TurboQuantBitSize.BITS1,
             }
-            bits_enum = _BITS_MAP.get(qc.turbo_bits or 4.0, TurboQuantBitSize.BITS4)
+            if qc.turbo_bits is None:
+                bits_enum = None           # user omitted BITS → preserve None, server applies default
+            elif qc.turbo_bits in _BITS_MAP:
+                bits_enum = _BITS_MAP[qc.turbo_bits]
+            else:
+                raise QQLRuntimeError(
+                    f"Unsupported TURBO bit depth: {qc.turbo_bits}. "
+                    f"Valid values: 1, 1.5, 2, 4"
+                )
             return TurboQuantization(
                 turbo=TurboQuantQuantizationConfig(
                     bits=bits_enum,

tests/test_executor.py

@@ -1661,15 +1661,16 @@ def test_turbo_passes_turbo_quantization(self, executor, mock_client):
         kw = mock_client.create_collection.call_args.kwargs
         assert isinstance(kw.get("quantization_config"), TurboQuantization)
 
-    def test_turbo_default_bits_is_bits4(self, executor, mock_client):
-        from qdrant_client.models import TurboQuantBitSize
+    def test_turbo_default_bits_is_none(self, executor, mock_client):
+        """When BITS is omitted, bits must be None — preserving omission so the
+        SDK/server applies its own default rather than QQL forcing BITS4."""
         node = CreateCollectionStmt(
             collection="articles",
             quantization=QuantizationConfig(type=QuantizationType.TURBO),
         )
         executor.execute(node)
         kw = mock_client.create_collection.call_args.kwargs
-        assert kw["quantization_config"].turbo.bits == TurboQuantBitSize.BITS4
+        assert kw["quantization_config"].turbo.bits is None
 
     def test_turbo_bits2(self, executor, mock_client):
         from qdrant_client.models import TurboQuantBitSize
@@ -1738,3 +1739,11 @@ def test_turbo_result_message_includes_turbo(self, executor, mock_client):
         )
         result = executor.execute(node)
         assert "turbo" in result.message
+
+    def test_turbo_invalid_bits_at_executor_raises(self, executor, mock_client):
+        """An unexpected turbo_bits value that bypasses parser validation must
+        raise QQLRuntimeError explicitly instead of silently coercing to BITS4."""
+        from qql.exceptions import QQLRuntimeError as QQLErr
+        qc = QuantizationConfig(type=QuantizationType.TURBO, turbo_bits=3.0)
+        with pytest.raises(QQLErr, match="Unsupported TURBO bit depth"):
+            executor._build_quantization_config(qc)