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.
Structure class name handling domain-qualified concepts (#874)
Louis Choquel5ce13d1c591b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 45f0c6c91..0101bf2a2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,11 @@# Changelog+## [Unreleased]++### Fixed++- **`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### Changeddiff --git a/pipelex/cli/commands/build/structures_cmd.py b/pipelex/cli/commands/build/structures_cmd.pyindex 2695135ec..87bb99d98 100644--- a/pipelex/cli/commands/build/structures_cmd.py+++ b/pipelex/cli/commands/build/structures_cmd.py@@ -9,11 +9,16 @@ from pipelex.base_exceptions import PipelexErrorfrom pipelex.cli.cli_factory import make_pipelex_for_clifrom pipelex.cli.error_handlers import ErrorContextfrom pipelex.core.concepts.concept_factory import ConceptFactory-from pipelex.core.concepts.helpers import get_structure_class_name_from_blueprint, normalize_structure_blueprint+from pipelex.core.concepts.helpers import (+ get_structure_class_name_from_blueprint,+ make_qualified_structure_class_name,+ normalize_structure_blueprint,+)from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.concepts.structure_generation.exceptions import ConceptStructureGeneratorErrorfrom pipelex.core.concepts.structure_generation.generator import ConceptClassInfo, StructureGeneratorfrom pipelex.core.interpreter.helpers import is_pipelex_file+from pipelex.core.qualified_ref import QualifiedReffrom pipelex.core.registry_models import CoreRegistryModelsfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.hub import get_class_registry, get_func_registry, resolve_library_dirs@@ -69,14 +74,22 @@ def _build_concept_ref_to_class_info(# Build the concept ref (domain.ConceptCode)concept_ref = f"{blueprint.domain}.{concept_code}"- # Get the class name from the blueprint- class_name = get_structure_class_name_from_blueprint(concept_blueprint, concept_code)+ # Get the class name from the blueprint. When the helper returns the bare+ # concept_code (i.e. no user-supplied structure class reference), qualify+ # it with the domain so cross-class imports/types match the qualified+ # class definitions emitted below.+ raw_class_name = get_structure_class_name_from_blueprint(concept_blueprint, concept_code)+ if raw_class_name == concept_code:+ class_name = make_qualified_structure_class_name(blueprint.domain, concept_code)+ file_stem_snake_case = pascal_case_to_snake_case(concept_code)+ else:+ class_name = raw_class_name+ file_stem_snake_case = pascal_case_to_snake_case(raw_class_name)# Build the module path for this concept's structure file- class_name_snake_case = pascal_case_to_snake_case(class_name)if base_relative_path:base_module_path = ".".join(base_relative_path.parts)- module_path = f"{base_module_path}.{blueprint.domain}__{class_name_snake_case}"+ module_path = f"{base_module_path}.{blueprint.domain}__{file_stem_snake_case}"else:module_path = None@@ -151,8 +164,10 @@ def generate_structures_from_blueprints(# Handle simple string concept definitions (description only, refines Text by default)if isinstance(concept_blueprint, str):try:- generated_code, _ = StructureGenerator(concept_ref_to_class_info=concept_ref_to_class_info).generate_from_structure_blueprint(- class_name=concept_code,+ generated_code, _ = StructureGenerator(+ concept_ref_to_class_info=concept_ref_to_class_info, local_domain=blueprint.domain+ ).generate_from_structure_blueprint(+ class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),structure_blueprint={},base_class_name=TextContent.__name__,description=concept_blueprint,@@ -179,9 +194,10 @@ def generate_structures_from_blueprints(try:generated_code, the_generated_class = StructureGenerator(- concept_ref_to_class_info=concept_ref_to_class_info+ concept_ref_to_class_info=concept_ref_to_class_info,+ local_domain=blueprint.domain,).generate_from_structure_blueprint(- class_name=concept_code,+ class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),structure_blueprint=normalized_structure,description=concept_blueprint.description,)@@ -212,21 +228,25 @@ def generate_structures_from_blueprints(raise PipelexError(msg) from exc# For native concepts, the structure class name is "ConceptCode" + "Content" (e.g., TextContent)- # For custom concepts, the structure class name is just the concept code (e.g., Customer)+ # For custom concepts, the structure class name is the domain-qualified name+ # (e.g., other_domain__Customer) so it matches what ConceptFactory registers.if current_refine:- refined_concept_code = current_refine.split(".")[1]+ refined_ref = QualifiedRef.parse_stripping_cross_package(current_refine)+ refined_concept_code = refined_ref.local_codeif NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=current_refine):refined_structure_class_name = refined_concept_code + "Content"else:- refined_structure_class_name = refined_concept_code+ refined_domain_code = refined_ref.domain_path or blueprint.domain+ refined_structure_class_name = make_qualified_structure_class_name(refined_domain_code, refined_concept_code)else:refined_structure_class_name = TextContent.__name__try:generated_code, the_generated_class = StructureGenerator(- concept_ref_to_class_info=concept_ref_to_class_info+ concept_ref_to_class_info=concept_ref_to_class_info,+ local_domain=blueprint.domain,).generate_from_structure_blueprint(- class_name=concept_code,+ class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),structure_blueprint={},base_class_name=refined_structure_class_name,description=concept_blueprint.description,@@ -254,9 +274,10 @@ def generate_structures_from_blueprints(else:try:generated_code, the_generated_class = StructureGenerator(- concept_ref_to_class_info=concept_ref_to_class_info+ concept_ref_to_class_info=concept_ref_to_class_info,+ local_domain=blueprint.domain,).generate_from_structure_blueprint(- class_name=concept_code,+ class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),structure_blueprint={},base_class_name=TextContent.__name__,description=concept_blueprint.description,diff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.pyindex 46b76e30e..4a8885fbd 100644--- a/pipelex/core/concepts/concept_factory.py+++ b/pipelex/core/concepts/concept_factory.py@@ -319,7 +319,7 @@ class ConceptFactory:qualified_class_name = make_qualified_structure_class_name(domain_code, concept_code)try:- _, the_generated_class = StructureGenerator().generate_from_structure_blueprint(+ _, the_generated_class = StructureGenerator(local_domain=domain_code).generate_from_structure_blueprint(class_name=qualified_class_name,structure_blueprint=normalized_structure,description=blueprint.description,diff --git a/pipelex/core/concepts/structure_generation/generator.py b/pipelex/core/concepts/structure_generation/generator.pyindex d9d9e30ea..8be90e0e3 100644--- a/pipelex/core/concepts/structure_generation/generator.py+++ b/pipelex/core/concepts/structure_generation/generator.py@@ -51,6 +51,7 @@ class StructureGenerator:def __init__(self,concept_ref_to_class_info: dict[str, ConceptClassInfo] | None = None,+ local_domain: str | None = None,):"""Initialize the StructureGenerator.@@ -58,6 +59,9 @@ class StructureGenerator:concept_ref_to_class_info: Optional mapping from concept refs to ConceptClassInfo.When module_path is provided, proper import statements will be generated.When module_path is None, forward references (strings) will be used.+ local_domain: Optional domain to use when resolving bare concept refs+ (refs without a domain prefix, e.g. "ColorPalette") to their+ domain-qualified structure class name."""self.imports = {"from typing import Optional, List, Dict, Any, Literal",@@ -67,6 +71,7 @@ class StructureGenerator:}self.enum_definitions: dict[str, dict[str, Any]] = {} # Store enum definitionsself.concept_ref_to_class_info = concept_ref_to_class_info or {}+ self.local_domain = local_domain# Track concept classes that need to be mocked during validation (for file generation)self._concept_classes_to_mock: set[str] = set()@@ -432,6 +437,14 @@ class StructureGenerator:except ValueError:pass+ # Bare concept_refs (e.g. "ColorPalette") in field defs are local to the+ # current bundle's domain. Promote them to a qualified ref so the lookup+ # below — and the qualified-name fallback after it — find the right class.+ parsed_ref = QualifiedRef.parse_stripping_cross_package(concept_ref)+ if not parsed_ref.domain_path and self.local_domain:+ concept_ref = f"{self.local_domain}.{concept_ref}"+ parsed_ref = QualifiedRef.parse_stripping_cross_package(concept_ref)+# Check concept_ref_to_class_info for the concept referenceif concept_ref in self.concept_ref_to_class_info:class_info = self.concept_ref_to_class_info[concept_ref]@@ -446,7 +459,6 @@ class StructureGenerator:# Default: use domain-qualified forward reference when domain is available# e.g., "myapp.Customer" -> '"myapp__Customer"'concept_code = extract_concept_code_from_concept_ref_or_code(concept_ref)- parsed_ref = QualifiedRef.parse_stripping_cross_package(concept_ref)if parsed_ref.domain_path and not NativeConceptCode.is_native_concept_ref_or_code(concept_ref):qualified_name = make_qualified_structure_class_name(parsed_ref.domain_path, concept_code)return f'"{qualified_name}"'diff --git a/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.py b/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.pyindex 80de61124..6a95acde1 100644--- a/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.py+++ b/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.py@@ -70,24 +70,29 @@ class TestStructureGeneratorCLI:assert customer_file.exists(), f"Customer structure file not generated: {customer_file}"assert invoice_file.exists(), f"Invoice structure file not generated: {invoice_file}"- # Read and verify the generated code contains proper structure+ # Read and verify the generated code contains proper structure.+ # Class names are domain-qualified (e.g. "nested_concepts_test__LineItem") so+ # they match what ConceptFactory registers in the class registry.line_item_code = line_item_file.read_text()customer_code = customer_file.read_text()invoice_code = invoice_file.read_text()- # Verify basic structure in generated code- assert "class LineItem(StructuredContent):" in line_item_code- assert "class Customer(StructuredContent):" in customer_code- assert "class Invoice(StructuredContent):" in invoice_code+ line_item_class_name = "nested_concepts_test__LineItem"+ customer_class_name = "nested_concepts_test__Customer"+ invoice_class_name = "nested_concepts_test__Invoice"- # Verify Invoice has forward references to Customer and LineItem- assert '"Customer"' in invoice_code or "Customer" in invoice_code- assert '"LineItem"' in invoice_code or "LineItem" in invoice_code+ assert f"class {line_item_class_name}(StructuredContent):" in line_item_code+ assert f"class {customer_class_name}(StructuredContent):" in customer_code+ assert f"class {invoice_class_name}(StructuredContent):" in invoice_code++ # Verify Invoice has forward references to the qualified Customer and LineItem names+ assert customer_class_name in invoice_code+ assert line_item_class_name in invoice_code# Dynamically import the generated modules# Import order matters: dependencies first- line_item_class = self._import_class_from_file(line_item_file, "LineItem")- customer_class = self._import_class_from_file(customer_file, "Customer")+ line_item_class = self._import_class_from_file(line_item_file, line_item_class_name)+ customer_class = self._import_class_from_file(customer_file, customer_class_name)# Now import Invoice - it has forward references to LineItem and Customer# We need to add LineItem and Customer to the namespace for forward reference resolution@@ -97,18 +102,18 @@ class TestStructureGeneratorCLI:invoice_module = importlib.util.module_from_spec(invoice_spec)# Add the dependencies to the module's globals for forward reference resolution- invoice_module.__dict__["LineItem"] = line_item_class- invoice_module.__dict__["Customer"] = customer_class+ invoice_module.__dict__[line_item_class_name] = line_item_class+ invoice_module.__dict__[customer_class_name] = customer_classsys.modules["invoice_module"] = invoice_moduleinvoice_spec.loader.exec_module(invoice_module)- invoice_class: Any = invoice_module.Invoice+ invoice_class: Any = getattr(invoice_module, invoice_class_name)# Rebuild the model to resolve forward referencesinvoice_class.model_rebuild(_types_namespace={- "LineItem": line_item_class,- "Customer": customer_class,+ line_item_class_name: line_item_class,+ customer_class_name: customer_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.pynew file mode 100644index 000000000..ae858cbda--- /dev/null+++ b/tests/unit/pipelex/cli/commands/build/test_structures_cmd_cross_package_refines.py@@ -0,0 +1,80 @@+"""Regression test for cross-package refines in structures_cmd.++Ensures that when a concept refines a cross-package reference like+``alias->other_domain.OtherConcept``, the generated structure file uses a+valid Python identifier as its base class. Previously, ``QualifiedRef.parse``+left the ``alias->`` prefix in ``domain_path``, which the+``make_qualified_structure_class_name`` helper does not sanitise — the+generated module then failed to import because the base class name was not a+legal identifier.+"""++import tempfile+from pathlib import Path++from pipelex.cli.commands.build.structures_cmd import generate_structures_from_blueprints+from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint+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."""+++class TestStructuresCmdCrossPackageRefines:+ 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.+ """+ # 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.+ get_class_registry().register_class(+ _CrossPackageBaseClassStub,+ name="other_domain__OtherConcept",+ should_warn_if_already_registered=False,+ )++ bundle = PipelexBundleBlueprint(+ domain="local_domain",+ description="Bundle that refines a cross-package concept.",+ concept={+ "RefiningConcept": ConceptBlueprint(+ description="Refines a concept defined in another package.",+ refines="some_alias->other_domain.OtherConcept",+ ),+ },+ )++ 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,+ )++ 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_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+ )