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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.13
+Version: 0.2.15
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -134,8 +134,9 @@ See [Data Plugin Input V2](docs/data-plugin-input-v2.md).
 
 New Pandas and Polars service projects are generated on the V2 lane by default;
 legacy source can continue using V1 unchanged. For materialized Pandas frames,
-use `data.read_population_pandas()` and
-`data.dataset_at(position).read_pandas()`.
+use `data.read_population_pandas()` and either
+`data.dataset_at(position).read_pandas()` or
+`data.dataset_named(name).read_pandas()`.
 
 When your service is done:
 

{pam_python-0.2.13 → pam_python-0.2.15}/README.md

@@ -114,8 +114,9 @@ See [Data Plugin Input V2](docs/data-plugin-input-v2.md).
 
 New Pandas and Polars service projects are generated on the V2 lane by default;
 legacy source can continue using V1 unchanged. For materialized Pandas frames,
-use `data.read_population_pandas()` and
-`data.dataset_at(position).read_pandas()`.
+use `data.read_population_pandas()` and either
+`data.dataset_at(position).read_pandas()` or
+`data.dataset_named(name).read_pandas()`.
 
 When your service is done:
 

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

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

{pam_python-0.2.13 → pam_python-0.2.15}/pam/models/data_input_v2.py

@@ -142,6 +142,15 @@ class DataInputV2:
             raise IndexError(f"V2 dataset position is out of range: {position}")
         return self.datasets[position]
 
+    def dataset_named(self, name: str) -> DataInputV2Dataset:
+        """Bind one configured dataset by an unambiguous manifest name."""
+        matches = [dataset for dataset in self.datasets if dataset.name == name]
+        if not matches:
+            raise KeyError(f"V2 dataset name is unknown: {name}")
+        if len(matches) > 1:
+            raise ValueError(f"V2 dataset name is ambiguous: {name}")
+        return matches[0]
+
 
 def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
     files_by_name = _validate_flat_input_files(input_files)
@@ -202,6 +211,7 @@ def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
         if position in positions:
             raise ValueError("V2 dataset position is duplicated")
         positions.add(position)
+        dataset_name = _required_string(raw_dataset, "name")
         dataset_format = _required_format(raw_dataset, "format")
         raw_parts = raw_dataset.get("parts")
         if not isinstance(raw_parts, list):
@@ -226,7 +236,7 @@ def parse_data_input_v2(input_files: list[str]) -> DataInputV2:
         datasets.append(
             DataInputV2Dataset(
                 position=position,
-                name=_required_string(raw_dataset, "name"),
+                name=dataset_name,
                 type=_required_string(raw_dataset, "type"),
                 format=dataset_format,
                 row_count=row_count,

{pam_python-0.2.13 → pam_python-0.2.15}/pam/reports/axis.py

@@ -1,6 +1,6 @@
-"""Shared declarations for partition-axis reports."""
+"""Shared declarations for reports with ordered axes."""
 
-from typing import Iterable, Optional, Tuple
+from typing import Any, Iterable, Optional, Tuple
 
 from pam.reports.errors import ReportStoreValidationError
 from pam.reports.fields import Dimension, Measure
@@ -9,6 +9,32 @@ from pam.reports.fields import Dimension, Measure
 NUMERIC_TYPES = {"integer", "number"}
 
 
+def normalize_value_order(
+    report_name: str,
+    option_name: str,
+    dimension: Dimension,
+    values: Optional[Iterable[Any]],
+) -> Optional[Tuple[Any, ...]]:
+    """Normalize an optional complete order for a categorical dimension."""
+    if values is None:
+        return None
+    if isinstance(values, (str, bytes)):
+        raise ReportStoreValidationError(
+            f"{report_name} {option_name} must be an iterable of values"
+        )
+    try:
+        normalized = tuple(dimension.normalize_value(value) for value in values)
+    except TypeError as exc:
+        raise ReportStoreValidationError(
+            f"{report_name} {option_name} must be an iterable of values"
+        ) from exc
+    if not normalized or len(normalized) != len(set(normalized)):
+        raise ReportStoreValidationError(
+            f"{report_name} {option_name} must be non-empty and unique"
+        )
+    return normalized
+
+
 def normalize_partition_series_declaration(
     report_name: str,
     values: Iterable[Measure],

{pam_python-0.2.13 → pam_python-0.2.15}/pam/reports/bar.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Iterable, Mapping, Optional, Sequence
 
-from pam.reports.axis import NUMERIC_TYPES
+from pam.reports.axis import NUMERIC_TYPES, normalize_value_order
 from pam.reports.collection import TypedCollectionReport
 from pam.reports.definition import ReportDefinition
 from pam.reports.errors import ReportStoreValidationError
@@ -29,21 +29,36 @@ class BarChartReport(TypedCollectionReport):
         series: Optional[Dimension],
         orientation: str,
         stacked: bool,
+        category_order: Optional[Sequence[Any]],
+        series_order: Optional[Sequence[Any]],
     ):
         fields = (category,) + ((series,) if series is not None else ()) + tuple(values)
         identity_fields = (category,) + ((series,) if series is not None else ())
+        def validate_order(item: Mapping[str, Any], _index: int) -> None:
+            if category_order is not None and item[category.name] not in category_order:
+                raise ReportStoreValidationError(
+                    f"Bar Chart category value '{item[category.name]}' is not declared in category_order"
+                )
+            if series_order is not None and item[series.name] not in series_order:
+                raise ReportStoreValidationError(
+                    f"Bar Chart series value '{item[series.name]}' is not declared in series_order"
+                )
+
         super().__init__(
             report=report,
             granularity=granularity,
             fields=fields,
             identity_fields=identity_fields,
             item_name="bar",
+            item_validator=validate_order,
         )
         self.category = category
         self.values = tuple(values)
         self.series = series
         self.orientation = orientation
         self.stacked = stacked
+        self.category_order = category_order
+        self.series_order = series_order
 
     @classmethod
     def declare(
@@ -58,6 +73,8 @@ class BarChartReport(TypedCollectionReport):
         stacked: bool = False,
         range_transform: Optional[TimeRangeTransform] = None,
         temporal_mode: Optional[TemporalMode] = None,
+        category_order: Optional[Iterable[Any]] = None,
+        series_order: Optional[Iterable[Any]] = None,
     ):
         if not isinstance(category, Dimension):
             raise ReportStoreValidationError(
@@ -107,6 +124,18 @@ class BarChartReport(TypedCollectionReport):
             )
         if not isinstance(stacked, bool):
             raise ReportStoreValidationError("Bar Chart stacked must be boolean")
+        normalized_category_order = normalize_value_order(
+            "Bar Chart", "category_order", category, category_order
+        )
+        if series_order is not None and series is None:
+            raise ReportStoreValidationError(
+                "Bar Chart series_order requires a series Dimension"
+            )
+        normalized_series_order = (
+            normalize_value_order("Bar Chart", "series_order", series, series_order)
+            if series is not None
+            else None
+        )
 
         fields = (category,) + ((series,) if series is not None else ()) + normalized_values
         normalized_range_transform = normalize_range_transform(
@@ -119,6 +148,11 @@ class BarChartReport(TypedCollectionReport):
             "Bar Chart",
             range_transform,
         )
+        options = {"orientation": orientation, "stacked": stacked}
+        if normalized_category_order is not None:
+            options["category_order"] = list(normalized_category_order)
+        if normalized_series_order is not None:
+            options["series_order"] = list(normalized_series_order)
         definition = ReportDefinition.create(
             report_type="bar",
             contract_version=BAR_CONTRACT_VERSION,
@@ -128,7 +162,7 @@ class BarChartReport(TypedCollectionReport):
                 "series": series.name if series is not None else None,
                 "values": [value.name for value in normalized_values],
             },
-            options={"orientation": orientation, "stacked": stacked},
+            options=options,
             range_transform=normalized_range_transform,
             temporal_mode=normalized_temporal_mode,
         )
@@ -147,6 +181,8 @@ class BarChartReport(TypedCollectionReport):
             series,
             orientation,
             stacked,
+            normalized_category_order,
+            normalized_series_order,
         )
 
     def append_bars(

{pam_python-0.2.13 → pam_python-0.2.15}/pam/reports/box_plot.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Iterable, Mapping, Optional
 
-from pam.reports.axis import NUMERIC_TYPES
+from pam.reports.axis import NUMERIC_TYPES, normalize_value_order
 from pam.reports.collection import TypedCollectionReport
 from pam.reports.definition import ReportDefinition
 from pam.reports.errors import ReportStoreValidationError
@@ -27,6 +27,7 @@ class BoxPlotReport(TypedCollectionReport):
         median: Measure,
         q3: Measure,
         maximum: Measure,
+        category_order: Optional[Iterable[Any]],
     ):
         values = (minimum, q1, median, q3, maximum)
         fields = (category,) + values
@@ -37,6 +38,10 @@ class BoxPlotReport(TypedCollectionReport):
                 raise ReportStoreValidationError(
                     f"Box Plot distribution {index} must satisfy minimum <= q1 <= median <= q3 <= maximum"
                 )
+            if category_order is not None and item[category.name] not in category_order:
+                raise ReportStoreValidationError(
+                    f"Box Plot category value '{item[category.name]}' is not declared in category_order"
+                )
 
         super().__init__(
             report=report,
@@ -52,6 +57,7 @@ class BoxPlotReport(TypedCollectionReport):
         self.median = median
         self.q3 = q3
         self.maximum = maximum
+        self.category_order = category_order
 
     @classmethod
     def declare(
@@ -65,6 +71,7 @@ class BoxPlotReport(TypedCollectionReport):
         median: Measure,
         q3: Measure,
         maximum: Measure,
+        category_order: Optional[Iterable[Any]] = None,
     ):
         if not isinstance(category, Dimension) or not category.required or category.nullable:
             raise ReportStoreValidationError(
@@ -85,7 +92,13 @@ class BoxPlotReport(TypedCollectionReport):
         names = [field.name for field in fields]
         if len(names) != len(set(names)):
             raise ReportStoreValidationError("Box Plot fields must use different names")
+        normalized_category_order = normalize_value_order(
+            "Box Plot", "category_order", category, category_order
+        )
 
+        options = {}
+        if normalized_category_order is not None:
+            options["category_order"] = list(normalized_category_order)
         definition = ReportDefinition.create(
             report_type="box_plot",
             contract_version=BOX_PLOT_CONTRACT_VERSION,
@@ -98,11 +111,15 @@ class BoxPlotReport(TypedCollectionReport):
                 "q3": q3.name,
                 "maximum": maximum.name,
             },
+            options=options,
         )
         report = store._declare_typed_report(
             key, BOX_PLOT_RENDERER, BOX_PLOT_SCHEMA, granularity, definition.to_json()
         )
-        return cls(report, granularity, category, minimum, q1, median, q3, maximum)
+        return cls(
+            report, granularity, category, minimum, q1, median, q3, maximum,
+            normalized_category_order,
+        )
 
     def append_distributions(
         self,

{pam_python-0.2.13 → pam_python-0.2.15}/pam/reports/heatmap.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Iterable, Mapping, Optional
 
-from pam.reports.axis import NUMERIC_TYPES
+from pam.reports.axis import NUMERIC_TYPES, normalize_value_order
 from pam.reports.collection import TypedCollectionReport
 from pam.reports.definition import ReportDefinition
 from pam.reports.errors import ReportStoreValidationError
@@ -22,17 +22,32 @@ class HeatmapReport(TypedCollectionReport):
         x: Dimension,
         y: Dimension,
         value: Measure,
+        x_order: Optional[Iterable[Any]],
+        y_order: Optional[Iterable[Any]],
     ):
+        def validate_order(item: Mapping[str, Any], _index: int) -> None:
+            if x_order is not None and item[x.name] not in x_order:
+                raise ReportStoreValidationError(
+                    f"Heatmap x value '{item[x.name]}' is not declared in x_order"
+                )
+            if y_order is not None and item[y.name] not in y_order:
+                raise ReportStoreValidationError(
+                    f"Heatmap y value '{item[y.name]}' is not declared in y_order"
+                )
+
         super().__init__(
             report=report,
             granularity=granularity,
             fields=(x, y, value),
             identity_fields=(x, y),
             item_name="cell",
+            item_validator=validate_order,
         )
         self.x = x
         self.y = y
         self.value = value
+        self.x_order = x_order
+        self.y_order = y_order
 
     @classmethod
     def declare(
@@ -43,6 +58,8 @@ class HeatmapReport(TypedCollectionReport):
         x: Dimension,
         y: Dimension,
         value: Measure,
+        x_order: Optional[Iterable[Any]] = None,
+        y_order: Optional[Iterable[Any]] = None,
     ):
         for name, field in (("x", x), ("y", y)):
             if not isinstance(field, Dimension):
@@ -61,17 +78,32 @@ class HeatmapReport(TypedCollectionReport):
             raise ReportStoreValidationError("Heatmap value must be required and non-nullable")
         if len({x.name, y.name, value.name}) != 3:
             raise ReportStoreValidationError("Heatmap fields must use different names")
+        normalized_x_order = normalize_value_order(
+            "Heatmap", "x_order", x, x_order
+        )
+        normalized_y_order = normalize_value_order(
+            "Heatmap", "y_order", y, y_order
+        )
 
+        options = {}
+        if normalized_x_order is not None:
+            options["x_order"] = list(normalized_x_order)
+        if normalized_y_order is not None:
+            options["y_order"] = list(normalized_y_order)
         definition = ReportDefinition.create(
             report_type="heatmap",
             contract_version=HEATMAP_CONTRACT_VERSION,
             fields=(x, y, value),
             binding={"x": x.name, "y": y.name, "value": value.name},
+            options=options,
         )
         report = store._declare_typed_report(
             key, HEATMAP_RENDERER, HEATMAP_SCHEMA, granularity, definition.to_json()
         )
-        return cls(report, granularity, x, y, value)
+        return cls(
+            report, granularity, x, y, value,
+            normalized_x_order, normalized_y_order,
+        )
 
     def append_cells(
         self,

{pam_python-0.2.13 → pam_python-0.2.15}/pam/reports/range_bar.py

@@ -2,6 +2,7 @@
 
 from typing import Any, Iterable, Mapping, Optional
 
+from pam.reports.axis import normalize_value_order
 from pam.reports.collection import TypedCollectionReport
 from pam.reports.definition import ReportDefinition
 from pam.reports.errors import ReportStoreValidationError
@@ -25,6 +26,8 @@ class RangeBarChartReport(TypedCollectionReport):
         start: Measure,
         end: Measure,
         series: Optional[Dimension],
+        category_order: Optional[Iterable[Any]],
+        series_order: Optional[Iterable[Any]],
     ):
         fields = (category,) + ((series,) if series is not None else ()) + (start, end)
         identity_fields = (
@@ -36,6 +39,14 @@ class RangeBarChartReport(TypedCollectionReport):
                 raise ReportStoreValidationError(
                     f"Range Bar range {index} field '{end.name}' must be greater than or equal to '{start.name}'"
                 )
+            if category_order is not None and item[category.name] not in category_order:
+                raise ReportStoreValidationError(
+                    f"Range Bar category value '{item[category.name]}' is not declared in category_order"
+                )
+            if series_order is not None and item[series.name] not in series_order:
+                raise ReportStoreValidationError(
+                    f"Range Bar series value '{item[series.name]}' is not declared in series_order"
+                )
 
         super().__init__(
             report=report,
@@ -49,6 +60,8 @@ class RangeBarChartReport(TypedCollectionReport):
         self.start = start
         self.end = end
         self.series = series
+        self.category_order = category_order
+        self.series_order = series_order
 
     @classmethod
     def declare(
@@ -60,6 +73,8 @@ class RangeBarChartReport(TypedCollectionReport):
         start: Measure,
         end: Measure,
         series: Optional[Dimension] = None,
+        category_order: Optional[Iterable[Any]] = None,
+        series_order: Optional[Iterable[Any]] = None,
     ):
         if not isinstance(category, Dimension) or not category.required or category.nullable:
             raise ReportStoreValidationError(
@@ -89,7 +104,24 @@ class RangeBarChartReport(TypedCollectionReport):
         names = [field.name for field in fields]
         if len(names) != len(set(names)):
             raise ReportStoreValidationError("Range Bar fields must use different names")
+        normalized_category_order = normalize_value_order(
+            "Range Bar", "category_order", category, category_order
+        )
+        if series_order is not None and series is None:
+            raise ReportStoreValidationError(
+                "Range Bar series_order requires a series Dimension"
+            )
+        normalized_series_order = (
+            normalize_value_order("Range Bar", "series_order", series, series_order)
+            if series is not None
+            else None
+        )
 
+        options = {}
+        if normalized_category_order is not None:
+            options["category_order"] = list(normalized_category_order)
+        if normalized_series_order is not None:
+            options["series_order"] = list(normalized_series_order)
         definition = ReportDefinition.create(
             report_type="range_bar",
             contract_version=RANGE_BAR_CONTRACT_VERSION,
@@ -100,11 +132,15 @@ class RangeBarChartReport(TypedCollectionReport):
                 "end": end.name,
                 "series": series.name if series is not None else None,
             },
+            options=options,
         )
         report = store._declare_typed_report(
             key, RANGE_BAR_RENDERER, RANGE_BAR_SCHEMA, granularity, definition.to_json()
         )
-        return cls(report, granularity, category, start, end, series)
+        return cls(
+            report, granularity, category, start, end, series,
+            normalized_category_order, normalized_series_order,
+        )
 
     def append_ranges(
         self,

{pam_python-0.2.13 → pam_python-0.2.15}/pam/reports/store.py

@@ -221,6 +221,8 @@ class ReportStore:
         stacked: bool = False,
         range_transform: Optional[TimeRangeTransform] = None,
         temporal_mode: Optional[TemporalMode] = None,
+        category_order: Optional[Iterable[Any]] = None,
+        series_order: Optional[Iterable[Any]] = None,
     ) -> BarChartReport:
         """Declare a typed Bar/Column Chart report."""
         return BarChartReport.declare(
@@ -234,6 +236,8 @@ class ReportStore:
             stacked,
             range_transform,
             temporal_mode,
+            category_order,
+            series_order,
         )
 
     def pie_chart(
@@ -355,6 +359,7 @@ class ReportStore:
         median: Measure,
         q3: Measure,
         maximum: Measure,
+        category_order: Optional[Iterable[Any]] = None,
     ) -> BoxPlotReport:
         """Declare a typed Box Plot report."""
         return BoxPlotReport.declare(
@@ -367,6 +372,7 @@ class ReportStore:
             median,
             q3,
             maximum,
+            category_order,
         )
 
     def heatmap(
@@ -376,9 +382,13 @@ class ReportStore:
         x: Dimension,
         y: Dimension,
         value: Measure,
+        x_order: Optional[Iterable[Any]] = None,
+        y_order: Optional[Iterable[Any]] = None,
     ) -> HeatmapReport:
         """Declare a typed Heatmap report."""
-        return HeatmapReport.declare(self, key, granularity, x, y, value)
+        return HeatmapReport.declare(
+            self, key, granularity, x, y, value, x_order, y_order
+        )
 
     def radar_chart(
         self,
@@ -402,10 +412,13 @@ class ReportStore:
         start: Measure,
         end: Measure,
         series: Optional[Dimension] = None,
+        category_order: Optional[Iterable[Any]] = None,
+        series_order: Optional[Iterable[Any]] = None,
     ) -> RangeBarChartReport:
         """Declare a typed Range Bar Chart report."""
         return RangeBarChartReport.declare(
-            self, key, granularity, category, start, end, series
+            self, key, granularity, category, start, end, series,
+            category_order, series_order,
         )
 
     def range_area_chart(

{pam_python-0.2.13 → pam_python-0.2.15}/pam/templates/init/AGENT.md

@@ -215,15 +215,16 @@ V2 is a separate, explicit lane. Call `_request_data_v2(...)` with CSV or
 Parquet when the PAM adapter is configured for V2. The requested format applies
 to that page and may change on a later request. In `on_data_input`, require
 `req.data_input_v2`, validate the expected dataset count, and bind each dataset
-by its configured position:
+by an unambiguous manifest name (or by its configured position when names are
+not unique or the contract requires positional binding):
 
 ```python
 data = req.data_input_v2
 if data is None or len(data.datasets) != 2:
     raise ValueError("Expected V2 profile and purchase datasets")
 
-profile = data.dataset_at(0)
-purchase = data.dataset_at(1)
+profile = data.dataset_named("profile")
+purchase = data.dataset_named("purchase")
 
 population = data.scan_population_polars()
 profile_frame = profile.scan_polars()

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

@@ -496,12 +496,16 @@ bars = store.bar_chart(
     series=Dimension("branch", label="สาขา", value_type="string"),
     orientation="vertical",
     stacked=False,
+    category_order=["Online", "Store"],
+    series_order=["Bangkok", "Chiang Mai"],
 )
 ```
 
 ต้องมี category Dimension หนึ่งตัวและ numeric Measure อย่างน้อยหนึ่งตัว `series`
 ต้องเป็น Dimension, `orientation` เป็น `vertical` หรือ `horizontal` และห้ามมี
 category/series identity ซ้ำ Partition เป็น metadata ไม่ถูกเติมหน้าชื่อ category
+กำหนดลำดับเองได้ด้วย `category_order` และ `series_order` โดยรายการที่ระบุถือเป็น
+รายการค่าที่อนุญาตทั้งหมด หากไม่กำหนด CMS จะเรียง label แบบ ascending ตามเดิม
 
 ---
 
@@ -598,9 +602,13 @@ heatmap = store.heatmap(
     x=Dimension("hour", label="ชั่วโมง", value_type="integer"),
     y=Dimension("weekday", label="วัน", value_type="string"),
     value=Measure("events", label="เหตุการณ์", value_type="integer"),
+    x_order=[9, 10],
+    y_order=["Monday", "Tuesday"],
 )
 ```
 
+`x_order` และ `y_order` ใช้กำหนดลำดับแกน โดยค่าที่เขียนต้องอยู่ในรายการที่ประกาศ
+
 ---
 
 # 16. Candlestick Chart Report
@@ -617,6 +625,7 @@ open, high, low, close โดยต้องเป็นไปตาม `low <=
 ต้องมี category Dimension หนึ่งตัวและ numeric Measure ห้าตัว: minimum, q1, median,
 q3, maximum โดยต้องเป็น `minimum <= q1 <= median <= q3 <= maximum` ห้าม category
 ซ้ำ และแต่ละ partition แสดง Box Plot แยกกัน ไม่ merge distribution ข้าม partition
+กำหนดลำดับ category ได้ด้วย `category_order=[...]` และค่าที่เขียนต้องอยู่ในรายการ
 
 ---
 
@@ -640,6 +649,7 @@ category ซ้ำ `NONE` คือ current snapshot หากใช้ fixed ra
 
 ต้องมี category, start และ end โดย start/end ต้องเป็นชนิด numeric หรือ datetime
 ชนิดเดียวกัน และ `end >= start` identity ของ category/series/range ห้ามซ้ำ
+กำหนดลำดับได้ด้วย `category_order` และ `series_order`; ค่าที่เขียนต้องอยู่ในรายการ
 
 ---