Merge pull request #929 from Pipelex/release/v0.29.1

lchoquel · web-flow · commit c824d73635f0 · 2026-05-21T17:56:36.000+02:00
Release v0.29.1
diff --git a/.badges/tests.json b/.badges/tests.json
@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "label": "tests",
-  "message": "6089",
+  "message": "6095",
   "color": "blue",
   "cacheSeconds": 300
 }
diff --git a/.pipelex/plxt.toml b/.pipelex/plxt.toml
@@ -1,5 +1,5 @@
 # =============================================================================
-# Pipelex TOML Configuration for pipelex-demo
+# PLXT Configuration
 # =============================================================================
 # Configures MTHDS/TOML formatting and linting behaviour for this project.
 # Powered by the Pipelex extension (plxt / taplo engine).
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## [v0.29.1] - 2026-05-21
+
+### Fixed
+
+- **`pipelex run` now prints the aggregated cost table when `[pipelex.reporting_config].is_log_costs_to_console = true`, with `--cost-report/--no-cost-report` to override per invocation.** The `cost-tracking.md` and `reporting-config.md` docs both promised a summary cost table at the end of a CLI run, but `pipelex/cli/commands/run/_run_core.py` never called `get_report_delegate().generate_report()` — the flag only triggered `log.verbose(...)` lines per inference job, which the default `INFO` log level swallows, so the table never appeared. The CLI now calls `generate_report()` after a successful run when either `is_log_costs_to_console` or `is_generate_cost_report_file_enabled` is true, so the Rich table (one row per model, plus a totals row) prints right before the "✓ Pipeline execution completed successfully" recap — and the CSV export branch finally fires too. The new `--cost-report/--no-cost-report` tri-state flag (default unset → use config) lets you force the cost table on for a single invocation (`--cost-report`) or skip reporting entirely — no Rich table **and** no CSV file (`--no-cost-report`) — without touching `.pipelex/pipelex.toml`. Applies to `pipelex run bundle`, `pipelex run pipe`, and `pipelex run method`; works in dry-run mode as well (synthetic usage rows).
+
 ## [v0.29.0] - 2026-05-20
 
 ### Added
diff --git a/README.md b/README.md
@@ -461,10 +461,21 @@ The same `.mthds` file runs from multiple execution targets:
 |--------|-----|
 | **CLI** | `pipelex run bundle method.mthds --inputs inputs.json` |
 | **Python** | `PipelexRunner().execute_pipeline(...)` |
+| **TypeScript / Node** | [`mthds`](https://www.npmjs.com/package/mthds) SDK calling a Pipelex API server |
 | **REST API** | Self-hosted API server |
 | **MCP** | Model Context Protocol — agents call methods as tools |
 | **n8n** | Pipelex node for workflow automation |
 
+## Use Pipelex from TypeScript
+
+For Node, Next.js, or any TypeScript app, call a Pipelex API server via the [`mthds`](https://www.npmjs.com/package/mthds) npm SDK (source: [`mthds-js`](https://github.com/mthds-ai/mthds-js)). Self-host the open-source [`pipelex-api`](https://github.com/Pipelex/pipelex-api) and point the SDK at your instance. A Pipelex-hosted runner at `api.pipelex.com` is also available in private beta — [join the waitlist](https://go.pipelex.com/waitlist).
+
+```bash
+npm install mthds
+```
+
+Fastest way to get started: fork the [`pipelex-starter-js`](https://github.com/Pipelex/pipelex-starter-js) template — a Next.js 16 + TypeScript app with three working demos (text entity extraction, PDF summary, image generation). Click *Use this template* on GitHub.
+
 
 # The MTHDS Ecosystem
 
diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.py
@@ -22,7 +22,7 @@
 from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
 from pipelex.core.stuffs.stuff_viewer import render_stuff_viewer
 from pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dir
-from pipelex.hub import get_console, get_telemetry_manager
+from pipelex.hub import get_console, get_report_delegate, get_telemetry_manager
 from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
 from pipelex.pipe_run.pipe_run_mode import PipeRunMode
 from pipelex.pipelex import Pipelex
@@ -51,6 +51,7 @@ async def _execute_run(
     dry_run: bool,
     mock_inputs: bool,
     library_dir: list[str] | None,
+    cost_report: bool | None,
     dynamic_output_concept_ref: str | None = None,
 ) -> None:
     """Core async execution logic for running a pipe.
@@ -212,6 +213,20 @@ async def _execute_run(
         save_as_json_to_path(object_to_save=working_memory_dict, path=working_memory_output_path)
         log.verbose(f"Working memory saved to: {working_memory_output_path}")
 
+    reporting_config = get_config().pipelex.reporting_config
+    # --no-cost-report (cost_report is False) skips the report entirely: no table, no CSV.
+    # Otherwise: console follows the flag (if given) or config; CSV follows config.
+    if cost_report is not False:
+        print_to_console = cost_report or reporting_config.is_log_costs_to_console
+        if print_to_console or reporting_config.is_generate_cost_report_file_enabled:
+            try:
+                get_report_delegate().generate_report(
+                    pipeline_run_id=response.pipeline_run_id,
+                    print_to_console=print_to_console,
+                )
+            except (OSError, PipelexError) as cost_report_error:
+                log.warning(f"Cost report generation failed (run succeeded): {cost_report_error}")
+
     # Print completion recap
     console = get_console()
     if dry_run:
@@ -245,6 +260,7 @@ def execute_run(
     dry_run: bool,
     mock_inputs: bool,
     library_dir: list[str] | None,
+    cost_report: bool | None = None,
     telemetry_command_label: str = COMMAND,
     temporal: bool | None = None,
     dynamic_output_concept_ref: str | None = None,
@@ -275,6 +291,7 @@ def execute_run(
                     dry_run=dry_run,
                     mock_inputs=mock_inputs,
                     library_dir=library_dir,
+                    cost_report=cost_report,
                     dynamic_output_concept_ref=dynamic_output_concept_ref,
                 )
             )
diff --git a/pipelex/cli/commands/run/bundle_cmd.py b/pipelex/cli/commands/run/bundle_cmd.py
@@ -81,6 +81,13 @@ def run_bundle_cmd(
             help="Concept ref (e.g. 'document_qa.ReferenceCount') used to resolve a pipe whose output is declared as 'Dynamic'.",
         ),
     ] = None,
+    cost_report: Annotated[
+        bool | None,
+        typer.Option(
+            "--cost-report/--no-cost-report",
+            help="Override config: --cost-report forces the cost table on; --no-cost-report skips reporting entirely (no table and no CSV file).",
+        ),
+    ] = None,
 ) -> None:
     """Run a pipeline from a bundle file (.mthds) or pipeline directory.
 
@@ -171,6 +178,7 @@ def run_bundle_cmd(
         dry_run=dry_run,
         mock_inputs=mock_inputs,
         library_dir=library_dir,
+        cost_report=cost_report,
         telemetry_command_label=f"{COMMAND} bundle",
         temporal=temporal,
         dynamic_output_concept_ref=dynamic_output_concept_ref,
diff --git a/pipelex/cli/commands/run/method_cmd.py b/pipelex/cli/commands/run/method_cmd.py
@@ -80,6 +80,13 @@ def run_method_cmd(
             help="Concept ref (e.g. 'document_qa.ReferenceCount') used to resolve a pipe whose output is declared as 'Dynamic'.",
         ),
     ] = None,
+    cost_report: Annotated[
+        bool | None,
+        typer.Option(
+            "--cost-report/--no-cost-report",
+            help="Override config: --cost-report forces the cost table on; --no-cost-report skips reporting entirely (no table and no CSV file).",
+        ),
+    ] = None,
 ) -> None:
     """Run an installed method by name.
 
@@ -141,6 +148,7 @@ def run_method_cmd(
         dry_run=dry_run,
         mock_inputs=mock_inputs,
         library_dir=effective_library_dir,
+        cost_report=cost_report,
         telemetry_command_label=f"{COMMAND} method",
         temporal=temporal,
         dynamic_output_concept_ref=dynamic_output_concept_ref,
diff --git a/pipelex/cli/commands/run/pipe_cmd.py b/pipelex/cli/commands/run/pipe_cmd.py
@@ -77,6 +77,13 @@ def run_pipe_cmd(
             help="Concept ref (e.g. 'document_qa.ReferenceCount') used to resolve a pipe whose output is declared as 'Dynamic'.",
         ),
     ] = None,
+    cost_report: Annotated[
+        bool | None,
+        typer.Option(
+            "--cost-report/--no-cost-report",
+            help="Override config: --cost-report forces the cost table on; --no-cost-report skips reporting entirely (no table and no CSV file).",
+        ),
+    ] = None,
 ) -> None:
     """Run a pipe by code.
 
@@ -136,6 +143,7 @@ def run_pipe_cmd(
         dry_run=dry_run,
         mock_inputs=mock_inputs,
         library_dir=library_dir,
+        cost_report=cost_report,
         telemetry_command_label=f"{COMMAND} pipe",
         temporal=temporal,
         dynamic_output_concept_ref=dynamic_output_concept_ref,
diff --git a/pipelex/cogt/usage/cost_registry.py b/pipelex/cogt/usage/cost_registry.py
@@ -42,6 +42,7 @@ def generate_report(
         tokens_usages: Sequence[TokensUsage],
         unit_scale: float,
         cost_report_file_path: Path | None = None,
+        print_to_console: bool = True,
     ):
         if not tokens_usages:
             if pipeline_run_id != "untitled":
@@ -115,69 +116,70 @@ def generate_report(
             msg = "Empty report aggregation by model name"
             raise CostRegistryError(msg)
 
-        console = get_console()
-        title = f"Costs by model for pipeline '{pipeline_run_id}'"
-        table = Table(title=title, box=box.ROUNDED)
+        if print_to_console:
+            console = get_console()
+            title = f"Costs by model for pipeline '{pipeline_run_id}'"
+            table = Table(title=title, box=box.ROUNDED)
 
-        scale_str: str
-        if unit_scale == 1:
-            scale_str = ""
-        else:
-            scale_str = str(unit_scale)
-        # Add columns
-        table.add_column("Model", style="cyan", overflow="fold", width=30)
-        table.add_column("Type", style="dim cyan", width=8)
-        table.add_column("Input Cached", justify="right", style="green")
-        table.add_column("Input Non Cached", justify="right", style="green")
-        table.add_column("Input Joined", justify="right", style="green")
-        table.add_column("Output", justify="right", style="green")
-        table.add_column(f"Input Cached Cost ({scale_str}$)", justify="right", style="yellow")
-        table.add_column(f"Input Non Cached Cost ({scale_str}$)", justify="right", style="yellow")
-        table.add_column(f"Input Joined Cost ({scale_str}$)", justify="right", style="yellow")
-        table.add_column(f"Output Cost ({scale_str}$)", justify="right", style="yellow")
-        table.add_column(f"Total Cost ({scale_str}$)", justify="right", style="bold yellow")
+            scale_str: str
+            if unit_scale == 1:
+                scale_str = ""
+            else:
+                scale_str = str(unit_scale)
+            # Add columns
+            table.add_column("Model", style="cyan", overflow="fold", width=30)
+            table.add_column("Type", style="dim cyan", width=8)
+            table.add_column("Input Cached", justify="right", style="green")
+            table.add_column("Input Non Cached", justify="right", style="green")
+            table.add_column("Input Joined", justify="right", style="green")
+            table.add_column("Output", justify="right", style="green")
+            table.add_column(f"Input Cached Cost ({scale_str}$)", justify="right", style="yellow")
+            table.add_column(f"Input Non Cached Cost ({scale_str}$)", justify="right", style="yellow")
+            table.add_column(f"Input Joined Cost ({scale_str}$)", justify="right", style="yellow")
+            table.add_column(f"Output Cost ({scale_str}$)", justify="right", style="yellow")
+            table.add_column(f"Total Cost ({scale_str}$)", justify="right", style="bold yellow")
 
-        # Add rows for each model
-        for model_name, aggregated_data in grouped_by_model.items():
-            row_total_cost = cls.compute_total_cost(
-                input_non_cached_cost=aggregated_data[report_field.COST_INPUT_NON_CACHED],
-                input_cached_cost=aggregated_data[report_field.COST_INPUT_CACHED],
-                output_cost=aggregated_data[report_field.COST_OUTPUT],
-            )
+            # Add rows for each model
+            for model_name, aggregated_data in grouped_by_model.items():
+                row_total_cost = cls.compute_total_cost(
+                    input_non_cached_cost=aggregated_data[report_field.COST_INPUT_NON_CACHED],
+                    input_cached_cost=aggregated_data[report_field.COST_INPUT_CACHED],
+                    output_cost=aggregated_data[report_field.COST_OUTPUT],
+                )
+                table.add_row(
+                    model_name,
+                    model_types.get(model_name, "llm"),
+                    f"{int(aggregated_data[report_field.NB_TOKENS_INPUT_CACHED]):,}",
+                    f"{int(aggregated_data[report_field.NB_TOKENS_INPUT_NON_CACHED]):,}",
+                    f"{int(aggregated_data[report_field.NB_TOKENS_INPUT_JOINED]):,}",
+                    f"{int(aggregated_data[report_field.NB_TOKENS_OUTPUT]):,}",
+                    f"{aggregated_data[report_field.COST_INPUT_CACHED] / unit_scale:.4f}",
+                    f"{aggregated_data[report_field.COST_INPUT_NON_CACHED] / unit_scale:.4f}",
+                    f"{aggregated_data[report_field.COST_INPUT_JOINED] / unit_scale:.4f}",
+                    f"{aggregated_data[report_field.COST_OUTPUT] / unit_scale:.4f}",
+                    f"{row_total_cost / unit_scale:.4f}",
+                )
+
+            # add total row
+            footer_style = "bold"
             table.add_row(
-                model_name,
-                model_types.get(model_name, "llm"),
-                f"{int(aggregated_data[report_field.NB_TOKENS_INPUT_CACHED]):,}",
-                f"{int(aggregated_data[report_field.NB_TOKENS_INPUT_NON_CACHED]):,}",
-                f"{int(aggregated_data[report_field.NB_TOKENS_INPUT_JOINED]):,}",
-                f"{int(aggregated_data[report_field.NB_TOKENS_OUTPUT]):,}",
-                f"{aggregated_data[report_field.COST_INPUT_CACHED] / unit_scale:.4f}",
-                f"{aggregated_data[report_field.COST_INPUT_NON_CACHED] / unit_scale:.4f}",
-                f"{aggregated_data[report_field.COST_INPUT_JOINED] / unit_scale:.4f}",
-                f"{aggregated_data[report_field.COST_OUTPUT] / unit_scale:.4f}",
-                f"{row_total_cost / unit_scale:.4f}",
+                "Total",
+                "",
+                f"{total_nb_tokens_input_cached:,}",
+                f"{total_nb_tokens_input_non_cached:,}",
+                f"{total_nb_tokens_input_joined:,}",
+                f"{total_nb_tokens_output:,}",
+                f"{total_cost_input_cached / unit_scale:.4f}",
+                f"{total_cost_input_non_cached / unit_scale:.4f}",
+                f"{total_cost_input_joined / unit_scale:.4f}",
+                f"{total_cost_output / unit_scale:.4f}",
+                f"{total_cost / unit_scale:.4f}",
+                style=footer_style,
+                end_section=True,
             )
 
-        # add total row
-        footer_style = "bold"
-        table.add_row(
-            "Total",
-            "",
-            f"{total_nb_tokens_input_cached:,}",
-            f"{total_nb_tokens_input_non_cached:,}",
-            f"{total_nb_tokens_input_joined:,}",
-            f"{total_nb_tokens_output:,}",
-            f"{total_cost_input_cached / unit_scale:.4f}",
-            f"{total_cost_input_non_cached / unit_scale:.4f}",
-            f"{total_cost_input_joined / unit_scale:.4f}",
-            f"{total_cost_output / unit_scale:.4f}",
-            f"{total_cost / unit_scale:.4f}",
-            style=footer_style,
-            end_section=True,
-        )
-
-        console.print(table)
-        console.print(" [dim]Note: some costs might be missing or not up-to-date.[/dim]")
+            console.print(table)
+            console.print(" [dim]Note: some costs might be missing or not up-to-date.[/dim]")
 
         if cost_report_file_path:
             cls.save_to_csv(records, cost_report_file_path)
diff --git a/pipelex/kit/configs/plxt.toml b/pipelex/kit/configs/plxt.toml
@@ -1,5 +1,5 @@
 # =============================================================================
-# Pipelex TOML Configuration for pipelex-demo
+# PLXT Configuration
 # =============================================================================
 # Configures MTHDS/TOML formatting and linting behaviour for this project.
 # Powered by the Pipelex extension (plxt / taplo engine).
diff --git a/pipelex/reporting/reporting_manager.py b/pipelex/reporting/reporting_manager.py
@@ -366,15 +366,10 @@ def report_inference_job(self, inference_job: InferenceJobAbstract):
             log.warning(f"ReportingManager does not support reporting for inference job type: {type(inference_job).__name__}")
 
     @override
-    def generate_report(self, pipeline_run_id: str | None = None):
-        cost_report_file_path: Path | None = None
-        if self._reporting_config.is_generate_cost_report_file_enabled:
+    def generate_report(self, pipeline_run_id: str | None = None, print_to_console: bool = True):
+        is_csv_enabled = self._reporting_config.is_generate_cost_report_file_enabled
+        if is_csv_enabled:
             ensure_path(self._reporting_config.cost_report_dir_path)
-            cost_report_file_path = get_incremental_file_path(
-                base_path=self._reporting_config.cost_report_dir_path,
-                base_name=self._reporting_config.cost_report_base_name,
-                extension=self._reporting_config.cost_report_extension,
-            )
 
         registries_to_process: dict[str, UsageRegistry] = {}
         if pipeline_run_id:
@@ -383,11 +378,19 @@ def generate_report(self, pipeline_run_id: str | None = None):
             registries_to_process = self._usage_registries
 
         for run_id, registry in registries_to_process.items():
+            cost_report_file_path: Path | None = None
+            if is_csv_enabled:
+                cost_report_file_path = get_incremental_file_path(
+                    base_path=self._reporting_config.cost_report_dir_path,
+                    base_name=self._reporting_config.cost_report_base_name,
+                    extension=self._reporting_config.cost_report_extension,
+                )
             CostRegistry.generate_report(
                 pipeline_run_id=run_id,
                 tokens_usages=registry.get_current_tokens_usage(),
                 unit_scale=self._reporting_config.cost_report_unit_scale,
                 cost_report_file_path=cost_report_file_path,
+                print_to_console=print_to_console,
             )
 
     @override
diff --git a/pipelex/reporting/reporting_protocol.py b/pipelex/reporting/reporting_protocol.py
@@ -11,7 +11,7 @@ def open_registry(self, pipeline_run_id: str): ...
 
     def report_inference_job(self, inference_job: InferenceJobAbstract): ...
 
-    def generate_report(self, pipeline_run_id: str | None = None): ...
+    def generate_report(self, pipeline_run_id: str | None = None, print_to_console: bool = True): ...
 
     def close_registry(self, pipeline_run_id: str): ...
 
@@ -40,7 +40,7 @@ def report_inference_job(self, inference_job: InferenceJobAbstract):
         pass
 
     @override
-    def generate_report(self, pipeline_run_id: str | None = None):
+    def generate_report(self, pipeline_run_id: str | None = None, print_to_console: bool = True):
         pass
 
     @override
diff --git a/pipelex/system/configuration/configs.py b/pipelex/system/configuration/configs.py
@@ -97,7 +97,7 @@ class ReportingConfig(ConfigModel):
     cost_report_dir_path: str
     cost_report_base_name: str
     cost_report_extension: str
-    cost_report_unit_scale: float
+    cost_report_unit_scale: Annotated[float, Field(gt=0)]
 
 
 class TracingBackend(StrEnum):
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "pipelex"
-version = "0.29.0"
+version = "0.29.1"
 description = "Execute composable AI methods declared in the MTHDS open standard"
 authors = [{ name = "Evotis S.A.S.", email = "oss@pipelex.com" }]
 maintainers = [{ name = "Pipelex staff", email = "oss@pipelex.com" }]
diff --git a/tests/unit/pipelex/cogt/usage/test_cost_registry.py b/tests/unit/pipelex/cogt/usage/test_cost_registry.py
diff --git a/tests/unit/pipelex/system/test_reporting_config_validation.py b/tests/unit/pipelex/system/test_reporting_config_validation.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"schemaVersion": 1,`
`3`	`3`	`"label": "tests",`
`4`		`- "message": "6089",`
	`4`	`+ "message": "6095",`
`5`	`5`	`"color": "blue",`
`6`	`6`	`"cacheSeconds": 300`
`7`	`7`	`}`