ouroboros-ai 0.1.0__py3-none-any.whl

ouroboros/evaluation/trigger.py

@@ -0,0 +1,278 @@
+"""Consensus Trigger Matrix.
+
+Implements the 6 trigger conditions for Stage 3 consensus:
+1. Seed Modification - Any change to immutable Seed
+2. Ontology Evolution - Schema changes
+3. Goal Interpretation - Reinterpretation of goal
+4. Seed Drift Alert - drift > 0.3
+5. Stage 2 Uncertainty - uncertainty > 0.3
+6. Lateral Thinking Adoption - Persona suggestion accepted
+
+The ConsensusTrigger is stateless and returns trigger decisions.
+"""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from ouroboros.core.errors import ValidationError
+from ouroboros.core.types import Result
+from ouroboros.evaluation.models import SemanticResult
+from ouroboros.events.base import BaseEvent
+from ouroboros.events.evaluation import create_consensus_triggered_event
+
+
+class TriggerType(StrEnum):
+    """Types of consensus triggers.
+
+    FR16: Consensus Trigger Matrix - 6 trigger conditions
+    """
+
+    SEED_MODIFICATION = "seed_modification"
+    ONTOLOGY_EVOLUTION = "ontology_evolution"
+    GOAL_INTERPRETATION = "goal_interpretation"
+    SEED_DRIFT_ALERT = "seed_drift_alert"
+    STAGE2_UNCERTAINTY = "stage2_uncertainty"
+    LATERAL_THINKING_ADOPTION = "lateral_thinking_adoption"
+
+
+@dataclass(frozen=True, slots=True)
+class TriggerContext:
+    """Context for evaluating consensus triggers.
+
+    Attributes:
+        execution_id: Execution identifier
+        seed_modified: Whether seed was modified
+        ontology_changed: Whether ontology schema changed
+        goal_reinterpreted: Whether goal was reinterpreted
+        drift_score: Current drift score (0.0-1.0)
+        uncertainty_score: Stage 2 uncertainty (0.0-1.0)
+        lateral_thinking_adopted: Whether lateral thinking was adopted
+        semantic_result: Optional Stage 2 result
+    """
+
+    execution_id: str
+    seed_modified: bool = False
+    ontology_changed: bool = False
+    goal_reinterpreted: bool = False
+    drift_score: float = 0.0
+    uncertainty_score: float = 0.0
+    lateral_thinking_adopted: bool = False
+    semantic_result: SemanticResult | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TriggerResult:
+    """Result of trigger evaluation.
+
+    Attributes:
+        should_trigger: Whether consensus should be triggered
+        trigger_type: Type of trigger activated (if any)
+        reason: Human-readable reason
+        details: Additional context
+    """
+
+    should_trigger: bool
+    trigger_type: TriggerType | None = None
+    reason: str = ""
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class TriggerConfig:
+    """Configuration for trigger thresholds.
+
+    Attributes:
+        drift_threshold: Drift score above which to trigger (default 0.3)
+        uncertainty_threshold: Uncertainty above which to trigger (default 0.3)
+    """
+
+    drift_threshold: float = 0.3
+    uncertainty_threshold: float = 0.3
+
+
+class ConsensusTrigger:
+    """Evaluates whether consensus should be triggered.
+
+    Implements FR16: Consensus Trigger Matrix with 6 conditions.
+    Stateless - all state passed via TriggerContext.
+
+    Example:
+        trigger = ConsensusTrigger()
+        result = trigger.evaluate(context)
+        if result.should_trigger:
+            # Run Stage 3 consensus
+    """
+
+    def __init__(self, config: TriggerConfig | None = None) -> None:
+        """Initialize trigger evaluator.
+
+        Args:
+            config: Trigger configuration
+        """
+        self._config = config or TriggerConfig()
+
+    def evaluate(
+        self,
+        context: TriggerContext,
+    ) -> Result[tuple[TriggerResult, list[BaseEvent]], ValidationError]:
+        """Evaluate all trigger conditions.
+
+        Checks triggers in priority order and returns on first match.
+
+        Args:
+            context: Trigger evaluation context
+
+        Returns:
+            Result containing TriggerResult and events
+        """
+        events: list[BaseEvent] = []
+
+        # Check each trigger condition in priority order
+        checks = [
+            self._check_seed_modification,
+            self._check_ontology_evolution,
+            self._check_goal_interpretation,
+            self._check_seed_drift,
+            self._check_stage2_uncertainty,
+            self._check_lateral_thinking,
+        ]
+
+        for check in checks:
+            result = check(context)
+            if result.should_trigger:
+                # Emit trigger event
+                events.append(
+                    create_consensus_triggered_event(
+                        execution_id=context.execution_id,
+                        trigger_type=result.trigger_type.value if result.trigger_type else "unknown",
+                        trigger_details=result.details,
+                    )
+                )
+                return Result.ok((result, events))
+
+        # No trigger condition met
+        return Result.ok((
+            TriggerResult(
+                should_trigger=False,
+                reason="No trigger conditions met",
+            ),
+            events,
+        ))
+
+    def _check_seed_modification(self, context: TriggerContext) -> TriggerResult:
+        """Check for seed modification trigger.
+
+        Seeds are immutable, any modification requires consensus.
+        """
+        if context.seed_modified:
+            return TriggerResult(
+                should_trigger=True,
+                trigger_type=TriggerType.SEED_MODIFICATION,
+                reason="Seed modification detected - requires consensus",
+                details={"seed_modified": True},
+            )
+        return TriggerResult(should_trigger=False)
+
+    def _check_ontology_evolution(self, context: TriggerContext) -> TriggerResult:
+        """Check for ontology evolution trigger.
+
+        Schema changes affect output structure and require validation.
+        """
+        if context.ontology_changed:
+            return TriggerResult(
+                should_trigger=True,
+                trigger_type=TriggerType.ONTOLOGY_EVOLUTION,
+                reason="Ontology schema changed - requires consensus",
+                details={"ontology_changed": True},
+            )
+        return TriggerResult(should_trigger=False)
+
+    def _check_goal_interpretation(self, context: TriggerContext) -> TriggerResult:
+        """Check for goal interpretation change trigger.
+
+        Reinterpretation of the goal needs diverse verification.
+        """
+        if context.goal_reinterpreted:
+            return TriggerResult(
+                should_trigger=True,
+                trigger_type=TriggerType.GOAL_INTERPRETATION,
+                reason="Goal interpretation changed - requires consensus",
+                details={"goal_reinterpreted": True},
+            )
+        return TriggerResult(should_trigger=False)
+
+    def _check_seed_drift(self, context: TriggerContext) -> TriggerResult:
+        """Check for seed drift alert trigger.
+
+        High drift from original seed intent needs verification.
+        """
+        # Use semantic result drift if available, otherwise use context drift
+        drift = context.drift_score
+        if context.semantic_result:
+            drift = context.semantic_result.drift_score
+
+        if drift > self._config.drift_threshold:
+            return TriggerResult(
+                should_trigger=True,
+                trigger_type=TriggerType.SEED_DRIFT_ALERT,
+                reason=f"Drift score {drift:.2f} exceeds threshold {self._config.drift_threshold}",
+                details={
+                    "drift_score": drift,
+                    "threshold": self._config.drift_threshold,
+                },
+            )
+        return TriggerResult(should_trigger=False)
+
+    def _check_stage2_uncertainty(self, context: TriggerContext) -> TriggerResult:
+        """Check for Stage 2 uncertainty trigger.
+
+        High uncertainty in semantic evaluation needs multi-model verification.
+        """
+        # Use semantic result uncertainty if available
+        uncertainty = context.uncertainty_score
+        if context.semantic_result:
+            uncertainty = context.semantic_result.uncertainty
+
+        if uncertainty > self._config.uncertainty_threshold:
+            return TriggerResult(
+                should_trigger=True,
+                trigger_type=TriggerType.STAGE2_UNCERTAINTY,
+                reason=f"Uncertainty {uncertainty:.2f} exceeds threshold {self._config.uncertainty_threshold}",
+                details={
+                    "uncertainty": uncertainty,
+                    "threshold": self._config.uncertainty_threshold,
+                },
+            )
+        return TriggerResult(should_trigger=False)
+
+    def _check_lateral_thinking(self, context: TriggerContext) -> TriggerResult:
+        """Check for lateral thinking adoption trigger.
+
+        Adopting alternative approaches from personas needs verification.
+        """
+        if context.lateral_thinking_adopted:
+            return TriggerResult(
+                should_trigger=True,
+                trigger_type=TriggerType.LATERAL_THINKING_ADOPTION,
+                reason="Lateral thinking approach adopted - requires consensus",
+                details={"lateral_thinking_adopted": True},
+            )
+        return TriggerResult(should_trigger=False)
+
+
+def check_consensus_trigger(
+    context: TriggerContext,
+    config: TriggerConfig | None = None,
+) -> Result[tuple[TriggerResult, list[BaseEvent]], ValidationError]:
+    """Convenience function for checking consensus triggers.
+
+    Args:
+        context: Trigger evaluation context
+        config: Optional configuration
+
+    Returns:
+        Result with TriggerResult and events
+    """
+    trigger = ConsensusTrigger(config)
+    return trigger.evaluate(context)

ouroboros/events/__init__.py

@@ -0,0 +1,5 @@
+"""Ouroboros events module - event definitions for event sourcing."""
+
+from ouroboros.events.base import BaseEvent
+
+__all__ = ["BaseEvent"]

ouroboros/events/base.py

@@ -0,0 +1,80 @@
+"""Base event definition for event sourcing.
+
+All events in Ouroboros inherit from BaseEvent. Events are immutable
+(frozen Pydantic models) and follow the dot.notation.past_tense naming convention.
+"""
+
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class BaseEvent(BaseModel, frozen=True):
+    """Base class for all Ouroboros events.
+
+    Events are immutable records of state changes. They are persisted in the
+    event store and can be replayed to reconstruct aggregate state.
+
+    Attributes:
+        id: Unique event identifier (UUID).
+        type: Event type following dot.notation.past_tense convention.
+              Examples: "ontology.concept.added", "execution.ac.completed"
+        timestamp: When the event occurred (UTC).
+        aggregate_type: Type of aggregate this event belongs to.
+        aggregate_id: Unique identifier of the aggregate.
+        data: Event-specific payload data.
+        consensus_id: Optional consensus identifier for grouped events.
+
+    Example:
+        event = BaseEvent(
+            type="ontology.concept.added",
+            aggregate_type="ontology",
+            aggregate_id="ont-123",
+            data={"concept_name": "authentication", "weight": 1.0}
+        )
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    type: str
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    aggregate_type: str
+    aggregate_id: str
+    data: dict[str, Any] = Field(default_factory=dict)
+    consensus_id: str | None = Field(default=None)
+
+    def to_db_dict(self) -> dict[str, Any]:
+        """Convert event to dictionary for database insertion.
+
+        Returns:
+            Dictionary with keys matching the events table columns.
+        """
+        return {
+            "id": self.id,
+            "event_type": self.type,
+            "timestamp": self.timestamp,
+            "aggregate_type": self.aggregate_type,
+            "aggregate_id": self.aggregate_id,
+            "payload": self.data,
+            "consensus_id": self.consensus_id,
+        }
+
+    @classmethod
+    def from_db_row(cls, row: dict[str, Any]) -> BaseEvent:
+        """Create event from database row.
+
+        Args:
+            row: Dictionary from database query result.
+
+        Returns:
+            BaseEvent instance.
+        """
+        return cls(
+            id=row["id"],
+            type=row["event_type"],
+            timestamp=row["timestamp"],
+            aggregate_type=row["aggregate_type"],
+            aggregate_id=row["aggregate_id"],
+            data=row["payload"],
+        )

ouroboros/events/decomposition.py

@@ -0,0 +1,153 @@
+"""Event definitions for AC decomposition and atomicity detection.
+
+These events enable full traceability of AC lifecycle through event sourcing:
+- Atomicity checks and their results
+- AC decomposition into children
+- AC marking as atomic (ready for execution)
+
+Event naming follows dot.notation.past_tense convention.
+"""
+
+from __future__ import annotations
+
+from ouroboros.events.base import BaseEvent
+
+
+def create_ac_atomicity_checked_event(
+    ac_id: str,
+    execution_id: str,
+    is_atomic: bool,
+    complexity_score: float,
+    tool_count: int,
+    estimated_duration: int,
+    reasoning: str,
+) -> BaseEvent:
+    """Factory for AC atomicity check event.
+
+    Emitted when an AC's atomicity has been evaluated.
+
+    Args:
+        ac_id: Unique identifier for the AC.
+        execution_id: Associated execution ID.
+        is_atomic: Whether the AC is atomic.
+        complexity_score: Normalized complexity (0.0-1.0).
+        tool_count: Estimated number of tools required.
+        estimated_duration: Estimated duration in seconds.
+        reasoning: Explanation of the atomicity decision.
+
+    Returns:
+        BaseEvent with type "ac.atomicity.checked".
+    """
+    return BaseEvent(
+        type="ac.atomicity.checked",
+        aggregate_type="ac_decomposition",
+        aggregate_id=ac_id,
+        data={
+            "execution_id": execution_id,
+            "is_atomic": is_atomic,
+            "complexity_score": complexity_score,
+            "tool_count": tool_count,
+            "estimated_duration": estimated_duration,
+            "reasoning": reasoning,
+        },
+    )
+
+
+def create_ac_decomposed_event(
+    parent_ac_id: str,
+    execution_id: str,
+    child_ac_ids: list[str],
+    child_contents: list[str],
+    depth: int,
+    reasoning: str,
+) -> BaseEvent:
+    """Factory for AC decomposition event.
+
+    Emitted when a non-atomic AC is decomposed into child ACs.
+
+    Args:
+        parent_ac_id: ID of the parent AC being decomposed.
+        execution_id: Associated execution ID.
+        child_ac_ids: List of child AC IDs.
+        child_contents: List of child AC content strings.
+        depth: Current depth in the AC tree.
+        reasoning: Explanation of the decomposition strategy.
+
+    Returns:
+        BaseEvent with type "ac.decomposition.completed".
+    """
+    return BaseEvent(
+        type="ac.decomposition.completed",
+        aggregate_type="ac_decomposition",
+        aggregate_id=parent_ac_id,
+        data={
+            "execution_id": execution_id,
+            "child_ac_ids": child_ac_ids,
+            "child_contents": child_contents,
+            "child_count": len(child_ac_ids),
+            "depth": depth,
+            "reasoning": reasoning,
+        },
+    )
+
+
+def create_ac_marked_atomic_event(
+    ac_id: str,
+    execution_id: str,
+    depth: int,
+) -> BaseEvent:
+    """Factory for AC marked atomic event.
+
+    Emitted when an AC is confirmed as atomic and ready for direct execution.
+
+    Args:
+        ac_id: Unique identifier for the AC.
+        execution_id: Associated execution ID.
+        depth: Current depth in the AC tree.
+
+    Returns:
+        BaseEvent with type "ac.marked_atomic".
+    """
+    return BaseEvent(
+        type="ac.marked_atomic",
+        aggregate_type="ac_decomposition",
+        aggregate_id=ac_id,
+        data={
+            "execution_id": execution_id,
+            "depth": depth,
+        },
+    )
+
+
+def create_ac_decomposition_failed_event(
+    ac_id: str,
+    execution_id: str,
+    error_message: str,
+    error_type: str,
+    depth: int,
+) -> BaseEvent:
+    """Factory for AC decomposition failure event.
+
+    Emitted when decomposition fails (max depth, cyclic, LLM error).
+
+    Args:
+        ac_id: Unique identifier for the AC.
+        execution_id: Associated execution ID.
+        error_message: Human-readable error description.
+        error_type: Type of error (e.g., "max_depth", "cyclic", "llm_failure").
+        depth: Current depth when failure occurred.
+
+    Returns:
+        BaseEvent with type "ac.decomposition.failed".
+    """
+    return BaseEvent(
+        type="ac.decomposition.failed",
+        aggregate_type="ac_decomposition",
+        aggregate_id=ac_id,
+        data={
+            "execution_id": execution_id,
+            "error_message": error_message,
+            "error_type": error_type,
+            "depth": depth,
+        },
+    )