pam-python 0.2.19__py3-none-any.whl → 0.2.20__py3-none-any.whl

pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.19"
+__version__ = "0.2.20"

pam/models/data_input_v2.py

@@ -127,6 +127,7 @@ class DataInputV2:
     datasets: tuple[DataInputV2Dataset, ...]
     run_complete: bool
     next: str
+    missing_contacts: DataInputV2File | None = None
 
     def iter_population_rows(self) -> Iterator[dict[str, str]]:
         """Stream the population file for this customer-aligned logical page."""
@@ -210,6 +211,15 @@ def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
     if contact_count > max_contacts_per_batch:
         raise ValueError("V2 population contact_count exceeds configured batch maximum")
 
+    missing_contacts = None
+    if "missing_contacts" in manifest:
+        missing_contacts = _parse_and_verify_file(
+            manifest["missing_contacts"],
+            files_by_name,
+            declared_names,
+            population_format,
+        )
+
     raw_datasets = manifest.get("datasets")
     if not isinstance(raw_datasets, list) or len(raw_datasets) > V2_MAX_DATASETS:
         raise ValueError("V2 manifest datasets must be a list of at most five items")
@@ -283,6 +293,7 @@ def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
         max_contacts_per_batch=max_contacts_per_batch,
         time_window=time_window,
         population=population_file,
+        missing_contacts=missing_contacts,
         datasets=tuple(datasets),
         run_complete=_required_bool(manifest, "run_complete"),
         next=_required_optional_string(manifest, "next"),

pam/task_manager.py

@@ -9,6 +9,7 @@ import math
 import os
 import time
 import threading
+import uuid
 from typing import Dict, TYPE_CHECKING
 from pam.utils import log
 from pam.api import API
@@ -453,34 +454,31 @@ class TaskManager(ITaskManager):
         return response
 
     def service_upload_report(self, service: Service, file_path):
-        """
-        Uploads a report file asynchronously and logs the response.
-        """
-        endpoint = service.request.response_api
-
-        def handle_report_response(response):
-            """Logs the response after the report upload completes."""
-            if response is None:
-                log(f"Response from report upload to {endpoint}: None")
-                return
-            try:
-                response_data = response.json()
-            except ValueError:
-                response_data = response.text
-            log(f"Response from report upload to {endpoint}: {response_data}")
-
-        def upload_wrapper():
-            """Wrapper for the report upload to handle response logging."""
-            response = self.api.http_upload(
-                endpoint,
-                file_path,
-                {"token": service.request.token},
-            )
-            handle_report_response(response)
-
-        log(f"Uploading Report to: {endpoint}")
-        http_thread = threading.Thread(target=upload_wrapper)
-        http_thread.start()
+        """Wait for PAM to enqueue a legacy report; propagate delivery failures."""
+        trace_id = uuid.uuid4().hex
+        started = time.monotonic()
+        log(f"report_delivery_started trace_id={trace_id} service={service.request.service_name} "
+            f"report_file={Path(file_path).name}")
+        response = self.api.http_upload(
+            service.request.response_api,
+            file_path,
+            {"token": service.request.token, "report_delivery_id": trace_id},
+        )
+        status = response.status_code if response is not None else None
+        if response is None or not 200 <= status < 300:
+            log(f"report_delivery_failed trace_id={trace_id} http_status={status}")
+            raise RuntimeError(f"Report delivery failed trace_id={trace_id} http_status={status}")
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        stage = body.get("stage", "accepted_unconfirmed") if isinstance(body, dict) else "accepted_unconfirmed"
+        log(f"report_delivery_response trace_id={trace_id} http_status={status} "
+            f"stage={stage} elapsed_s={time.monotonic() - started:.3f}")
+        # Older PAM deployments only acknowledge receipt. Do not report that as
+        # successful publication: the new endpoint explicitly confirms enqueue.
+        if not isinstance(body, dict) or body.get("report_delivery_id") != trace_id or stage != "tracker_queued":
+            raise RuntimeError(f"Report delivery was not confirmed; update PAM first trace_id={trace_id}")
 
     def service_publish_report_pointer_v2(
         self,

pam/templates/init/AGENT.md

@@ -680,3 +680,13 @@ Prefer streaming/chunked/incremental processing whenever possible.
 - Treat Polars lazy queries as the default compute path.
 - Use Pandas only when the selected service template or an integration requires it.
 - Prefer streaming or incremental durable steps when a query cannot stay in memory.
+
+### Missing contacts in V2 input
+
+`data.missing_contacts` is an optional verified `DataInputV2File` with one `id`
+column, using the same CSV or Parquet format as population. Read it with
+`scan_polars()` or `read_pandas()`; `iter_csv_rows()` is CSV-only. Older
+manifests expose `None`, while a present zero-row file is valid. These IDs are
+excluded from population and configured datasets. Their absence does not prove
+deletion; plugin developers decide whether and how to handle them. Read the
+file before page cleanup. Do not treat it as a configured dataset position.

{pam_python-0.2.19.dist-info → pam_python-0.2.20.dist-info}/METADATA

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

{pam_python-0.2.19.dist-info → pam_python-0.2.20.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pam/__init__.py,sha256=FJm-IRTRlhqCfc4j3SOZSm0M6COGOUIQWtufhNDjpAA,57
+pam/__init__.py,sha256=KdW64FpMxu2aAx-3gs199l6f7BdAIK_OkLhszvC_MM0,57
 pam/api.py,sha256=nfsq9OLHutitRMqwkoi3mD0gZ3EfMUzN2rwmS9gpVpY,8198
 pam/cli.py,sha256=Ip4kYNbZ49WAkcMN4SuNc2qXxDeagOzJwE7GSb-BYlE,13831
 pam/datetime_utils.py,sha256=sDFxNRR46FsO61p-EzhmIRS6ARnfMPRquKee_RcQ_3E,664
@@ -9,12 +9,12 @@ pam/result_batch_uploader.py,sha256=xw4b-q7i52CoCjvQtQ8EgfBrrqAl1zEl6sTO-wIvFPc,
 pam/server.py,sha256=auok-4Ls3fTnRS-_sQHt0SHQIOLW1NPwk8B_tmmZwI0,8191
 pam/service.py,sha256=nH8dupZWFr8-Ab00S9UJvaJfqNd-_6qvKMQMzTiWibc,9416
 pam/sqlite.py,sha256=0bEUnb17V_Z6N6u843MYyGQnigaAuMx6FUckeWifn8I,2585
-pam/task_manager.py,sha256=iNXm5gFwl8ybijd36RedZpkj7J9TEF6ZRLTpReHgPQs,20681
+pam/task_manager.py,sha256=psO6RRd_n-PgEGp0OwOfuHG-TMOYrq4YajKwhv9PqZU,21188
 pam/temp_file_utils.py,sha256=noMyF4SZ17AWtZcRkZtNtdObRWzykAMxeFr-WkOEQi4,9450
 pam/tester_task.py,sha256=SKRIut-kksIVWSMwzquqi7MxrZyTO6x2ggqlnRsVJQ4,11967
 pam/utils.py,sha256=-pfnQ00Ib-IXvrMz4S5lTlO36PtSaJoQOhwXpwet8h4,1744
 pam/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pam/models/data_input_v2.py,sha256=0mkZHPjb0RLmc-v4W5Su8_bAw-3U5qL-YU1yF5Z-oCI,17536
+pam/models/data_input_v2.py,sha256=XiLLOPziIo016dC-OfDUgASLkn6oU09HRCcsvNx3Rhg,17888
 pam/models/request_command.py,sha256=6QBJyQfu75bMfhqBUILE1chvhjRdZ8WHWiBbX3k8K5s,14211
 pam/models/sqlite_download.py,sha256=7JMWwLp_5LSCMR5Ppk1RgbgcOaX_2LmRFrJiADAnIfs,678
 pam/reports/__init__.py,sha256=vdAzsUN0bmYPGjqKveg9HjNWe_MnBZj3b42TsDBE6_w,2368
@@ -51,7 +51,7 @@ pam/reports/transport.py,sha256=iDm63RQnPfhCJ1zFbr1uAVYHz3ondNfp2scz21JAnL8,2111
 pam/reports/treemap.py,sha256=W_VwxbiRMSvkNpY2z1HfbZtGKWXNr6FdbVdI0grVesw,4251
 pam/templates/buildcmd/pamb,sha256=58GCN59ysvHGNhPvTD3nkF4aLg-kM1WfWmH7CL3eQVo,530
 pam/templates/buildcmd/pamb-base.sh,sha256=Q0DkbeHtPx33PIjc68EeI7ZIwBOLlwcSmPhpxALXxVY,518
-pam/templates/init/AGENT.md,sha256=yOtdr5aSsqPbjh7gWbyfoFYnCZ7opVSF9ol0LbONCTw,27030
+pam/templates/init/AGENT.md,sha256=36J7Si-C7n_als111-iRaH6-iQbqFtdFpN0JTGwNUA4,27601
 pam/templates/init/REPORTS-th.md,sha256=VdGUFvxU0Zl6pYKgFHIC6U8pmQJcz4JFM7_QYbcXblc,36196
 pam/templates/init/REPORTS.md,sha256=LCMXW1SLRpOz2yWYM5Pp_B7H90E_X_aQ9vXYvHhEJgc,49868
 pam/templates/init/dockerignore.tmpl,sha256=Ht1eCgQLqalEwpUjih0FQavzhYJbT2jH-FP4btM3960,52
@@ -73,9 +73,9 @@ pam/templates/service/pandas/service_class.tmpl,sha256=qaq9tqRhxogWQlqi09dbX5vLu
 pam/templates/service/polars/functions.tmpl,sha256=7Qlwsd5Q1vdkOvXHtlltjb2oS-i7JuNKPor2iNDSsQg,701
 pam/templates/service/polars/service.test.tmpl,sha256=nC6VoauZMYy_UTTXxxergfWbXvUD_VWwpM7-7A3aKqE,6881
 pam/templates/service/polars/service_class.tmpl,sha256=jMGeruXduu0eBB7FPDEkZu8b4mSIO3uRt5TiDuNq5T4,3688
-pam_python-0.2.19.dist-info/licenses/LICENSE.txt,sha256=yeHD2-gzrkkET2ZkMe22WyUGpDjlwTrqA4POb0FoZi4,1138
-pam_python-0.2.19.dist-info/METADATA,sha256=y4WkR7ZBdQWvV2GkxmuoaBiSNZmLmUHX2-jzd12KYPM,10116
-pam_python-0.2.19.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-pam_python-0.2.19.dist-info/entry_points.txt,sha256=xqYpsIqvNlO0j8elZc02bDwR-12dLK9FU2B1ACsLYxw,37
-pam_python-0.2.19.dist-info/top_level.txt,sha256=0EOjbyc3hQyzjhn6iyMgsEseqA66Xz0p27iBN7G7W1w,4
-pam_python-0.2.19.dist-info/RECORD,,
+pam_python-0.2.20.dist-info/licenses/LICENSE.txt,sha256=yeHD2-gzrkkET2ZkMe22WyUGpDjlwTrqA4POb0FoZi4,1138
+pam_python-0.2.20.dist-info/METADATA,sha256=l8sFUyXDsXS9GU9GVnhN9DcIRolP9POSLkXYR0-hkVI,10116
+pam_python-0.2.20.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pam_python-0.2.20.dist-info/entry_points.txt,sha256=xqYpsIqvNlO0j8elZc02bDwR-12dLK9FU2B1ACsLYxw,37
+pam_python-0.2.20.dist-info/top_level.txt,sha256=0EOjbyc3hQyzjhn6iyMgsEseqA66Xz0p27iBN7G7W1w,4
+pam_python-0.2.20.dist-info/RECORD,,