aiecs 1.0.1__py3-none-any.whl → 1.7.6__py3-none-any.whl

aiecs/domain/knowledge_graph/models/relation.py

@@ -0,0 +1,202 @@
+"""
+Relation Domain Model
+
+Represents an edge/relationship between two entities in the knowledge graph.
+"""
+
+from typing import Any, Optional
+from datetime import datetime
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from aiecs.infrastructure.graph_storage.tenant import validate_tenant_id, InvalidTenantIdError, CrossTenantRelationError
+
+
+class Relation(BaseModel):
+    """
+    Knowledge Graph Relation
+
+    Represents a directed edge between two entities in the knowledge graph.
+
+    Attributes:
+        id: Unique identifier for the relation
+        relation_type: Type of relation (e.g., "WORKS_FOR", "KNOWS")
+        source_id: ID of the source entity
+        target_id: ID of the target entity
+        properties: Additional properties of the relation
+        weight: Optional weight/strength of the relation (0.0-1.0)
+        created_at: Creation timestamp
+        source: Source of the relation data
+
+    Example:
+        ```python
+        relation = Relation(
+            id="rel_001",
+            relation_type="WORKS_FOR",
+            source_id="person_001",
+            target_id="company_001",
+            properties={"role": "Engineer", "since": "2020-01-01"},
+            weight=1.0
+        )
+        ```
+    """
+
+    id: str = Field(..., description="Unique identifier for the relation")
+
+    relation_type: str = Field(..., description="Type of the relation (e.g., 'WORKS_FOR', 'KNOWS')")
+
+    source_id: str = Field(..., description="ID of the source entity")
+
+    target_id: str = Field(..., description="ID of the target entity")
+
+    properties: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional properties of the relation",
+    )
+
+    weight: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description="Weight/strength of the relation (0.0-1.0)",
+    )
+
+    created_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="Timestamp when relation was created",
+    )
+
+    source: Optional[str] = Field(default=None, description="Source of the relation data")
+
+    tenant_id: Optional[str] = Field(
+        default=None,
+        description="Tenant identifier for multi-tenant isolation (alphanumeric, hyphens, underscores only)",
+    )
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+    @field_validator("source_id", "target_id")
+    @classmethod
+    def validate_entity_ids(cls, v: str) -> str:
+        """Validate entity IDs are non-empty"""
+        if not v or not v.strip():
+            raise ValueError("Entity IDs must be non-empty strings")
+        return v
+
+    @field_validator("source_id")
+    @classmethod
+    def validate_no_self_loop(cls, v: str, info) -> str:
+        """Prevent self-loops (optional validation)"""
+        # Note: We allow self-loops for now, but this validator can be enabled if needed
+        # if info.data.get('target_id') and v == info.data['target_id']:
+        #     raise ValueError("Self-loops are not allowed (source_id == target_id)")
+        return v
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_tenant_id_before(cls, data: Any) -> Any:
+        """Validate tenant_id format before model creation"""
+        # Pydantic converts keyword arguments to dict before calling model_validator
+        if isinstance(data, dict):
+            tenant_id = data.get("tenant_id")
+            if tenant_id is not None:
+                # Validate and raise InvalidTenantIdError directly
+                # Note: Pydantic will wrap this in ValidationError, but the error info is preserved
+                validate_tenant_id(tenant_id)
+        return data
+
+    def validate_tenant_consistency(self, source_entity_tenant_id: Optional[str], target_entity_tenant_id: Optional[str]) -> Optional[str]:
+        """
+        Validate that relation tenant_id matches source and target entity tenant_ids.
+
+        This should be called when creating a relation to ensure tenant isolation.
+        Returns the effective tenant_id that should be used for this relation.
+
+        Args:
+            source_entity_tenant_id: Tenant ID of the source entity
+            target_entity_tenant_id: Tenant ID of the target entity
+
+        Returns:
+            The effective tenant_id for this relation (relation's tenant_id if set,
+            otherwise inferred from entities). Callers should use this value to
+            set the relation's tenant_id if needed.
+
+        Raises:
+            CrossTenantRelationError: If tenant IDs don't match
+        """
+        # If relation has tenant_id, it must match both entities
+        if self.tenant_id is not None:
+            if source_entity_tenant_id != self.tenant_id:
+                raise CrossTenantRelationError(source_entity_tenant_id, self.tenant_id)
+            if target_entity_tenant_id != self.tenant_id:
+                raise CrossTenantRelationError(self.tenant_id, target_entity_tenant_id)
+        
+        # Both entities must have the same tenant_id (or both None)
+        if source_entity_tenant_id != target_entity_tenant_id:
+            raise CrossTenantRelationError(source_entity_tenant_id, target_entity_tenant_id)
+        
+        # Return the effective tenant_id (relation's own or inferred from entities)
+        # Callers can use this to set the relation's tenant_id if needed
+        return self.tenant_id if self.tenant_id is not None else source_entity_tenant_id
+    
+    def with_tenant_id(self, tenant_id: Optional[str]) -> "Relation":
+        """
+        Create a copy of this relation with a new tenant_id.
+        
+        This is the Pydantic-idiomatic way to create a modified copy
+        without mutating the original instance.
+        
+        Args:
+            tenant_id: The tenant_id to set on the new relation
+            
+        Returns:
+            A new Relation instance with the updated tenant_id
+        """
+        return self.model_copy(update={"tenant_id": tenant_id})
+
+    def get_property(self, key: str, default: Any = None) -> Any:
+        """
+        Get a specific property value
+
+        Args:
+            key: Property key
+            default: Default value if key not found
+
+        Returns:
+            Property value or default
+        """
+        return self.properties.get(key, default)
+
+    def set_property(self, key: str, value: Any) -> None:
+        """
+        Set a property value
+
+        Args:
+            key: Property key
+            value: Property value
+        """
+        self.properties[key] = value
+
+    def reverse(self) -> "Relation":
+        """
+        Create a reversed relation (swap source and target)
+
+        Returns:
+            New Relation with swapped source and target
+        """
+        return Relation(
+            id=f"{self.id}_reversed",
+            relation_type=f"{self.relation_type}_REVERSE",
+            source_id=self.target_id,
+            target_id=self.source_id,
+            properties=self.properties.copy(),
+            weight=self.weight,
+            created_at=self.created_at,
+            source=self.source,
+        )
+
+    def __str__(self) -> str:
+        return f"Relation({self.source_id} -[{self.relation_type}]-> {self.target_id})"
+
+    def __repr__(self) -> str:
+        return f"Relation(id='{self.id}', type='{self.relation_type}', " f"source='{self.source_id}', target='{self.target_id}', weight={self.weight})"

aiecs/domain/knowledge_graph/schema/__init__.py

@@ -0,0 +1,23 @@
+"""
+Knowledge Graph Schema Management
+
+Schema definitions for entity types, relation types, and properties.
+"""
+
+from aiecs.domain.knowledge_graph.schema.property_schema import (
+    PropertySchema,
+    PropertyType,
+)
+from aiecs.domain.knowledge_graph.schema.entity_type import EntityType
+from aiecs.domain.knowledge_graph.schema.relation_type import RelationType
+from aiecs.domain.knowledge_graph.schema.graph_schema import GraphSchema
+from aiecs.domain.knowledge_graph.schema.schema_manager import SchemaManager
+
+__all__ = [
+    "PropertySchema",
+    "PropertyType",
+    "EntityType",
+    "RelationType",
+    "GraphSchema",
+    "SchemaManager",
+]

aiecs/domain/knowledge_graph/schema/entity_type.py

@@ -0,0 +1,131 @@
+"""
+Entity Type Schema Definition
+
+Defines the schema for entity types in the knowledge graph.
+"""
+
+from typing import Dict, List, Optional, Any
+from pydantic import BaseModel, Field
+from aiecs.domain.knowledge_graph.schema.property_schema import PropertySchema
+
+
+class EntityType(BaseModel):
+    """
+    Entity Type Schema
+
+    Defines the schema for a type of entity in the knowledge graph,
+    including its properties and constraints.
+
+    Attributes:
+        name: Entity type name (e.g., "Person", "Company")
+        description: Human-readable description
+        properties: Dictionary of property schemas
+        parent_type: Optional parent entity type for inheritance
+        is_abstract: Whether this is an abstract type (cannot be instantiated)
+
+    Example:
+        ```python
+        person_type = EntityType(
+            name="Person",
+            description="A person entity",
+            properties={
+                "name": PropertySchema(name="name", property_type=PropertyType.STRING, required=True),
+                "age": PropertySchema(name="age", property_type=PropertyType.INTEGER),
+            }
+        )
+        ```
+    """
+
+    name: str = Field(..., description="Entity type name (must be unique)")
+
+    description: Optional[str] = Field(
+        default=None,
+        description="Human-readable description of this entity type",
+    )
+
+    properties: Dict[str, PropertySchema] = Field(
+        default_factory=dict,
+        description="Dictionary of property schemas (key=property name)",
+    )
+
+    parent_type: Optional[str] = Field(default=None, description="Parent entity type name for inheritance")
+
+    is_abstract: bool = Field(
+        default=False,
+        description="Whether this is an abstract type (cannot be instantiated)",
+    )
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def add_property(self, prop: PropertySchema) -> None:
+        """
+        Add a property to this entity type
+
+        Args:
+            prop: Property schema to add
+        """
+        self.properties[prop.name] = prop
+
+    def remove_property(self, property_name: str) -> None:
+        """
+        Remove a property from this entity type
+
+        Args:
+            property_name: Name of property to remove
+        """
+        if property_name in self.properties:
+            del self.properties[property_name]
+
+    def get_property(self, property_name: str) -> Optional[PropertySchema]:
+        """
+        Get a property schema by name
+
+        Args:
+            property_name: Name of property to get
+
+        Returns:
+            Property schema or None if not found
+        """
+        return self.properties.get(property_name)
+
+    def validate_properties(self, properties: Dict[str, Any]) -> bool:
+        """
+        Validate a dictionary of properties against this schema
+
+        Args:
+            properties: Dictionary of properties to validate
+
+        Returns:
+            True if all properties are valid
+
+        Raises:
+            ValueError: If validation fails
+        """
+        # Check required properties
+        for prop_name, prop_schema in self.properties.items():
+            if prop_schema.required and prop_name not in properties:
+                raise ValueError(f"Required property '{prop_name}' missing for entity type '{self.name}'")
+
+        # Validate each provided property
+        for prop_name, prop_value in properties.items():
+            if prop_name in self.properties:
+                prop_schema = self.properties[prop_name]
+                prop_schema.validate_value(prop_value)
+
+        return True
+
+    def get_required_properties(self) -> List[str]:
+        """
+        Get list of required property names
+
+        Returns:
+            List of required property names
+        """
+        return [prop.name for prop in self.properties.values() if prop.required]
+
+    def __str__(self) -> str:
+        return f"EntityType(name='{self.name}', properties={len(self.properties)})"
+
+    def __repr__(self) -> str:
+        return self.__str__()

aiecs/domain/knowledge_graph/schema/graph_schema.py

@@ -0,0 +1,253 @@
+"""
+Graph Schema Container
+
+Container for all entity types and relation types in the knowledge graph.
+"""
+
+from typing import Dict, List, Optional
+from pydantic import BaseModel, Field
+from aiecs.domain.knowledge_graph.schema.entity_type import EntityType
+from aiecs.domain.knowledge_graph.schema.relation_type import RelationType
+
+
+class GraphSchema(BaseModel):
+    """
+    Knowledge Graph Schema
+
+    Container for all entity types and relation types in the knowledge graph.
+    Provides methods for schema management and validation.
+
+    Attributes:
+        version: Schema version identifier
+        entity_types: Dictionary of entity type schemas
+        relation_types: Dictionary of relation type schemas
+        description: Human-readable description of the schema
+
+    Example:
+        ```python
+        schema = GraphSchema(
+            version="1.0",
+            description="Company knowledge graph schema"
+        )
+        schema.add_entity_type(person_type)
+        schema.add_entity_type(company_type)
+        schema.add_relation_type(works_for_type)
+        ```
+    """
+
+    version: str = Field(default="1.0", description="Schema version identifier")
+
+    entity_types: Dict[str, EntityType] = Field(
+        default_factory=dict,
+        description="Dictionary of entity type schemas (key=type name)",
+    )
+
+    relation_types: Dict[str, RelationType] = Field(
+        default_factory=dict,
+        description="Dictionary of relation type schemas (key=type name)",
+    )
+
+    description: Optional[str] = Field(default=None, description="Human-readable description of this schema")
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    # Entity Type Management
+
+    def add_entity_type(self, entity_type: EntityType) -> None:
+        """
+        Add an entity type to the schema
+
+        Args:
+            entity_type: Entity type to add
+
+        Raises:
+            ValueError: If entity type already exists
+        """
+        if entity_type.name in self.entity_types:
+            raise ValueError(f"Entity type '{entity_type.name}' already exists in schema")
+        self.entity_types[entity_type.name] = entity_type
+
+    def update_entity_type(self, entity_type: EntityType) -> None:
+        """
+        Update an existing entity type
+
+        Args:
+            entity_type: Updated entity type
+
+        Raises:
+            ValueError: If entity type doesn't exist
+        """
+        if entity_type.name not in self.entity_types:
+            raise ValueError(f"Entity type '{entity_type.name}' not found in schema")
+        self.entity_types[entity_type.name] = entity_type
+
+    def delete_entity_type(self, type_name: str) -> None:
+        """
+        Delete an entity type from the schema
+
+        Args:
+            type_name: Name of entity type to delete
+
+        Raises:
+            ValueError: If entity type doesn't exist or is in use
+        """
+        if type_name not in self.entity_types:
+            raise ValueError(f"Entity type '{type_name}' not found in schema")
+
+        # Check if any relation types reference this entity type
+        for rel_type in self.relation_types.values():
+            if rel_type.source_entity_types and type_name in rel_type.source_entity_types:
+                raise ValueError(f"Cannot delete entity type '{type_name}': " f"referenced by relation '{rel_type.name}' as source")
+            if rel_type.target_entity_types and type_name in rel_type.target_entity_types:
+                raise ValueError(f"Cannot delete entity type '{type_name}': " f"referenced by relation '{rel_type.name}' as target")
+
+        del self.entity_types[type_name]
+
+    def get_entity_type(self, type_name: str) -> Optional[EntityType]:
+        """
+        Get an entity type by name
+
+        Args:
+            type_name: Name of entity type
+
+        Returns:
+            Entity type or None if not found
+        """
+        return self.entity_types.get(type_name)
+
+    def has_entity_type(self, type_name: str) -> bool:
+        """
+        Check if entity type exists
+
+        Args:
+            type_name: Name of entity type
+
+        Returns:
+            True if entity type exists
+        """
+        return type_name in self.entity_types
+
+    # Relation Type Management
+
+    def add_relation_type(self, relation_type: RelationType) -> None:
+        """
+        Add a relation type to the schema
+
+        Args:
+            relation_type: Relation type to add
+
+        Raises:
+            ValueError: If relation type already exists
+        """
+        if relation_type.name in self.relation_types:
+            raise ValueError(f"Relation type '{relation_type.name}' already exists in schema")
+        self.relation_types[relation_type.name] = relation_type
+
+    def update_relation_type(self, relation_type: RelationType) -> None:
+        """
+        Update an existing relation type
+
+        Args:
+            relation_type: Updated relation type
+
+        Raises:
+            ValueError: If relation type doesn't exist
+        """
+        if relation_type.name not in self.relation_types:
+            raise ValueError(f"Relation type '{relation_type.name}' not found in schema")
+        self.relation_types[relation_type.name] = relation_type
+
+    def delete_relation_type(self, type_name: str) -> None:
+        """
+        Delete a relation type from the schema
+
+        Args:
+            type_name: Name of relation type to delete
+
+        Raises:
+            ValueError: If relation type doesn't exist
+        """
+        if type_name not in self.relation_types:
+            raise ValueError(f"Relation type '{type_name}' not found in schema")
+        del self.relation_types[type_name]
+
+    def get_relation_type(self, type_name: str) -> Optional[RelationType]:
+        """
+        Get a relation type by name
+
+        Args:
+            type_name: Name of relation type
+
+        Returns:
+            Relation type or None if not found
+        """
+        return self.relation_types.get(type_name)
+
+    def has_relation_type(self, type_name: str) -> bool:
+        """
+        Check if relation type exists
+
+        Args:
+            type_name: Name of relation type
+
+        Returns:
+            True if relation type exists
+        """
+        return type_name in self.relation_types
+
+    # Schema Queries
+
+    def get_entity_type_names(self) -> List[str]:
+        """Get list of all entity type names"""
+        return list(self.entity_types.keys())
+
+    def get_relation_type_names(self) -> List[str]:
+        """Get list of all relation type names"""
+        return list(self.relation_types.keys())
+
+    def get_entity_types_with_property(self, property_name: str) -> List[EntityType]:
+        """
+        Get all entity types that have a specific property
+
+        Args:
+            property_name: Name of property to search for
+
+        Returns:
+            List of entity types with that property
+        """
+        return [entity_type for entity_type in self.entity_types.values() if property_name in entity_type.properties]
+
+    def get_relation_types_for_entities(self, source_type: str, target_type: str) -> List[RelationType]:
+        """
+        Get all relation types allowed between two entity types
+
+        Args:
+            source_type: Source entity type name
+            target_type: Target entity type name
+
+        Returns:
+            List of allowed relation types
+        """
+        allowed_relations = []
+
+        for rel_type in self.relation_types.values():
+            # Check if source type is allowed
+            if rel_type.source_entity_types is not None:
+                if source_type not in rel_type.source_entity_types:
+                    continue
+
+            # Check if target type is allowed
+            if rel_type.target_entity_types is not None:
+                if target_type not in rel_type.target_entity_types:
+                    continue
+
+            allowed_relations.append(rel_type)
+
+        return allowed_relations
+
+    def __str__(self) -> str:
+        return f"GraphSchema(version='{self.version}', " f"entity_types={len(self.entity_types)}, " f"relation_types={len(self.relation_types)})"
+
+    def __repr__(self) -> str:
+        return self.__str__()