Skip to content

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.toml
index 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 = false
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-07
diff --git a/docs/configuration/config-practical/telemetry-config.md b/docs/configuration/config-practical/telemetry-config.md
index 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 contro
This 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
```toml
diff --git a/docs/contribute/configuration-defaults-and-overrides.md b/docs/contribute/configuration-defaults-and-overrides.md
index 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](../configu
Pipelex 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 code
diff --git a/docs/setup/telemetry.md b/docs/setup/telemetry.md
index 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 cr
pipelex 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 Tracing
diff --git a/docs/under-the-hood/init-cli-flows.md b/docs/under-the-hood/init-cli-flows.md
index 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 Modules
diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.py
index 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_NAME
from pipelex.tools.misc.file_utils import path_exists
from 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_name
target_path = target_dir / TELEMETRY_CONFIG_FILE_NAME
target_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_gateway
is 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 backends
template_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.py
index 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 needed
if 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.py
index 087da9538..6f0e94e60 100644
--- a/pipelex/cli/commands/init/telemetry.py
+++ b/pipelex/cli/commands/init/telemetry.py
@@ -6,31 +6,41 @@ import shutil
from rich.console import Console
from 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.toml
new file mode 100644
index 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 = false
diff --git a/pipelex/kit/configs/telemetry.toml b/pipelex/kit/configs/telemetry.toml
index 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 default
diff --git a/pipelex/kit/paths.py b/pipelex/kit/paths.py
index 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-is
GIT_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.py
index 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_dir
if 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.py
index 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, StrEnum
TELEMETRY_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) -> Telemetr
Raises:
TelemetryConfigValidationError: If configuration is invalid or variable substitution fails.
"""
+ global_config_dir = config_manager.global_config_dir
telemetry_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.py
index 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 config
diff --git a/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py b/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py
new file mode 100644
index 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 False
diff --git a/tests/unit/pipelex/system/test_load_config_layering.py b/tests/unit/pipelex/system/test_load_config_layering.py
new file mode 100644
index 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"