sondera-harness 0.6.0__py3-none-any.whl

sondera/adk/plugin.py

@@ -0,0 +1,387 @@
+"""
+Sondera Harness Plugin for Google ADK integration.
+
+This plugin implements the ADK BasePlugin callback patterns for policy enforcement,
+guardrails, and security controls across agent workflows using the Sondera Harness.
+"""
+
+import logging
+from typing import Any, cast
+
+from google.adk.agents.base_agent import BaseAgent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.events.event import Event
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.adk.plugins.base_plugin import BasePlugin
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types as genai_types
+
+from sondera.adk.analyze import format
+from sondera.harness import Harness
+from sondera.types import (
+    PromptContent,
+    Role,
+    Stage,
+    ToolRequestContent,
+    ToolResponseContent,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SonderaHarnessPlugin(BasePlugin):
+    """Sondera Harness Plugin for ADK integration.
+
+    This plugin integrates with the Sondera Harness for policy enforcement,
+    guardrails, and governance across ADK agent workflows. It implements
+    the ADK BasePlugin interface and uses dependency injection for the
+    Harness instance.
+
+    The plugin intercepts agent execution at key points:
+    - User message: Initialize trajectory and evaluate user input
+    - Before/after model: Evaluate model requests and responses
+    - Before/after tool: Evaluate tool calls and results
+    - After run: Finalize the trajectory
+
+    Example:
+        ```python
+        from sondera.adk import SonderaHarnessPlugin
+        from sondera.harness import RemoteHarness
+        from google.adk import Agent
+        from google.adk.runners import Runner
+
+        # Create a harness instance
+        harness = RemoteHarness(
+            sondera_harness_endpoint="localhost:50051",
+            sondera_api_key="<YOUR_SONDERA_API_KEY>",
+        )
+
+        # Create the plugin with the harness
+        plugin = SonderaHarnessPlugin(harness=harness)
+
+        # Create agent and runner with the plugin
+        agent = Agent(name="my-agent", model="gemini-2.0-flash", ...)
+        runner = Runner(
+            agent=agent,
+            app_name="my-app",
+            plugins=[plugin],
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        harness: Harness,
+        *,
+        logger_instance: logging.Logger | None = None,
+    ):
+        """Initialize the Sondera Harness Plugin.
+
+        Args:
+            harness: The Sondera Harness instance to use for policy enforcement.
+                     Can be RemoteHarness for production or LocalHarness for testing.
+            logger_instance: Optional custom logger instance.
+        """
+        super().__init__(name="sondera_harness")
+        self._harness = harness
+        self._log = logger_instance or logger
+
+    # -------------------------------------------------------------------------
+    # User Message Callback
+    # -------------------------------------------------------------------------
+
+    async def on_user_message_callback(
+        self,
+        *,
+        invocation_context: InvocationContext,
+        user_message: genai_types.Content,
+    ) -> genai_types.Content | None:
+        """Callback executed when a user message is received.
+
+        Initializes the harness trajectory and evaluates the user input
+        against policies before the agent processes it.
+
+        Args:
+            invocation_context: The context for the entire invocation.
+            user_message: The message content input by user.
+
+        Returns:
+            Modified content if policy violation, None to proceed normally.
+        """
+        # Initialize trajectory with agent metadata
+        agent = format(
+            cast(LlmAgent, invocation_context.agent),
+            invocation_context.app_name,
+            invocation_context.app_name,
+        )
+        await self._harness.initialize(agent=agent)
+
+        # Extract text content from user message
+        content = None
+        if user_message.parts is not None:
+            content = user_message.parts[-1].text
+        if not content:
+            return None
+
+        # Adjudicate user input
+        adjudication = await self._harness.adjudicate(
+            Stage.PRE_MODEL, Role.USER, PromptContent(text=content)
+        )
+        self._log.info(
+            f"[SonderaHarness] User message adjudication for trajectory {self._harness.trajectory_id}"
+        )
+
+        if adjudication.is_denied:
+            return genai_types.Content(
+                parts=[genai_types.Part(text=adjudication.reason)]
+            )
+        return None
+
+    # -------------------------------------------------------------------------
+    # Agent Callbacks
+    # -------------------------------------------------------------------------
+
+    async def before_agent_callback(
+        self,
+        *,
+        agent: BaseAgent,
+        callback_context: CallbackContext,
+    ) -> genai_types.Content | None:
+        """Callback executed before an agent's primary logic is invoked.
+
+        Args:
+            agent: The agent that is about to run.
+            callback_context: The context for the agent invocation.
+
+        Returns:
+            None to allow agent to proceed normally.
+        """
+        self._log.debug(f"[SonderaHarness] Before agent: {agent.name}")
+        return None
+
+    async def after_agent_callback(
+        self,
+        *,
+        agent: BaseAgent,
+        callback_context: CallbackContext,
+    ) -> genai_types.Content | None:
+        """Callback executed after an agent's primary logic has completed.
+
+        Args:
+            agent: The agent that has just run.
+            callback_context: The context for the agent invocation.
+
+        Returns:
+            None to use original agent response.
+        """
+        self._log.debug(f"[SonderaHarness] After agent: {agent.name}")
+        return None
+
+    # -------------------------------------------------------------------------
+    # Model Callbacks
+    # -------------------------------------------------------------------------
+
+    async def before_model_callback(
+        self,
+        *,
+        callback_context: CallbackContext,
+        llm_request: LlmRequest,
+    ) -> LlmResponse | None:
+        """Callback executed before a request is sent to the model.
+
+        Evaluates the model request against policies.
+
+        Args:
+            callback_context: The context for the current agent call.
+            llm_request: The prepared request object to be sent to the model.
+
+        Returns:
+            LlmResponse if policy violation, None to proceed normally.
+        """
+        self._log.debug(
+            f"[SonderaHarness] Before model call for trajectory {self._harness.trajectory_id}"
+        )
+        adjudication = await self._harness.adjudicate(
+            Stage.PRE_MODEL, Role.MODEL, PromptContent(text="")
+        )
+        self._log.info(
+            f"[SonderaHarness] Before model adjudication for trajectory {self._harness.trajectory_id}"
+        )
+
+        if adjudication.is_denied:
+            return LlmResponse(
+                content=genai_types.Content(
+                    parts=[genai_types.Part(text=adjudication.reason)]
+                )
+            )
+        return None
+
+    async def after_model_callback(
+        self,
+        *,
+        callback_context: CallbackContext,
+        llm_response: LlmResponse,
+    ) -> LlmResponse | None:
+        """Callback executed after a response is received from the model.
+
+        Evaluates the model response against policies.
+
+        Args:
+            callback_context: The context for the current agent call.
+            llm_response: The response object received from the model.
+
+        Returns:
+            Modified LlmResponse if policy violation, None to use original.
+        """
+        self._log.debug("[SonderaHarness] After model call")
+
+        # Extract text content from response
+        content = None
+        if llm_response.content is not None and llm_response.content.parts is not None:
+            content = llm_response.content.parts[-1].text
+
+        if not content:
+            return None
+
+        adjudication = await self._harness.adjudicate(
+            Stage.POST_MODEL, Role.MODEL, PromptContent(text=content)
+        )
+        self._log.info(
+            f"[SonderaHarness] After model adjudication for trajectory {self._harness.trajectory_id}"
+        )
+
+        if adjudication.is_denied:
+            return LlmResponse(
+                content=genai_types.Content(
+                    parts=[genai_types.Part(text=adjudication.reason)]
+                )
+            )
+        return None
+
+    # -------------------------------------------------------------------------
+    # Tool Callbacks
+    # -------------------------------------------------------------------------
+
+    async def before_tool_callback(
+        self,
+        *,
+        tool: BaseTool,
+        tool_args: dict[str, Any],
+        tool_context: ToolContext,
+    ) -> dict[str, Any] | None:
+        """Callback executed before a tool is called.
+
+        Evaluates the tool request against policies.
+
+        Args:
+            tool: The tool instance that is about to be executed.
+            tool_args: The dictionary of arguments for the tool.
+            tool_context: The context specific to the tool execution.
+
+        Returns:
+            Dict result if policy violation (stops tool), None to proceed.
+        """
+        self._log.debug(f"[SonderaHarness] Before tool: {tool.name}")
+
+        adjudication = await self._harness.adjudicate(
+            Stage.PRE_TOOL,
+            Role.TOOL,
+            ToolRequestContent(tool_id=tool.name, args=tool_args),
+        )
+        self._log.info(
+            f"[SonderaHarness] Before tool adjudication for trajectory {self._harness.trajectory_id}"
+        )
+
+        if adjudication.is_denied:
+            return {"error": f"Tool blocked: {adjudication.reason}"}
+        return None
+
+    async def after_tool_callback(
+        self,
+        *,
+        tool: BaseTool,
+        tool_args: dict[str, Any],
+        tool_context: ToolContext,
+        result: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        """Callback executed after a tool has been called.
+
+        Evaluates the tool result against policies.
+
+        Args:
+            tool: The tool instance that has just been executed.
+            tool_args: The original arguments passed to the tool.
+            tool_context: The context specific to the tool execution.
+            result: The dictionary returned by the tool invocation.
+
+        Returns:
+            Modified result dict if policy violation, None to use original.
+        """
+        self._log.debug(f"[SonderaHarness] After tool: {tool.name}")
+
+        adjudication = await self._harness.adjudicate(
+            Stage.POST_TOOL,
+            Role.TOOL,
+            ToolResponseContent(tool_id=tool.name, response=result),
+        )
+        self._log.info(
+            f"[SonderaHarness] After tool adjudication for trajectory {self._harness.trajectory_id}"
+        )
+
+        if adjudication.is_denied:
+            return {"error": f"Tool result blocked: {adjudication.reason}"}
+        return None
+
+    # -------------------------------------------------------------------------
+    # Event Callback
+    # -------------------------------------------------------------------------
+
+    async def on_event_callback(
+        self,
+        *,
+        invocation_context: InvocationContext,
+        event: Event,
+    ) -> Event | None:
+        """Callback executed after an event is yielded from runner.
+
+        Args:
+            invocation_context: The context for the entire invocation.
+            event: The event raised by the runner.
+
+        Returns:
+            None to use original event.
+        """
+        self._log.debug(f"[SonderaHarness] Event: {event.author}")
+        return None
+
+    # -------------------------------------------------------------------------
+    # Runner Lifecycle Callbacks
+    # -------------------------------------------------------------------------
+
+    async def after_run_callback(
+        self,
+        *,
+        invocation_context: InvocationContext,
+    ) -> None:
+        """Callback executed after an ADK runner run has completed.
+
+        Finalizes the harness trajectory.
+
+        Args:
+            invocation_context: The context for the entire invocation.
+        """
+        self._log.info(
+            f"[SonderaHarness] Finalizing trajectory {self._harness.trajectory_id}"
+        )
+        await self._harness.finalize()
+
+    async def close(self) -> None:
+        """Method executed when the runner is closed.
+
+        Used for cleanup tasks such as closing network connections.
+        """
+        self._log.debug("[SonderaHarness] Plugin closed")

sondera/cli.py

@@ -0,0 +1,22 @@
+"""The Sondera Harness CLI and TUI entrypoints."""
+
+import click
+from click_default_group import DefaultGroup
+
+from sondera.tui.app import SonderaApp
+
+
+@click.group(cls=DefaultGroup, default="default", default_if_no_args=True)
+def cli() -> None:
+    """A CLI and TUI for interacting with the Sondera Harness SDK and Harness Service."""
+
+
+@cli.command()
+def default() -> None:
+    """Launch the Sondera Harness TUI."""
+    app = SonderaApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    cli()

sondera/exceptions.py

@@ -0,0 +1,167 @@
+"""Sondera SDK exception hierarchy."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sondera.types import Adjudication, Stage
+
+
+class SonderaError(Exception):
+    """Base exception for all Sondera SDK errors."""
+
+    pass
+
+
+class ConfigurationError(SonderaError):
+    """Raised when there is a configuration error.
+
+    Examples:
+        - Missing required API key
+        - Invalid endpoint format
+        - Missing required settings
+    """
+
+    pass
+
+
+class AuthenticationError(SonderaError):
+    """Raised when authentication fails.
+
+    Examples:
+        - Invalid or expired JWT token
+        - Missing authentication credentials
+        - Token lacks required claims
+    """
+
+    pass
+
+
+class ConnectionError(SonderaError):
+    """Raised when connection to the harness service fails.
+
+    Examples:
+        - Network unreachable
+        - Service unavailable
+        - TLS handshake failure
+    """
+
+    pass
+
+
+class TrajectoryError(SonderaError):
+    """Raised for trajectory-related errors.
+
+    Examples:
+        - Trajectory not initialized
+        - Invalid trajectory state
+        - Trajectory already finalized
+    """
+
+    pass
+
+
+class TrajectoryNotInitializedError(TrajectoryError):
+    """Raised when attempting operations without an active trajectory."""
+
+    def __init__(self, message: str = "No active trajectory. Call initialize() first."):
+        super().__init__(message)
+
+
+class PolicyError(SonderaError):
+    """Base exception for policy-related errors."""
+
+    pass
+
+
+class PolicyViolationError(PolicyError):
+    """Raised when a policy violation blocks execution.
+
+    Attributes:
+        stage: The execution stage where the violation occurred
+        reason: The policy violation reason
+        adjudication: The full adjudication result
+    """
+
+    def __init__(
+        self,
+        stage: Stage,
+        reason: str,
+        adjudication: Adjudication | None = None,
+    ):
+        self.stage = stage
+        self.reason = reason
+        self.adjudication = adjudication
+        super().__init__(f"Policy violation at {stage.value}: {reason}")
+
+
+class PolicyEvaluationError(PolicyError):
+    """Raised when policy evaluation fails.
+
+    Examples:
+        - Invalid policy syntax
+        - Schema mismatch
+        - Policy engine internal error
+    """
+
+    pass
+
+
+class AgentError(SonderaError):
+    """Raised for agent-related errors.
+
+    Examples:
+        - Invalid agent configuration
+        - Agent not found
+        - Agent registration failed
+    """
+
+    pass
+
+
+class ToolError(SonderaError):
+    """Raised for tool-related errors.
+
+    Examples:
+        - Tool not found
+        - Invalid tool arguments
+        - Tool execution blocked
+    """
+
+    def __init__(
+        self,
+        tool_name: str,
+        message: str,
+        *,
+        tool_args: dict | None = None,
+    ):
+        self.tool_name = tool_name
+        self.tool_args = tool_args
+        super().__init__(f"Tool '{tool_name}': {message}")
+
+
+class ToolBlockedError(ToolError):
+    """Raised when a tool execution is blocked by policy."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        reason: str,
+        *,
+        tool_args: dict | None = None,
+    ):
+        self.reason = reason
+        super().__init__(tool_name, f"Blocked - {reason}", tool_args=tool_args)
+
+
+class SerializationError(SonderaError):
+    """Raised when serialization or deserialization fails.
+
+    Examples:
+        - Invalid protobuf message
+        - JSON encoding error
+        - Type conversion failure
+    """
+
+    pass

sondera/harness/__init__.py

@@ -0,0 +1,6 @@
+from sondera.harness.cedar.harness import CedarPolicyHarness
+from sondera.harness.sondera.harness import SonderaRemoteHarness
+
+from .abc import Harness
+
+__all__ = ["SonderaRemoteHarness", "CedarPolicyHarness", "Harness"]

sondera/harness/abc.py

@@ -0,0 +1,102 @@
+from abc import ABC, abstractmethod
+
+from sondera.types import Adjudication, Agent, Content, Role, Stage
+
+
+class Harness(ABC):
+    """Abstract base class defining the interface for Sondera Harness implementations.
+
+    This ABC defines the core contract for harness implementations that integrate
+    with the Sondera Platform for agent governance, trajectory management, and
+    real-time step adjudication.
+
+    Subclasses must implement:
+        - resume: Resume an existing trajectory for continued execution
+        - initialize: Set up a new trajectory for agent execution
+        - finalize: Complete and save the current trajectory
+        - adjudicate: Evaluate a trajectory step against policies
+
+    Attributes:
+        trajectory_id: The current active trajectory ID (None if no active trajectory)
+        agent: The agent being governed (may be None until initialize is called)
+    """
+
+    _trajectory_id: str | None
+    _agent: Agent | None
+
+    @property
+    def trajectory_id(self) -> str | None:
+        """Get the current trajectory ID."""
+        return self._trajectory_id
+
+    @property
+    def agent(self) -> Agent | None:
+        """Get the current agent."""
+        return self._agent
+
+    @abstractmethod
+    async def resume(self, trajectory_id, *, agent: Agent | None = None) -> None:
+        """Resume an existing trajectory for the given agent."""
+        ...
+
+    @abstractmethod
+    async def initialize(self, *, agent: Agent | None = None) -> None:
+        """Initialize a new trajectory for the current execution.
+
+        This method should:
+        1. Register the agent with the Sondera Platform if not already registered
+        2. Create a new trajectory for tracking the agent's execution
+        3. Store the trajectory ID for subsequent adjudication calls
+
+        Args:
+            agent: Optional agent to use for this trajectory. If provided, overrides
+                   any agent set during construction.
+
+        Raises:
+            ValueError: If no agent is provided and none was set during construction
+            RuntimeError: If connection to the harness service fails
+        """
+        ...
+
+    @abstractmethod
+    async def finalize(self) -> None:
+        """Finalize the current trajectory and save artifacts.
+
+        This method should:
+        1. Mark the trajectory as completed
+        2. Persist any remaining trajectory data
+        3. Clear the active trajectory state
+
+        Raises:
+            ValueError: If no active trajectory exists (initialize not called)
+            RuntimeError: If finalization fails
+        """
+        ...
+
+    @abstractmethod
+    async def adjudicate(
+        self,
+        stage: Stage,
+        role: Role,
+        content: Content,
+    ) -> Adjudication:
+        """Adjudicate a trajectory step using the policy engine.
+
+        Evaluates the given step against configured policies and returns
+        an adjudication decision (ALLOW, DENY, or ESCALATE).
+
+        Args:
+            stage: The execution stage (PRE_RUN, PRE_MODEL, POST_MODEL,
+                   PRE_TOOL, POST_TOOL, POST_RUN)
+            role: The role of the actor (USER, MODEL, TOOL, SYSTEM)
+            content: The content to evaluate (PromptContent, ToolRequestContent,
+                     or ToolResponseContent)
+
+        Returns:
+            Adjudication containing the decision and reason
+
+        Raises:
+            RuntimeError: If no active trajectory exists (initialize not called)
+            ValueError: If the content type is not supported
+        """
+        ...