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: address PR #898 review comments
Louis Choquel83c1b6cac9ba
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6716af16b..4239a4b95 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,6 +18,7 @@- **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`.+- **`pipelex build structures` cross-package refines now emit the base-class import.** A concept that refines a class defined in another already-installed package (e.g. `RefiningConcept` with `refines: some_alias->other_domain.OtherConcept`) was generating a file that inherited from `other_domain__OtherConcept` without importing it. `StructureGenerator._validate_execution` injects the base class into `exec_globals` from the class registry, so codegen-time validation passed; the failure surfaced only when the generated structures module was later loaded via the normal Python import system, raising `NameError: name 'other_domain__OtherConcept' is not defined`. The generator now falls back to the class registry's `__module__` when `concept_ref_to_class_info` has no entry for the base class and emits the corresponding import (guarded on `cls.__name__ == base_class` so we never emit a name the target module won't expose). Regression test in `tests/unit/pipelex/cli/commands/build/test_structures_cmd_cross_package_refines.py` was tightened to assert the import statement is present.## [v0.27.0] - 2026-05-07diff --git a/docs/building-methods/pipes/pipe-operators/PipeLLM.md b/docs/building-methods/pipes/pipe-operators/PipeLLM.mdindex 737c120b4..742a2d3a8 100644--- a/docs/building-methods/pipes/pipe-operators/PipeLLM.md+++ b/docs/building-methods/pipes/pipe-operators/PipeLLM.md@@ -222,7 +222,7 @@ Analyze the document and explain how it relates to the context: $reference_doc| `model` | string or table | Specifies the LLM choice by name, setting, or preset to use. | No || `model_to_structure` | string or table | Specifies the LLM choice by name, setting, or preset to use for structuring after preliminary text generation. | No || `system_prompt` | string | A system-level prompt to guide the LLM's behavior (e.g., "You are a helpful assistant"). Supports the same variable syntax as `prompt`, including image and document references. | No |-| `prompt` | string | A template for the user prompt. Use `$` for inline variables (e.g., `$topic`) and `@` to insert the content of an entire input (e.g., `@text_to_summarize`). Image and document variables should also be tagged with `$` or `@`. Escape with `@@` or `$$` to emit a literal `@` or `$` (e.g., `@@font-face` inside a `<style>` block). | No |+| `prompt` | string | A template for the user prompt. Use `$` for inline variables (e.g., `$topic`). Use `@input_name` as a block sigil on its own line to insert the content of an entire input — inline `@var` raises `TemplateSigilSyntaxError` when `var` collides with a declared input. Image and document variables follow the same rules. Escape with `@@` or `$$` to emit a literal `@` or `$` (e.g., `@@font-face` inside a `<style>` block). | No || `structuring_method` | string | The method for generating structured output. Can be `direct` or `preliminary_text`. Defaults to the global configuration. | No |### LLM Setting Fieldsdiff --git a/docs/setup/telemetry.md b/docs/setup/telemetry.mdindex 754e39566..a2fce9854 100644--- a/docs/setup/telemetry.md+++ b/docs/setup/telemetry.md@@ -56,7 +56,7 @@ pipelex init telemetryThe 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.+- **Project init** (`pipelex init telemetry --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.diff --git a/pipelex/cogt/templating/template_preprocessor.py b/pipelex/cogt/templating/template_preprocessor.pyindex a808b7c29..5d5c28db6 100644--- a/pipelex/cogt/templating/template_preprocessor.py+++ b/pipelex/cogt/templating/template_preprocessor.py@@ -118,6 +118,7 @@ def _validate_at_sigil_alone_on_line(template: str, declared_inputs: set[str]) -f"you intend a literal `@`.")raise TemplateSigilSyntaxError(msg)+ continuefor candidate in _AT_CANDIDATE_PATTERN.finditer(line):sigil = candidate.group(1)identifier = candidate.group(2)diff --git a/pipelex/core/concepts/structure_generation/generator.py b/pipelex/core/concepts/structure_generation/generator.pyindex 8be90e0e3..4792c682c 100644--- a/pipelex/core/concepts/structure_generation/generator.py+++ b/pipelex/core/concepts/structure_generation/generator.py@@ -273,10 +273,22 @@ class StructureGenerator:self.imports.add(f"from {cls.__module__} import {cls.__name__}")elif base_class != "StructuredContent":# Check if we have module info for this custom base class in concept_ref_to_class_info+ base_module_path: str | None = Nonefor class_info in self.concept_ref_to_class_info.values():if class_info.class_name == base_class and class_info.module_path:- self.imports.add(f"from {class_info.module_path} import {class_info.class_name}")+ base_module_path = class_info.module_pathbreak+ if base_module_path is None:+ # Cross-package refines: the base class lives in another package's+ # already-generated structures module and is not in concept_ref_to_class_info+ # (which only covers the bundles passed to `pipelex build structures`).+ # Recover the import path from the class registry. Guard on+ # __name__ == base_class so we only emit a valid `from X import <base_class>`.+ registered_cls = _get_class_registry().get_class(name=base_class)+ if registered_cls is not None and registered_cls.__name__ == base_class and registered_cls.__module__ not in {"__main__", "builtins"}:+ base_module_path = registered_cls.__module__+ if base_module_path:+ self.imports.add(f"from {base_module_path} import {base_class}")# Generate class header with docstring (use class name if no description provided)docstring = description or f"Generated {class_name} class"diff --git a/tests/unit/pipelex/cli/commands/build/test_structures_cmd_cross_package_refines.py b/tests/unit/pipelex/cli/commands/build/test_structures_cmd_cross_package_refines.pyindex ae858cbda..15573a351 100644--- a/tests/unit/pipelex/cli/commands/build/test_structures_cmd_cross_package_refines.py+++ b/tests/unit/pipelex/cli/commands/build/test_structures_cmd_cross_package_refines.py@@ -9,8 +9,11 @@ generated module then failed to import because the base class name was not alegal identifier."""+import re+import sysimport tempfilefrom pathlib import Path+from types import ModuleTypefrom pipelex.cli.commands.build.structures_cmd import generate_structures_from_blueprintsfrom pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint@@ -18,28 +21,40 @@ from pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.hub import get_class_registry--class _CrossPackageBaseClassStub(StructuredContent):- """Placeholder that stands in for a class registered by another package."""+_FAKE_BASE_MODULE_PATH = "tests_pr898_other_pkg_stub.structures.other_domain__other_concept"class TestStructuresCmdCrossPackageRefines:- def test_cross_package_refine_produces_valid_identifier(self):- """A cross-package refine must produce a clean qualified base class name.+ def _register_cross_package_stub(self) -> type:+ """Register a stub that mimics what another package's `pipelex build structures`+ would have produced for `other_domain.OtherConcept`:- The generated code must contain the domain-qualified class name- (e.g. ``other_domain__OtherConcept``) and must NOT leak the- cross-package alias separator ``->`` into the Python source.+ - The class name equals the registry key (`other_domain__OtherConcept`),+ matching what `ConceptFactory` registers.+ - The class lives at a stable, importable-looking module path on `sys.modules`+ so the generator can recover an import statement from `__module__`."""- # Register a stub for the cross-package base class. In a real scenario- # this would have been registered when the other package's bundle was- # generated; here we register it directly so the generator's validation- # step can resolve the base class.+ stub_module = ModuleType(_FAKE_BASE_MODULE_PATH)+ stub_class: type = type("other_domain__OtherConcept", (StructuredContent,), {"__module__": _FAKE_BASE_MODULE_PATH})+ stub_module.other_domain__OtherConcept = stub_class # type: ignore[attr-defined]+ sys.modules[_FAKE_BASE_MODULE_PATH] = stub_moduleget_class_registry().register_class(- _CrossPackageBaseClassStub,+ stub_class,name="other_domain__OtherConcept",should_warn_if_already_registered=False,)+ return stub_class++ def test_cross_package_refine_produces_valid_identifier(self):+ """A cross-package refine must produce a clean qualified base class name.++ The generated code must contain the domain-qualified class name+ (e.g. ``other_domain__OtherConcept``) and must NOT leak the+ cross-package alias separator ``->`` into the Python source. The+ generated file must also import the base class so it is loadable+ outside the generator's validation harness.+ """+ self._register_cross_package_stub()bundle = PipelexBundleBlueprint(domain="local_domain",@@ -52,29 +67,38 @@ class TestStructuresCmdCrossPackageRefines:},)- with tempfile.TemporaryDirectory() as temp_dir:- output_directory = Path(temp_dir)+ try:+ with tempfile.TemporaryDirectory() as temp_dir:+ output_directory = Path(temp_dir)- generated_files = generate_structures_from_blueprints(- blueprints=[bundle],- output_directory=output_directory,- skip_existing_check=True,- quiet=True,- )+ generated_files = generate_structures_from_blueprints(+ blueprints=[bundle],+ output_directory=output_directory,+ skip_existing_check=True,+ quiet=True,+ )- assert generated_files == [("local_domain", "RefiningConcept")]+ assert generated_files == [("local_domain", "RefiningConcept")]- generated_file = output_directory / "local_domain__refining_concept.py"- assert generated_file.exists(), f"Generated file not found: {generated_file}"+ generated_file = output_directory / "local_domain__refining_concept.py"+ assert generated_file.exists(), f"Generated file not found: {generated_file}"- generated_code = generated_file.read_text()+ generated_code = generated_file.read_text()- assert "->" not in generated_code, (- "Generated code leaked the cross-package alias separator '->' (produces an invalid Python identifier):\n" + generated_code- )- assert "some_alias" not in generated_code, (- "Generated code leaked the cross-package alias name into the class definition:\n" + generated_code- )- assert "class local_domain__RefiningConcept(other_domain__OtherConcept):" in generated_code, (- "Expected generated class to inherit from the qualified cross-package base class. Got:\n" + generated_code- )+ assert "->" not in generated_code, (+ "Generated code leaked the cross-package alias separator '->' (produces an invalid Python identifier):\n" + generated_code+ )+ assert "some_alias" not in generated_code, (+ "Generated code leaked the cross-package alias name into the class definition:\n" + generated_code+ )+ assert "class local_domain__RefiningConcept(other_domain__OtherConcept):" in generated_code, (+ "Expected generated class to inherit from the qualified cross-package base class. Got:\n" + generated_code+ )+ import_pattern = re.compile(r"^from\s+\S+\s+import\s+other_domain__OtherConcept(\s|$)", re.MULTILINE)+ assert import_pattern.search(generated_code), (+ "Generated code is missing an import for the cross-package base class "+ "`other_domain__OtherConcept`. Without it, importing the generated module fails with "+ "`NameError: name 'other_domain__OtherConcept' is not defined`. Got:\n" + generated_code+ )+ finally:+ sys.modules.pop(_FAKE_BASE_MODULE_PATH, None)