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

aiecs/domain/knowledge_graph/models/entity.py

@@ -0,0 +1,148 @@
+"""
+Entity Domain Model
+
+Represents a node/entity in the knowledge graph with properties and embeddings.
+"""
+
+from typing import Any, Optional
+from datetime import datetime
+from pydantic import BaseModel, Field, field_validator, model_validator
+import numpy as np
+
+from aiecs.infrastructure.graph_storage.tenant import validate_tenant_id, InvalidTenantIdError
+
+
+class Entity(BaseModel):
+    """
+    Knowledge Graph Entity
+
+    Represents a node in the knowledge graph with:
+    - Unique identifier
+    - Entity type (e.g., "Person", "Company", "Product")
+    - Properties (arbitrary key-value data)
+    - Optional vector embedding for semantic search
+    - Metadata (timestamps, source info)
+
+    Example:
+        ```python
+        entity = Entity(
+            id="person_001",
+            entity_type="Person",
+            properties={
+                "name": "John Doe",
+                "age": 30,
+                "occupation": "Software Engineer"
+            }
+        )
+        ```
+    """
+
+    id: str = Field(..., description="Unique identifier for the entity")
+
+    entity_type: str = Field(..., description="Type of the entity (e.g., 'Person', 'Company')")
+
+    properties: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary properties associated with the entity",
+    )
+
+    embedding: Optional[list[float]] = Field(default=None, description="Vector embedding for semantic search")
+
+    created_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="Timestamp when entity was created",
+    )
+
+    updated_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="Timestamp when entity was last updated",
+    )
+
+    source: Optional[str] = Field(
+        default=None,
+        description="Source of the entity data (e.g., document ID)",
+    )
+
+    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()}
+        # Allow arbitrary types for numpy arrays if needed
+        arbitrary_types_allowed = True
+
+    @field_validator("embedding")
+    @classmethod
+    def validate_embedding(cls, v: Optional[list[float]]) -> Optional[list[float]]:
+        """Validate embedding is a list of floats"""
+        if v is not None:
+            if not isinstance(v, list):
+                raise ValueError("Embedding must be a list of floats")
+            if not all(isinstance(x, (int, float)) for x in v):
+                raise ValueError("All embedding values must be numeric")
+        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 get_embedding_vector(self) -> Optional[np.ndarray]:
+        """
+        Get embedding as numpy array
+
+        Returns:
+            numpy array of embedding or None if no embedding
+        """
+        if self.embedding is None:
+            return None
+        return np.array(self.embedding, dtype=np.float32)
+
+    def set_embedding_vector(self, vector: np.ndarray) -> None:
+        """
+        Set embedding from numpy array
+
+        Args:
+            vector: Numpy array of embedding values
+        """
+        self.embedding = vector.tolist()
+
+    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
+        self.updated_at = datetime.utcnow()
+
+    def __str__(self) -> str:
+        return f"Entity(id={self.id}, type={self.entity_type})"
+
+    def __repr__(self) -> str:
+        return f"Entity(id='{self.id}', entity_type='{self.entity_type}', properties={len(self.properties)} keys)"

aiecs/domain/knowledge_graph/models/evidence.py

@@ -0,0 +1,178 @@
+"""
+Evidence Domain Models
+
+Models for representing evidence from reasoning processes.
+"""
+
+from typing import List, Optional, Dict, Any
+from enum import Enum
+from pydantic import BaseModel, Field
+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 EvidenceType(str, Enum):
+    """Types of evidence"""
+
+    ENTITY = "entity"  # Single entity
+    RELATION = "relation"  # Single relation
+    PATH = "path"  # Complete path
+    SUBGRAPH = "subgraph"  # Subgraph fragment
+
+
+class Evidence(BaseModel):
+    """
+    Evidence from Reasoning
+
+    Represents a piece of evidence collected during reasoning,
+    with confidence scoring and provenance tracking.
+
+    Attributes:
+        evidence_id: Unique identifier for this evidence
+        evidence_type: Type of evidence (entity, relation, path, etc.)
+        entities: Entities involved in this evidence
+        relations: Relations involved in this evidence
+        paths: Paths involved in this evidence (for path-based evidence)
+        confidence: Confidence score (0-1, higher = more confident)
+        relevance_score: Relevance to the query (0-1)
+        explanation: Human-readable explanation of this evidence
+        source: Source of this evidence (e.g., "traversal", "vector_search")
+        metadata: Additional metadata
+
+    Example:
+        ```python
+        evidence = Evidence(
+            evidence_id="ev_001",
+            evidence_type=EvidenceType.PATH,
+            entities=[alice, bob, company],
+            relations=[knows_rel, works_at_rel],
+            paths=[path],
+            confidence=0.9,
+            relevance_score=0.85,
+            explanation="Alice knows Bob who works at Company X",
+            source="multi_hop_traversal"
+        )
+        ```
+    """
+
+    evidence_id: str = Field(..., description="Unique identifier for this evidence")
+
+    evidence_type: EvidenceType = Field(..., description="Type of evidence")
+
+    entities: List[Entity] = Field(default_factory=list, description="Entities involved in this evidence")
+
+    relations: List[Relation] = Field(default_factory=list, description="Relations involved in this evidence")
+
+    paths: List[Path] = Field(default_factory=list, description="Paths involved in this evidence")
+
+    confidence: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description="Confidence score (0-1, higher = more confident)",
+    )
+
+    relevance_score: float = Field(default=0.5, ge=0.0, le=1.0, description="Relevance to the query (0-1)")
+
+    explanation: str = Field(default="", description="Human-readable explanation of this evidence")
+
+    source: str = Field(default="", description="Source of this evidence (e.g., query step ID)")
+
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+    @property
+    def combined_score(self) -> float:
+        """Get combined score (confidence * relevance)"""
+        return self.confidence * self.relevance_score
+
+    def get_entity_ids(self) -> List[str]:
+        """Get list of all entity IDs in evidence"""
+        return [entity.id for entity in self.entities]
+
+    def __str__(self) -> str:
+        return f"Evidence(type={self.evidence_type}, " f"score={self.combined_score:.2f}, " f"entities={len(self.entities)})"
+
+
+class ReasoningResult(BaseModel):
+    """
+    Result of Reasoning Process
+
+    Contains evidence collected, answer generated, and reasoning trace.
+
+    Attributes:
+        query: Original query that was answered
+        evidence: List of evidence pieces collected
+        answer: Generated answer (if applicable)
+        confidence: Overall confidence in the answer (0-1)
+        reasoning_trace: Human-readable trace of reasoning steps
+        execution_time_ms: Time taken to perform reasoning
+        metadata: Additional metadata
+
+    Example:
+        ```python
+        result = ReasoningResult(
+            query="What companies does Alice know people at?",
+            evidence=[ev1, ev2, ev3],
+            answer="Alice knows people at Company X and Company Y",
+            confidence=0.87,
+            reasoning_trace="Step 1: Find Alice\nStep 2: Find people Alice knows\n...",
+            execution_time_ms=125.5
+        )
+        ```
+    """
+
+    query: str = Field(..., description="Original query that was answered")
+
+    evidence: List[Evidence] = Field(default_factory=list, description="List of evidence pieces collected")
+
+    answer: Optional[str] = Field(default=None, description="Generated answer (if applicable)")
+
+    confidence: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Overall confidence in the answer (0-1)",
+    )
+
+    reasoning_trace: List[str] = Field(default_factory=list, description="List of reasoning steps taken")
+
+    execution_time_ms: Optional[float] = Field(default=None, ge=0.0, description="Time taken to perform reasoning")
+
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+    @property
+    def evidence_count(self) -> int:
+        """Get number of evidence pieces"""
+        return len(self.evidence)
+
+    @property
+    def has_answer(self) -> bool:
+        """Check if result has an answer"""
+        return self.answer is not None and len(self.answer) > 0
+
+    def get_top_evidence(self, n: int = 5) -> List[Evidence]:
+        """
+        Get top N evidence pieces by combined score
+
+        Args:
+            n: Number of evidence pieces to return
+
+        Returns:
+            Top N evidence pieces
+        """
+        sorted_evidence = sorted(self.evidence, key=lambda e: e.combined_score, reverse=True)
+        return sorted_evidence[:n]
+
+    def get_trace_string(self) -> str:
+        """Get reasoning trace as a single string"""
+        return "\n".join(self.reasoning_trace)
+
+    def __str__(self) -> str:
+        parts = [
+            f"ReasoningResult(evidence={self.evidence_count}",
+            f"confidence={self.confidence:.2f})",
+        ]
+        if self.has_answer and self.answer:
+            parts.insert(1, f"answer={self.answer[:50]}...")
+        return " ".join(parts)

aiecs/domain/knowledge_graph/models/inference_rule.py

@@ -0,0 +1,184 @@
+"""
+Inference Rule Domain Models
+
+Models for representing logical inference rules.
+"""
+
+from typing import List, Dict, Any
+from enum import Enum
+from pydantic import BaseModel, Field
+from aiecs.domain.knowledge_graph.models.relation import Relation
+
+
+class RuleType(str, Enum):
+    """Types of inference rules"""
+
+    TRANSITIVE = "transitive"  # A->B, B->C => A->C
+    SYMMETRIC = "symmetric"  # A->B => B->A
+    REFLEXIVE = "reflexive"  # A => A->A
+    CUSTOM = "custom"  # User-defined rule
+
+
+class InferenceRule(BaseModel):
+    """
+    Inference Rule
+
+    Represents a logical rule for inferring new relations from existing ones.
+
+    Attributes:
+        rule_id: Unique identifier for this rule
+        rule_type: Type of rule (transitive, symmetric, etc.)
+        relation_type: Relation type this rule applies to
+        description: Human-readable description
+        enabled: Whether this rule is enabled
+        confidence_decay: How much confidence decreases with each inference step (0-1)
+        metadata: Additional metadata
+
+    Example:
+        ```python
+        rule = InferenceRule(
+            rule_id="rule_001",
+            rule_type=RuleType.TRANSITIVE,
+            relation_type="WORKS_FOR",
+            description="If A works for B and B works for C, then A works for C",
+            confidence_decay=0.1
+        )
+        ```
+    """
+
+    rule_id: str = Field(..., description="Unique identifier for this rule")
+
+    rule_type: RuleType = Field(..., description="Type of inference rule")
+
+    relation_type: str = Field(..., description="Relation type this rule applies to")
+
+    description: str = Field(default="", description="Human-readable description of the rule")
+
+    enabled: bool = Field(default=True, description="Whether this rule is enabled")
+
+    confidence_decay: float = Field(
+        default=0.1,
+        ge=0.0,
+        le=1.0,
+        description="Confidence decay per inference step (0-1)",
+    )
+
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+    def can_apply(self, relation: Relation) -> bool:
+        """
+        Check if this rule can apply to a given relation
+
+        Args:
+            relation: Relation to check
+
+        Returns:
+            True if rule can apply
+        """
+        if not self.enabled:
+            return False
+        return relation.relation_type == self.relation_type
+
+
+class InferenceStep(BaseModel):
+    """
+    Single Inference Step
+
+    Represents one step in an inference chain, tracking what was inferred
+    and how.
+
+    Attributes:
+        step_id: Unique identifier for this step
+        inferred_relation: The relation that was inferred
+        source_relations: Relations used to infer this one
+        rule: The rule that was applied
+        confidence: Confidence in this inference (0-1)
+        explanation: Human-readable explanation
+
+    Example:
+        ```python
+        step = InferenceStep(
+            step_id="step_001",
+            inferred_relation=inferred_rel,
+            source_relations=[rel1, rel2],
+            rule=rule,
+            confidence=0.9,
+            explanation="Inferred from transitive rule"
+        )
+        ```
+    """
+
+    step_id: str = Field(..., description="Unique identifier for this step")
+
+    inferred_relation: Relation = Field(..., description="The relation that was inferred")
+
+    source_relations: List[Relation] = Field(..., description="Relations used to infer this one")
+
+    rule: InferenceRule = Field(..., description="The rule that was applied")
+
+    confidence: float = Field(..., ge=0.0, le=1.0, description="Confidence in this inference (0-1)")
+
+    explanation: str = Field(default="", description="Human-readable explanation of the inference")
+
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class InferenceResult(BaseModel):
+    """
+    Inference Result
+
+    Contains the results of applying inference rules.
+
+    Attributes:
+        inferred_relations: List of relations that were inferred
+        inference_steps: List of inference steps taken
+        total_steps: Total number of inference steps
+        confidence: Overall confidence in the results
+        explanation: Human-readable explanation
+
+    Example:
+        ```python
+        result = InferenceResult(
+            inferred_relations=[rel1, rel2],
+            inference_steps=[step1, step2],
+            total_steps=2,
+            confidence=0.85,
+            explanation="Inferred 2 relations using transitive rule"
+        )
+        ```
+    """
+
+    inferred_relations: List[Relation] = Field(
+        default_factory=list,
+        description="List of relations that were inferred",
+    )
+
+    inference_steps: List[InferenceStep] = Field(default_factory=list, description="List of inference steps taken")
+
+    total_steps: int = Field(default=0, ge=0, description="Total number of inference steps")
+
+    confidence: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description="Overall confidence in the results",
+    )
+
+    explanation: str = Field(default="", description="Human-readable explanation")
+
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+    @property
+    def has_results(self) -> bool:
+        """Check if any relations were inferred"""
+        return len(self.inferred_relations) > 0
+
+    def get_explanation_string(self) -> str:
+        """Get explanation as a single string"""
+        if not self.explanation:
+            return f"Inferred {len(self.inferred_relations)} relations in {self.total_steps} steps"
+        return self.explanation
+
+    def get_step_explanations(self) -> List[str]:
+        """Get explanations for each step"""
+        return [step.explanation for step in self.inference_steps]

aiecs/domain/knowledge_graph/models/path.py

@@ -0,0 +1,171 @@
+"""
+Path Domain Model
+
+Represents a path through the knowledge graph (sequence of entities and relations).
+"""
+
+from typing import List, Optional
+from pydantic import BaseModel, Field, field_validator
+from aiecs.domain.knowledge_graph.models.entity import Entity
+from aiecs.domain.knowledge_graph.models.relation import Relation
+
+
+class Path(BaseModel):
+    """
+    Knowledge Graph Path
+
+    Represents a path through the knowledge graph as a sequence of entities
+    connected by relations. Paths are results of graph traversal operations.
+
+    Attributes:
+        nodes: Sequence of entities in the path
+        edges: Sequence of relations connecting the entities
+        score: Optional relevance score for the path
+        length: Number of hops in the path
+
+    Example:
+        ```python
+        path = Path(
+            nodes=[entity1, entity2, entity3],
+            edges=[relation1_2, relation2_3],
+            score=0.85
+        )
+        ```
+
+    Invariants:
+        - len(edges) == len(nodes) - 1 (for a valid path)
+        - edges[i].source_id == nodes[i].id
+        - edges[i].target_id == nodes[i+1].id
+    """
+
+    nodes: List[Entity] = Field(..., min_length=1, description="Sequence of entities in the path")
+
+    edges: List[Relation] = Field(
+        default_factory=list,
+        description="Sequence of relations connecting entities",
+    )
+
+    score: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description="Relevance score for the path (0.0-1.0)",
+    )
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    @field_validator("edges")
+    @classmethod
+    def validate_path_structure(cls, v: List[Relation], info) -> List[Relation]:
+        """Validate that edges match nodes structure"""
+        nodes = info.data.get("nodes", [])
+        if not nodes:
+            return v
+
+        # Check edge count
+        if len(v) != len(nodes) - 1:
+            if len(v) > 0:  # Only raise error if edges are provided
+                raise ValueError(f"Number of edges ({len(v)}) must be len(nodes) - 1 ({len(nodes) - 1})")
+
+        # Validate edge connectivity (if we have edges)
+        for i, edge in enumerate(v):
+            if i < len(nodes) - 1:
+                expected_source = nodes[i].id
+                expected_target = nodes[i + 1].id
+
+                if edge.source_id != expected_source:
+                    raise ValueError(f"Edge {i} source_id ({edge.source_id}) doesn't match " f"node {i} id ({expected_source})")
+
+                if edge.target_id != expected_target:
+                    raise ValueError(f"Edge {i} target_id ({edge.target_id}) doesn't match " f"node {i+1} id ({expected_target})")
+
+        return v
+
+    @property
+    def length(self) -> int:
+        """
+        Get path length (number of hops)
+
+        Returns:
+            Number of edges in the path
+        """
+        return len(self.edges)
+
+    @property
+    def start_entity(self) -> Entity:
+        """
+        Get the starting entity of the path
+
+        Returns:
+            First entity in the path
+        """
+        return self.nodes[0]
+
+    @property
+    def end_entity(self) -> Entity:
+        """
+        Get the ending entity of the path
+
+        Returns:
+            Last entity in the path
+        """
+        return self.nodes[-1]
+
+    def get_entity_ids(self) -> List[str]:
+        """
+        Get list of entity IDs in the path
+
+        Returns:
+            List of entity IDs
+        """
+        return [node.id for node in self.nodes]
+
+    def get_relation_types(self) -> List[str]:
+        """
+        Get list of relation types in the path
+
+        Returns:
+            List of relation types
+        """
+        return [edge.relation_type for edge in self.edges]
+
+    def contains_entity(self, entity_id: str) -> bool:
+        """
+        Check if path contains a specific entity
+
+        Args:
+            entity_id: Entity ID to check
+
+        Returns:
+            True if entity is in the path
+        """
+        return entity_id in self.get_entity_ids()
+
+    def contains_relation_type(self, relation_type: str) -> bool:
+        """
+        Check if path contains a specific relation type
+
+        Args:
+            relation_type: Relation type to check
+
+        Returns:
+            True if relation type is in the path
+        """
+        return relation_type in self.get_relation_types()
+
+    def __str__(self) -> str:
+        if not self.edges:
+            return f"Path({self.nodes[0]})"
+
+        path_str = str(self.nodes[0].id)
+        for edge, node in zip(self.edges, self.nodes[1:]):
+            path_str += f" -[{edge.relation_type}]-> {node.id}"
+
+        if self.score is not None:
+            path_str += f" (score={self.score:.3f})"
+
+        return f"Path({path_str})"
+
+    def __repr__(self) -> str:
+        return f"Path(length={self.length}, nodes={len(self.nodes)}, score={self.score})"