pam-python 0.2.13__tar.gz → 0.2.14__tar.gz

{pam_python-0.2.13/pam_python.egg-info → pam_python-0.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.13
+Version: 0.2.14
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -134,8 +134,9 @@ See [Data Plugin Input V2](docs/data-plugin-input-v2.md).
 
 New Pandas and Polars service projects are generated on the V2 lane by default;
 legacy source can continue using V1 unchanged. For materialized Pandas frames,
-use `data.read_population_pandas()` and
-`data.dataset_at(position).read_pandas()`.
+use `data.read_population_pandas()` and either
+`data.dataset_at(position).read_pandas()` or
+`data.dataset_named(name).read_pandas()`.
 
 When your service is done:
 

{pam_python-0.2.13 → pam_python-0.2.14}/README.md

@@ -114,8 +114,9 @@ See [Data Plugin Input V2](docs/data-plugin-input-v2.md).
 
 New Pandas and Polars service projects are generated on the V2 lane by default;
 legacy source can continue using V1 unchanged. For materialized Pandas frames,
-use `data.read_population_pandas()` and
-`data.dataset_at(position).read_pandas()`.
+use `data.read_population_pandas()` and either
+`data.dataset_at(position).read_pandas()` or
+`data.dataset_named(name).read_pandas()`.
 
 When your service is done:
 

{pam_python-0.2.13 → pam_python-0.2.14}/pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.13"
+__version__ = "0.2.14"

{pam_python-0.2.13 → pam_python-0.2.14}/pam/models/data_input_v2.py

@@ -142,6 +142,15 @@ class DataInputV2:
             raise IndexError(f"V2 dataset position is out of range: {position}")
         return self.datasets[position]
 
+    def dataset_named(self, name: str) -> DataInputV2Dataset:
+        """Bind one configured dataset by an unambiguous manifest name."""
+        matches = [dataset for dataset in self.datasets if dataset.name == name]
+        if not matches:
+            raise KeyError(f"V2 dataset name is unknown: {name}")
+        if len(matches) > 1:
+            raise ValueError(f"V2 dataset name is ambiguous: {name}")
+        return matches[0]
+
 
 def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
     files_by_name = _validate_flat_input_files(input_files)
@@ -202,6 +211,7 @@ def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
         if position in positions:
             raise ValueError("V2 dataset position is duplicated")
         positions.add(position)
+        dataset_name = _required_string(raw_dataset, "name")
         dataset_format = _required_format(raw_dataset, "format")
         raw_parts = raw_dataset.get("parts")
         if not isinstance(raw_parts, list):
@@ -226,7 +236,7 @@ def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
         datasets.append(
             DataInputV2Dataset(
                 position=position,
-                name=_required_string(raw_dataset, "name"),
+                name=dataset_name,
                 type=_required_string(raw_dataset, "type"),
                 format=dataset_format,
                 row_count=row_count,

{pam_python-0.2.13 → pam_python-0.2.14}/pam/templates/init/AGENT.md

@@ -215,15 +215,16 @@ V2 is a separate, explicit lane. Call `_request_data_v2(...)` with CSV or
 Parquet when the PAM adapter is configured for V2. The requested format applies
 to that page and may change on a later request. In `on_data_input`, require
 `req.data_input_v2`, validate the expected dataset count, and bind each dataset
-by its configured position:
+by an unambiguous manifest name (or by its configured position when names are
+not unique or the contract requires positional binding):
 
 ```python
 data = req.data_input_v2
 if data is None or len(data.datasets) != 2:
     raise ValueError("Expected V2 profile and purchase datasets")
 
-profile = data.dataset_at(0)
-purchase = data.dataset_at(1)
+profile = data.dataset_named("profile")
+purchase = data.dataset_named("purchase")
 
 population = data.scan_population_polars()
 profile_frame = profile.scan_polars()

{pam_python-0.2.13 → pam_python-0.2.14/pam_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.13
+Version: 0.2.14
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -134,8 +134,9 @@ See [Data Plugin Input V2](docs/data-plugin-input-v2.md).
 
 New Pandas and Polars service projects are generated on the V2 lane by default;
 legacy source can continue using V1 unchanged. For materialized Pandas frames,
-use `data.read_population_pandas()` and
-`data.dataset_at(position).read_pandas()`.
+use `data.read_population_pandas()` and either
+`data.dataset_at(position).read_pandas()` or
+`data.dataset_named(name).read_pandas()`.
 
 When your service is done:
 

{pam_python-0.2.13 → pam_python-0.2.14}/tests/test_data_input_v2.py

@@ -215,6 +215,26 @@ class DataInputV2Test(unittest.TestCase):
         with self.assertRaisesRegex(IndexError, "out of range"):
             data_input.dataset_at(1)
 
+    def test_dataset_named_resolves_unique_manifest_name(self):
+        manifest_path = self._write_manifest(self._valid_manifest())
+        data_input = parse_data_input_v2(
+            [str(manifest_path), str(self.population_path), str(self.dataset_path)]
+        )
+
+        dataset = data_input.dataset_named("demographic")
+
+        self.assertEqual(0, dataset.position)
+        self.assertEqual("demographic", dataset.name)
+
+    def test_dataset_named_rejects_unknown_name(self):
+        manifest_path = self._write_manifest(self._valid_manifest())
+        data_input = parse_data_input_v2(
+            [str(manifest_path), str(self.population_path), str(self.dataset_path)]
+        )
+
+        with self.assertRaisesRegex(KeyError, "name is unknown: purchase"):
+            data_input.dataset_named("purchase")
+
     def test_parse_rejects_sha256_mismatch(self):
         manifest = self._valid_manifest()
         manifest["population"]["file"]["sha256"] = "0" * 64
@@ -249,6 +269,38 @@ class DataInputV2Test(unittest.TestCase):
                 [str(manifest_path), str(self.population_path), str(self.dataset_path)]
             )
 
+    def test_dataset_named_rejects_ambiguous_name_without_breaking_positions(self):
+        second_dataset_path = self._write_file(
+            "dataset_002_event_part_0001.csv",
+            b"id,event\ncontact-1,purchase\n",
+        )
+        manifest = self._valid_manifest()
+        manifest["datasets"].append(
+            {
+                "position": 1,
+                "name": "demographic",
+                "type": "demographic",
+                "format": "csv",
+                "row_count": 1,
+                "complete": True,
+                "parts": [self._metadata(second_dataset_path, 1)],
+            }
+        )
+        manifest_path = self._write_manifest(manifest)
+
+        data_input = parse_data_input_v2(
+            [
+                str(manifest_path),
+                str(self.population_path),
+                str(self.dataset_path),
+                str(second_dataset_path),
+            ]
+        )
+
+        self.assertEqual("demographic", data_input.dataset_at(1).name)
+        with self.assertRaisesRegex(ValueError, "name is ambiguous: demographic"):
+            data_input.dataset_named("demographic")
+
     def test_parse_exposes_event_population_and_half_open_time_window(self):
         manifest = self._valid_manifest()
         manifest["population"]["mode"] = "event_all"