feat: add Opaque type and allow planner disengagement

src/graphty/__init__.py

@@ -8,3 +8,4 @@
 from graphty.utils.exceptions import MissingGroupByError as MissingGroupByError
 from graphty.utils.types import Agg as Agg
 from graphty.utils.types import ConfigDict as ConfigDict
+from graphty.utils.types import Opaque as Opaque

src/graphty/planner.py

@@ -28,7 +28,7 @@
     is_pydantic_model_static_type,
     is_pydantic_model_union_static_type,
 )
-from graphty.utils.types import Agg
+from graphty.utils.types import Agg, Opaque
 
 
 class ModelUnionDispatch:
@@ -199,10 +199,7 @@ def run(self) -> pl.LazyFrame:
         model_projection: set[str] = model_info.model_projection
 
         if group_by is None:
-            if self.model.model_fields:
-                # TODO: when Opacity/planner disengagement is implemented, fields marked
-                # as Opaque should not count as "model fields" for this check — a model
-                # with only Opaque fields should also return the raw frame.
+            if self._has_actionable_fields:
                 return self.lazy_frame.with_columns(
                     *self._generate_expressions(model=self.model)
                 ).drop(self._base_cols.difference(model_projection))
@@ -217,10 +214,21 @@ def run(self) -> pl.LazyFrame:
     def _base_cols(self) -> set[str]:
         return set(self.lazy_frame.collect_schema().names())
 
+    @property
+    def _has_actionable_fields(self) -> bool:
+        return any(
+            get_metadata(field_info=field_info, cls=Opaque) is None
+            for _, field_info in self.model.model_fields.items()
+        )
+
     def _generate_expressions(
         self, model: type[BaseModel], group_context: bool = False
     ) -> Iterator[pl.Expr]:
         for field_name, field_info in model.model_fields.items():
+            if get_metadata(field_info=field_info, cls=Opaque) is not None:
+                yield pl.struct(self._base_cols).alias(field_name)
+                continue
+
             annotation = cast(TypeForm, field_info.annotation)
 
             if is_pydantic_model_static_type(annotation):

src/graphty/utils/model_info.py

@@ -3,7 +3,8 @@
 
 from graphty.utils.alias_map import AliasMap
 from graphty.utils.exceptions import InvalidGroupByError
-from graphty.utils.type_utils import is_structured_field_static_type
+from graphty.utils.type_utils import get_metadata, is_structured_field_static_type
+from graphty.utils.types import Opaque
 from pydantic import BaseModel
 
 
@@ -22,6 +23,7 @@ def model_projection(self) -> set[str]:
             self.alias_map[field_name]
             for field_name, field_info in self.model.model_fields.items()
             if not is_structured_field_static_type(field_info.annotation)
+            and not get_metadata(field_info=field_info, cls=Opaque)
         }
 
     @cached_property

src/graphty/utils/types.py

@@ -34,3 +34,15 @@ def __iter__(self) -> Iterator[Callable[[pl.Expr], pl.Expr]]:
 
     def apply_to(self, expr: pl.Expr) -> pl.Expr:
         return reduce(lambda x, y: y(x), self, expr)
+
+
+class Opaque:
+    """Type for marking a field as opaque for the planner.
+
+    For Pydantic fields typed with `Annotated[<type>, Opaque()]`
+    the GraphTy planner will forward the entire projection as a pl.Struct
+    and otherwise ignore that field.
+
+    Disengaging the planner for a field with `Opaque`
+    allows a before-validator to act on the raw bindings on the Python level.
+    """