Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
fix: layer global pipelex.toml and telemetry.toml under project overrides (#892)
Louis Choquel02ed1a16f3f1
diff --git a/.pipelex/telemetry.toml b/.pipelex/telemetry.tomlindex ed9a90901..9b89befc9 100644--- a/.pipelex/telemetry.toml+++ b/.pipelex/telemetry.toml@@ -1,14 +1,18 @@####################################################################################################-# Custom Telemetry Configuration+# Custom Telemetry Configuration (Project Override)#####################################################################################################-# This file controls YOUR custom telemetry settings for observability and analytics.-# Configure your own PostHog, Langfuse, or OTLP-compatible backends here.+# This file lives in your project's `.pipelex/` directory. Every setting below is+# commented out on purpose: the project file is layered ON TOP of your global+# `~/.pipelex/telemetry.toml` and `~/.pipelex/telemetry_override.toml`, so any+# value you set here REPLACES the global one for this project.+#+# Leave it commented out to inherit your global telemetry settings unchanged.+# Uncomment a key (or whole section) to override it for this project only.## NOTE: When using Pipelex Gateway, identified telemetry is automatically enabled-# (tied to your Gateway API key, hashed for security). This allows us to monitor-# service quality, enforce fair usage, and provide you with better support.-# Gateway telemetry operates independently from your settings below - you can have both!+# (tied to your Gateway API key, hashed for security). This is independent of the+# settings below — you can have both.## To disable all telemetry, set the DO_NOT_TRACK=1 environment variable.#@@ -21,50 +25,50 @@# PostHog Configuration (Event tracking + AI span tracing)# ──────────────────────────────────────────────────────────────────────────────-[custom_posthog]-mode = "off" # Values: "off" | "anonymous" | "identified"-# user_id = "your_user_id" # Required when mode = "identified"-endpoint = "${POSTHOG_ENDPOINT}" # Default: https://us.i.posthog.com (or https://eu.i.posthog.com for EU)-api_key = "${POSTHOG_API_KEY}" # Get from PostHog Project Settings-geoip = true # Enable GeoIP lookup-debug = false # Enable PostHog debug mode-redact_properties = [- "prompt",- "system_prompt",- "response",- "file_path",- "url",-] # Event properties to redact+# [custom_posthog]+# mode = "off" # Values: "off" | "anonymous" | "identified"+# user_id = "your_user_id" # Required when mode = "identified"+# endpoint = "${POSTHOG_ENDPOINT}" # Default: https://us.i.posthog.com (or https://eu.i.posthog.com for EU)+# api_key = "${POSTHOG_API_KEY}" # Get from PostHog Project Settings+# geoip = true # Enable GeoIP lookup+# debug = false # Enable PostHog debug mode+# redact_properties = [+# "prompt",+# "system_prompt",+# "response",+# "file_path",+# "url",+# ]# AI span tracing to YOUR PostHog (does NOT affect Langfuse/OTLP - they receive full data)-[custom_posthog.tracing]-enabled = false # Send AI spans to your PostHog+# [custom_posthog.tracing]+# enabled = false # Send AI spans to your PostHog# Privacy controls for data sent to YOUR PostHog only-[custom_posthog.tracing.capture]-content = false # Capture prompt/completion content-# content_max_length = 1000 # Max length for captured content (omit for unlimited)-pipe_codes = false # Include pipe codes in span names/attributes-output_class_names = false # Include output class names in span names/attributes+# [custom_posthog.tracing.capture]+# content = false # Capture prompt/completion content+# content_max_length = 1000 # Max length for captured content (omit for unlimited)+# pipe_codes = false # Include pipe codes in span names/attributes+# output_class_names = false # Include output class names in span names/attributes# ──────────────────────────────────────────────────────────────────────────────# Portkey SDK Configuration# ──────────────────────────────────────────────────────────────────────────────-[custom_portkey]-force_debug_enabled = false-force_tracing_enabled = false+# [custom_portkey]+# force_debug_enabled = false+# force_tracing_enabled = false# ──────────────────────────────────────────────────────────────────────────────# Langfuse Integration# Note: Langfuse receives FULL span data (no redaction)# ──────────────────────────────────────────────────────────────────────────────-[langfuse]-enabled = false-# endpoint = "https://cloud.langfuse.com" # Override for self-hosted Langfuse-# public_key = "${LANGFUSE_PUBLIC_KEY}" # Langfuse public key-# secret_key = "${LANGFUSE_SECRET_KEY}" # Langfuse secret key+# [langfuse]+# enabled = false+# endpoint = "https://cloud.langfuse.com" # Override for self-hosted Langfuse+# public_key = "${LANGFUSE_PUBLIC_KEY}"+# secret_key = "${LANGFUSE_SECRET_KEY}"# ──────────────────────────────────────────────────────────────────────────────# Additional OTLP Exporters (array for multiple)@@ -72,21 +76,22 @@ enabled = false# ──────────────────────────────────────────────────────────────────────────────# [[otlp]]-# name = "my-collector" # Identifier for logging-# endpoint = "https://..." # OTLP endpoint URL-# headers = { Authorization = "Bearer ${OTLP_AUTH_TOKEN}" } # Headers for OTLP export+# name = "my-collector"+# endpoint = "https://..."+# headers = { Authorization = "Bearer ${OTLP_AUTH_TOKEN}" }# ──────────────────────────────────────────────────────────────────────────────# Custom Telemetry Allowed Modes# Controls which integration modes can use custom telemetry settings above.+# Defaults live in the Pydantic model (TelemetryConfig.telemetry_allowed_modes).# ──────────────────────────────────────────────────────────────────────────────-[telemetry_allowed_modes]-ci = false # CI environments don't use custom telemetry-cli = true # CLI usage allows custom telemetry-docker = true # Docker deployments allow custom telemetry-fastapi = true # FastAPI integrations allow custom telemetry-mcp = true # MCP integrations allow custom telemetry-n8n = true # n8n integrations allow custom telemetry-pytest = false # Tests don't use custom telemetry-python = false # Direct Python SDK usage doesn't use custom telemetry by default+# [telemetry_allowed_modes]+# ci = false+# cli = true+# docker = true+# fastapi = true+# mcp = true+# n8n = true+# pytest = false+# python = falsediff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0101bf2a2..8f2e2100f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@### Fixed+- **Project `.pipelex/telemetry.toml` created by `pipelex init` no longer silently disables globally-enabled telemetry.** The kit previously shipped one `telemetry.toml` template carrying explicit `enabled = false` / `mode = "off"` defaults, and `pipelex init telemetry` copied it into both `~/.pipelex/` and the project's `.pipelex/`. Because the layered loader appends the project base file after `~/.pipelex/telemetry_override.toml`, a user who enabled Langfuse/PostHog globally in their override still had it turned off in every initialized project. The kit now ships a separate `telemetry.project.toml` template with every setting commented out, used only by project-level init. The global init still copies the active `telemetry.toml`. As a safety net, `telemetry_allowed_modes` defaults (`ci=False`, `cli=True`, `docker=True`, `fastapi=True`, `mcp=True`, `n8n=True`, `pytest=False`, `python=False`) now live in the `TelemetryConfig` Pydantic model rather than the TOML template, so a project file that omits the section can't disable custom telemetry for everyone.+- **Global `pipelex.toml` and `telemetry.toml` overrides no longer silently disappear when a project `.pipelex/` exists.** `ConfigLoader.load_config()` previously sourced *all* override files (`pipelex_local.toml`, `pipelex_{env}.toml`, `pipelex_{run_mode}.toml`, `pipelex_override.toml`, `pipelex_temporary_override.toml`) from a single "effective config dir" — project `.pipelex/` if present, else `~/.pipelex/`. As a result, the user's machine-wide overrides in `~/.pipelex/` were ignored entirely the moment a project shipped its own `.pipelex/`. `load_telemetry_config` had the same shadowing behavior for `telemetry.toml` and `telemetry_override.toml`, which was particularly painful because telemetry holds Langfuse/PostHog/OTLP secrets that users typically set once globally. Both loaders now layer global → project: package defaults → global base → global overrides → project base → project overrides, deep-merged so machine-wide personal preferences keep applying unless explicitly overridden by the project. The unit-testing run_mode behavior is preserved: `./tests/pipelex_{run_mode}.toml` is still the only run_mode file loaded under unit testing, replacing both layers to keep test runs hermetic. **Migration:** if a project previously relied on its `.pipelex/` to fully *replace* the user's global config rather than merging over it, the project must now redeclare any keys it wants to set explicitly — silent inheritance from `~/.pipelex/` is the new default.- **`pipelex build structures` now emits domain-qualified class names and cross-references.** `ConceptFactory` registers each concept's structure class under `make_qualified_structure_class_name(domain, concept_code)` (e.g. `expense_validator__SpendingLimitCheck`), but the CLI generator was passing the bare `concept_code` to `StructureGenerator`. Generated files therefore contained `class ConceptCode(StructuredContent)` and unqualified cross-imports/types, while the registry expected the qualified name. `PipeFunc` validation against `concept.structure_class_name` then rejected the mismatch with `output concept expects structure class 'domain__X', but the function return type is 'X'`, breaking library load for any project that had regenerated structures. Fixed in `pipelex/cli/commands/build/structures_cmd.py`: the class-definition call sites now call `make_qualified_structure_class_name(blueprint.domain, concept_code)`; `_build_concept_ref_to_class_info` qualifies cross-reference class names while keeping the file stem unqualified so output filenames stay `domain__concept_code.py`; the `refines:` branch resolves the refined concept's domain via `QualifiedRef.parse_stripping_cross_package` and qualifies the base-class name for non-native refines, mirroring `ConceptFactory._handle_refines`.## [v0.27.0] - 2026-05-07diff --git a/docs/configuration/config-practical/telemetry-config.md b/docs/configuration/config-practical/telemetry-config.mdindex b433c6ab1..c02c48517 100644--- a/docs/configuration/config-practical/telemetry-config.md+++ b/docs/configuration/config-practical/telemetry-config.md@@ -24,6 +24,23 @@ Telemetry configuration is stored in `.pipelex/telemetry.toml`. This file controThis file is created when you run `pipelex init telemetry` or `pipelex init`.+### Global vs project config++Telemetry config is layered: a project `.pipelex/telemetry.toml` is merged **on top of** the user's global `~/.pipelex/telemetry.toml`, not as a replacement. The load order is:++1. `~/.pipelex/telemetry.toml`+2. `~/.pipelex/telemetry_override.toml`+3. `{project_root}/.pipelex/telemetry.toml` *(if it exists and the project dir is distinct from the global dir)*+4. `{project_root}/.pipelex/telemetry_override.toml` *(same condition)*++Files are deep-merged, with later layers winning per leaf key. This means Langfuse keys or OTLP endpoints declared once in `~/.pipelex/telemetry.toml` keep applying across every project — a project file can override specific keys without redeclaring the rest.++!!! info "Project telemetry.toml is empty by default"+ To make the layering above actually work, `pipelex init` (when targeting a project's `.pipelex/`) drops in a **fully commented-out template**. Every section is present as documentation, but no key is set. This is deliberate: a value defined in the project file would otherwise override your global setting. Uncomment a key in the project template only when you want this project to diverge from your global telemetry config. Global init (`~/.pipelex/`) gets the active template with real defaults.++!!! note "List merge behavior"+ The `[[otlp]]` array and the `redact_properties` list do not concatenate across layers — the later layer replaces the whole list. If you want to add an OTLP exporter on top of the global set, redeclare all exporters in the layer that wins.+## Full Example Configuration```tomldiff --git a/docs/contribute/configuration-defaults-and-overrides.md b/docs/contribute/configuration-defaults-and-overrides.mdindex c7cade005..f24d8cc35 100644--- a/docs/contribute/configuration-defaults-and-overrides.md+++ b/docs/contribute/configuration-defaults-and-overrides.md@@ -13,10 +13,11 @@ For the user-facing configuration guide, see [Configuration Overview](../configuPipelex configuration is merged in layers:- **Shipped defaults**: maintained by the Pipelex project and used as the baseline by the installed package.-- **Project overrides**: created in `.pipelex/` by `pipelex init …` and edited by projects that use Pipelex.-- **Root override files** (advanced): optional files for machine/env/run-mode/super overrides.+- **Global config** (`~/.pipelex/`): machine-wide settings for a developer, applied to every project on the machine.+- **Project config** (`{project_root}/.pipelex/`): per-project settings, edited by teams using Pipelex.+- **Override files** at each level (`pipelex_local.toml`, `pipelex_{environment}.toml`, `pipelex_{run_mode}.toml`, `pipelex_override.toml`, `pipelex_temporary_override.toml`): optional, typically gitignored, used for personal or ephemeral tweaks.-The key idea: client projects typically edit **`.pipelex/`**, while the Pipelex repository holds the **default values** used as a starting point.+The key idea: global personal preferences layer **under** project-specific settings — both are loaded, and project values win on collisions. Nothing in `~/.pipelex/` is shadowed by the mere existence of a project `.pipelex/`.## Where defaults live (Pipelex repository)@@ -25,20 +26,24 @@ The key idea: client projects typically edit **`.pipelex/`**, while the Pipelex## Merge order (runtime)-The configuration loading/merging behavior is implemented in `pipelex/system/configuration/config_loader.py`.+The configuration loading/merging behavior is implemented in `pipelex/system/configuration/config_loader.py`. Files are deep-merged via `load_toml_from_path_and_merge_with_overrides`; the later a file appears in the load list, the higher its precedence per leaf key.-At a high level, the load order is:+Load order:-1. **Pipelex base defaults** (from the installed package)-2. **Project config** from `.pipelex/pipelex.toml` (when running in a client project)-3. **Root overrides** (optional), in this order:- 1. `pipelex_local.toml`- 2. `pipelex_{environment}.toml`- 3. `pipelex_{run_mode}.toml`- 4. `pipelex_override.toml`+1. **Package defaults** — `pipelex/pipelex.toml` shipped with the installed package.+2. **Global base** — `~/.pipelex/pipelex.toml`.+3. **Global override sequence** — from `~/.pipelex/`, in this order:+ 1. `pipelex_local.toml`+ 2. `pipelex_{environment}.toml`+ 3. `pipelex_{run_mode}.toml` *(see unit-test special case below)*+ 4. `pipelex_override.toml`+ 5. `pipelex_temporary_override.toml`+4. **Project base** — `{project_root}/.pipelex/pipelex.toml`, if a project `.pipelex/` exists and is distinct from `~/.pipelex/`.+5. **Project override sequence** — same five files as step 3, read from `{project_root}/.pipelex/`, if the project dir is distinct from the global dir.+6. **Programmatic `extra_overrides`** passed into `ConfigLoader.load_config()` (if any).-!!! note "Unit test special case"- When unit testing, run-mode overrides may be loaded from `tests/pipelex_{run_mode}.toml` (example: `tests/pipelex_unit_test.toml`).+!!! note "Unit-test special case"+ When `runtime_manager.is_unit_testing` is true, the `pipelex_{run_mode}.toml` entry is sourced exclusively from `./tests/pipelex_{run_mode}.toml` (e.g. `tests/pipelex_unit_test.toml`). Global and project run_mode files are not loaded, keeping test runs hermetic from machine-wide overrides.## Where to change things in codediff --git a/docs/setup/telemetry.md b/docs/setup/telemetry.mdindex d84bc6845..754e39566 100644--- a/docs/setup/telemetry.md+++ b/docs/setup/telemetry.md@@ -53,7 +53,13 @@ When you run `pipelex init`, a default `telemetry.toml` configuration file is crpipelex init telemetry```-This creates `.pipelex/telemetry.toml` with all options disabled by default. Edit this file to enable your preferred telemetry destinations.+The behavior depends on the target:++- **Global init** (default — writes to `~/.pipelex/telemetry.toml`): an active template is created with all options disabled. Edit it to enable your preferred telemetry destinations machine-wide.+- **Project init** (`pipelex init --local` — writes to `{project_root}/.pipelex/telemetry.toml`): a fully **commented-out** template is created. The project file is layered on top of your global config, so leaving it commented means the project inherits your global telemetry settings as-is. Uncomment a key only when this project should diverge.++!!! note "Global vs project config"+ Pipelex looks for telemetry config in **both** `~/.pipelex/` (machine-wide) and `{project_root}/.pipelex/` (per-project). Both are deep-merged, with the project file winning on key collisions — your global Langfuse keys keep applying across every project unless a project explicitly overrides them. See [Telemetry Configuration → Global vs project config](../configuration/config-practical/telemetry-config.md#global-vs-project-config) for the full load order.### Example: Enable PostHog Tracingdiff --git a/docs/under-the-hood/init-cli-flows.md b/docs/under-the-hood/init-cli-flows.mdindex 4e5cbfe3b..9f26f381a 100644--- a/docs/under-the-hood/init-cli-flows.md+++ b/docs/under-the-hood/init-cli-flows.md@@ -224,7 +224,12 @@ If `needs_routing` is `True` (only for `focus=routing`), runs `customize_routing### Step 4: Telemetry Step-Copies the `telemetry.toml` template and prints instructions. No interactive prompts.+Copies a telemetry template and prints instructions. No interactive prompts. Which template is copied depends on the target:++- **Global init** (target is `~/.pipelex/`): copies `pipelex/kit/configs/telemetry.toml` — the active template with disabled-by-default settings.+- **Project init** (target is `{project_root}/.pipelex/`): copies `pipelex/kit/configs/telemetry.project.toml` — every setting commented out so the project file does not shadow `~/.pipelex/telemetry.toml` or `~/.pipelex/telemetry_override.toml` during layered loading.++`setup_telemetry()` selects the template via a `for_project: bool` arg passed down from the `--local` flag on `pipelex init`.---@@ -267,7 +272,7 @@ Copies the `telemetry.toml` template and prints instructions. No interactive pro| Constant | Contents | Reason ||----------|----------|--------|-| `INIT_SKIP_FILES` | All `GIT_IGNORED_CONFIG_FILES` (`pipelex_service.toml`, `pipelex_override.toml`, `telemetry_override.toml`, `pipelex_gateway_models.md`, `pipelex_gateway_models_plain.md`, `x_custom_llm_deck.toml`, `x_custom_extract_deck.toml`) plus `telemetry.toml` and `.DS_Store` | Git-ignored, auto-generated, or managed by other steps |+| `INIT_SKIP_FILES` | All `GIT_IGNORED_CONFIG_FILES` (`pipelex_service.toml`, `pipelex_override.toml`, `telemetry_override.toml`, `telemetry.project.toml`, `pipelex_gateway_models.md`, `pipelex_gateway_models_plain.md`, `x_custom_llm_deck.toml`, `x_custom_extract_deck.toml`) plus `telemetry.toml` and `.DS_Store` | Git-ignored, auto-generated, or managed by other steps || `INIT_SKIP_DIRS` | `inference` | Managed independently by inference step |### Source Modulesdiff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.pyindex 7f6b98b1e..f8fd4de3e 100644--- a/pipelex/cli/agent_cli/commands/init_cmd.py+++ b/pipelex/cli/agent_cli/commands/init_cmd.py@@ -22,7 +22,7 @@ from pipelex.system.pipelex_service.pipelex_service_agreement import (update_inference_setup_completed,update_service_terms_acceptance,)-from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME+from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, TELEMETRY_PROJECT_TEMPLATE_FILE_NAMEfrom pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path@@ -125,13 +125,21 @@ def _copy_inference_templates(target_dir: Path) -> None:shutil.copy2(template_routing_path, target_inference_dir / "routing_profiles.toml")-def _copy_telemetry_template(target_dir: Path) -> None:- """Copy the telemetry template (defaults to off) to the target directory.+def _copy_telemetry_template(target_dir: Path, for_project: bool) -> None:+ """Copy the appropriate telemetry template to the target directory.++ The global template (`telemetry.toml`) carries active defaults. The project+ template (`telemetry.project.toml`) is fully commented out so a project's+ `.pipelex/telemetry.toml` doesn't shadow the user's global telemetry+ settings during layered loading.Args:target_dir: Target config directory (e.g. .pipelex/).+ for_project: True when targeting a project's `.pipelex/`; False when+ targeting the global `~/.pipelex/`."""- template_path = Path(str(get_kit_configs_dir())) / TELEMETRY_CONFIG_FILE_NAME+ template_name = TELEMETRY_PROJECT_TEMPLATE_FILE_NAME if for_project else TELEMETRY_CONFIG_FILE_NAME+ template_path = Path(str(get_kit_configs_dir())) / template_nametarget_path = target_dir / TELEMETRY_CONFIG_FILE_NAMEtarget_path.parent.mkdir(parents=True, exist_ok=True)shutil.copy2(template_path, target_path)@@ -327,7 +335,9 @@ def agent_init_cmd(- primary_backend: required when 2+ backends are selected and pipelex_gatewayis not among them. Auto-derived when only 1 backend or pipelex_gateway is present.- Telemetry is always initialized to "off" (can be changed manually in telemetry.toml).+ Telemetry: global init seeds an active `telemetry.toml` template with all destinations+ off; project init drops in a commented-out template that inherits the user's global+ telemetry settings via layered loading. Edit `telemetry.toml` to enable destinations."""try:# Parse config@@ -342,8 +352,10 @@ def agent_init_cmd(# Step 1.5: Copy inference templates (init_config skips inference/)_copy_inference_templates(target_dir)- # Step 1.6: Copy telemetry template (defaults to off)- _copy_telemetry_template(target_dir)+ # Step 1.6: Copy telemetry template. Global init seeds active defaults;+ # project init drops in a commented-out template so it doesn't shadow+ # the user's global telemetry settings during layered loading.+ _copy_telemetry_template(target_dir, for_project=not global_)# Step 2: Configure backendstemplate_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.pyindex 69abb9867..7a20d51b3 100644--- a/pipelex/cli/commands/init/command.py+++ b/pipelex/cli/commands/init/command.py@@ -178,6 +178,7 @@ def execute_initialization(telemetry_config_path: str,is_first_time_backends_setup: bool,target_config_dir: Path | None = None,+ for_project: bool = False,):"""Execute the initialization steps.@@ -195,6 +196,8 @@ def execute_initialization(telemetry_config_path: Path to telemetry config file.is_first_time_backends_setup: Whether backends.toml didn't exist before this run.target_config_dir: Explicit target .pipelex directory. If None, uses config_manager.pipelex_config_dir.+ for_project: True when initializing a project's .pipelex/; False when initializing+ the global ~/.pipelex/. Selects which telemetry template gets copied."""# Step 1: Initialize config if needed@@ -301,7 +304,7 @@ def execute_initialization(# Step 4: Set up telemetry if neededif needs_telemetry:- setup_telemetry(console, telemetry_config_path)+ setup_telemetry(console, telemetry_config_path, for_project=for_project)console.print()@@ -472,6 +475,7 @@ def init_cmd(telemetry_config_path=telemetry_config_path,is_first_time_backends_setup=is_first_time_backends_setup,target_config_dir=pipelex_config_dir,+ for_project=local,)except typer.Exit:diff --git a/pipelex/cli/commands/init/telemetry.py b/pipelex/cli/commands/init/telemetry.pyindex 087da9538..6f0e94e60 100644--- a/pipelex/cli/commands/init/telemetry.py+++ b/pipelex/cli/commands/init/telemetry.py@@ -6,31 +6,41 @@ import shutilfrom rich.console import Consolefrom pipelex.kit.paths import get_kit_configs_dir-from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME+from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, TELEMETRY_PROJECT_TEMPLATE_FILE_NAME-def setup_telemetry(console: Console, telemetry_config_path: str) -> None:- """Set up telemetry configuration by copying the template.+def setup_telemetry(console: Console, telemetry_config_path: str, for_project: bool) -> None:+ """Set up telemetry configuration by copying the appropriate kit template.++ The global template (`telemetry.toml`) carries active defaults and seeds+ `~/.pipelex/telemetry.toml`. The project template (`telemetry.project.toml`)+ is fully commented out so a project's `.pipelex/telemetry.toml` does not+ override the user's global telemetry settings during layered loading.Args:console: Rich Console instance for user interaction.telemetry_config_path: Path to save the telemetry configuration.+ for_project: True when targeting a project's `.pipelex/`; False when+ targeting the global `~/.pipelex/`."""- # Ensure parent directory exists (needed when running `pipelex init telemetry` on fresh project)os.makedirs(os.path.dirname(telemetry_config_path), exist_ok=True)- # Copy template to destination- template_path = os.path.join(str(get_kit_configs_dir()), TELEMETRY_CONFIG_FILE_NAME)+ template_name = TELEMETRY_PROJECT_TEMPLATE_FILE_NAME if for_project else TELEMETRY_CONFIG_FILE_NAME+ template_path = os.path.join(str(get_kit_configs_dir()), template_name)shutil.copy(template_path, telemetry_config_path)console.print()console.print("[green]✓[/green] Telemetry configuration created")console.print(f" [dim]File:[/dim] [cyan]{telemetry_config_path}[/cyan]")console.print()- console.print("[dim]Edit this file to configure AI trace destinations:[/dim]")- console.print("[dim] • \\[posthog] - Send traces to your own PostHog project[/dim]")- console.print("[dim] • \\[langfuse] - Enable Langfuse LLM observability[/dim]")- console.print("[dim] • \\[\\[otlp]] - Add custom OpenTelemetry exporters[/dim]")+ if for_project:+ console.print("[dim]Project telemetry inherits your global settings. Uncomment any key[/dim]")+ console.print("[dim]in this file to override it for this project only.[/dim]")+ else:+ console.print("[dim]Edit this file to configure AI trace destinations:[/dim]")+ console.print("[dim] • \\[posthog] - Send traces to your own PostHog project[/dim]")+ console.print("[dim] • \\[langfuse] - Enable Langfuse LLM observability[/dim]")+ console.print("[dim] • \\[\\[otlp]] - Add custom OpenTelemetry exporters[/dim]")console.print()console.print("[dim]💡 Note: If you use Pipelex Gateway, separate telemetry is sent to Pipelex[/dim]")console.print("[dim]servers regardless of these settings.[/dim]")diff --git a/pipelex/kit/configs/telemetry.project.toml b/pipelex/kit/configs/telemetry.project.tomlnew file mode 100644index 000000000..9b89befc9--- /dev/null+++ b/pipelex/kit/configs/telemetry.project.toml@@ -0,0 +1,97 @@+####################################################################################################+# Custom Telemetry Configuration (Project Override)+####################################################################################################+#+# This file lives in your project's `.pipelex/` directory. Every setting below is+# commented out on purpose: the project file is layered ON TOP of your global+# `~/.pipelex/telemetry.toml` and `~/.pipelex/telemetry_override.toml`, so any+# value you set here REPLACES the global one for this project.+#+# Leave it commented out to inherit your global telemetry settings unchanged.+# Uncomment a key (or whole section) to override it for this project only.+#+# NOTE: When using Pipelex Gateway, identified telemetry is automatically enabled+# (tied to your Gateway API key, hashed for security). This is independent of the+# settings below — you can have both.+#+# To disable all telemetry, set the DO_NOT_TRACK=1 environment variable.+#+# Documentation: https://docs.pipelex.com+# Support: https://go.pipelex.com/discord+#+####################################################################################################++# ──────────────────────────────────────────────────────────────────────────────+# PostHog Configuration (Event tracking + AI span tracing)+# ──────────────────────────────────────────────────────────────────────────────++# [custom_posthog]+# mode = "off" # Values: "off" | "anonymous" | "identified"+# user_id = "your_user_id" # Required when mode = "identified"+# endpoint = "${POSTHOG_ENDPOINT}" # Default: https://us.i.posthog.com (or https://eu.i.posthog.com for EU)+# api_key = "${POSTHOG_API_KEY}" # Get from PostHog Project Settings+# geoip = true # Enable GeoIP lookup+# debug = false # Enable PostHog debug mode+# redact_properties = [+# "prompt",+# "system_prompt",+# "response",+# "file_path",+# "url",+# ]++# AI span tracing to YOUR PostHog (does NOT affect Langfuse/OTLP - they receive full data)+# [custom_posthog.tracing]+# enabled = false # Send AI spans to your PostHog++# Privacy controls for data sent to YOUR PostHog only+# [custom_posthog.tracing.capture]+# content = false # Capture prompt/completion content+# content_max_length = 1000 # Max length for captured content (omit for unlimited)+# pipe_codes = false # Include pipe codes in span names/attributes+# output_class_names = false # Include output class names in span names/attributes++# ──────────────────────────────────────────────────────────────────────────────+# Portkey SDK Configuration+# ──────────────────────────────────────────────────────────────────────────────++# [custom_portkey]+# force_debug_enabled = false+# force_tracing_enabled = false++# ──────────────────────────────────────────────────────────────────────────────+# Langfuse Integration+# Note: Langfuse receives FULL span data (no redaction)+# ──────────────────────────────────────────────────────────────────────────────++# [langfuse]+# enabled = false+# endpoint = "https://cloud.langfuse.com" # Override for self-hosted Langfuse+# public_key = "${LANGFUSE_PUBLIC_KEY}"+# secret_key = "${LANGFUSE_SECRET_KEY}"++# ──────────────────────────────────────────────────────────────────────────────+# Additional OTLP Exporters (array for multiple)+# Note: OTLP exporters receive FULL span data (no redaction)+# ──────────────────────────────────────────────────────────────────────────────++# [[otlp]]+# name = "my-collector"+# endpoint = "https://..."+# headers = { Authorization = "Bearer ${OTLP_AUTH_TOKEN}" }++# ──────────────────────────────────────────────────────────────────────────────+# Custom Telemetry Allowed Modes+# Controls which integration modes can use custom telemetry settings above.+# Defaults live in the Pydantic model (TelemetryConfig.telemetry_allowed_modes).+# ──────────────────────────────────────────────────────────────────────────────++# [telemetry_allowed_modes]+# ci = false+# cli = true+# docker = true+# fastapi = true+# mcp = true+# n8n = true+# pytest = false+# python = falsediff --git a/pipelex/kit/configs/telemetry.toml b/pipelex/kit/configs/telemetry.tomlindex ed9a90901..56271ec7d 100644--- a/pipelex/kit/configs/telemetry.toml+++ b/pipelex/kit/configs/telemetry.toml@@ -79,14 +79,18 @@ enabled = false# ──────────────────────────────────────────────────────────────────────────────# Custom Telemetry Allowed Modes# Controls which integration modes can use custom telemetry settings above.+# Defaults live in the Pydantic model (TelemetryConfig.telemetry_allowed_modes):+# ci=false, cli=true, docker=true, fastapi=true, mcp=true, n8n=true,+# pytest=false, python=false+# Uncomment below to override.# ──────────────────────────────────────────────────────────────────────────────-[telemetry_allowed_modes]-ci = false # CI environments don't use custom telemetry-cli = true # CLI usage allows custom telemetry-docker = true # Docker deployments allow custom telemetry-fastapi = true # FastAPI integrations allow custom telemetry-mcp = true # MCP integrations allow custom telemetry-n8n = true # n8n integrations allow custom telemetry-pytest = false # Tests don't use custom telemetry-python = false # Direct Python SDK usage doesn't use custom telemetry by default+# [telemetry_allowed_modes]+# ci = false # CI environments don't use custom telemetry+# cli = true # CLI usage allows custom telemetry+# docker = true # Docker deployments allow custom telemetry+# fastapi = true # FastAPI integrations allow custom telemetry+# mcp = true # MCP integrations allow custom telemetry+# n8n = true # n8n integrations allow custom telemetry+# pytest = false # Tests don't use custom telemetry+# python = false # Direct Python SDK usage doesn't use custom telemetry by defaultdiff --git a/pipelex/kit/paths.py b/pipelex/kit/paths.pyindex 266b57871..0848faa3a 100644--- a/pipelex/kit/paths.py+++ b/pipelex/kit/paths.py@@ -7,12 +7,15 @@ from pipelex.types import Traversable# - pipelex_service.toml: Contains terms_accepted (False for new users, True for devs)# - pipelex_override.toml: Personal config overrides# - telemetry_override.toml: Personal telemetry settings+# - telemetry.project.toml: Kit-internal commented-out template used by project init+# only; must never be propagated into ~/.pipelex/ or a project's .pipelex/ as-isGIT_IGNORED_CONFIG_FILES: frozenset[str] = frozenset({".DS_Store","pipelex_service.toml","pipelex_override.toml","telemetry_override.toml",+ "telemetry.project.toml","pipelex_gateway_models.md", # Auto-generated from remote config"pipelex_gateway_models_plain.md", # Auto-generated from remote config# Custom deck files differ intentionally: kit templates have waterfalls@@ -23,9 +26,10 @@ GIT_IGNORED_CONFIG_FILES: frozenset[str] = frozenset()# Files excluded from config sync checks but still copied during `pipelex init config`.-# Currently equals GIT_IGNORED_CONFIG_FILES; kept as a separate variable so that-# additional auto-generated or environment-specific files can be excluded independently.-CONFIG_SYNC_EXCLUDED_FILES: frozenset[str] = GIT_IGNORED_CONFIG_FILES+# Extends GIT_IGNORED_CONFIG_FILES with `telemetry.toml`: the kit's `telemetry.toml`+# holds the active global template, while the pipelex repo's `.pipelex/telemetry.toml`+# dogfoods the commented-out project template. The two files intentionally differ.+CONFIG_SYNC_EXCLUDED_FILES: frozenset[str] = GIT_IGNORED_CONFIG_FILES | {"telemetry.toml"}# Directories that should not be synced between .pipelex and kit/configs.# These are runtime directories created locally:diff --git a/pipelex/system/configuration/config_loader.py b/pipelex/system/configuration/config_loader.pyindex 4bde9346e..ee143f243 100644--- a/pipelex/system/configuration/config_loader.py+++ b/pipelex/system/configuration/config_loader.py@@ -166,58 +166,81 @@ class ConfigLoader:write_manifest(global_dir / "inference" / "deck", compute_kit_manifest())+ @classmethod+ def _override_files_for_dir(cls, config_dir: Path, include_run_mode: bool) -> list[Path]:+ """Build the override file sequence for a single config dir.++ Order matters: later files win on key collisions during deep-merge.++ Args:+ config_dir: The .pipelex directory to look in.+ include_run_mode: When False, omit the `pipelex_{run_mode}.toml` entry.+ Used under unit testing so the run_mode file is sourced only from+ `./tests/` and not from per-dir overrides.++ Returns:+ Ordered list of candidate file paths (missing files are ignored at load time).+ """+ files = [+ config_dir / "pipelex_local.toml",+ config_dir / f"pipelex_{runtime_manager.environment}.toml",+ ]+ if include_run_mode:+ files.append(config_dir / f"pipelex_{runtime_manager.run_mode}.toml")+ files.append(config_dir / "pipelex_override.toml")+ files.append(config_dir / "pipelex_temporary_override.toml")+ return files+def load_config(self, extra_overrides: dict[str, Any] | None = None) -> dict[str, Any]:"""Load and merge configurations from pipelex and local config files.- The configuration is loaded and merged in the following order:- 1. Base pipelex config (pipelex/pipelex.toml — package defaults)- 2. Global config (~/.pipelex/pipelex.toml)- 3. Project config ({project_root}/.pipelex/pipelex.toml, if found)- 4. Override configs from effective config dir in sequence:- - pipelex_local.toml (local execution)+ The configuration is loaded and deep-merged in the following order+ (later wins per leaf key):++ 1. Package defaults (pipelex/pipelex.toml)+ 2. Global base (~/.pipelex/pipelex.toml)+ 3. Global override sequence (from ~/.pipelex/):+ - pipelex_local.toml- pipelex_{environment}.toml- - pipelex_{run_mode}.toml- - pipelex_override.toml (user's final override)- - pipelex_temporary_override.toml (ephemeral, safe for tools to create/delete)+ - pipelex_{run_mode}.toml (omitted under unit testing — see below)+ - pipelex_override.toml+ - pipelex_temporary_override.toml+ 4. Project base ({project_root}/.pipelex/pipelex.toml, if found and+ distinct from the global dir)+ 5. Project override sequence (same five files as step 3, from the+ project's .pipelex/), if the project dir is distinct from global+ 6. Programmatic `extra_overrides`, if any++ Unit-testing special case: when `runtime_manager.is_unit_testing` is+ true, the `pipelex_{run_mode}.toml` entry is sourced exclusively from+ `./tests/pipelex_{run_mode}.toml` and is layered at the highest run_mode+ precedence. Global and project run_mode files are not loaded, to keep+ test runs hermetic.Returns:dict[str, Any]: The merged configuration dictionary"""self.ensure_global_config_exists()- list_of_configs: list[Path] = []-- # 1. Pipelex package defaults- list_of_configs.append(self.pipelex_root_dir / CONFIG_NAME)+ is_unit_testing = runtime_manager.is_unit_testing+ project_dir = self.project_config_dir- # 2. Global config- list_of_configs.append(self.global_config_dir / CONFIG_NAME)+ list_of_configs: list[Path] = [+ self.pipelex_root_dir / CONFIG_NAME,+ self.global_config_dir / CONFIG_NAME,+ ]+ list_of_configs.extend(+ self._override_files_for_dir(self.global_config_dir, include_run_mode=not is_unit_testing),+ )- # 3. Project config (if different from global)- project_dir = self.project_config_dirif project_dir is not None and project_dir != self.global_config_dir:list_of_configs.append(project_dir / CONFIG_NAME)+ list_of_configs.extend(+ self._override_files_for_dir(project_dir, include_run_mode=not is_unit_testing),+ )- # Effective config dir for overrides- effective_config_dir = self.pipelex_config_dir-- # 4. Override for local execution- list_of_configs.append(effective_config_dir / "pipelex_local.toml")-- # Override for environment- list_of_configs.append(effective_config_dir / f"pipelex_{runtime_manager.environment}.toml")-- # Override for run mode- if runtime_manager.is_unit_testing:+ if is_unit_testing:list_of_configs.append(Path.cwd() / "tests" / f"pipelex_{runtime_manager.run_mode}.toml")- else:- list_of_configs.append(effective_config_dir / f"pipelex_{runtime_manager.run_mode}.toml")-- # Final override- list_of_configs.append(effective_config_dir / "pipelex_override.toml")-- # Temporary override (e.g. for testing tools — safe to create/delete)- list_of_configs.append(effective_config_dir / "pipelex_temporary_override.toml")merged = load_toml_from_path_and_merge_with_overrides(paths=list_of_configs)if extra_overrides:diff --git a/pipelex/system/telemetry/telemetry_config.py b/pipelex/system/telemetry/telemetry_config.pyindex d60ee2857..db141e2b7 100644--- a/pipelex/system/telemetry/telemetry_config.py+++ b/pipelex/system/telemetry/telemetry_config.py@@ -17,6 +17,12 @@ from pipelex.types import Self, StrEnumTELEMETRY_CONFIG_FILE_NAME = "telemetry.toml"TELEMETRY_CONFIG_OVERRIDE_FILE_NAME = "telemetry_override.toml"+# Kit template used when populating a project's `.pipelex/`. Every setting is commented+# out so the project file does not shadow `~/.pipelex/telemetry.toml` or+# `~/.pipelex/telemetry_override.toml` during layered config loading. Kit-internal:+# this filename never appears in `~/.pipelex/` or in a project's `.pipelex/` — it is+# always renamed to `telemetry.toml` on copy.+TELEMETRY_PROJECT_TEMPLATE_FILE_NAME = "telemetry.project.toml"class PostHogMode(StrEnum):@@ -159,8 +165,19 @@ class TelemetryConfig(ConfigModel):langfuse: LangfuseConfig = Field(default_factory=LangfuseConfig, description="Langfuse configuration")otlp: list[OtlpExporterConfig] = Field(default_factory=empty_list_factory_of(OtlpExporterConfig), description="Additional OTLP exporters")telemetry_allowed_modes: dict[str, bool] = Field(- default_factory=dict,- description="Which integration modes allow custom telemetry (e.g. cli=true, pytest=false)",+ default_factory=lambda: {+ "ci": False,+ "cli": True,+ "docker": True,+ "fastapi": True,+ "mcp": True,+ "n8n": True,+ "pytest": False,+ "python": False,+ },+ description="Which integration modes allow custom telemetry (e.g. cli=true, pytest=false). "+ "Defaults live here so a project-level telemetry.toml that omits the section "+ "doesn't silently disable custom telemetry for everyone.",)pipelex_gateway: PipelexGatewayTelemetryConfig | None = Field(default=None, description="Pipelex Gateway telemetry configuration")@@ -224,6 +241,18 @@ class TelemetryRedactionConfig(BaseModel):def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> TelemetryConfig:"""Load telemetry configuration from a TOML file with variable substitution.+ Files are deep-merged in this order (later wins per leaf key):++ 1. ~/.pipelex/telemetry.toml (global base)+ 2. ~/.pipelex/telemetry_override.toml+ 3. {project_root}/.pipelex/telemetry.toml (if project dir exists and is+ distinct from the global dir)+ 4. {project_root}/.pipelex/telemetry_override.toml (same condition)++ This means a project telemetry config layers *on top of* the user's global+ one rather than replacing it — secrets and personal observability settings+ declared once in ~/.pipelex/ stay in effect across all projects.+Supports variable placeholders in string values:- ${VAR_NAME} -> use secrets provider by default- ${env:ENV_VAR_NAME} -> force use environment variable@@ -239,10 +268,15 @@ def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> TelemetrRaises:TelemetryConfigValidationError: If configuration is invalid or variable substitution fails."""+ global_config_dir = config_manager.global_config_dirtelemetry_config_paths = [- config_manager.pipelex_config_dir / TELEMETRY_CONFIG_FILE_NAME,- config_manager.pipelex_config_dir / TELEMETRY_CONFIG_OVERRIDE_FILE_NAME,+ global_config_dir / TELEMETRY_CONFIG_FILE_NAME,+ global_config_dir / TELEMETRY_CONFIG_OVERRIDE_FILE_NAME,]+ project_config_dir = config_manager.project_config_dir+ if project_config_dir is not None and project_config_dir != global_config_dir:+ telemetry_config_paths.append(project_config_dir / TELEMETRY_CONFIG_FILE_NAME)+ telemetry_config_paths.append(project_config_dir / TELEMETRY_CONFIG_OVERRIDE_FILE_NAME)telemetry_config_toml_raw = load_toml_from_path_and_merge_with_overrides(paths=telemetry_config_paths)# Apply variable substitution to all string values (keep placeholders for missing vars)diff --git a/tests/integration/pipelex/cli/test_init_cmd_integration.py b/tests/integration/pipelex/cli/test_init_cmd_integration.pyindex fe05a02db..b1947ebae 100644--- a/tests/integration/pipelex/cli/test_init_cmd_integration.py+++ b/tests/integration/pipelex/cli/test_init_cmd_integration.py@@ -179,6 +179,32 @@ class TestInitCommandIntegration:# Verify telemetry was created with default mode (off)env.verify_telemetry("off")+ def test_init_telemetry_project_uses_commented_template(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """Project-targeted telemetry init must drop the commented-out template so it+ doesn't shadow the user's global telemetry settings.+ """+ env = MockedInitEnvironment(tmp_path, mocker)+ env.setup_with_configs(include_backends=True, include_routing=True, include_telemetry=False)++ env.add_confirm_input(True) # Confirm initialization+ env.setup_mocks()++ init_cmd(focus=InitFocus.TELEMETRY, local=True)++ telemetry_path = env.pipelex_dir / "telemetry.toml"+ assert telemetry_path.exists()+ content = telemetry_path.read_text(encoding="utf-8")+ # Every non-blank line in the project template must be a comment — no active+ # assignments are allowed, otherwise the file would shadow global telemetry settings.+ for raw_line in content.splitlines():+ line = raw_line.strip()+ if not line:+ continue+ assert line.startswith("#"), f"Project template should be fully commented; found active line: {raw_line!r}"+ # Still documents available knobs as "invitation to override" markers.+ assert "# [custom_posthog]" in content+ assert "# [langfuse]" in content+def test_init_with_reset_flag(self, tmp_path: Path, mocker: MockerFixture) -> None:"""Test initialization with reset flag overwrites existing config."""# Setup environment with existing configdiff --git a/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py b/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.pynew file mode 100644index 000000000..db7a04c27--- /dev/null+++ b/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py@@ -0,0 +1,214 @@+"""Tests for layered telemetry config loading.++Validates that ~/.pipelex/telemetry.toml and ~/.pipelex/telemetry_override.toml+are layered under the project's equivalents instead of being silently shadowed.+"""++from __future__ import annotations++import shutil+from pathlib import Path+from typing import TYPE_CHECKING++import pytest++from pipelex.kit.paths import get_kit_configs_dir+from pipelex.system.telemetry import telemetry_config as telemetry_config_module+from pipelex.system.telemetry.telemetry_config import load_telemetry_config+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++class TestLoadTelemetryConfigLayering:+ """Cover global → project layering for telemetry.toml and telemetry_override.toml."""++ @pytest.fixture+ def fake_dirs(self, tmp_path: Path, mocker: MockerFixture) -> tuple[Path, Path]:+ """Set up a fake home + project tree and patch Path.home / Path.cwd."""+ fake_home = tmp_path / "home"+ fake_home.mkdir()+ global_dir = fake_home / ".pipelex"+ global_dir.mkdir()++ project_root = tmp_path / "project"+ (project_root / ".git").mkdir(parents=True)+ project_dir = project_root / ".pipelex"+ project_dir.mkdir()++ mocker.patch.object(Path, "home", return_value=fake_home)+ mocker.patch.object(Path, "cwd", return_value=project_root)++ return global_dir, project_dir++ @pytest.fixture+ def secrets_provider(self) -> EnvSecretsProvider:+ return EnvSecretsProvider()++ @pytest.mark.usefixtures("fake_dirs")+ def test_empty_returns_defaults(self, secrets_provider: EnvSecretsProvider) -> None:+ """No config files at any layer → defaults from pydantic model."""+ config = load_telemetry_config(secrets_provider=secrets_provider)++ assert config.langfuse.enabled is False+ assert config.langfuse.public_key is None++ def test_global_config_applies_when_no_project_config(self, fake_dirs: tuple[Path, Path], secrets_provider: EnvSecretsProvider) -> None:+ """Settings declared in ~/.pipelex/telemetry.toml are picked up."""+ global_dir, _ = fake_dirs+ (global_dir / "telemetry.toml").write_text(+ '[langfuse]\nenabled = true\npublic_key = "pk_global"\nsecret_key = "sk_global"\n',+ )++ config = load_telemetry_config(secrets_provider=secrets_provider)++ assert config.langfuse.enabled is True+ assert config.langfuse.public_key == "pk_global"+ assert config.langfuse.secret_key == "sk_global"++ def test_project_config_layers_over_global(self, fake_dirs: tuple[Path, Path], secrets_provider: EnvSecretsProvider) -> None:+ """Keys set only in global telemetry.toml survive when project sets other keys."""+ global_dir, project_dir = fake_dirs+ (global_dir / "telemetry.toml").write_text(+ '[langfuse]\nenabled = true\npublic_key = "pk_global"\nsecret_key = "sk_global"\n',+ )+ (project_dir / "telemetry.toml").write_text(+ '[langfuse]\nendpoint = "https://project.langfuse.example"\n',+ )++ config = load_telemetry_config(secrets_provider=secrets_provider)++ # Project added endpoint without redefining keys → global keys survive.+ assert config.langfuse.enabled is True+ assert config.langfuse.public_key == "pk_global"+ assert config.langfuse.secret_key == "sk_global"+ assert config.langfuse.endpoint == "https://project.langfuse.example"++ def test_project_override_wins_over_global_on_collision(self, fake_dirs: tuple[Path, Path], secrets_provider: EnvSecretsProvider) -> None:+ """When a key is defined at both layers, the project value wins."""+ global_dir, project_dir = fake_dirs+ (global_dir / "telemetry.toml").write_text('[langfuse]\nenabled = true\npublic_key = "pk_global"\n')+ (project_dir / "telemetry.toml").write_text('[langfuse]\npublic_key = "pk_project"\n')++ config = load_telemetry_config(secrets_provider=secrets_provider)++ assert config.langfuse.enabled is True # from global+ assert config.langfuse.public_key == "pk_project" # from project++ def test_override_files_layer_after_base_files(self, fake_dirs: tuple[Path, Path], secrets_provider: EnvSecretsProvider) -> None:+ """telemetry_override.toml at either layer wins over telemetry.toml at that layer."""+ global_dir, project_dir = fake_dirs+ (global_dir / "telemetry.toml").write_text('[langfuse]\nenabled = true\npublic_key = "pk_global_base"\n')+ (global_dir / "telemetry_override.toml").write_text('[langfuse]\npublic_key = "pk_global_override"\n')+ (project_dir / "telemetry.toml").write_text('[langfuse]\nsecret_key = "sk_project_base"\n')+ (project_dir / "telemetry_override.toml").write_text('[langfuse]\nsecret_key = "sk_project_override"\n')++ config = load_telemetry_config(secrets_provider=secrets_provider)++ assert config.langfuse.enabled is True # global base, never overridden+ assert config.langfuse.public_key == "pk_global_override" # global override beats global base+ assert config.langfuse.secret_key == "sk_project_override" # project override beats project base++ def test_project_layer_skipped_when_no_project_pipelex_dir(+ self, tmp_path: Path, mocker: MockerFixture, secrets_provider: EnvSecretsProvider+ ) -> None:+ """When cwd has no `.pipelex/`, `project_config_dir` resolves to None and only the+ global layers are loaded — the project-layer branch is never entered.+ """+ fake_home = tmp_path / "home"+ fake_home.mkdir()+ global_dir = fake_home / ".pipelex"+ global_dir.mkdir()+ (global_dir / "telemetry.toml").write_text('[langfuse]\npublic_key = "pk_global"\n')++ project_root = tmp_path / "project"+ (project_root / ".git").mkdir(parents=True)+ # No project .pipelex/ — project_config_dir resolves to None.++ mocker.patch.object(Path, "home", return_value=fake_home)+ mocker.patch.object(Path, "cwd", return_value=project_root)++ config = load_telemetry_config(secrets_provider=secrets_provider)++ assert config.langfuse.public_key == "pk_global"++ def test_project_layer_skipped_when_project_dir_equals_global_dir(+ self, tmp_path: Path, mocker: MockerFixture, secrets_provider: EnvSecretsProvider+ ) -> None:+ """When the user runs from their home directory itself, project-root detection lands+ on `~`, so `project_config_dir` resolves to `~/.pipelex/` — the same path as+ `global_config_dir`. The project-layer branch must be skipped to avoid double-loading+ the same files. This test spies on the toml loader to assert the paths list is the+ global-only sequence, not the global-then-project doubled sequence.+ """+ fake_home = tmp_path / "home"+ fake_home.mkdir()+ # Make the home directory itself a project root so project_root detection picks it.+ (fake_home / ".git").mkdir()+ global_dir = fake_home / ".pipelex"+ global_dir.mkdir()+ (global_dir / "telemetry.toml").write_text('[langfuse]\npublic_key = "pk_global"\n')+ (global_dir / "telemetry_override.toml").write_text('[langfuse]\nsecret_key = "sk_global"\n')++ mocker.patch.object(Path, "home", return_value=fake_home)+ mocker.patch.object(Path, "cwd", return_value=fake_home)++ spy = mocker.spy(telemetry_config_module, "load_toml_from_path_and_merge_with_overrides")++ config = load_telemetry_config(secrets_provider=secrets_provider)++ # Skip guard fired: paths list contains only the two global-layer entries, not four.+ spy.assert_called_once()+ paths_passed = spy.call_args.kwargs["paths"]+ assert paths_passed == [+ global_dir / "telemetry.toml",+ global_dir / "telemetry_override.toml",+ ]+ # Sanity: merged config still reflects the global values.+ assert config.langfuse.public_key == "pk_global"+ assert config.langfuse.secret_key == "sk_global"++ def test_commented_project_template_does_not_shadow_global_override(+ self, fake_dirs: tuple[Path, Path], secrets_provider: EnvSecretsProvider+ ) -> None:+ """The kit's project template is fully commented out, so dropping it into a+ project's .pipelex/ must not override globally-enabled telemetry.++ This is the regression guard for the bug Codex flagged: prior to splitting the+ kit template, the project copy carried explicit `enabled = false` defaults that+ silently disabled Langfuse in every initialized project even when the user had+ enabled it globally.+ """+ global_dir, project_dir = fake_dirs+ (global_dir / "telemetry_override.toml").write_text(+ '[langfuse]\nenabled = true\npublic_key = "pk_global"\nsecret_key = "sk_global"\n',+ )+ # Copy the actual kit project template (the one shipped to users via init).+ kit_project_template = Path(str(get_kit_configs_dir())) / "telemetry.project.toml"+ shutil.copy2(kit_project_template, project_dir / "telemetry.toml")++ config = load_telemetry_config(secrets_provider=secrets_provider)++ assert config.langfuse.enabled is True+ assert config.langfuse.public_key == "pk_global"+ assert config.langfuse.secret_key == "sk_global"++ @pytest.mark.usefixtures("fake_dirs")+ def test_telemetry_allowed_modes_defaults_from_pydantic(self, secrets_provider: EnvSecretsProvider) -> None:+ """`telemetry_allowed_modes` defaults must live in the Pydantic model so a project+ telemetry.toml that omits the section doesn't silently disable custom telemetry+ for cli/docker/fastapi/etc.+ """+ config = load_telemetry_config(secrets_provider=secrets_provider)++ assert config.is_custom_telemetry_allowed_for_mode("cli") is True+ assert config.is_custom_telemetry_allowed_for_mode("docker") is True+ assert config.is_custom_telemetry_allowed_for_mode("fastapi") is True+ assert config.is_custom_telemetry_allowed_for_mode("mcp") is True+ assert config.is_custom_telemetry_allowed_for_mode("n8n") is True+ assert config.is_custom_telemetry_allowed_for_mode("ci") is False+ assert config.is_custom_telemetry_allowed_for_mode("pytest") is False+ assert config.is_custom_telemetry_allowed_for_mode("python") is False+ # Unknown modes still fall back to False.+ assert config.is_custom_telemetry_allowed_for_mode("does_not_exist") is Falsediff --git a/tests/unit/pipelex/system/test_load_config_layering.py b/tests/unit/pipelex/system/test_load_config_layering.pynew file mode 100644index 000000000..e1e92c20c--- /dev/null+++ b/tests/unit/pipelex/system/test_load_config_layering.py@@ -0,0 +1,163 @@+"""Tests for layered override loading in ConfigLoader.load_config().++Validates that global and project override files are both layered, with project+on top, instead of project shadowing global entirely.+"""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++import pytest++from pipelex.system.configuration.config_loader import ConfigLoader+from pipelex.system.runtime import RunEnvironment, RunMode, RuntimeManager++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++class TestLoadConfigLayering:+ """Cover the four-layer merge: package → global base → global override → project base → project override."""++ @pytest.fixture+ def fake_dirs(self, tmp_path: Path, mocker: MockerFixture) -> tuple[Path, Path]:+ """Set up a fake home + project tree and patch Path.home / Path.cwd.++ Returns:+ Tuple of (global_pipelex_dir, project_pipelex_dir). Caller writes+ override files into either dir as needed.+ """+ fake_home = tmp_path / "home"+ fake_home.mkdir()+ global_dir = fake_home / ".pipelex"+ global_dir.mkdir()++ project_root = tmp_path / "project"+ (project_root / ".git").mkdir(parents=True)+ project_dir = project_root / ".pipelex"+ project_dir.mkdir()++ mocker.patch.object(Path, "home", return_value=fake_home)+ mocker.patch.object(Path, "cwd", return_value=project_root)++ # Force non-unit-testing run_mode and a fixed environment so the test+ # exercises the standard override sequence rather than the hermetic+ # ./tests/ branch.+ mocker.patch.object(RuntimeManager, "run_mode", new=RunMode.NORMAL)+ mocker.patch.object(RuntimeManager, "environment", new=RunEnvironment.DEV)++ return global_dir, project_dir++ def test_global_override_survives_when_project_base_does_not_set_key(self, fake_dirs: tuple[Path, Path]) -> None:+ """A leaf key set only in the global override is preserved under the project base."""+ global_dir, project_dir = fake_dirs+ (global_dir / "pipelex_override.toml").write_text('[section]\nkey_only_in_global = "from_global_override"\n')+ (project_dir / "pipelex.toml").write_text('[section]\nkey_only_in_project = "from_project_base"\n')++ merged = ConfigLoader().load_config()++ assert merged["section"]["key_only_in_global"] == "from_global_override"+ assert merged["section"]["key_only_in_project"] == "from_project_base"++ def test_project_override_wins_over_global_override(self, fake_dirs: tuple[Path, Path]) -> None:+ """Project override is the last loaded layer for a colliding key."""+ global_dir, project_dir = fake_dirs+ (global_dir / "pipelex_override.toml").write_text('[section]\nshared_key = "from_global_override"\n')+ (project_dir / "pipelex_override.toml").write_text('[section]\nshared_key = "from_project_override"\n')++ merged = ConfigLoader().load_config()++ assert merged["section"]["shared_key"] == "from_project_override"++ def test_project_base_wins_over_global_override(self, fake_dirs: tuple[Path, Path]) -> None:+ """Project base is layered AFTER global overrides, so it wins on collisions."""+ global_dir, project_dir = fake_dirs+ (global_dir / "pipelex_override.toml").write_text('[section]\nshared_key = "from_global_override"\n')+ (project_dir / "pipelex.toml").write_text('[section]\nshared_key = "from_project_base"\n')++ merged = ConfigLoader().load_config()++ assert merged["section"]["shared_key"] == "from_project_base"++ def test_env_override_layered_at_both_levels(self, fake_dirs: tuple[Path, Path]) -> None:+ """Env-specific override files are picked up at both global and project layers."""+ global_dir, project_dir = fake_dirs+ (global_dir / "pipelex_dev.toml").write_text('[section]\nfrom_global_env = "yes"\nshared = "global"\n')+ (project_dir / "pipelex_dev.toml").write_text('[section]\nfrom_project_env = "yes"\nshared = "project"\n')++ merged = ConfigLoader().load_config()++ assert merged["section"]["from_global_env"] == "yes"+ assert merged["section"]["from_project_env"] == "yes"+ assert merged["section"]["shared"] == "project"++ def test_no_project_dir_only_global_layers_load(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """When no project .pipelex/ exists, only the global stack is loaded."""+ fake_home = tmp_path / "home"+ fake_home.mkdir()+ global_dir = fake_home / ".pipelex"+ global_dir.mkdir()+ (global_dir / "pipelex_override.toml").write_text('[section]\nkey = "from_global"\n')++ project_root = tmp_path / "project"+ (project_root / ".git").mkdir(parents=True)+ # Deliberately no .pipelex/ in project.++ mocker.patch.object(Path, "home", return_value=fake_home)+ mocker.patch.object(Path, "cwd", return_value=project_root)+ mocker.patch.object(RuntimeManager, "run_mode", new=RunMode.NORMAL)+ mocker.patch.object(RuntimeManager, "environment", new=RunEnvironment.DEV)++ merged = ConfigLoader().load_config()++ assert merged["section"]["key"] == "from_global"++ def test_unit_testing_run_mode_replaces_both_layers(self, fake_dirs: tuple[Path, Path], tmp_path: Path, mocker: MockerFixture) -> None:+ """Under unit testing, only ./tests/pipelex_unit_test.toml feeds the run_mode slot.++ Global and project pipelex_unit_test.toml files must be ignored to keep+ test runs hermetic regardless of machine-wide overrides.+ """+ global_dir, project_dir = fake_dirs+ # Override the fixture's RunMode patch — we want unit testing here.+ mocker.patch.object(RuntimeManager, "run_mode", new=RunMode.UNIT_TEST)++ (global_dir / "pipelex_unit_test.toml").write_text('[section]\nfrom_layer = "global"\n')+ (project_dir / "pipelex_unit_test.toml").write_text('[section]\nfrom_layer = "project"\n')++ tests_dir = tmp_path / "project" / "tests"+ tests_dir.mkdir()+ (tests_dir / "pipelex_unit_test.toml").write_text('[section]\nfrom_layer = "tests_dir"\n')++ merged = ConfigLoader().load_config()++ assert merged["section"]["from_layer"] == "tests_dir"++ def test_extra_overrides_win_last(self, fake_dirs: tuple[Path, Path]) -> None:+ """Programmatic extra_overrides override every file layer."""+ _, project_dir = fake_dirs+ (project_dir / "pipelex_override.toml").write_text('[section]\nkey = "from_project_override"\n')++ merged = ConfigLoader().load_config(extra_overrides={"section": {"key": "from_extra"}})++ assert merged["section"]["key"] == "from_extra"++ def test_temporary_override_wins_within_each_layer(self, fake_dirs: tuple[Path, Path]) -> None:+ """`pipelex_temporary_override.toml` is the last file in each layer's sequence.++ Within the global layer it beats `pipelex_override.toml`. The project's+ temporary_override then beats everything from the global layer.+ """+ global_dir, project_dir = fake_dirs+ (global_dir / "pipelex_override.toml").write_text('[section]\nglobal_key = "from_global_override"\n')+ (global_dir / "pipelex_temporary_override.toml").write_text(+ '[section]\nglobal_key = "from_global_temp"\nshared = "global_temp"\n',+ )+ (project_dir / "pipelex_temporary_override.toml").write_text('[section]\nshared = "project_temp"\n')++ merged = ConfigLoader().load_config()++ assert merged["section"]["global_key"] == "from_global_temp"+ assert merged["section"]["shared"] == "project_temp"