pam-python 0.2.2__tar.gz → 0.2.3__tar.gz

{pam_python-0.2.2/pam_python.egg-info → pam_python-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.2
+Version: 0.2.3
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -122,7 +122,7 @@ The runtime calls your service in two main phases.
 2. `on_data_input`
 
 - Called when CDP sends input files
-- `req.input_files` contains ordered Parquet files
+- `req.input_files` is the ordered positional data-source contract configured in PAM
 - `req.file_format` is the typed format sent by PAM
 - Should also return quickly (use a thread if needed)
 

{pam_python-0.2.2 → pam_python-0.2.3}/README.md

@@ -102,7 +102,7 @@ The runtime calls your service in two main phases.
 2. `on_data_input`
 
 - Called when CDP sends input files
-- `req.input_files` contains ordered Parquet files
+- `req.input_files` is the ordered positional data-source contract configured in PAM
 - `req.file_format` is the typed format sent by PAM
 - Should also return quickly (use a thread if needed)
 

{pam_python-0.2.2 → pam_python-0.2.3}/pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

{pam_python-0.2.2 → pam_python-0.2.3}/pam/templates/init/AGENT.md

@@ -117,15 +117,17 @@ input data. CDP returns up to 5 Parquet files (each file is a separate event).
 
 - File order is guaranteed per agreement, so you can index by position.
 - Column names and record counts are defined by CDP configuration.
+- `input_files` is not a list of interchangeable files. Each position represents
+  a different configured data source and must be bound to a meaningful domain name.
+- Never process `input_files` with `for file_path in req.input_files`.
 
 Example file order usage:
 
 ```python
-input_files = req.input_files
-# Index 0: purchase events
-# Index 1: use points events
-purchase_path = input_files[0]
-use_points_path = input_files[1]
+if len(req.input_files) != 2:
+    raise ValueError("Expected purchase_event and point_received_event inputs")
+
+purchase_event_file, point_received_event_file = req.input_files
 ```
 
 Column meaning
@@ -163,20 +165,30 @@ def __run_process_data_in_thread(self, req: RequestCommand):
     if req.file_format is not RequestFileFormat.PARQUET:
         raise ValueError(f"Expected parquet, received {req.file_format.value}")
 
-    result = transform(pl.scan_parquet(req.input_files[0]))
+    if len(req.input_files) != 2:
+        raise ValueError("Expected purchase_event and point_received_event inputs")
+
+    purchase_event_file, point_received_event_file = req.input_files
+    result = transform(
+        pl.scan_parquet(purchase_event_file),
+        pl.scan_parquet(point_received_event_file),
+    )
     self._upload_result(result)
 
     if not req.is_end:
-        self._request_data(req.next, file_format=RequestFileFormat.PARQUET)
+        self._request_data(
+            page=req.next,
+            file_format=RequestFileFormat.PARQUET,
+        )
     else:
         self._exit()
 ```
 
 Why a thread: to end the HTTP request quickly and avoid timeouts.
 
-`req.input_files` is the ordered list of Parquet paths. `req.file_format` is the
-typed metadata sent by PAM and is the source of truth; validate file extensions as
-an additional consistency check.
+`req.input_files` is the ordered positional contract of Parquet paths.
+`req.file_format` is the typed metadata sent by PAM and is the source of truth;
+validate file extensions as an additional consistency check.
 
 ---
 
@@ -258,21 +270,32 @@ CDP paging is **customer-based**, not row-based.
 
 When requesting data page by page:
 
-- CDP collects customers in batches of approximately **10,000 customers per page**.
-- All events belonging to those customers are merged into **a single Parquet file**.
-- The number of rows is **unknown** and depends on how many events each customer has.
+- PAM first selects a cohort of approximately **10,000 unique customers per page**.
+- PAM then queries **every configured dataset** with that same customer-ID cohort.
+- Dataset 1 through dataset N in one callback therefore belong to the same group
+  of customers, while retaining their configured positional meanings.
+- Each dataset has its own Parquet file and may have a different row count because
+  event density differs and some customers may have no rows in a dataset.
+- A customer's relevant data is kept within one logical page instead of being
+  split across customer pages.
+- `req.next` advances the customer-cohort cursor, not an event-row offset.
 
 This means:
 
 - Each page represents a logical customer group, not a fixed number of records.
 - A page may contain a small or very large number of rows depending on behavior density.
+- Files at different input positions must be joined or compared by the agreed
+  customer key; row positions across files do not correspond.
 
 ### Execution Implications
 
 Because paging is based on customers:
 
 - In many cases, a service can process **one page (≈10,000 customers)** independently.
-- If the logic allows, you may process and upload results immediately because the dataset is self-contained.
+- If the logic allows, you may process and upload results immediately because all
+  configured datasets for that customer cohort arrive together.
+- Do not create row-offset pagination or carry partial state because one dataset
+  happens to have more event rows than another.
 
 However, upload behavior must balance two constraints:
 

{pam_python-0.2.2 → pam_python-0.2.3}/pam/templates/service/pandas/service_class.tmpl

@@ -13,6 +13,7 @@ from #MODULE_NAME#.functions import load_input_file, transform
 
 class #CLASS_NAME#(Service):
     INPUT_FILE_FORMAT = RequestFileFormat.PARQUET
+    EXPECTED_DATASET_COUNT = 1
 
     def __init__(self, task_manager, req):
         super().__init__(task_manager, req)
@@ -40,11 +41,22 @@ class #CLASS_NAME#(Service):
                 f"received {req.file_format.value}"
             )
 
-        for file_path in req.input_files:
-            if not file_path.lower().endswith(".parquet"):
-                raise ValueError(f"Expected a .parquet input file: {file_path}")
-            result = transform(load_input_file(file_path))
-            self.batch_uploader.upload(result, name="main")
+        if len(req.input_files) != self.EXPECTED_DATASET_COUNT:
+            raise ValueError(
+                f"Expected {self.EXPECTED_DATASET_COUNT} configured dataset, "
+                f"received {len(req.input_files)}"
+            )
+
+        # Bind every position to the data source name configured in PAM.
+        # Add more named positions here when the service contract has more datasets.
+        (input_dataset_file,) = req.input_files
+        if not input_dataset_file.lower().endswith(".parquet"):
+            raise ValueError(
+                f"Expected a .parquet input file: {input_dataset_file}"
+            )
+
+        result = transform(load_input_file(input_dataset_file))
+        self.batch_uploader.upload(result, name="main")
 
         if not req.is_end:
             self._request_data(

{pam_python-0.2.2 → pam_python-0.2.3}/pam/templates/service/polars/service_class.tmpl

@@ -12,6 +12,7 @@ from #MODULE_NAME#.functions import load_input_file, transform
 
 class #CLASS_NAME#(Service):
     INPUT_FILE_FORMAT = RequestFileFormat.PARQUET
+    EXPECTED_DATASET_COUNT = 1
 
     def on_start(self):
         log("on_start")
@@ -35,11 +36,22 @@ class #CLASS_NAME#(Service):
                 f"received {req.file_format.value}"
             )
 
-        for file_path in req.input_files:
-            if not file_path.lower().endswith(".parquet"):
-                raise ValueError(f"Expected a .parquet input file: {file_path}")
-            result = transform(load_input_file(file_path))
-            self._upload_result(result)
+        if len(req.input_files) != self.EXPECTED_DATASET_COUNT:
+            raise ValueError(
+                f"Expected {self.EXPECTED_DATASET_COUNT} configured dataset, "
+                f"received {len(req.input_files)}"
+            )
+
+        # Bind every position to the data source name configured in PAM.
+        # Add more named positions here when the service contract has more datasets.
+        (input_dataset_file,) = req.input_files
+        if not input_dataset_file.lower().endswith(".parquet"):
+            raise ValueError(
+                f"Expected a .parquet input file: {input_dataset_file}"
+            )
+
+        result = transform(load_input_file(input_dataset_file))
+        self._upload_result(result)
 
         if not req.is_end:
             self._request_data(

{pam_python-0.2.2 → pam_python-0.2.3/pam_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.2
+Version: 0.2.3
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -122,7 +122,7 @@ The runtime calls your service in two main phases.
 2. `on_data_input`
 
 - Called when CDP sends input files
-- `req.input_files` contains ordered Parquet files
+- `req.input_files` is the ordered positional data-source contract configured in PAM
 - `req.file_format` is the typed format sent by PAM
 - Should also return quickly (use a thread if needed)
 

{pam_python-0.2.2 → pam_python-0.2.3}/tests/test_cli_templates.py

@@ -43,6 +43,10 @@ class CLITemplateTest(unittest.TestCase):
             self.assertIn("pyarrow>=19.0.1", (root / "requirements.txt").read_text())
             self.assertFalse((root / "pyproject.toml").exists())
             self.assertTrue((root / "REPORTS.md").is_file())
+            agent_guide = (root / "AGENT.md").read_text()
+            self.assertIn("Customer-based Pagination Contract", agent_guide)
+            self.assertIn("same customer-ID cohort", agent_guide)
+            self.assertIn("customer-cohort cursor", agent_guide)
             self.assertTrue((root / "run_unit_test.sh").is_file())
             self.assertTrue(os.access(root / "run_unit_test.sh", os.X_OK))
             self.assertTrue((root / "run_unit_test.ps1").is_file())
@@ -62,6 +66,9 @@ class CLITemplateTest(unittest.TestCase):
             ):
                 service_source = service_path.read_text()
                 self.assertIn("page=req.next", service_source)
+                self.assertIn("EXPECTED_DATASET_COUNT = 1", service_source)
+                self.assertIn("(input_dataset_file,) = req.input_files", service_source)
+                self.assertNotIn("for file_path in req.input_files", service_source)
                 self.assertEqual(
                     2,
                     service_source.count("file_format=self.INPUT_FILE_FORMAT"),