fix(client,demo): limit validation, HybridResult comment, embedded fallthrough

- text_search, hybrid_text_vector_search: validate limit is int >= 1
  (reject bool and negative/zero to avoid opaque server-side failures)
- HybridResult: fix doc comment — point callers to client.get_node()
  instead of invalid MATCH (n) WHERE id(n) = ... Cypher
- notebook 03: when auto-detected localhost port is open but not serving
  CoordiNode, close and fall through to LocalClient instead of raising;
  only raise hard error when COORDINODE_ADDR was explicitly provided

Author: polaz

coordinode/coordinode/client.py

@@ -122,8 +122,9 @@ def __init__(self, proto_result: Any) -> None:
         self.score: float = proto_result.score
         # NOTE: proto HybridResult carries only node_id + score (no embedded Node
         # message). A full node is not included by design — the server returns IDs
-        # for efficiency; callers that need properties should issue a follow-up
-        # Cypher query: MATCH (n) WHERE id(n) = <node_id> RETURN n.
+        # for efficiency. Callers that need node properties should use the client
+        # API: `client.get_node(self.node_id)`, or match on an application-level
+        # property in Cypher (e.g. WHERE n.id = <value>).
 
     def __repr__(self) -> str:
         return f"HybridResult(node_id={self.node_id}, score={self.score:.6f})"
@@ -765,6 +766,8 @@ async def text_search(
             or via :meth:`create_text_index`.  Nodes written before the index
             was created are indexed immediately at DDL execution time.
         """
+        if not isinstance(limit, int) or isinstance(limit, bool) or limit < 1:
+            raise ValueError(f"limit must be an integer >= 1, got {limit!r}.")
         from coordinode._proto.coordinode.v1.query.text_pb2 import TextSearchRequest  # type: ignore[import]
 
         req = TextSearchRequest(label=label, query=query, limit=limit, fuzzy=fuzzy, language=language)
@@ -811,6 +814,8 @@ async def hybrid_text_vector_search(
             ``CREATE TEXT INDEX`` Cypher statement.  Calling this method on a
             label without a text index returns an empty list.
         """
+        if not isinstance(limit, int) or isinstance(limit, bool) or limit < 1:
+            raise ValueError(f"limit must be an integer >= 1, got {limit!r}.")
         from coordinode._proto.coordinode.v1.query.text_pb2 import (  # type: ignore[import]
             HybridTextVectorSearchRequest,
         )

demo/notebooks/03_langgraph_agent.ipynb

@@ -142,7 +142,10 @@
     "        return False\n",
     "\n",
     "\n",
+    "_use_embedded = True\n",
+    "\n",
     "if os.environ.get(\"COORDINODE_ADDR\"):\n",
+    "    # Explicit address — fail hard if health check fails.\n",
     "    COORDINODE_ADDR = os.environ[\"COORDINODE_ADDR\"]\n",
     "    from coordinode import CoordinodeClient\n",
     "\n",
@@ -151,6 +154,7 @@
     "        client.close()\n",
     "        raise RuntimeError(f\"CoordiNode at {COORDINODE_ADDR} is not serving health checks\")\n",
     "    print(f\"Connected to {COORDINODE_ADDR}\")\n",
+    "    _use_embedded = False\n",
     "else:\n",
     "    try:\n",
     "        grpc_port = int(os.environ.get(\"COORDINODE_PORT\", \"7080\"))\n",
@@ -162,23 +166,27 @@
     "        from coordinode import CoordinodeClient\n",
     "\n",
     "        client = CoordinodeClient(COORDINODE_ADDR)\n",
-    "        if not client.health():\n",
+    "        if client.health():\n",
+    "            print(f\"Connected to {COORDINODE_ADDR}\")\n",
+    "            _use_embedded = False\n",
+    "        else:\n",
+    "            # Port is open but not a CoordiNode server — fall through to embedded.\n",
     "            client.close()\n",
-    "            raise RuntimeError(f\"CoordiNode at {COORDINODE_ADDR} is not serving health checks\")\n",
-    "        print(f\"Connected to {COORDINODE_ADDR}\")\n",
-    "    else:\n",
-    "        # No server available — use the embedded in-process engine.\n",
-    "        try:\n",
-    "            from coordinode_embedded import LocalClient\n",
-    "        except ImportError as exc:\n",
-    "            raise RuntimeError(\n",
-    "                \"coordinode-embedded is not installed. \"\n",
-    "                f\"Run: pip install {_EMBEDDED_PIP_SPEC}\"\n",
-    "                \" — or start a CoordiNode server and set COORDINODE_ADDR.\"\n",
-    "            ) from exc\n",
-    "\n",
-    "        client = LocalClient(\":memory:\")\n",
-    "        print(\"Using embedded LocalClient (in-process)\")"
+    "\n",
+    "if _use_embedded:\n",
+    "    # No server available — use the embedded in-process engine.\n",
+    "    # Works without Docker or any external service; data is in-memory.\n",
+    "    try:\n",
+    "        from coordinode_embedded import LocalClient\n",
+    "    except ImportError as exc:\n",
+    "        raise RuntimeError(\n",
+    "            \"coordinode-embedded is not installed. \"\n",
+    "            f\"Run: pip install {_EMBEDDED_PIP_SPEC}\"\n",
+    "            \" — or start a CoordiNode server and set COORDINODE_ADDR.\"\n",
+    "        ) from exc\n",
+    "\n",
+    "    client = LocalClient(\":memory:\")\n",
+    "    print(\"Using embedded LocalClient (in-process)\")\n"
    ]
   },
   {