ouroboros-ai 0.2.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

ouroboros/evaluation/models.py

@@ -9,7 +9,9 @@ Classes:
     MechanicalResult: Aggregated Stage 1 results
     SemanticResult: Stage 2 LLM evaluation results
     Vote: Single model vote in consensus
+    VoterRole: Role in deliberative consensus
     ConsensusResult: Aggregated Stage 3 results
+    DeliberationResult: Aggregated Stage 3 deliberative results
     EvaluationContext: Input context for evaluation
     EvaluationResult: Complete pipeline output
 """
@@ -21,6 +23,20 @@ from typing import Any
 from ouroboros.events.base import BaseEvent
 
 
+class VoterRole(StrEnum):
+    """Roles in deliberative consensus.
+
+    Each role has a specific perspective in the 2-round deliberation:
+    - ADVOCATE: Argues in favor, finds strengths
+    - DEVIL: Critical perspective using ontological questions
+    - JUDGE: Weighs both sides, makes final decision
+    """
+
+    ADVOCATE = "advocate"
+    DEVIL = "devil"
+    JUDGE = "judge"
+
+
 class CheckType(StrEnum):
     """Types of mechanical checks in Stage 1.
 
@@ -120,12 +136,14 @@ class Vote:
         approved: Whether the model approves the output
         confidence: Model's confidence in its decision (0.0-1.0)
         reasoning: Explanation of the vote
+        role: Role in deliberative consensus (optional, for deliberative mode)
     """
 
     model: str
     approved: bool
     confidence: float
     reasoning: str
+    role: VoterRole | None = None
 
     def __post_init__(self) -> None:
         """Validate confidence range."""
@@ -163,6 +181,69 @@ class ConsensusResult:
         return len(self.votes)
 
 
+class FinalVerdict(StrEnum):
+    """Final verdict from Judge in deliberative consensus."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    CONDITIONAL = "conditional"
+
+
+@dataclass(frozen=True, slots=True)
+class JudgmentResult:
+    """Result from the Judge in deliberative consensus.
+
+    Attributes:
+        verdict: Final decision (approved/rejected/conditional)
+        confidence: Judge's confidence in decision (0.0-1.0)
+        reasoning: Explanation of the judgment
+        conditions: Conditions for approval (if conditional)
+    """
+
+    verdict: FinalVerdict
+    confidence: float
+    reasoning: str
+    conditions: tuple[str, ...] | None = None
+
+    def __post_init__(self) -> None:
+        """Validate confidence range."""
+        if not 0.0 <= self.confidence <= 1.0:
+            msg = f"confidence must be between 0.0 and 1.0, got {self.confidence}"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class DeliberationResult:
+    """Result of 2-round deliberative consensus.
+
+    Round 1: Advocate and Devil's Advocate present positions
+    Round 2: Judge reviews both and makes final decision
+
+    Attributes:
+        final_verdict: The Judge's final decision
+        advocate_position: The Advocate's vote and reasoning
+        devil_position: The Devil's Advocate vote and reasoning
+        judgment: The Judge's full judgment
+        is_root_solution: Whether Devil confirmed this addresses root cause
+    """
+
+    final_verdict: FinalVerdict
+    advocate_position: Vote
+    devil_position: Vote
+    judgment: JudgmentResult
+    is_root_solution: bool
+
+    @property
+    def approved(self) -> bool:
+        """Whether the final verdict is approval."""
+        return self.final_verdict == FinalVerdict.APPROVED
+
+    @property
+    def has_conditions(self) -> bool:
+        """Whether approval is conditional."""
+        return self.final_verdict == FinalVerdict.CONDITIONAL
+
+
 @dataclass(frozen=True, slots=True)
 class EvaluationContext:
     """Input context for the evaluation pipeline.

ouroboros/events/ontology.py

@@ -0,0 +1,135 @@
+"""Ontological Analysis Events.
+
+Events emitted during ontological analysis across phases.
+These events support observability and audit trails for
+the AOP-based ontological framework.
+
+Event Types:
+- ontology.analysis.passed: Analysis passed, execution continues
+- ontology.analysis.violated: Analysis failed, execution may halt
+
+Reference: docs/ontological-framework/aop-design.md
+"""
+
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+from pydantic import Field
+
+from ouroboros.core.ontology_aspect import OntologicalJoinPoint
+from ouroboros.events.base import BaseEvent
+
+
+class OntologicalAnalysisEvent(BaseEvent):
+    """Base event for ontological analysis.
+
+    Common fields for all ontology-related events.
+    """
+
+    join_point: OntologicalJoinPoint
+    """Which phase triggered this event."""
+
+    confidence: float = 0.0
+    """Analysis confidence (0.0-1.0)."""
+
+
+class OntologicalPassedEvent(OntologicalAnalysisEvent):
+    """Emitted when ontological analysis passes.
+
+    The subject passed ontological scrutiny and execution continues.
+
+    Event Type: ontology.analysis.passed
+    """
+
+    type: str = "ontology.analysis.passed"
+    aggregate_type: str = "ontology"
+    aggregate_id: str = Field(default_factory=lambda: str(uuid4()))
+
+    def __init__(
+        self,
+        *,
+        join_point: OntologicalJoinPoint,
+        confidence: float = 1.0,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize passed event.
+
+        Args:
+            join_point: Which phase triggered this event.
+            confidence: Analysis confidence.
+            **kwargs: Additional BaseEvent fields.
+        """
+        super().__init__(
+            join_point=join_point,
+            confidence=confidence,
+            data={
+                "join_point": join_point.value,
+                "confidence": confidence,
+                "outcome": "passed",
+            },
+            **kwargs,
+        )
+
+
+class OntologicalViolationEvent(OntologicalAnalysisEvent):
+    """Emitted when ontological analysis fails.
+
+    The subject failed ontological scrutiny. Execution may halt
+    depending on aspect configuration.
+
+    Event Type: ontology.analysis.violated
+    """
+
+    type: str = "ontology.analysis.violated"
+    aggregate_type: str = "ontology"
+    aggregate_id: str = Field(default_factory=lambda: str(uuid4()))
+
+    reasoning: tuple[str, ...] = ()
+    """Why the analysis failed."""
+
+    suggestions: tuple[str, ...] = ()
+    """Refinement suggestions."""
+
+    def __init__(
+        self,
+        *,
+        join_point: OntologicalJoinPoint,
+        confidence: float = 0.8,
+        reasoning: tuple[str, ...] | list[str] = (),
+        suggestions: tuple[str, ...] | list[str] = (),
+        **kwargs: Any,
+    ) -> None:
+        """Initialize violation event.
+
+        Args:
+            join_point: Which phase triggered this event.
+            confidence: Analysis confidence.
+            reasoning: Why the analysis failed.
+            suggestions: Refinement suggestions.
+            **kwargs: Additional BaseEvent fields.
+        """
+        reasoning_tuple = tuple(reasoning) if isinstance(reasoning, list) else reasoning
+        suggestions_tuple = tuple(suggestions) if isinstance(suggestions, list) else suggestions
+
+        super().__init__(
+            join_point=join_point,
+            confidence=confidence,
+            reasoning=reasoning_tuple,
+            suggestions=suggestions_tuple,
+            data={
+                "join_point": join_point.value,
+                "confidence": confidence,
+                "outcome": "violated",
+                "reasoning": reasoning_tuple,
+                "suggestions": suggestions_tuple,
+            },
+            **kwargs,
+        )
+
+
+__all__ = [
+    "OntologicalAnalysisEvent",
+    "OntologicalPassedEvent",
+    "OntologicalViolationEvent",
+]

ouroboros/mcp/__init__.py

@@ -0,0 +1,83 @@
+"""MCP (Model Context Protocol) integration for Ouroboros.
+
+This module provides both MCP client and server functionality:
+- MCP Client: Connect to external MCP servers to use their tools and resources
+- MCP Server: Expose Ouroboros functionality as an MCP server
+
+Public API:
+    Errors:
+        MCPError, MCPClientError, MCPServerError, MCPAuthError,
+        MCPTimeoutError, MCPConnectionError, MCPProtocolError,
+        MCPResourceNotFoundError, MCPToolError
+
+    Types:
+        TransportType, MCPServerConfig, MCPToolDefinition, MCPToolResult,
+        MCPToolParameter, MCPContentItem, ContentType,
+        MCPResourceDefinition, MCPResourceContent,
+        MCPPromptDefinition, MCPPromptArgument,
+        MCPCapabilities, MCPServerInfo, MCPRequest, MCPResponse
+
+    Client:
+        MCPClient (Protocol), MCPClientAdapter, MCPClientManager
+
+    Server:
+        MCPServer (Protocol), MCPServerAdapter
+"""
+
+from ouroboros.mcp.errors import (
+    MCPAuthError,
+    MCPClientError,
+    MCPConnectionError,
+    MCPError,
+    MCPProtocolError,
+    MCPResourceNotFoundError,
+    MCPServerError,
+    MCPTimeoutError,
+    MCPToolError,
+)
+from ouroboros.mcp.types import (
+    ContentType,
+    MCPCapabilities,
+    MCPContentItem,
+    MCPPromptArgument,
+    MCPPromptDefinition,
+    MCPRequest,
+    MCPResourceContent,
+    MCPResourceDefinition,
+    MCPResponse,
+    MCPServerConfig,
+    MCPServerInfo,
+    MCPToolDefinition,
+    MCPToolParameter,
+    MCPToolResult,
+    TransportType,
+)
+
+__all__ = [
+    # Errors
+    "MCPError",
+    "MCPClientError",
+    "MCPServerError",
+    "MCPAuthError",
+    "MCPTimeoutError",
+    "MCPConnectionError",
+    "MCPProtocolError",
+    "MCPResourceNotFoundError",
+    "MCPToolError",
+    # Types
+    "TransportType",
+    "ContentType",
+    "MCPServerConfig",
+    "MCPToolDefinition",
+    "MCPToolParameter",
+    "MCPToolResult",
+    "MCPContentItem",
+    "MCPResourceDefinition",
+    "MCPResourceContent",
+    "MCPPromptDefinition",
+    "MCPPromptArgument",
+    "MCPCapabilities",
+    "MCPServerInfo",
+    "MCPRequest",
+    "MCPResponse",
+]

ouroboros/mcp/client/__init__.py

@@ -0,0 +1,20 @@
+"""MCP Client package.
+
+This package provides MCP client functionality for connecting to external
+MCP servers and using their tools, resources, and prompts.
+
+Public API:
+    MCPClient: Protocol defining the client interface
+    MCPClientAdapter: Concrete implementation using the MCP SDK
+    MCPClientManager: Manager for multiple server connections
+"""
+
+from ouroboros.mcp.client.adapter import MCPClientAdapter
+from ouroboros.mcp.client.manager import MCPClientManager
+from ouroboros.mcp.client.protocol import MCPClient
+
+__all__ = [
+    "MCPClient",
+    "MCPClientAdapter",
+    "MCPClientManager",
+]