pam-python 0.2.16__tar.gz → 0.2.17__tar.gz

{pam_python-0.2.16/pam_python.egg-info → pam_python-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.16
+Version: 0.2.17
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python

{pam_python-0.2.16 → pam_python-0.2.17}/pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.16"
+__version__ = "0.2.17"

{pam_python-0.2.16 → pam_python-0.2.17}/pam/models/data_input_v2.py

@@ -71,21 +71,34 @@ class DataInputV2Dataset:
         for part in self.parts:
             yield from part.iter_csv_rows()
 
-    def scan_polars(self) -> Any:
-        """Return one lazy frame across all ordered CSV or Parquet parts."""
+    def scan_polars(self, empty_schema: dict[str, Any] | None = None) -> Any:
+        """Return one lazy frame across all ordered CSV or Parquet parts.
+
+        PAM represents a valid dataset with no rows as ``row_count=0`` and no
+        physical parts. In that case the plugin may provide its domain schema
+        so downstream computation can handle the empty input normally.
+        """
         pl = _import_polars()
         if not self.parts:
-            return pl.LazyFrame(schema={"id": pl.String})
+            schema = {"id": pl.String} if empty_schema is None else empty_schema
+            return pl.LazyFrame(schema=schema)
         scans = [part.scan_polars() for part in self.parts]
         if len(scans) == 1:
             return scans[0]
         return pl.concat(scans, how="diagonal_relaxed")
 
-    def read_pandas(self) -> Any:
-        """Materialize and concatenate all verified parts using their metadata."""
+    def read_pandas(self, empty_dtypes: dict[str, Any] | None = None) -> Any:
+        """Materialize and concatenate all verified parts using their metadata.
+
+        ``empty_dtypes`` is used only for a declared empty dataset, allowing
+        the plugin to retain its domain columns without fabricating data rows.
+        """
         pd = _import_pandas()
         if not self.parts:
-            return pd.DataFrame({"id": pd.Series(dtype="string")})
+            dtypes = {"id": "string"} if empty_dtypes is None else empty_dtypes
+            return pd.DataFrame(
+                {name: pd.Series(dtype=dtype) for name, dtype in dtypes.items()}
+            )
         frames = [part.read_pandas() for part in self.parts]
         if len(frames) == 1:
             return frames[0]

{pam_python-0.2.16 → pam_python-0.2.17}/pam/templates/init/AGENT.md

@@ -234,6 +234,11 @@ result = calculate(population, profile_frame, purchase_frame).collect()
 
 `scan_polars()` returns one lazy frame across ordered CSV or Parquet parts and
 uses verified manifest format metadata. CSV-only code may use `iter_rows()`.
+`row_count=0` with `parts=[]` is a valid empty dataset. The plugin decides the
+business result for the page population; it must not treat the absence of event
+rows as a transport error. If computation requires domain columns on an empty
+frame, call `scan_polars(empty_schema=...)` or
+`read_pandas(empty_dtypes=...)` with the plugin-owned schema.
 The external customer key is `id`. The population file is authoritative: in
 `contacts` mode, contacts with no event rows remain visible there. Use the
 opaque `data.next` cursor for the next `_request_data_v2(...)` call and stop when

{pam_python-0.2.16 → pam_python-0.2.17/pam_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.16
+Version: 0.2.17
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python

{pam_python-0.2.16 → pam_python-0.2.17}/tests/test_data_input_v2.py

@@ -78,6 +78,30 @@ class DataInputV2Test(unittest.TestCase):
         self.assertEqual(0, data_input.datasets[0].row_count)
         self.assertEqual((), data_input.datasets[0].parts)
 
+    def test_empty_dataset_readers_use_plugin_owned_schema(self):
+        import polars as pl
+
+        manifest = self._valid_manifest()
+        manifest["datasets"][0]["row_count"] = 0
+        manifest["datasets"][0]["parts"] = []
+        self.dataset_path.unlink()
+        manifest_path = self._write_manifest(manifest)
+        dataset = parse_data_input_v2(
+            [str(manifest_path), str(self.population_path)]
+        ).datasets[0]
+
+        polars_frame = dataset.scan_polars(
+            empty_schema={"id": pl.String, "netamount": pl.Float64}
+        ).collect()
+        self.assertEqual(0, polars_frame.height)
+        self.assertEqual(["id", "netamount"], polars_frame.columns)
+
+        pandas_frame = dataset.read_pandas(
+            empty_dtypes={"id": "string", "netamount": "float64"}
+        )
+        self.assertTrue(pandas_frame.empty)
+        self.assertEqual(["id", "netamount"], pandas_frame.columns.tolist())
+
     def test_streams_population_and_ordered_dataset_parts(self):
         second_part_path = self._write_file(
             "dataset_001_demographic_part_0002.csv",