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/concept-structure-comparison (#529)
Thomas Hebrarda7f1d4e7dc12
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f6e45be1b..901d42f53 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -89,6 +89,7 @@### Fixed- Fixed the issue with the `find_files_in_dir` force including virtual environment directories: Now it force includes the `pipelex.builder` directory.+- Fixed a bug with the comparison of Concept structures.## [v0.17.2] - 2025-12-01diff --git a/pipelex/cli/commands/validate_cmd.py b/pipelex/cli/commands/validate_cmd.pyindex 4c3a5fd3b..13462538e 100644--- a/pipelex/cli/commands/validate_cmd.py+++ b/pipelex/cli/commands/validate_cmd.py@@ -43,6 +43,8 @@ def do_validate_all_libraries_and_dry_run() -> None:library_manager.load_libraries(library_id=library_id, library_dirs=[Path.cwd()])pipes = library.get_pipe_library().get_pipes()+ for pipe in pipes:+ pipe.validate_with_libraries()get_telemetry_manager().track_event(EventName.PIPE_DRY_RUN, properties={EventProperty.NB_PIPES: len(pipes)})diff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.pyindex b6d671abe..5d6143263 100644--- a/pipelex/core/concepts/concept.py+++ b/pipelex/core/concepts/concept.py@@ -109,9 +109,13 @@ class Concept(BaseModel):if concept_1_class is None or concept_2_class is None:return False+ # Check if classes are structurally equivalent (same fields, types)+ if are_classes_equivalent(concept_1_class, concept_2_class):+ return True+if strict:- # Check if classes are equivalent (same fields, types, descriptions)- return are_classes_equivalent(concept_1_class, concept_2_class)+ # In strict mode, only structural equivalence is accepted+ return False# Check if concept_1 is a subclass of concept_2# This handles inheritance from refined concepts (e.g., RefusalEmail inherits from TextContent)diff --git a/pipelex/tools/typing/class_utils.py b/pipelex/tools/typing/class_utils.pyindex 0541aba97..94e1f9936 100644--- a/pipelex/tools/typing/class_utils.py+++ b/pipelex/tools/typing/class_utils.py@@ -1,5 +1,5 @@import types-from typing import TYPE_CHECKING, Annotated, Any, Union, get_args, get_origin+from typing import TYPE_CHECKING, Annotated, Any, Union, cast, get_args, get_originif TYPE_CHECKING:from pydantic.fields import FieldInfo@@ -9,8 +9,67 @@ _NoneType = type(None)_UnionType = getattr(types, "UnionType", None) # Py3.10+: types.UnionType+def normalize_property_for_comparison(prop: dict[str, Any]) -> dict[str, Any]:+ """Normalize a property dict by removing description and keeping only structural parts.++ This recursively removes 'description' keys from the property dict, allowing+ structural comparison of JSON schemas that ignores field descriptions.++ Args:+ prop: A property dict from a JSON schema (e.g., {'type': 'string', 'description': 'A name'})++ Returns:+ The property dict with all 'description' keys removed at any nesting level.++ Example:+ >>> prop = {'type': 'string', 'description': 'The user name', 'title': 'Name'}+ >>> normalize_property_for_comparison(prop)+ {'type': 'string', 'title': 'Name'}++ >>> nested_prop = {'type': 'object', 'properties': {'id': {'type': 'integer', 'description': 'ID'}}}+ >>> normalize_property_for_comparison(nested_prop)+ {'type': 'object', 'properties': {'id': {'type': 'integer'}}}+ """+ normalized: dict[str, Any] = {}+ for key, value in prop.items():+ if key == "description":+ continue # Skip descriptions for structural comparison+ if isinstance(value, dict):+ normalized[key] = normalize_property_for_comparison(cast("dict[str, Any]", value))+ else:+ normalized[key] = value+ return normalized+++def normalize_properties_for_comparison(properties: dict[str, Any]) -> dict[str, Any]:+ """Normalize all properties in a schema for structural comparison.++ Applies normalize_property_for_comparison to each property in a JSON schema's+ 'properties' dict, removing descriptions from all fields.++ Args:+ properties: The 'properties' dict from a JSON schema++ Returns:+ A new dict with all property descriptions removed.++ Example:+ >>> properties = {+ ... 'name': {'type': 'string', 'description': 'User name'},+ ... 'age': {'type': 'integer', 'description': 'User age'}+ ... }+ >>> normalize_properties_for_comparison(properties)+ {'name': {'type': 'string'}, 'age': {'type': 'integer'}}+ """+ return {name: normalize_property_for_comparison(prop) for name, prop in properties.items()}++def are_classes_equivalent(class_1: type[Any], class_2: type[Any]) -> bool:- """Check if two Pydantic classes are equivalent (same fields, types, descriptions)."""+ """Check if two Pydantic classes are structurally equivalent (same fields, types).++ This compares the structural parts of the JSON schema (properties, required fields, type)+ and ignores metadata like the class title/name and field descriptions.+ """if not (hasattr(class_1, "model_fields") and hasattr(class_2, "model_fields")):return class_1 == class_2@@ -18,7 +77,23 @@ def are_classes_equivalent(class_1: type[Any], class_2: type[Any]) -> bool:try:schema_1: dict[str, Any] = class_1.model_json_schema()schema_2: dict[str, Any] = class_2.model_json_schema()- return schema_1 == schema_2++ # Compare required fields+ if schema_1.get("required") != schema_2.get("required"):+ return False++ # Compare type+ if schema_1.get("type") != schema_2.get("type"):+ return False++ # Compare properties, normalized to ignore descriptions+ props_1 = normalize_properties_for_comparison(schema_1.get("properties", {}))+ props_2 = normalize_properties_for_comparison(schema_2.get("properties", {}))+ if props_1 != props_2:+ return False++ # Compare $defs if present (for nested types)+ return schema_1.get("$defs") == schema_2.get("$defs")except Exception:# Fallback to manual field comparison if schema comparison failsfields_1: dict[str, FieldInfo] = class_1.model_fields@@ -35,10 +110,6 @@ def are_classes_equivalent(class_1: type[Any], class_2: type[Any]) -> bool:if field_1.annotation != field_2.annotation:return False- # Compare field descriptions if they exist- if getattr(field_1, "description", None) != getattr(field_2, "description", None):- return False-# Compare default valuesif field_1.default != field_2.default:return False@@ -47,7 +118,7 @@ def are_classes_equivalent(class_1: type[Any], class_2: type[Any]) -> bool:def has_compatible_field(class_1: type[Any], class_2: type[Any]) -> bool:- """Check if class_1 has a field whose (possibly wrapped) type matches/subclasses class_2."""+ """Check if class_1 has a field whose (possibly wrapped) type matches/subclasses class_2 or is structurally equivalent."""if not hasattr(class_1, "model_fields"):return False@@ -71,9 +142,17 @@ def has_compatible_field(class_1: type[Any], class_2: type[Any]) -> bool:# Base case: direct match / subclasstry:- return type_param is class_2 or (isinstance(type_param, type) and issubclass(type_param, class_2))+ if type_param is class_2 or (isinstance(type_param, type) and issubclass(type_param, class_2)):+ return Trueexcept TypeError:# Not a class type (e.g., typing constructs you don't care about)- return False+ pass++ # Also check for structural equivalence (same JSON schema)+ if isinstance(type_param, type) and hasattr(type_param, "model_fields"):+ if are_classes_equivalent(type_param, class_2):+ return True++ return Falsereturn any(_is_compatible(field.annotation) for field in fields.values())diff --git a/tests/unit/pipelex/core/concepts/concept_library/test_concept_library.py b/tests/unit/pipelex/core/concepts/concept_library/test_concept_library.pydeleted file mode 100644index 818c15fe7..000000000--- a/tests/unit/pipelex/core/concepts/concept_library/test_concept_library.py+++ /dev/null@@ -1,97 +0,0 @@-from typing import Callable--from pipelex.core.concepts.concept import Concept-from pipelex.core.concepts.concept_blueprint import ConceptBlueprint-from pipelex.core.concepts.concept_factory import ConceptFactory-from pipelex.core.concepts.native.concept_native import NativeConceptCode-from pipelex.hub import get_native_concept---class TestConceptLibrary:- def test_is_image_concept(self, load_empty_library: Callable[[], None]):- load_empty_library()- native_image_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.IMAGE)-- concept_1 = ConceptFactory.make_from_blueprint(- domain="test",- concept_code="TestConcept",- blueprint_or_string_description=ConceptBlueprint(- description="Lorem Ipsum",- structure="ImageContent",- ),- )-- concept_2 = ConceptFactory.make_from_blueprint(- domain="test",- concept_code="TestConcept2",- blueprint_or_string_description=ConceptBlueprint(- description="Lorem Ipsum",- refines="native.Image",- ),- )- concept_3 = ConceptFactory.make_from_blueprint(- domain="test",- concept_code="TestConcept2",- blueprint_or_string_description=ConceptBlueprint(- description="Lorem Ipsum",- refines="Image",- ),- )-- concept_4 = ConceptFactory.make_from_blueprint(- domain="test",- concept_code="TestConcept4",- blueprint_or_string_description=ConceptBlueprint(- description="Lorem Ipsum",- structure="ImageContent",- ),- )-- concept_5 = ConceptFactory.make_from_blueprint(- domain="test",- concept_code="TestConcept5",- blueprint_or_string_description=ConceptBlueprint(- description="Lorem Ipsum",- structure="TextContent",- ),- )-- concept_6 = ConceptFactory.make_from_blueprint(- domain="test",- concept_code="TestConcept6",- blueprint_or_string_description=ConceptBlueprint(- description="Lorem Ipsum",- structure="PDFContent",- ),- )-- assert (- Concept.are_concept_compatible(- concept_1=native_image_concept, concept_2=get_native_concept(native_concept=NativeConceptCode.IMAGE), strict=True- )- is True- )- assert (- Concept.are_concept_compatible(concept_1=concept_1, concept_2=get_native_concept(native_concept=NativeConceptCode.IMAGE), strict=True)- is True- )- assert (- Concept.are_concept_compatible(concept_1=concept_2, concept_2=get_native_concept(native_concept=NativeConceptCode.IMAGE), strict=True)- is True- )- assert (- Concept.are_concept_compatible(concept_1=concept_3, concept_2=get_native_concept(native_concept=NativeConceptCode.IMAGE), strict=True)- is True- )- assert (- Concept.are_concept_compatible(concept_1=concept_4, concept_2=get_native_concept(native_concept=NativeConceptCode.IMAGE), strict=True)- is True- )- assert (- Concept.are_concept_compatible(concept_1=concept_5, concept_2=get_native_concept(native_concept=NativeConceptCode.IMAGE), strict=True)- is False- )- assert (- Concept.are_concept_compatible(concept_1=concept_6, concept_2=get_native_concept(native_concept=NativeConceptCode.IMAGE), strict=True)- is False- )diff --git a/tests/unit/pipelex/core/concepts/test_concept.py b/tests/unit/pipelex/core/concepts/test_concept.pyindex 6b9d64303..1743be436 100644--- a/tests/unit/pipelex/core/concepts/test_concept.py+++ b/tests/unit/pipelex/core/concepts/test_concept.py@@ -1,13 +1,33 @@import pytest+from kajson.kajson_manager import KajsonManagerfrom pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldTypefrom pipelex.core.concepts.exceptions import ConceptStringErrorfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.concepts.native.exceptions import NativeConceptDefinitionErrorfrom pipelex.core.concepts.validation import validate_concept_stringfrom pipelex.core.domains.domain import SpecialDomain+from pipelex.core.stuffs.structured_content import StructuredContent+++# Custom StuffContent class with nested ImageContent-like field for testing+class NestedImageInfo(StructuredContent):+ """A nested structure that contains image-like data."""++ url: str+ source_prompt: str | None = None+ caption: str | None = None+ base_64: str | None = None+++class DocumentWithNestedImage(StructuredContent):+ """A content class that has a nested field containing image info."""++ title: str+ metadata: NestedImageInfoclass TestConcept:@@ -283,3 +303,73 @@ class TestConcept:# A concept that refines Text should be strictly compatible with Textassert Concept.are_concept_compatible(concept_not_native_text, text_concept, strict=True) is Trueassert Concept.are_concept_compatible(concept_not_native_text, text_concept, strict=False) is True++ def test_concept_with_same_structure_as_text_content(self):+ """Test: create a concept with a structure EXACTLY like TextContent (text: str) and compare with native Text."""+ # Create a concept with a structure blueprint that has exactly the same field as TextContent: text: str+ custom_text_like_concept = ConceptFactory.make_from_blueprint(+ concept_code="MyTextLikeConcept",+ domain="test_structure_equiv",+ blueprint_or_string_description=ConceptBlueprint(+ description="A concept with the exact same structure as TextContent",+ structure={+ "text": ConceptStructureBlueprint(+ type=ConceptStructureBlueprintFieldType.TEXT,+ description="The text content",+ ),+ },+ ),+ )++ # Get the native Text concept+ native_text_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT)++ # They have different structure_class_names but the same JSON structure+ assert custom_text_like_concept.structure_class_name != native_text_concept.structure_class_name++ # Concepts with the same JSON structure should be compatible+ assert Concept.are_concept_compatible(custom_text_like_concept, native_text_concept, strict=True) is True+ assert Concept.are_concept_compatible(custom_text_like_concept, native_text_concept, strict=False) is True++ def test_nested_image_content_strict_false_nonstrict_true(self):+ """Test: strict=True returns False, strict=False returns True for nested compatible field."""+ # Register our custom classes with the class registry+ KajsonManager.get_class_registry().register_class(NestedImageInfo)+ KajsonManager.get_class_registry().register_class(DocumentWithNestedImage)++ # Create a concept using our custom DocumentWithNestedImage class+ concept_with_nested_image = ConceptFactory.make(+ domain="test_nested",+ concept_code="DocumentWithImage",+ description="A document containing nested image info",+ structure_class_name="DocumentWithNestedImage",+ )++ # Create a concept using the NestedImageInfo class (same structure as ImageContent)+ concept_image_like = ConceptFactory.make(+ domain="test_nested",+ concept_code="ImageInfo",+ description="Image-like info",+ structure_class_name="NestedImageInfo",+ )++ # Get the native Image concept (uses ImageContent)+ native_image_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.IMAGE)++ # --- Test with NestedImageInfo (custom class with same structure as ImageContent) ---+ # strict=True should be False: DocumentWithNestedImage is NOT structurally equivalent to NestedImageInfo+ assert Concept.are_concept_compatible(concept_with_nested_image, concept_image_like, strict=True) is False+ # strict=False should be True: DocumentWithNestedImage has a field (metadata) that is NestedImageInfo+ assert Concept.are_concept_compatible(concept_with_nested_image, concept_image_like, strict=False) is True++ # --- Test NestedImageInfo vs native Image (ImageContent) ---+ # NestedImageInfo has the same structure as ImageContent, so should be strictly compatible+ assert Concept.are_concept_compatible(concept_image_like, native_image_concept, strict=True) is True+ assert Concept.are_concept_compatible(concept_image_like, native_image_concept, strict=False) is True++ # --- Test DocumentWithNestedImage vs native Image (ImageContent) ---+ # strict=True should be False: DocumentWithNestedImage is NOT structurally equivalent to ImageContent+ assert Concept.are_concept_compatible(concept_with_nested_image, native_image_concept, strict=True) is False+ # strict=False should be True: DocumentWithNestedImage has a nested field (metadata: NestedImageInfo)+ # that is STRUCTURALLY EQUIVALENT to ImageContent+ assert Concept.are_concept_compatible(concept_with_nested_image, native_image_concept, strict=False) is Truediff --git a/tests/unit/pipelex/tools/typing/test_class_utils.py b/tests/unit/pipelex/tools/typing/test_class_utils.pynew file mode 100644index 000000000..383e2cd20--- /dev/null+++ b/tests/unit/pipelex/tools/typing/test_class_utils.py@@ -0,0 +1,283 @@+from pydantic import BaseModel, Field++from pipelex.tools.typing.class_utils import (+ are_classes_equivalent,+ has_compatible_field,+ normalize_properties_for_comparison,+ normalize_property_for_comparison,+)+++class TestNormalizePropertyForComparison:+ """Tests for normalize_property_for_comparison function."""++ def test_removes_description_from_simple_property(self):+ """Test that description is removed from a simple property."""+ prop = {"type": "string", "description": "The user name", "title": "Name"}+ result = normalize_property_for_comparison(prop)+ assert result == {"type": "string", "title": "Name"}+ assert "description" not in result++ def test_preserves_other_keys(self):+ """Test that other keys are preserved."""+ prop = {"type": "integer", "minimum": 0, "maximum": 100}+ result = normalize_property_for_comparison(prop)+ assert result == {"type": "integer", "minimum": 0, "maximum": 100}++ def test_removes_description_from_nested_dict(self):+ """Test that description is removed from nested dicts."""+ prop = {+ "type": "object",+ "description": "A nested object",+ "properties": {"id": {"type": "integer", "description": "The ID"}},+ }+ result = normalize_property_for_comparison(prop)+ assert result == {"type": "object", "properties": {"id": {"type": "integer"}}}+ assert "description" not in result+ assert "description" not in result["properties"]["id"]++ def test_handles_empty_dict(self):+ """Test that empty dict returns empty dict."""+ assert normalize_property_for_comparison({}) == {}++ def test_handles_deeply_nested_descriptions(self):+ """Test removal of descriptions at multiple nesting levels."""+ prop = {+ "type": "object",+ "description": "Level 1",+ "items": {+ "type": "object",+ "description": "Level 2",+ "properties": {+ "field": {"type": "string", "description": "Level 3"},+ },+ },+ }+ result = normalize_property_for_comparison(prop)+ assert "description" not in result+ assert "description" not in result["items"]+ assert "description" not in result["items"]["properties"]["field"]+++class TestNormalizePropertiesForComparison:+ """Tests for normalize_properties_for_comparison function."""++ def test_normalizes_multiple_properties(self):+ """Test that all properties have descriptions removed."""+ properties = {+ "name": {"type": "string", "description": "User name"},+ "age": {"type": "integer", "description": "User age"},+ }+ result = normalize_properties_for_comparison(properties)+ assert result == {"name": {"type": "string"}, "age": {"type": "integer"}}++ def test_handles_empty_properties(self):+ """Test that empty properties dict returns empty dict."""+ assert normalize_properties_for_comparison({}) == {}++ def test_preserves_non_description_metadata(self):+ """Test that other metadata is preserved."""+ properties = {+ "count": {"type": "integer", "minimum": 0, "description": "A count"},+ "active": {"type": "boolean", "default": True, "description": "Is active"},+ }+ result = normalize_properties_for_comparison(properties)+ assert result == {+ "count": {"type": "integer", "minimum": 0},+ "active": {"type": "boolean", "default": True},+ }+++class TestAreClassesEquivalent:+ """Tests for are_classes_equivalent function."""++ def test_identical_classes_are_equivalent(self):+ """Test that the same class is equivalent to itself."""++ class MyModel(BaseModel):+ name: str+ age: int++ assert are_classes_equivalent(MyModel, MyModel) is True++ def test_classes_with_same_structure_are_equivalent(self):+ """Test that two classes with the same fields are equivalent."""++ class ModelA(BaseModel):+ name: str+ value: int++ class ModelB(BaseModel):+ name: str+ value: int++ assert are_classes_equivalent(ModelA, ModelB) is True++ def test_classes_with_different_fields_are_not_equivalent(self):+ """Test that classes with different field names are not equivalent."""++ class ModelA(BaseModel):+ name: str++ class ModelB(BaseModel):+ title: str++ assert are_classes_equivalent(ModelA, ModelB) is False++ def test_classes_with_different_types_are_not_equivalent(self):+ """Test that classes with different field types are not equivalent."""++ class ModelA(BaseModel):+ value: int++ class ModelB(BaseModel):+ value: str++ assert are_classes_equivalent(ModelA, ModelB) is False++ def test_classes_with_different_descriptions_are_equivalent(self):+ """Test that field descriptions don't affect equivalence."""++ class ModelA(BaseModel):+ name: str = Field(description="The name of something")++ class ModelB(BaseModel):+ name: str = Field(description="A completely different description")++ assert are_classes_equivalent(ModelA, ModelB) is True++ def test_classes_with_different_required_fields_are_not_equivalent(self):+ """Test that required vs optional fields matter."""++ class ModelA(BaseModel):+ name: str++ class ModelB(BaseModel):+ name: str | None = None++ assert are_classes_equivalent(ModelA, ModelB) is False++ def test_non_pydantic_classes(self):+ """Test that non-Pydantic classes are compared by identity."""++ class RegularClass:+ pass++ assert are_classes_equivalent(RegularClass, RegularClass) is True+ assert are_classes_equivalent(str, str) is True+ assert are_classes_equivalent(str, int) is False+++class TestHasCompatibleField:+ """Tests for has_compatible_field function."""++ def test_direct_type_match(self):+ """Test that a field with exact type match is found."""++ class Inner(BaseModel):+ value: str++ class Outer(BaseModel):+ data: Inner++ assert has_compatible_field(Outer, Inner) is True++ def test_subclass_match(self):+ """Test that a field with subclass type is found."""++ class Parent(BaseModel):+ name: str++ class Child(Parent):+ age: int++ class Container(BaseModel):+ item: Child++ assert has_compatible_field(Container, Parent) is True++ def test_no_match(self):+ """Test that no match is found when field types don't match."""++ class TypeA(BaseModel):+ x: int++ class TypeB(BaseModel):+ y: str++ class Container(BaseModel):+ data: TypeA++ assert has_compatible_field(Container, TypeB) is False++ def test_structural_equivalence_match(self):+ """Test that structurally equivalent types are found."""++ class StructureA(BaseModel):+ name: str+ value: int++ class StructureB(BaseModel):+ name: str+ value: int++ class Container(BaseModel):+ data: StructureA++ # StructureA and StructureB have the same structure+ assert has_compatible_field(Container, StructureB) is True++ def test_optional_field_match(self):+ """Test that optional fields are checked correctly."""++ class Inner(BaseModel):+ value: str++ class Outer(BaseModel):+ data: Inner | None = None++ assert has_compatible_field(Outer, Inner) is True++ def test_non_pydantic_class(self):+ """Test that non-Pydantic classes return False."""++ class RegularClass:+ pass++ class PydanticClass(BaseModel):+ name: str++ assert has_compatible_field(RegularClass, PydanticClass) is False # type: ignore[arg-type]+++class TestAreClassesEquivalentWithOptionalFields:+ """Additional tests for are_classes_equivalent with optional fields."""++ def test_same_optional_fields_are_equivalent(self):+ """Test that classes with same optional fields are equivalent."""++ class ModelA(BaseModel):+ name: str+ nickname: str | None = None++ class ModelB(BaseModel):+ name: str+ nickname: str | None = None++ assert are_classes_equivalent(ModelA, ModelB) is True++ def test_classes_with_same_fields_different_defaults_may_differ(self):+ """Test that default values don't affect JSON schema equivalence (they're in 'default' key)."""++ class ModelA(BaseModel):+ count: int = 0++ class ModelB(BaseModel):+ count: int = 100++ # JSON schema includes 'default' key, so these may or may not be equivalent+ # depending on whether defaults are in the schema properties+ # This test documents the actual behavior+ result = are_classes_equivalent(ModelA, ModelB)+ # The behavior depends on Pydantic's schema generation+ assert isinstance(result, bool)