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.

Structure class name handling domain-qualified concepts (#874)

Louis Choquel5ce13d1c591b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Changed
diff --git a/pipelex/cli/commands/build/structures_cmd.py b/pipelex/cli/commands/build/structures_cmd.py
index 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 PipelexError
from pipelex.cli.cli_factory import make_pipelex_for_cli
from pipelex.cli.error_handlers import ErrorContext
from 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 NativeConceptCode
from pipelex.core.concepts.structure_generation.exceptions import ConceptStructureGeneratorError
from pipelex.core.concepts.structure_generation.generator import ConceptClassInfo, StructureGenerator
from pipelex.core.interpreter.helpers import is_pipelex_file
+from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.registry_models import CoreRegistryModels
from pipelex.core.stuffs.text_content import TextContent
from 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_code
if 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.py
index 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.py
index 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 definitions
self.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 reference
if 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.py
index 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_class
sys.modules["invoice_module"] = invoice_module
invoice_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 references
invoice_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.py
new file mode 100644
index 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
+ )