pam-python 0.1.44__tar.gz → 0.2.0__tar.gz

{pam_python-0.1.44/pam_python.egg-info → pam_python-0.2.0}/PKG-INFO

@@ -1,26 +1,24 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.1.44
+Version: 0.2.0
 Summary: Pam Python Library
 Home-page: https://github.com/heart/pam-python
 Author: Narongrit Kanhanoi
 Author-email: narongrit@pams.ai
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: License :: Other/Proprietary License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Customer Service
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: setuptools>=70.0.0
 Requires-Dist: Flask>=3.0.2
 Requires-Dist: aiohttp>=3.11.11
 Requires-Dist: pandas>=2.2.3
-Requires-Dist: Faker>=33.1.0
 Requires-Dist: dask>=2024.12.1
 Requires-Dist: dask-expr>=1.1.21
 Requires-Dist: requests>=2.32.3
@@ -43,11 +41,15 @@ This repository provides the `pam` CLI and runtime framework to build Data Plugi
 
 This README is a practical, step-by-step guide you can follow to create and run a real service.
 
+Current release target: **0.2.0**
+
 **What you get**
 
 - CLI to initialize a project and scaffold services
 - Service lifecycle contract (start, data input, upload, exit)
 - Temp file and SQLite helpers
+- Managed Report Store V2 with typed Table, Metric, and ApexCharts-compatible builders
+- Named `ResultBatchUploader` streams for bounded DataFrame uploads
 - A monitoring loop for service timeouts and periodic cleanup
 
 ---
@@ -70,7 +72,7 @@ This README is a practical, step-by-step guide you can follow to create and run
 
 **Prerequisites**
 
-- Python 3.8+ recommended
+- Python 3.9+
 - `pip` and a working virtual environment
 
 ---
@@ -94,7 +96,8 @@ pip install pam-python
 ---
 
 **Initialize a Project**
-This creates a runnable project with templates (including `AGENT.md`).
+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
@@ -143,7 +146,8 @@ The runtime calls your service in two main phases.
 
 When your service is done:
 
-- Call `self._upload_result(...)` or `self._upload_report(...)`
+- Upload ordinary CDP result rows through `ResultBatchUploader` or `_upload_result(...)`
+- Publish managed reports through `self.reports`; do not build report JSON manually
 - Call `self._exit()` to signal completion
 
 ---
@@ -173,15 +177,47 @@ Recommended usage:
 from pam.result_batch_uploader import ResultBatchUploader
 
 batch_uploader = ResultBatchUploader(self, batch_size=50000)
-batch_uploader.upload(df, "data-name")
+batch_uploader.upload(df, name="main")
 batch_uploader.flush()
 status = batch_uploader.get_status()
 ```
 
 Notes:
 
-- `name` separates different result streams (A/B) to avoid schema conflicts.
-- `flush()` uploads any remaining rows that are below the batch size.
+- `request.runtime_parameters["batch_size"]` overrides the constructor default when valid.
+- `name` separates result streams and enforces one stable column schema per stream.
+- `options` may be passed to `upload(...)` and are forwarded to `_upload_result`.
+- Complete batches upload immediately; `flush()` sends the remaining rows.
+- `get_status()` returns buffered rows, uploaded rows, and uploaded batch counts per stream.
+
+---
+
+**Managed Reports (Report Store V2)**
+
+Managed reports are static facts stored in framework-owned SQLite. Plugin code
+selects a typed builder, writes source-derived `DAY`, `MONTH`, or `NONE` facts, and
+publishes only after the full calculation succeeds.
+
+```python
+fresh = self.request.get_runtime_bool("fresh", default=False)
+store = (
+    self.reports.create("reports.sqlite")
+    if fresh
+    else self.reports.open("reports.sqlite")
+)
+
+# Choose the builder agreed in the customer requirement.
+# See generated REPORTS.md for every supported declaration and write API.
+```
+
+Important rules:
+
+- Use only typed builders documented in `REPORTS.md`; there is no raw-report API.
+- `open()` resumes the remote file or creates it only after an authoritative 404.
+- Network/5xx download failures never create a replacement store.
+- Use `create()` only for a human-requested fresh restart.
+- Delete a partition, write its recalculated facts, then call `store.publish()` once.
+- Low-level `_request_sqlite`/`_upload_sqlite` remain for custom plugin state, not reports.
 
 ---
 
@@ -202,13 +238,29 @@ export SERVER_PORT=8000
 ---
 
 **Testing a Service**
-Run unit tests for a service:
+Run tests through the generated script for your current shell. This keeps the
+active terminal's Python environment and project context instead of launching
+test discovery through the `pam` CLI.
+
+macOS/Linux:
 
 ```bash
-pam test rfm_segment
+./run_unit_test.sh rfm_segment
+```
+
+Windows PowerShell:
+
+```powershell
+.\run_unit_test.ps1 rfm_segment
+```
+
+Windows Command Prompt:
+
+```bat
+run_unit_test.bat rfm_segment
 ```
 
-If you write custom tests, place them in the service folder and name them `test_<service>.py`.
+Place custom tests in the service folder and name them `test_<service>.py`.
 
 ---
 
@@ -231,6 +283,7 @@ After `pam init` and one service:
 .
 ├── main.py
 ├── AGENT.md
+├── REPORTS.md
 ├── Dockerfile
 ├── rfm_segment/
 │   ├── RfmSegmentSvc.py
@@ -256,4 +309,5 @@ After `pam init` and one service:
 - Implement your logic in `functions.py`.
 - Wire it into `on_start` and `on_data_input` in your service class.
 - Use the temp utilities to write intermediate files.
-- Use `_upload_result` to return output to CDP.
+- Use `ResultBatchUploader` to return ordinary output to CDP.
+- Read `REPORTS.md` before implementing a managed report.

{pam_python-0.1.44 → pam_python-0.2.0}/README.md

@@ -4,11 +4,15 @@ This repository provides the `pam` CLI and runtime framework to build Data Plugi
 
 This README is a practical, step-by-step guide you can follow to create and run a real service.
 
+Current release target: **0.2.0**
+
 **What you get**
 
 - CLI to initialize a project and scaffold services
 - Service lifecycle contract (start, data input, upload, exit)
 - Temp file and SQLite helpers
+- Managed Report Store V2 with typed Table, Metric, and ApexCharts-compatible builders
+- Named `ResultBatchUploader` streams for bounded DataFrame uploads
 - A monitoring loop for service timeouts and periodic cleanup
 
 ---
@@ -31,7 +35,7 @@ This README is a practical, step-by-step guide you can follow to create and run
 
 **Prerequisites**
 
-- Python 3.8+ recommended
+- Python 3.9+
 - `pip` and a working virtual environment
 
 ---
@@ -55,7 +59,8 @@ pip install pam-python
 ---
 
 **Initialize a Project**
-This creates a runnable project with templates (including `AGENT.md`).
+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
@@ -104,7 +109,8 @@ The runtime calls your service in two main phases.
 
 When your service is done:
 
-- Call `self._upload_result(...)` or `self._upload_report(...)`
+- Upload ordinary CDP result rows through `ResultBatchUploader` or `_upload_result(...)`
+- Publish managed reports through `self.reports`; do not build report JSON manually
 - Call `self._exit()` to signal completion
 
 ---
@@ -134,15 +140,47 @@ Recommended usage:
 from pam.result_batch_uploader import ResultBatchUploader
 
 batch_uploader = ResultBatchUploader(self, batch_size=50000)
-batch_uploader.upload(df, "data-name")
+batch_uploader.upload(df, name="main")
 batch_uploader.flush()
 status = batch_uploader.get_status()
 ```
 
 Notes:
 
-- `name` separates different result streams (A/B) to avoid schema conflicts.
-- `flush()` uploads any remaining rows that are below the batch size.
+- `request.runtime_parameters["batch_size"]` overrides the constructor default when valid.
+- `name` separates result streams and enforces one stable column schema per stream.
+- `options` may be passed to `upload(...)` and are forwarded to `_upload_result`.
+- Complete batches upload immediately; `flush()` sends the remaining rows.
+- `get_status()` returns buffered rows, uploaded rows, and uploaded batch counts per stream.
+
+---
+
+**Managed Reports (Report Store V2)**
+
+Managed reports are static facts stored in framework-owned SQLite. Plugin code
+selects a typed builder, writes source-derived `DAY`, `MONTH`, or `NONE` facts, and
+publishes only after the full calculation succeeds.
+
+```python
+fresh = self.request.get_runtime_bool("fresh", default=False)
+store = (
+    self.reports.create("reports.sqlite")
+    if fresh
+    else self.reports.open("reports.sqlite")
+)
+
+# Choose the builder agreed in the customer requirement.
+# See generated REPORTS.md for every supported declaration and write API.
+```
+
+Important rules:
+
+- Use only typed builders documented in `REPORTS.md`; there is no raw-report API.
+- `open()` resumes the remote file or creates it only after an authoritative 404.
+- Network/5xx download failures never create a replacement store.
+- Use `create()` only for a human-requested fresh restart.
+- Delete a partition, write its recalculated facts, then call `store.publish()` once.
+- Low-level `_request_sqlite`/`_upload_sqlite` remain for custom plugin state, not reports.
 
 ---
 
@@ -163,13 +201,29 @@ export SERVER_PORT=8000
 ---
 
 **Testing a Service**
-Run unit tests for a service:
+Run tests through the generated script for your current shell. This keeps the
+active terminal's Python environment and project context instead of launching
+test discovery through the `pam` CLI.
+
+macOS/Linux:
 
 ```bash
-pam test rfm_segment
+./run_unit_test.sh rfm_segment
+```
+
+Windows PowerShell:
+
+```powershell
+.\run_unit_test.ps1 rfm_segment
+```
+
+Windows Command Prompt:
+
+```bat
+run_unit_test.bat rfm_segment
 ```
 
-If you write custom tests, place them in the service folder and name them `test_<service>.py`.
+Place custom tests in the service folder and name them `test_<service>.py`.
 
 ---
 
@@ -192,6 +246,7 @@ After `pam init` and one service:
 .
 ├── main.py
 ├── AGENT.md
+├── REPORTS.md
 ├── Dockerfile
 ├── rfm_segment/
 │   ├── RfmSegmentSvc.py
@@ -217,4 +272,5 @@ After `pam init` and one service:
 - Implement your logic in `functions.py`.
 - Wire it into `on_start` and `on_data_input` in your service class.
 - Use the temp utilities to write intermediate files.
-- Use `_upload_result` to return output to CDP.
+- Use `ResultBatchUploader` to return ordinary output to CDP.
+- Read `REPORTS.md` before implementing a managed report.

pam_python-0.2.0/pam/__init__.py

@@ -0,0 +1,3 @@
+"""PAM Data Plugin framework."""
+
+__version__ = "0.2.0"

pam_python-0.2.0/pam/api.py

@@ -0,0 +1,188 @@
+from pathlib import Path
+import os
+import sqlite3
+import requests
+from pam.models.sqlite_download import SQLiteDownloadResult, SQLiteDownloadStatus
+from pam.utils import log
+
+
+class API:
+    def __init__(self):
+        self.session = requests.Session()  # Use a session for connection reuse
+
+    def http_post(self, url: str, data: dict) -> requests.Response | None:
+        """
+        Sends an HTTP POST request to the specified URL with the given data as JSON.
+
+        :param url: The URL to send the POST request to.
+        :param data: A dictionary to be used as the JSON body of the POST request.
+        :return: The response from the server, or None if an error occurred.
+        """
+        headers = {'Content-Type': 'application/json'}
+        try:
+            response = self.session.post(
+                url, json=data, timeout=30, headers=headers
+            )
+            response.raise_for_status()
+            return response
+        except requests.RequestException as e:
+            log(f"HTTP POST request failed. URL: {url}, Error: {e}")
+            return None
+
+    def http_upload(self, url: str, file_path: str, payload: dict = None) -> requests.Response | None:
+        """
+        Uploads a file to the specified URL with optional form data (payload).
+
+        :param url: The URL to upload the file to.
+        :param file_path: The path to the file to be uploaded.
+        :param payload: Optional dictionary of form fields to include in the request.
+        :return: The response from the server, or None if an error occurred.
+        """
+        if not Path(file_path).is_file():
+            log(f"File does not exist: {file_path}")
+            return None
+
+        try:
+            with open(file_path, 'rb') as file:
+                files = {'file': file}
+                response = self.session.post(
+                    url,
+                    files=files,
+                    data=payload or {},  # optional form data
+                    timeout=300
+                )
+                response.raise_for_status()
+                return response
+        except requests.RequestException as e:
+            log(f"File upload failed. URL: {url}, File: {file_path}, Error: {e}")
+            return None
+
+    def download_sqlite_from_post(self, url: str, data: dict, output_path: str) -> bool:
+        """
+        Sends a POST request with JSON data and expects a SQLite file in response.
+        Saves the response content as a .sqlite file.
+
+        :param url: The URL to send the POST request to.
+        :param data: Dictionary to send as JSON in the body.
+        :param output_path: File path to save the .sqlite file.
+        :return: True if successful, False otherwise.
+        """
+        headers = {'Content-Type': 'application/json'}
+        try:
+            response = self.session.post(
+                url, json=data, timeout=60, headers=headers, stream=True
+            )
+            response.raise_for_status()
+
+            with open(output_path, "wb") as f:
+                for chunk in response.iter_content(chunk_size=1024 * 1024):
+                    if chunk:
+                        f.write(chunk)
+
+            log(f"SQLite file saved to {output_path}")
+            return True
+        except requests.RequestException as e:
+            log(f"Failed to download SQLite. URL: {url}, Error: {e}")
+            return False
+        except IOError as e:
+            log(f"Failed to save SQLite file. Path: {output_path}, Error: {e}")
+            return False
+
+    def download_sqlite_v2_from_post(
+        self, url: str, data: dict, output_path: str
+    ) -> SQLiteDownloadResult:
+        """Download and validate managed report state without hiding failures."""
+        headers = {'Content-Type': 'application/json'}
+        target_path = Path(output_path)
+        partial_path = Path(f"{output_path}.part")
+
+        self.__remove_partial_file(partial_path)
+
+        try:
+            response = self.session.post(
+                url, json=data, timeout=60, headers=headers, stream=True
+            )
+        except requests.RequestException as exc:
+            return SQLiteDownloadResult(
+                status=SQLiteDownloadStatus.FAILED,
+                error_code="NETWORK_ERROR",
+                message=str(exc),
+                retryable=True,
+            )
+
+        if response.status_code == 404:
+            response.close()
+            return SQLiteDownloadResult(
+                status=SQLiteDownloadStatus.NOT_FOUND,
+                http_status=response.status_code,
+                error_code="NOT_FOUND",
+                retryable=False,
+            )
+
+        if response.status_code < 200 or response.status_code >= 300:
+            retryable = response.status_code >= 500 or response.status_code in (408, 429)
+            response.close()
+            return SQLiteDownloadResult(
+                status=SQLiteDownloadStatus.FAILED,
+                http_status=response.status_code,
+                error_code="HTTP_ERROR",
+                message=f"SQLite download failed with HTTP {response.status_code}",
+                retryable=retryable,
+            )
+
+        try:
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            with partial_path.open("wb") as output_file:
+                for chunk in response.iter_content(chunk_size=1024 * 1024):
+                    if chunk:
+                        output_file.write(chunk)
+
+            self.__validate_sqlite(partial_path)
+            os.replace(str(partial_path), str(target_path))
+        except requests.RequestException as exc:
+            self.__remove_partial_file(partial_path)
+            response.close()
+            return SQLiteDownloadResult(
+                status=SQLiteDownloadStatus.FAILED,
+                http_status=response.status_code,
+                error_code="NETWORK_ERROR",
+                message=str(exc),
+                retryable=True,
+            )
+        except (OSError, sqlite3.Error) as exc:
+            self.__remove_partial_file(partial_path)
+            response.close()
+            return SQLiteDownloadResult(
+                status=SQLiteDownloadStatus.FAILED,
+                http_status=response.status_code,
+                error_code="INVALID_SQLITE_OR_LOCAL_IO",
+                message=str(exc),
+                retryable=False,
+            )
+
+        response.close()
+        log(f"Report Store V2 SQLite file saved to {target_path}")
+        return SQLiteDownloadResult(
+            status=SQLiteDownloadStatus.DOWNLOADED,
+            path=target_path,
+            http_status=response.status_code,
+        )
+
+    @staticmethod
+    def __validate_sqlite(path: Path) -> None:
+        sqlite_uri = f"file:{path.resolve()}?mode=ro"
+        with sqlite3.connect(sqlite_uri, uri=True) as connection:
+            result = connection.execute("PRAGMA quick_check").fetchone()
+        if result is None or result[0] != "ok":
+            raise sqlite3.DatabaseError("SQLite quick_check failed")
+
+    @staticmethod
+    def __remove_partial_file(path: Path) -> None:
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+
+    def close(self):
+        """Close the session."""
+        self.session.close()

{pam_python-0.1.44 → pam_python-0.2.0}/pam/cli.py

@@ -1,12 +1,13 @@
 import os
-import sys
 import re
 import shutil
+import sys
 import importlib.resources as resources
 from importlib import metadata
 
-def main():
-    args = sys.argv[1:]
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
     if len(args) == 0:
         print("Usage: pam <command> [args]")
         return
@@ -40,13 +41,14 @@ def to_pascal_case(input_string: str) -> str:
     :return: The string in PascalCase.
     """
     # Split the string into words using non-alphanumeric characters as delimiters
-    words = re.split(r'\W+', input_string)
+    words = re.split(r'[^A-Za-z0-9]+', input_string)
 
     # Capitalize each word and join them
-    pascal_case = ''.join(word.capitalize() for word in words if word)
+    pascal_case = ''.join(word[:1].upper() + word[1:] for word in words if word)
 
     return pascal_case
 
+
 def cpy(src, dest):
     template_dir = resources.files("pam") / "templates"
     src_file = os.path.join(template_dir, src)
@@ -59,6 +61,7 @@ def read_template_text(src: str) -> str:
     with open(src_file, "r", encoding="utf-8") as file:
         return file.read()
 
+
 def replace_template_content(service_name, class_name, file_name):
     file_path = os.path.join(service_name, file_name)
     with open(file_path, 'r+', encoding='utf-8') as file:
@@ -71,9 +74,15 @@ def replace_template_content(service_name, class_name, file_name):
 
 
 def create_service(name):
+    if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", name):
+        raise ValueError(
+            "service_name must start with a letter and contain only letters, "
+            "numbers, and underscores"
+        )
     if os.path.exists(name):
         response = input(
-            f"Service {name} already exists. Do you want to overwrite it? (y/N): ").strip().lower()
+            f"Service {name} already exists. Do you want to overwrite it? (y/N): "
+        ).strip().lower()
         if response == 'y':
             shutil.rmtree(name)
         else:
@@ -83,22 +92,27 @@ def create_service(name):
     os.mkdir(name)
     open(os.path.join(name, "__init__.py"), 'a', encoding='utf-8').close()
 
-    cpy("service/service_class.tmpl",
-        os.path.join(name, to_pascal_case(name)+"Svc.py"))
+    cpy(
+        "service/service_class.tmpl",
+        os.path.join(name, to_pascal_case(name) + "Svc.py"),
+    )
 
     cpy("service/service.yaml", os.path.join(name, "service.yaml"))
     cpy("service/functions.tmpl", os.path.join(name, "functions.py"))
     cpy("service/service.test.tmpl", os.path.join(name, f"test_{name}.py"))
-    
 
-    replace_template_content(name, to_pascal_case(
-        name)+"Svc", to_pascal_case(name)+"Svc.py")
-    replace_template_content(name, to_pascal_case(name)+"Svc", "service.yaml")
+    class_name = to_pascal_case(name) + "Svc"
+    replace_template_content(name, class_name, class_name + ".py")
+    replace_template_content(name, class_name, "service.yaml")
     replace_template_content(
-        name, to_pascal_case(name)+"Svc", f"test_{name}.py")
+        name, class_name, f"test_{name}.py"
+    )
 
     print(f"Service {name} created.")
-    print(f"Run `pam test {name}` to run tests for the service.")
+    print(
+        f"Run the generated run_unit_test script for your shell with `{name}` "
+        "to test the service."
+    )
 
 
 def init_project():
@@ -113,6 +127,7 @@ def init_project():
     cpy("init/run_unit_test.bat", "run_unit_test.bat")
     cpy("init/run_unit_test.ps1", "run_unit_test.ps1")
     cpy("init/AGENT.md", "AGENT.md")
+    cpy("init/REPORTS.md", "REPORTS.md")
 
     requirements_path = "requirements.txt"
     has_requirements = os.path.exists(requirements_path)
@@ -147,7 +162,7 @@ def init_project():
         open("__init__.py", 'a', encoding='utf-8').close()
 
     print("--- Welcome to PAM ---\n")
-    print("To create a new servive run\n`pam new service <service_name>`\n\n")
+    print("To create a new service run\n`pam new service <service_name>`\n\n")
 
 
 def _parse_requirement_name(line: str) -> str:
@@ -167,13 +182,12 @@ def _parse_requirement_name(line: str) -> str:
 
 
 def _get_installed_pam_version() -> str:
-    setup_py = os.path.join(os.path.dirname(os.path.dirname(__file__)), "setup.py")
-    if os.path.exists(setup_py):
-        with open(setup_py, "r", encoding="utf-8") as file:
-            content = file.read()
-        match = re.search(r'version="([^"]+)"', content)
-        if match:
-            return match.group(1)
+    try:
+        from pam import __version__
+
+        return __version__
+    except ImportError:
+        pass
 
     try:
         return metadata.version("pam-python")
@@ -206,3 +220,7 @@ def _merge_requirements(existing_lines, frozen_lines):
             merged.append(line)
             existing_keys.add(key)
     return merged
+
+
+if __name__ == "__main__":
+    main()