crca 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

schemas/conversation.py

@@ -0,0 +1,193 @@
+"""
+Schema definitions for conversation management and context tracking.
+
+Implements data structures for multi-turn conversations with memory networks,
+attention mechanisms, and coreference resolution.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Tuple, Set
+from enum import Enum
+import time
+
+
+class MessageRole(Enum):
+    """Role of message sender."""
+    USER = "user"
+    AGENT = "agent"
+    SYSTEM = "system"
+
+
+@dataclass
+class ConversationMessage:
+    """
+    Represents a single message in a conversation.
+    
+    Attributes:
+        role: Role of the message sender (user/agent/system)
+        content: Message text content
+        timestamp: When message was sent (Unix timestamp)
+        metadata: Additional metadata (variables extracted, graph state, etc.)
+        message_id: Unique identifier for this message
+    """
+    role: MessageRole
+    content: str
+    timestamp: float = field(default_factory=time.time)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    message_id: Optional[str] = None
+    
+    def __post_init__(self):
+        """Generate message ID if not provided."""
+        if self.message_id is None:
+            self.message_id = f"{self.role.value}_{int(self.timestamp * 1000)}"
+
+
+@dataclass
+class VariableMapping:
+    """
+    Maps variables across conversation turns.
+    
+    Tracks variable evolution: φ: V_t → V_{t+1}
+    
+    Attributes:
+        source_variable: Variable name at turn t
+        target_variable: Variable name at turn t+1
+        confidence: Confidence in the mapping (0.0-1.0)
+        evidence: Evidence for the mapping (e.g., "same context", "explicit mention")
+        turn_from: Source turn number
+        turn_to: Target turn number
+    """
+    source_variable: str
+    target_variable: str
+    confidence: float = 1.0
+    evidence: str = ""
+    turn_from: int = 0
+    turn_to: int = 0
+
+
+@dataclass
+class GraphSnapshot:
+    """
+    Immutable snapshot of graph state at a specific turn.
+    
+    Attributes:
+        turn_number: Turn number this snapshot represents
+        nodes: Set of node names
+        edges: List of (source, target) tuples
+        node_attributes: Dictionary of node attributes
+        edge_attributes: Dictionary of edge attributes {(source, target): attrs}
+        timestamp: When snapshot was created
+    """
+    turn_number: int
+    nodes: Set[str] = field(default_factory=set)
+    edges: List[Tuple[str, str]] = field(default_factory=list)
+    node_attributes: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    edge_attributes: Dict[Tuple[str, str], Dict[str, Any]] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class ConversationContext:
+    """
+    Full conversation state with memory network and attention mechanisms.
+    
+    Implements episodic memory with exponential decay attention weights.
+    
+    Attributes:
+        conversation_id: Unique identifier for this conversation
+        messages: List of conversation messages (temporal ordering)
+        graph_snapshots: Graph state snapshots per turn
+        variable_mappings: Variable evolution mappings across turns
+        current_turn: Current turn number
+        attention_weights: Attention weights for each message (computed on demand)
+        decay_lambda: Exponential decay parameter for attention
+        topic_history: Conversation topic transitions
+        reference_resolution: Coreference resolution mappings
+    """
+    conversation_id: str
+    messages: List[ConversationMessage] = field(default_factory=list)
+    graph_snapshots: Dict[int, GraphSnapshot] = field(default_factory=dict)
+    variable_mappings: List[VariableMapping] = field(default_factory=list)
+    current_turn: int = 0
+    attention_weights: Optional[Dict[int, float]] = None
+    decay_lambda: float = 0.1  # Exponential decay parameter
+    topic_history: List[Dict[str, Any]] = field(default_factory=list)
+    reference_resolution: Dict[str, str] = field(default_factory=dict)
+    
+    def add_message(self, message: ConversationMessage) -> None:
+        """
+        Add a message to the conversation.
+        
+        Args:
+            message: Message to add
+        """
+        self.messages.append(message)
+        self.current_turn = len(self.messages)
+    
+    def get_recent_messages(self, k: int = 10) -> List[ConversationMessage]:
+        """
+        Get k most recent messages.
+        
+        Args:
+            k: Number of recent messages to retrieve
+            
+        Returns:
+            List of k most recent messages
+        """
+        return self.messages[-k:] if len(self.messages) > k else self.messages
+    
+    def compute_attention_weights(self, query: Optional[str] = None) -> Dict[int, float]:
+        """
+        Compute attention weights for messages using exponential decay.
+        
+        Attention weights: w_i = exp(-λ·(t-i)) where t is current turn, i is message turn.
+        
+        Args:
+            query: Optional query for attention computation (for future query-based attention)
+            
+        Returns:
+            Dictionary mapping message index to attention weight
+        """
+        if query is None:
+            # Simple exponential decay: w_i = exp(-λ·(t-i))
+            weights = {}
+            t = len(self.messages)
+            import math
+            for i, msg in enumerate(self.messages):
+                if NUMPY_AVAILABLE:
+                    weights[i] = float(np.exp(-self.decay_lambda * (t - i)))
+                else:
+                    weights[i] = float(math.exp(-self.decay_lambda * (t - i)))
+            self.attention_weights = weights
+            return weights
+        else:
+            # Future: Implement query-based attention
+            # For now, fall back to exponential decay
+            return self.compute_attention_weights(None)
+    
+    def get_context_window(self, window_size: int = 5) -> List[ConversationMessage]:
+        """
+        Get context window using attention-weighted selection.
+        
+        Args:
+            window_size: Maximum number of messages to include
+            
+        Returns:
+            List of messages in context window
+        """
+        weights = self.compute_attention_weights()
+        # Sort by attention weight and take top k
+        sorted_indices = sorted(weights.items(), key=lambda x: x[1], reverse=True)
+        top_indices = [idx for idx, _ in sorted_indices[:window_size]]
+        return [self.messages[i] for i in sorted(top_indices)]
+
+
+# Import numpy for attention computation
+try:
+    import numpy as np
+    NUMPY_AVAILABLE = True
+except ImportError:
+    # Fallback if numpy not available
+    import math
+    NUMPY_AVAILABLE = False
+    np = None

schemas/hybrid.py

@@ -0,0 +1,211 @@
+"""
+Schema definitions for the hybrid agent system.
+
+Defines data structures for provenance tracking, temporal edges,
+language compilation, and error correction.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Tuple, Set
+from enum import Enum
+import time
+
+
+class TemporalType(Enum):
+    """Temporal relationship types for causal edges."""
+    BEFORE = "before"
+    AFTER = "after"
+    DELAYED = "delayed"
+    FEEDBACK_LOOP = "feedback_loop"
+    IMMEDIATE = "immediate"  # Default, no temporal delay
+
+
+@dataclass
+class EdgeProvenance:
+    """
+    Tracks the provenance of a causal edge - where it came from and how confident we are.
+    
+    Attributes:
+        source_sentence: Original text that created the edge
+        extraction_pattern: Pattern that matched (pattern ID/name)
+        pattern_confidence: Initial confidence from pattern (0.0-1.0)
+        extraction_timestamp: When edge was extracted (Unix timestamp)
+        confidence_decay_rate: How confidence decays over time (per day, 0.0-1.0)
+        validation_history: List of validations/updates with timestamps
+        contradictions: List of contradictory edges found
+    """
+    source_sentence: str
+    extraction_pattern: str
+    pattern_confidence: float = 1.0
+    extraction_timestamp: float = field(default_factory=time.time)
+    confidence_decay_rate: float = 0.01  # 1% per day
+    validation_history: List[Dict[str, Any]] = field(default_factory=list)
+    contradictions: List[Dict[str, Any]] = field(default_factory=list)
+    
+    def get_current_confidence(self) -> float:
+        """
+        Calculate current confidence accounting for decay.
+        
+        Returns:
+            Current confidence value (0.0-1.0)
+        """
+        days_elapsed = (time.time() - self.extraction_timestamp) / 86400.0
+        decay_factor = (1.0 - self.confidence_decay_rate) ** days_elapsed
+        return max(0.0, min(1.0, self.pattern_confidence * decay_factor))
+    
+    def add_validation(self, validation_type: str, result: bool, notes: str = "") -> None:
+        """
+        Add a validation entry to the history.
+        
+        Args:
+            validation_type: Type of validation (e.g., "data_check", "expert_review")
+            result: Whether validation passed
+            notes: Additional notes about the validation
+        """
+        self.validation_history.append({
+            "type": validation_type,
+            "result": result,
+            "notes": notes,
+            "timestamp": time.time()
+        })
+    
+    def add_contradiction(self, contradictory_edge: str, reason: str) -> None:
+        """
+        Record a contradiction with another edge.
+        
+        Args:
+            contradictory_edge: Identifier of the contradictory edge
+            reason: Why this is a contradiction
+        """
+        self.contradictions.append({
+            "edge": contradictory_edge,
+            "reason": reason,
+            "timestamp": time.time()
+        })
+
+
+@dataclass
+class TemporalEdge:
+    """
+    Represents a temporal causal relationship.
+    
+    Attributes:
+        temporal_type: Type of temporal relationship
+        delay: Optional delay duration (in time units, e.g., days)
+        decay_function: How effect decays over time (function name or parameters)
+        feedback_strength: For feedback loops, the strength of the feedback
+    """
+    temporal_type: TemporalType = TemporalType.IMMEDIATE
+    delay: Optional[float] = None
+    decay_function: Optional[str] = None  # e.g., "exponential", "linear", "step"
+    decay_params: Dict[str, float] = field(default_factory=dict)
+    feedback_strength: float = 1.0
+    
+    def apply_temporal_decay(self, base_strength: float, time_elapsed: float) -> float:
+        """
+        Apply temporal decay to a base strength value.
+        
+        Args:
+            base_strength: Base strength of the effect
+            time_elapsed: Time elapsed since the cause (in same units as delay)
+            
+        Returns:
+            Decayed strength value
+        """
+        if self.decay_function is None:
+            return base_strength
+        
+        if self.decay_function == "exponential":
+            decay_rate = self.decay_params.get("rate", 0.1)
+            return base_strength * (1.0 - decay_rate) ** time_elapsed
+        elif self.decay_function == "linear":
+            max_time = self.decay_params.get("max_time", 100.0)
+            if time_elapsed >= max_time:
+                return 0.0
+            return base_strength * (1.0 - time_elapsed / max_time)
+        elif self.decay_function == "step":
+            threshold = self.decay_params.get("threshold", 1.0)
+            return base_strength if time_elapsed < threshold else 0.0
+        else:
+            return base_strength
+
+
+@dataclass
+class AnnotatedToken:
+    """
+    Represents a token with correction metadata (for error correction pipeline).
+    
+    Attributes:
+        original_form: What user typed
+        normalized_form: Corrected version
+        confidence: Correction confidence (0.0-1.0)
+        correction_type: Type of correction (spelling/abbreviation/inferred)
+        provenance: Why correction was made
+        metadata: Optional additional metadata (e.g., dictionary info)
+    """
+    original_form: str
+    normalized_form: str
+    confidence: float = 1.0
+    correction_type: str = "none"  # spelling, abbreviation, inferred, none
+    provenance: str = ""
+    metadata: Optional[Dict[str, Any]] = field(default=None)
+
+
+@dataclass
+class LexicalGraph:
+    """
+    Represents a compiled lexical knowledge graph.
+    
+    Attributes:
+        synonym_sets: Dictionary mapping canonical terms to sets of synonyms
+        hypernym_chains: Dictionary mapping terms to their hypernym chains
+        vocabulary: Set of all known terms
+    """
+    synonym_sets: Dict[str, Set[str]] = field(default_factory=dict)
+    hypernym_chains: Dict[str, List[str]] = field(default_factory=dict)
+    vocabulary: set = field(default_factory=set)
+
+
+@dataclass
+class SynonymSet:
+    """
+    A set of synonymous terms.
+    
+    Attributes:
+        canonical: Canonical form of the term
+        synonyms: Set of synonymous terms
+    """
+    canonical: str
+    synonyms: set = field(default_factory=set)
+
+
+@dataclass
+class DependencyTree:
+    """
+    Represents a dependency parse tree.
+    
+    Attributes:
+        nodes: List of nodes (words/phrases)
+        edges: List of (head, dependent, relation) tuples
+        root: Root node identifier
+    """
+    nodes: List[str] = field(default_factory=list)
+    edges: List[Tuple[str, str, str]] = field(default_factory=list)
+    root: Optional[str] = None
+
+
+@dataclass
+class CausalStructure:
+    """
+    Represents extracted causal structure from a sentence.
+    
+    Attributes:
+        cause: Cause variable/phrase
+        effect: Effect variable/phrase
+        relation_type: Type of causal relation
+        confidence: Confidence in the extraction
+    """
+    cause: str
+    effect: str
+    relation_type: str
+    confidence: float = 1.0

schemas/reasoning.py

@@ -0,0 +1,276 @@
+"""
+Schema definitions for chain-of-thought reasoning and proof tracking.
+
+Implements natural deduction with proof trees, explicit inference chains,
+and evidence tracking for complete traceability.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Tuple, Set
+from enum import Enum
+import time
+
+
+class InferenceRule(Enum):
+    """Inference rules for natural deduction."""
+    MODUS_PONENS = "modus_ponens"
+    UNIVERSAL_INSTANTIATION = "universal_instantiation"
+    CAUSAL_INFERENCE = "causal_inference"
+    EXTRACTION = "extraction"
+    VALIDATION = "validation"
+    INFERENCE = "inference"
+    DEDUCTION = "deduction"
+    INDUCTION = "induction"
+    ABDUCTION = "abduction"
+
+
+class StepType(Enum):
+    """Type of reasoning step."""
+    EXTRACTION = "extraction"
+    INFERENCE = "inference"
+    VALIDATION = "validation"
+    TRANSFORMATION = "transformation"
+    AGGREGATION = "aggregation"
+    DECISION = "decision"
+
+
+@dataclass
+class Evidence:
+    """
+    Evidence for a conclusion.
+    
+    Attributes:
+        source: Source of evidence (e.g., "extraction", "inference", "user_input")
+        content: Evidence content
+        confidence: Confidence in evidence (0.0-1.0)
+        timestamp: When evidence was collected
+        metadata: Additional metadata
+    """
+    source: str
+    content: Any
+    confidence: float = 1.0
+    timestamp: float = field(default_factory=time.time)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ReasoningStep:
+    """
+    Individual reasoning step in a proof chain.
+    
+    Implements a proof step with type safety and evidence tracking.
+    
+    Attributes:
+        step_id: Unique identifier for this step
+        step_type: Type of reasoning step
+        inference_rule: Inference rule used (if applicable)
+        input_state: Precondition graph G_pre (as dictionary representation)
+        operation: Description of operation performed
+        output_state: Postcondition graph G_post (as dictionary representation)
+        confidence: Bayesian posterior P(conclusion | evidence)
+        uncertainty: Uncertainty quantification (standard deviation or credible interval)
+        evidence: Set of premises {p₁, ..., pₙ} and evidence for conclusion
+        premises: List of premise step IDs
+        conclusion: Conclusion reached in this step
+        timestamp: When step was executed
+        metadata: Additional metadata
+    """
+    step_id: str
+    step_type: StepType
+    inference_rule: Optional[InferenceRule] = None
+    input_state: Dict[str, Any] = field(default_factory=dict)
+    operation: str = ""
+    output_state: Dict[str, Any] = field(default_factory=dict)
+    confidence: float = 1.0
+    uncertainty: Optional[float] = None
+    evidence: List[Evidence] = field(default_factory=list)
+    premises: List[str] = field(default_factory=list)
+    conclusion: Optional[Any] = None
+    timestamp: float = field(default_factory=time.time)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def add_evidence(self, evidence: Evidence) -> None:
+        """
+        Add evidence to this step.
+        
+        Args:
+            evidence: Evidence to add
+        """
+        self.evidence.append(evidence)
+    
+    def is_valid_proof_step(self) -> bool:
+        """
+        Check if this is a valid proof step.
+        
+        A valid step must have:
+        - Valid inference rule (if inference step)
+        - Evidence or premises
+        - Conclusion
+        
+        Returns:
+            True if valid, False otherwise
+        """
+        if self.step_type == StepType.INFERENCE and self.inference_rule is None:
+            return False
+        if not self.evidence and not self.premises:
+            return False
+        if self.conclusion is None:
+            return False
+        return True
+
+
+@dataclass
+class ReasoningChain:
+    """
+    Complete reasoning path (proof tree/DAG structure).
+    
+    Tracks complete reasoning path with backtracking support and decision point recording.
+    
+    Attributes:
+        chain_id: Unique identifier for this reasoning chain
+        steps: List of reasoning steps (ordered sequence)
+        root_step: Root step ID (starting point)
+        leaf_steps: Leaf step IDs (end points)
+        alternative_branches: Alternative proof branches explored
+        decision_points: Choice points with alternatives explored
+        success: Whether reasoning chain succeeded
+        final_conclusion: Final conclusion reached
+        timestamp: When chain was created
+        metadata: Additional metadata
+    """
+    chain_id: str
+    steps: List[ReasoningStep] = field(default_factory=list)
+    root_step: Optional[str] = None
+    leaf_steps: List[str] = field(default_factory=list)
+    alternative_branches: List[List[str]] = field(default_factory=list)
+    decision_points: List[Dict[str, Any]] = field(default_factory=list)
+    success: bool = False
+    final_conclusion: Optional[Any] = None
+    timestamp: float = field(default_factory=time.time)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def add_step(self, step: ReasoningStep) -> None:
+        """
+        Add a step to the reasoning chain.
+        
+        Args:
+            step: Reasoning step to add
+        """
+        self.steps.append(step)
+        
+        # Update root if this is first step
+        if self.root_step is None:
+            self.root_step = step.step_id
+        
+        # Update leaf steps
+        if not step.premises:  # No dependencies, could be a leaf
+            if step.step_id not in self.leaf_steps:
+                self.leaf_steps.append(step.step_id)
+        
+        # Remove from leaf steps if other steps depend on it
+        for other_step in self.steps:
+            if step.step_id in other_step.premises and step.step_id in self.leaf_steps:
+                self.leaf_steps.remove(step.step_id)
+                break
+        
+        # Add to leaf steps if no other steps depend on it
+        has_dependents = any(step.step_id in s.premises for s in self.steps if s.step_id != step.step_id)
+        if not has_dependents and step.step_id not in self.leaf_steps:
+            self.leaf_steps.append(step.step_id)
+    
+    def get_step(self, step_id: str) -> Optional[ReasoningStep]:
+        """
+        Get step by ID.
+        
+        Args:
+            step_id: Step ID
+            
+        Returns:
+            ReasoningStep or None if not found
+        """
+        for step in self.steps:
+            if step.step_id == step_id:
+                return step
+        return None
+    
+    def get_path_to_step(self, step_id: str) -> List[ReasoningStep]:
+        """
+        Get reasoning path to a specific step.
+        
+        Args:
+            step_id: Target step ID
+            
+        Returns:
+            List of steps forming path from root to target
+        """
+        step = self.get_step(step_id)
+        if step is None:
+            return []
+        
+        path = [step]
+        visited = {step_id}
+        
+        # Backtrack through premises
+        current_premises = step.premises.copy()
+        while current_premises:
+            next_premise = current_premises.pop(0)
+            if next_premise in visited:
+                continue
+            visited.add(next_premise)
+            
+            premise_step = self.get_step(next_premise)
+            if premise_step:
+                path.insert(0, premise_step)
+                current_premises.extend(premise_step.premises)
+        
+        return path
+    
+    def validate_chain(self) -> Tuple[bool, Optional[str]]:
+        """
+        Validate that reasoning chain is sound.
+        
+        Checks:
+        - All steps are valid proof steps
+        - All premises exist
+        - No circular dependencies
+        - Chain is connected
+        
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # Check all steps are valid
+        for step in self.steps:
+            if not step.is_valid_proof_step():
+                return False, f"Invalid proof step: {step.step_id}"
+        
+        # Check all premises exist
+        step_ids = {step.step_id for step in self.steps}
+        for step in self.steps:
+            for premise_id in step.premises:
+                if premise_id not in step_ids:
+                    return False, f"Premise {premise_id} not found for step {step.step_id}"
+        
+        # Check for circular dependencies (simple check)
+        # Build dependency graph and check for cycles
+        dependencies = {step.step_id: step.premises for step in self.steps}
+        visited = set()
+        rec_stack = set()
+        
+        def has_cycle(node: str) -> bool:
+            visited.add(node)
+            rec_stack.add(node)
+            for dep in dependencies.get(node, []):
+                if dep not in visited:
+                    if has_cycle(dep):
+                        return True
+                elif dep in rec_stack:
+                    return True
+            rec_stack.remove(node)
+            return False
+        
+        for step_id in step_ids:
+            if step_id not in visited:
+                if has_cycle(step_id):
+                    return False, f"Circular dependency detected involving {step_id}"
+        
+        return True, None