pam-python 0.2.10__tar.gz → 0.2.11__tar.gz

{pam_python-0.2.10/pam_python.egg-info → pam_python-0.2.11}/PKG-INFO

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

{pam_python-0.2.10 → pam_python-0.2.11}/pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.10"
+__version__ = "0.2.11"

{pam_python-0.2.10 → pam_python-0.2.11}/pam/interface_task_manager.py

@@ -79,5 +79,6 @@ class ITaskManager(ABC):
         service: Service,
         report_key: str,
         pointer: dict,
+        tracker_name: str,
     ):
         pass

{pam_python-0.2.10 → pam_python-0.2.11}/pam/reports/manager.py

@@ -31,9 +31,15 @@ class ReportStoreManager:
         self._sleep = sleep_fn
         self._stores = {}
 
-    def create(self, file_name: str, shared: bool = False) -> ReportStore:
+    def create(
+        self,
+        file_name: str,
+        shared: bool = False,
+        tracker_name: str | None = None,
+    ) -> ReportStore:
         """Start a fresh local file without performing a download."""
         self._validate_file_name(file_name)
+        tracker_name = self._resolve_tracker_name(tracker_name)
         session_key = (file_name, shared)
         self._assert_not_open(session_key)
         path = self._new_local_path(file_name)
@@ -41,18 +47,29 @@ class ReportStoreManager:
             path,
             file_name,
             shared,
+            tracker_name=tracker_name,
             transport=self._transport,
             cleanup_on_close=True,
         )
         self._stores[session_key] = store
         return store
 
-    def open(self, file_name: str, shared: bool = False) -> ReportStore:
+    def open(
+        self,
+        file_name: str,
+        shared: bool = False,
+        tracker_name: str | None = None,
+    ) -> ReportStore:
         """Resume remote state, or create only after an authoritative 404."""
         self._validate_file_name(file_name)
+        tracker_name = self._resolve_tracker_name(tracker_name)
         session_key = (file_name, shared)
         existing = self._stores.get(session_key)
         if existing is not None:
+            if existing.tracker_name != tracker_name:
+                raise ReportStoreLocalIOError(
+                    "This report store is already open with a different tracker_name"
+                )
             return existing
 
         path = self._new_local_path(file_name)
@@ -64,6 +81,7 @@ class ReportStoreManager:
                     downloaded_path,
                     file_name,
                     shared,
+                    tracker_name=tracker_name,
                     transport=self._transport,
                     cleanup_on_close=True,
                 )
@@ -75,6 +93,7 @@ class ReportStoreManager:
                     path,
                     file_name,
                     shared,
+                    tracker_name=tracker_name,
                     transport=self._transport,
                     cleanup_on_close=True,
                 )
@@ -138,6 +157,15 @@ class ReportStoreManager:
                 "This report store is already open for the current service run"
             )
 
+    def _resolve_tracker_name(self, tracker_name: str | None) -> str:
+        if tracker_name is None:
+            tracker_name = self._service.request.service_name
+        if not isinstance(tracker_name, str) or not tracker_name.strip():
+            raise ReportStoreLocalIOError(
+                "tracker_name must be a non-empty string"
+            )
+        return tracker_name.strip()
+
     @staticmethod
     def _validate_file_name(file_name: str) -> None:
         if not isinstance(file_name, str) or not file_name.strip():

{pam_python-0.2.10 → pam_python-0.2.11}/pam/reports/store.py

@@ -60,12 +60,14 @@ class ReportStore:
         path: Path,
         file_name: str,
         shared: bool,
+        tracker_name: str = "",
         transport=None,
         cleanup_on_close: bool = False,
     ):
         self.path = Path(path)
         self.file_name = file_name
         self.shared = shared
+        self.tracker_name = tracker_name
         self._transport = transport
         self._cleanup_on_close = cleanup_on_close
         self._lock = threading.RLock()
@@ -87,6 +89,7 @@ class ReportStore:
         path: Path,
         file_name: str,
         shared: bool,
+        tracker_name: str = "",
         transport=None,
         cleanup_on_close: bool = False,
     ):
@@ -97,7 +100,14 @@ class ReportStore:
         except OSError as exc:
             raise ReportStoreLocalIOError(str(exc)) from exc
 
-        store = cls(path, file_name, shared, transport, cleanup_on_close)
+        store = cls(
+            path,
+            file_name,
+            shared,
+            tracker_name=tracker_name,
+            transport=transport,
+            cleanup_on_close=cleanup_on_close,
+        )
         try:
             with store._connection:
                 store._connection.executescript(CREATE_SCHEMA_SQL)
@@ -116,10 +126,18 @@ class ReportStore:
         path: Path,
         file_name: str,
         shared: bool,
+        tracker_name: str = "",
         transport=None,
         cleanup_on_close: bool = False,
     ):
-        store = cls(path, file_name, shared, transport, cleanup_on_close)
+        store = cls(
+            path,
+            file_name,
+            shared,
+            tracker_name=tracker_name,
+            transport=transport,
+            cleanup_on_close=cleanup_on_close,
+        )
         try:
             store._migrate_compatible_schema()
             store.validate()

{pam_python-0.2.10 → pam_python-0.2.11}/pam/reports/transport.py

@@ -51,6 +51,7 @@ class ReportStoreTransport:
                 self._service,
                 report_key,
                 pointer,
+                tracker_name=store.tracker_name,
             ):
                 raise ReportStoreUploadError(
                     f"Failed to publish pointer for report '{report_key}'"

{pam_python-0.2.10 → pam_python-0.2.11}/pam/task_manager.py

@@ -476,6 +476,7 @@ class TaskManager(ITaskManager):
         service: Service,
         report_key: str,
         pointer: dict,
+        tracker_name: str,
     ) -> bool:
         """Synchronously publish one V2 pointer through the existing response API."""
         adapter_id = service.get_adapter_id()
@@ -496,7 +497,7 @@ class TaskManager(ITaskManager):
                 writer.writeheader()
                 writer.writerow({
                     "customer": adapter_id,
-                    "_tracker_name": "",
+                    "_tracker_name": tracker_name,
                     column_name: json.dumps(pointer, ensure_ascii=False, sort_keys=True),
                 })
 

{pam_python-0.2.10 → pam_python-0.2.11}/pam/templates/init/AGENT.md

@@ -112,7 +112,10 @@ Notes
 
 - All values are strings. Cast with defaults to avoid errors.
 - `dry_run` is the only built-in parameter. If missing, it runs for real. If `dry_run="true"`, the service runs fully but does not upload results to CDP.
-- You do not need to check `dry_run` manually. Always call `_upload_result`; the system handles it.
+- You do not need to check `dry_run` manually. Submit tabular results through
+  `ResultBatchUploader` and managed reports through `ReportStore.publish()`; the
+  framework suppresses their remote transport during a dry run. Never call the
+  private `_upload_result` path directly from plugin code.
 
 **Important:** `on_start` must return quickly because CDP calls via HTTP. If it hangs, the client may time out and the job will be terminated. If work is long-running, move it to a thread and return from `on_start` first. This applies to all lifecycle functions.
 
@@ -146,8 +149,9 @@ Column meaning
 
 Date format is always:
 `"2025-09-11 13:07:38"`
-Timezone may vary by customer data (usually Bangkok time).
-You may sometimes be asked for the exact time zone if it is logically important for the program.
+The timezone of customer-owned source fields is an external data contract and may
+vary by customer. Confirm it when business logic depends on calendar boundaries,
+then convert explicitly. This does not change PAM's internal UTC+0 contract above.
 
 ---
 
@@ -238,6 +242,20 @@ the optional half-open `data.time_window` expose the captured run semantics.
 The framework rejects callback-token/run-ID mismatches and contradictory event
 population or time-window metadata before plugin code runs.
 
+Data Input V2 and Report Store V2 are independent contracts. A service may use
+Data Input V2 without producing managed reports, and report calculations are not
+required to use Data Input V2.
+
+For Data Input V2 pagination:
+
+- Use `data.run_complete`, not legacy `req.is_end`, as the completion signal.
+- Use only the opaque `data.next` cursor when requesting the next page.
+- Materialize every lazy computation that still reads the page before calling
+  `data.cleanup()`.
+- Treat a failed cleanup as an error before requesting the next page.
+- If the service produces managed reports, do not publish a partially calculated
+  store on an intermediate page. Publish after all intended pages and writes finish.
+
 ---
 
 ## Upload Results to CDP
@@ -400,7 +418,7 @@ Use it for cleanup.
 
 ---
 
-# 4. Persist State Between Runs (sqlite/duckdb)
+# 5. Persist State Between Runs (sqlite/duckdb)
 
 Services can be killed and restarted at any time. If you need state across runs, use sqlite or duckdb via the provided API.
 
@@ -434,17 +452,97 @@ Notes
 
 Note: `file_name` acts like a server key, while `sqlite_file` is the local file path.
 
-## Managed reports are a separate contract
+# 6. Managed Report Store V2 Agent Contract
 
 The low-level SQLite API above is for custom plugin state. Do not use it to invent
 SQLite tables or JSON payloads for reports rendered by PAM CMS.
 
-For managed reports, read `REPORTS.md` and use only one of its typed report builders.
-Report types outside that closed contract require a newer framework and CMS release.
+Before implementing a managed report, read `REPORTS.md` completely and use only its
+public typed report builders. Report types outside that closed contract require a
+newer framework and CMS release. Do not use `_request_sqlite`, `_upload_sqlite`,
+`_upload_report`, private declaration methods, raw SQLite schema changes, handwritten
+renderer/schema identifiers, or handcrafted report-pointer CSV files for Report
+Store V2.
+
+## Store, tracker group, and report identity
+
+These identifiers have different responsibilities:
+
+- `file_name` identifies one managed SQLite store. One store may contain many report
+  definitions and their records.
+- `tracker_name` is the stable, user-facing Analytics Tracker group shown in PAM CMS.
+  Related reports in the same store should normally use one shared tracker name.
+- `report key` uniquely identifies one report inside the store and must remain stable.
+  Every changed report key is published as its own Analytics Tracker attribute, so
+  PAM CMS can list every report separately even though they share one tracker group
+  and one SQLite file.
+
+Always pass a non-empty, customer-facing `tracker_name` to both `self.reports.open`
+and `self.reports.create` when the service owns managed reports:
+
+```python
+REPORT_FILE = "reports.sqlite"
+REPORT_TRACKER_NAME = "Customer Overall Reports"
+
+fresh = self.request.get_runtime_bool("fresh", default=False)
+if fresh:
+    self.report_store = self.reports.create(
+        REPORT_FILE,
+        tracker_name=REPORT_TRACKER_NAME,
+    )
+else:
+    self.report_store = self.reports.open(
+        REPORT_FILE,
+        tracker_name=REPORT_TRACKER_NAME,
+    )
+```
+
+If `tracker_name` is omitted, the framework falls back to `request.service_name`,
+but an explicit label is preferred for customer projects. Never generate one tracker
+name per report merely to separate reports. Never write `_tracker_name` yourself;
+the framework propagates the store's tracker name to every V2 pointer. Reopening the
+same file in one service run with a different tracker name is an error.
+
+The framework also publishes the service adapter ID as the Analytics Tracker owner.
+PAM and PAM CMS use that metadata for Hard Refresh routing. Plugin code must not ask
+a user to select an owner, encode the owner in `tracker_name` or `report key`, or add
+an ad-hoc owner field to the pointer.
+
+## Required lifecycle
+
+1. Open the store once during service initialization. Use `create` only for an
+   explicit human-requested fresh reset. Normal first use calls `open`; the framework
+   creates a store only after an authoritative not-found response.
+2. Do not catch authorization, transient download, or unknown remote-state errors and
+   replace the store. Let the framework retry or raise the typed error.
+3. Declare every report once after opening the store. Multiple reports should share
+   the same `ReportStore` when they belong to the same customer report group.
+4. Bind input datasets by their configured positions and complete all required page
+   calculations before publishing. Report calculations may accumulate in memory or
+   write incrementally to the local store, depending on the domain requirement.
+5. For refreshed `DAY` or `MONTH` facts, delete the source-derived partition before
+   writing its complete replacement. Never derive a business partition from plugin
+   run time unless that is explicitly the source contract.
+6. Call `self.report_store.publish()` once after the complete calculation succeeds,
+   then call `_exit()`. Do not publish after a calculation, validation, or cleanup
+   failure, and normally do not publish once per input page.
+
+One successful `publish()` uploads the SQLite file once, then publishes one pointer
+for every report key changed during the run. All of those pointers carry the same
+stable tracker name. The framework handles `dry_run` and local-file cleanup; plugin
+code must not reproduce the transport lifecycle.
+
+An existing report key cannot silently change renderer, schema, field declaration,
+granularity, or presentation contract. Use a deliberate new key or an explicitly
+approved fresh reset when the compatibility contract changes.
+
+Before using a report API, verify that the project's pinned `pam-python` release
+contains it. Customer plugins consume the framework package from their dependency
+manager; do not copy framework internals into the plugin as a workaround.
 
 ---
 
-# 5. Batch upload policy (DataFrame batching)
+# 7. Batch upload policy (DataFrame batching)
 
 ## Goal
 
@@ -518,7 +616,7 @@ After retries are exhausted, the uploader logs the failed batch, records
 
 ---
 
-# 6. Memory / RAM safety policy (Data Plugin)
+# 8. Memory / RAM safety policy (Data Plugin)
 
 ## Goal
 

{pam_python-0.2.10 → pam_python-0.2.11}/pam/templates/init/REPORTS.md

@@ -127,17 +127,29 @@ store; an authoritative not-found response creates the first store automatically
 fresh = self.request.get_runtime_bool("fresh", default=False)
 
 if fresh:
-    store = self.reports.create("reports.sqlite")
+    store = self.reports.create(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
 else:
-    store = self.reports.open("reports.sqlite")
+    store = self.reports.open(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
 ```
 
+`tracker_name` is the Analytics Tracker group label shown in PAM CMS. Keep it stable
+for all reports in the store. If omitted, the framework uses the service name.
+
 Declare reports once after opening the store. Append data across as many input
 pages as required, then publish once after all intended work is complete.
 
 ```python
 def on_start(self):
-    self.report_store = self.reports.open("reports.sqlite")
+    self.report_store = self.reports.open(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
     self._declare_reports()
     self._request_data(file_format=RequestFileFormat.PARQUET)
 

{pam_python-0.2.10 → pam_python-0.2.11}/pam/tester_task.py

@@ -18,7 +18,7 @@ UploadSqliteCallbackType = Callable[[str, bool, str], Optional[str]]
 UploadResultCallbackType = Callable[[str], None]
 UploadReportCallbackType = Callable[[str], None]
 RequestReportStoreCallbackType = Callable[[str, bool, str], SQLiteDownloadResult]
-PublishReportPointerCallbackType = Callable[[str, dict], bool]
+PublishReportPointerCallbackType = Callable[..., bool]
 
 class TesterTask(ITaskManager):
     """
@@ -289,8 +289,29 @@ class TesterTask(ITaskManager):
         service: Service,
         report_key: str,
         pointer: dict,
+        tracker_name: str,
     ) -> bool:
         if self.publish_report_pointer_callback is not None:
+            parameters = list(
+                inspect.signature(self.publish_report_pointer_callback).parameters.values()
+            )
+            accepts_varargs = any(
+                parameter.kind is inspect.Parameter.VAR_POSITIONAL
+                for parameter in parameters
+            )
+            positional_count = sum(
+                parameter.kind in (
+                    inspect.Parameter.POSITIONAL_ONLY,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                )
+                for parameter in parameters
+            )
+            if accepts_varargs or positional_count >= 3:
+                return self.publish_report_pointer_callback(
+                    report_key,
+                    pointer,
+                    tracker_name,
+                )
             return self.publish_report_pointer_callback(report_key, pointer)
         print("Publish Report Store V2 pointer callback is not set.")
         return False

{pam_python-0.2.10 → pam_python-0.2.11/pam_python.egg-info}/PKG-INFO

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

{pam_python-0.2.10 → pam_python-0.2.11}/tests/test_cli_templates.py

@@ -47,6 +47,23 @@ class CLITemplateTest(unittest.TestCase):
             self.assertIn("Customer-based Pagination Contract", agent_guide)
             self.assertIn("same customer-ID cohort", agent_guide)
             self.assertIn("customer-cohort cursor", agent_guide)
+            normalized_agent_guide = " ".join(agent_guide.split())
+            self.assertIn(
+                "Data Input V2 and Report Store V2 are independent contracts",
+                normalized_agent_guide,
+            )
+            self.assertIn(
+                "One store may contain many report",
+                normalized_agent_guide,
+            )
+            self.assertIn(
+                "Never generate one tracker name per report",
+                normalized_agent_guide,
+            )
+            self.assertIn(
+                "publishes one pointer for every report key changed",
+                normalized_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())

{pam_python-0.2.10 → pam_python-0.2.11}/tests/test_report_store.py

@@ -16,6 +16,7 @@ from pam.reports import (
     ReportDefinitionConflictError,
     ReportStore,
     ReportStoreDownloadError,
+    ReportStoreLocalIOError,
     ReportStoreManager,
     ReportStoreValidationError,
 )
@@ -45,7 +46,9 @@ class FakeTransport:
         return result
 
     def publish(self, store, changed_report_keys):
-        self.publish_calls.append((store.file_name, tuple(changed_report_keys)))
+        self.publish_calls.append(
+            (store.file_name, store.tracker_name, tuple(changed_report_keys))
+        )
 
 
 def make_service():
@@ -70,8 +73,14 @@ class FakeTaskManager:
         self.uploads.append((file_name, shared, sqlite_file))
         return file_name
 
-    def service_publish_report_pointer_v2(self, service, report_key, pointer):
-        self.pointers.append((report_key, pointer))
+    def service_publish_report_pointer_v2(
+        self,
+        service,
+        report_key,
+        pointer,
+        tracker_name,
+    ):
+        self.pointers.append((report_key, pointer, tracker_name))
         return True
 
 
@@ -277,7 +286,7 @@ class ReportStoreTest(unittest.TestCase):
         self.store.publish()
 
         self.assertEqual([
-            ("reports.sqlite", ("test-report-a", "test-report-b"))
+            ("reports.sqlite", "", ("test-report-a", "test-report-b"))
         ], self.transport.publish_calls)
 
     def test_generated_consumer_contract_uses_public_framework_api(self):
@@ -338,9 +347,28 @@ class ReportStoreManagerTest(unittest.TestCase):
         store = manager.create("reports.sqlite")
 
         self.assertTrue(store.path.is_file())
+        self.assertEqual("test-service", store.tracker_name)
         self.assertEqual([], transport.download_calls)
         manager.close()
 
+    def test_create_accepts_explicit_tracker_name(self):
+        transport = FakeTransport()
+        manager = ReportStoreManager(self.service, transport=transport)
+
+        store = manager.create(
+            "reports.sqlite",
+            tracker_name="Customer Report Group",
+        )
+
+        self.assertEqual("Customer Report Group", store.tracker_name)
+        manager.close()
+
+    def test_create_rejects_empty_tracker_name(self):
+        manager = ReportStoreManager(self.service, transport=FakeTransport())
+
+        with self.assertRaises(ReportStoreLocalIOError):
+            manager.create("reports.sqlite", tracker_name="  ")
+
     def test_discard_local_removes_only_open_local_store_and_allows_recreate(self):
         transport = FakeTransport()
         manager = ReportStoreManager(self.service, transport=transport)
@@ -447,6 +475,7 @@ class ReportStoreTransportTest(unittest.TestCase):
         store = SimpleNamespace(
             file_name="reports.sqlite",
             shared=False,
+            tracker_name="Customer Report Group",
             path=Path("/tmp/reports.sqlite"),
         )
 
@@ -454,10 +483,11 @@ class ReportStoreTransportTest(unittest.TestCase):
 
         self.assertEqual(1, len(service.task_manager.uploads))
         self.assertEqual(2, len(service.task_manager.pointers))
-        report_key, pointer = service.task_manager.pointers[0]
+        report_key, pointer, tracker_name = service.task_manager.pointers[0]
         self.assertEqual("test-report-a", report_key)
         self.assertEqual("REPORT_STORE_V2", pointer["protocol"])
         self.assertEqual("adapter-1", pointer["namespace"])
+        self.assertEqual("Customer Report Group", tracker_name)
 
     def test_task_manager_wraps_pointer_in_existing_report_csv_format(self):
         with tempfile.TemporaryDirectory() as temp_dir:
@@ -495,7 +525,10 @@ class ReportStoreTransportTest(unittest.TestCase):
 
             try:
                 published = manager.service_publish_report_pointer_v2(
-                    service, "test-report-a", pointer
+                    service,
+                    "test-report-a",
+                    pointer,
+                    tracker_name="Customer Report Group",
                 )
             finally:
                 TempfileUtils.temp_datasource_path = previous_temp_path
@@ -503,6 +536,7 @@ class ReportStoreTransportTest(unittest.TestCase):
         self.assertTrue(published)
         self.assertEqual(request.response_api, captured["endpoint"])
         self.assertEqual("adapter-1", captured["row"]["customer"])
+        self.assertEqual("Customer Report Group", captured["row"]["_tracker_name"])
         self.assertEqual(
             pointer,
             json.loads(captured["row"]["data_test-report-a_no_index"]),