feat(sdk,tests): add create_text_index/drop_text_index, fix FTS test assumptions

FTS indexing is NOT automatic — a CREATE TEXT INDEX DDL is required
before text_search() can return results.  The previous code and tests
incorrectly assumed automatic indexing.

SDK changes:
- Add TextIndexInfo result class (name, label, properties, documents_indexed)
- Add AsyncCoordinodeClient.create_text_index() and drop_text_index()
- Add CoordinodeClient sync wrappers for both methods
- Export TextIndexInfo from coordinode package
- Fix text_search() docstring: document DDL requirement, remove false
  claim about automatic indexing

Test changes:
- Fix test_text_search_returns_results: create/drop TEXT INDEX around
  the search call; drop empty-results xfail (now a hard assertion)
- Fix test_text_search_fuzzy: create/drop TEXT INDEX; assert results
  are non-empty (was: just verify no exception)
- Fix test_hybrid_text_vector_search_returns_results: add TEXT INDEX
- Update header comment: remove 'automatic indexing' statement

Author: polaz

coordinode/coordinode/__init__.py

@@ -27,6 +27,7 @@
     LabelInfo,
     NodeResult,
     PropertyDefinitionInfo,
+    TextIndexInfo,
     TextResult,
     TraverseResult,
     VectorResult,
@@ -47,5 +48,6 @@
     "LabelInfo",
     "EdgeTypeInfo",
     "PropertyDefinitionInfo",
+    "TextIndexInfo",
     "TraverseResult",
 ]

coordinode/coordinode/client.py

@@ -161,6 +161,23 @@ def __repr__(self) -> str:
         return f"TraverseResult(nodes={len(self.nodes)}, edges={len(self.edges)})"
 
 
+class TextIndexInfo:
+    """Information about a full-text index returned by :meth:`create_text_index`."""
+
+    def __init__(self, row: dict[str, Any]) -> None:
+        self.name: str = str(row.get("index", ""))
+        self.label: str = str(row.get("label", ""))
+        self.properties: str = str(row.get("properties", ""))
+        self.default_language: str = str(row.get("default_language", ""))
+        self.documents_indexed: int = int(row.get("documents_indexed", 0))
+
+    def __repr__(self) -> str:
+        return (
+            f"TextIndexInfo(name={self.name!r}, label={self.label!r},"
+            f" properties={self.properties!r}, documents_indexed={self.documents_indexed})"
+        )
+
+
 # ── Async client ─────────────────────────────────────────────────────────────
 
 
@@ -524,6 +541,57 @@ async def create_edge_type(
         et = await self._schema_stub.CreateEdgeType(req, timeout=self._timeout)
         return EdgeTypeInfo(et)
 
+    async def create_text_index(
+        self,
+        name: str,
+        label: str,
+        properties: str | list[str],
+        *,
+        language: str = "",
+    ) -> TextIndexInfo:
+        """Create a full-text (BM25) index on one or more node properties.
+
+        Args:
+            name: Unique index name (e.g. ``"article_body"``).
+            label: Node label to index (e.g. ``"Article"``).
+            properties: Property name or list of property names to index
+                (e.g. ``"body"`` or ``["title", "body"]``).
+            language: Default stemming/tokenization language (e.g. ``"english"``,
+                ``"russian"``).  Empty string uses the server default
+                (``"english"``).
+
+        Returns:
+            :class:`TextIndexInfo` with index metadata and document count.
+
+        Example::
+
+            info = await client.create_text_index("article_body", "Article", "body")
+            # then: results = await client.text_search("Article", "machine learning")
+        """
+        if isinstance(properties, str):
+            prop_list = [properties]
+        else:
+            prop_list = list(properties)
+        props_expr = ", ".join(prop_list)
+        lang_clause = f" DEFAULT LANGUAGE {language}" if language else ""
+        cypher = f"CREATE TEXT INDEX {name} ON :{label}({props_expr}){lang_clause}"
+        rows = await self.cypher(cypher)
+        if rows:
+            return TextIndexInfo(rows[0])
+        return TextIndexInfo({"index": name, "label": label, "properties": ", ".join(prop_list)})
+
+    async def drop_text_index(self, name: str) -> None:
+        """Drop a full-text index by name.
+
+        Args:
+            name: Index name previously passed to :meth:`create_text_index`.
+
+        Example::
+
+            await client.drop_text_index("article_body")
+        """
+        await self.cypher(f"DROP TEXT INDEX {name}")
+
     async def traverse(
         self,
         start_node_id: int,
@@ -604,6 +672,16 @@ async def text_search(
 
         Returns:
             List of :class:`TextResult` ordered by BM25 score descending.
+            Returns ``[]`` if no text index exists for *label*.
+
+        Note:
+            Text indexing is **not** automatic.  Before calling this method,
+            create a full-text index with the Cypher DDL statement::
+
+                CREATE TEXT INDEX my_index ON :Label(property)
+
+            or via :meth:`create_text_index`.  Nodes written before the index
+            was created are indexed immediately at DDL execution time.
         """
         from coordinode._proto.coordinode.v1.query.text_pb2 import TextSearchRequest  # type: ignore[import]
 
@@ -806,6 +884,21 @@ def create_edge_type(
         """Create an edge type in the schema registry."""
         return self._run(self._async.create_edge_type(name, properties))
 
+    def create_text_index(
+        self,
+        name: str,
+        label: str,
+        properties: str | list[str],
+        *,
+        language: str = "",
+    ) -> TextIndexInfo:
+        """Create a full-text (BM25) index on one or more node properties."""
+        return self._run(self._async.create_text_index(name, label, properties, language=language))
+
+    def drop_text_index(self, name: str) -> None:
+        """Drop a full-text index by name."""
+        return self._run(self._async.drop_text_index(name))
+
     def traverse(
         self,
         start_node_id: int,

tests/integration/test_sdk.py

@@ -20,6 +20,7 @@
     EdgeTypeInfo,
     HybridResult,
     LabelInfo,
+    TextIndexInfo,
     TextResult,
     TraverseResult,
 )
@@ -566,16 +567,13 @@ def test_vector_search_returns_results(client):
 
 
 # FTS tests require a CoordiNode server with TextService implemented (>=0.3.8).
-# They are marked xfail so the suite stays green against older servers; once
-# upgraded, the tests turn into expected passes automatically.
+# They are wrapped with @_fts so the suite stays green against older servers
+# (UNIMPLEMENTED gRPC status → xfail); against >=0.3.8 servers they are real passes.
 #
-# Note: create_label() is intentionally NOT called before text_search().
-# FTS indexing in CoordiNode is automatic for all nodes whose label was written
-# via CREATE/MERGE — no explicit label registration is required.  On schema-strict
-# servers a caller may choose to pre-register a label, but the SDK's text_search()
-# and hybrid_text_vector_search() work on schema-free graphs too.  These tests
-# exercise the common schema-free path; calling create_label() here would test a
-# different (schema-strict) code path and is covered by test_create_label_*.
+# FTS indexing is NOT automatic.  Each test that expects non-empty results must
+# first create a text index with CREATE TEXT INDEX (or client.create_text_index())
+# and drop it in the finally block.  Tests that deliberately cover the "no-index"
+# case (test_text_search_empty_for_unindexed_label) must NOT create an index.
 def _fts(fn):
     """Wrap an FTS test to handle servers without TextService.
 
@@ -606,18 +604,22 @@ def test_text_search_returns_results(client):
     """text_search() finds nodes whose text property matches the query."""
     label = f"FtsTest_{uid()}"
     tag = uid()
+    idx_name = f"idx_{label.lower()}"
     # CoordiNode executor serialises a node variable as Value::Int(node_id) — runner.rs NodeScan
     # path. No id() function needed; rows[0]["node_id"] is the integer internal node id.
     rows = client.cypher(
         f"CREATE (n:{label} {{tag: $tag, body: 'machine learning and neural networks'}}) RETURN n AS node_id",
         params={"tag": tag},
     )
     seed_id = rows[0]["node_id"]
+    # Text index must be created explicitly; nodes written before index creation
+    # are indexed immediately at DDL time.
+    idx_info = client.create_text_index(idx_name, label, "body")
+    assert isinstance(idx_info, TextIndexInfo)
     try:
         results = client.text_search(label, "machine learning", limit=5)
         assert isinstance(results, list)
-        if not results:
-            pytest.xfail("text_search returned no results — FTS index not available on this server")
+        assert results, "text_search returned no results after index creation"
         assert any(r.node_id == seed_id for r in results), (
             f"seeded node {seed_id} not found in text_search results: {results}"
         )
@@ -628,6 +630,7 @@ def test_text_search_returns_results(client):
         assert r.score > 0
         assert isinstance(r.snippet, str)
     finally:
+        client.drop_text_index(idx_name)
         client.cypher(f"MATCH (n:{label} {{tag: $tag}}) DELETE n", params={"tag": tag})
 
 
@@ -663,17 +666,19 @@ def test_text_search_fuzzy(client):
     """text_search() with fuzzy=True matches approximate terms."""
     label = f"FtsFuzzyTest_{uid()}"
     tag = uid()
+    idx_name = f"idx_{label.lower()}"
     client.cypher(
         f"CREATE (n:{label} {{tag: $tag, body: 'coordinode graph database'}})",
         params={"tag": tag},
     )
+    client.create_text_index(idx_name, label, "body")
     try:
-        # "coordinode" with a typo — fuzzy should still match
+        # "coordinode" with a one-character typo — Levenshtein-1 fuzzy must match.
         results = client.text_search(label, "coordinod", fuzzy=True, limit=5)
         assert isinstance(results, list)
-        # May return 0 results if fuzzy is not yet supported or index is cold;
-        # just verify the call does not raise.
+        assert results, "fuzzy text_search returned no results after index creation"
     finally:
+        client.drop_text_index(idx_name)
         client.cypher(f"MATCH (n:{label} {{tag: $tag}}) DELETE n", params={"tag": tag})
 
 
@@ -682,13 +687,15 @@ def test_hybrid_text_vector_search_returns_results(client):
     """hybrid_text_vector_search() returns HybridResult list with RRF scores."""
     label = f"FtsHybridTest_{uid()}"
     tag = uid()
+    idx_name = f"idx_{label.lower()}"
     vec = [float(i) / 16 for i in range(16)]
     # Same node-as-int pattern: RETURN n → Value::Int(node_id) in CoordiNode executor.
     rows = client.cypher(
         f"CREATE (n:{label} {{tag: $tag, body: 'graph neural network embedding', embedding: $vec}}) RETURN n AS node_id",
         params={"tag": tag, "vec": vec},
     )
     seed_id = rows[0]["node_id"]
+    client.create_text_index(idx_name, label, "body")
     try:
         results = client.hybrid_text_vector_search(
             label,
@@ -698,7 +705,7 @@ def test_hybrid_text_vector_search_returns_results(client):
         )
         assert isinstance(results, list)
         if not results:
-            pytest.xfail("hybrid_text_vector_search returned no results — FTS index not available on this server")
+            pytest.xfail("hybrid_text_vector_search returned no results — vector index not available on this server")
         assert any(r.node_id == seed_id for r in results), (
             f"seeded node {seed_id} not found in hybrid_text_vector_search results: {results}"
         )
@@ -708,4 +715,5 @@ def test_hybrid_text_vector_search_returns_results(client):
         assert isinstance(r.score, float)
         assert r.score > 0
     finally:
+        client.drop_text_index(idx_name)
         client.cypher(f"MATCH (n:{label} {{tag: $tag}}) DETACH DELETE n", params={"tag": tag})