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

{pam_python-0.2.1/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.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 → pam_python-0.2.3}/README.md

@@ -38,46 +38,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
@@ -106,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.1 → pam_python-0.2.3}/pam/__init__.py

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

{pam_python-0.2.1 → pam_python-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_python-0.2.1 → 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.1 → 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.1 → 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.1 → 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.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 → pam_python-0.2.3}/tests/test_cli_templates.py

@@ -1,3 +1,4 @@
+import json
 import os
 from pathlib import Path
 import sys
@@ -42,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())
@@ -61,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"),
@@ -114,6 +122,57 @@ class CLITemplateTest(unittest.TestCase):
                 calls,
             )
 
+    def test_init_adopts_a_fresh_uv_project_without_rewriting_uv_files(self):
+        calls = []
+        original_pyproject = """[project]
+name = "customer-plugin"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["pam-python>=0.2.1"]
+"""
+        uv_main = '''def main():
+    print("Hello from customer-plugin!")
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+        with tempfile.TemporaryDirectory() as temp_dir, WorkingDirectory(temp_dir):
+            root = Path(temp_dir)
+            (root / "pyproject.toml").write_text(original_pyproject)
+            (root / ".python-version").write_text("3.12\n")
+            (root / "uv.lock").write_text("version = 1\n")
+            (root / ".gitignore").write_text(".venv\n")
+            (root / "README.md").touch()
+            (root / "main.py").write_text(uv_main)
+
+            with mock.patch.object(cli.shutil, "which", return_value="/usr/bin/uv"), mock.patch.object(
+                cli, "_run_uv", side_effect=lambda args, cwd: calls.append(list(args))
+            ):
+                cli.init_project()
+
+            self.assertEqual(original_pyproject, (root / "pyproject.toml").read_text())
+            self.assertEqual("3.12\n", (root / ".python-version").read_text())
+            self.assertEqual("version = 1\n", (root / "uv.lock").read_text())
+            self.assertEqual(".venv\n", (root / ".gitignore").read_text())
+            self.assertIn("plugin_server = Server", (root / "main.py").read_text())
+            self.assertEqual("uv", json.loads((root / ".pam-project").read_text())["package_manager"])
+            self.assertEqual([], calls)
+
+    def test_init_rejects_an_edited_uv_project(self):
+        with tempfile.TemporaryDirectory() as temp_dir, WorkingDirectory(temp_dir):
+            root = Path(temp_dir)
+            (root / "pyproject.toml").write_text(
+                '[project]\nname = "plugin"\nversion = "0.1.0"\n'
+                'dependencies = ["pam-python"]\n'
+            )
+            (root / ".python-version").write_text("3.12\n")
+            (root / "main.py").write_text("print('real code')\n")
+
+            with self.assertRaisesRegex(FileExistsError, "edited main.py"):
+                cli.init_project()
+
     def test_init_rejects_an_existing_project_without_overwriting(self):
         with tempfile.TemporaryDirectory() as temp_dir, WorkingDirectory(temp_dir):
             original = Path("main.py")