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: address PR #898 review comments

Louis Choquel83c1b6cac9ba
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-07
diff --git a/docs/building-methods/pipes/pipe-operators/PipeLLM.md b/docs/building-methods/pipes/pipe-operators/PipeLLM.md
index 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 Fields
diff --git a/docs/setup/telemetry.md b/docs/setup/telemetry.md
index 754e39566..a2fce9854 100644
--- a/docs/setup/telemetry.md
+++ b/docs/setup/telemetry.md
@@ -56,7 +56,7 @@ pipelex init telemetry
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.
+- **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.py
index 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)
+ continue
for 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.py
index 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 = None
for 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_path
break
+ 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.py
index 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 a
legal identifier.
"""
+import re
+import sys
import tempfile
from pathlib import Path
+from types import ModuleType
from pipelex.cli.commands.build.structures_cmd import generate_structures_from_blueprints
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
@@ -18,28 +21,40 @@ from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.stuffs.structured_content import StructuredContent
from 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_module
get_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)