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

aiecs/application/knowledge_graph/traversal/path_scorer.py

@@ -0,0 +1,271 @@
+"""
+Path Scoring and Ranking
+
+Provides utilities for scoring and ranking graph paths based on various criteria.
+"""
+
+from typing import List, Callable, Optional, Dict, Any, Tuple
+from aiecs.domain.knowledge_graph.models.path import Path
+
+
+class PathScorer:
+    """
+    Path Scoring Utility
+
+    Scores and ranks paths based on configurable criteria:
+    - Path length (shorter/longer)
+    - Relation types (preferred types)
+    - Entity types (preferred types)
+    - Relation weights (accumulated)
+    - Custom scoring functions
+
+    Example:
+        ```python
+        scorer = PathScorer()
+
+        # Score by path length (shorter is better)
+        scored_paths = scorer.score_by_length(paths, prefer_shorter=True)
+
+        # Score by relation weights
+        scored_paths = scorer.score_by_weights(paths)
+
+        # Custom scoring
+        scored_paths = scorer.score_custom(paths, lambda p: compute_score(p))
+
+        # Rank and return top paths
+        top_paths = scorer.rank_paths(scored_paths, top_k=10)
+        ```
+    """
+
+    def score_by_length(
+        self,
+        paths: List[Path],
+        prefer_shorter: bool = True,
+        normalize: bool = True,
+    ) -> List[Path]:
+        """
+        Score paths by their length
+
+        Args:
+            paths: List of paths to score
+            prefer_shorter: If True, shorter paths get higher scores
+            normalize: If True, normalize scores to 0-1 range
+
+        Returns:
+            List of paths with scores assigned
+        """
+        if not paths:
+            return []
+
+        # Get length range
+        lengths = [p.length for p in paths]
+        min_len = min(lengths)
+        max_len = max(lengths)
+
+        scored_paths = []
+        for path in paths:
+            if max_len == min_len:
+                # All paths same length
+                score = 1.0
+            elif prefer_shorter:
+                # Shorter paths get higher scores
+                if normalize:
+                    score = 1.0 - ((path.length - min_len) / (max_len - min_len))
+                else:
+                    score = 1.0 / (path.length + 1)
+            else:
+                # Longer paths get higher scores
+                if normalize:
+                    score = (path.length - min_len) / (max_len - min_len)
+                else:
+                    score = path.length / (max_len + 1)
+
+            # Create new path with score
+            scored_path = Path(nodes=path.nodes, edges=path.edges, score=score)
+            scored_paths.append(scored_path)
+
+        return scored_paths
+
+    def score_by_weights(self, paths: List[Path], aggregation: str = "mean") -> List[Path]:
+        """
+        Score paths by relation weights
+
+        Args:
+            paths: List of paths to score
+            aggregation: How to aggregate weights ("mean", "sum", "min", "max")
+
+        Returns:
+            List of paths with scores based on relation weights
+        """
+        scored_paths = []
+
+        for path in paths:
+            if not path.edges:
+                score = 1.0
+            else:
+                weights = [edge.weight for edge in path.edges]
+
+                if aggregation == "mean":
+                    score = sum(weights) / len(weights)
+                elif aggregation == "sum":
+                    score = sum(weights) / len(weights)  # Normalized by length
+                elif aggregation == "min":
+                    score = min(weights)
+                elif aggregation == "max":
+                    score = max(weights)
+                else:
+                    score = sum(weights) / len(weights)  # Default to mean
+
+            scored_path = Path(nodes=path.nodes, edges=path.edges, score=score)
+            scored_paths.append(scored_path)
+
+        return scored_paths
+
+    def score_by_relation_types(
+        self,
+        paths: List[Path],
+        preferred_types: List[str],
+        penalty: float = 0.5,
+    ) -> List[Path]:
+        """
+        Score paths by preferred relation types
+
+        Args:
+            paths: List of paths to score
+            preferred_types: List of preferred relation types
+            penalty: Score multiplier for non-preferred relations
+
+        Returns:
+            List of paths scored by relation type preferences
+        """
+        scored_paths = []
+
+        for path in paths:
+            if not path.edges:
+                score = 1.0
+            else:
+                # Calculate score based on preferred types
+                type_scores = []
+                for edge in path.edges:
+                    if edge.relation_type in preferred_types:
+                        type_scores.append(1.0)
+                    else:
+                        type_scores.append(penalty)
+
+                score = sum(type_scores) / len(type_scores)
+
+            scored_path = Path(nodes=path.nodes, edges=path.edges, score=score)
+            scored_paths.append(scored_path)
+
+        return scored_paths
+
+    def score_custom(self, paths: List[Path], scoring_fn: Callable[[Path], float]) -> List[Path]:
+        """
+        Score paths using a custom scoring function
+
+        Args:
+            paths: List of paths to score
+            scoring_fn: Function that takes a Path and returns a score (0.0-1.0)
+
+        Returns:
+            List of paths with custom scores
+        """
+        scored_paths = []
+
+        for path in paths:
+            score = scoring_fn(path)
+            # Clamp score to valid range
+            score = max(0.0, min(1.0, score))
+
+            scored_path = Path(nodes=path.nodes, edges=path.edges, score=score)
+            scored_paths.append(scored_path)
+
+        return scored_paths
+
+    def combine_scores(
+        self,
+        paths_lists: List[List[Path]],
+        weights: Optional[List[float]] = None,
+    ) -> List[Path]:
+        """
+        Combine scores from multiple scoring methods
+
+        Args:
+            paths_lists: List of path lists (each with different scores)
+            weights: Optional weights for each scoring method
+
+        Returns:
+            List of paths with combined scores
+        """
+        if not paths_lists:
+            return []
+
+        if weights is None:
+            weights = [1.0] * len(paths_lists)
+
+        # Normalize weights
+        total_weight = sum(weights)
+        weights = [w / total_weight for w in weights]
+
+        # Build path ID to combined score mapping
+        path_scores: Dict[Tuple[str, ...], Dict[str, Any]] = {}
+
+        for paths, weight in zip(paths_lists, weights):
+            for path in paths:
+                # Use path node IDs as key
+                path_key = tuple(p.id for p in path.nodes)
+
+                if path_key not in path_scores:
+                    path_scores[path_key] = {"path": path, "score": 0.0}
+
+                # Add weighted score
+                if path.score is not None:
+                    score = path_scores[path_key]["score"]
+                    if isinstance(score, (int, float)):
+                        path_scores[path_key]["score"] = score + path.score * weight
+
+        # Create scored paths
+        combined_paths = []
+        for data in path_scores.values():
+            scored_path = Path(
+                nodes=data["path"].nodes,
+                edges=data["path"].edges,
+                score=data["score"],
+            )
+            combined_paths.append(scored_path)
+
+        return combined_paths
+
+    def rank_paths(
+        self,
+        paths: List[Path],
+        top_k: Optional[int] = None,
+        min_score: Optional[float] = None,
+    ) -> List[Path]:
+        """
+        Rank paths by score and return top results
+
+        Args:
+            paths: List of paths to rank
+            top_k: Number of top paths to return (None = all)
+            min_score: Minimum score threshold (None = no threshold)
+
+        Returns:
+            Sorted list of paths (highest score first)
+        """
+        # Filter by minimum score if specified
+        if min_score is not None:
+            paths = [p for p in paths if p.score is not None and p.score >= min_score]
+
+        # Sort by score (descending)
+        sorted_paths = sorted(
+            paths,
+            key=lambda p: p.score if p.score is not None else 0.0,
+            reverse=True,
+        )
+
+        # Return top k if specified
+        if top_k is not None:
+            return sorted_paths[:top_k]
+
+        return sorted_paths

aiecs/application/knowledge_graph/validators/__init__.py

@@ -0,0 +1,13 @@
+"""
+Knowledge Graph Validators
+
+Validators for entities and relations against schema.
+"""
+
+from aiecs.application.knowledge_graph.validators.relation_validator import (
+    RelationValidator,
+)
+
+__all__ = [
+    "RelationValidator",
+]

aiecs/application/knowledge_graph/validators/relation_validator.py

@@ -0,0 +1,239 @@
+"""
+Relation Validator
+
+Validates relations against knowledge graph schema.
+"""
+
+from typing import List, Optional, Tuple
+from aiecs.domain.knowledge_graph.models.entity import Entity
+from aiecs.domain.knowledge_graph.models.relation import Relation
+from aiecs.domain.knowledge_graph.schema.graph_schema import GraphSchema
+
+
+class RelationValidator:
+    """
+    Validate relations against schema rules
+
+    Ensures that:
+    - Relation type exists in schema
+    - Source and target entity types are compatible
+    - Relation properties match schema
+    - Required properties are present
+
+    Example:
+        ```python
+        validator = RelationValidator(schema)
+
+        is_valid, errors = validator.validate_relation(
+            relation,
+            source_entity,
+            target_entity
+        )
+
+        if not is_valid:
+            print(f"Invalid relation: {errors}")
+        ```
+    """
+
+    def __init__(self, schema: Optional[GraphSchema] = None, strict: bool = False):
+        """
+        Initialize relation validator
+
+        Args:
+            schema: GraphSchema to validate against (optional)
+            strict: If True, reject relations not in schema; if False, allow unknown types
+        """
+        self.schema = schema
+        self.strict = strict
+
+    def validate_relation(self, relation: Relation, source_entity: Entity, target_entity: Entity) -> Tuple[bool, List[str]]:
+        """
+        Validate a relation against schema
+
+        Args:
+            relation: Relation to validate
+            source_entity: Source entity
+            target_entity: Target entity
+
+        Returns:
+            Tuple of (is_valid, error_messages)
+        """
+        errors = []
+
+        # Basic validation (always performed)
+        if not relation.source_id:
+            errors.append("Relation missing source_id")
+        if not relation.target_id:
+            errors.append("Relation missing target_id")
+        if not relation.relation_type:
+            errors.append("Relation missing relation_type")
+
+        # Check entity IDs match
+        if relation.source_id != source_entity.id:
+            errors.append(f"Relation source_id '{relation.source_id}' does not match " f"source_entity id '{source_entity.id}'")
+        if relation.target_id != target_entity.id:
+            errors.append(f"Relation target_id '{relation.target_id}' does not match " f"target_entity id '{target_entity.id}'")
+
+        # Schema-based validation (if schema provided)
+        if self.schema:
+            schema_errors = self._validate_against_schema(relation, source_entity, target_entity)
+            errors.extend(schema_errors)
+
+        return (len(errors) == 0, errors)
+
+    def validate_relations(self, relations: List[Relation], entities: List[Entity]) -> List[Tuple[Relation, bool, List[str]]]:
+        """
+        Validate multiple relations
+
+        Args:
+            relations: List of relations to validate
+            entities: List of entities (source and targets)
+
+        Returns:
+            List of (relation, is_valid, errors) tuples
+        """
+        # Build entity lookup
+        entity_lookup = {e.id: e for e in entities}
+
+        results = []
+        for relation in relations:
+            source = entity_lookup.get(relation.source_id)
+            target = entity_lookup.get(relation.target_id)
+
+            if not source or not target:
+                is_valid = False
+                errors = [f"Source or target entity not found for relation {relation.id}"]
+            else:
+                is_valid, errors = self.validate_relation(relation, source, target)
+
+            results.append((relation, is_valid, errors))
+
+        return results
+
+    def filter_valid_relations(self, relations: List[Relation], entities: List[Entity]) -> List[Relation]:
+        """
+        Filter relations to only valid ones
+
+        Args:
+            relations: List of relations
+            entities: List of entities
+
+        Returns:
+            List of valid relations
+        """
+        validation_results = self.validate_relations(relations, entities)
+        return [relation for relation, is_valid, errors in validation_results if is_valid]
+
+    def _validate_against_schema(self, relation: Relation, source_entity: Entity, target_entity: Entity) -> List[str]:
+        """
+        Validate relation against schema rules
+
+        Args:
+            relation: Relation to validate
+            source_entity: Source entity
+            target_entity: Target entity
+
+        Returns:
+            List of error messages (empty if valid)
+        """
+        errors = []
+
+        # Check if schema is available
+        if self.schema is None:
+            if self.strict:
+                errors.append("Schema is required for strict validation")
+            return errors
+
+        # Check if relation type exists in schema
+        if not self.schema.has_relation_type(relation.relation_type):
+            if self.strict:
+                errors.append(f"Relation type '{relation.relation_type}' not found in schema")
+            # In non-strict mode, allow unknown relation types
+            return errors
+
+        # Get relation type schema
+        rel_type_schema = self.schema.get_relation_type(relation.relation_type)
+
+        # Skip validation if relation type schema not found
+        if rel_type_schema is None:
+            return errors
+
+        # Validate source entity type
+        if rel_type_schema.source_entity_types:
+            if source_entity.entity_type not in rel_type_schema.source_entity_types:
+                errors.append(f"Source entity type '{source_entity.entity_type}' not allowed for " f"relation '{relation.relation_type}'. " f"Allowed types: {rel_type_schema.source_entity_types}")
+
+        # Validate target entity type
+        if rel_type_schema.target_entity_types:
+            if target_entity.entity_type not in rel_type_schema.target_entity_types:
+                errors.append(f"Target entity type '{target_entity.entity_type}' not allowed for " f"relation '{relation.relation_type}'. " f"Allowed types: {rel_type_schema.target_entity_types}")
+
+        # Validate relation properties against schema
+        property_errors = self._validate_relation_properties(relation, rel_type_schema)
+        errors.extend(property_errors)
+
+        return errors
+
+    def _validate_relation_properties(self, relation: Relation, rel_type_schema) -> List[str]:
+        """
+        Validate relation properties against schema
+
+        Checks:
+        - Required properties are present
+        - Property types match schema definitions
+        - Property values are within allowed ranges/values
+        - Unknown properties are not present (in strict mode)
+
+        Args:
+            relation: Relation to validate
+            rel_type_schema: RelationType schema to validate against
+
+        Returns:
+            List of error messages (empty if valid)
+        """
+        errors = []
+        relation_properties = relation.properties or {}
+
+        # Check required properties are present
+        for prop_name, prop_schema in rel_type_schema.properties.items():
+            if prop_schema.required and prop_name not in relation_properties:
+                available_props = list(rel_type_schema.properties.keys())
+                errors.append(
+                    f"Required property '{prop_name}' missing for relation type '{relation.relation_type}'. "
+                    f"Available properties: {', '.join(available_props)}"
+                )
+
+        # Validate each provided property
+        for prop_name, prop_value in relation_properties.items():
+            # Check if property exists in schema
+            if prop_name not in rel_type_schema.properties:
+                if self.strict:
+                    available_props = list(rel_type_schema.properties.keys())
+                    errors.append(
+                        f"Unknown property '{prop_name}' for relation type '{relation.relation_type}'. "
+                        f"Available properties: {', '.join(available_props) if available_props else 'none'}"
+                    )
+                # In non-strict mode, allow unknown properties
+                continue
+
+            # Get property schema
+            prop_schema = rel_type_schema.properties[prop_name]
+
+            # Validate property value against schema
+            try:
+                prop_schema.validate_value(prop_value)
+            except ValueError as e:
+                # Convert ValueError to helpful error message
+                error_msg = str(e)
+                # Enhance error message with relation context
+                if "Property" in error_msg and "'" in error_msg:
+                    # Error already includes property name, just add relation context
+                    errors.append(
+                        f"Property validation failed for relation '{relation.relation_type}': {error_msg}"
+                    )
+                else:
+                    errors.append(
+                        f"Property '{prop_name}' validation failed for relation '{relation.relation_type}': {error_msg}"
+                    )
+
+        return errors

aiecs/application/knowledge_graph/visualization/__init__.py

@@ -0,0 +1,11 @@
+"""
+Knowledge Graph Visualization
+
+Tools for visualizing and exporting knowledge graphs.
+"""
+
+from aiecs.application.knowledge_graph.visualization.graph_visualizer import (
+    GraphVisualizer,
+)
+
+__all__ = ["GraphVisualizer"]