pam-python 0.2.12__tar.gz → 0.2.13__tar.gz

{pam_python-0.2.12/pam_python.egg-info → pam_python-0.2.13}/PKG-INFO

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

{pam_python-0.2.12 → pam_python-0.2.13}/pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.12"
+__version__ = "0.2.13"

{pam_python-0.2.12 → pam_python-0.2.13}/pam/cli.py

@@ -21,6 +21,7 @@ COMMON_PROJECT_TEMPLATES = {
     "buildcmd/pamb-base.sh": "pamb-base.sh",
     "init/pylintrc.tmpl": ".pylintrc",
     "init/REPORTS.md": "REPORTS.md",
+    "init/REPORTS-th.md": "REPORTS-th.md",
     "init/AGENT.md": "AGENT.md",
     "init/gitignore.tmpl": ".gitignore",
     "init/dockerignore.tmpl": ".dockerignore",

pam_python-0.2.13/pam/templates/init/REPORTS-th.md

@@ -0,0 +1,744 @@
+# Managed Reports สำหรับนักพัฒนา Data Plugin
+
+คู่มือนี้อธิบายวิธีสร้าง แก้ไข และเผยแพร่ Managed Report ด้วย public Python API
+ของ PAM นักพัฒนาไม่ต้องสร้างตาราง SQLite, renderer payload หรือ report JSON เอง
+ชื่อ class, method, parameter และค่าคงที่ในตัวอย่างคงเป็นภาษาอังกฤษตาม API จริง
+
+Framework รองรับ Report ต่อไปนี้
+
+| กลุ่ม | Report | Public builder |
+|---|---|---|
+| PAM native | Table | `store.table(...)` |
+| PAM native | Metric | `store.metric(...)` |
+| Apex axis | Line | `store.line_chart(...)` |
+| Apex axis | Area | `store.area_chart(...)` |
+| Apex axis | Bar/Column | `store.bar_chart(...)` |
+| Apex non-axis | Pie | `store.pie_chart(...)` |
+| Apex non-axis | Donut | `store.donut_chart(...)` |
+| Apex non-axis | Radial Bar | `store.radial_bar_chart(...)` |
+| Apex axis | Scatter | `store.scatter_chart(...)` |
+| Apex axis | Bubble | `store.bubble_chart(...)` |
+| Apex matrix | Heatmap | `store.heatmap(...)` |
+| Apex financial | Candlestick | `store.candlestick_chart(...)` |
+| Apex statistical | Box Plot | `store.box_plot(...)` |
+| Apex non-axis | Radar | `store.radar_chart(...)` |
+| Apex non-axis | Polar Area | `store.polar_area_chart(...)` |
+| Apex range | Range Bar | `store.range_bar_chart(...)` |
+| Apex range | Range Area | `store.range_area_chart(...)` |
+| Apex hierarchy | Treemap | `store.treemap(...)` |
+
+ไม่มี raw report builder หรือช่องทางสร้าง custom report ด้วย JSON หากลูกค้าต้องการ
+Report ชนิดใหม่ ต้องใช้ Framework รุ่นที่มี typed builder สำหรับ Report นั้น
+
+---
+
+# 1. หลักการสำคัญ
+
+## นักพัฒนาเลือกชนิด Report อย่างชัดเจน
+
+Framework ไม่เดาชนิด Report จากข้อมูล นักพัฒนาต้องเลือกตาม requirement ที่ตกลง
+กับลูกค้า โดยเรียก builder ที่ตรงกับความหมายของข้อมูล
+
+```python
+store.table(...)
+store.metric(...)
+store.line_chart(...)
+store.area_chart(...)
+store.bar_chart(...)
+store.pie_chart(...)
+store.donut_chart(...)
+store.radial_bar_chart(...)
+store.scatter_chart(...)
+store.bubble_chart(...)
+store.heatmap(...)
+store.candlestick_chart(...)
+store.box_plot(...)
+store.radar_chart(...)
+store.polar_area_chart(...)
+store.range_bar_chart(...)
+store.range_area_chart(...)
+store.treemap(...)
+```
+
+## นักพัฒนาไม่ระบุ renderer หรือ schema identifier
+
+ห้ามกำหนดค่าทางเทคนิคเอง เช่น
+
+```python
+renderer="table"
+schema="customer/report-a@1"
+```
+
+Typed builder เป็นเจ้าของ renderer และ contract version รายละเอียดเหล่านี้เป็น
+สัญญาภายในระหว่าง Framework กับ CMS
+
+## ประกาศ Field เพียงครั้งเดียว
+
+ชื่อแสดงผล ชนิดข้อมูล หน่วย และ nullability อยู่ใน Report definition ไม่ต้องส่งซ้ำ
+ในทุก record
+
+```python
+Measure(
+    "amount",
+    label="ยอดขาย",
+    value_type="number",
+    unit="THB",
+)
+
+{"amount": 1250.50}
+```
+
+Typed writer จะแปลง declaration และข้อมูลเป็น managed definition, `dimensions`
+และ `measures` นักพัฒนาห้ามสร้าง `definition_json`, `dimensions_json`,
+`measures_json`, ตาราง SQLite หรือ renderer payload เอง
+
+---
+
+# 2. พฤติกรรม Chart ที่รองรับ
+
+- Column คือ Bar ที่ใช้ `orientation="vertical"`
+- Horizontal Bar คือ Bar ที่ใช้ `orientation="horizontal"`
+- Funnel ในรุ่นนี้เป็นตัวเลือกการแสดงผลของ Bar ไม่ใช่ top-level report type
+- Mixed Chart ต้องมี public contract แยกก่อน Framework จึงจะรองรับ
+- Straight, Smooth และ Stepline เป็นตัวเลือกการแสดงผลของ Line
+- Pie และ Donut เป็นคนละ Apex type แต่ใช้โครงสร้าง slice แบบเดียวกัน
+
+ห้ามประกอบ ApexCharts type อื่นผ่าน raw JSON
+
+---
+
+# 3. วงจรชีวิตของ Report Store
+
+สร้าง Store ใหม่เฉพาะเมื่อผู้ใช้สั่ง fresh restart อย่างชัดเจน กรณีทั่วไปให้เปิด
+Store เดิม หาก remote object ยังไม่มี Framework จะสร้าง Store แรกให้อัตโนมัติ
+
+```python
+fresh = self.request.get_runtime_bool("fresh", default=False)
+
+if fresh:
+    store = self.reports.create(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
+else:
+    store = self.reports.open(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
+```
+
+`tracker_name` คือชื่อ Analytics Tracker group ใน PAM CMS ต้องใช้ชื่อเดิมสำหรับ
+ทุก Report ใน Store หากไม่ระบุ Framework จะใช้ชื่อ Service
+
+ประกาศ Report หลังเปิด Store เพียงครั้งเดียว สะสมข้อมูลจาก input page ได้หลายหน้า
+และเรียก `publish()` ครั้งเดียวหลังคำนวณข้อมูลที่ต้องการครบและสำเร็จ
+
+```python
+def on_start(self):
+    self.report_store = self.reports.open(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
+    self._declare_reports()
+    self._request_data_v2(file_format=RequestFileFormat.PARQUET)
+
+
+def on_data_input(self, req):
+    self._append_page(req.data_input_v2)
+    if not req.data_input_v2.run_complete:
+        self._request_data_v2(
+            page=req.data_input_v2.next,
+            file_format=RequestFileFormat.PARQUET,
+        )
+        return
+
+    self.report_store.publish()
+    self._exit()
+```
+
+การ publish จะ upload SQLite หนึ่งครั้ง และเผยแพร่ pointer ของ Report key ที่มี
+การเปลี่ยนแปลงในรอบนั้น Remote read เป็น eventually consistent; Plugin ไม่ต้องรอ
+หรือ poll จนผู้ใช้อ่าน Report ได้
+
+Task lifecycle จะปิด manager และลบ local working files ให้อัตโนมัติ หากต้องการ
+ทิ้ง Store ที่ยังเปิดก่อนเวลา ให้ใช้
+
+```python
+self.reports.discard_local("reports.sqlite")
+```
+
+คำสั่งนี้ไม่ลบ remote object และจะทิ้ง local change ที่ยังไม่ได้ publish
+
+---
+
+# 4. สัญญาร่วมของ Field
+
+Import ที่ใช้บ่อย:
+
+```python
+from pam.reports import (
+    Dimension,
+    Measure,
+    Sum,
+    TemporalMode,
+    TimeRangeTransform,
+)
+```
+
+## Dimension
+
+Dimension ใช้ระบุ จัดกลุ่ม เรียง หรือแสดงชื่อของ data point
+
+```python
+Dimension("branch", label="สาขา", value_type="string")
+```
+
+## Measure
+
+Measure คือค่าที่คำนวณแล้วและนำไปแสดงหรือ plot
+
+```python
+Measure("amount", label="ยอดขาย", value_type="number", unit="THB")
+```
+
+Field ทุกตัวต้องมี:
+
+| Property | ความหมาย |
+|---|---|
+| `name` | key ที่คงที่และอ่านโดยระบบ แนะนำ `snake_case` |
+| `label` | ชื่อที่ CMS แสดงต่อผู้ใช้ |
+| `value_type` | ชนิดข้อมูลสำหรับ validation และ formatting |
+
+Property เสริม:
+
+| Property | Default | ความหมาย |
+|---|---:|---|
+| `required` | `True` | ทุก row/point ต้องมี field นี้หรือไม่ |
+| `nullable` | `False` | ยอมให้ส่ง `None` อย่างชัดเจนหรือไม่ |
+| `unit` | `None` | หน่วย เช่น `THB`, `people`, `orders`, `%` |
+| `description` | `None` | คำอธิบายสำหรับนักพัฒนา |
+
+ชนิดข้อมูลเริ่มต้น:
+
+- `string`
+- `integer`
+- `number`
+- `boolean`
+- `date` — serialize เป็น `YYYY-MM-DD`
+- `datetime` — เก็บเป็น epoch milliseconds; string input ภายใน PAM ต้องใช้
+  UTC format `YYYY-MM-DD HH:mm:ss`
+
+ยังไม่รองรับ object และ array เป็นชนิด cell/point หากต้องใช้ข้อมูลซับซ้อนต้องเพิ่ม
+Framework และ CMS contract อย่างชัดเจนก่อน
+
+`label="สาขา"` อธิบาย field แต่ไม่ได้แปลค่า `BKK` เป็น `กรุงเทพฯ` หากต้องการทั้ง
+code และชื่อแสดงผล ให้ประกาศคนละ field
+
+```python
+Dimension("branch_code", label="รหัสสาขา", value_type="string")
+Dimension("branch_name", label="สาขา", value_type="string")
+```
+
+---
+
+# 5. Range, Partition และความหมายของข้อมูลข้ามเวลา
+
+หนึ่ง Report มี granularity คงที่เพียงค่าเดียว:
+
+- `DAY`
+- `MONTH`
+- `NONE`
+
+ใช้ `NONE` เมื่อ Report ไม่มี date range ให้ผู้ใช้เลือก `DAY` และ `MONTH` เก็บข้อมูล
+แยกตาม partition โดย partition key ต้องมาจาก business date ในข้อมูล ไม่ใช่เวลา
+ที่ Plugin เริ่มทำงาน
+
+- `DAY` ใช้ `YYYY-MM-DD`
+- `MONTH` ใช้ `YYYY-MM`
+
+การคำนวณ partition เดิมซ้ำต้องแทนที่ข้อมูลทั้ง partition:
+
+```python
+table.delete_partition("2026-08")
+table.append_rows(rows_from_page, partition_key="2026-08")
+table.append_rows(more_rows, partition_key="2026-08")
+
+# Publish หลังคำนวณครบและสำเร็จเท่านั้น
+store.publish()
+```
+
+## เลือกความหมายให้ถูกก่อนกำหนด Temporal Mode
+
+อย่าเลือกจากรูปทรง Chart เพราะ Pie, Bar หรือ Table อาจเก็บข้อมูลคนละความหมายได้
+ให้พิจารณาว่าหนึ่ง partition หมายถึงอะไรในทางธุรกิจ
+
+| ความหมายของหนึ่ง partition | Declaration | สิ่งที่ผู้ใช้ CMS เลือกได้ |
+|---|---|---|
+| ค่าของช่วงเวลานั้นซึ่งรวม เฉลี่ย หาค่าต่ำสุด/สูงสุดได้อย่างมีเหตุผล | `temporal_mode=TemporalMode.AGGREGATE` | Trend, Total, Average, Minimum, Maximum |
+| สถานะทั้งชุด ณ เวลานั้น | `temporal_mode=TemporalMode.SNAPSHOT` | หนึ่งสถานะใน Chart เดิม หรือหลายสถานะเป็นแนวโน้ม |
+| Business บังคับ bucket และ reducer ตายตัว | `range_transform=TimeRangeTransform(...)` | เลือกได้เฉพาะ bucket ที่ developer อนุญาต |
+| ไม่ต้องตีความข้าม partition | ไม่ระบุทั้งคู่ | คงพฤติกรรมเดิมของ Report |
+
+### `AGGREGATE`: ค่าประจำช่วงเวลา
+
+ใช้เมื่อแต่ละ partition เป็นค่าที่เกิดขึ้นในช่วงนั้นและการคำนวณทุกแบบยังมีเหตุผล
+เช่น ยอดขายรายวัน จำนวนคำสั่งซื้อรายเดือน หรือค่าใช้จ่ายแคมเปญรายวัน
+
+```python
+sales = store.line_chart(
+    key="daily-sales",
+    granularity="DAY",
+    values=[Measure("sales_amount", label="ยอดขาย", value_type="number", unit="THB")],
+    temporal_mode=TemporalMode.AGGREGATE,
+)
+```
+
+Plugin ไม่เลือก `TREND`, `SUM`, `MEAN`, `MIN` หรือ `MAX` นักการตลาดเลือกใน CMS
+หนึ่งตัวเลือกจะใช้กับทุก Measure ใน Report และค่าเริ่มต้นคือ `TREND`
+
+อย่าใช้ `AGGREGATE` เพียงเพราะ Measure เป็นตัวเลข เช่น จำนวนสมาชิกปัจจุบันในแต่ละ
+วันเป็นประชากรชุดเดิม การบวกหลายวันจะนับคนเดิมซ้ำ
+
+### `SNAPSHOT`: สถานะทั้งชุด
+
+ใช้เมื่อแต่ละ partition คือสถานะสมบูรณ์ ณ วันหรือเดือนนั้น เช่น สมาชิกปัจจุบันแยก
+VIP/LOYAL/LOST, สินค้าคงคลังรายคลัง หรือการกระจาย tier ลูกค้า
+
+```python
+members = store.pie_chart(
+    key="member-status",
+    granularity="DAY",
+    category=Dimension("status", label="สถานะ", value_type="string"),
+    value=Measure("members", label="สมาชิก", value_type="integer"),
+    temporal_mode=TemporalMode.SNAPSHOT,
+)
+```
+
+หนึ่ง partition แสดงด้วย Chart ที่ประกาศไว้ หลาย partition เรียงตามเวลาและ CMS
+เลือก presentation ตาม temporal policy เช่น Pie หลายวันเปลี่ยนเป็น Stacked Area
+category ที่หายจาก snapshot หนึ่งจะถูกแสดงเป็นศูนย์ หาก zero กับ missing มีความหมาย
+ต่างกัน Plugin ต้องเขียน category ที่ตั้งใจให้เป็นศูนย์ให้ครบ
+
+Snapshot หลายจุดแสดงว่าจำนวนรวมเปลี่ยน แต่พิสูจน์ transition รายบุคคลไม่ได้ เช่น
+ไม่สามารถสรุปว่าใครย้ายจาก LOYAL ไป VIP ได้ Sankey ต้องใช้ source-to-target facts
+ที่ประกาศอย่างชัดเจน
+
+Temporal Mode รองรับ Table, Metric, Line, Area, Bar/Column, Pie, Donut,
+Polar Area และ Radial Bar โดยมีกฎดังนี้
+
+- Granularity ต้องเป็น `DAY` หรือ `MONTH`
+- ต้องมี numeric Measure อย่างน้อยหนึ่งตัว
+- ต้องใช้ `TemporalMode` enum ห้ามส่ง raw string เช่น `"SNAPSHOT"`
+- `temporal_mode` และ `range_transform` ใช้พร้อมกันไม่ได้
+- หนึ่ง Mode ใช้กับทั้ง Report ห้ามรวม Aggregate และ Snapshot Measure ใน Report เดียว
+- partition เดิมต้องถูกลบและเขียนสถานะใหม่ทั้งชุดก่อน publish
+
+### Fixed `range_transform`
+
+ใช้เมื่อ requirement บังคับ reducer และ allowed bucket ตายตัว เช่น KPI ต้องรวมด้วย
+SUM เสมอ หรือ compliance report ต้องเลือกค่ารายวันล่าสุดเสมอ หากต้องการให้นักการตลาด
+สลับ Trend/Total/Average/Minimum/Maximum ให้ใช้ `TemporalMode.AGGREGATE`
+
+```python
+line = store.line_chart(
+    key="sales-trend",
+    granularity="DAY",
+    values=[Measure("sales_amount", label="ยอดขาย", value_type="number")],
+    range_transform=TimeRangeTransform(
+        default_bucket="MONTH",
+        allowed_buckets=["DAY", "WEEK", "MONTH", "YEAR"],
+        reducers={"sales_amount": Sum()},
+    ),
+)
+```
+
+Source granularity และ bucket ที่อนุญาต:
+
+| Source | Allowed buckets |
+|---|---|
+| `DAY` | `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL` |
+| `MONTH` | `MONTH`, `YEAR`, `ALL` |
+| `NONE` | ไม่รองรับ range transform |
+
+Output key:
+
+- `DAY`: `YYYY-MM-DD`
+- `WEEK`: ISO week `YYYY-Www` (จันทร์–อาทิตย์)
+- `MONTH`: `YYYY-MM`
+- `YEAR`: `YYYY`
+- `ALL`: literal `ALL` ซึ่งหมายถึง range ที่ผู้ใช้เลือก ไม่ใช่ทุกวันใน Store
+
+Reducer ที่รองรับ:
+
+| Reducer | ความหมาย |
+|---|---|
+| `SUM` | บวก numeric value ที่มีอยู่ทั้งหมดใน bucket |
+| `MEAN` | ค่าเฉลี่ยเลขคณิต โดยทุก source value มีน้ำหนักเท่ากัน |
+| `MIN` | ค่าต่ำสุด |
+| `MAX` | ค่าสูงสุด |
+| `LAST` | ค่าจาก source partition ล่าสุดตาม canonical partition order |
+
+`MEAN` ไม่ใช่ weighted average หากต้องการ `WEIGHTED_MEAN` หรือ `RATIO_OF_SUMS`
+ต้องเพิ่ม contract ที่ระบุความสัมพันธ์ของ Measure ก่อน
+
+เมื่อไม่ระบุทั้ง `range_transform` และ `temporal_mode` จะคงพฤติกรรมเดิม: Table
+คืน record ที่เลือก, Metric คืน value group ต่อ partition, Line/Area เรียงตาม
+partition และ `NONE` แสดง current snapshot โดยตรง
+
+---
+
+# 6. Table Report
+
+เหมาะกับรายละเอียด Ranking, audit output หรือข้อมูลหลาย column
+
+```python
+table = store.table(
+    key="member-summary",
+    granularity="MONTH",
+    columns=[
+        Dimension("branch", label="สาขา", value_type="string"),
+        Measure("members", label="สมาชิก", value_type="integer", unit="คน"),
+    ],
+)
+
+table.append_rows(
+    [{"branch": "กรุงเทพฯ", "members": 1250}],
+    partition_key="2026-08",
+)
+```
+
+กฎ:
+
+- ไม่รับ column ที่ไม่ได้ประกาศ
+- Required column ต้องมีครบและค่าต้องตรงชนิด
+- Row ใน Report เดียวกันห้ามมี generated identity ซ้ำ
+- CMS ใช้ลำดับ column จาก definition ไม่ใช่ row แรก
+- Partition เป็น metadata สำหรับ range/order ไม่ถูกเพิ่มเป็น Day/Month column พิเศษ
+- `remove_rows` รับเฉพาะ Dimension identity; Measure ไม่ใช่ identity
+
+---
+
+# 7. Metric Report
+
+เหมาะกับ KPI card หรือ headline number ที่ไม่มี Dimension
+
+```python
+metric = store.metric(
+    key="monthly-kpis",
+    granularity="MONTH",
+    metrics=[
+        Measure("revenue", label="รายได้", value_type="number", unit="THB"),
+        Measure("orders", label="คำสั่งซื้อ", value_type="integer"),
+    ],
+)
+
+metric.delete_partition("2026-08")
+metric.set_values(
+    {"revenue": 125000.0, "orders": 320},
+    partition_key="2026-08",
+)
+```
+
+ต้องมี Measure อย่างน้อยหนึ่งตัว ไม่รองรับ Dimension และหนึ่ง partition มี value set
+ได้ชุดเดียว `set_values` ซ้ำใน DAY/MONTH ต้องลบ partition เดิมก่อน ส่วน `NONE`
+จะ replace current value atomically
+
+---
+
+# 8. Line Chart Report
+
+ใช้ partition เป็นแกนเวลา นักพัฒนาไม่ต้องประกาศ x ซ้ำ
+
+```python
+line = store.line_chart(
+    key="daily-sales",
+    granularity="DAY",
+    values=[Measure("amount", label="ยอดขาย", value_type="number")],
+    series=Dimension("branch", label="สาขา", value_type="string"),
+)
+
+line.append_points(
+    [{"branch": "กรุงเทพฯ", "amount": 1250}],
+    partition_key="2026-08-24",
+)
+```
+
+ต้องมี numeric Measure อย่างน้อยหนึ่งตัว `series` ต้องเป็น Dimension และ identity
+คือ partition + optional series CMS เรียงตาม canonical partition ไม่ใช่ insertion order
+
+---
+
+# 9. Area Chart Report
+
+ใช้ contract ของ Line และเพิ่ม `stacked` ซึ่งเป็น presentation metadata ไม่ใช่กฎ
+การคำนวณ business value
+
+```python
+area = store.area_chart(
+    key="member-trend",
+    granularity="DAY",
+    values=[Measure("members", label="สมาชิก", value_type="integer")],
+    series=Dimension("status", label="สถานะ", value_type="string"),
+    stacked=True,
+)
+```
+
+---
+
+# 10. Bar และ Column Chart Report
+
+```python
+bars = store.bar_chart(
+    key="sales-by-channel",
+    granularity="MONTH",
+    category=Dimension("channel", label="ช่องทาง", value_type="string"),
+    values=[Measure("amount", label="ยอดขาย", value_type="number")],
+    series=Dimension("branch", label="สาขา", value_type="string"),
+    orientation="vertical",
+    stacked=False,
+)
+```
+
+ต้องมี category Dimension หนึ่งตัวและ numeric Measure อย่างน้อยหนึ่งตัว `series`
+ต้องเป็น Dimension, `orientation` เป็น `vertical` หรือ `horizontal` และห้ามมี
+category/series identity ซ้ำ Partition เป็น metadata ไม่ถูกเติมหน้าชื่อ category
+
+---
+
+# 11. Pie และ Donut Chart Report
+
+ใช้แสดงส่วนประกอบของ whole หนึ่งชุด ไม่เหมาะกับค่าติดลบ แนวโน้ม หรือ category มาก
+
+```python
+pie = store.pie_chart(
+    key="members-by-status",
+    granularity="DAY",
+    category=Dimension("status", label="สถานะ", value_type="string"),
+    value=Measure("members", label="สมาชิก", value_type="integer"),
+    temporal_mode=TemporalMode.SNAPSHOT,
+)
+
+pie.append_slices(
+    [{"status": "VIP", "members": 100}],
+    partition_key="2026-08-24",
+)
+```
+
+ต้องมี category หนึ่งตัวและ numeric Measure หนึ่งตัว ค่า finite และไม่ติดลบ ห้ามมี
+category ซ้ำ Framework ไม่รวม category เล็กเป็น `Other` เอง Donut ใช้กฎข้อมูล
+เดียวกับ Pie แต่ยังเป็นคนละ public type
+
+---
+
+# 12. Radial Bar Chart Report
+
+ใช้กับ progress, completion หรือ score ที่มีขอบเขต
+
+```python
+radial = store.radial_bar_chart(
+    key="completion",
+    granularity="MONTH",
+    metrics=[Measure("score", label="ความสำเร็จ", value_type="number")],
+    min_value=0,
+    max_value=100,
+)
+```
+
+ต้องมี numeric Measure อย่างน้อยหนึ่งตัว ทุกค่าต้องอยู่ระหว่าง `min_value` และ
+`max_value` และหนึ่ง partition มี value set เดียว Framework เก็บ business value จริง;
+CMS เป็นผู้ normalize เป็นช่วง 0–100 ของ Apex
+
+---
+
+# 13. Scatter Chart Report
+
+```python
+scatter = store.scatter_chart(
+    key="price-volume",
+    granularity="DAY",
+    x=Dimension("price", label="ราคา", value_type="number"),
+    y=Measure("volume", label="ปริมาณ", value_type="number"),
+    series=Dimension("product", label="สินค้า", value_type="string"),
+)
+```
+
+x และ y ต้องเป็น finite number, series เป็น Dimension Partition ใช้ filter source
+facts แต่ไม่ใช่แกน Chart CMS รวม point จาก partition ที่เลือกไว้ใน Scatter เดียว
+และไม่รองรับ `range_transform`
+
+---
+
+# 14. Bubble Chart Report
+
+ใช้กฎ x, y และ series แบบ Scatter และเพิ่ม numeric `size` ที่ finite และไม่ติดลบ
+`size` ไม่ใช่ identity และ selected partitions จะรวม raw bubbles ใน Chart เดียว
+
+```python
+bubble = store.bubble_chart(
+    key="market-bubbles",
+    granularity="DAY",
+    x=Dimension("x", label="X", value_type="number"),
+    y=Measure("y", label="Y", value_type="number"),
+    size=Measure("size", label="ขนาด", value_type="number"),
+)
+```
+
+---
+
+# 15. Heatmap Report
+
+ต้องมี Dimension สองตัวและ numeric Measure หนึ่งตัว x/y coordinate ต้องไม่ซ้ำ
+cell ที่ไม่มีข้อมูลจะยังคง missing ไม่เติมศูนย์ และแต่ละ partition แสดงเป็น grid
+แยกกัน จึงไม่รองรับ `range_transform`
+
+```python
+heatmap = store.heatmap(
+    key="activity",
+    granularity="DAY",
+    x=Dimension("hour", label="ชั่วโมง", value_type="integer"),
+    y=Dimension("weekday", label="วัน", value_type="string"),
+    value=Measure("events", label="เหตุการณ์", value_type="integer"),
+)
+```
+
+---
+
+# 16. Candlestick Chart Report
+
+x ต้องเป็น ordered date/datetime Dimension และมี finite numeric Measure สี่ตัว:
+open, high, low, close โดยต้องเป็นไปตาม `low <= open <= high` และ
+`low <= close <= high` ห้าม x ซ้ำ Selected partitions รวมเป็น Candlestick series
+ที่เรียงแล้ว และ Framework ไม่เดา price reducer
+
+---
+
+# 17. Box Plot Report
+
+ต้องมี category Dimension หนึ่งตัวและ numeric Measure ห้าตัว: minimum, q1, median,
+q3, maximum โดยต้องเป็น `minimum <= q1 <= median <= q3 <= maximum` ห้าม category
+ซ้ำ และแต่ละ partition แสดง Box Plot แยกกัน ไม่ merge distribution ข้าม partition
+
+---
+
+# 18. Radar Chart Report
+
+ต้องมี axis Dimension หนึ่งตัวและ numeric Measure หนึ่งตัว optional series จะแยก
+polygon แต่ละ axis/series ต้องไม่ซ้ำ `axis_order` ใช้กำหนดลำดับและปฏิเสธ axis
+นอก declaration แต่ละ partition แสดง Radar หนึ่งชุดและไม่รองรับ `range_transform`
+
+---
+
+# 19. Polar Area Chart Report
+
+ต้องมี category Dimension หนึ่งตัวและ numeric Measure ที่ไม่ติดลบหนึ่งตัว ห้าม
+category ซ้ำ `NONE` คือ current snapshot หากใช้ fixed range transform สามารถใช้
+`ALL` ได้เมื่อ developer ประกาศ reducer สำหรับ Measure นั้น
+
+---
+
+# 20. Range Bar Chart Report
+
+ต้องมี category, start และ end โดย start/end ต้องเป็นชนิด numeric หรือ datetime
+ชนิดเดียวกัน และ `end >= start` identity ของ category/series/range ห้ามซ้ำ
+
+---
+
+# 21. Range Area Chart Report
+
+ต้องมี ordered x Dimension และ numeric Measure สองตัวคือ lower/upper โดย
+`upper >= lower` แต่ละ x/series ต้องไม่ซ้ำ และ CMS เรียงตาม normalized x
+
+---
+
+# 22. Treemap Report
+
+ต้องมี label Dimension และ factual numeric `value` หนึ่งตัว optional `size` ต้อง
+เป็น numeric Measure ที่ไม่ติดลบ หากไม่ระบุ `size` ค่า `value` จะควบคุมทั้ง geometry
+และค่าที่แสดง optional `group` ต้องเป็น Dimension และ label/group identity ห้ามซ้ำ
+
+```python
+tree = store.treemap(
+    key="sales-by-brand",
+    granularity="DAY",
+    label=Dimension("brand", label="แบรนด์", value_type="string"),
+    value=Measure("sales", label="ยอดขาย", value_type="number"),
+)
+```
+
+หาก `size` เป็น synthetic layout weight CMS ต้องไม่แสดงเสมือนเป็น factual value
+`NONE` Treemap เป็น snapshot ส่วน partitioned Treemap ใช้ fixed `range_transform`
+ตาม declaration ปัจจุบัน Treemap ยังไม่รองรับ temporal mode
+
+---
+
+# 23. กฎร่วมสำหรับการแก้ไขข้อมูล
+
+| Report | เขียนข้อมูล | ลบเฉพาะรายการ |
+|---|---|---|
+| Table | `append_rows` | `remove_rows` |
+| Metric | `set_values` | `delete_partition` หรือ `clear` |
+| Line / Area | `append_points` | `remove_points` |
+| Bar/Column | `append_bars` | `remove_bars` |
+| Pie / Donut | `append_slices` | `remove_slices` |
+| Radial Bar | `set_values` | `delete_partition` หรือ `clear` |
+| Scatter | `append_points` | `remove_points` |
+| Bubble | `append_bubbles` | `remove_bubbles` |
+| Heatmap | `append_cells` | `remove_cells` |
+| Candlestick | `append_candles` | `remove_candles` |
+| Box Plot | `append_distributions` | `remove_distributions` |
+| Radar | `append_points` | `remove_points` |
+| Polar Area | `append_sectors` | `remove_sectors` |
+| Range Bar / Range Area | `append_ranges` | `remove_ranges` |
+| Treemap | `append_nodes` | `remove_nodes` |
+
+ทุก Report รองรับ `delete_partition(partition_key)` สำหรับ DAY/MONTH, write method
+ที่รับ `partition_key` อย่างชัดเจน และ `clear()` เพื่อลบ local records ก่อน publish
+ถ้าคำนวณไม่สำเร็จห้าม publish; remote report จะไม่เปลี่ยน
+
+Identity ที่ส่งให้ `remove_*`:
+
+| Report | Identity fields |
+|---|---|
+| Table | Dimension ทุกตัวที่ประกาศ |
+| Line / Area | optional `series`; หากไม่มีใช้ object ว่าง |
+| Bar/Column | `category` และ optional `series` |
+| Pie / Donut / Polar Area | `category` |
+| Scatter | `x`, `y`, optional `series` |
+| Bubble | `x`, `y`, optional `series`; ไม่รวม `size` |
+| Heatmap | `x`, `y` |
+| Candlestick | `x` |
+| Box Plot | `category` |
+| Radar | `axis`, optional `series` |
+| Range Bar | `category`, optional `series`, `start`, `end` |
+| Range Area | `x`, optional `series` |
+| Treemap | `label`, optional `group` |
+
+Metric และ Radial Bar มี value set เดียวต่อ partition จึง refresh ด้วย
+`delete_partition` แล้วตามด้วย `set_values` สำหรับ `NONE`, `set_values` จะแทนที่
+current snapshot
+
+---
+
+# 24. Validation และการจัดการความล้มเหลว
+
+- Field ที่ไม่ได้ประกาศเป็น error และไม่ถูกละเลย
+- Required field ที่หายเป็น error
+- Boolean ไม่ถูกยอมรับเป็น integer หรือ number
+- ปฏิเสธ `NaN`, positive infinity และ negative infinity
+- Field name เป็น contract key ที่คงที่ เปลี่ยนได้เมื่อเปลี่ยน definition/version โดยตั้งใจ
+- Report key เดิมห้ามเปลี่ยน report type, fields, granularity หรือ presentation options
+- เมื่อคำนวณล้มเหลว ห้ามเรียก `store.publish()`
+- ทุก write batch เป็น transaction; validation failure ต้องไม่ insert เพียงบางส่วน
+- Error ต้องระบุ report key, field, expected type และตำแหน่งค่าที่ผิด โดยไม่ log
+  sensitive dataset ทั้งชุด
+
+---
+
+# 25. Report Type ที่ยังไม่รองรับ
+
+Type นอก compatibility allowlist ถือว่าไม่รองรับ ห้ามเลียนแบบด้วยการเลือก renderer
+หรือสร้าง raw JSON เอง Visual variant เช่น Mixed หรือ Funnel ต้องมี public contract
+ก่อน แม้ ApexCharts ระดับล่างจะวาดได้ก็ตาม
+
+หากลูกค้าต้องการ Report ชนิดใหม่ ให้หยุดและขอ Framework release ที่เพิ่ม typed
+builder นั้น ห้ามเพิ่ม unregistered type ภายใน Plugin เพียงตัวเดียว

{pam_python-0.2.12 → pam_python-0.2.13}/pam/templates/init/REPORTS.md

@@ -591,8 +591,9 @@ table.append_rows([
 - Values must match their declared types.
 - Two rows in the same report cannot have the same generated identity.
 - CMS renders columns from the stored declaration, not from the first row.
-- For `DAY` and `MONTH`, CMS also shows the record partition as a leading Day or
-  Month column. It never merges rows from different partitions implicitly.
+- For `DAY` and `MONTH`, partition remains internal range and ordering metadata.
+  CMS does not add a special Day or Month column, and it never merges rows from
+  different partitions implicitly.
 
 ## Removing selected rows
 

{pam_python-0.2.12 → pam_python-0.2.13/pam_python.egg-info}/PKG-INFO

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

{pam_python-0.2.12 → pam_python-0.2.13}/pam_python.egg-info/SOURCES.txt

@@ -55,6 +55,7 @@ pam/reports/treemap.py
 pam/templates/buildcmd/pamb
 pam/templates/buildcmd/pamb-base.sh
 pam/templates/init/AGENT.md
+pam/templates/init/REPORTS-th.md
 pam/templates/init/REPORTS.md
 pam/templates/init/dockerignore.tmpl
 pam/templates/init/gitignore.tmpl

{pam_python-0.2.12 → pam_python-0.2.13}/tests/test_cli_templates.py

@@ -43,7 +43,13 @@ 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())
+            self.assertTrue((root / "REPORTS-th.md").is_file())
             reports_guide = (root / "REPORTS.md").read_text()
+            thai_reports_guide = (root / "REPORTS-th.md").read_text()
+            self.assertIn("Managed Reports สำหรับนักพัฒนา Data Plugin", thai_reports_guide)
+            self.assertIn("TemporalMode.AGGREGATE", thai_reports_guide)
+            self.assertIn("TemporalMode.SNAPSHOT", thai_reports_guide)
+            self.assertIn("อย่าเลือกจากรูปทรง Chart", thai_reports_guide)
             self.assertIn("TemporalMode.AGGREGATE", reports_guide)
             self.assertIn("TemporalMode.SNAPSHOT", reports_guide)
             self.assertIn(
@@ -196,6 +202,8 @@ class CLITemplateTest(unittest.TestCase):
                 (root / "pyproject.toml").read_text(),
             )
             self.assertTrue((root / "uv.lock").is_file())
+            self.assertTrue((root / "REPORTS.md").is_file())
+            self.assertTrue((root / "REPORTS-th.md").is_file())
             self.assertFalse((root / "requirements.txt").exists())
             self.assertFalse((root / "run_unit_test.sh").exists())
             self.assertIn(