pam-python 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

pam/__init__.py

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

pam/cli.py

@@ -8,6 +8,7 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import tomllib
 
 
 PROJECT_MARKER = ".pam-project"
@@ -159,6 +160,67 @@ def _assert_new_project(directory: Path):
         )
 
 
+def _requirement_name(requirement: str) -> str:
+    return re.split(r"[<>=!~;\s\[]", requirement, maxsplit=1)[0].lower()
+
+
+def _assert_fresh_uv_project(directory: Path):
+    pyproject_path = directory / "pyproject.toml"
+    try:
+        project = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))["project"]
+    except (OSError, tomllib.TOMLDecodeError, KeyError, TypeError) as exc:
+        raise FileExistsError(f"Invalid fresh uv project: {exc}") from exc
+
+    dependencies = project.get("dependencies", [])
+    if not isinstance(dependencies, list) or not any(
+        isinstance(item, str) and _requirement_name(item) == "pam-python"
+        for item in dependencies
+    ):
+        raise FileExistsError(
+            "Run `uv add pam-python` before `uv run pam init`"
+        )
+
+    python_version = directory / ".python-version"
+    if not python_version.is_file() or not python_version.read_text().strip().startswith("3.12"):
+        raise FileExistsError(
+            "A fresh uv project must pin Python 3.12; run `uv init --python 3.12`"
+        )
+
+    allowed = {
+        ".git",
+        ".gitignore",
+        ".python-version",
+        ".venv",
+        "README.md",
+        "main.py",
+        "pyproject.toml",
+        "uv.lock",
+    }
+    unexpected = sorted(path.name for path in directory.iterdir() if path.name not in allowed)
+    if unexpected:
+        raise FileExistsError(
+            "pam init only accepts a fresh uv project; existing files: "
+            + ", ".join(unexpected)
+        )
+
+    readme = directory / "README.md"
+    if readme.is_file() and readme.read_text(encoding="utf-8").strip():
+        raise FileExistsError("pam init will not overwrite a non-empty README.md")
+
+    main_file = directory / "main.py"
+    if main_file.is_file():
+        source = main_file.read_text(encoding="utf-8")
+        uv_placeholder = re.fullmatch(
+            r'def main\(\):\n'
+            r'    print\("Hello from [a-z0-9-]+!"\)\n\n\n'
+            r'if __name__ == "__main__":\n'
+            r'    main\(\)\n?',
+            source,
+        )
+        if uv_placeholder is None:
+            raise FileExistsError("pam init will not overwrite an edited main.py")
+
+
 def _run_uv(args: list[str], cwd: Path):
     uv = shutil.which("uv")
     if uv is None:
@@ -167,12 +229,20 @@ def _run_uv(args: list[str], cwd: Path):
 
 
 def init_project(package_manager: str | None = None):
-    package_manager = package_manager or _select_package_manager()
+    destination = Path.cwd()
+    preinitialized_uv = (destination / "pyproject.toml").is_file()
+    if preinitialized_uv:
+        if package_manager not in (None, "uv"):
+            raise FileExistsError("A uv project cannot be initialized as a pip project")
+        _assert_fresh_uv_project(destination)
+        package_manager = "uv"
+    else:
+        package_manager = package_manager or _select_package_manager()
+        _assert_new_project(destination)
+
     if package_manager not in PACKAGE_MANAGER_TEMPLATES:
         raise ValueError(f"Unsupported package manager: {package_manager}")
 
-    destination = Path.cwd()
-    _assert_new_project(destination)
     if package_manager == "uv" and shutil.which("uv") is None:
         raise RuntimeError("uv is required for this project but was not found on PATH")
 
@@ -184,6 +254,11 @@ def init_project(package_manager: str | None = None):
         **COMMON_PROJECT_TEMPLATES,
         **PACKAGE_MANAGER_TEMPLATES[package_manager],
     }
+    if preinitialized_uv:
+        templates = {
+            src: dest for src, dest in templates.items()
+            if dest not in {".gitignore", ".python-version", "pyproject.toml"}
+        }
 
     with tempfile.TemporaryDirectory(prefix=".pam-init-", dir=destination) as temp_dir:
         staging = Path(temp_dir)
@@ -202,7 +277,7 @@ def init_project(package_manager: str | None = None):
             encoding="utf-8",
         )
 
-        if package_manager == "uv":
+        if package_manager == "uv" and not preinitialized_uv:
             _run_uv(["lock"], staging)
 
         for path in staging.iterdir():

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/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/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.1.dist-info → pam_python-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.1
+Version: 0.2.3
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -58,46 +58,42 @@ This README is a practical, step-by-step guide you can follow to create and run
 
 ---
 
-**Install**
-Recommended installation:
+**Create a uv project**
+
+Install PAM inside each project instead of installing the CLI globally:
 
 ```bash
 mkdir my_data_plugin
 cd my_data_plugin
-uv tool install pam-python
+uv init --python 3.12
+uv add pam-python
+uv run pam init
 ```
 
-Pip remains supported:
+`pam init` recognizes a fresh uv project, keeps its uv configuration, and adds
+the PAM scaffold. It refuses projects whose generated source files have already
+been edited.
+
+Pip remains supported for new projects that do not use uv:
 
 ```bash
+mkdir my_data_plugin
+cd my_data_plugin
 python3 -m venv venv
 source venv/bin/activate
 python -m pip install pam-python
-```
-
----
-
-**Initialize a Project**
-This creates a runnable project with templates, including `AGENT.md` for runtime
-rules and `REPORTS.md` for the managed-report public API and copyable examples.
-
-```bash
 pam init
 ```
 
-`pam init` asks you to select `uv` (default) or `pip`. A uv project contains
-`pyproject.toml`, `.python-version`, and `uv.lock`; a pip project contains
-`requirements.txt`. The two templates are independent and are never mixed.
-
-Initialization only supports a new project directory and will not migrate or
-overwrite an existing project.
+When run in an empty directory, `pam init` still asks whether to create a uv or
+pip project. PAM never migrates an existing application.
 
 ---
 
 **Create a Service**
 
 ```bash
-pam new service rfm_segment
+uv run pam new service rfm_segment
 ```
 
 The generator asks you to select Polars (default) or Pandas. Polars services use
@@ -126,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.1.dist-info → pam_python-0.2.3.dist-info}/RECORD

@@ -1,6 +1,6 @@
-pam/__init__.py,sha256=HkDyjbFKSTG9cYUIHwpisICJbo99Cl8uvvTA7cva-wg,56
+pam/__init__.py,sha256=_my-Ddw7odQ1s6OaAir2Dk7rSmUS9FIHUgcNaBBy6mw,56
 pam/api.py,sha256=4t64ey_Jc4gC3SvfI-mtedEGzkX2cPTt0cdZgP_huLk,7231
-pam/cli.py,sha256=1jzS7a4Tz9SSIDraSdIQ88AhpAKMMMvtjiRmdQT4umU,11381
+pam/cli.py,sha256=GbTyHD2Gc2WLTY54bZ9rtofjVc7bV2JjqXThR9JCQf4,14130
 pam/interface_task_manager.py,sha256=moKUjSpAeNF9C2dluDFPAdU4IyvwXckB0RK-jINTLm4,1665
 pam/logger.py,sha256=JYPfIpaQZy6QrfVKrzEMrxOgTzWIEhoegvIZgHTGWoc,3021
 pam/request_file_format.py,sha256=fSRlJagbvVGqdIEqhINSeqBNUTNQdm8GL5JfqgX9bxU,317
@@ -48,7 +48,7 @@ pam/reports/transport.py,sha256=t3oEVptS9msnNafia1G8vmTUCdhxvV5L2-0AY-8SKFk,2062
 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=XoguXdHm7qw4ssHIL7yP3ZVhmiPosOc0Js_WCLbw_3o,14822
+pam/templates/init/AGENT.md,sha256=PWZ-qp1bfyU5D0H5hnFLR6LHnv4efNLIglAGhsAfb1A,16105
 pam/templates/init/REPORTS.md,sha256=rg9oi0_xDYr0BZBluJh0vPF8lSx7mCRFpDCpUgNl68A,42851
 pam/templates/init/dockerignore.tmpl,sha256=Ht1eCgQLqalEwpUjih0FQavzhYJbT2jH-FP4btM3960,52
 pam/templates/init/gitignore.tmpl,sha256=U59ynPRu_Kw6evqQzOOTAhWKdIXbf1uBOF2V8223tU8,3510
@@ -65,13 +65,13 @@ pam/templates/project/uv/python-version,sha256=e1X45ntWI8S-8_ppEojalDfXnTq6FW3kj
 pam/templates/service/common/service.yaml,sha256=ceyFswXjTh07vB4hrJEu7pj3mjlq3NPD4GPYTmvGwmE,44
 pam/templates/service/pandas/functions.tmpl,sha256=ziHgPaK7i8ESY-TxPMuKbqAFILjzdgn1p5FdPf3pYuw,360
 pam/templates/service/pandas/service.test.tmpl,sha256=PybHu_c5BMhUmvkc9ycQH7vJbPWt7isJAH2r-ElQ9dE,3760
-pam/templates/service/pandas/service_class.tmpl,sha256=LGgIYjfdsBwppOqP-FfgEsF1kxeSwUnYwK935gqC7GQ,2138
+pam/templates/service/pandas/service_class.tmpl,sha256=629kX2qJAmNzj5MrGdg6FLqgijEML8D3Ddo7k27LzbM,2614
 pam/templates/service/polars/functions.tmpl,sha256=nMKFC5GqIm2Q1dSg2zDOscSwQaOpzS2jzqjQV7xhPRk,382
 pam/templates/service/polars/service.test.tmpl,sha256=58x_MJYwp7BvDtuSsETAt9Q6v5KwOI8MaEdjNciAQDk,3746
-pam/templates/service/polars/service_class.tmpl,sha256=8FDTFb6I5OHFqM0KPJtYDFAHeL3kl2WbwtbHAjwTG4Y,1830
-pam_python-0.2.1.dist-info/licenses/LICENSE.txt,sha256=yeHD2-gzrkkET2ZkMe22WyUGpDjlwTrqA4POb0FoZi4,1138
-pam_python-0.2.1.dist-info/METADATA,sha256=fPvsI78skyXPDA5yh_a2dZopS9xLmYa7TY2HftO9a4s,8730
-pam_python-0.2.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-pam_python-0.2.1.dist-info/entry_points.txt,sha256=xqYpsIqvNlO0j8elZc02bDwR-12dLK9FU2B1ACsLYxw,37
-pam_python-0.2.1.dist-info/top_level.txt,sha256=0EOjbyc3hQyzjhn6iyMgsEseqA66Xz0p27iBN7G7W1w,4
-pam_python-0.2.1.dist-info/RECORD,,
+pam/templates/service/polars/service_class.tmpl,sha256=tWfEv6dBeL0wm41VfL2YI5JA6EUF08rH_nnsmk25A84,2306
+pam_python-0.2.3.dist-info/licenses/LICENSE.txt,sha256=yeHD2-gzrkkET2ZkMe22WyUGpDjlwTrqA4POb0FoZi4,1138
+pam_python-0.2.3.dist-info/METADATA,sha256=Ce02r8gxDTde0fNWk6WGCIwxBz6538-pJBTcy8HR0Do,8703
+pam_python-0.2.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pam_python-0.2.3.dist-info/entry_points.txt,sha256=xqYpsIqvNlO0j8elZc02bDwR-12dLK9FU2B1ACsLYxw,37
+pam_python-0.2.3.dist-info/top_level.txt,sha256=0EOjbyc3hQyzjhn6iyMgsEseqA66Xz0p27iBN7G7W1w,4
+pam_python-0.2.3.dist-info/RECORD,,