sondera-harness 0.6.0__py3-none-any.whl

sondera/tui/widgets/violations_list.py

@@ -0,0 +1,78 @@
+from textual.app import ComposeResult
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import DataTable
+
+from sondera.types import AdjudicationRecord, Decision
+
+
+class ViolationsList(Widget):
+    """Widget displaying a list of violations/adjudications in a table format."""
+
+    BORDER_TITLE = "Adjudications"
+
+    adjudications: reactive[list[AdjudicationRecord]] = reactive([])
+
+    HEADERS = ["Decision", "Agent", "Trajectory", "Step", "Reason", "Annotations"]
+
+    def compose(self) -> ComposeResult:
+        yield DataTable()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.add_columns(*self.HEADERS)
+        table.cursor_type = "row"
+        table.zebra_stripes = True
+        table.can_focus = True
+
+    def watch_adjudications(
+        self,
+        _old_adjudications: list[AdjudicationRecord],
+        new_adjudications: list[AdjudicationRecord],
+    ) -> None:
+        table = self.query_one(DataTable)
+        table.clear()
+        for record in new_adjudications:
+            decision = record.adjudication.decision
+            if decision == Decision.DENY:
+                decision_display = "❌ DENY"
+            elif decision == Decision.ESCALATE:
+                decision_display = "⚠️ ESCALATE"
+            else:
+                decision_display = "✅ ALLOW"
+
+            reason = record.adjudication.reason
+            reason_display = reason[:40] + "..." if len(reason) > 43 else reason
+
+            # Format annotations as comma-separated policy IDs
+            annotations = record.adjudication.annotations
+            if annotations:
+                ann_ids = [ann.id for ann in annotations]
+                annotations_display = ", ".join(ann_ids)
+                if len(annotations_display) > 30:
+                    annotations_display = annotations_display[:27] + "..."
+            else:
+                annotations_display = "-"
+
+            table.add_row(
+                decision_display,
+                record.agent_id[:12] + "..."
+                if len(record.agent_id) > 15
+                else record.agent_id,
+                record.trajectory_id[:8] + "..."
+                if len(record.trajectory_id) > 11
+                else record.trajectory_id,
+                record.step_id[:8] + "..."
+                if len(record.step_id) > 11
+                else record.step_id,
+                reason_display,
+                annotations_display,
+            )
+
+    def get_selected_adjudication(self) -> AdjudicationRecord | None:
+        """Get the currently selected adjudication record from the table."""
+        table = self.query_one(DataTable)
+        cursor_row = table.cursor_row
+        if cursor_row is not None and 0 <= cursor_row < len(self.adjudications):
+            return self.adjudications[cursor_row]
+        return None

sondera/tui/widgets/violations_summary.py

@@ -0,0 +1,104 @@
+from collections import Counter
+
+from textual.app import ComposeResult
+from textual.containers import Container, Horizontal
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Digits, Static
+
+from sondera.types import AdjudicationRecord, Decision
+
+
+class ViolationsSummary(Widget):
+    """Widget displaying violations statistics.
+
+    Shows:
+    - Total violations count
+    - Violations grouped by agent
+    - Violations grouped by policy
+    """
+
+    BORDER_TITLE = "Violations Summary"
+
+    adjudications: reactive[list[AdjudicationRecord]] = reactive([], recompose=True)
+
+    def _get_violations(self) -> list[AdjudicationRecord]:
+        """Filter adjudications to only include violations (DENY decisions)."""
+        return [
+            adj
+            for adj in self.adjudications
+            if adj.adjudication.decision == Decision.DENY
+        ]
+
+    def _get_escalations(self) -> list[AdjudicationRecord]:
+        """Filter adjudications to include escalations."""
+        return [
+            adj
+            for adj in self.adjudications
+            if adj.adjudication.decision == Decision.ESCALATE
+        ]
+
+    def _count_by_agent(self, violations: list[AdjudicationRecord]) -> Counter:
+        """Count violations by agent ID."""
+        return Counter(v.agent_id for v in violations)
+
+    def _count_by_policy(self, violations: list[AdjudicationRecord]) -> Counter:
+        """Count violations by policy (from reason field)."""
+        # Extract policy identifier from reason - typically first word or phrase
+        return Counter(v.adjudication.reason.split(":")[0].strip() for v in violations)
+
+    def compose(self) -> ComposeResult:
+        violations = self._get_violations()
+        escalations = self._get_escalations()
+        total_adjudications = len(self.adjudications)
+        allowed = total_adjudications - len(violations) - len(escalations)
+
+        # Overall counts
+        yield Static("[bold]Overview[/bold]", classes="section-header")
+        with Horizontal(classes="summary-row"):
+            with Container(classes="summary-item"):
+                yield Static("Total Adjudications")
+                yield Digits(str(total_adjudications), classes="summary-digit")
+            with Container(classes="summary-item"):
+                yield Static("Allowed", classes="stat-allowed")
+                yield Digits(str(allowed), classes="summary-digit digit-allowed")
+            with Container(classes="summary-item"):
+                yield Static("Violations", classes="stat-violations")
+                yield Digits(
+                    str(len(violations)), classes="summary-digit digit-violations"
+                )
+            with Container(classes="summary-item"):
+                yield Static("Escalated", classes="stat-escalated")
+                yield Digits(
+                    str(len(escalations)), classes="summary-digit digit-escalated"
+                )
+
+        # Violations by Agent
+        yield Static("[bold]Violations by Agent[/bold]", classes="section-header")
+        by_agent = self._count_by_agent(violations)
+        if by_agent:
+            with Horizontal(classes="summary-row"):
+                for agent_id, count in by_agent.most_common(5):
+                    with Container(classes="summary-item"):
+                        display_id = (
+                            agent_id[:12] + "..." if len(agent_id) > 15 else agent_id
+                        )
+                        yield Static(display_id, classes="agent-label")
+                        yield Digits(str(count), classes="summary-digit")
+        else:
+            yield Static("No violations by agent", classes="empty-message")
+
+        # Violations by Policy/Reason
+        yield Static("[bold]Violations by Policy[/bold]", classes="section-header")
+        by_policy = self._count_by_policy(violations)
+        if by_policy:
+            with Horizontal(classes="summary-row"):
+                for policy, count in by_policy.most_common(5):
+                    with Container(classes="summary-item"):
+                        display_policy = (
+                            policy[:15] + "..." if len(policy) > 18 else policy
+                        )
+                        yield Static(display_policy, classes="policy-label")
+                        yield Digits(str(count), classes="summary-digit")
+        else:
+            yield Static("No violations by policy", classes="empty-message")

sondera/types.py

@@ -0,0 +1,346 @@
+"""Sondera SDK type definitions for agent interoperability and policy evaluation."""
+
+import uuid
+from datetime import datetime
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class Model(BaseModel):
+    """Base model for all Sondera SDK types."""
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class Parameter(Model):
+    """
+    Parameter object allows the definition of input and output data types.
+
+    Simple parameter type theory for now.
+    """
+
+    name: str
+    """ Name of the parameter. For human-readable display or metadata.
+    """
+    description: str
+    """ Description of the parameter. For human-readable display or metadata.
+    """
+    type: str
+    """ Type of the parameter.
+    """
+
+
+class SourceCode(Model):
+    language: str
+    code: str
+
+
+class Tool(Model):
+    id: str | None = None
+    """ Optional unique identifier for the tool. Auto-generated if not provided.
+    """
+    name: str
+    """ Name of the tool. For human-readable display or metadata.
+    """
+    description: str
+    """ Description of the tool. For human-readable display or metadata.
+    """
+    parameters: list[Parameter]
+    """ The parameters that are used by the tool.
+    """
+    parameters_json_schema: str | None = None
+    """ JSON schema for the tool parameters.
+    """
+    response: str | None = None
+    """ The type that is returned by the tool.
+    """
+    response_json_schema: str | None = None
+    """ JSON schema for the tool response.
+    """
+    source: SourceCode | None = None
+    """ The source of the tool if available.
+    """
+
+
+class Agent(Model):
+    id: str
+    """ Unique identifier for the agent.
+    """
+    provider_id: str
+    """ Identifier for the provider of the agent.
+    """
+    name: str
+    """ Name of the agent. For human-readable display or metadata.
+    """
+    description: str
+    """ Description of the agent. For human-readable display or metadata.
+    """
+    instruction: str
+    """ Instruction or goal of the agent.
+    """
+    tools: list[Tool]
+
+
+class TrajectoryStatus(Enum):
+    """Status of the trajectory."""
+
+    UNKNOWN = "unknown"
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    SUSPENDED = "suspended"
+    FAILED = "failed"
+
+
+class Stage(Enum):
+    """Lifecycle stage of the step."""
+
+    PRE_RUN = "pre_run"
+    PRE_MODEL = "pre_model"
+    POST_MODEL = "post_model"
+    PRE_TOOL = "pre_tool"
+    POST_TOOL = "post_tool"
+    POST_RUN = "post_run"
+
+
+class Role(Enum):
+    """Role of the step."""
+
+    USER = "user"
+    MODEL = "model"
+    TOOL = "tool"
+    SYSTEM = "system"
+
+
+class TrajectoryStep(Model):
+    role: Role
+    """ Role of the step.
+    """
+    state: dict[str, Any] = Field(default_factory=dict)
+    """ State of the step.
+    """
+    stage: Stage
+    """ Stage of the step.
+    """
+    created_at: datetime = Field(default_factory=datetime.now)
+    """ Created at timestamp.
+    """
+    context: Any | None = None
+    """ Context of the step.
+    """
+    content: Any
+    """ Content of the step.
+    """
+
+
+class Trajectory(Model):
+    id: str = Field(default_factory=lambda: f"traj-{uuid.uuid4()}")
+    """ Unique identifier for the trajectory.
+    """
+    agent_id: str = Field(default_factory=lambda: "agent-1")
+    """ Identifier for the agent that created the trajectory.
+    """
+    status: TrajectoryStatus = Field(default=TrajectoryStatus.PENDING)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """ Metadata of the trajectory.
+    """
+    created_at: datetime = Field(default_factory=datetime.now)
+    """ Created at timestamp.
+    """
+    updated_at: datetime = Field(default_factory=datetime.now)
+    """ Updated at timestamp.
+    """
+    started_at: datetime | None = Field(default=None)
+    """ Started at timestamp.
+    """
+    ended_at: datetime | None = Field(default=None)
+    """ Ended at timestamp.
+    """
+    steps: list[TrajectoryStep] = Field(default_factory=list)
+
+    @property
+    def duration(self) -> float | None:
+        """Calculate trajectory duration in seconds."""
+        if self.started_at and self.ended_at:
+            return (self.ended_at - self.started_at).total_seconds()
+        return None
+
+    @property
+    def step_count(self) -> int:
+        """Get the total number of steps."""
+        return len(self.steps)
+
+    @property
+    def is_completed(self) -> bool:
+        """Check if trajectory is in a terminal state."""
+        return self.status in [TrajectoryStatus.COMPLETED, TrajectoryStatus.FAILED]
+
+    @property
+    def is_active(self) -> bool:
+        """Check if trajectory is currently running."""
+        return self.status == TrajectoryStatus.RUNNING
+
+    def get_steps_by_role(self, role: Role) -> list[TrajectoryStep]:
+        """Get all steps with a specific role."""
+        return [step for step in self.steps if step.role == role]
+
+    def get_steps_by_stage(self, stage: Stage) -> list[TrajectoryStep]:
+        """Get all steps at a specific stage."""
+        return [step for step in self.steps if step.stage == stage]
+
+
+class PolicyEngineMode(Enum):
+    """Policy engine mode."""
+
+    MONITOR = "monitor"
+    """Monitor policy. Run policies but allow all actions."""
+    GOVERN = "govern"
+    """Govern policy on all actions."""
+
+
+class Decision(Enum):
+    """Decision of the adjudication."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    ESCALATE = "escalate"
+
+
+class PolicyAnnotation(Model):
+    """Annotation from a policy evaluation."""
+
+    id: str
+    """Unique identifier of the policy that produced this annotation."""
+    description: str
+    """Human-readable description of why this annotation was added."""
+    custom: dict[str, str] = Field(default_factory=dict)
+    """Custom key-value metadata from the policy."""
+
+
+class Adjudication(Model):
+    """Result of the adjudication."""
+
+    decision: Decision
+    """Whether the input is allowed."""
+    reason: str
+    """Reason for the adjudication decision."""
+    annotations: list[PolicyAnnotation] = Field(default_factory=list)
+    """Annotations from policy evaluations."""
+
+    @property
+    def is_denied(self) -> bool:
+        """Check if is denied."""
+        return self.decision == Decision.DENY
+
+    @property
+    def is_allowed(self) -> bool:
+        """Check if allowed."""
+        return self.decision == Decision.ALLOW
+
+    @property
+    def is_escalated(self) -> bool:
+        """Check if result requires escalation."""
+        return self.decision == Decision.ESCALATE
+
+
+class AdjudicatedStep(Model):
+    """Result of the adjudicated input."""
+
+    mode: PolicyEngineMode
+    """Mode of the adjudication."""
+    adjudication: Adjudication
+    """Adjudication of the input."""
+    step: TrajectoryStep
+    """Step of the adjudication."""
+
+    @property
+    def is_denied(self) -> bool:
+        """Check if result is denied."""
+        return (
+            self.adjudication.decision == Decision.DENY
+            and self.mode == PolicyEngineMode.GOVERN
+        )
+
+    @property
+    def is_allowed(self) -> bool:
+        """Check if result is allowed."""
+        return self.adjudication.decision == Decision.ALLOW
+
+    @property
+    def is_escalated(self) -> bool:
+        """Check if result requires escalation."""
+        return (
+            self.adjudication.decision == Decision.ESCALATE
+            and self.mode == PolicyEngineMode.GOVERN
+        )
+
+    @property
+    def message(self) -> str:
+        """Get the adjudication reason in a friendly format."""
+        decision = self.adjudication.decision.value.capitalize()
+        return f"{decision}: {self.adjudication.reason}"
+
+
+class AdjudicatedTrajectory(Trajectory):
+    """Adjudicated trajectory with annotated steps."""
+
+    steps: list[AdjudicatedStep] = Field(default_factory=list)  # type: ignore[assignment]
+    """Steps of the adjudicated trajectory."""
+
+
+class PromptContent(Model):
+    """Prompt content type for trajectory steps."""
+
+    content_type: Literal["prompt"] = "prompt"
+    text: str
+
+
+class ToolRequestContent(Model):
+    """Tool request content type for trajectory steps."""
+
+    content_type: Literal["tool_request"] = "tool_request"
+    tool_id: str
+    args: dict[str, Any]
+
+
+class ToolResponseContent(Model):
+    """Tool response content type for trajectory steps."""
+
+    content_type: Literal["tool_response"] = "tool_response"
+    tool_id: str
+    response: Any
+
+
+Content = PromptContent | ToolRequestContent | ToolResponseContent
+"""Union type representing the content of a trajectory step.
+
+Corresponds to the Content protobuf message which uses a oneof field
+to represent different types of step content:
+- PromptContent: Text prompts or messages
+- ToolRequestContent: Requests to execute tools
+- ToolResponseContent: Results from tool execution
+"""
+
+
+class AdjudicationRecord(Model):
+    """Record of an adjudication event from the harness service.
+
+    Represents a single adjudication (policy decision) that occurred during
+    agent execution, linking the decision to its agent, trajectory, and step.
+    """
+
+    agent_id: str = Field(description="ID of the agent that triggered the adjudication")
+    trajectory_id: str = Field(
+        description="ID of the trajectory containing the adjudicated step"
+    )
+    step_id: str = Field(description="ID of the step that was adjudicated")
+    adjudication: Adjudication = Field(
+        description="The adjudication decision and reason"
+    )