sondera-harness 0.6.0__py3-none-any.whl

sondera/strands/analyze.py

@@ -0,0 +1,244 @@
+"""Strands Agent analysis utilities."""
+
+import inspect
+import json
+import logging
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from sondera.types import Agent, Parameter, SourceCode, Tool
+
+logger = logging.getLogger(__name__)
+
+
+def _get_function_source(func: Callable) -> tuple[str, str]:
+    """Extract source code and language from a function."""
+    try:
+        source = inspect.getsource(func)
+        return "python", source
+    except (OSError, TypeError):
+        return "python", f"# Source code not available for {func.__name__}"
+
+
+def _analyze_function_parameters(func: Callable) -> list[Parameter]:
+    """Analyze function parameters and return Sondera format Parameters."""
+    parameters = []
+    sig = inspect.signature(func)
+
+    try:
+        type_hints = get_type_hints(func)
+    except Exception:
+        type_hints = {}
+
+    for param_name, param in sig.parameters.items():
+        if param_name in ["tool_context", "self", "cls"]:
+            continue
+
+        param_type = "Any"
+        if param.annotation != inspect.Parameter.empty:
+            if isinstance(param.annotation, type):
+                param_type = param.annotation.__name__
+            else:
+                param_type = str(param.annotation)
+        elif param_name in type_hints:
+            hint = type_hints[param_name]
+            param_type = hint.__name__ if isinstance(hint, type) else str(hint)
+
+        description = f"Parameter {param_name}"
+        if func.__doc__:
+            lines = func.__doc__.split("\n")
+            for line in lines:
+                if param_name in line:
+                    description = line.strip()
+                    break
+
+        parameters.append(
+            Parameter(name=param_name, description=description, type=param_type)
+        )
+
+    return parameters
+
+
+def _get_function_return_type(func: Callable) -> str:
+    """Extract the return type from a function."""
+    sig = inspect.signature(func)
+    if sig.return_annotation != inspect.Signature.empty:
+        if isinstance(sig.return_annotation, type):
+            return sig.return_annotation.__name__
+        else:
+            return str(sig.return_annotation)
+
+    try:
+        type_hints = get_type_hints(func)
+        if "return" in type_hints:
+            hint = type_hints["return"]
+            if isinstance(hint, type):
+                return hint.__name__
+            else:
+                return str(hint)
+    except Exception:
+        pass
+
+    return "Any"
+
+
+def _extract_strands_tool_schema(tool: Any) -> tuple[str | None, str | None]:
+    """Extract JSON schemas from a Strands tool.
+
+    Strands tools decorated with @tool have a tool_spec attribute containing:
+    - name: tool name
+    - description: tool description
+    - inputSchema: dict with 'json' key containing the JSON schema
+
+    Args:
+        tool: A Strands tool (decorated function or tool object)
+
+    Returns:
+        Tuple of (parameters_json_schema, response_json_schema)
+    """
+    parameters_json_schema = None
+    response_json_schema = None
+
+    try:
+        # Check for tool_spec attribute (Strands @tool decorated functions)
+        tool_spec = getattr(tool, "tool_spec", None)
+        if tool_spec and isinstance(tool_spec, dict):
+            # Extract inputSchema from tool_spec
+            input_schema = tool_spec.get("inputSchema", {})
+            if input_schema:
+                # Strands stores the JSON schema under the 'json' key
+                json_schema = input_schema.get("json", input_schema)
+                if json_schema:
+                    parameters_json_schema = json.dumps(json_schema)
+
+        # Try to generate response schema from return type annotation
+        if callable(tool):
+            return_type = _get_function_return_type(tool)
+            if return_type and return_type != "Any":
+                response_json_schema = json.dumps(
+                    {
+                        "type": _python_type_to_json_schema_type(return_type),
+                        "description": f"Return value of type {return_type}",
+                    }
+                )
+    except Exception as e:
+        logger.debug(f"Could not extract JSON schema from tool: {e}")
+
+    return parameters_json_schema, response_json_schema
+
+
+def _python_type_to_json_schema_type(python_type: str) -> str:
+    """Convert Python type name to JSON Schema type."""
+    type_mapping = {
+        "str": "string",
+        "int": "integer",
+        "float": "number",
+        "bool": "boolean",
+        "list": "array",
+        "dict": "object",
+        "None": "null",
+        "NoneType": "null",
+    }
+    return type_mapping.get(python_type, "string")
+
+
+def _extract_tool_info(tool: Any) -> dict[str, Any]:
+    """Extract all tool information from a Strands tool.
+
+    Args:
+        tool: A Strands tool
+
+    Returns:
+        Dictionary with tool name, description, and schemas
+    """
+    # Get tool_spec if available (Strands @tool decorated functions)
+    tool_spec = getattr(tool, "tool_spec", None)
+
+    if tool_spec and isinstance(tool_spec, dict):
+        tool_name = tool_spec.get(
+            "name", getattr(tool, "tool_name", getattr(tool, "__name__", "unknown"))
+        )
+        tool_description = tool_spec.get("description", "")
+    else:
+        tool_name = getattr(
+            tool,
+            "tool_name",
+            getattr(tool, "name", getattr(tool, "__name__", "unknown")),
+        )
+        tool_description = getattr(
+            tool, "description", tool.__doc__ or f"Tool {tool_name}"
+        )
+
+    return {
+        "name": tool_name,
+        "description": tool_description,
+    }
+
+
+def format_strands_agent(agent: Any) -> Agent:
+    """Transform a Strands agent into Sondera Agent format.
+
+    Extracts tool metadata including JSON schemas for parameters and responses.
+
+    Args:
+        agent: The Strands agent instance
+
+    Returns:
+        Sondera Agent representation with full tool schemas
+    """
+    # Extract agent metadata
+    agent_name = getattr(agent, "name", "strands-agent")
+    agent_id = agent_name
+    system_prompt = getattr(agent, "system_prompt", "")
+    description = getattr(agent, "description", f"Strands agent: {agent_name}")
+
+    # Extract tools
+    tools = []
+    agent_tools = getattr(agent, "tools", []) or []
+
+    for tool in agent_tools:
+        try:
+            # Extract tool info from tool_spec or attributes
+            tool_info = _extract_tool_info(tool)
+            tool_name = tool_info["name"]
+            tool_description = tool_info["description"]
+
+            # Extract JSON schemas
+            parameters_json_schema, response_json_schema = _extract_strands_tool_schema(
+                tool
+            )
+
+            # Analyze function for additional info
+            if callable(tool):
+                parameters = _analyze_function_parameters(tool)
+                response_type = _get_function_return_type(tool)
+                language, source_code = _get_function_source(tool)
+            else:
+                parameters = []
+                response_type = "Any"
+                language, source_code = "python", f"# Tool object: {tool_name}"
+
+            tools.append(
+                Tool(
+                    name=tool_name,
+                    description=tool_description.strip()
+                    if isinstance(tool_description, str)
+                    else str(tool_description),
+                    parameters=parameters,
+                    parameters_json_schema=parameters_json_schema,
+                    response=response_type,
+                    response_json_schema=response_json_schema,
+                    source=SourceCode(language=language, code=source_code),
+                )
+            )
+        except Exception as e:
+            logger.warning(f"Could not analyze tool {tool}: {e}")
+
+    return Agent(
+        id=agent_id,
+        provider_id="strands",
+        name=agent_name,
+        instruction=system_prompt,
+        description=description,
+        tools=tools,
+    )

sondera/strands/harness.py

@@ -0,0 +1,333 @@
+"""Sondera Harness Hook for Strands Agent SDK integration."""
+
+import logging
+from typing import Any
+
+from strands.hooks import HookProvider, HookRegistry
+from strands.hooks.events import (
+    AfterInvocationEvent,
+    AfterModelCallEvent,
+    AfterToolCallEvent,
+    BeforeInvocationEvent,
+    BeforeModelCallEvent,
+    BeforeToolCallEvent,
+)
+
+from sondera.harness import Harness
+from sondera.strands.analyze import format_strands_agent
+from sondera.types import (
+    PromptContent,
+    Role,
+    Stage,
+    ToolRequestContent,
+    ToolResponseContent,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SonderaHarnessHook(HookProvider):
+    """Sondera Harness Hook for Strands integration.
+
+    This hook implements the HookProvider protocol to integrate with
+    Strands' hook system. It uses dependency injection for the Harness
+    instance, allowing flexibility in choosing RemoteHarness or LocalHarness.
+
+    The hook intercepts agent execution at key lifecycle points:
+    - Before/after invocation: Initialize and finalize trajectory
+    - Before/after model call: Evaluate model requests and responses
+    - Before/after tool call: Evaluate tool calls and results
+
+    Example:
+        ```python
+        from strands import Agent
+        from sondera.strands import SonderaHarnessHook
+        from sondera.harness import RemoteHarness
+
+        # Create harness instance
+        harness = RemoteHarness(
+            sondera_harness_endpoint="localhost:50051",
+            sondera_api_key="<YOUR_SONDERA_API_KEY>",
+        )
+
+        # Create hook with harness using dependency injection
+        hook = SonderaHarnessHook(harness=harness)
+
+        # Create Strands agent with hooks
+        agent = Agent(
+            system_prompt="You are a helpful assistant",
+            model="anthropic.claude-3-5-sonnet-20241022-v2:0",
+            hooks=[hook],
+        )
+
+        # Run agent (hooks will fire automatically)
+        response = agent("What is 5 + 3?")
+        ```
+
+    Hook Lifecycle:
+        1. BeforeInvocationEvent - Initialize trajectory
+        2. BeforeModelCallEvent - Pre-model guardrails
+        3. AfterModelCallEvent - Post-model guardrails
+        4. BeforeToolCallEvent - Pre-tool guardrails (can cancel with event.cancel_tool)
+        5. AfterToolCallEvent - Post-tool guardrails (can modify event.result)
+        6. AfterInvocationEvent - Finalize trajectory
+    """
+
+    def __init__(
+        self,
+        harness: Harness,
+        *,
+        logger_instance: logging.Logger | None = None,
+    ):
+        """Initialize the Strands Harness Hook.
+
+        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.
+        """
+        self._harness = harness
+        self._log = logger_instance or logger
+        self._strands_agent: Any | None = None
+
+    # -------------------------------------------------------------------------
+    # HookProvider interface - required by Strands
+    # -------------------------------------------------------------------------
+
+    def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
+        """Register all Strands lifecycle hooks.
+
+        This method is called by Strands when the agent is constructed with
+        hooks=[SonderaHarnessHook(harness=...)].
+
+        Args:
+            registry: The Strands hook registry
+            **kwargs: Additional keyword arguments (unused)
+        """
+        registry.add_callback(BeforeInvocationEvent, self._on_before_invocation)
+        registry.add_callback(AfterInvocationEvent, self._on_after_invocation)
+        registry.add_callback(BeforeModelCallEvent, self._on_before_model_call)
+        registry.add_callback(AfterModelCallEvent, self._on_after_model_call)
+        registry.add_callback(BeforeToolCallEvent, self._on_before_tool_call)
+        registry.add_callback(AfterToolCallEvent, self._on_after_tool_call)
+
+        self._log.info("[SonderaHarness] Registered Strands hooks")
+
+    # -------------------------------------------------------------------------
+    # Invocation Callbacks
+    # -------------------------------------------------------------------------
+
+    async def _on_before_invocation(self, event: BeforeInvocationEvent) -> None:
+        """Callback for BeforeInvocationEvent - Initialize trajectory."""
+        try:
+            self._strands_agent = event.agent
+            agent = format_strands_agent(event.agent)
+            await self._harness.initialize(agent=agent)
+            self._log.debug(
+                f"[SonderaHarness] Initialized trajectory {self._harness.trajectory_id}"
+            )
+        except Exception as e:
+            self._log.error(
+                f"[SonderaHarness] Error in before_invocation: {e}", exc_info=True
+            )
+
+    async def _on_after_invocation(self, event: AfterInvocationEvent) -> None:
+        """Callback for AfterInvocationEvent - Finalize trajectory."""
+        try:
+            trajectory_id = self._harness.trajectory_id
+            await self._harness.finalize()
+            self._log.info(f"[SonderaHarness] Finalized trajectory {trajectory_id}")
+        except Exception as e:
+            self._log.error(
+                f"[SonderaHarness] Error in after_invocation: {e}", exc_info=True
+            )
+
+    # -------------------------------------------------------------------------
+    # Model Callbacks
+    # -------------------------------------------------------------------------
+
+    async def _on_before_model_call(self, event: BeforeModelCallEvent) -> None:
+        """Callback for BeforeModelCallEvent - Pre-model guardrails."""
+        try:
+            if not self._harness.trajectory_id:
+                self._log.warning(
+                    "[SonderaHarness] No active trajectory for before_model_call"
+                )
+                return
+
+            content = self._extract_text_from_event(event)
+            adjudication = await self._harness.adjudicate(
+                Stage.PRE_MODEL, Role.MODEL, PromptContent(text=content)
+            )
+            self._log.info(
+                f"[SonderaHarness] Before model adjudication for trajectory {self._harness.trajectory_id}"
+            )
+
+            if adjudication.is_denied:
+                self._log.warning(
+                    f"[SonderaHarness] Model call blocked: {adjudication.reason}"
+                )
+        except Exception as e:
+            self._log.error(
+                f"[SonderaHarness] Error in before_model_call: {e}", exc_info=True
+            )
+
+    async def _on_after_model_call(self, event: AfterModelCallEvent) -> None:
+        """Callback for AfterModelCallEvent - Post-model guardrails."""
+        try:
+            if not self._harness.trajectory_id:
+                self._log.warning(
+                    "[SonderaHarness] No active trajectory for after_model_call"
+                )
+                return
+
+            content = self._extract_text_from_event(event)
+            if not content:
+                return
+
+            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:
+                self._log.warning(
+                    f"[SonderaHarness] Model response blocked: {adjudication.reason}"
+                )
+        except Exception as e:
+            self._log.error(
+                f"[SonderaHarness] Error in after_model_call: {e}", exc_info=True
+            )
+
+    # -------------------------------------------------------------------------
+    # Tool Callbacks
+    # -------------------------------------------------------------------------
+
+    async def _on_before_tool_call(self, event: BeforeToolCallEvent) -> None:
+        """Callback for BeforeToolCallEvent - Pre-tool guardrails."""
+        try:
+            if not self._harness.trajectory_id:
+                self._log.warning(
+                    "[SonderaHarness] No active trajectory for before_tool_call"
+                )
+                return
+
+            tool_name = event.tool_use.get("name", "unknown")
+            tool_input = event.tool_use.get("input", {})
+
+            adjudication = await self._harness.adjudicate(
+                Stage.PRE_TOOL,
+                Role.TOOL,
+                ToolRequestContent(
+                    tool_id=tool_name,
+                    args=tool_input
+                    if isinstance(tool_input, dict)
+                    else {"input": tool_input},
+                ),
+            )
+            self._log.info(
+                f"[SonderaHarness] Before tool adjudication for trajectory {self._harness.trajectory_id}"
+            )
+
+            if adjudication.is_denied:
+                # Cancel the tool call using Strands' cancel_tool mechanism
+                event.cancel_tool = f"Tool blocked by policy: {adjudication.reason}"
+                self._log.warning(
+                    f"[SonderaHarness] Blocked tool '{tool_name}': {adjudication.reason}"
+                )
+        except Exception as e:
+            self._log.error(
+                f"[SonderaHarness] Error in before_tool_call: {e}", exc_info=True
+            )
+
+    async def _on_after_tool_call(self, event: AfterToolCallEvent) -> None:
+        """Callback for AfterToolCallEvent - Post-tool guardrails."""
+        try:
+            if not self._harness.trajectory_id:
+                self._log.warning(
+                    "[SonderaHarness] No active trajectory for after_tool_call"
+                )
+                return
+
+            tool_name = event.tool_use.get("name", "unknown")
+
+            adjudication = await self._harness.adjudicate(
+                Stage.POST_TOOL,
+                Role.TOOL,
+                ToolResponseContent(tool_id=tool_name, response=event.result),
+            )
+            self._log.info(
+                f"[SonderaHarness] After tool adjudication for trajectory {self._harness.trajectory_id}"
+            )
+
+            if adjudication.is_denied:
+                # Modify the result to indicate policy violation
+                event.result = {
+                    "content": [
+                        {"text": f"Tool result blocked: {adjudication.reason}"}
+                    ],
+                    "status": "error",
+                    "toolUseId": event.tool_use.get("toolUseId", ""),
+                }
+                self._log.warning(
+                    f"[SonderaHarness] Tool result blocked: {adjudication.reason}"
+                )
+        except Exception as e:
+            self._log.error(
+                f"[SonderaHarness] Error in after_tool_call: {e}", exc_info=True
+            )
+
+    # -------------------------------------------------------------------------
+    # Helper methods
+    # -------------------------------------------------------------------------
+
+    def _extract_text_from_event(self, event: Any) -> str:
+        """Extract text content from Strands events for adjudication.
+
+        Args:
+            event: The Strands hook event
+
+        Returns:
+            Extracted text content for adjudication
+        """
+        if isinstance(event, BeforeModelCallEvent):
+            try:
+                if (
+                    hasattr(event.agent, "conversation_manager")
+                    and event.agent.conversation_manager
+                ):
+                    messages = []
+                    conv_mgr = event.agent.conversation_manager
+                    messages_attr = getattr(conv_mgr, "messages", None)
+                    if messages_attr:
+                        for msg in messages_attr:
+                            role = (
+                                msg.get("role", "unknown")
+                                if hasattr(msg, "get")
+                                else getattr(msg, "role", "unknown")
+                            )
+                            content = (
+                                msg.get("content", "")
+                                if hasattr(msg, "get")
+                                else getattr(msg, "content", "")
+                            )
+                            messages.append(f"{role}: {content}")
+                    if messages:
+                        return "\n".join(messages)
+            except (AttributeError, TypeError) as e:
+                self._log.debug(f"Could not extract conversation: {e}")
+            return ""
+
+        if isinstance(event, AfterModelCallEvent):
+            if event.stop_response and event.stop_response.message:
+                content = (
+                    event.stop_response.message.get("content", "")
+                    if hasattr(event.stop_response.message, "get")
+                    else getattr(event.stop_response.message, "content", "")
+                )
+                return str(content)
+            return ""
+
+        return ""