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

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

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

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

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

pam_python-0.2.10/pam/datetime_utils.py

@@ -0,0 +1,20 @@
+"""PAM's canonical suffix-free UTC+0 datetime contract."""
+
+from datetime import datetime, timezone
+
+
+PAM_DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def parse_pam_datetime(value: str) -> datetime:
+    """Parse an exact PAM datetime string and attach UTC without shifting it."""
+    return datetime.strptime(value, PAM_DATETIME_FORMAT).replace(tzinfo=timezone.utc)
+
+
+def format_pam_datetime(value: datetime) -> str:
+    """Format a datetime as PAM UTC+0 without a timezone suffix."""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    else:
+        value = value.astimezone(timezone.utc)
+    return value.strftime(PAM_DATETIME_FORMAT)

{pam_python-0.2.8 → pam_python-0.2.10}/pam/logger.py

@@ -4,9 +4,11 @@ from datetime import datetime, timezone
 from threading import Lock
 from typing import Any
 
+from pam.datetime_utils import format_pam_datetime
 from pam.utils import log as stdout_log
 from pam.service import Service
 
+
 class Logger:
     def __init__(self, service: Service, buffer_size: int = 20, source: str = "worker"):
         self.service = service
@@ -92,4 +94,4 @@ class Logger:
 
     @staticmethod
     def _utc_now() -> str:
-        return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+        return format_pam_datetime(datetime.now(timezone.utc))

{pam_python-0.2.8 → pam_python-0.2.10}/pam/models/data_input_v2.py

@@ -2,12 +2,12 @@ from __future__ import annotations
 
 import csv
 from dataclasses import dataclass
-from datetime import datetime
 from hashlib import sha256
 import json
 from pathlib import Path
 from typing import Any, Iterator
 
+from pam.datetime_utils import parse_pam_datetime
 from pam.temp_file_utils import TempfileUtils
 
 
@@ -374,11 +374,11 @@ def _parse_time_window(raw_time_window: Any) -> DataInputV2TimeWindow | None:
     start_inclusive = _required_bool(raw_time_window, "start_inclusive")
     end_inclusive = _required_bool(raw_time_window, "end_inclusive")
     try:
-        start_time = datetime.fromisoformat(start.replace("Z", "+00:00"))
-        end_time = datetime.fromisoformat(end.replace("Z", "+00:00"))
+        start_time = parse_pam_datetime(start)
+        end_time = parse_pam_datetime(end)
     except ValueError as error:
         raise ValueError("V2 manifest time_window timestamps are invalid") from error
-    if start_time.tzinfo is None or end_time.tzinfo is None or start_time >= end_time:
+    if start_time >= end_time:
         raise ValueError("V2 manifest time_window order is invalid")
     if not start_inclusive or end_inclusive:
         raise ValueError("V2 manifest time_window must be half-open")

{pam_python-0.2.8 → pam_python-0.2.10}/pam/reports/record.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass, field
 from datetime import date, datetime, timezone
 from typing import Any, Dict, Optional, Tuple
 
+from pam.datetime_utils import parse_pam_datetime
 from pam.reports.errors import ReportStoreValidationError
 
 
@@ -75,14 +76,15 @@ def normalize_timestamp(value: Any) -> Optional[int]:
         parsed = datetime.combine(value, datetime.min.time(), tzinfo=timezone.utc)
     elif isinstance(value, str) and value:
         try:
-            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+            parsed = parse_pam_datetime(value)
         except ValueError as exc:
             raise ReportStoreValidationError(
-                f"Timestamp value is not ISO-8601: {value}"
+                f"Timestamp value must use PAM UTC format YYYY-MM-DD HH:mm:ss: {value}"
             ) from exc
     else:
         raise ReportStoreValidationError(
-            "Timestamp values must be epoch milliseconds, date, datetime, or ISO-8601 string"
+            "Timestamp values must be epoch milliseconds, date, datetime, "
+            "or a PAM UTC string using YYYY-MM-DD HH:mm:ss"
         )
     if parsed.tzinfo is None:
         parsed = parsed.replace(tzinfo=timezone.utc)

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

@@ -8,6 +8,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Iterable, List, Optional, Set
 
+from pam.datetime_utils import format_pam_datetime
 from pam.reports.errors import (
     DuplicateReportRecordError,
     ReportDefinitionConflictError,
@@ -48,7 +49,7 @@ from pam.reports.treemap import TreemapReport
 
 
 def _now() -> str:
-    return datetime.now(timezone.utc).isoformat()
+    return format_pam_datetime(datetime.now(timezone.utc))
 
 
 class ReportStore:

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

@@ -1,5 +1,13 @@
 # AGENT
 
+## PAM date and time contract
+
+PAM timestamps are UTC+0 strings in the exact format `%Y-%m-%d %H:%M:%S`, for
+example `2026-03-31 02:37:44`. The timezone suffix is intentionally omitted.
+Interpret these values as UTC without shifting the clock value. Do not emit or
+expect RFC3339, ISO-8601, `T`, `Z`, or explicit timezone suffixes in internal PAM
+contracts.
+
 This document defines the **data plugin runtime specification** and execution contract so developers and agents can create services and understand runtime behavior inside the CDP environment.
 
 This is not a tutorial.

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

@@ -230,7 +230,8 @@ Initial value types:
 - `number`
 - `boolean`
 - `date` — calendar date, serialized as `YYYY-MM-DD`
-- `datetime` — timestamp normalized to epoch milliseconds internally
+- `datetime` — timestamp normalized to epoch milliseconds internally; string
+  inputs must use PAM UTC format `YYYY-MM-DD HH:mm:ss`
 
 Objects and arrays are not initial field types. A report that requires a complex
 cell or point must first introduce an explicit framework and CMS contract.
@@ -1127,8 +1128,8 @@ ranges.append_ranges([
         {
             "task": "Phase A",
             "group": "Project 1",
-            "start": "2026-08-01T09:00:00+07:00",
-            "end": "2026-08-05T18:00:00+07:00",
+            "start": "2026-08-01 09:00:00",
+            "end": "2026-08-05 18:00:00",
         },
 ], partition_key="2026-08")
 ```

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

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

{pam_python-0.2.8 → pam_python-0.2.10}/pam_python.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 pam/__init__.py
 pam/api.py
 pam/cli.py
+pam/datetime_utils.py
 pam/interface_task_manager.py
 pam/logger.py
 pam/request_file_format.py
@@ -84,6 +85,7 @@ tests/test_cli_templates.py
 tests/test_data_error_v2.py
 tests/test_data_input_v2.py
 tests/test_data_timeout_v2.py
+tests/test_datetime_utils.py
 tests/test_range_transform.py
 tests/test_report_store.py
 tests/test_request_data_v2.py

{pam_python-0.2.8 → pam_python-0.2.10}/tests/test_data_input_v2.py

@@ -23,7 +23,7 @@ class DataInputV2Test(unittest.TestCase):
         TempfileUtils.temp_datasource_path = str(self.temp_dir / "data_sources")
         self.population_path = self._write_file(
             "population.csv",
-            b"id,contact_created_at\ncontact-1,2025-01-01T00:00:00Z\n",
+            b"id,contact_created_at\ncontact-1,2025-01-01 00:00:00\n",
         )
         self.dataset_path = self._write_file(
             "dataset_001_demographic_part_0001.csv",
@@ -255,8 +255,8 @@ class DataInputV2Test(unittest.TestCase):
         manifest["datasets"][0]["type"] = "event"
         manifest["datasets"][0]["event_names"] = ["purchase"]
         manifest["time_window"] = {
-            "start": "2025-08-14T07:00:00Z",
-            "end": "2026-08-14T07:00:00Z",
+            "start": "2025-08-14 07:00:00",
+            "end": "2026-08-14 07:00:00",
             "start_inclusive": True,
             "end_inclusive": False,
         }
@@ -268,8 +268,8 @@ class DataInputV2Test(unittest.TestCase):
 
         self.assertEqual("event_all", data_input.population_mode)
         self.assertIsNotNone(data_input.time_window)
-        self.assertEqual("2025-08-14T07:00:00Z", data_input.time_window.start)
-        self.assertEqual("2026-08-14T07:00:00Z", data_input.time_window.end)
+        self.assertEqual("2025-08-14 07:00:00", data_input.time_window.start)
+        self.assertEqual("2026-08-14 07:00:00", data_input.time_window.end)
         self.assertTrue(data_input.time_window.start_inclusive)
         self.assertFalse(data_input.time_window.end_inclusive)
 
@@ -299,8 +299,8 @@ class DataInputV2Test(unittest.TestCase):
         manifest["datasets"][0]["type"] = "event"
         manifest["datasets"][0]["event_names"] = ["purchase"]
         manifest["time_window"] = {
-            "start": "2025-08-14T07:00:00Z",
-            "end": "2026-08-14T07:00:00Z",
+            "start": "2025-08-14 07:00:00",
+            "end": "2026-08-14 07:00:00",
             "start_inclusive": True,
             "end_inclusive": True,
         }
@@ -311,6 +311,23 @@ class DataInputV2Test(unittest.TestCase):
                 [str(manifest_path), str(self.population_path), str(self.dataset_path)]
             )
 
+    def test_parse_rejects_rfc3339_event_time_window(self):
+        manifest = self._valid_manifest()
+        manifest["datasets"][0]["type"] = "event"
+        manifest["datasets"][0]["event_names"] = ["purchase"]
+        manifest["time_window"] = {
+            "start": "2025-08-14T07:00:00Z",
+            "end": "2026-08-14T07:00:00Z",
+            "start_inclusive": True,
+            "end_inclusive": False,
+        }
+        manifest_path = self._write_manifest(manifest)
+
+        with self.assertRaisesRegex(ValueError, "timestamps are invalid"):
+            parse_data_input_v2(
+                [str(manifest_path), str(self.population_path), str(self.dataset_path)]
+            )
+
     def test_parse_rejects_event_population_without_event_dataset(self):
         manifest = self._valid_manifest()
         manifest["population"]["mode"] = "event_any"

pam_python-0.2.10/tests/test_datetime_utils.py

@@ -0,0 +1,43 @@
+import unittest
+from datetime import datetime, timedelta, timezone
+
+from pam.datetime_utils import format_pam_datetime, parse_pam_datetime
+from pam.logger import Logger
+
+
+class PAMDateTimeUtilsTest(unittest.TestCase):
+    def test_round_trip_uses_suffix_free_utc_format(self):
+        parsed = parse_pam_datetime("2026-03-31 02:37:44")
+
+        self.assertEqual(timezone.utc, parsed.tzinfo)
+        self.assertEqual("2026-03-31 02:37:44", format_pam_datetime(parsed))
+
+    def test_format_converts_aware_datetime_to_utc(self):
+        value = datetime(
+            2026,
+            3,
+            31,
+            9,
+            37,
+            44,
+            tzinfo=timezone(timedelta(hours=7)),
+        )
+
+        self.assertEqual("2026-03-31 02:37:44", format_pam_datetime(value))
+
+    def test_parse_rejects_rfc3339(self):
+        with self.assertRaises(ValueError):
+            parse_pam_datetime("2026-03-31T02:37:44Z")
+
+    def test_structured_logger_uses_pam_utc_format(self):
+        logged_at = Logger._utc_now()
+
+        self.assertEqual(19, len(logged_at))
+        self.assertEqual(
+            logged_at,
+            format_pam_datetime(parse_pam_datetime(logged_at)),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -1,6 +1,7 @@
 import csv
 import importlib
 import json
+import re
 import shutil
 import sqlite3
 import tempfile
@@ -136,6 +137,23 @@ class ReportStoreTest(unittest.TestCase):
                 definition_json="{}",
             )
 
+    def test_metadata_timestamps_use_pam_utc_format(self):
+        self.report()
+        self.store._append_records(
+            "test-report-a",
+            [ReportRecord(dimensions={"customer": "contact-1"}, measures={})],
+        )
+
+        timestamps = self.store._connection.execute(
+            "SELECT created_at, updated_at FROM report_definitions "
+            "UNION ALL SELECT created_at, updated_at FROM report_records"
+        ).fetchall()
+        pattern = re.compile(r"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$")
+        self.assertTrue(timestamps)
+        for created_at, updated_at in timestamps:
+            self.assertRegex(created_at, pattern)
+            self.assertRegex(updated_at, pattern)
+
         with self.assertRaises(ReportStoreValidationError):
             self.store._declare_report(
                 key="invalid-range",

{pam_python-0.2.8 → pam_python-0.2.10}/tests/test_typed_range_bar_report.py

@@ -50,8 +50,8 @@ class TypedRangeBarReportTest(unittest.TestCase):
             [{
                 "task": "Phase A",
                 "group": "Project 1",
-                "start": "2026-08-01T09:00:00+07:00",
-                "end": "2026-08-05T18:00:00+07:00",
+                "start": "2026-08-01 09:00:00",
+                "end": "2026-08-05 18:00:00",
             }],
             "2026-08",
         )
@@ -61,6 +61,16 @@ class TypedRangeBarReportTest(unittest.TestCase):
         measures = json.loads(row[0])
         self.assertIsInstance(measures["start"], int)
         self.assertGreater(measures["end"], measures["start"])
+        with self.assertRaises(ReportStoreValidationError):
+            report.append_ranges(
+                [{
+                    "task": "Wrong format",
+                    "group": "Project 1",
+                    "start": "2026-08-01T09:00:00Z",
+                    "end": "2026-08-05T18:00:00Z",
+                }],
+                "2026-08",
+            )
         with self.assertRaises(ReportStoreValidationError):
             report.append_ranges(
                 [{"task": "Bad", "group": "Project 1", "start": 20, "end": 10}],