Merge typing/wave0-polars-frame into perf/gfql-h3-two-hop-count-lazy (linear PR stack)

Stacked so the shared CHANGELOG stops conflicting on every landing: this branch
now sits on top of typing/wave0-polars-frame rather than beside it. Files touched by both were
3-way merged with zero conflict markers; CHANGELOG resolved structurally, with
this branch's entry re-inserted into the parent's file under the same section.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YYZRXegrALuXd3NHH5evqx

Author: lmeyerov

CHANGELOG.md

@@ -13,5 +13,5 @@
       "max_properties": 0
     }
   },
-  "lowering_py_max_lines": 9255
+  "lowering_py_max_lines": 9260
 }

bin/ci_cypher_surface_guard_baseline.json

@@ -34,6 +34,9 @@ POLARS_TEST_FILES=(
     # only ever run here (the file has no module-level importorskip, so nothing else flags it)
     graphistry/tests/compute/gfql/test_exec_context_scoping.py
     graphistry/tests/compute/gfql/test_engine_polars_cypher_conformance.py
+    # aggregate x dtype type contract: the polars params of this file are the ONLY lane where the
+    # native polars aggregate guard and the raw-polars-exception wrap are exercised
+    graphistry/tests/compute/gfql/test_aggregate_type_contract.py
     graphistry/tests/compute/gfql/test_engine_polars_conformance_matrix.py
     graphistry/tests/compute/gfql/test_polars_string_predicate_nonstring.py
     graphistry/tests/compute/gfql/cypher/test_order_by_null_placement.py

bin/test-polars.sh

@@ -437,10 +437,25 @@ analysis = g.gfql([
 | `LIMIT 10` | `limit(10)` | Row cap |
 | `WHERE <row expr>` | `where_rows(expr="...")` | Scalar expression subset |
 | `count(*)` | `group_by(keys=[...], aggregations=[("cnt", "count")])` | Grouped count |
-| `sum(n.val)` | `group_by(..., aggregations=[("total", "sum", "val")])` | Grouped sum |
+| `sum(n.val)` | `group_by(..., aggregations=[("total", "sum", "val")])` | Grouped sum; see [Aggregate input types](#aggregate-input-types) |
 | `collect(n.x)` | `group_by(..., aggregations=[("xs", "collect", "x")])` | Nulls excluded from collection |
 | Named patterns | `rows(source="alias")` | Scope row table to a named match alias |
 
+### Aggregate input types
+
+`sum` and `avg` accept `INTEGER`, `FLOAT` and `DURATION`, matching Cypher — **plus `BOOLEAN`, which
+is a deliberate GFQL extension.** Neo4j rejects it (*"expected Float, Integer or Duration but was
+Boolean"*); GFQL accepts it because summing an indicator column is idiomatic in the dataframe
+surface GFQL also serves, and every engine already agrees on the answer. `sum` over a boolean
+counts the true values; `avg` gives their fraction.
+
+Any other input type **raises**. This is stricter than earlier releases, where a string column
+returned its *concatenation* on pandas and leaked a raw polars error on polars — wrong in two
+different directions.
+
+Empty and all-null inputs follow Cypher rather than SQL: `sum` returns **0**, `avg` returns
+**null**.
+
 ## Key Differences
 
 | Feature | Python | Wire Protocol |

docs/source/gfql/spec/cypher_mapping.md

@@ -13,7 +13,14 @@
     # Frame aliases (pandas types for mypy; ``Any`` at runtime). Imported under TYPE_CHECKING
     # and referenced via string annotations below so Engine.py — imported very early — never
     # triggers ``graphistry.compute`` package init at runtime (would be circular).
-    from graphistry.compute.typing import DataFrameT, SeriesT
+    from graphistry.compute.typing import DataFrameT, PolarsFrame, PolarsSeriesT, SeriesT
+    # TypeGuard, NOT TypeIs (PEP 742). TypeIs additionally narrows the negative branch, and to
+    # do that soundly it REQUIRES the narrowed type to be consistent with the declared input
+    # type. ``is_polars_df`` is called on values declared ``DataFrameT``/``SeriesT`` (i.e.
+    # pandas), and a polars frame is not a subtype of a pandas one, so TypeIs is rejected here
+    # — it typechecks only where the declared type already contains the narrowed one (as in
+    # ``polars/dtypes.py:is_lazy``, whose input is already ``PolarsFrame``).
+    from typing_extensions import TypeGuard
 
 
 class Engine(Enum):
@@ -196,13 +203,20 @@ def _cudf_from_pandas_best_effort(df: pd.DataFrame, *, validate: Optional[Valida
         return out_gdf
 
 
-def is_polars_df(df: Any) -> bool:
+def is_polars_df(df: object) -> "TypeGuard[PolarsFrame]":
     """True if ``df`` is a polars DataFrame or LazyFrame.
 
     Import-light module-name check (polars is an optional dependency, so we avoid importing
     it just to ``isinstance``). ``type(df).__module__`` starts with ``polars.`` for both
     ``pl.DataFrame`` and ``pl.LazyFrame``. Single source of truth — the gfql engine had this
-    reimplemented in 5 places."""
+    reimplemented in 5 places.
+
+    Declared ``TypeGuard[PolarsFrame]`` rather than ``bool`` so the polars branch of an
+    engine-dispatching helper actually narrows: callers pass a value declared ``DataFrameT``
+    (pandas at checking time) and the guard is what proves the polars API is available inside
+    the branch, with no ``cast`` at the call site. ``object`` (not ``Any``) as the parameter
+    type is deliberate — it is the widest input a predicate can accept while still checking
+    its own body."""
     return df is not None and "polars" in type(df).__module__
 
 
@@ -287,7 +301,10 @@ def df_to_engine(df, engine: Engine, *, validate: Optional[ValidationParam] = No
             with target_mode(_tgt):
                 return _pl_nan_to_null(_lazy_collect(df))
         if isinstance(df, pa.Table):
-            return _pl_nan_to_null(pl.from_arrow(df))
+            # ``pl.from_arrow`` is declared ``DataFrame | Series`` because polars cannot
+            # overload it on the pyarrow input type (see polars/convert/general.py); a
+            # ``pa.Table`` in always yields a DataFrame, so the Series arm is unreachable here.
+            return _pl_nan_to_null(pl.from_arrow(df))  # type: ignore[arg-type]
         pl_validate: ValidationParam = 'strict' if validate is None else validate
         if isinstance(df, pd.DataFrame):
             return _pl_from_pandas(df, validate=pl_validate, warn=warn)
@@ -300,7 +317,8 @@ def df_to_engine(df, engine: Engine, *, validate: Optional[ValidationParam] = No
         if 'cudf' in str(type(df).__module__):
             import cudf
             if isinstance(df, cudf.DataFrame):
-                return _pl_nan_to_null(pl.from_arrow(df.to_arrow()))
+                # see the pa.Table branch above for the from_arrow union
+                return _pl_nan_to_null(pl.from_arrow(df.to_arrow()))  # type: ignore[arg-type]
         # dask/spark and anything else: route through pandas
         return _pl_from_pandas(df_to_engine(df, Engine.PANDAS), validate=pl_validate, warn=warn)
     raise ValueError(f'Only engines pandas/cudf/dask/polars supported, got: {engine}')
@@ -862,39 +880,51 @@ def safe_merge(
 # Engine-agnostic series / frame primitives (pandas / cuDF / polars dispatch).
 #
 # Pure per-row/per-column dispatch helpers with no domain knowledge — the polars
-# branches genuinely return polars objects mypy can't narrow to the pandas frame
-# aliases, so the localized ``# type: ignore`` lives here at the dispatch point and
-# callers get a clean ``SeriesT`` / ``DataFrameT`` contract with no ``cast()``.
+# branches genuinely RETURN polars objects, which cannot be the pandas frame aliases
+# the engine-agnostic signature promises, so the localized ``# type: ignore`` lives
+# here at the dispatch point and callers get a clean ``SeriesT`` / ``DataFrameT``
+# contract with no ``cast()``.
+# Since ``is_polars_df`` / ``is_polars_series`` became TypeGuards the polars branch is
+# now genuinely CHECKED against the polars API (the ignores below are scoped to the
+# return/argument mismatch alone, no longer blanket ``attr-defined``).
 # Annotations are strings so the TYPE_CHECKING-only alias import stays runtime-free.
 # ---------------------------------------------------------------------------
 
 
+def is_polars_series(s: object) -> "TypeGuard[PolarsSeriesT]":
+    """True if ``s`` is a polars Series. Same import-light module check as ``is_polars_df``
+    (``polars.series.series``), split out only so the SERIES call sites narrow to
+    ``pl.Series`` instead of to a frame -- the frame guard would wrongly promise
+    ``.height`` / ``.columns`` on a value that is a column."""
+    return s is not None and "polars" in type(s).__module__
+
+
 def is_series_like(s: object) -> bool:
     """True for a pandas/cuDF Series (``.dropna``) or a polars Series (module check).
 
     Some engine-agnostic callers accept an ``ids`` Series that is pandas under
     ``engine='pandas'`` and polars under ``engine='polars'``; both are valid."""
-    return hasattr(s, "dropna") or is_polars_df(s)
+    return hasattr(s, "dropna") or is_polars_series(s)
 
 
 def series_not_null_mask(s: "SeriesT") -> "SeriesT":
     """Non-null boolean mask, engine-aware (polars ``is_not_null`` vs pandas ``notna``)."""
-    if is_polars_df(s):
-        return s.is_not_null()  # type: ignore[attr-defined,no-any-return]
+    if is_polars_series(s):
+        return s.is_not_null()  # type: ignore[return-value]  # polars Series, not the pandas alias
     return s.notna()
 
 
 def series_filter(s: "SeriesT", mask: "SeriesT") -> "SeriesT":
     """Filter a Series by a boolean mask, engine-aware, dropping the old index (pandas)."""
-    if is_polars_df(s):
-        return s.filter(mask)  # type: ignore[attr-defined,no-any-return]
+    if is_polars_series(s):
+        return s.filter(mask)  # type: ignore[return-value]  # polars Series, not the pandas alias
     return s[mask].reset_index(drop=True)
 
 
 def frame_filter(df: "DataFrameT", mask: "SeriesT") -> "DataFrameT":
     """Filter a DataFrame's rows by a boolean mask, engine-aware, dropping the old index."""
     if is_polars_df(df):
-        return df.filter(mask)  # type: ignore[attr-defined,no-any-return]
+        return df.filter(mask)  # type: ignore[return-value]  # polars frame, not the pandas alias
     return df.loc[mask].reset_index(drop=True)
 
 
@@ -909,16 +939,18 @@ def ordered_left_join(left: "DataFrameT", right: "DataFrameT", *, on: str) -> "D
     if is_polars_df(left):
         if not is_polars_df(right):
             right = df_to_engine(right, Engine.POLARS)
-        return left.join(right, on=on, how="left", maintain_order="left")  # type: ignore[call-arg,no-any-return]
+        return left.join(right, on=on, how="left", maintain_order="left")  # type: ignore[arg-type,return-value]
     return safe_merge(left, right, on=on, how="left")
 
 
 def row_as_mapping(rows: "DataFrameT", row_index: int) -> Mapping[str, Any]:
     """One frame row as a col->scalar mapping, engine-aware (``row[col]`` works for
     both the pandas Series and the polars named-row dict)."""
     if is_polars_df(rows):
-        return rows.row(row_index, named=True)  # type: ignore[attr-defined,no-any-return]
-    return rows.iloc[row_index]
+        # ``.row()`` is eager-only; the guard cannot rule out a LazyFrame, and callers of
+        # this helper are always past collection.
+        return rows.row(row_index, named=True)  # type: ignore[union-attr]
+    return rows.iloc[row_index]  # type: ignore[return-value]  # pandas Series is a str->scalar mapping
 
 
 def assign_constant_columns(df: "DataFrameT", values: Dict[str, Any]) -> "DataFrameT":
@@ -927,14 +959,14 @@ def assign_constant_columns(df: "DataFrameT", values: Dict[str, Any]) -> "DataFr
         return df
     if is_polars_df(df):
         import polars as pl
-        return df.with_columns([pl.lit(v).alias(k) for k, v in values.items()])  # type: ignore[attr-defined,no-any-return]
+        return df.with_columns([pl.lit(v).alias(k) for k, v in values.items()])  # type: ignore[return-value]
     return df.assign(**values)
 
 
 def drop_columns(df: "DataFrameT", cols: Sequence[str]) -> "DataFrameT":
     """Drop columns by name, engine-aware (polars ``drop(list)`` vs pandas ``drop(columns=)``)."""
     if is_polars_df(df):
-        return df.drop(list(cols))  # type: ignore[no-any-return]
+        return df.drop(list(cols))  # type: ignore[return-value]
     return df.drop(columns=list(cols))