fix(client,demo): align type annotations and query_facts param guard

- create_label (async + sync): widen properties annotation to
  list[dict] | tuple[dict, ...] | None (matches _build_property_definitions)
- HybridResult: add doc comment explaining why .node is absent —
  proto HybridResult carries only node_id + score by design
- query_facts (notebook): reject queries with parameters other than
  $sess to prevent unbound-parameter runtime errors

Author: polaz

coordinode/coordinode/client.py

@@ -120,6 +120,10 @@ def __init__(self, proto_result: Any) -> None:
         self.node_id: int = proto_result.node_id
         # Combined RRF score: text_weight/(60+rank_text) + vector_weight/(60+rank_vec).
         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.
 
     def __repr__(self) -> str:
         return f"HybridResult(node_id={self.node_id}, score={self.score:.6f})"
@@ -527,7 +531,7 @@ def _normalize_schema_mode(schema_mode: str | int, mode_map: dict[str, int]) ->
     async def create_label(
         self,
         name: str,
-        properties: list[dict[str, Any]] | None = None,
+        properties: list[dict[str, Any]] | tuple[dict[str, Any], ...] | None = None,
         *,
         schema_mode: str | int = "strict",
     ) -> LabelInfo:
@@ -953,7 +957,7 @@ def get_edge_types(self) -> list[EdgeTypeInfo]:
     def create_label(
         self,
         name: str,
-        properties: list[dict[str, Any]] | None = None,
+        properties: list[dict[str, Any]] | tuple[dict[str, Any], ...] | None = None,
         *,
         schema_mode: str | int = "strict",
     ) -> LabelInfo:

demo/notebooks/03_langgraph_agent.ipynb

@@ -260,11 +260,17 @@
     "    _LIMIT_AT_END_RE = re.compile(r\"\\bLIMIT\\s+(\\d+)\\s*;?\\s*$\", re.IGNORECASE | re.DOTALL)\n",
     "    def _cap_limit(m):\n",
     "        return f\"LIMIT {min(int(m.group(1)), 20)}\"\n",
+    "    # Reject queries with parameters other than $sess — only {\"sess\": SESSION} is passed.\n",
+    "    extra_params = sorted(\n",
+    "        {m.group(1) for m in re.finditer(r\"\\$([A-Za-z_][A-Za-z0-9_]*)\", q)} - {\"sess\"}\n",
+    "    )\n",
+    "    if extra_params:\n",
+    "        return f\"Only $sess is supported in query_facts; found additional parameters: {', '.join(extra_params)}\"\n",
     "    if _LIMIT_AT_END_RE.search(q):\n",
     "        q = _LIMIT_AT_END_RE.sub(_cap_limit, q)\n",
     "    elif re.search(r\"\\bLIMIT\\b\", q, re.IGNORECASE):\n",
-    "        # Respect caller-provided non-terminal / parameterized LIMIT clauses\n",
-    "        # (e.g. LIMIT $n); appending a second LIMIT would produce invalid Cypher.\n",
+    "        # Respect caller-provided non-terminal LIMIT clauses;\n",
+    "        # appending a second LIMIT would produce invalid Cypher.\n",
     "        pass\n",
     "    else:\n",
     "        q = q.rstrip().rstrip(\";\") + \" LIMIT 20\"\n",