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

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

@@ -1,39 +1,22 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.0
+Version: 0.2.2
 Summary: Pam Python Library
-Home-page: https://github.com/heart/pam-python
-Author: Narongrit Kanhanoi
-Author-email: narongrit@pams.ai
+Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
+Project-URL: Homepage, https://github.com/heart/pam-python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Customer Service
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.9
+Requires-Python: <3.13,>=3.12
 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: dask>=2024.12.1
-Requires-Dist: dask-expr>=1.1.21
 Requires-Dist: requests>=2.32.3
-Requires-Dist: gunicorn>=23.0.0
-Requires-Dist: pyarrow>=19.0.1
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
+Requires-Dist: PyYAML>=6.0.2
 Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 # pam-python-data-plugin-framework
 
@@ -41,8 +24,6 @@ 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
@@ -72,54 +53,54 @@ Current release target: **0.2.0**
 
 **Prerequisites**
 
-- Python 3.9+
-- `pip` and a working virtual environment
+- Python 3.12
+- `uv` (recommended) or `pip`
 
 ---
 
-**Install**
-Create a project folder and a virtual environment.
+**Create a uv project**
+
+Install PAM inside each project instead of installing the CLI globally:
 
 ```bash
 mkdir my_data_plugin
 cd my_data_plugin
-python3 -m venv venv
-source venv/bin/activate
+uv init --python 3.12
+uv add pam-python
+uv run pam init
 ```
 
-Install the framework:
+`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.
 
-```bash
-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.
+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
 pam init
 ```
 
-When `requirements.txt` already exists, you will be prompted to choose how to proceed:
-
-- overwrite
-- keep
-- merge
-
-`pam init` now writes a project baseline `requirements.txt`. It pins `pam-python` to the scaffold version and includes core runtime/test dependencies used by the generated project. It does not copy the current machine's `pip freeze`.
+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**
-Generate a service scaffold. Do not hand-create service templates.
 
 ```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
+lazy Parquet processing. Pandas services also receive Parquet and install
+`pandas` plus `pyarrow`. The selected direct dependencies are added to the
+project automatically.
+
 This creates a new folder (e.g. `rfm_segment/`) with:
 
 - a service class (`RfmSegmentSvc.py`)
@@ -141,7 +122,8 @@ The runtime calls your service in two main phases.
 2. `on_data_input`
 
 - Called when CDP sends input files
-- `req.input_files` contains ordered CSV files
+- `req.input_files` contains ordered Parquet files
+- `req.file_format` is the typed format sent by PAM
 - Should also return quickly (use a thread if needed)
 
 When your service is done:
@@ -169,7 +151,11 @@ Notes:
 ---
 
 **Uploading Results in Batches**
-If your service produces too many rows (or too few per event), use the batch uploader to handle chunking and flushing automatically.
+Polars templates pass `LazyFrame` results directly to `_upload_result(...)`, which
+streams them to the CSV upload boundary. Do not collect or convert to Pandas first.
+
+For eager Polars or Pandas DataFrames, use the batch uploader to handle chunking
+and flushing automatically.
 
 Recommended usage:
 
@@ -189,6 +175,7 @@ Notes:
 - `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.
+- `ResultBatchUploader` intentionally rejects Polars `LazyFrame`; upload it directly.
 
 ---
 
@@ -225,7 +212,8 @@ Important rules:
 The generated `main.py` runs the Flask server.
 
 ```bash
-python main.py
+uv run python main.py  # uv project
+python main.py         # pip project
 ```
 
 By default it binds to `0.0.0.0:8000`. You can override with:
@@ -238,9 +226,13 @@ export SERVER_PORT=8000
 ---
 
 **Testing 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.
+For uv projects, use one cross-platform command:
+
+```bash
+uv run python -m unittest discover -s rfm_segment -p "test_*.py"
+```
+
+Pip projects include shell-specific scripts:
 
 macOS/Linux:
 
@@ -285,20 +277,23 @@ After `pam init` and one service:
 ├── AGENT.md
 ├── REPORTS.md
 ├── Dockerfile
+├── pyproject.toml
+├── uv.lock
+├── .python-version
 ├── rfm_segment/
 │   ├── RfmSegmentSvc.py
 │   ├── functions.py
 │   ├── service.yaml
 │   └── test_rfm_segment.py
-├── requirements.txt
-└── run_unit_test.sh
+└── .pam-project
 ```
 
 ---
 
 **Troubleshooting**
 
-- If `pam` command is missing, ensure your virtualenv is activated.
+- If `pam` is missing, verify the uv tool installation or activate the pip virtualenv.
+- If uv initialization fails, verify `uv` is on `PATH` and package indexes are reachable.
 - If `pam new service` fails, confirm the service name is provided.
 - If temp cleanup is too frequent or too slow, adjust `TEMP_CLEAN_INTERVAL_HOURS` and `TEMP_CLEAN_DAYS`.
 
@@ -309,5 +304,6 @@ 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 `ResultBatchUploader` to return ordinary output to CDP.
+- Keep Polars transformations lazy and upload the resulting `LazyFrame` directly.
+- Use `ResultBatchUploader` only for eager Polars/Pandas frames that need row batching.
 - Read `REPORTS.md` before implementing a managed report.

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

@@ -4,8 +4,6 @@ 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
@@ -35,54 +33,54 @@ Current release target: **0.2.0**
 
 **Prerequisites**
 
-- Python 3.9+
-- `pip` and a working virtual environment
+- Python 3.12
+- `uv` (recommended) or `pip`
 
 ---
 
-**Install**
-Create a project folder and a virtual environment.
+**Create a uv project**
+
+Install PAM inside each project instead of installing the CLI globally:
 
 ```bash
 mkdir my_data_plugin
 cd my_data_plugin
-python3 -m venv venv
-source venv/bin/activate
+uv init --python 3.12
+uv add pam-python
+uv run pam init
 ```
 
-Install the framework:
+`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.
 
-```bash
-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.
+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
 pam init
 ```
 
-When `requirements.txt` already exists, you will be prompted to choose how to proceed:
-
-- overwrite
-- keep
-- merge
-
-`pam init` now writes a project baseline `requirements.txt`. It pins `pam-python` to the scaffold version and includes core runtime/test dependencies used by the generated project. It does not copy the current machine's `pip freeze`.
+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**
-Generate a service scaffold. Do not hand-create service templates.
 
 ```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
+lazy Parquet processing. Pandas services also receive Parquet and install
+`pandas` plus `pyarrow`. The selected direct dependencies are added to the
+project automatically.
+
 This creates a new folder (e.g. `rfm_segment/`) with:
 
 - a service class (`RfmSegmentSvc.py`)
@@ -104,7 +102,8 @@ The runtime calls your service in two main phases.
 2. `on_data_input`
 
 - Called when CDP sends input files
-- `req.input_files` contains ordered CSV files
+- `req.input_files` contains ordered Parquet files
+- `req.file_format` is the typed format sent by PAM
 - Should also return quickly (use a thread if needed)
 
 When your service is done:
@@ -132,7 +131,11 @@ Notes:
 ---
 
 **Uploading Results in Batches**
-If your service produces too many rows (or too few per event), use the batch uploader to handle chunking and flushing automatically.
+Polars templates pass `LazyFrame` results directly to `_upload_result(...)`, which
+streams them to the CSV upload boundary. Do not collect or convert to Pandas first.
+
+For eager Polars or Pandas DataFrames, use the batch uploader to handle chunking
+and flushing automatically.
 
 Recommended usage:
 
@@ -152,6 +155,7 @@ Notes:
 - `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.
+- `ResultBatchUploader` intentionally rejects Polars `LazyFrame`; upload it directly.
 
 ---
 
@@ -188,7 +192,8 @@ Important rules:
 The generated `main.py` runs the Flask server.
 
 ```bash
-python main.py
+uv run python main.py  # uv project
+python main.py         # pip project
 ```
 
 By default it binds to `0.0.0.0:8000`. You can override with:
@@ -201,9 +206,13 @@ export SERVER_PORT=8000
 ---
 
 **Testing 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.
+For uv projects, use one cross-platform command:
+
+```bash
+uv run python -m unittest discover -s rfm_segment -p "test_*.py"
+```
+
+Pip projects include shell-specific scripts:
 
 macOS/Linux:
 
@@ -248,20 +257,23 @@ After `pam init` and one service:
 ├── AGENT.md
 ├── REPORTS.md
 ├── Dockerfile
+├── pyproject.toml
+├── uv.lock
+├── .python-version
 ├── rfm_segment/
 │   ├── RfmSegmentSvc.py
 │   ├── functions.py
 │   ├── service.yaml
 │   └── test_rfm_segment.py
-├── requirements.txt
-└── run_unit_test.sh
+└── .pam-project
 ```
 
 ---
 
 **Troubleshooting**
 
-- If `pam` command is missing, ensure your virtualenv is activated.
+- If `pam` is missing, verify the uv tool installation or activate the pip virtualenv.
+- If uv initialization fails, verify `uv` is on `PATH` and package indexes are reachable.
 - If `pam new service` fails, confirm the service name is provided.
 - If temp cleanup is too frequent or too slow, adjust `TEMP_CLEAN_INTERVAL_HOURS` and `TEMP_CLEAN_DAYS`.
 
@@ -272,5 +284,6 @@ 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 `ResultBatchUploader` to return ordinary output to CDP.
+- Keep Polars transformations lazy and upload the resulting `LazyFrame` directly.
+- Use `ResultBatchUploader` only for eager Polars/Pandas frames that need row batching.
 - Read `REPORTS.md` before implementing a managed report.

{pam_python-0.2.0 → pam_python-0.2.2}/pam/__init__.py

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