aiecs 1.5.1__py3-none-any.whl

aiecs/application/knowledge_graph/validators/relation_validator.py

@@ -0,0 +1,189 @@
+"""
+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 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)
+
+        # 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}"
+                )
+
+        # TODO: Validate relation properties against schema (if PropertySchema defined)
+        # This would check:
+        # - Required properties are present
+        # - Property types match schema
+        # - Values are within allowed ranges/values
+
+        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"]

aiecs/application/knowledge_graph/visualization/graph_visualizer.py

@@ -0,0 +1,321 @@
+"""
+Graph Visualization Utilities
+
+Export knowledge graphs to various formats for visualization.
+"""
+
+from typing import List, Dict, Any
+from aiecs.domain.knowledge_graph.models.entity import Entity
+from aiecs.domain.knowledge_graph.models.relation import Relation
+from aiecs.domain.knowledge_graph.models.path import Path
+
+
+class GraphVisualizer:
+    """
+    Visualize knowledge graphs in various formats
+
+    Supports export to:
+    - DOT format (Graphviz)
+    - JSON for D3.js, Cytoscape.js, etc.
+    - NetworkX-compatible format
+
+    Example:
+        ```python
+        visualizer = GraphVisualizer()
+
+        # Export to DOT
+        dot = visualizer.to_dot(entities, relations)
+        with open("graph.dot", "w") as f:
+            f.write(dot)
+
+        # Export to JSON
+        json_data = visualizer.to_json(entities, relations)
+        ```
+    """
+
+    def to_dot(
+        self,
+        entities: List[Entity],
+        relations: List[Relation],
+        graph_name: str = "knowledge_graph",
+        include_properties: bool = True,
+        max_label_length: int = 50,
+    ) -> str:
+        """
+        Export graph to DOT format (Graphviz)
+
+        Args:
+            entities: List of entities
+            relations: List of relations
+            graph_name: Name of the graph
+            include_properties: Include entity properties in labels
+            max_label_length: Maximum label length
+
+        Returns:
+            DOT format string
+        """
+        lines = []
+        lines.append(f"digraph {graph_name} {{")
+        lines.append("  rankdir=LR;")
+        lines.append("  node [shape=box, style=rounded];")
+        lines.append("")
+
+        # Add nodes
+        for entity in entities:
+            label = self._create_entity_label(entity, include_properties, max_label_length)
+            node_id = self._sanitize_id(entity.id)
+            color = self._get_entity_color(entity.entity_type)
+
+            lines.append(
+                f'  {node_id} [label="{label}", fillcolor="{color}", style="rounded,filled"];'
+            )
+
+        lines.append("")
+
+        # Add edges
+        for relation in relations:
+            source_id = self._sanitize_id(relation.source_id)
+            target_id = self._sanitize_id(relation.target_id)
+            label = relation.relation_type
+
+            lines.append(f'  {source_id} -> {target_id} [label="{label}"];')
+
+        lines.append("}")
+        return "\n".join(lines)
+
+    def to_json(
+        self,
+        entities: List[Entity],
+        relations: List[Relation],
+        format: str = "d3",
+    ) -> Dict[str, Any]:
+        """
+        Export graph to JSON format
+
+        Args:
+            entities: List of entities
+            relations: List of relations
+            format: JSON format ("d3", "cytoscape", "networkx")
+
+        Returns:
+            Dictionary suitable for JSON export
+        """
+        if format == "d3":
+            return self._to_d3_json(entities, relations)
+        elif format == "cytoscape":
+            return self._to_cytoscape_json(entities, relations)
+        elif format == "networkx":
+            return self._to_networkx_json(entities, relations)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+
+    def _to_d3_json(self, entities: List[Entity], relations: List[Relation]) -> Dict[str, Any]:
+        """Export to D3.js force-directed graph format"""
+        nodes = []
+        for entity in entities:
+            nodes.append(
+                {
+                    "id": entity.id,
+                    "name": entity.properties.get("name", entity.id),
+                    "type": entity.entity_type,
+                    "properties": entity.properties,
+                    "group": hash(entity.entity_type) % 10,  # Color group
+                }
+            )
+
+        links = []
+        for relation in relations:
+            links.append(
+                {
+                    "source": relation.source_id,
+                    "target": relation.target_id,
+                    "type": relation.relation_type,
+                    "properties": relation.properties,
+                }
+            )
+
+        return {"nodes": nodes, "links": links}
+
+    def _to_cytoscape_json(
+        self, entities: List[Entity], relations: List[Relation]
+    ) -> Dict[str, Any]:
+        """Export to Cytoscape.js format"""
+        elements = []
+
+        # Add nodes
+        for entity in entities:
+            elements.append(
+                {
+                    "data": {
+                        "id": entity.id,
+                        "label": entity.properties.get("name", entity.id),
+                        "type": entity.entity_type,
+                        "properties": entity.properties,
+                    },
+                    "group": "nodes",
+                }
+            )
+
+        # Add edges
+        for relation in relations:
+            elements.append(
+                {
+                    "data": {
+                        "id": relation.id,
+                        "source": relation.source_id,
+                        "target": relation.target_id,
+                        "label": relation.relation_type,
+                        "properties": relation.properties,
+                    },
+                    "group": "edges",
+                }
+            )
+
+        return {"elements": elements}
+
+    def _to_networkx_json(
+        self, entities: List[Entity], relations: List[Relation]
+    ) -> Dict[str, Any]:
+        """Export to NetworkX node-link format"""
+        nodes = []
+        for entity in entities:
+            nodes.append(
+                {
+                    "id": entity.id,
+                    "entity_type": entity.entity_type,
+                    **entity.properties,
+                }
+            )
+
+        links = []
+        for relation in relations:
+            links.append(
+                {
+                    "source": relation.source_id,
+                    "target": relation.target_id,
+                    "relation_type": relation.relation_type,
+                    **relation.properties,
+                }
+            )
+
+        return {
+            "directed": True,
+            "multigraph": False,
+            "graph": {},
+            "nodes": nodes,
+            "links": links,
+        }
+
+    def to_mermaid(
+        self,
+        entities: List[Entity],
+        relations: List[Relation],
+        max_entities: int = 50,
+    ) -> str:
+        """
+        Export graph to Mermaid diagram format
+
+        Args:
+            entities: List of entities
+            relations: List of relations
+            max_entities: Maximum entities to include
+
+        Returns:
+            Mermaid diagram string
+        """
+        lines = []
+        lines.append("graph LR")
+
+        # Limit entities for readability
+        entities_subset = entities[:max_entities]
+        entity_ids = {e.id for e in entities_subset}
+
+        # Add nodes
+        for entity in entities_subset:
+            label = entity.properties.get("name", entity.id)
+            label = label[:30]  # Truncate long labels
+            node_id = self._sanitize_id(entity.id)
+            lines.append(f'  {node_id}["{label}"]')
+
+        # Add edges (only between included entities)
+        for relation in relations:
+            if relation.source_id in entity_ids and relation.target_id in entity_ids:
+                source_id = self._sanitize_id(relation.source_id)
+                target_id = self._sanitize_id(relation.target_id)
+                label = relation.relation_type
+                lines.append(f"  {source_id} -->|{label}| {target_id}")
+
+        return "\n".join(lines)
+
+    def export_path_to_dot(self, path: Path) -> str:
+        """
+        Export a single path to DOT format
+
+        Args:
+            path: Path to export
+
+        Returns:
+            DOT format string
+        """
+        lines = []
+        lines.append("digraph path {")
+        lines.append("  rankdir=LR;")
+        lines.append("  node [shape=box, style=rounded];")
+        lines.append("")
+
+        # Add nodes from path
+        for entity in path.nodes:
+            label = entity.properties.get("name", entity.id)
+            node_id = self._sanitize_id(entity.id)
+            lines.append(f'  {node_id} [label="{label}"];')
+
+        lines.append("")
+
+        # Add edges from path
+        for relation in path.edges:
+            source_id = self._sanitize_id(relation.source_id)
+            target_id = self._sanitize_id(relation.target_id)
+            label = relation.relation_type
+            lines.append(f'  {source_id} -> {target_id} [label="{label}"];')
+
+        lines.append("}")
+        return "\n".join(lines)
+
+    def _create_entity_label(
+        self, entity: Entity, include_properties: bool, max_length: int
+    ) -> str:
+        """Create label for entity node"""
+        label_parts = [f"{entity.entity_type}: {entity.id}"]
+
+        if include_properties and entity.properties:
+            # Add key properties
+            for key, value in list(entity.properties.items())[:3]:
+                label_parts.append(f"{key}: {value}")
+
+        label = "\\n".join(label_parts)
+
+        if len(label) > max_length:
+            label = label[:max_length] + "..."
+
+        return label
+
+    def _sanitize_id(self, id_str: str) -> str:
+        """Sanitize ID for DOT format"""
+        # Replace special characters
+        sanitized = id_str.replace("-", "_").replace(":", "_").replace(" ", "_")
+        # Ensure it starts with a letter
+        if not sanitized[0].isalpha():
+            sanitized = "n_" + sanitized
+        return sanitized
+
+    def _get_entity_color(self, entity_type: str) -> str:
+        """Get color for entity type"""
+        colors = {
+            "Person": "lightblue",
+            "Company": "lightgreen",
+            "Product": "lightyellow",
+            "Location": "lightcoral",
+            "Event": "lightpink",
+            "Document": "lightgray",
+        }
+        return colors.get(entity_type, "white")

aiecs/common/__init__.py

@@ -0,0 +1,9 @@
+"""
+Common utilities and shared components
+"""
+
+from . import knowledge_graph
+
+__all__ = [
+    "knowledge_graph",
+]

aiecs/common/knowledge_graph/__init__.py

@@ -0,0 +1,17 @@
+"""Common knowledge graph utilities and patterns"""
+
+from .runnable import (
+    Runnable,
+    RunnableConfig,
+    RunnableState,
+    ExecutionMetrics,
+    CircuitBreaker,
+)
+
+__all__ = [
+    "Runnable",
+    "RunnableConfig",
+    "RunnableState",
+    "ExecutionMetrics",
+    "CircuitBreaker",
+]